guards need their position inside a pair of waypoint boxes (else the game removes them): placing a guard gives it a box and event bit 0, check and inspector state with box around it button; exit and object checks use the engine's cell rule (tiles listed in the cell, swap models), tile cell from the map loader formula

docs/manual/09-objects.md

@@ -304,18 +304,25 @@ The editor knows the parameters of these types (the rest show raw values):
 | **ForcePlayerMovement**, **WaterReboundPoints**, **ObjectDontDropInBox**, **FallOffNoHurt**, **RiverCurrentBox** | see [Force and water objects](11-cameras-triggers.md#force-and-water-objects) | points / box |
 | **RubyIdolDoor** | Idols needed, Offset (sign distance) | – |
 | **PressurePadDoor** | Pad flags (bit field), Door z, Camera, Camera hold | – |
-| **CityGuard** | View range, Chase range, Event bit, Wall collision | Patrol path (wraps to the first node) |
+| **CityGuard** (and CityGuardWithRubyIdol, CowGuard, GorillaGuard, LizardGuard, WarthogGuard) | View range, Chase range, Event bit (0 = active at once), Wall collision (CityGuard only) | Walking boxes: node pairs; the guard must **start inside one box** |
 | **JumpingBeetleBlue**, **JumpingBeetle** | Jump time, Wait, Jump height, Pause | Jump targets |
 | **Spider** | Range, Speed, Down time, Up time, Start down | Path |
 | **Bunny** | Flee range | – |
 
+> **Guards:** a guard walks around inside the boxes of its waypoint pairs and chases the llama
+> only inside them. If it does not start inside one of its boxes, or the node count is odd, the
+> game removes it when the level starts – it never appears. Placing a guard gives it one 4×4 box
+> around itself and Event bit 0; the Inspector shows a warning and a **Box around it** button
+> when the boxes are wrong. An **Event bit** above 0 keeps the guard hidden until another object
+> with that event number (a talking character, a smash statue, a door pad …) sets the bit.
+
 > **Tip:** For pickups, leave **Snap to floor** on: the game then drops the coin onto the floor
 > when the level starts, so a coin placed slightly too high still ends up in the right place.
 
 ## Duplicating, copying and pasting
 
 * **Edit → Duplicate** (**Ctrl+D**) copies the selection one cell east. Objects keep a copy of
-  their waypoint chain, so a duplicated guard gets its own patrol path.
+  their waypoint chain, so a duplicated guard gets its own walking boxes.
 * **Edit → Copy** / **Paste** (**Ctrl+C** / **Ctrl+V**) work inside the open level.
 * **Delete** removes objects; waypoint chains used only by the deleted objects are removed too.
 

docs/manual/10-waypoints.md

@@ -1,6 +1,6 @@
 # Waypoints and paths
 
-Many objects need positions besides their own: a guard walks along a patrol path, a camera zone
+Many objects need positions besides their own: a guard walks inside its boxes, a beetle jumps along a patrol path, a camera zone
 covers a box, a checkpoint stores where the llama respawns, a cut scene flies its camera along a
 route. The game stores all of these as **waypoints** – points linked into **chains**. This
 chapter explains how chains work and how to edit them with the **Waypoint paths** tool.
@@ -27,10 +27,10 @@ What the nodes mean depends on the object type. The Inspector names the role in
 
 | Role | Used by | Meaning of the nodes |
 |---|---|---|
-| **patrol path** | CityGuard, JumpingBeetleBlue, Spider … | Points the character walks or jumps to; patrols wrap from the last node back to the first |
+| **patrol path** | JumpingBeetleBlue, Spider … | Points the character walks or jumps to; patrols wrap from the last node back to the first |
 | **camera positions** | Llama (first node), cut-scene cameras, CutSceneTrigger | Camera position; node yaw and pitch give the view direction |
 | **respawn point** | CheckPointPost | Where the llama reappears, and which way it faces |
-| **box area (two opposite corners)** | Secret, CameraSide, CameraLift, ObjectDontDropInBox, FallOffNoHurt … | Two nodes span a rectangle on the ground (x and z only); some types use several pairs |
+| **box area (two opposite corners)** | Secret, CameraSide, CameraLift, ObjectDontDropInBox, FallOffNoHurt, guards … | Two nodes span a rectangle on the ground (x and z only); some types use several pairs (guards walk inside their boxes and must start inside one) |
 | **point list** | ForcePlayerMovement, WaterReboundPoints | Target points |
 | **waypoint chain** | other types | Meaning unknown – keep the original layout |
 
@@ -162,5 +162,7 @@ The Problems panel reports:
 | … needs n waypoint(s) (…), has m | The type reads more nodes than the chain has |
 | … uses only n waypoint(s), the chain has m (info) | Extra nodes are ignored by the game |
 | … box nodes come in pairs | Box zones need an even number of nodes |
+| … never appears: the game removes it at level start (error) | A guard without boxes, with an odd node count or starting outside all of its boxes; use **Box around it** in the Inspector |
+| … stays hidden until event bit n is set (info) | A guard waiting for an event; set Event bit to 0 to have it active at once |
 | … has no waypoints; all original … objects have a chain | Most likely the type needs one |
 | Respawn node is n cells away (info) | A checkpoint's respawn point far from the post |