🦅 GlymeraGuard 🦅

Place a bird cage, and guard birds will automatically patrol the area and attack hostile NPCs.

What is GlymeraGuard?

GlymeraGuard adds an automated guard bird system to your Hytale server. Players place one of four special Bird Cage blocks, and guard birds automatically spawn and begin patrolling the sky above the cage. When hostile NPCs enter the guard radius, the birds chase them down using natural flight AI and deal damage when close enough. Breaking the cage despawns the birds instantly.

Each cage type spawns a different bird species with unique stats. Birds are invulnerable to player damage but can be killed by hostile NPCs. When all birds from a cage are dead, a fresh set respawns automatically. Birds that get stuck in terrain are automatically pushed upward after 3 seconds.

Players can place up to 3 cages simultaneously (configurable). The limit applies to the total across all bird types.

How to Get the Bird Cages

Bird cages can be obtained in two ways:

• Crafting Recipes: Each cage is crafted from a Trork Cage combined with a specific feather type. All recipes can be enabled or disabled in the plugin config.

• Commands: Use /give Cage_Vulture, /give Cage_Hawk, /give Cage_Archaeopteryx, or /give Cage_Pterodactyl to obtain them directly.

How it Works - Step by Step

1. The player obtains a bird cage via crafting or the /give command.
2. The player places the cage on the ground.
3. Within a few seconds, the cage scanner detects the new cage and automatically spawns guard birds above it.
4. The birds begin patrolling in circles above the cage at natural flight height (15-35 blocks above ground).
5. When a hostile NPC enters the guard radius (default: 20 blocks around the cage), the birds chase it using AI-driven flight.
6. When a bird is close enough (within 2 blocks), it deals damage to the hostile NPC with impact sound and particle effects.
7. When the hostile is dead or leaves the area, birds return to their patrol pattern.
8. Breaking the cage despawns all its birds immediately.

Bird Types

All birds:

• Fly at natural height (15-35 blocks above ground)
• Are invulnerable to player damage but can be killed by hostile NPCs
• Use LockedTarget AI to chase hostiles naturally
• Deal configurable damage (default: 20) every 2 seconds when within attack range
• Automatically pushed upward if stuck in terrain for 3+ seconds

Features

• Fully automated - Place a cage, birds appear. Break the cage, birds disappear. No commands needed for operation.
• Craftable cages - Each cage can be crafted from a Trork Cage and a specific feather type. Recipes can be toggled in the config.
• 4 bird species - Each cage type spawns a different bird with unique stats (health, speed, agility).
• Natural flight behavior - Birds patrol in circles at realistic altitude and chase hostiles using Hytale's native AI flight system.
• Configurable guard radius - Birds detect and attack hostile NPCs within a configurable radius around the cage (default: 20 blocks).
• Per-player cage limit - Each player can have up to 3 active cages (configurable). The limit counts all cage types combined.
• Bird respawn - When all birds from a cage are killed, a fresh set spawns automatically.
• Anti-stuck system - Birds that don't move at least 1 block in any direction within 3 seconds are pushed 5 blocks upward.
• Player-safe - Birds cannot be damaged by players. Only hostile NPCs can hurt them.
• Attack effects - Each bird attack includes impact sound and particle effects visible to all nearby players.
• Optional neutral targeting - Can be configured to also attack neutral NPCs (disabled by default).
• Chunk-aware - Birds only operate when their chunks are loaded. No duplication when players leave and return.
• Anti-duplication - Three-layer protection against NPC duplication: chunk-loaded checks, pre-spawn cleanup, and periodic duplicate removal.
• Clean restart - Old bird entities are cleaned up on server restart. Fresh birds spawn when players return to their cages.

Commands

This plugin has no commands for operation. Everything is controlled through placing and breaking bird cages.

To obtain cage items via command, use:

• /give Cage_Vulture
• /give Cage_Hawk
• /give Cage_Archaeopteryx
• /give Cage_Pterodactyl

Configuration

A configuration file is automatically created at plugins/GlymeraGuard/config.json on first start. All values can be changed and take effect after a server restart.

Installation

1. Stop your Hytale server.
2. Copy GlymeraGuard.jar into your server's mods/ folder.
3. Start your server.
4. Check the server log for the startup message.

No additional dependencies or asset packs required — everything is included in the single JAR file.

Known Limitations

• Birds attack based on cage position - The guard radius is measured from the cage, not from the birds. Birds may chase a hostile outside the radius but will not detect new hostiles beyond it.
• No bird persistence - Individual bird health and positions are not saved. On server restart, fresh birds spawn at full health.
• Multi-block cage detection - Cages placed within 2 blocks of each other are treated as one cage to prevent duplicate detection from multi-block furniture hitboxes.

Support

Having issues or questions? Leave a message here or visit our Discord!

Developed by GlymeraCraft

The GlymeraGuard Team