# Step 3 Map-Only Godot Import Guide

## Purpose

Step 3 imports a validated Step 2B object-free map pack into Godot. It should build a playable empty map from reusable terrain tiles, tile layers, collision, navigation, zones, spawn/no-spawn regions, exits, camera limits, and debug overlays hidden by default.

Step 3 does not import final props, pickups, houses, trees, signs, chests, gates, walls, foreground occluders, or interactable object sprites. Those are added later one by one after Step 2A object approval.

## Production Gate

Step 3 is a production map import step by default. It should proceed only when the Step 2B pack says:

- `production_ready: true`
- `step3_map_ready: true`
- visual QA confirms the object-free map matches Step 1's approved ground/path composition

Stop before import when:

- Step 2B is schema-valid but visually weaker than Step 1
- object art is baked into `ground_only_map.png` or `object_free_runtime_preview.png`
- tile repetition, missing transitions, or bad boundaries make the map feel like a test field
- 5x5 repeat previews show obvious stamp repetition, checkerboard rhythm, or generic filler
- gameplay-scale crops do not preserve Step 1's terrain density, route readability, or blocked-edge language
- collisions, navigation, zones, spawns, exits, or camera limits are vague
- runtime preview includes labels, arrows, route lines, collision colors, zone outlines, object slot markers, or debug guide art

Prototype import is allowed only when Cristian explicitly asks for a prototype. In that case, label the result prototype-only and do not use it as proof that the production pipeline succeeded.

## Map Import Order

1. Read `metadata/map.json` for map size, tile size, camera limits, coordinate spaces, asset status, and image paths.
2. Read `tiles/tileset_atlas.json`, `tiles/tile_source_manifest.json`, and `tiles/terrain_rules.json`.
3. Build or update Godot `TileSet` resources.
4. Build `TileMapLayer` nodes from `metadata/tile_layers.json`.
5. Create map boundary and terrain collision from `metadata/collisions.json`.
6. Create navigation polygons or route helpers from `metadata/navigation.json`.
7. Create zone `Area2D` regions from `metadata/zones.json`.
8. Create spawn/no-spawn regions from `metadata/spawn_tables.json`.
9. Create exit/transition `Area2D` regions from `metadata/exits.json`.
10. Load `metadata/object_slots.json` as future placement guides only; do not draw object art.
11. Place the player at the declared start or best visual-test/spawn fallback.
12. Apply camera limits and hide debug overlays by default.
13. Run validation, headless Godot load/export, and live web smoke checks.

## Runtime Layer Contract

Use these map-only layers consistently:

- `GroundTileLayer`: base terrain.
- `PathTileLayer`: roads, trails, floors, stairs, bridges, or walkable route surfaces.
- `TransitionTileLayer`: terrain edges, corners, caps, junctions, cliffs, water edges, walls, or ramps.
- `GroundDetailLayer`: small non-blocking floor detail.
- `BoundaryTileLayer`: terrain/boundary art that blocks movement when used.
- `CollisionLayer`: invisible `StaticBody2D` or tile collisions generated from metadata.
- `NavigationLayer`: invisible navigation regions or route helpers.
- `ZoneLayer`: invisible `Area2D` map regions.
- `SpawnerLayer`: enemy/pickup spawn markers or no-spawn regions.
- `ExitLayer`: map transition markers/triggers.
- `ObjectSlotLayer`: editor/debug-only future object slots, hidden in runtime.
- `DebugOverlayLayer`: optional authoring view, hidden in normal exports.

## Acceptance Checklist

Before publishing Step 3:

- Step 2B validator passes.
- Step 2B pack declares `production_ready: true` and `step3_map_ready: true`.
- Visual QA accepts the object-free terrain sheets, transition previews, runtime preview, and overlays.
- Visual QA accepts every base terrain 5x5 repeat preview and the gameplay-scale crop.
- The live Step 3 view resembles the approved Step 1 map in ground composition, path readability, blocked-edge language, terrain density, and mood.
- The map is larger than the viewport and camera limits stay inside the map.
- Tile layers are built from metadata, not one flattened poster image.
- No final gameplay objects are drawn.
- Future object slots are available as hidden debug/editor guides only.
- Collisions match terrain boundaries and intended blockers.
- Navigation regions/routes align with walkable space.
- Zones and exits trigger from the right regions.
- Spawn/no-spawn regions avoid the player start.
- Debug overlays are hidden by default.
- Mobile controls and portrait guard still work in the web export.
- Live web build loads over the secure Tailscale Serve URL.

## Step 4 Object Import

After Step 3 succeeds, add objects one at a time from Step 2A outputs.

For each approved object:

1. Read its `metadata/object_entry.json`.
2. Place the standalone sprite or scene at the matching Step 2B object slot.
3. Apply Y-sort/base point, pivot, and intended layer.
4. Add collision from `collision_patch.json`.
5. Add foreground/occluder art from `occlusion_patch.json` when relevant.
6. Add `Area2D` triggers from `interactable_patch.json` when relevant.
7. Run that object's `visual_tests_patch.json`.
8. Publish only when the map still plays correctly with the new object.

If an object fails, repair that object. Do not regenerate the whole map unless the object reveals a real map-slot or clearance problem.

## Publishing Checks

Run the focused checks that fit the change:

```bash
python3 scripts/validate_map_pack.py assets/map_packs/map-pack --output-dir reports/map-pack-validation --write-report
```

Then run a Godot headless scene load/export before publishing. After publishing, verify the live web files return non-empty `index.pck` and `index.wasm`.