====== Expedition Jigsaw Rules ======

Expedition rooms use vanilla Jigsaw Blocks and template pools. Do not use orange wool or custom marker blocks for connectivity.

===== Paths =====

Minecraft writes live Structure Block saves to the world folder with plural ''structures'':

''saves/<world>/generated/lanteacraft/structures/expedition/*.nbt''

Packaged mod resources use singular ''structure'':

''src/main/resources/data/lanteacraft/structure/expedition/*.nbt''

Template pools live here:

''src/main/resources/data/lanteacraft/worldgen/template_pool/expedition/*.json''

Import finished server structures from the generated folder into the packaged ''structure/expedition'' folder before shipping the mod.

===== Tools =====

Generate pools from packaged structures:

<code powershell>
python tools/generate_expedition_pools.py
</code>

Import server-saved structures and regenerate pools:

<code powershell>
.\gradlew.bat importExpeditionStructures
</code>

By default this imports from:

''run/saves/New World/generated/lanteacraft/structures/expedition''

For a different local/server world:

<code powershell>
.\gradlew.bat importExpeditionStructures -PexpeditionGeneratedDir="E:\LanteaCraftServer\world\generated\lanteacraft\structures\expedition"
</code>

The underlying script is also available directly:

<code powershell>
python tools/generate_expedition_pools.py --import-generated run/saves/TestWorld/generated/lanteacraft/structures/expedition
</code>

Validate packaged structures and pools:

<code powershell>
.\gradlew.bat validateExpeditionStructures
</code>

or:

<code powershell>
python tools/validate_expedition_jigsaws.py
</code>

Validate server-saved structures too:

<code powershell>
python tools/validate_expedition_jigsaws.py --generated run/saves/TestWorld/generated/lanteacraft/structures/expedition
</code>

===== Required Start Socket =====

''ExpeditionGenerator'' starts vanilla jigsaw placement with:

''lanteacraft:expedition/start''

and asks for this jigsaw name:

''lanteacraft:expedition/door''

At least one structure in the start pool, normally ''gate_room.nbt'', must contain a Jigsaw Block whose ''Name'' is exactly:

''lanteacraft:expedition/door''

===== Matching Rule =====

A spawning jigsaw connects when:

''previous_jigsaw.target == candidate_piece_jigsaw.name''

The previous piece chooses a target pool. Minecraft picks a candidate structure from that pool, then looks for a Jigsaw Block in the candidate whose ''Name'' matches the previous jigsaw's ''Target''.

===== Simple Chain =====

Expected basic flow:

''gate_room -> hall_1 -> room/intersection/combat -> reward_room''

Useful socket names:

  * Start: ''lanteacraft:expedition/door''
  * Halls: ''lanteacraft:expedition/hall_in'', ''lanteacraft:expedition/hall_out''
  * Rooms/intersections: ''lanteacraft:expedition/room_in'', ''lanteacraft:expedition/room_out''
  * Combat: ''lanteacraft:expedition/combat_in'', ''lanteacraft:expedition/combat_out''
  * Reward: ''lanteacraft:expedition/reward_in''

===== Runtime Placement =====

Expedition spawning starts Minecraft's jigsaw placement from ''lanteacraft:expedition/start''. After Minecraft finishes generating the structure, the mod scans the generated blocks and replaces expedition marker blocks.

This applies to both ''/lanteacraft spawn_trial'' and expeditions generated after dialing an expedition address.

The reward lock uses the reward-room entrance jigsaw as its anchor. Put ''lanteacraft:expedition/reward_in'' at the center-bottom block of the reward doorway, facing out toward the room/path the player comes from. When the expedition spawns, that jigsaw block is replaced by a 5 wide by 5 tall Ancient Containment Block lock. When all tracked combat mobs are cleared, that same 5 by 5 area is cleared.

Other gameplay placement uses marker blocks inside the saved structures:

  * Blue glazed terracotta: Stargate base position and facing.
  * Cyan glazed terracotta: DHD position and facing.
  * Lime wool: combat mob spawn position.
  * Trapped chest: final reward chest. It is replaced with a normal filled chest.
  * Chest or barrel: side loot container.
  * Decorated pot: side loot jar.
  * ''lanteacraft:expedition_reward_door_marker'': reward lock marker. Put this at the center-bottom of the reward doorway. It is replaced with Ancient Containment Blocks and cleared when the trial is complete.

===== Troubleshooting =====

''No starting jigsaw lanteacraft:expedition/door found''

The start pool exists, but none of its structures has a Jigsaw Block with ''Name = lanteacraft:expedition/door''. Add one to ''gate_room.nbt'', save the structure, and rerun the validator.

''Missing pool JSON''

A Jigsaw Block references a pool that does not exist under ''data/lanteacraft/worldgen/template_pool/expedition/''. Fix the pool field or regenerate pools.

''Typoed socket names''

If a previous jigsaw targets ''lanteacraft:expedition/room_in'', at least one structure in that previous jigsaw's pool must contain a Jigsaw Block named ''lanteacraft:expedition/room_in''.

''Pool references missing structure''

The pool JSON points at a structure location that has no packaged ''.nbt''. Run the pool generator after copying the NBTs into ''src/main/resources/data/lanteacraft/structure/expedition/''.

''Generated structures saved in plural structures but not copied into singular structure''

Structure Blocks save to the world ''generated/lanteacraft/structures/expedition/'' folder. The mod jar reads packaged resources from ''src/main/resources/data/lanteacraft/structure/expedition/''. Copy or import the generated files before building.