# Step 2A One-Object Production Guide

## Purpose

Step 2A produces map objects one at a time after the object-free Step 2B map pack exists. It uses the Step 1 object inventory and Step 2B `metadata/object_slots.json` to create a single production-ready Godot object with sprite art, metadata, placement, collision, Y-sort, occlusion, interaction, and visual QA.

Do not use Step 2A to generate a giant object pack in one pass. The production unit is one object or one tightly related variant set.

## Current Workflow

1. Step 1 defines the map design, object inventory, and object intent.
2. Step 2B creates the object-free map and reserves future object slots.
3. Step 3 imports the object-free map into Godot.
4. Step 2A produces one object for one slot.
5. Step 4 imports that one object into the Godot map.
6. Repeat Step 2A/Step 4 for the next object.

This prevents one weak object sheet from blocking the whole map and makes it easier to judge collision, scale, Y-sort, occlusion, and interaction in the actual running scene.

## Production-Ready Default

Ask for each object as production-ready by default. Do not accept `reference_only`, `prototype_only`, `repair_needed`, cropped, blurry, matte-backed, alpha-dirty, or visually downgraded output unless Cristian explicitly asks for a prototype.

If the image model cannot produce the object cleanly, the output should say `object_import_ready: false` and list repairs. Do not fake approval.

## Required Per-Object Output

```text
map-object-work/
  README.md
  source/
    step1_object_card.png
    step1_map_reference.png
    step2b_object_slot_reference.png
  objects/
    individual/
      signpost_north_exit_01.png
  preview/
    signpost_light_dark_edge_qa.png
    signpost_map_background_preview.png
    signpost_scale_preview.png
    signpost_depth_preview.png
    signpost_interaction_preview.png
  metadata/
    object_entry.json
    placement_patch.json
    collision_patch.json
    occlusion_patch.json
    interactable_patch.json
    visual_tests_patch.json
  validation-report.md
```

If an object has no occlusion or interaction, include the corresponding patch file with an empty list and a short reason.

## Object Categories

- Blocking props: rocks, trees, walls, houses, fences, cliffs, locked gates, large ruins.
- Decorative props: grass clumps, tiny stones, flowers, rugs, floor clutter, broken boards.
- Soft blockers: bushes, cracked barriers, destructible debris, temporary gates.
- Prizes and pickups: coins, XP, health, rare rewards, keys, relics, scrolls, holy items.
- Landmarks: shrine, cave gate, ruin altar, old statue, bridge, signpost, tower, fountain.
- Interactables: chests, doors, signs, blessing points, locked gates, vendors, readable objects.
- Foreground occluders: roofs, tree canopies, arches, cliff lips, wall tops, tall fence rails.

## Quality Bar

Approved object sprites must:

- match the approved Step 1 art style and Step 2B map palette
- communicate their gameplay purpose at a glance
- guide attention when the object is meant to indicate a route, pickup, exit, landmark, danger boundary, or interaction
- be readable at gameplay zoom
- use consistent top-down/action-RPG perspective and light direction
- have clean silhouettes and intentional shapes
- use real transparent alpha, not checkerboard or matte backgrounds
- have generous transparent padding around the full silhouette
- avoid cropped edges, missing parts, halos, blurry upscales, pasted-looking cutouts, alpha dust, and detached specks
- avoid text labels, arrows, UI borders, guide marks, or grid marks inside importable pixels
- use a stable id that matches Step 1 and the Step 2B object slot
- include collision, Y-sort/base point, pivot, layer role, occlusion, interaction, and placement metadata when relevant

Prefer one excellent object over a sheet of inconsistent objects.

## Image Generation Strategy

Generate the object as a standalone transparent sprite first. Contact sheets and atlases are packaging after approval, not the source of the art.

For important objects, use focused prompts:

- one standalone sign, chest, shrine, gate, tree, rock barrier, house, landmark, pickup, or other object
- one small variant set only when the variants are closely related and easy to separate cleanly
- one foreground occluder cutout only after the base object is approved

Do not crop production sprites from a painted screenshot, object container, contact sheet, or preview. If the output looks like a square crop from a sheet, regenerate it.

Repair wording:

```text
Regenerate this as one isolated production sprite, not as a crop from a sheet. Put only this object on a transparent PNG canvas with generous empty padding around the full silhouette. Do not include a white/gray/matte background, border, contact-sheet cell, labels, other objects, or cropped edges. The object should look intentionally painted as a complete standalone top-down game sprite.
```

If the model cannot produce real transparent alpha, mark the output `reference_only` until alpha cleanup is done and verified.

## High-Fidelity Object Art Contract

Ask for oversampled source art by default. If the final object sprite will be imported around 64-256 px wide in Godot, request the source sprite at 2x or 4x that size, then downsample after alpha cleanup. Keep the high-resolution source in `objects/source_2x/` or `objects/source_4x/`, and keep the final import PNG in `objects/individual/`.

For each important object, request three small candidate variants before approval when practical:

- same gameplay role
- same approximate footprint
- same palette and light direction
- different silhouette/readability choices

Pick one approved variant, then create final metadata and atlas packaging only for that chosen object.

Required quality previews:

- light-background alpha edge preview
- dark-background alpha edge preview
- Step 2B map-background placement preview
- player scale preview
- collision footprint preview
- Y-sort/front-behind preview when the object can occlude the player
- interaction side/trigger preview when usable

Quality targets:

- clear silhouette before texture detail
- gameplay role readable at camera distance
- collision footprint smaller and more useful than the visible art when appropriate
- bottom contact point obvious for Y-sort
- enough padding that the whole object reads as intentionally painted, not cropped
- no matte halo, alpha dust, cutout debris, or detached pixels
- no text labels baked into the sprite, even for signs; sign text can be metadata or a later UI/detail layer
- no sheet-first generation for important objects

Visual rejection rule:

- If the object looks like it was cropped from a contact sheet or map painting, regenerate it as one isolated sprite.
- If the object is technically transparent but weak, muddy, over-smoothed, or hard to read in the map-background preview, set `object_import_ready: false`.
- If a whole object pack is generated at once and the important object quality varies, approve nothing by default; split into one-object requests.

## Metadata Requirements

`metadata/object_entry.json` should include:

- `step1_object_id`
- `object_slot_id`
- `runtime_id`
- `display_name`
- `category`
- `individual_source_image`
- `production_status`
- `object_import_ready`
- `intended_layer`: below_player, y_sort, foreground_occluder, pickup, interaction, decorative, collision, or custom declared layer
- `collision_role`: blocking, decorative, soft_block, pickup, hazard, gate, interactable, or none
- `collision_footprint` or `collision_rect`
- `y_sort_base_point`
- `pivot`
- `foreground_occluder_id` when relevant
- `interactable_id` when relevant
- `placement_slot`
- `readability_note`
- `navigation_or_attention_purpose`

`metadata/placement_patch.json` should describe the single placement in map coordinates and reference the Step 2B object slot.

`metadata/collision_patch.json` should contain only this object's blocking or soft-blocking footprint.

`metadata/occlusion_patch.json` should contain roof/canopy/top-pixel regions when the player should walk behind the object.

`metadata/interactable_patch.json` should contain trigger regions for doors, signs, chests, pickups, gates, shrines, readable objects, vendors, transitions, or custom interactions.

`metadata/visual_tests_patch.json` should include:

- object scale check against player
- collision check
- front/behind Y-sort check when relevant
- occlusion check when relevant
- interaction/pickup check when relevant
- map-background preview check
- alpha/edge cleanup check

## Approval Checklist

Approve the object for import only when:

- standalone transparent PNG exists under `objects/individual/`
- it matches the Step 1 style and looks natural on the Step 2B map
- no alpha dust, matte halo, edge contact, crop debris, labels, or guide marks are present
- scale matches the player and the reserved object slot
- collision footprint is smaller and more useful than visible art when appropriate
- Y-sort base point sits at the real ground-contact point
- occluder cutout exists when the player should pass behind upper pixels
- interactable trigger is on the usable side
- metadata references the exact Step 2B object slot
- `object_import_ready: true`

Repair before import when:

- sprite is valid but visually weak, muddy, cropped, over-smoothed, haloed, or mismatched
- object looks like a sheet crop instead of a complete standalone sprite
- collision, Y-sort, occlusion, interaction, or placement metadata is vague
- pickup/interaction readability is too low at gameplay zoom

Reject when:

- the object exists only inside a flat map/background
- the sprite has fake checkerboard or matte background
- the sprite is cropped from a concept/contact sheet
- important metadata is missing
- the output claims production-ready while the art is placeholder quality

## Prompt Template

```text
Create one production-ready Step 2A Godot map object from the approved Step 1 object inventory and Step 2B object slot metadata.

Target object:
- step1_object_id: [id]
- object_slot_id: [id from metadata/object_slots.json]
- role: [blocking/decorative/pickup/interactable/gate/transition/landmark/foreground-only/etc.]
- expected map position or reserved footprint: [from object_slots.json]
- gameplay expectation: [what the player should understand at a glance]
- navigation/attention purpose: [if any]
- style reference: [Step 1 object card and Step 2B map palette]

Do not create terrain tiles, a full object pack, a contact-sheet-only asset, or a giant map image. Produce this one object only.

Output a zip-ready `map-object-work/` folder with:
- source references
- one standalone transparent PNG under `objects/individual/`
- light/dark alpha edge QA preview
- map-background preview
- scale preview
- depth and/or interaction preview when relevant
- object_entry.json
- placement_patch.json
- collision_patch.json
- occlusion_patch.json
- interactable_patch.json
- visual_tests_patch.json
- validation-report.md

Quality requirements:
- Match the approved Step 1 style and Step 2B map palette.
- Generate the object as an intentional standalone sprite, not a crop from a larger sheet.
- Generate source art at 2x or 4x when possible, then downsample to the final import sprite after cleanup.
- Provide up to three candidate variants for important objects, then mark only the selected final as import-ready.
- Use real transparent alpha with generous padding.
- No checkerboard, matte background, labels, arrows, borders, guide marks, missing pieces, edge contact, alpha dust, detached pixels, or crop debris.
- Make the object readable at gameplay zoom.
- Make its gameplay purpose clear: blocked, collectible, readable, usable, safe path, danger boundary, exit, landmark, or decoration.
- Include light/dark alpha edge previews, map-background preview, player scale preview, collision footprint preview, and Y-sort/interact previews when relevant.
- Include collision footprint, Y-sort base point, pivot, intended layer, placement slot, and interaction/occlusion metadata when relevant.
- Include `object_import_ready: true` only when this exact object is ready to add to the Godot map.

If the object cannot meet production quality, set `production_ready: false`, `object_import_ready: false`, and list the required repairs.
```