summer-engine 2.8.1 → 3.0.0

package/library/skills/godogen-visual-proof-game-generation/resource.yaml

@@ -0,0 +1,33 @@
+id: skill/godogen-visual-proof-game-generation
+kind: skill
+version: 0.1.1
+summary: "Godogen-style game generation with a visual QC loop — capture frames from the running game, self-verify against the brief, bounded fix rounds, proof clip."
+use_when:
+  - "generate a whole small game from a short brief and prove it actually runs"
+  - "the agent says the game works but never looked at it running — make it verify from captured frames"
+  - "add a visual QC loop with a capped number of fix rounds and a proof recording at the end"
+  - "set up headless capture so an unattended generation run ends with a 15-20 second proof clip"
+do_not_use_when:
+  - "large hand-authored production work, purely logical code fixes with no visual component, or hosts with no GPU or headless capture path"
+  - "intake from the gamedev-knowledge pipeline (source-cited, pipeline-validated, not yet exercised in-engine by the Summer team) — verify results in the engine as you would any technique"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - verification
+  modalities:
+    - project
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/verification-before-completion
+    - skill/playtesting-a-feature
+    - skill/verifying-scenes
+    - skill/make-game
+source: official
+license: MIT
+status: preview
+recommended: false

package/{skills/workflow → library/skills}/headless-scripting/SKILL.md

@@ -70,7 +70,7 @@ If neither is available (an older engine build that predates `engineBinaryPath`,
 |---|---|
 | macOS | `/Applications/Summer.app/Contents/MacOS/Summer` |
 | Windows | `%LOCALAPPDATA%\Summer\current\Summer.exe` |
-| Linux | wherever the AppImage/binary was installed |
+| Linux | `~/.summer/engine/summer-linux-x86_64`, or `$SUMMER_ENGINE_BINARY` (see `running-in-the-cloud`) |
 
 <EXTREMELY-IMPORTANT>
 There is no `godot` binary on a Summer user's machine. `godot --headless`, `godot4`, `/usr/local/bin/godot` — none of these exist. A command built on that name fails with "command not found" on every single user, and no amount of retrying changes it. This skill exists partly because that exact instruction shipped in our own docs for months.
@@ -342,14 +342,21 @@ frames saved        : 00_start.jpg  01_after_walk.jpg  02_after_jump.jpg
 
 So: **scripting and authoring go through `--headless`. Seeing and measuring go through the verify instance.** Choose on that axis and you will not get a null.
 
-For writing probes — the `SummerProbeBase` API, the coroutine rules, what is and is not reproducible — see `summer:playtesting-a-feature`.
+For writing probes — the `SummerProbeBase` API, the coroutine rules, what is and is not reproducible — see `playtesting-a-feature`.
 
 ## What a script genuinely cannot do
 
 Short list, and it is short on purpose. Everything not on it is worth attempting.
 
-- **Lightmap baking.** `LightmapGI::bake` is not runtime-callable. Editor process only.
-- **Occlusion culling bake.** `OccluderInstance3D.bake_single_node`, same.
+- **Lightmap baking — headless specifically.** The binding exists on this build
+  (Summer script-binds `LightmapGI.bake(from_node, image_data_path)`), but the GPU
+  lightmapper needs a RenderingDevice, which a `--headless` process never has: the
+  call returns `BAKE_ERROR_NO_LIGHTMAPPER`. Bake from `summer_run_script` in the
+  **live editor** instead — a normal desktop editor works as-is; a cloud container
+  needs the xvfb + GL renderer setup from `running-in-the-cloud`. Wrong
+  reason kills the right fix: it is "no renderer in this process", not "no binding".
+- **Occlusion culling bake.** `OccluderInstance3D.bake_single_node` is not
+  script-callable at all. Editor-button only.
 - **Anything needing `EditorInterface`.** Outside the editor, `ClassDB.can_instantiate("EditorScript")` is `false`.
   **Trap:** `Engine.has_singleton("EditorInterface")` returns **`true`** even in a plain headless script — it lies. Retrieving the singleton then fails with `Can't retrieve singleton 'EditorInterface' outside of editor`. Test with `ClassDB.can_instantiate("EditorScript")`, which tells the truth.
 
@@ -402,6 +409,6 @@ Keep scripts in the project (`res://` is required for `-s`), but name them so th
 | "There's no tool for that, so it can't be done" | There is a script for it. Write the script. |
 
 **Related skills:**
-- `summer:playtesting-a-feature` — the verify instance, probes, and proving gameplay behaviour.
-- `summer:export-and-ship` — the full release pipeline this skill's export example is one step of.
-- `summer:verification-before-completion` — checking the artifact before claiming done.
+- `playtesting-a-feature` — the verify instance, probes, and proving gameplay behaviour.
+- `export-and-ship` — the full release pipeline this skill's export example is one step of.
+- `verification-before-completion` — checking the artifact before claiming done.

package/library/skills/headless-scripting/resource.yaml

@@ -0,0 +1,26 @@
+id: skill/headless-scripting
+kind: skill
+version: 1.1.3
+summary: Run a GDScript file against Summer Engine from the shell for operations no MCP tool exposes — navmesh baking, collision shapes, TileSets, re-imports.
+use_when:
+  - a Summer project needs an operation no MCP tool exposes — baking a navmesh, generating collision shapes, authoring an Animation, building a TileSet, re-importing assets
+  - a plan involves 'run it headless and screenshot it' (which does not work — this skill explains why)
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - headless
+  modalities:
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/scene-scripting
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/workflow/headless-scripting

package/{skills/multiplayer-and-networking → library/skills}/host-authoritative-state/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: host-authoritative-state
-description: Use when designing the state layer of a multiplayer Summer game: deciding what the host owns, how clients request changes, and how the host validates and broadcasts. Pairs with `/peer-to-peer-multiplayer`. Trigger on "host authority", "authoritative state", "state ownership", "MP cheating", "client validation", "RPC patterns".
+description: "Use when designing the state layer of a multiplayer Summer game: deciding what the host owns, how clients request changes, and how the host validates and broadcasts. Pairs with `/peer-to-peer-multiplayer`. Trigger on \"host authority\", \"authoritative state\", \"state ownership\", \"MP cheating\", \"client validation\", \"RPC patterns\"."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: multiplayer-and-networking

package/library/skills/host-authoritative-state/resource.yaml

@@ -0,0 +1,28 @@
+id: skill/host-authoritative-state
+kind: skill
+version: 1.0.3
+summary: Design the state layer of a multiplayer game — what the host owns, how clients request changes, and how the host validates and broadcasts.
+use_when:
+  - "designing the state layer of a multiplayer Summer game: host ownership, client change requests, host validation and broadcast"
+  - clients desync, cheat, or fight over one object and the state ownership model is undefined
+facets:
+  lifecycle:
+    - build
+  domains:
+    - multiplayer
+    - game-design
+  modalities:
+    - scripts
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/peer-to-peer-multiplayer
+    - skill/setup-multiplayer
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/multiplayer-and-networking/host-authoritative-state

package/{skills/2d-assets → library/skills}/instantiate-asset-pack/SKILL.md

@@ -11,9 +11,9 @@ paths: ["assets/**", "art/**", "ui/**", "scenes/**"]
 
 # instantiate-asset-pack — Instantiate Asset Pack into Scene
 
-A pack ArtAsset (produced by `summer:2d-assets/create-asset-sheet`) is a bundle of cropped slice PNGs with per-slice metadata. This skill is the runtime side: given a pack, lay its slices into the current scene as a correctly-grouped, correctly-layered set of nodes.
+A pack ArtAsset (produced by `create-asset-sheet`) is a bundle of cropped slice PNGs with per-slice metadata. This skill is the runtime side: given a pack, lay its slices into the current scene as a correctly-grouped, correctly-layered set of nodes.
 
-For wiring individual widget slices (9-slice panels, progress bars, toggles), this skill delegates to `summer:2d-assets/use-widget-asset`. This skill handles the pack-level layout: grouping composites, paint order, spatial offset, naming.
+For wiring individual widget slices (9-slice panels, progress bars, toggles), this skill delegates to `use-widget-asset`. This skill handles the pack-level layout: grouping composites, paint order, spatial offset, naming.
 
 ## When to use
 
@@ -25,14 +25,12 @@ For wiring individual widget slices (9-slice panels, progress bars, toggles), th
 
 ## When NOT to use
 
-- User wants a single slice → import it directly as a `Sprite2D` (or `summer:2d-assets/use-widget-asset` if it's a UI widget).
-- User wants to **generate** a new pack → `summer:2d-assets/create-asset-sheet`.
+- User wants a single slice → import it directly as a `Sprite2D` (or `use-widget-asset` if it's a UI widget).
+- User wants to **generate** a new pack → `create-asset-sheet`.
 - User wants to apply a slice as a material/texture on a 3D mesh → not the pack flow; see `asset_pipeline.json`.
 
 ## Pack JSON shape
 
-Full schema: `publicsummerengine/public/knowledge/asset_pack_schema.json`.
-
 The per-slice fields this skill cares about:
 
 | Field | Used for |
@@ -58,7 +56,7 @@ A standalone slice has no `parentSliceIndex` and isn't a composite parent. Spawn
 3. `summer_set_prop` — `texture = res://...`.
 4. If `slice.zOrder` is set, `summer_set_prop` — `z_index = slice.zOrder`.
 
-If the slice has a `widget` field, hand off to `summer:2d-assets/use-widget-asset` after step 1.
+If the slice has a `widget` field, hand off to `use-widget-asset` after step 1.
 
 ## Composite parent + children
 
@@ -89,7 +87,7 @@ When a child slice has `widget.kind` set, the bare Sprite2D is not the right nod
 | `slider` | `HSlider`/`VSlider` + `NinePatchRect` track | track uses `frameMargins`; slider sits on top |
 | `toggle` | `TextureRect` | Swap `texture` between this slice and `packFiles[pairWith].url` |
 
-Delegate the actual wiring (percentage-to-pixel conversion, node-specific props) to `summer:2d-assets/use-widget-asset`. This skill places the node; that skill configures the geometry.
+Delegate the actual wiring (percentage-to-pixel conversion, node-specific props) to `use-widget-asset`. This skill places the node; that skill configures the geometry.
 
 ## Naming convention
 
@@ -224,9 +222,9 @@ Pack has a composite parent `settings_panel` (filtered out) plus three children:
 }
 ```
 
-After this, hand `panel_bg` and `apply_button` to `summer:2d-assets/use-widget-asset` to set `patch_margin_*` from their `widget.frameMargins`.
+After this, hand `panel_bg` and `apply_button` to `use-widget-asset` to set `patch_margin_*` from their `widget.frameMargins`.
 
-Note the ops format: `position` is the **Godot string** `"Vector2(0, 0)"`, not a JSON object. `z_index` is a bare integer. This is the format Summer Engine expects — see the publicsummerengine CLAUDE.md.
+Note the ops format: `position` is the **Godot string** `"Vector2(0, 0)"`, not a JSON object. `z_index` is a bare integer. This is the format Summer Engine expects — see `../../references/mcp-tools-reference/mcp-tools-reference.md`.
 
 ## Failure modes
 
@@ -240,6 +238,6 @@ Note the ops format: `position` is the **Godot string** `"Vector2(0, 0)"`, not a
 
 ## Related skills
 
-- `summer:2d-assets/create-asset-sheet` — production side; how the pack was made.
-- `summer:2d-assets/use-widget-asset` — wiring an individual widget slice (NinePatchRect, TextureProgressBar geometry).
+- `create-asset-sheet` — production side; how the pack was made.
+- `use-widget-asset` — wiring an individual widget slice (NinePatchRect, TextureProgressBar geometry).
 - `asset_pipeline.json` — broader find-or-generate -> import -> apply flow.

package/library/skills/instantiate-asset-pack/resource.yaml

@@ -0,0 +1,29 @@
+id: skill/instantiate-asset-pack
+kind: skill
+version: 1.0.3
+summary: "Import a whole create-asset-sheet pack into the scene: groups composites, sorts paint order, emits Sprite2D/Node2D/NinePatchRect ops to lay it out."
+use_when:
+  - importing or spawning an entire asset pack (multi-slice ArtAsset from create-asset-sheet) into the current scene
+  - laying out a generated tile sheet, UI kit, or biome pack as placed Sprite2D and NinePatchRect nodes in one pass
+do_not_use_when:
+  - importing a single slice rather than the whole pack
+facets:
+  lifecycle:
+    - build
+  domains:
+    - 2d
+    - assets
+  modalities:
+    - scenes
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/create-asset-sheet
+    - skill/use-widget-asset
+source: official
+license: MIT
+status: stable
+aliases:
+  - skills/2d-assets/instantiate-asset-pack

package/{skills/workflow → library/skills}/investigating-bugs/SKILL.md

@@ -105,7 +105,7 @@ You MUST complete each phase before proceeding to the next.
    codesign --sign "$IDENTITY" --verbose=4 "$APP"
    ```
 
-   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
+   **This reveals:** Which layer fails (secrets → workflow passes, workflow → build fails)
 
 5. **Trace Data Flow**
 
@@ -285,9 +285,9 @@ These techniques are part of systematic debugging and available in this director
 - **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
 
 **Related skills:**
-- **summer:verification-before-completion** - Verify fix worked before claiming success
-- **summer:debug** - The Summer-specific triage loop (script errors → console → debugger → probe)
-- **summer:playtesting-a-feature** - When the fix is a gameplay behaviour that has to be walked
+- **verification-before-completion** - Verify fix worked before claiming success
+- **debug** - The Summer-specific triage loop (script errors → console → debugger → probe)
+- **playtesting-a-feature** - When the fix is a gameplay behaviour that has to be walked
 
 ## Real-World Impact
 

package/{skills/workflow → library/skills}/investigating-bugs/condition-based-waiting.md

@@ -34,12 +34,12 @@ digraph when_to_use {
 ## Core Pattern
 
 ```typescript
-// ❌ BEFORE: Guessing at timing
+// BEFORE: Guessing at timing
 await new Promise(r => setTimeout(r, 50));
 const result = getResult();
 expect(result).toBeDefined();
 
-// ✅ AFTER: Waiting for condition
+// AFTER: Waiting for condition
 await waitFor(() => getResult() !== undefined);
 const result = getResult();
 expect(result).toBeDefined();
@@ -83,14 +83,14 @@ See `condition-based-waiting-example.ts` in this directory for complete implemen
 
 ## Common Mistakes
 
-**❌ Polling too fast:** `setTimeout(check, 1)` - wastes CPU
-**✅ Fix:** Poll every 10ms
+**Bad: Polling too fast:** `setTimeout(check, 1)` - wastes CPU
+**Fix:** Poll every 10ms
 
-**❌ No timeout:** Loop forever if condition never met
-**✅ Fix:** Always include timeout with clear error
+**No timeout:** Loop forever if condition never met
+**Fix:** Always include timeout with clear error
 
-**❌ Stale data:** Cache state before loop
-**✅ Fix:** Call getter inside loop for fresh data
+**Stale data:** Cache state before loop
+**Fix:** Call getter inside loop for fresh data
 
 ## When Arbitrary Timeout IS Correct
 

package/library/skills/investigating-bugs/resource.yaml

@@ -0,0 +1,24 @@
+id: skill/investigating-bugs
+kind: skill
+version: 1.0.3
+summary: Systematic investigation of any bug, test failure, or unexpected behavior before proposing fixes.
+use_when:
+  - encountering any bug, test failure, or unexpected behavior, before proposing fixes
+  - the character falls through the floor and nobody knows why — find the root cause before patching
+  - a test fails or the game misbehaves and the first guess at the cause is unproven
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - debug
+  modalities:
+    - project
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/workflow/investigating-bugs

package/{skills/workflow → library/skills}/investigating-bugs/root-cause-tracing.md

@@ -98,13 +98,7 @@ npm test 2>&1 | grep 'DEBUG git init'
 
 If something appears during tests but you don't know which test:
 
-Use the bisection script `find-polluter.sh` in this directory:
-
-```bash
-./find-polluter.sh '.git' 'src/**/*.test.ts'
-```
-
-Runs tests one-by-one, stops at first polluter. See script for usage.
+Bisect: run the test files one at a time (or in halves) and check for the artifact after each run. The first run that produces it is the polluter. A five-line shell loop over the test files is enough; stop at the first hit.
 
 ## Real Example: Empty projectDir
 

package/library/skills/lumera-single-image-scene-reconstruction/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: lumera-single-image-scene-reconstruction
+description: "Use when building a Lumera-style single-image → editable-engine-scene pipeline in SummerEngine: VLM-parsed object boxes and parametric lights, per-object meshes, HDR environment probe, engine-native assembly, and a bounded dual-agent refinement loop."
+license: MIT
+category: art-pipeline
+tags:
+  - image-to-3d
+  - scene-reconstruction
+  - lighting
+  - vlm
+  - procedural-content
+  - godot4
+confidence: extracted
+---
+
+# Single-Image → Editable Scene Reconstruction (Lumera-style) in SummerEngine
+
+## Outcome
+
+Turn one reference image into an **editable, engine-native scene** in SummerEngine: individual `MeshInstance3D` objects with transforms, countable parametric light nodes, and an HDR environment probe — not a fused point cloud, Gaussian splat, or baked texture. This is the adaptation of the Lumera pipeline (arXiv:2607.20889, Tsinghua AIRSUN lab) from UE5 to SummerEngine.
+
+**Honesty caveat:** Lumera itself is UE5-only with no public code as of retrieval (2026-08-30); the paper explicitly lists Godot/engine-portable extraction as future work. This skill documents the architecture and the parts an agent can build in SummerEngine today (assembly, scene representation, refinement loop, evaluation), and flags the parts that require external model components (VLM box/light parsers, per-object mesh generator, HDR estimator).
+
+## When to Use
+
+- Bootstrapping a level/blockout from concept art or a screenshot, where artists need movable objects and re-tunable lights afterward.
+- Producing 3D scene conditions for 3D-conditioned video generation (a use case the paper calls out).
+- You specifically need **editable entities** (instances, lights, probes) rather than a render-able blob.
+
+## When NOT to Use
+
+- You only need a visual backdrop: a Gaussian-splat or depth-mesh bake is cheaper and looks as good or better.
+- Large unbounded outdoor scenes: the paper reports ~17 m Chamfer-L2 drift outdoors — geometry is unreliable at that scale.
+- Exact light counts/positions are critical: individual-light localization F1 is 0.209 at 0.5 m; intensity error is ~2.7× (log-MAE 0.431). Expect hand-tuning.
+
+## Core Principle
+
+Treat image-to-3D as **game-engine structured parsing**: engines already store exactly the entities downstream tools need — object components, transforms, cameras, materials, environment probes, and countable parametric lights. The pipeline therefore parses those entities directly instead of reconstructing geometry first and deriving entities later.
+
+Lumera's stages (from paper abstract + appendices):
+
+1. **Lumera-Box** — VLM parses object-level 3D boxes (position, size, yaw) from the image.
+2. **Lumera-Light** — VLM parses parametric light tuples `(x, y, z, r, g, b, I)`.
+3. **Per-object mesh reconstruction** — a mesh per parsed box.
+4. **HDR environment estimation** — environment probe (IntrinsicHDR partially compensates for SkyLight/unseen near-camera lights).
+5. **Bounded agentic refinement loop** — dual-agent (geometry stage, then light stage) edits + verifies against the reference image.
+6. **Assembly** — emit engine-native scene (Blender/UE5 in the paper; `.tscn` in SummerEngine).
+
+Dataset backing it: Lumera-2K, 2,513 UE5 projects → 3.73M components, 63M object instances, 102.6K parametric lights, 95.1K camera views.
+
+## Scene / Node Shape (SummerEngine target)
+
+The assembly stage should emit this node tree so output stays inspectable/editable:
+
+```
+ReconstructedScene (Node3D)
+├── Camera3D                    # recovered viewpoint (intrinsics from parsing stage)
+├── WorldEnvironment
+│   └── Environment
+│       └── Sky (HDR panorama from stage 4) + ambient light settings
+├── Objects (Node3D)
+│   └── MeshInstance3D × N      # one per parsed box; transform = box center/yaw
+│       └── unique material per object (so meshes are replaceable/refinable)
+└── Lights (Node3D)
+    ├── OmniLight3D / SpotLight3D / DirectionalLight3D × M
+    │     # position/rotation from (x,y,z); color from (r,g,b);
+    │     # light_energy from I (mind log-scale calibration, see Tunables)
+    └── (SkyLight-equivalent is carried by WorldEnvironment in Godot)
+```
+
+Keep objects and lights as **separate siblings under named containers** — this mirrors UE5's component structure and is what makes the scene "editable" rather than "looks 3D".
+
+## Implementation Steps
+
+### 1. Define the intermediate scene schema
+
+Before touching models, define the serializable tuple set the pipeline passes between stages (this is the engine-native contract):
+
+```gdscript
+# object record parsed by the box stage
+class_name ParsedObject
+var box_center: Vector3
+var box_size: Vector3      # must be > 0; validate (paper strips non-positive sizes)
+var yaw: float             # watch 0 vs ±π/2 symmetry for near-square objects
+var label: String
+var id: int                # unique; duplicates are a known model failure mode
+
+# light record parsed by the light stage
+class_name ParsedLight
+var position: Vector3
+var color: Color           # r,g,b
+var intensity: float       # I, log-scale calibration needed (~2.7x error typical)
+var kind: String           # point / spot / directional mapping
+```
+
+Add a **repair layer** on ingest: drop/fix invalid labels, non-positive sizes, duplicate IDs. The paper notes sanitized evaluation silently removed these, and recommends constrained decoding or a repair layer in the inference path.
+
+### 2. Box + light parsing (external VLM components)
+
+Lumera-Box/Lumera-Light are VLMs SFT'd on Lumera-2K; there is no public checkpoint. Options: use a hosted VLM prompted to emit the JSON tuples above, or fine-tune an open VLM on your own engine-exported scenes (Godot scenes are text `.tscn` and trivially exportable — this is the "build Lumera-2K for your engine" step the paper identifies as missing for non-UE5 engines).
+
+### 3. Per-object mesh generation + HDR environment estimation
+
+Also external model components in Lumera (per-object mesh reconstruction; IntrinsicHDR-style environment estimation). For a SummerEngine blockout you can substitute: box mesh (`BoxMesh` sized to the parsed box) per object and a generated/estimated panorama `Sky`. Swap in real reconstructed meshes later without changing the schema.
+
+### 4. Assembly: write a `.tscn`
+
+Deterministic GDScript/tool script: instantiate the node shape above from the repaired records. Godot's `.tscn` is text — generating it directly keeps the output diffable and versionable. Save with `PackedScene.pack()` / `ResourceSaver.save()` from an editor tool.
+
+### 5. Bounded dual-agent refinement loop
+
+The paper's Algorithm 1 (Appendix H.7), adapted:
+
+- **Two stages in order:** geometry (objects/boxes), then lights. Switch the agent scope and prompt head per stage, but **inherit scene state `s` and conversation history `M`** across the switch — this avoids a cold start and lets the light-stage verifier refer to object identities already confirmed in the geometry stage.
+- **Each round:** agent proposes an action `a_t` (move/resize/add/remove an entity) given the history, reference image, and current scene state; the executor applies it to the scene; a verifier renders the result and reports `r_t` against the reference image.
+- **Sliding-window history:** keep only the system prompt + most recent `L` action/report pairs (`M_{t+1} = Tail_L(M_t ∪ {a_t, r_t})`, per VIGA). Skip records adjacent to rolled-back steps. This keeps 30+ rounds inside the VLM context window.
+- **Bounded:** hard round limits `T_g` (geometry) and `T_l` (light), plus early termination when the verifier report triggers it. Never run unbounded — that is what keeps this agentic loop "bounded" and cheap.
+
+### 6. Evaluation harness
+
+Reproduce the paper's metrics on held-out scenes so improvements are measurable:
+
+| Target | Metric |
+|---|---|
+| Boxes | 3D mAP, IoU-B, F-score (Lumera-Box reference: mAP 0.1141, IoU-B 0.2472, F 0.2762) |
+| Lights (scene-level) | non-empty-scene recall (reference: 0.998) |
+| Lights (per-light) | F1 @ 0.5 m (reference: 0.209 — weak; expect hand-tuning) |
+| Matched lights | median position error (0.261 m), median ΔE2000 color error (4.59), intensity Pearson r (0.628), log-intensity MAE (0.431) |
+| Geometry (scene) | Chamfer-L2 (outdoor reference ≈ 17 m — large unbounded scenes drift) |
+| Relations | SRF / anchor recall (known weak point; WildDet3D beats Lumera-Box here) |
+
+## Tunables
+
+| Parameter | Meaning | Notes |
+|---|---|---|
+| `T_g`, `T_l` | max refinement rounds per stage | paper keeps 30+ rounds total inside context; bound them |
+| `L` | history window size (action/report pairs) | trade context use vs. verifier memory of confirmed objects |
+| Light intensity calibration | map predicted `I` to `light_energy` | ~2.7× brightness error typical; log-scale loss recommended by authors |
+| Yaw symmetry handling | treat 0 and ±π/2 as equivalent for near-square footprints | explicit paper limitation; add symmetry classes or snap checks |
+| Supervision scope (if fine-tuning) | lights whose influence intersects the view frustum, not just visible sources | authors' recommended fix for missing SkyLight/carriers |
+
+## Failure Modes & Gotchas
+
+- **Merged/baked outputs defeat the point.** If assembly emits one combined mesh or a splat, you've built an image-to-3D renderer, not Lumera. Keep per-object nodes + parametric lights.
+- **Invalid model outputs are common:** non-positive box sizes, duplicate IDs, ID fallbacks. Validate and repair before assembly; the paper's benchmark silently sanitized these.
+- **Yaw ambiguity** on near-square objects (0 vs ±π/2 look identical) — single-token yaw serialization in prior work does not handle symmetry.
+- **Relation structure is unsolved** (object-to-object spatial relations): anchor recall/SRF are Lumera's weakest scores. Don't promise correct relative layouts.
+- **Per-light localization is weak** (F1 0.209 @ 0.5 m) while scene-level light *count* recall is strong (0.998). Frame the output as "right number of lights, roughly right places."
+- **SkyLight / near-camera lights whose source is off-screen** are not supervised; the environment probe (IntrinsicHDR) only partially compensates.
+- **Large outdoor scenes drift geometrically** (~17 m Chamfer-L2); consider joint camera+geometry calibration if you need metric outdoor consistency.
+- **Engine conventions don't transfer for free** — the dataset and light conventions are UE5's; Godot's light units/probes differ, so recalibrate intensity and validate the representation on Godot-native scenes.
+
+## Verification
+
+Not summerengine-verified. To validate an implementation in SummerEngine:
+
+1. Assemble a scene from a test image; confirm the `.tscn` contains separate, selectable `MeshInstance3D`s and light nodes (editability check).
+2. Move/replace one mesh and re-tune one light in the editor without breaking the scene.
+3. Run the evaluation harness (§6) against a held-out set of known Godot scenes and compare to the reference numbers above.
+4. Confirm the refinement loop terminates within `T_g`/`T_l` and the history window never exceeds the VLM context budget.
+
+## Confidence
+
+`extracted` — Architecture, metrics, refinement-loop design, and limitations are drawn directly from the arXiv paper (abstract, intro, appendices H.7–I as retrieved; middle method sections were truncated and are not documented here) and the author's announcement post. The SummerEngine node mapping and GDScript schema are adaptations, not from the sources; no public Lumera code exists to reference.

package/library/skills/lumera-single-image-scene-reconstruction/resource.yaml

@@ -0,0 +1,35 @@
+id: skill/lumera-single-image-scene-reconstruction
+kind: skill
+version: 0.1.1
+summary: "Lumera-style single image to editable 3D scene — VLM-parsed object boxes and parametric lights, per-object meshes, HDR probe, .tscn assembly, refinement loop."
+use_when:
+  - "turn this concept art or screenshot into an editable 3D scene with separate objects and lights"
+  - "block out a level from a single reference image"
+  - "reconstruct a room from one photo as movable meshes and tunable lights, not a point cloud or splat"
+  - "build a bounded agent loop that refines a generated scene against a reference image"
+do_not_use_when:
+  - "you only need a visual backdrop (a splat or depth-mesh bake is cheaper), large unbounded outdoor scenes, or exact light positions and intensities"
+  - "Lumera itself has no public code; the VLM box/light parsers, per-object mesh generator, and HDR estimator are external components you must supply"
+  - "intake from the gamedev-knowledge pipeline (source-cited, pipeline-validated, not yet exercised in-engine by the Summer team) — verify results in the engine as you would any technique"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - assets
+    - pipeline
+    - 3d
+    - scenes
+  modalities:
+    - scenes
+    - 3d-models
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/environment-kit
+    - skill/3d-lighting
+    - skill/scene-composition
+source: official
+license: MIT
+status: preview
+recommended: false