QJX-XXXX/game-visual-forge / skills/forge-2d-map
forge-2d-map
VerifiedGenerate and integrate playable 2D game maps with demand-driven or coherent-foundation terrain Tilemaps, complete building/prop objects, collision and traversal contracts, deterministic quality gates, and explicit user approvals. Use for RPG villages, overworlds, arenas, bridges, water, Unity Tilemaps, and map previews/imports.
Forge 2D Map
For external CLI/MCP generation, read the provider tool guide. Use existing installations and ask for user confirmation before installing missing tools.
Use this Skill when the result must be a runtime map that a player can walk through, collide with, and enter—not a decorative bitmap. Treat the request, generated candidates, processed artifacts, approval records, and Unity scene as one hash-bound contract.
Compatibility terms: standard_16 remains the one-page legacy profile; adaptive_hd remains the 4×4 multi-page profile; COHERENT_FOUNDATION is the fixed authored foundation route; and TWO_GATE names the two user gates. Tile dimensions use preset_16, preset_32, or custom; Unity derives cell size from tile_width / pixels_per_unit. Keep map-quality-report.json, Buildings, and Props in the artifact vocabulary.
Before local CLI work, follow the Python environment guide. Report missing Python/packages with instructions for the detected OS. Offer manual setup or assist within existing user authorization, use the exact selected interpreter, and verify the environment afterward.
Standard interaction
- Collect one grouped intake card before creating a request. Ask together for gameplay actions, visual direction, terrain topology, object identities and entrances, engine/project delivery, and source/regeneration policy. Do not repeat answered questions or ask one question per field.
- Run
map tile planwith the raw intake. It must return one of:needs_user_inputwith all unresolved groups in stable order;needs_user_confirmationwith one canonical summary and SHA-256;plannedonly after the user confirms that exact summary. No plan, Job state, or generated artifact may be written for either unresolved status.
- Keep exactly two user approval gates:
style-sample: approve visual direction before generation;assembled-map: approve one assembled review sheet after processing. Intake confirmation and agent preassembly review are workflow checks, not extra user gates.
- If a critical candidate fails, replace only that candidate inside the confirmed layout, source, cost, art direction, and delivery boundaries. Re-run preflight and agent review; do not terminally reject the run just because a candidate needs replacement.
Architecture routing
- Route a fixed authored layout containing any of
watercourse,bridge,complex-paths,paths, orbuilding-padstocoherent_foundation. Use one foundation image at map pixel dimensions, one unique tile per map cell, and verify pixel-identical recomposition. - Route reusable or procedural terrain to
demand_driven. Declare only the pages and semantics the layout needs. - Reject a request when its declared profile conflicts with the deterministic route.
- Use hybrid delivery: repeatable ground, roads, water, banks, and bridge deck are Tilemap layers; complete buildings and meaningful props are independent Sprite/Prefab objects.
- Water is blocked by default. A bridge is traversable only when its contract declares
traversable=trueand a positiveminimum_traversal_width; then preserve the declared corridor width and verify bridge cells are not terrain blockers. Main roads are not globally required unless the request declares a requiredroad_connectivity_policy.
Native atlas normalization
When the routed source is agent-native, normalize every generated atlas page after generation and before critical-asset preflight:
python skills/forge-2d-map/scripts/run.py map tile normalize-atlases --request <run>/tilemap-request.json --decision <run>/source-decision.json --atlas-page page-01=<generated-page-01.png> --atlas-page page-02=<generated-page-02.png> --repo-root <repo> --out-dir <run>/normalized
Use the returned output page paths for every later command. Pass --decision <run>/source-decision.json --normalization-report <run>/normalized/atlas-normalization-report.json to preflight-assets for the native path. The command preserves generated sources, records source/output hashes, supports the declared standard/adaptive/demand-driven atlas geometry, and rejects coherent_foundation. Do not silently normalize user-supplied or external-provider assets. Normalization fixes atlas geometry only; it is not evidence that Tile artwork, seams, bridges, buildings, or visual composition are correct.
Candidate preflight
Before ingest, run:
python skills/forge-2d-map/scripts/run.py map tile preflight-assets --request <run>/tilemap-request.json --architecture <run>/architecture-decision.json --atlas-page page-01=<foundation-or-atlas.png> --object-asset inn=<inn.png> --repo-root <repo> --out-dir <run>/preflight
python skills/forge-2d-map/scripts/run.py map tile record-asset-review --report <run>/preflight/critical-assets-report.json --decisions <run>/preflight/decisions.json --out <run>/preflight/preassembly-review.json --now <utc>
The report must contain candidate paths and hashes, deterministic checks, visual-review status, a critical-assets review sheet, and focused bridge/object crops. Ingest must refuse missing, rejected, stale, or hash-mismatched reports/reviews. Keep candidate pixels unchanged; labels belong in review-sheet margins. The page arguments are repeated --atlas-page values.
Two-gate CLI flow
After planned, route and ingest only with the accepted preassembly review:
python skills/forge-2d-map/scripts/run.py map tile route --request <run>/tilemap-request.json --capabilities <capabilities.json> --out <run>/source-decision.json --state <run>/job-state.json --now <utc>
python skills/forge-2d-map/scripts/run.py map tile ingest --request <run>/tilemap-request.json --decision <run>/source-decision.json --atlas-page page-01=<terrain.png> --object-asset inn=<inn.png> --repo-root <repo> --out <run>/raw/source-set.json --state <run>/job-state.json --style-approval <run>/source/style-approval.json --preassembly-review <run>/preflight/preassembly-review.json --critical-assets-report <run>/preflight/critical-assets-report.json --now <utc>
python skills/forge-2d-map/scripts/run.py map tile process --request <run>/tilemap-request.json --raw-image <run>/raw/source-set.json --repo-root <repo> --out-dir <run> --state <run>/job-state.json --now <utc>
Inspect assembled-review-sheet.png and the underlying tilemap-preview.png, tilemap-gameplay-crop.png, tilemap-collision-preview.png, bridge crops, object entrance crops, tile-seam-preview.png, tile-usage-preview.png, and map-quality-report.json. Record the assembled approval with the exact role order beginning with review-sheet, then validate:
python skills/forge-2d-map/scripts/run.py map tile record-approval --gate assembled-map --artifact review-sheet=<staging>/assembled-review-sheet.png --artifact tilemap-preview=<staging>/tilemap-preview.png --artifact gameplay-crop=<staging>/tilemap-gameplay-crop.png --artifact tilemap-placement=<staging>/tilemap-placement.json --artifact tilemap-objects=<staging>/tilemap-objects.json --artifact tilemap-collision=<staging>/tilemap-collision.json --artifact asset-set=<staging>/asset-set.json --out <run>/assembled-map-approval.json --repo-root <repo> --now <utc>
python skills/forge-2d-map/scripts/run.py map tile validate --request <run>/tilemap-request.json --raw-image <run>/raw/source-set.json --processing-result <staging>/processing-result.json --repo-root <repo> --staging-dir <staging> --final-dir <run>/final --style-approval <run>/source/style-approval.json --assembled-approval <run>/assembled-map-approval.json --state <run>/job-state.json --now <utc>
Approval hashes are rechecked at validation and Unity import. A rejection.json artifact is immutable and blocks publication/import. For COHERENT_FOUNDATION, inspect foundation.png, foundation.prompt.txt, and foundation-recomposition.png; recomposition must be pixel-identical.
Unity completion
Use integrations/unity/com.game-visual-forge.tilemap. Use AssetsOnly unless the user explicitly requests placing the prefab in the active scene; then use ImportAndPlace. The importer validates approvals and rejection state before mutation, preserves generated GUIDs on repeat imports, and runs post-placement scene acceptance. Acceptance must report passed and cover one owned root, tile/object counts, object transforms and Sprite bounds, colliders, doorway cells, terrain blockers, and traversable bridge cells. AssetsOnly records scene_acceptance_status=not_run.
After Unity changes, wait for compilation, inspect the console, run EditMode and PlayMode tests, save the target scene, confirm it is clean, and capture an orthographic top-down screenshot that matches the assembled review sheet. Never claim playability from a preview alone.
Use native image tools first under auto source policy when the required
text generation or reference editing operation is available. If it is absent,
ask the user to choose an API or another source. MiniMax is the recommended API;
credentials never count as source selection. For failed/rejected native output,
route with --native-outcome failed or quality-rejected and obtain the user's
choice before switching. Explicit source selections override this default.
Follow the shared image API workflow
through this Skill's launcher using image provider and --kind map or
--kind tilemap. Preflight the selected provider and keep each candidate's
generation attempt and provenance.
Keep provider safety explicit: native Agent tools, Jimeng, and Wanxiang remain
explicit choices. Confirm the provider, model, and parameters for every paid
attempt, and obtain explicit paid confirmation with a verified total quote.
Never install tools automatically. User-authorized Python/package setup may
follow the shared environment guide; do not repeat an approval already given.
Never resubmit a failed or
submission_unknown task. Keep generation within the confirmed intake and
candidate review; API download does not replace either map approval gate.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |