====== Expedition Template Authoring ======

Expedition arenas can be built from structure templates in:

''src/main/resources/data/lanteacraft/structure/expedition/''

Structure block names include the ''expedition/'' folder. For example, the gate room loads as:

''lanteacraft:expedition/gate_room''

Required template names:

  * ''gate_room.nbt''
  * ''reward_room.nbt''
  * at least one ''combat_room_#.nbt''

Optional template names:

  * ''hall_#.nbt''
  * ''hall_left_#.nbt''
  * ''hall_right_#.nbt''
  * ''room_#.nbt''
  * ''combat_room_#.nbt''
  * ''intersection_cross.nbt''
  * ''intersection_tee.nbt''

''#'' can be any positive number. Examples:

  * ''hall_1.nbt''
  * ''hall_12.nbt''
  * ''hall_left_1.nbt''
  * ''hall_right_1.nbt''
  * ''room_4.nbt''
  * ''combat_room_1.nbt''
  * ''combat_room_27.nbt''

If any required template is missing, the Java fallback arena is used.

===== Coordinate Convention =====

Preferred authoring should use vanilla Jigsaw Blocks for connected rooms. Orange wool connectors are a legacy/debug shortcut kept only so older test rooms still work while the expedition generator moves to vanilla jigsaw pools.

For ''gate_room.nbt'', the blue glazed terracotta marker defines the generated Stargate base position. You can move it inside the gate room; the generator uses that marker as the anchor for the whole trial layout.

Recommended module sizes are no longer strict. The generator reads each template's actual size and orange connector positions from the NBT.

Java still places the Stargate, DHD, reward chest contents, and mobs after template placement. Templates should provide room geometry, cover, lighting, doors, decorations, and containment blocks.

Do not include real Stargate or DHD blocks in the template NBT. The generator injects the functional blocks so it can assign the expedition address, set ancient power, install the DHD crystal, and register the gate correctly.

The legacy generator builds a seeded-random main path using the available halls, turn halls, filler rooms, intersections, combat rooms, and final reward room. It chooses which numbered halls/rooms/combat rooms to use per expedition, and may use different counts per expedition. It uses roughly ''tier + 1'' combat rooms, with a minimum of two. Each next piece is rotated and placed by matching a connector to the previous connector.

===== Jigsaw Authoring =====

Use Jigsaw Blocks for new connected expedition rooms. This is the same vanilla system used by villages, bastions, trail ruins, and other modular structures.

''/lanteacraft spawn_trial'' tries vanilla jigsaw generation first when ''lanteacraft:expedition/start'' exists. The old Java fallback room is disabled for the debug command, so a broken jigsaw setup reports an error instead of silently spawning the old room.

The bundled ''.nbt'' structure files belong here:

''src/main/resources/data/lanteacraft/structure/expedition/''

The jigsaw pool JSON files belong here:

''src/main/resources/data/lanteacraft/worldgen/template_pool/expedition/''

Jigsaw pieces need:

  * Jigsaw Blocks saved inside the ''.nbt'' structure.
  * Matching ''name'' / ''target'' values on the jigsaw connectors that should attach.
  * A ''target_pool'' pointing at the template pool for the next category of piece.
  * Template pool JSON files under ''data/lanteacraft/worldgen/template_pool/''.
  * A fallback pool for dead ends or failed branches.

Recommended expedition pool layout:

  * ''lanteacraft:expedition/start'': starts with ''gate_room''.
  * ''lanteacraft:expedition/halls'': hall and turn hall pieces.
  * ''lanteacraft:expedition/rooms'': filler rooms and intersections.
  * ''lanteacraft:expedition/combat_rooms'': combat rooms.
  * ''lanteacraft:expedition/reward'': final reward room.
  * ''lanteacraft:expedition/terminators'': sealed doorway/end-cap pieces.

The starter pool already exists at:

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

That pool points at:

''lanteacraft:expedition/gate_room''

So ''gate_room.nbt'' must contain at least one Jigsaw Block that can start generation. If it has no matching jigsaw, vanilla placement fails and ''/spawn_trial'' will spawn nothing.

For jigsaw connectors, use a consistent connector name such as:

''lanteacraft:expedition/door''

Set doorway jigsaw blocks to replace themselves with air unless you intentionally want a cap block:

''final_state: minecraft:air''

Vanilla jigsaw placement rejects partial intersections. If a candidate child piece would partially overlap another piece, it is not placed; fallback pools can be used to close that doorway instead.

==== Jigsaw Block Fields ====

Put the Jigsaw Block inside the doorway/opening where another piece should attach. The block's front-facing arrow should point out of the current room toward the next room. For normal horizontal doorways, use ''Joint: Aligned''.

Use these values for a normal expedition doorway:

  * ''Name'': ''lanteacraft:expedition/door''
  * ''Target'': ''lanteacraft:expedition/door''
  * ''Pool'': the pool this doorway should pull the next piece from
  * ''Final State'': ''minecraft:air''
  * ''Joint'': ''aligned''

The parent jigsaw's ''Target'' must match the child jigsaw's ''Name''. Using ''lanteacraft:expedition/door'' for both sides makes all expedition doorways compatible.

Use these target pools:

  * Gate room exit to the first generated piece: ''lanteacraft:expedition/halls''
  * Hall/room exits that should continue exploration: ''lanteacraft:expedition/rooms''
  * Doorways that should lead into fights: ''lanteacraft:expedition/combat_rooms''
  * Doorways that should end in the prize room: ''lanteacraft:expedition/reward''
  * Doorways that should close if nothing fits: ''lanteacraft:expedition/terminators''

For a simple straight hallway:

  - Put one Jigsaw Block at the north doorway, facing north.
  - Put one Jigsaw Block at the south doorway, facing south.
  - Set both ''Name'' and ''Target'' to ''lanteacraft:expedition/door''.
  - Set the north/entrance side's ''Pool'' to ''lanteacraft:expedition/terminators'' unless you intentionally want it to branch backward.
  - Set the south/exit side's ''Pool'' to the next category, such as ''lanteacraft:expedition/rooms'' or ''lanteacraft:expedition/combat_rooms''.
  - Set ''Final State'' to ''minecraft:air''.
  - Set ''Joint'' to ''aligned''.

For a tee or cross room, put Jigsaw Blocks in each valid doorway. Point each block outward from the room. Set the pool on side exits to whatever can legally attach there. If a side branch is optional, use a pool with ''terminators'' as its fallback so failed branches become sealed/empty instead of overlapping.

To edit a Jigsaw Block in-game:

  - Give yourself one with ''/give @s minecraft:jigsaw''.
  - Place it in the doorway.
  - Face the direction the next piece should spawn, then rotate the block until its front arrow points out of the room.
  - Right-click the Jigsaw Block in creative mode.
  - Fill in ''Name'', ''Target'', ''Pool'', ''Final State'', and ''Joint''.
  - Save the room with a Structure Block.

==== Converting Existing Orange Wool Rooms ====

If an old room already uses orange wool doorway markers, load that room into the world with a Structure Block, then run:

''/lanteacraft expeditions convert_orange_jigsaws <from> <to> <pool>''

''<from>'' and ''<to>'' are the opposite corners of the loaded structure's bounding box. ''<pool>'' is the target pool every converted doorway should use.

Example:

''/lanteacraft expeditions convert_orange_jigsaws 100 64 100 124 76 124 lanteacraft:expedition/rooms''

The command treats each connected orange wool patch as one doorway marker. A 5x5 orange panel becomes one Jigsaw Block at the bottom center of the doorway edge, row 1 block 3, and the remaining orange wool is replaced with air.

Each generated Jigsaw Block is configured as:

  * ''Name'': ''lanteacraft:expedition/door''
  * ''Target'': ''lanteacraft:expedition/door''
  * ''Pool'': the pool you passed to the command
  * ''Final State'': ''minecraft:air''
  * ''Joint'': ''aligned''

It infers the Jigsaw Block direction from the closest structure edge, so an orange patch on the north edge becomes a north-facing jigsaw, south edge becomes south-facing, and so on.

After conversion, inspect the Jigsaw Blocks. If a specific doorway should lead to a different pool, edit that one block manually. Then save the structure again with the Structure Block.

===== Path Pieces =====

All path pieces are authored once in the same south-facing orientation. The generator rotates each placed piece to match the current connector direction.

  * ''hall_#'': straight segment.
  * ''hall_left_#'': left-turn segment.
  * ''hall_right_#'': right-turn segment.
  * ''room_#'': filler segment.
  * ''combat_room_#'': combat segment.
  * ''reward_room'': final segment.
  * ''intersection_cross'' / ''intersection_tee'': decorative intersection segment. For now these can continue forward, left, or right, but they do not create real side branches yet.

You do not need north/east/south/west copies of a hall. Build one canonical version and let the generator rotate it.

===== Marker Blocks =====

Markers are ordinary blocks placed in templates and replaced after the template is placed:

  * Orange wool: legacy connector/doorway marker. Replaced with air after placement. Prefer Jigsaw Blocks for new rooms.
  * Lime wool: combat spawn marker. Replaced with air, then used as a Goa'uld soldier spawn point.
  * Blue glazed terracotta: Stargate base marker. Replaced with air, then a functional gate is placed there. The glazed terracotta facing controls the gate facing.
  * Cyan glazed terracotta: DHD marker. Replaced with air, then a functional DHD is placed there. The glazed terracotta facing controls the DHD facing.
  * Trapped chest: final reward chest marker. Replaced with a normal filled reward chest. The trapped chest facing is preserved.
  * Chest: side loot marker. Kept as a chest and filled with lower-value expedition loot.
  * Barrel: side loot marker. Kept as a barrel and filled with lower-value expedition loot.
  * Decorated pot: loot jar marker. Kept as a decorated pot and given one small hidden item.

Place orange wool on the outside edge of every doorway that can connect to another module. Any orange wool in a placed template is replaced with air. Multiple orange connectors in a room are allowed. The generator treats them like lightweight jigsaw sockets: it matches the next piece to a socket, checks that the next piece does not overlap any already placed piece, and then removes the marker.

For south-facing templates, north-edge orange is preferred as the entrance and south-edge orange is preferred as the main-path exit. East/west connectors are valid for turns, tees, crosses, and side paths when they fit without overlapping existing rooms.

For ''gate_room.nbt'', put the blue glazed terracotta wherever the Stargate base should appear. The generator reads its local position before placement and keeps the reward door, chest, and combat-room offsets lined up with the rest of the trial.

The reward room entrance connector is locked with Ancient Containment Blocks until all tracked combat rooms are clear.

You can use multiple trapped chest markers; each one becomes a normal filled reward chest. If none is present, the generator places one reward chest in the default reward-room spot. Multiple normal chests, barrels, and decorated pots are also supported.

===== Testing =====

===== Server Editing Workflow =====

To edit templates live on a server:

  - Run ''/lanteacraft expeditions export_templates''.
  - Place a Structure Block and set it to Load.
  - Use names like ''lanteacraft:expedition/gate_room'', not ''lanteacraft:gate_room''.
  - Load the structure, edit it, then switch the Structure Block to Save.
  - Save with the same name, or a numbered module name like ''lanteacraft:expedition/combat_room_1''.
  - Run ''/reload'' before testing the expedition generator.

The command exports bundled templates to the world's generated structure folder:

''generated/lanteacraft/structures/expedition/''

Structure Blocks save there too. Once templates are good, import them back into the mod resources and regenerate pools:

''.\gradlew.bat importExpeditionStructures''

For a different local/server world:

''.\gradlew.bat importExpeditionStructures -PexpeditionGeneratedDir="E:\LanteaCraftServer\world\generated\lanteacraft\structures\expedition"''

Server-saved templates in ''generated/lanteacraft/structures/expedition/'' are valid for testing immediately after ''/reload''; you do not have to copy them into the repo before using ''/lanteacraft spawn_trial''.

Use this command to spawn a trial directly in front of you:

''/lanteacraft spawn_trial''

It prints the generated seed. Reuse that seed to spawn the same layout again:

''/lanteacraft spawn_trial 123456789''

The debug spawner does not pre-clear the test area by default. If you really want to wipe a large clean area before spawning, use:

''/lanteacraft spawn_trial clear''

''/lanteacraft spawn_trial 123456789 clear''