AMBUSH SETUP GUIDE
==================

Ambushes are made with Minecraft structure blocks. Enter each marker name in
Structure Name, click Done, then Save & Quit the Minecraft world before building.
The structure blocks are authoring markers; they are not visible in the game.

QUICK EXAMPLE: WALK-IN AMBUSH
----------------------------
Place these markers on solid, clear floor:

  ambush_a1             SAVE mode, with a selection box around the trigger area
  zombie_3_a1_w1        three Zombies requested for wave 1
  spider_2_a1_w2        two Spiders requested for wave 2
  ambush_wall_4_a1      optional four-block-long barrier wall

Walk into the SAVE selection to begin. The notification and walls appear first;
wave 1 begins about one second later. Wave 2 begins after wave 1's spawned
enemies are defeated. The walls disappear after the final wave ends.
The game shows a short A1 - WAVE 1 message at the start and announces each
following wave. Leaving the map resets its ambushes, including completed ones;
they can be triggered again when you return.

MARKER NAMES
------------
Use a group such as a1 for every part of one ambush. For another independent
ambush, use a2 throughout. Groups must match exactly.

  ambush_a1                       A1 encounter marker
  zombie_a1_w1                    one Zombie in A1 wave 1
  zombie_3_a1_w1                  request three Zombies in A1 wave 1
  slime_1_a1_w2                   one Slime in A1 wave 2
  monstrosity_redstone_1_a1_w3   Redstone Monstrosity in A1 wave 3
  soulstorm_generator_1_a1_w4   Soulstorm Generator in A1 wave 4
  ambush_wall_4_a1                optional A1 wall, four blocks long
  prop_button_a1                  optional A1 button trigger
  prop_lever_a1                   optional A1 lever trigger
  prop_pressure_plate_a1          optional A1 pressure-plate trigger

Use mob names from the compiler's entities.csv. The mob must be enabled there.
Waves start at w1 and cannot skip a number. Add at least one mob marker to
every ambush; there is no default Zombie. A grouped mob name without _wN is
treated as wave 1. An ordinary mob marker without _aN is not in the ambush.
The Soulstorm Generator uses its native Soulstorm encounter. Its ambush wave
ends only after the generator is defeated. Give it clear floor and room for
its spawned enemies; test the encounter in-game before sharing the map.

The count in a name such as zombie_3_a1_w1 is a request, not a promise. The
compiler uses nearby floor cells that have enough headroom. If only one cell
is clear, it can place fewer than three. Spread large groups across multiple
markers on open floor if needed. Keep spawn markers inside or close to the
ambush area, away from walls, water, barriers and low ceilings.

CHOOSE A TRIGGER
----------------
1. Area only: set ambush_a1 to SAVE mode. Set Relative Position and Structure
   Size so its outlined box covers the place the player will enter. No button
   is needed. The box is invisible in the finished game and has no collision.

2. Button only: set ambush_a1 to LOAD mode and add prop_button_a1,
   prop_lever_a1 or prop_pressure_plate_a1. The matching control starts A1
   when its state changes. A LOAD-mode ambush without a matching control is
   a build error.

3. Area OR button: set ambush_a1 to SAVE mode and add a matching control.
   Either entering the box or using the control starts A1. The control does
   not need to be inside the box.

For SAVE mode, set Structure Size X/Y/Z to 1-48 blocks each. Include enough
vertical space for the player. Leave structure rotation at NONE. A selection
box that misses the player's height will not trigger. Use the compiler option
"Show ambush bounds (debug)" to see a temporary, non-colliding outline in
game. Turn that option off and rebuild for the finished map.

WALLS
-----
Walls are optional. Use ambush_wall_N_a1, where N is a length from 1 to 32.
The marker is the first block; the wall extends N blocks to its right as seen
from the structure block's rotation. Each panel is thin and three blocks
high, positioned on the back edge of its marked block. Several wall markers
can form a perimeter. Plain ambush_wall_a1 makes a three-block wall centered
on the marker for older maps.

Right-hand extension by structure rotation:

  NONE                 +Minecraft X
  CLOCKWISE_90         +Minecraft Z
  CLOCKWISE_180        -Minecraft X
  COUNTERCLOCKWISE_90  -Minecraft Z

The wall group must match an ambush group. Walls appear when the ambush starts
and lower after the last wave is cleared. They are not the trigger area; use
the SAVE selection or a control to start the encounter.

MULTIPLE AMBUSHES AND BUILD OPTIONS
----------------------------------
Use ambush_a1, ambush_a2, etc., with matching wave mobs, walls and controls.
In-game boss names work as mob markers too: monarch_1_a1_w1 and
shade_1_a1_w1 both spawn Monarch. Prefer the in-game name when making maps.
Each group has its own trigger and waves. Waves and wave-mob slots have no
fixed compiler limit; large encounters will still increase build size and
game load. The compiler allows at most 16 ambushes and 64 wall panels per map.

Leave Mobs enabled in Build Contents; turning it off removes ambush content.
For button, lever or pressure-plate activation, also leave Props enabled.
Area-only ambushes do not need Props. Chests are separate markers and are not
automatically awarded or unlocked by an ambush.

TESTING AND TROUBLESHOOTING
---------------------------
- Save & Quit Minecraft before compiling; the compiler reads saved world data.
- No trigger: check SAVE bounds and player height, or check that the control
  has the same _aN suffix and Props is enabled.
- No enemies: check explicit _aN_wN mob names, Mobs enabled, solid floor,
  headroom and room for navigation around each spawn marker.
- Fewer enemies than requested: clear more nearby floor cells or use more
  markers spaced apart. The compiler uses the cells it can place.
- No next wave: defeat the remaining enemies from the current wave. The next
  wave starts only after none of its tracked enemies remain.
- No walls: check the matching _aN suffix and place wall markers on solid
  floor with three blocks of clearance above them.
- If the player dies during an active ambush, its walls and wave state reset;
  re-enter the area or use the control again to restart it.
- Leaving the map resets all ambush groups so they can restart on your next
  visit. Button-triggered groups require another button press.
- Reset to Checkpoint also clears ambush waves and walls, then rearms their
  triggers. Landing inside its SAVE box starts it again immediately; a matching
  button can also start it.

For a first test, use only ambush_a1 in SAVE mode and zombie_1_a1_w1. Once
that works, add later waves, walls and controls one at a time.
