🦅 GlymeraGuard 🦅

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

Most actual version only working for Hytale stable 5 ! Don't miss my other exciting projects — take a look at GlymeraCraft's Profile Discord: https://discord.gg/s5NRFWfxgy

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.

Cage	Ingredient 1	Ingredient 2
Cage_Vulture	Deco_Trork_Cage	Ingredient_Feathers_Light
Cage_Hawk	Deco_Trork_Cage	Ingredient_Feathers_Dark
Cage_Archaeopteryx	Deco_Trork_Cage	Ingredient_Feathers_Red
Cage_Pterodactyl	Deco_Trork_Cage	Ingredient_Feathers_Blue

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

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

Bird Types

Cage Item	Bird Species	Health	Speed	Special
Cage_Vulture	Vulture	500 HP	Fast (15)	High roll angle, tight turns
Cage_Hawk	Hawk	400 HP	Fastest (18)	Very agile, fastest turn speed
Cage_Archaeopteryx	Archaeopteryx	600 HP	Moderate (14)	Tanky, wide patrol circle
Cage_Pterodactyl	Pterodactyl	700 HP	Slow (12)	Tankiest, high max altitude

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.

Parameter	Default	Description
maxCagesPerPlayer	3	Maximum number of bird cages a player can have active simultaneously. Counts all cage types combined.
birdsPerCage	3	Number of guard birds spawned per cage.
guardRadius	20	Radius in blocks around the cage within which hostile NPCs are detected and attacked.
attackNeutral	false	If true, birds will also attack neutral NPCs (not just hostile ones).
combatTickMs	1000	Interval in milliseconds between combat updates (target assignment, damage checks, stuck detection).
cageScanTickMs	5000	Interval in milliseconds between cage detection scans (detecting new or removed cages).
attackDamage	20.0	Damage dealt per bird attack.
attackIntervalMs	2000	Minimum time in milliseconds between attacks for each bird.
attackRange	2.0	Distance in blocks within which a bird can deal damage to its target.

Installation

Stop your Hytale server.
Copy GlymeraGuard.jar into your server's mods/ folder.
Start your server.
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