MaptoMCD2 Compiler v1.3 - Preview
OFFLINE MODE ONLY

Extract the archive to a new, non-synced local folder, then run
MaptoMCD2_Compiler.bat. The download contains no saved paths, keys, builds,
tools, or save files. The launcher can download Python; the Set Up Now guide
retrieves pinned tools and walks through the remaining setup. Game files, Unreal Engine 5.6.1, your AES key, and
Blueprint Loader remain user-supplied. Install only one map package at a time.

Each build extracts game data again, then removes its extraction, Unreal
intermediates and temporary files when the run ends, including cancellations
and failures. A successful build retains only its verified install packages
and build receipt. The next successful build for that map removes the previous
compiler-owned release. Install rollback copies are temporary and removed
after success or a completed rollback. Existing SaveBackups folders and older
folders made by previous compiler versions are not deleted automatically.

Local regression scripts live in test/. Run them from this folder with
python -m unittest discover -s test -t . -p "test_*.py". They are kept for
development and are not included in the packaged compiler.

Since v1.2, the compiler generates native spawn definitions and volumes for every enabled mob marker.
A marker such as baby_zombie_2 or zombie_2 requests two native spawns from
one volume. Baby zombie is the confirmed in-game type; other mob types need
individual tests, especially bosses, flying mobs, pets and friendlies.

Level Theme also selects the map's native area family. Frozen Highlands,
Singer's Meadow, Lullaby Hills, Rainy Plains, Humbler Huskland, and Deep Dark
A2 use their own area definitions and registration templates. The choice names
show the Plains or Forest terrain variant used for Minecraft blocks; the
Overworld atlas has no separate terrain variant for these additional areas.
Deadleaf Forest, Cinder Crags, Squid Coast, Ravines, and Deep Dark A1 have no
matching native indoor registration row. Their choices reuse a compatible
indoor row and are marked experimental until tested in-game.

Each map now has its own persistent area tags. The first build writes
Maps/<map name>/area-identity.json; keep this file with the map. Later theme
changes may change terrain, visuals and native templates, but will not change
that map's area tags. Existing completed maps keep their previous area tag on
the first upgraded build; new maps get map-specific tags. Renaming the map
creates a different identity. The
Haven return doorway still targets the native Town area. This prevents theme
changes from silently changing the map's saved area identity, but does not
repair an already-missing hero or prove that saving while on a custom map is
safe. Test with a disposable offline hero before relying on it.

The compiler no longer manages Dungeons II save backups or restores. Custom
maps may corrupt a save file. Use a disposable offline hero when testing;
existing SaveBackups folders are left untouched.

Build Contents can omit mobs, props, and chests for diagnostic builds.
Uncheck Guaranteed chest loot (6 types) to keep native chest rules and the selected
theme's item pool, registered to this map's two area tags. It does not change
the six global chest weapon pools or disable repeat filtering. This native
area-loot path needs an in-game drop test. Unchecked marker types are still
read from the Minecraft world but excluded from the installed map. Terrain,
doors and area registration remain required for a playable portal map.

Level Theme selects both terrain textures and area registration: Plains uses
Plains A1, Forest uses Forest A1, and Haven / Town uses Town. Town has no native
indoor-map template, so its custom area keeps the proven fixed-map layout
structure while using Town's area identity and display assets. Each choice
needs an in-game portal and mob-spawn check after building.

Edit entities.csv beside the compiler BAT for mobs, prop collision and walking
animation profiles. See ENTITIES_GUIDE.txt. Restart the compiler and rebuild
after changes. Do not edit generated catalogues or old build folders.

Decorative prop test: barrel
- Use a STRUCTURE BLOCK (not a command block), the same as chest/mob markers.
- Place it directly on a solid floor with two blocks of clear space above.
- In LOAD mode, set Structure Name to minecraft:prop_barrel.
- Choose rotation 0, 90, 180 or 270, then click Done, NOT Load.
- Save and Quit Minecraft. Restart the compiler, build and install with MCD II closed.
- The marker is replaced by a native barrel mesh, aligned to the floor.
- Set collision to mesh for a solid prop using its native mesh collision, or
  none for walk-through decoration. The barrel now defaults to mesh.
- No breaking, loot or interaction. Mesh collision still needs in-game testing.
- prop_barrel is the initial entry; add other verified meshes as prop rows in
  entities.csv. Runtime code compiles; appearance needs in-game testing.
- No new portal, loot-table or mob-animation changes are involved.

Confirmed chest-drop update:
- Builds include terrain, water materials, native chest templates and a ChestSupport package.
- Keep all generated packages together. ChestSupport uses the current map's terrain mesh.
- ChestSupport also includes DT_LootSlotDefinition.json and
  DT_LootSourceDefinition_LootActor.json, matching the working baseline.
- A fresh compiler build and install has been confirmed to drop weapons in-game.
- The compatibility profile preserves the tested map's unresolved native gameplay imports.
  It is an experimental reproduction of the working setup, not a proven root-cause fix.
- With chests present, the verified rules affect six chest types globally and disable
  equipment repeat filtering while installed. Chest abilities are left unchanged.
- Test your own builds offline; individual maps and untested mobs may behave differently.
- Installing automatically backs up and retires the recognised old ChestBaseline test.
  Its replacement is named Custom Map_ChestSupport_P inside the fixed map slot.
  Unrecognised or modified conflicting mods are left untouched and reported.

1. Extract this folder to a local drive and double-click MaptoMCD2_Compiler.bat.
   If Python is absent, the launcher downloads a verified copy to Tools\Python.
2. Click Set Up Now. The guide shows which tools are ready and has a
   Download / Repair Tools button for pinned Mod Kit, UAssetGUI, NeoRune SDK,
   .NET 10 SDK and Python packages. Downloads are checked against
   tool-manifest.json before use.
3. Follow the guide to locate your game and Unreal Engine 5.6.1 installation,
   enter your own AES key, and confirm Blueprint Loader. These remain manual;
   no game, engine, key or Blueprint Loader is supplied. Advanced Setup allows
   direct path editing later.
5. Build in a Minecraft Java void world, then Save and Quit.
6. Click Choose World and select the saved world folder containing level.dat.
7. Select Auto-detect (Void World), or Set Bounds and enter start X/Y/Z and width/height/length.
   Banner / Build Name controls the in-game title and build folder. Every new
   build installs to Paks\~mods\Custom Map with a fixed internal area tag.
   Changing the banner name or Minecraft world does not change that tag.
   Open Mods Folder opens the game's ~mods folder.
   Choose Level Theme: Plains, Forest, or Haven / Town. This changes terrain
   textures, not lighting, scenery or gameplay. Blocks without a matching
   themed texture keep their standard texture. Rebuild to apply changes.
   Auto includes every saved non-air block, including any starter platform.
   Click Build Map and confirm the detected bounds. When it succeeds, close
   Dungeons II and click Install Last Build.
8. Start the game OFFLINE and use the entrance in Haven.

Place objects in Minecraft before Save and Quit:
- For mobs, click Mob Names in the compiler for the complete list.
  In a structure block's LOAD mode, use a listed name such as zombie, skeleton,
  creeper or spider, choose rotation, then click Done (not Load).
  Only zombie is runtime-tested. All other mobs are experimental: animation,
  navigation, spawn height and boss/quest requirements may need individual fixes.
  The mob catalogue refreshes from your installed game's definitions on each build.
- Run /give @s minecraft:structure_block
- Place it on the floor where you want a chest. Open it, switch to LOAD,
  enter wooden_chest in Structure Name, then click Done. Do not click Load.
- For the return door, place another structure block, switch to LOAD,
  enter exit_door in Structure Name, then click Done. Do not click Load.
- For a respawn checkpoint, place a structure block on solid floor in LOAD
  mode, enter checkpoint in Structure Name, then click Done. Do not click Load.
  It places the game's fixed checkpoint volume and checkpoint visual, separate
  from doors. Checkpoint activation still needs an in-game test.
- Run /give @s minecraft:player_head and place one head on the floor where
  the player should arrive. Leave three blocks of headroom above the floor.
- Leave two blocks of opening for the door. You can place several chest
  markers, but only one exit_door and one player head per map.
- Save and Quit, then Build Map. The confirmation lists detected markers.
  Marker blocks disappear from the finished terrain. The chest uses the
  compiler's explicit melee/ranged weapon pool; the door returns to Haven.
  Each compiler chest requests one guaranteed weapon roll. Native item filters
  still apply. The weapon-pool override also affects the selected chest types
  elsewhere in the game while this mod is installed. Native chest actors and
  global anti-repeat rules are unchanged. Use OFFLINE mode only.
  DATA-mode markers with wooden_chest / exit_door in Custom Data also work.

Chest names (enter exactly, without spaces):
  wooden_chest
  fancy_chest
  wellspring_chest
  deep_dark_chest
  fancy_chest_procedural
  wellspring_chest_procedural
  camp_wooden_chest
  storminator_chest
  storminator_chest_final
Additional chest types are not yet tested in-game. Mission-specific types may
need their normal mission state for rewards or interaction.

Rotation:
- Chests and exit_door: choose 0, 90, 180 or 270 in the structure block's LOAD
  screen, then click Done, not LOAD. Save and Quit before building.
- Player arrival: rotate the player head to face the desired direction.
- Relative Position, Mirror and Include Entities are not used. The marker
  block itself sets the position. Rotation turns the actor around that spot.

The launcher installs Python 3.12.10 with Tcl/Tk locally if needed. Tool setup
creates .venv and installs the pinned versions in requirements-bootstrap.txt.

Setup requires:
- Dungeons-II-Mod-Kit folder containing Tools and Internal. Download / Repair
  Tools obtains a pinned copy automatically.
- Your own AES key matching your installed game version. Enter it in setup.
  It is encrypted using Windows DPAPI in LocalAppData/MaptoMCD2_Compiler/aes-key.dat
  and remembered for your Windows account until you replace it in setup.
  No key is supplied with the compiler or included in shared downloads.
- UAssetGUI with UE 5.6 support (automatically downloaded).
- Unreal Engine 5.6.1: Engine\Binaries\Win64\UnrealEditor-Cmd.exe.
- NeoRune SDK 1.0.0 and .NET 10 SDK (automatically downloaded into Tools).
- Your own Dungeons II 1.1.2 WinGDK Content\Paks folder.
- Blueprint Loader installed in the game before entering the map.

The compiler exports the runtime atlas automatically using the installed Mod Kit
and your saved AES key. No atlas or key is shipped. It creates Temp beside the
compiler when on the game drive, or MaptoMCD2_Compiler_Temp on the game drive
otherwise. Successful builds remove their temporary files; failures keep them.
The compiler extracts loose game data from your installation. It does not
download game data, AES keys, Unreal Engine, or Blueprint Loader. File checks
do not prove full game compatibility; test a disposable offline hero first.

Current limits:
- Invisible boundaries: run /give @s minecraft:barrier in Minecraft. Place
  barrier blocks around your map, save and quit, then rebuild. They export as
  invisible solid collision, not stone. Build walls high enough to prevent
  jumping over them. They count towards auto-detected map bounds, but cannot
  be used as the compiler's automatic arrival floor.
- Water is exported as a separate non-solid surface using the game's water
  material. Build a shallow pond with a solid bed underneath, fill it with
  water in Minecraft, save and quit, then rebuild normally. No marker needed.
  Water is excluded from solid collision and safe arrival locations.
  This preview does not add swimming, currents, waterfalls or drowning.
  Waterlogged blocks are not supported as water surfaces yet.
- Minecraft Java solid blocks are matched through the game's atlas and Mod Kit.
- Unsupported blocks are listed before conversion. Choose Continue to replace
  them with stone, or Cancel to stop. The original Minecraft save is unchanged.
  unsupported-blocks.json records names, counts and positions; supported-blocks.json
  lists the supported materials found in your game's definitions.
- Void worlds only. Manual bounds use start X/Y/Z plus width/height/length.
- Maximum 256 per axis, 1,048,576 cells and 100,000 solid blocks in this preview.
- Include a flat 3x3 area with three blocks of headroom. The compiler finds a
  safe arrival and return-door location. No safe area means the build stops.
- Fixed native Haven entrance; island arrival and return door follow the build.
  One installed map at a time.
- Experimental zombie marker: place a structure block on the floor, set its
  Structure Name to minecraft:zombie, then click Done (not LOAD). Leave two
  blocks of clear space above the floor. Save and quit Minecraft, then rebuild
  and install your map. Structure-block rotation controls its starting facing.
  This uses the native SW.Mob.Zombie spawner. Combat is confirmed. An experimental
  map-local helper plays the native walk clip from measured grounded movement;
  walking animation still needs in-game verification. Attacks and death montages
  remain native. This does not add navigation or pathfinding around obstacles.
- No minimap or navigation generation. Chest markers supported.
- This wizard has not yet completed its own end-to-end in-game test.

Every build gets a separate folder in Maps beside the launcher. The original
world is never written. Logs are inside the build folder. Only the compiler's
four package triplets are installed in Paks\~mods\Custom Map. Earlier copies
are backed up inside the build folder. Remove old tutorial mods from other
folders before installing. Mods replacing world-door tables may conflict.
To uninstall, close the game and move Custom Map out of ~mods.

Source and settings stay local. Do not share compiler-settings.json,
map-slot-identity.json, downloaded Tools, extracted game data or Maps build
folders. Share only the clean compiler ZIP.
