# Godot-Lab

Godot-Lab is the support-guide area for this game. It holds the reusable planning guides that help us generate and validate art, maps, assets, and implementation packs before they enter the Godot project.

## Current Workflow

For major map work, use five steps, with terrain/map composition completely separated from object production:

1. Create a map design page, including a clean object-free map plan plus an object inventory.
2. Step 2B: convert the approved map into a production-ready tileset and map composition with no objects baked in.
3. Step 2A: create an object implementation guide/inventory, then generate objects one by one with per-object guidance.
4. Import the map-only pack into Godot as terrain layers, collisions, navigation, zones, spawns, exits, and camera limits.
5. Add objects to the Godot map one by one as approved sprites/scenes with collision, Y-sort, occlusion, interaction, and placement metadata.

This mirrors the BooksyMissy character workflow: first make a clear visual reference, then make a focused app/game-consumable asset, then import and validate it in the running product. The important change is that map terrain and map objects are no longer generated together.

## Production Contract

The default Godot-Lab map workflow is production-ready output, not prototype output. Do not accept a step because it is "good enough for testing" unless the current request explicitly asks for a prototype.

Each step must produce the real deliverable needed by the next step:

- Step 1 must be a production design handoff: clear playable layout, object-free terrain plan, object inventory, separable runtime plan, and concrete companion exports or overlays.
- Step 2B must be production terrain/composition only: 2x/4x source tiles when practical, reusable final tile cells, style reference strip, transition pieces, 5x5 repeat previews, gameplay-scale crop, tile layers, collision/navigation/zone/spawn/exit metadata, and no gameplay objects baked into the map.
- Step 2A must produce object implementation guidance and then production object art one object at a time: 2x/4x standalone transparent source sprites when practical, selected final import sprite, collisions, Y-sort bases, occluders, interactables, and QA.
- Step 3 map import must only import packs that pass technical validation and visual QA against the object-free Step 1/Step 2B map. If the pack is `reference_only`, `prototype_only`, `repair_needed`, or `production_ready: false`, stop and repair the previous step unless Cristian explicitly authorizes a prototype.
- Step 4 object import must add only approved individual objects. A weak object should block that object's import, not block the whole map.

The failure mode to avoid is approving a schema-valid pack whose runtime view is visibly worse than the design. Passing JSON checks is not enough. The live Step 3 map must preserve the approved Step 1 composition, path shape, blocked-edge density, landmark placement, gameplay readability, and mood.

For gameplay work, use `gameplay_guide.md` as the source direction for starting plain, earning points, leveling Power/Agility/Intelligence, unlocking classes, class passive tracks, and material-colored powers.

For player-character art, use the split Players guides when downloading prompts: `player_design_page_guide.md` for Step 1 design-page generation and `player_sprite_action_guide.md` for Step 2 one-action sprite generation. `player_guide.md` remains the combined overview.

## Guides

- `map_design_page_guide.md` - how to create the creative/reference page and object container for a map.
- `object_guide.md` - Step 2A guide for object inventory plus one-object-at-a-time production-quality props, prizes, pickups, obstacles, landmarks, foreground occluders, and interactables.
- `map_tile_pack_guide.md` - Step 2B guide for converting the design into object-free Godot-ready terrain tiles, map composition, zones, navigation, collision, and metadata.
- `map_step3_import_guide.md` - how to import the map-only pack first, then add objects incrementally after separate approval.
- `gameplay_guide.md` - gameplay progression, stats, classes, passives, material colors, and balancing recommendations.
- `player_design_page_guide.md` - Step 1 AI guide for the approved player design page and technical handoff.
- `player_sprite_action_guide.md` - Step 2 AI guide for focused one-action sprite generation with explicit action input.
- `player_guide.md` - combined two-step overview for player design page and max-10-action sprite production.
- `asset_scale_guide.md` - shared pixel scale rules for player, enemies, objects, tiles, and generated image sheets.

## Output Standard

Each generated map should eventually have:

- a human-readable design page
- playable layout metrics for player/enemy footprint, path width, chokepoints, object spacing, pickup clearance, and readable blocked edges
- a Step 1 object container for reusable gameplay objects
- a production-ready object-free technical map pack
- high-resolution source art for important tiles/objects when practical, downsampled final runtime assets, and repeat/edge/alpha QA previews
- sliced tile/object sprites with real transparency where needed
- an object catalog mapping Step 1 object ids to Step 2 atlas/runtime ids
- atlas metadata for tiles first, then per-object metadata as objects are added one by one
- tile-layer placement metadata that can rebuild the map in Godot
- zone definitions
- collision/navigation notes
- a validation checklist