summer-engine 4.3.0 → 4.6.0

package/library/skills/make-game/SKILL.md

@@ -40,13 +40,15 @@ Distilled blueprints for common genres live in this skill's `references/` folder
 | Third-person action / 3D platformer | `references/3d-third-person.md` | `references/3d-third-person-systems.md` | Node3D / CharacterBody3D / SpringArm3D |
 | First-person horror | `references/3d-horror.md` | `references/3d-horror-systems.md` | Node3D / CharacterBody3D / Camera3D on Head |
 
+**2D and 2.5D games look painted.** For any 2D or 2.5D request (top-down, RPG, cozy, side-scroller, platformer look), build the world with the `painted-25d-world` skill: a 3D blockout under one fixed orthographic camera, an AI paint-over projected onto the blocks, sprite characters (Node3D / CharacterBody3D / translate-only Camera3D). Use the 2D playbooks above for the core loop, mechanics and build order only, not for the scene tree or art. Do not start a 2D game from a 2D template unless the user asks for that template.
+
 No playbook (racing, sandbox, sim): build fresh through the phases below. The playbooks lean on these system skills — load one when its mechanic comes up: `character-movement`, `camera-rigs`, `combat-basics`, `save-load`, `ui-basics`, `multiplayer-project`.
 
 These rules from the playbooks apply to every genre:
 
 - **2D scales to the viewport.** Set `display/window/stretch/mode = canvas_items` and `stretch/aspect = expand`; UI uses Control anchors; code-positioned nodes compute from `get_viewport_rect().size`. Never hardcode 1920x1080.
 - **Playable slice, not tech demo.** Name the core loop in one sentence; every input gets feedback (tween, sound, particle, flash, shake); progression is visible; a restart exists. The bar is "feels good for 30 seconds".
-- **Fast first draft when someone is waiting.** The first playable version uses shapes, the palette and any template art, plus at most one or two generated assets the person specifically asked for; generation takes minutes, so it never blocks the first play. Say plainly that it is a first draft to get a feel for the game, that the art is not final, and ask if this is the direction they want. Generate the rest of the art in later passes.
+- **The first playable already looks good.** People judge Summer by the first frame of their first game, so the first version looks finished even when they ask for a quick prototype: keep the features they asked for and raise the look. Sky and sun with shadows, tonemapping and a little fog; a texture on every surface; real models for the player, characters and main props from the starter project or the Summer asset library (`summer_assets_search`), never capsules or boxes as final art; one colour palette; a styled UI font. Generation takes minutes, so it never blocks the first play: use starter and library art first, plus at most one or two generated assets the person asked for, and generate the rest in later passes. Before you say it is ready, play it and look at a screenshot of the running game, not the editor (the editor shows a preview sky and sun that the game does not have).
 - **A way back to the title.** From inside play, a pause menu or a **Leave** button returns to the title screen without quitting the app.
 - **Text the default font can show.** No emoji or symbols (▲ ◀ ★ ♥ ✓) in UI text: they render as boxes with hex codes. Use words or icons; see `ui-basics`.
 
@@ -199,7 +201,7 @@ Repeat until every mechanic in the plan is implemented OR the user calls cut.
 
 ## Phase 5: Layer (look + sound)
 
-**Goal**: the game stops looking like a programmer art prototype.
+**Goal**: deepen the look and add sound. The first playable already looks good (see "The first playable already looks good" above); this phase writes the art bible, replaces the remaining stand-in art and adds audio.
 
 ```
 Skill: art-direction
@@ -274,7 +276,7 @@ If the brief said "jam" or "prototype", skip this phase. If the brief said "game
 |---|---|
 | Skip the brainstorm because the user said "FPS" | Even with the genre named, you need the scope cut list. Otherwise mechanic 4 quietly sneaks in and the game never ships. |
 | Let mechanic 2 start before mechanic 1 is verified clean | Compounding bugs. You'll spend the rest of the session debugging which mechanic broke what. |
-| Stack art direction on top of unfinished mechanics | Art changes are reversible only if the underlying scene structure is stable. Get mechanics done first. |
+| Change the art style while mechanics are unfinished | Art changes are reversible only if the underlying scene structure is stable. Get mechanics done before a new style; the first playable still starts good-looking. |
 | Treat "polish" as required | If the brief says "jam in 2 days", polish is a cut item. Respect the brief. |
 | Run all phases without confirming | The user owns scope. Stop at every checkpoint. |
 | Ship online play behind a setting nobody changes | Hosted join is never exercised, so it breaks without anyone noticing. Reachable by default, or the owner joins online before every release. |
@@ -311,7 +313,7 @@ No Summer MCP tools in this session? Run each one as a command; when `summer --v
 
 | In this skill | Command |
 |---|---|
-| `assets.search` | `summer assets search` |
+| `assets.search`, `summer_assets_search` | `summer assets search` |
 | `summer_docs_read` | `summer docs read` |
 | `summer_add_node` | `summer engine add-node` |
 | `summer_batch` | `summer engine batch` |

package/library/skills/make-game/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/make-game
 kind: skill
-version: 1.1.0
+version: 1.2.0
 summary: "Orchestrate 'make me a game': brainstorm, plan, scaffold, mechanics, art, audio, polish, verify, ship."
 use_when:
   - the user says 'make me a game', 'build me a game', 'I want to make a [genre] game', or 'let's build something' — running the full game-dev pipeline
@@ -33,6 +33,7 @@ related:
     - skill/camera-rigs
     - skill/combat-basics
     - skill/save-load
+    - skill/painted-25d-world
 source: official
 license: MIT
 status: stable

package/library/skills/navigate-summer/SKILL.md

@@ -24,10 +24,10 @@ Rigid skill: follow the rules below exactly.
 | The user wants to… | Do |
 |---|---|
 | **see / check / decide** — plan and billing (money), their published games and releases, usage, pricing, the MCP setup guide for their agent, docs, the scene or node you just built ("show me") | **Open the surface** with `studio.open` |
-| **get a result** — add a node, set a property, import an asset, run the game, publish | **Act through Summer tools** (mutation tools, `summer_play`, `store.publish`); do not open the editor to do by hand what a tool does |
+| **get a result** — add a node, set a property, import an asset, run the game, publish | **Act through Summer tools** (mutation tools, `summer_play`, `store.publish`); do not click through the editor by hand to do what a tool does |
 | **both** ("add a camera and show me") | act first, then open the scene / select the node so the user sees the result |
 
-Never open a browser or switch the editor's tab as a side effect of building. Opening is a user-visible action — do it because the user asked to look, and say what will open before it opens.
+Never open a browser or switch the editor's tab as a side effect of building. Opening a page or panel is a user-visible action — do it because the user asked to look, and say what will open before it opens. Playing the game and taking screenshots to check your own work is different: that is allowed and expected (`summer_play`, then `summer_screenshot` or `summer_frame_shot`).
 
 ## How to call it
 
@@ -70,9 +70,11 @@ No Summer MCP tools in this session? Run each one as a command; when `summer --v
 | In this skill | Command |
 |---|---|
 | `summer_docs_read` | `summer docs read` |
+| `summer_frame_shot` | `summer engine frame-shot` |
 | `summer_get_project_context` | `summer engine get-project-context` |
 | `summer_is_running` | `summer engine is-running` |
 | `summer_play` | `summer engine play` |
+| `summer_screenshot` | `summer engine screenshot` |
 | `store.publish` | `summer store publish` |
 | `studio.open`, `summer_open` | `summer studio open` |
 <!-- /shell-commands -->

package/library/skills/new-project/SKILL.md

@@ -42,37 +42,29 @@ Default: `my-game`. If they say "anything is fine" or similar, use `my-game` and
 Two built-in options:
 
 - `empty` — root `Node3D` only. Pure blank canvas. Best for: experimentation, when the user knows exactly what they want to build.
-- `3d-basic` — root `Node3D` with `Camera3D`, `DirectionalLight3D`, a floor `MeshInstance3D`, and a `WorldEnvironment`. Best for: first-time users who want something they can press Play on.
+- `3d-basic` — root `Node3D` with a procedural sky on a `WorldEnvironment`, a sun with soft shadows, a tinted ground, one hero mesh and a `Camera3D` that frames it. Best for: first-time users who want something they can press Play on.
 
 If you're not sure which fits, ask:
 
 > "Empty (just a root node) or 3d-basic (camera, light, and a floor — you can press play immediately)?"
 
-If the user has clearly invoked `brainstorm-game` already and the brief calls for 3D, default to `3d-basic` and mention you did. If 2D, use `empty` (we don't ship a 2D-basic yet).
+If the user has clearly invoked `brainstorm-game` already and the brief calls for 3D, default to `3d-basic` and mention you did. If 2D or 2.5D, use `empty`, keep its `Node3D` root and build the world with `painted-25d-world` (a painted 3D blockout under a fixed orthographic camera with sprite characters).
 
-### 3. Create
+### 3. Create and open it
 
-```
-summer create empty my-game
-```
-
-or
+One command creates the project and opens it. When Summer Engine is missing it also installs it (about 660 MB): ask the user first, and pass `--yes` only with their OK (without it nothing is installed):
 
 ```
-summer create 3d-basic my-game
+summer dev --yes 3d-basic my-game
 ```
 
-The command writes `project.godot` and the chosen `main.tscn`. It makes no network call.
+or `summer dev --yes empty my-game`. It writes `project.godot` and the chosen `main.tscn` (no network call for these two), opens the editor and waits until it answers.
 
-### 4. Open it
-
-```
-summer run my-game
-```
+No shell in this session (a chat app)? Call `projects.create_local` with `template` and `name`, then `projects.open_local` with its `projectPath` (and `install: true` only after the user said yes to installing the engine).
 
-Confirm the engine launched and the project loaded. If `summer run` fails, run `summer doctor` and surface the failure to the user.
+Confirm the project loaded with `summer_get_project_context`. If it fails, run `summer doctor` and surface the failure to the user.
 
-### 5. Don't keep going automatically
+### 4. Don't keep going automatically
 
 After scaffolding, **stop and let the user direct.** A common mistake: fire `fps-controller` or `design-mechanic` automatically because "now we make a game." Wait. The user might want to:
 
@@ -88,16 +80,16 @@ Ask: "Project is open. What do you want to build?"
 | Don't | Why |
 |---|---|
 | Skip the name question and use `my-game` silently | The user has opinions about the directory name. Two seconds of asking saves a `mv` later. |
-| Use `summer create 3d-basic` for a 2D game | Wrong starting scene. Use `empty` and let the user/agent build the 2D root from there. |
+| Use `summer create 3d-basic` for a 2D game | Its light and floor fight the painted look. Use `empty` and follow `painted-25d-world`. |
 | Default to a community template | That's `browse-templates`. This skill is specifically for "blank canvas." |
 | Continue into `fps-controller` automatically | Most users want to brainstorm or set art direction first. Stop and ask. |
 | Run this when the user is in an existing project | Check `summer status` or `summer_get_project_context` first. If a project is already open, the user probably wanted to modify it, not create a new one. |
 
 ## Edge cases
 
-- **Engine not running** → that's fine. `summer create` doesn't need the engine. After scaffolding, `summer run <name>` will start it.
-- **User wants 2D but `empty` is the only 2D-friendly built-in** → use `empty`, then set up a 2D scene root via `summer_replace_node` (Node3D → Node2D). Mention this — don't surprise the user.
-- **Directory exists** → the CLI errors out. Ask for a different name; don't try to overwrite.
+- **Engine not running** → that's fine. `summer dev` (or `projects.open_local`) starts it; `summer create` alone doesn't need it.
+- **User wants 2D or 2.5D** → use `empty`, keep the `Node3D` root and follow `painted-25d-world`. Use a `Node2D` root only when the user asks for a classic 2D tile or pixel game.
+- **Directory exists** → a folder that already holds `project.godot` is just opened; one with other files is refused. Ask for a different name; don't try to overwrite.
 
 ## Closing
 
@@ -111,5 +103,6 @@ No Summer MCP tools in this session? Run each one as a command; when `summer --v
 | In this skill | Command |
 |---|---|
 | `summer_get_project_context` | `summer engine get-project-context` |
-| `summer_replace_node` | `summer engine replace-node` |
+| `projects.create_local` | `summer projects create-local` |
+| `projects.open_local` | `summer projects open-local` |
 <!-- /shell-commands -->

package/library/skills/new-project/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/new-project
 kind: skill
-version: 1.0.4
+version: 1.0.5
 summary: "Create a blank Summer Engine project: ask for the project name and run summer create empty."
 use_when:
   - the user wants a fresh blank Summer Engine project — from scratch, blank canvas
@@ -20,6 +20,7 @@ compatibility:
 related:
   skills:
     - skill/make-game
+    - skill/painted-25d-world
 source: official
 license: MIT
 status: stable

package/library/skills/painted-25d-world/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: painted-25d-world
+description: "Build a 2D or 2.5D game as a painted world: a 3D blockout under one fixed camera, an AI paint-over projected onto it, sprite characters."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: 2d
+user-invocable: true
+allowed-tools: Read Write Edit Bash summer_write_file summer_read_file summer_create_scene summer_add_node summer_set_prop summer_run_script summer_save_scene summer_screenshot summer_play summer_stop summer_get_script_errors summer_assets_generate_image summer_get_project_context summer_jobs_wait summer_import_from_url summer_call
+paths: ["painted/**", "**/*.gdshader", "**/*.gd", "**/*.tscn"]
+---
+
+# Painted 2.5D world
+
+The world looks like one hand-painted illustration, but it is real 3D: the player walks behind houses, enters
+buildings and collides with walls. The trick: build the level from cheap blocks, render the blocks from one fixed
+camera, have an image model paint over that render, then project the painting back onto the blocks from the same
+camera. Characters are 2D sprite sheets standing in the 3D world.
+
+## The rule
+
+**Whenever a user asks for a 2D or 2.5D game** (top-down, RPG, cozy village, adventure, farming, dungeon,
+side-scroller, platformer look), build it with this skill. Do not start from a 2D template or a Node2D tile map.
+The genre playbooks in `make-game` still decide the mechanics; this skill decides how the world is made and looks.
+
+- Top-down / three-quarter games: camera 30 degrees down, 45 degrees around (houses show two faces). Image
+  models draw "isometric" as 2:1 dimetric, which is exactly 30 degrees down; use 30 so the blockout can match a
+  generated concept.
+- Side-scrollers: the same technique with a camera that looks along the side axis (about 10-20 degrees down,
+  0 degrees around) and pans left and right only. Paint one frame per screen-wide chunk.
+
+Tell the user once, before the first character generation or animation: "The world blockout is cheap. Animating
+characters costs a couple of dollars in credits and can come out with mistakes; I will check every frame." Then
+continue. The blockout, the camera and the projection cost nothing.
+
+## Hard rules (a playtest found each one)
+
+1. **Scale.** Doors 2.5 m. Hero height = door height / 1.15 (2.15 m). One-storey eaves 3.5-4 m, two-storey about
+   6 m. Check the hero against a door in the first screenshot.
+2. **The gait follows the game type.** Cozy, exploration and RPG games walk by default (about 1.8 m/s, walk cycle)
+   and run on Shift (about 4 m/s, run cycle). Action games may run by default (about 4.2 m/s, run cycle). Never
+   play the run cycle for the default gait of a cozy game. `painted_player.gd`: `move_speed`, `sprint_speed`,
+   `run_cycle_from` (3 m/s).
+3. **Animation speed follows ground speed.** A cycle's natural speed is the ground speed at which its feet stick
+   (stride per cycle x cycles per second, scaled to the hero height). Each sheet json carries `height_m`,
+   `stride_m` and `cycles_per_s` per kind; `speed_scale = speed / natural speed`, clamped. The feet must not
+   slide. Never one fixed fps for every speed.
+4. **Framing.** The game camera shows about 16 m across (7-8 hero heights). Clamp it inside the painting with
+   the real viewport aspect, never an assumed 16:9. The clear colour is the painting's edge colour, per location.
+   Rooms are framed whole, like a stage.
+5. **At least one enterable building** in every village: a cut-away interior, same view direction, its own 4K
+   paint-over, door triggers both ways, a door gap of about 1.8 m. Blockout door and step slabs are hidden in the
+   game; the painting shows them.
+6. **Eight directions** for idle, walk and run: down, up, left, right, down_left, down_right, up_left, up_right.
+   One clip per direction and animation. Mirror only where every frame holds up (never asymmetric hair, a held
+   weapon or a walking stick). The player picks the facing by 45 degree sectors.
+7. **Blockout proportions from the concept.** Dormers sit on the roof slope (never floating); gables and roofs
+   from measured concept pixels; doors 2.5 m; a low block for every flower bed, barrel and crate.
+8. **No long cast shadows in the paint.** "Soft short contact shadows only, no long cast shadows on the ground":
+   baked long shadows look wrong once the hero walks through them.
+9. **Verify in a real window.** Run the game with `-- --shots=<dir>`: `painted_world.gd` walks and runs the hero
+   through `shot_plan` (add a walk through each door) and saves a JPG per step. Look at every frame.
+10. **Generate a walk whose stride fits the default speed.** Keep the walk cycle's playback within about 1.5x
+   (`speed / natural <= 1.5`): a short-step clip played fast looks wrong. Measure the natural walk speed; if it
+   is too low, regenerate the walk clips with the brisk long-stride prompt (step 9). The plug-in walks are natural
+   at about 1.25-1.4 m/s at 2.15 m, so 1.8 m/s plays at 1.3-1.45x. Short, 4-heads-tall characters reach about
+   half a body height per cycle at most; taller proportions (6-7 heads) give longer strides.
+
+## Steps
+
+### 0. The project and the engine
+
+- No project yet: `summer create empty <name>` (or write a plain `project.godot`), open it with
+  `summer run <path>`, and check that `summer_get_project_context` answers for that project.
+- `engine_not_running` while an editor is open: the editor was started with another HOME, or the MCP is bound to
+  a different editor. Start this project's editor with `summer run <path>`, or drive it from a shell with the CLI
+  and `SUMMER_ENGINE_PROJECT=<path>` set.
+- Image generation through Summer: always pass an `idempotencyKey` and `numImages: 1`. A call that answers
+  `outcome_unknown` (a timeout) may still run and charge: retry with the **same** key, never a new one.
+
+### 1. Concept (one image)
+
+`summer_assets_generate_image` with `model: "seedream-5-pro"`, `width` 2048, `height` 1152 (the largest 16:9
+image Summer's models return; the others stop near 1024x576):
+
+```
+Hand-painted illustration of <place>, rich detail, warm painterly light, seen from a high three-quarter
+top-down camera (looking down about 30 degrees, orthographic, no perspective distortion), like a tilted
+isometric game map. In the scene: <every object with its rough position: "three cottages around a dirt
+plaza, a well with a small roof in the centre, a striped market stall top left, fences, round trees">.
+Clean readable shapes, soft brush texture, no characters, no text, no UI, no border.
+```
+
+Pick the image the user likes. It is the art direction and the layout.
+
+### 2. Blockout (cheap: you write it)
+
+Write one GDScript or scene that rebuilds the concept **one to one** from the fixed camera: the same building
+positions and footprints, roof shapes (gable, hip, dormers on the slope, thatch overhang), chimneys, the well, the
+stall, fences, paths, trees and bushes where the concept has them. Use `MeshInstance3D` with `BoxMesh`,
+`PrismMesh`, `CylinderMesh`, `SphereMesh` (not CSG: only MeshInstance3D nodes get the painting). Give each
+material one flat colour (red = tile roof, yellow =
+thatch, dark blue = slate, cream = plaster walls, grey = stone, brown = wood, tall brown slabs = doors, green =
+grass, pink low blocks = flower beds): the colours tell the painter what each block is, and the paint-over prompt
+repeats them as a colour key. Name door and step slabs `..._door` / `..._steps`: they are hidden in the game.
+
+```
+World (Node3D, painted_world.gd: player_path, start_location)
+  Village       Node3D, painted_location.gd (paint, frame_whole = false)
+    PaintCamera Camera3D  ORTHOGONAL, KEEP_WIDTH, size = frame width in metres (40 for a village square)
+                rotation_degrees = Vector3(-30, 45, 0)   # 30 down, 45 around; never change it later
+                position = frame centre - forward * 60, far = 200
+    Painted     Node3D    every block (or blockout_builder.gd reading a spec), Ground walkable
+  Cottage       Node3D, painted_location.gd (frame_whole = true), 100 m off to the side
+    PaintCamera same rotation, size 14 for a 9 x 7.5 m room
+    Painted     ...
+  DoorIn        Area3D, painted_door.gd (to = Cottage, spawn = a Marker3D inside the room)
+  DoorOut       Area3D, painted_door.gd (to = Village, spawn = a Marker3D outside the village door)
+  GameCamera    Camera3D
+  Player        CharacterBody3D, painted_player.gd (sheet, sheet_json)
+```
+
+One world script owns the player, the camera and the doors; locations never move the player themselves.
+`painted_world.gd` sets the player up after every child is ready, so the node order is free.
+
+In a `.tscn`, the paint camera line for 30 down, 45 around is (Godot writes the basis by rows; hand-written
+columns give a wrong camera):
+`transform = Transform3D(0.707107, -0.353553, 0.612372, 0, 0.866025, 0.5, -0.707107, -0.353553, 0.612372, cx + 36.742, cy + 30, cz + 36.742)`
+for a frame centred on (cx, cy, cz), 60 m back along the view.
+
+**Write the blockout as a spec** (`_building-blocks/blockout_builder.gd` documents the JSON: box, prism, cyl,
+sphere, poly ground, invisible wall blockers). The same file drives the engine (the builder is the location's
+`Painted` node) and an engine-free wireframe preview over the concept (`tools/preview.py`), so the fitting loop
+needs no engine runs.
+
+- **Gable roofs are two parts:** a wall-coloured prism for the gable triangle plus two thin slanted roof slabs
+  with an overhang. A single roof-coloured prism makes the painter paint roof on the gable wall.
+- **Edges and water:** put invisible `wall` blockers along water and ledge edges, with gaps at pier roots and
+  doorways. Ground made from a polygon is one-sided: use the spec's `poly` (two-sided collision) or a box.
+
+Solid things get a `StaticBody3D` and a box/cylinder shape: walls, trunks, fence posts, the well, furniture.
+Things the player walks behind need real height (houses, trees, stalls).
+
+**Paint richness follows blockout density.** The painter details what the blocks give it. Add low blocks for
+flower beds, barrels, crates, benches, lanterns and window boxes wherever the concept has them; a sparse blockout
+comes back as a sparse painting. Only truly flat detail (cobbles, rugs, grass) can stay paint-only.
+
+**Match the concept.** Read positions straight from the concept by inverting the orthographic camera
+(`tools/cam.py <height> <px,py> ...` does it). With the
+concept W x H pixels, `s` = pixels per metre (W / frame width), `elev` = 30 degrees and a pixel (sx, sy) on the
+ground (a wall's bottom corner):
+
+```
+u = (sx - W/2) / s                      # metres along the camera's right axis
+v = (H/2 - sy) / (s * sin(elev))        # metres along the ground, away from the camera
+height = dy / (s * cos(elev))           # a vertical edge dy pixels long (wall, ridge, chimney)
+world = target + right_ground * u + far_ground * v
+```
+
+Three wall-bottom corners give a footprint; the ridge gives the roof height. Draw the spec over the concept with
+`tools/preview.py` and move blocks until the red silhouettes line up, then build it in the engine.
+If the blockout does not match the concept, the painting will not match the blocks.
+
+### 3. Render the blockout from the paint camera
+
+- Play with the location's `paint` left empty: `painted_world.gd` then shows the blockout through that
+  `PaintCamera`, lit by a sun and ambient light so its faces read (an unlit blockout comes out near black).
+  `summer_screenshot` `target: "game"` captures it.
+- Exact PNG for the painter: copy `_building-blocks/capture_paint_view.gd`, make a scene with just that node
+  (`level` = the world scene, `camera_path` = the location's camera, `size` = 2048x1152), and play it in a run
+  that renders (the editor, or a windowed run; `--headless` renders nothing). It saves
+  `res://painted/blockout.png` and quits.
+- `summer_screenshot` `target: "scene"` renders the saved scene without running scripts: a blockout built by a
+  script or the spec builder shows nothing there.
+
+Then upload it: `summer_call` `assets.upload_begin`, post its form fields plus the file to `uploadUrl`, then
+`assets.upload_complete` with `publicId`, `version`, `uploadSignature` (the `signature` of the upload's answer)
+and `format`. Its answer carries the `fileUrl`.
+
+### 4. Paint-over (strict image to image)
+
+**Never pass the whole concept as a reference.** Even when the blockout rebuilds it one to one, frontier edit
+models copy the full concept and ignore the blocks. Pass a **material sheet** instead: a 2x2 grid of close-up
+crops from the concept (for a village: clay-tile roof with a timber-framed wall, thatch, market stall with
+cobbles, slate roof with flower beds). It carries the style and materials but no layout.
+
+With two images (image 1 = blockout render, image 2 = material sheet), the best frontier edit model you have, 16:9,
+the largest size (4K):
+
+```
+Image 1 is a flat-coloured 3D blockout render of <place> from a fixed game camera. Image 2 is a sheet of four
+close-up material samples from the finished concept art (<the four samples>). Image 2 is a style and
+material reference only: never copy its layout or composition.
+Repaint image 1 in exactly that style, materials, light and detail. This is a strict image-to-image
+paint-over: keep every shape, edge and position of image 1 identical, pixel-aligned. Same camera, same
+framing. Every <building, roof, chimney, dormer, door, steps, well, stall, crate, bench, barrel, fence, tree and
+bush> stays exactly where image 1 has it, with exactly the same silhouette and size. Do not add, remove or move
+anything. Do not add extra props, buildings or trees. Only paint surface detail inside the existing shapes.
+Colour key of image 1: red = clay-tile roof, yellow = golden thatch roof, dark blue = slate roof, cream =
+timber-framed plaster walls, grey = mossy stone (chimneys, well, low walls, steps), brown = worn wood (tall
+brown slabs on walls = wooden doors), light brown floor = cobblestone plaza, green ground = grass, green
+spheres = round leafy tree canopies, small green domes = flowering bushes, orange = lit lanterns and fruit
+crates, pink low blocks = dense flower beds and window boxes.
+<Light and finish: e.g. warm golden late-afternoon light, soft short contact shadows only (no long cast shadows
+on the ground), glowing windows, painterly near-realistic detail as in image 2: ivy on walls, moss on stones,
+rich textures>. No characters, no text, no border.
+```
+
+`summer_assets_generate_image` takes one `referenceImageUrl` (the blockout render): put the material and
+style description into the prompt in words and keep the colour key. Use `model: "seedream-5-pro"`, `width`
+2048, `height` 1152, `numImages: 1` and an `idempotencyKey`: it holds pixel alignment well and is the only
+Summer model that returns 2048 px.
+
+**Check alignment before you use it.** Overlay the blockout's edges (red) on the painting
+(`tools/overlay.py <blockout.png> <painting.png> <out.png>`) and look: roof lines,
+wall corners, the well and the stall must sit on the red lines. Reject any painting where objects moved, were
+added, or the framing zoomed; generate again rather than project a drifted painting.
+
+### 5. Resolution
+
+Painting pixels per metre must be at least the screen's pixels per metre. A 4K painting (about 5500 px) over a
+40 m frame gives 137 px/m; a 16 m view on a 1080p-class game view needs about 96-120 px/m, so it stays sharp. A
+2048 px painting over 32 m (64 px/m) is soft at that view. For bigger worlds use more frames, not a wider frame.
+
+**4K through Summer:** no Summer image model returns 4K. `tools/detail4k.py <painting_2k.png> <out_dir> "<style
+words>"` upscales the 2K paint-over 2x, cuts nine overlapping 2048x1152 tiles, runs a strict "redraw sharper,
+pixel-aligned" image-to-image pass on each with `seedream-5-pro` and blends them back. Nine generations; the
+alignment holds.
+
+### 6. Projection in the engine
+
+Copy `_building-blocks/paint_projection.gdshader`, `painted_location.gd`, `painted_world.gd`,
+`painted_door.gd` and `painted_player.gd` to `res://painted/`. Set each location's `paint`. On `_ready` a
+location puts one `ShaderMaterial` on every mesh under its `Painted`; the shader takes each surface point's
+position in that location's paint camera frame as its UV. No UV unwrapping, no baking.
+
+- Keep the scene's tonemap **Linear**, exposure 1, no glow, no fog: the painting already holds the light.
+- Import the painting lossless (Import dock: Compress Mode Lossless, mipmaps on); VRAM compression smears it.
+- Verify: `_building-blocks/paintcam_check.gd` renders the painted world through a `PaintCamera` to a PNG; it
+  must match the painting. Then play and look at the real window (hard rule 9).
+
+### 7. Camera rules
+
+- The game camera has the paint camera's direction and only **moves** (follows the player). With an orthographic
+  camera, moving never reveals a surface the painting did not see. Never orbit or tilt it: turned views show the
+  painting's mistakes (a painted chimney next to the real one, roof edges smeared on the ground).
+- Outdoors it shows about 16 m across; rooms are framed whole. `painted_world.gd` sizes and clamps it with the
+  real viewport aspect and sets the clear colour to the painting's edge colour.
+- More world = more frames. Every frame uses the same direction, its own paint camera position and painting.
+  Paint neighbouring frames with an overlap strip so the seams match.
+
+### 8. Interiors
+
+Every village gets at least one enterable building. Each interior is its own location far away (for example 100 m
+off to the side) with the **same** camera direction and a frame that holds the whole room with its back walls
+(14 m for a 9 x 7.5 m room; 12 m cut the walls off), `frame_whole = true`. Lower
+the two walls nearest the camera to knee height (a dollhouse cut-away) and leave a door gap of about 1.8 m.
+Blockout, render, paint over (its own 4K paint-over, the same rules and colour key: warm floorboards, plaster,
+beams, fireplace, bed, shelves, rug, "keep the area outside the room plain flat dark") and project exactly like
+the outside. `painted_door.gd` triggers go both ways; put each spawn marker clear of the other door's trigger.
+
+### 9. Characters
+
+1. **Ready-made:** use the painted plug-in characters first: a man, a woman, the man with a sword and an old man,
+   8 directions, idle, walk and run (`hero_m_sword`: idle and walk). They live in the public repo
+   `SummerEngine/painted-characters`, pinned at commit `c70dae1b4043656ad23d5ab6d76fe992f593b6ba`. For `<id>`, import
+   `https://raw.githubusercontent.com/SummerEngine/painted-characters/c70dae1b4043656ad23d5ab6d76fe992f593b6ba/characters/<id>/<file>`
+   for the three files `<id>_sheet.png`, `<id>_sheet.json` and `<id>_frames.tres` into `res://characters/<id>/`
+   (`summer_import_from_url`; the `.tres` expects that path), then set `sheet` = `<id>_sheet.png` and
+   `sheet_json` = `<id>_sheet.json` on `painted_player.gd`. With a shell, `git clone` the repo and copy
+   `characters/` to the project root. Need a different look: make one.
+2. **New character:** generate an 8-pose turnaround (or two 4-pose sheets) in the world's style on flat pure
+   green:
+   ```
+   Character turnaround sheet in the art style of <the world>: <character>. Draw the same character 8 times,
+   same size, feet on one baseline: facing down toward the viewer, down-left, left, up-left, up (back view),
+   up-right, right, down-right. Seen from a high three-quarter top-down camera. Plain flat pure green
+   background (#00FF00), no ground, no shadows, no text.
+   ```
+   Crop each pose, pad it to 9:16 with the same green, upload it, then `summer_call` `assets.generate_video`
+   (`model: "minimax-h3-max"`, `aspectRatio: "9:16"`, 5 s, an `idempotencyKey`): one clip per direction and
+   animation:
+   ```
+   The character, <facing>, walks in place on the spot with a brisk, purposeful walk cycle: long confident strides, heel to toe, the front leg reaching far forward and the back leg pushing far back, arms swinging strongly opposite the legs, upright posture. The character
+   stays exactly centred at the same size and never moves across the frame or turns. Static locked camera, no
+   zoom. The plain flat pure green background stays perfectly flat and unchanged. Seamless loop.
+   ```
+   That is the walk prompt for a default walk (a plain "steady, simple walk cycle" takes short steps and must be
+   over-sped). For a longer stride still: "walks in place on the spot with a long-legged power walk: very wide
+   steps, at each step the front heel lands far ahead and the back foot pushes off far behind, legs nearly fully
+   extended front to back, arms swinging wide, a quick purposeful pace."
+   Idle: "stands still in a relaxed idle: gentle breathing, one blink, feet planted". Run: "runs in place".
+3. **Clip to sheet** (host with a shell and ffmpeg): key out the green by colour, take one cycle (skip the
+   first second), sample 8 frames evenly, crop every frame of every clip with the **same** box so the feet stay
+   on one line, and tile them into one sheet: one row per animation and direction (`idle_down`,
+   `walk_up_left`, `run_right`, ...). Write the json beside it: `{"cell_w", "cell_h", "frames", "rows",
+   "fps": {"idle", "walk", "run"}, "height_m", "stride_m": {"walk", "run"}, "cycles_per_s": {"walk", "run"}}`.
+   Measure once per kind: `stride_m` = how far a planted foot slides back during one cycle at `height_m`,
+   `cycles_per_s` = cycles per second at the sheet's fps. Look at every frame; regenerate a clip with a broken
+   frame.
+   Without video: `summer_call` `assets.generate_sprite_sheet` (8-frame walk from one picture, per direction).
+4. **In the game:** `painted_player.gd` makes an `AnimatedSprite3D`: Y-billboard, unshaded, alpha cut (so painted
+   walls hide the character), height stretched by `1 / cos(camera pitch)`, 8 facings by 45 degree sectors (a
+   missing diagonal falls back to its side row), the game-type gait (hard rule 2), animation speed = speed /
+   natural speed.
+   Spawn points 0.5 m or more away from walls, or the flat card cuts into them.
+
+### 10. Weapons
+
+- **Variant sheet (best look):** edit the turnaround so the character holds the weapon, then animate the clips
+  again. One extra sheet per weapon. Never mirror a sheet with a held weapon.
+- **Held sprite layer (cheap):** a second `Sprite3D` child with the weapon, a per-direction offset and draw order
+  (behind the body when facing up). Good for many weapons; the hand will not wrap around the grip.
+
+## Common mistakes
+
+- **The whole concept as a reference:** the painting copies the concept and ignores the blocks, even when the
+  blockout matches it. Pass a 2x2 material sheet cropped from the concept.
+- **A sparse blockout:** the painting comes back sparse. Add low blocks for flower beds, crates, barrels, benches.
+- **35 degrees against a generated concept:** generated "isometric" art is 30 degrees down; the blocks will not fit.
+- **A tiny or giant hero:** check the hero against a door (door = hero x 1.15) in the first screenshot.
+- **Sliding feet or the wrong gait:** speed_scale = speed / natural; cozy games walk by default and run on Shift.
+- **4096 px asked from Summer's image models:** refused. 2048x1152 with seedream-5-pro, then the tiled 4K pass.
+- **A new idempotencyKey after a timeout:** pays twice. Retry with the same key; keep numImages 1.
+- **An unlit blockout capture, CSG blocks, a one-sided polygon ground, no water blockers:** see steps 2 and 3.
+- **Long baked shadows:** they lie on the ground while the hero walks through them. Contact shadows only.
+- **Floating dormers, blockout door slabs left visible:** dormers on the slope; hide door and step slabs.
+- **Rotating the game camera:** shows painted detail on the wrong surfaces. Translate only.
+- **Filmic/ACES tonemap or lights on painted meshes:** colours shift. Unshaded material, Linear tonemap.
+- **Perspective camera:** moving it reveals hidden faces. Use orthographic.
+- **Assuming a 16:9 window:** the clamp shows past the painting in the editor's game view. Use the real aspect.
+
+## Optional: Blender route
+
+If the host has Blender, `_building-blocks/blender-route.md` bakes the same projection into ordinary UVs and
+exports glTF; use it when the scene must ship as plain textured meshes.
+
+## See also
+
+- `make-game` (genre mechanics), `concept-art`, `sprite-sheet`, `scene-composition`
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `summer_assets_generate_image` | `summer assets generate-image` |
+| `assets.generate_video` | `summer assets generate-video` |
+| `assets.upload_begin` | `summer assets upload-begin` |
+| `assets.upload_complete` | `summer assets upload-complete` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_create_scene` | `summer engine create-scene` |
+| `summer_get_project_context` | `summer engine get-project-context` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_import_from_url` | `summer engine import-from-url` |
+| `summer_play` | `summer engine play` |
+| `summer_read_file` | `summer engine read-file` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_screenshot` | `summer engine screenshot` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_stop` | `summer engine stop` |
+| `summer_write_file` | `summer engine write-file` |
+| `summer_jobs_wait` | `summer jobs wait` |
+<!-- /shell-commands -->

package/library/skills/painted-25d-world/_building-blocks/blender-route.md

@@ -0,0 +1,33 @@
+# Blender route: bake the projection into UVs
+
+Use this only when the host has Blender and the level must ship as plain textured meshes (no projection shader).
+It gives the same picture as `paint_projection.gdshader`.
+
+1. Build the blockout in Blender with the same orthographic camera: rotation (60, 0, 45) degrees in Blender's
+   Z-up axes (90 - 30 down, 45 around), `ortho_scale` = frame width in metres. Render it (Workbench, studio light,
+   outlines on) at 2048x1152 or larger.
+2. Paint over the render (SKILL.md step 4) and resize the painting to the exact render size.
+3. Project: for every mesh, add one UV layer and set each loop's UV to the camera-view position of its vertex.
+
+```python
+import bpy
+from bpy_extras.object_utils import world_to_camera_view
+
+scene, cam = bpy.context.scene, bpy.data.objects["PaintCamera"]
+for ob in bpy.data.collections["blockout"].objects:
+    if ob.type != "MESH":
+        continue
+    me = ob.data
+    uv = me.uv_layers.new(name="proj")
+    uv.active = uv.active_render = True
+    for loop in me.loops:
+        p = world_to_camera_view(scene, cam, ob.matrix_world @ me.vertices[loop.vertex_index].co)
+        uv.data[loop.index].uv = (p.x, p.y)
+```
+
+   With an orthographic camera the UVs are exact per vertex, so no subdivision is needed.
+4. One material for all meshes: the painting as base colour (texture extension EXTEND). Export glTF with separate
+   textures. Name solid objects `<name>-col` so the engine adds collision on import.
+5. In the engine, override every imported mesh with an unshaded `StandardMaterial3D` that uses the painting, and
+   import the painting lossless. Blender (x, y, z) is engine (x, z, -y): rebuild the paint camera from the same
+   30 / 45 degree direction with `keep_aspect` KEEP_WIDTH and `size` = the ortho scale.