#Guardians & Chases
#The state machine
Every guardian is a small state machine stepped on Heartbeat (with the frame delta clamped to 0.1 s):
| State | Behaviour |
|---|---|
sleeping | Stands at its home nest with the sleep particle enabled and its label hidden |
chasing | Walks at full walkSpeed toward the target player and ignores the zone bounds |
fetching | Walks toward an egg that was dropped inside its zone |
hauling | Carries that egg home at RETURN_SPEED_MUL (0.75) |
returning | Walks home at the same reduced speed, then falls asleep |
#Waking up
GuardianService listens on EggSpawnService.EggTaken. When a player claims the egg belonging to a guardian's nest, the guardian waits Config.Guardian.AWAKE_DELAY (1 second), re-checks that the player is still carrying that exact egg and is inside the zone, and only then wakes and locks on.
That is also why a biome can be crossed safely: only the big nest (BIG_EGG_NEST_INDEX = 6) belongs to the guardian, and only the player who took from it is chased.
#Rules while chasing
| Setting | Value | Meaning |
|---|---|---|
PATROL_RADIUS | 26 | Reference radius for the idle placement |
CHASE_RADIUS | 150 | Give-up radius, used only when CHASE_WHOLE_ZONE is false |
CATCH_DISTANCE | 6 | Flat distance that counts as a catch, plus a per-model pad (up to 6 studs) |
REPATH_INTERVAL | 0.55 | How often the path is refreshed |
GIVE_UP_SECONDS | 20 | Chase time limit, again only when CHASE_WHOLE_ZONE is false |
STUN_SECONDS | 3 | Stun applied to the player on a catch |
DROP_EGG_ON_CATCH | true | The egg returns to its nest |
RETURN_SPEED_MUL | 0.75 | Speed multiplier while returning or hauling |
ONE_PER_ZONE | true | One guardian per biome |
CONFINE_TO_ZONE | true | The guardian stays inside its biome except while chasing |
CHASE_WHOLE_ZONE | true | The pursuit continues until the player reaches safety |
Because CHASE_WHOLE_ZONE is true, a chase ends only when:
- the player enters
Workspace.Spawn.SafeZone— the guardian gives up and returns home, - the player loses the egg (death, drop, disconnect, or a successful catch),
- or the target's character disappears.
#Getting caught
catchPlayer returns the egg to its nest, notifies the player with the guardian's display name, and knocks the character over. The knock uses PlatformStand plus a FallingDown state for FLOP_SECONDS = 2, an upward impulse (KNOCK_RISE = 18) with a horizontal speed derived from KNOCK_STUDS = 26, and a light spin that is damped after 0.5 s so the character does not keep rolling. The SAE_KnockedUntil attribute blocks pickups until the flop ends.
#Dropped eggs
After a chase a guardian scans its zone for dropped eggs (EggCarryService.droppedEggs). If it finds one inside its bounds, it switches to fetching, grabs the egg within 7 studs, carries it at CARRY_LIFT = 3.5 above its head and puts it back on the nest before going to sleep. This is the main reason a dropped egg rarely survives its full 60-second return timer.
#Tuning the difficulty
The chase is meant to be winnable: guardian speeds (25 → 142) stay under Config.Movement.MAX_WALK_SPEED (150), and player Speed converts into walk speed logarithmically, so late biomes stay tense without becoming impossible.
Useful levers:
Config.Guardian.AWAKE_DELAY— the head start a thief gets.Config.Guardian.CATCH_DISTANCE— the raw difficulty of every catch.Config.Guardian.CHASE_WHOLE_ZONE— flip tofalseto restore the 150-stud leash and the 20-second timer.Config.Guardian.STUN_SECONDS— currently 3; the catch knockdown is separate and lasts 2 seconds.Config.GuardianStats[zone.guardian].walkSpeed— per-biome pressure.
#Bat knockback and traps
A bat swing (Features.Tools.Bat) has a 1.2-second cooldown, a 10-stud range and a 0.35 cone dot; it applies 45 studs of knockback and interrupts the chase long enough to escape. Bear traps (Features.Tools.BearTrap) arm after 1 second, live for 600 seconds, trigger within 2.5 studs, have a 2-second cooldown and stun for Config.BearTrap.STUN_SECONDS = 7.
#Diagnostics
GuardianService.awakeCount()— how many guardians are currently active.GuardianService.outOfBounds()— guardians whose pivot drifted outside their zone, which normally means the zone X range and the authored geometry disagree.Config.GuardianStats— display names used in chat messages (pl), so an unnamed guardian would show up as its internal id.