oda-engine 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +151 -2
- package/bin/nowhere.mjs +352 -0
- package/lib/account.mjs +57 -0
- package/lib/agentModules.mjs +57 -0
- package/lib/devServer.mjs +351 -0
- package/lib/headless.mjs +231 -0
- package/lib/headlessPreview.mjs +212 -0
- package/lib/keys.mjs +517 -0
- package/lib/make.mjs +855 -0
- package/lib/mcp.mjs +537 -0
- package/lib/open.mjs +22 -0
- package/lib/preview.mjs +87 -0
- package/lib/previewRpc.mjs +134 -0
- package/lib/project.mjs +359 -0
- package/lib/publishFlow.mjs +90 -0
- package/lib/resources.mjs +50 -0
- package/lib/rules.mjs +60 -0
- package/lib/scaffold.mjs +42 -0
- package/lib/setup.mjs +59 -0
- package/lib/tools.mjs +668 -0
- package/package.json +51 -4
- package/template/game.config.json +9 -0
- package/template/scene.json +4 -0
- package/template/src/main.ts +11 -0
- package/vendor/DOCS.md +447 -0
- package/vendor/agent/appRun.mjs +520 -0
- package/vendor/agent/assets/brief.mjs +242 -0
- package/vendor/agent/assets/collider.mjs +531 -0
- package/vendor/agent/assets/environments/index.mjs +12 -0
- package/vendor/agent/assets/environments/worldlabs.mjs +161 -0
- package/vendor/agent/assets/fetch.mjs +168 -0
- package/vendor/agent/assets/footprint.mjs +13 -0
- package/vendor/agent/assets/gltf.mjs +547 -0
- package/vendor/agent/assets/hdr.mjs +269 -0
- package/vendor/agent/assets/imageOps.mjs +171 -0
- package/vendor/agent/assets/images/codex.mjs +307 -0
- package/vendor/agent/assets/images/fal.mjs +75 -0
- package/vendor/agent/assets/images/gemini.mjs +84 -0
- package/vendor/agent/assets/images/index.mjs +25 -0
- package/vendor/agent/assets/images/openai.mjs +75 -0
- package/vendor/agent/assets/images/stability.mjs +71 -0
- package/vendor/agent/assets/images/views.mjs +31 -0
- package/vendor/agent/assets/import.mjs +1352 -0
- package/vendor/agent/assets/inspect.mjs +465 -0
- package/vendor/agent/assets/jobs.mjs +196 -0
- package/vendor/agent/assets/ktx2.mjs +290 -0
- package/vendor/agent/assets/ledger.mjs +466 -0
- package/vendor/agent/assets/net.mjs +254 -0
- package/vendor/agent/assets/prices.json +39 -0
- package/vendor/agent/assets/providers/fal.mjs +115 -0
- package/vendor/agent/assets/providers/index.mjs +22 -0
- package/vendor/agent/assets/providers/meshy.mjs +119 -0
- package/vendor/agent/assets/providers/tripo.mjs +188 -0
- package/vendor/agent/assets/sources/ambientcg.mjs +129 -0
- package/vendor/agent/assets/sources/index.mjs +23 -0
- package/vendor/agent/assets/sources/polyhaven.mjs +237 -0
- package/vendor/agent/assets/sources/polypizza.mjs +121 -0
- package/vendor/agent/assets/splat.mjs +631 -0
- package/vendor/agent/assets/targets.mjs +122 -0
- package/vendor/agent/assets/tile.mjs +261 -0
- package/vendor/agent/assets/unzip.mjs +180 -0
- package/vendor/agent/blender/cleanup.py +360 -0
- package/vendor/agent/blender/convert.py +167 -0
- package/vendor/agent/blender/find.mjs +192 -0
- package/vendor/agent/blender/nw_export.py +104 -0
- package/vendor/agent/blender/nw_rubric.py +426 -0
- package/vendor/agent/blender/run.mjs +193 -0
- package/vendor/agent/blender/runner.py +252 -0
- package/vendor/agent/blender/sheet.py +743 -0
- package/vendor/agent/depth.mjs +134 -0
- package/vendor/agent/director/board.mjs +451 -0
- package/vendor/agent/director/contracts.mjs +663 -0
- package/vendor/agent/director/director.mjs +2365 -0
- package/vendor/agent/director/estimate.mjs +200 -0
- package/vendor/agent/director/gate.mjs +802 -0
- package/vendor/agent/director/limits.json +16 -0
- package/vendor/agent/director/methods.mjs +457 -0
- package/vendor/agent/director/policy.json +33 -0
- package/vendor/agent/director/prompts.mjs +244 -0
- package/vendor/agent/director/reading.mjs +341 -0
- package/vendor/agent/director/router.mjs +184 -0
- package/vendor/agent/director/seams.mjs +243 -0
- package/vendor/agent/director/session.mjs +643 -0
- package/vendor/agent/director/store.mjs +119 -0
- package/vendor/agent/director/taskGate.mjs +110 -0
- package/vendor/agent/director/teamLedger.mjs +118 -0
- package/vendor/agent/director/triage.mjs +63 -0
- package/vendor/agent/downloads.cjs +363 -0
- package/vendor/agent/flow.mjs +78 -0
- package/vendor/agent/guard.mjs +613 -0
- package/vendor/agent/host.mjs +1736 -0
- package/vendor/agent/language.mjs +58 -0
- package/vendor/agent/ledger.mjs +360 -0
- package/vendor/agent/locale.cjs +186 -0
- package/vendor/agent/loop/capacity.mjs +74 -0
- package/vendor/agent/loop/compose.mjs +127 -0
- package/vendor/agent/loop/gate.mjs +205 -0
- package/vendor/agent/loop/judge.mjs +189 -0
- package/vendor/agent/loop/levels.mjs +273 -0
- package/vendor/agent/loop/state.mjs +358 -0
- package/vendor/agent/notes.cjs +278 -0
- package/vendor/agent/pace.mjs +258 -0
- package/vendor/agent/panels.mjs +431 -0
- package/vendor/agent/prompt.mjs +342 -0
- package/vendor/agent/reference/board.mjs +410 -0
- package/vendor/agent/reference/compose.mjs +364 -0
- package/vendor/agent/reference/decode.mjs +56 -0
- package/vendor/agent/reference/facts.mjs +1874 -0
- package/vendor/agent/reference/png.mjs +107 -0
- package/vendor/agent/reference/records.mjs +63 -0
- package/vendor/agent/reference/web.mjs +252 -0
- package/vendor/agent/roles/artist.mjs +69 -0
- package/vendor/agent/roles/builder.mjs +79 -0
- package/vendor/agent/roles/checks.mjs +223 -0
- package/vendor/agent/roles/common.mjs +188 -0
- package/vendor/agent/roles/critic.mjs +171 -0
- package/vendor/agent/roles/index.mjs +39 -0
- package/vendor/agent/roles/modeller.mjs +142 -0
- package/vendor/agent/roles/qa.mjs +58 -0
- package/vendor/agent/roles/rubrics.mjs +79 -0
- package/vendor/agent/roles/sound.mjs +69 -0
- package/vendor/agent/rounds.cjs +333 -0
- package/vendor/agent/shared.mjs +284 -0
- package/vendor/agent/stopGate.mjs +574 -0
- package/vendor/agent/subagents.mjs +129 -0
- package/vendor/agent/tools/assets.mjs +499 -0
- package/vendor/agent/tools/blender.mjs +754 -0
- package/vendor/agent/tools/cards.mjs +479 -0
- package/vendor/agent/tools/choices.mjs +479 -0
- package/vendor/agent/tools/compose.mjs +74 -0
- package/vendor/agent/tools/environment.mjs +488 -0
- package/vendor/agent/tools/eyes.mjs +733 -0
- package/vendor/agent/tools/generate.mjs +338 -0
- package/vendor/agent/tools/guide.mjs +46 -0
- package/vendor/agent/tools/harness.mjs +193 -0
- package/vendor/agent/tools/image.mjs +643 -0
- package/vendor/agent/tools/index.mjs +162 -0
- package/vendor/agent/tools/look.mjs +578 -0
- package/vendor/agent/tools/loop.mjs +858 -0
- package/vendor/agent/tools/others.mjs +123 -0
- package/vendor/agent/tools/pictures.mjs +535 -0
- package/vendor/agent/tools/reference.mjs +366 -0
- package/vendor/agent/transcripts.mjs +118 -0
- package/vendor/agent-loop.mjs +602 -0
- package/vendor/agent-plugin/.claude-plugin/plugin.json +5 -0
- package/vendor/agent-plugin/skills/art-direction/SKILL.md +82 -0
- package/vendor/agent-plugin/skills/asset-legality/SKILL.md +101 -0
- package/vendor/agent-plugin/skills/asset-sources/SKILL.md +111 -0
- package/vendor/agent-plugin/skills/blender-modeling/SKILL.md +97 -0
- package/vendor/agent-plugin/skills/look-dev/SKILL.md +104 -0
- package/vendor/agent-plugin/skills/playtesting/SKILL.md +74 -0
- package/vendor/agent-plugin/skills/reference-loop/SKILL.md +102 -0
- package/vendor/agent-plugin/skills/sound-design/SKILL.md +60 -0
- package/vendor/agent-plugin/skills/style/SKILL.md +35 -0
- package/vendor/agent-plugin/skills/tsl-r185/SKILL.md +107 -0
- package/vendor/auth.cjs +570 -0
- package/vendor/build.cjs +953 -0
- package/vendor/catalog.json +455 -0
- package/vendor/connectors.cjs +688 -0
- package/vendor/eyes.mjs +733 -0
- package/vendor/gameExports.json +1390 -0
- package/vendor/git.cjs +222 -0
- package/vendor/models.json +57 -0
- package/vendor/publish.cjs +1018 -0
- package/vendor/refBoard.cjs +301 -0
- package/vendor/schema/dist/assets.d.ts +335 -0
- package/vendor/schema/dist/assets.js +439 -0
- package/vendor/schema/dist/brief.d.ts +357 -0
- package/vendor/schema/dist/brief.js +302 -0
- package/vendor/schema/dist/common.d.ts +9 -0
- package/vendor/schema/dist/common.js +13 -0
- package/vendor/schema/dist/config.d.ts +406 -0
- package/vendor/schema/dist/config.js +355 -0
- package/vendor/schema/dist/contract.d.ts +599 -0
- package/vendor/schema/dist/contract.js +1146 -0
- package/vendor/schema/dist/index.d.ts +14 -0
- package/vendor/schema/dist/index.js +21 -0
- package/vendor/schema/dist/look.d.ts +463 -0
- package/vendor/schema/dist/look.js +681 -0
- package/vendor/schema/dist/lookStats.d.ts +230 -0
- package/vendor/schema/dist/lookStats.js +768 -0
- package/vendor/schema/dist/pilot.d.ts +32 -0
- package/vendor/schema/dist/pilot.js +44 -0
- package/vendor/schema/dist/publish.d.ts +214 -0
- package/vendor/schema/dist/publish.js +291 -0
- package/vendor/schema/dist/scene.d.ts +75 -0
- package/vendor/schema/dist/scene.js +120 -0
- package/vendor/schema/dist/skyLight.d.ts +141 -0
- package/vendor/schema/dist/skyLight.js +436 -0
- package/vendor/schema/dist/style.d.ts +131 -0
- package/vendor/schema/dist/style.js +155 -0
- package/vendor/schema/package.json +1 -0
- package/vendor/selectionPrompt.mjs +51 -0
- package/vendor/useTools.mjs +195 -0
- package/vendor/userMessage.mjs +26 -0
- package/web-dist/assets/GaussianSplatUtils-CB77cP9U.js +1 -0
- package/web-dist/assets/KTX2Loader-6OIWUF7s.js +2 -0
- package/web-dist/assets/SPZLoader-zYj0Alfv.js +1 -0
- package/web-dist/assets/gaussianSplat-CJTI1sEh.js +1 -0
- package/web-dist/assets/index-CcjyyQco.css +1 -0
- package/web-dist/assets/index-DMyJcoZJ.js +693 -0
- package/web-dist/assets/meshopt_decoder.module-BvwdjiD3.js +1 -0
- package/web-dist/assets/zstddec.module-CfFeQW7d.js +1 -0
- package/web-dist/index.html +34 -0
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: art-direction
|
|
3
|
+
description: Turning the reference board or a description into a space brief (brief.json and brief.md) and judging the space against it at its hero views. Load at the start of any visual request.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Art direction from the references
|
|
7
|
+
|
|
8
|
+
A space looks right when it matches a clear picture of what it should be. Write that picture down first, as numbers (brief.json) and in words (brief.md), build towards it, and judge every view against it in words and numbers. "Looks good" is not a judgement; "the arch is 1.2 visitor heights, the reference reads about 3" is.
|
|
9
|
+
|
|
10
|
+
Everything in the brief comes from this request: the creator's words and the references' measured facts (nw_reference). There is no house style, no stock palette and no stock mood; two requests that differ get briefs that differ. A value neither the request nor the references give is an assumption: write it down with why.
|
|
11
|
+
|
|
12
|
+
## The order
|
|
13
|
+
|
|
14
|
+
This skill covers the second and third steps and the eighth of the order for a space (the system prompt has all nine; nowhere:reference-loop has the loop around them):
|
|
15
|
+
1. **The kickoff** (nowhere:reference-loop) comes first.
|
|
16
|
+
2. **The targets on the reference board.** The target pictures (made for the hero views, or the creator's own photos) join the reference board, which the studio context lists with what each measured, beside anything the creator attached (.nowhere/refs/) or you gathered (refs/). `nw_reference { board: true }` measures the whole board in one answer: each picture's palette, values, warmth, haze, horizon and camera by its R id (one brief.json already lists keeps its id; a new one takes the next free number), the palette pooled over the board, and each picture's `measured` block in brief.json's units, with its project path. Then `nw_reference { image }` on each picture a hero view is judged against, for its masses, composition and camera guess.
|
|
17
|
+
3. **The brief**, before anything visual (below).
|
|
18
|
+
8. **The rounds** at the hero views, judged against their targets (Judging, below).
|
|
19
|
+
|
|
20
|
+
## Reading a reference
|
|
21
|
+
|
|
22
|
+
When the creator attached several pictures, let the creator pick the reference set with **nw_ask_pictures** before you write the brief: each candidate with what it shows and what the space would take from it, and a few words under it, all in the screen language (brief.json cites the picks with those words). The picks stay with you and brief.json cites them (R1, R2...); the rest are no longer handed to you. Once per space, or when the creator asks to change it. On "you choose" or no answer, pick yourself, record it by calling nw_ask_pictures again with the same pictures and `decide` (the paths you take; no card shows), and say which. Pictures you find on the web you choose yourself: nw_find_pictures, then nw_keep_pictures for the ones you build from (references to look at, cited in brief.json by path like any other). A web find nobody took stays set aside on the board until you take it.
|
|
23
|
+
|
|
24
|
+
Open each reference (its path is in the studio context) and look at it for each of these in turn, with its measured facts beside it. Write what you see in this picture, not what the subject usually looks like. Where pictures of one place disagree, say which one rules which part (the courtyard's walls from R2, its light from R4).
|
|
25
|
+
|
|
26
|
+
1. **Palette.** Its colours as hex with their share of the frame, each with what it is in the picture; the accents that carry the eye.
|
|
27
|
+
2. **Values.** Where the darkest darks and the brightest lights are, and how much of the frame is dark, middle and light (the value key and percentiles). The contrast between the subject and what is behind it.
|
|
28
|
+
3. **Silhouettes and proportions.** The shapes that make the subject recognisable, measured in visitor heights (1.75 m): "<the thing> is about <n> visitors tall and <m> wide".
|
|
29
|
+
4. **Camera.** Eye height (the visitor's eye is at the brief's eyeHeight; the reference's may be anywhere), lens, what is in the foreground, middle and back, and where the horizon sits (the horizon and camera guess).
|
|
30
|
+
5. **Light.** Where the key light comes from (the sun's azimuth and elevation, from the shadows), its colour, how hard the shadows are and what colour they take, what glows.
|
|
31
|
+
6. **Atmosphere and depth.** How fast things fade with distance (the haze bands), the fog colour, whether the horizon is visible.
|
|
32
|
+
7. **Materials.** Each surface: what it is, rough or polished, worn or new, and how close the visitor comes to it, which sets its texel density.
|
|
33
|
+
8. **What to leave out.** Clutter, text, people, effects that are not the point.
|
|
34
|
+
|
|
35
|
+
## brief.json
|
|
36
|
+
|
|
37
|
+
`nw_schema { kind: "brief" }` gives the exact shape; nw_check fails while it does not pass. No field has a default: a value the brief does not give stays missing, and the tools say so.
|
|
38
|
+
|
|
39
|
+
- **references**: R1, R2, ... with the path, what it shows and what the space takes from it, and its numbers as nw_reference measured them (`measured`, copied from the board's answer: palette, valueKey, contrast, saturation, warmth, haze, horizonY; add the lit, shadow and sky colours where the picture shows them).
|
|
40
|
+
- **palette**: each hex, where it goes in the space, and the reference it came from (`from`).
|
|
41
|
+
- **light**: the sun's azimuth (degrees clockwise from north, -z), elevation and colour; the sky's kind (`hdri` or `panorama` with its asset, `physical`, `gradient`, `color`) as the references show it; the shadow colour; fog with its colour and distances when the references have it; the references these came from.
|
|
42
|
+
- **scale**: the visitor's walking speed, run, eye height and field of view, which config.player copies.
|
|
43
|
+
- **materials**: every surface the visitor comes close to, with the name it is imported as, what it is, its texel density in px/m, worked out from the closest the visitor comes to it (the screen's width in pixels over the metres of that surface it then shows), and the metres one tile covers.
|
|
44
|
+
- **heroViews**: H1 to H6, one per target, the views the space is judged from: where the camera stands, the point it looks at and its fov (the camera the target was drawn from), what it shows and the target it cites. H1 is where the visitor arrives; the others are the places the creator named.
|
|
45
|
+
- **budget**: what the space's files may weigh (at most the planet's 100 MB), and a texel density for every other texture.
|
|
46
|
+
- **sources**: the libraries this space draws from (one family of scans matches itself); asset_import records each pick.
|
|
47
|
+
|
|
48
|
+
## brief.md
|
|
49
|
+
|
|
50
|
+
The same brief in words, short and concrete; a checklist, not prose. Sections, in this order:
|
|
51
|
+
|
|
52
|
+
- **Palette**: each hex, what it is, its share of the frame and the fact it came from.
|
|
53
|
+
- **Shapes and proportions**: every element the request names and every form the references show, each with its size in metres against the visitor and its silhouette.
|
|
54
|
+
- **Camera**: where the visitor arrives and what they see first; each hero view as the reference's framing.
|
|
55
|
+
- **Light and mood**: the sun, the sky, the shadows, what glows, the fog, each from the fact that gave it.
|
|
56
|
+
- **Materials**: each surface's colours, roughness, metal or not, its detail and its texel density.
|
|
57
|
+
- **Hero assets**: the few things the eye goes to, with their sizes.
|
|
58
|
+
- **Leave out**: what the request or the references have that the space will not.
|
|
59
|
+
- **Differences**: kept current while you build, biggest first, with numbers.
|
|
60
|
+
|
|
61
|
+
## Translating to Oda
|
|
62
|
+
|
|
63
|
+
- **The look comes from the brief** (the nowhere:look-dev skill has the knobs): `look_apply { set }` with the sun from the brief's light, the sky from its kind, the fog from its atmosphere (fog null when it has none), the exposure and contrast from its values, the grade from its palette. Until nw_status's lookWarnings is empty, the look still leaves something to the engine's defaults. The studio and the published planet draw the same pipeline, so what you see is what is published.
|
|
64
|
+
- **Scale** against the 1.75 m visitor, in the brief's metres. Build to them and keep models at their real size (`"normalize": false` on their placements).
|
|
65
|
+
- **Emissive and bloom:** emissive intensity above 1 glows; bloom's threshold keeps dim emissive from glowing.
|
|
66
|
+
- **Fog** decides depth: the far value is where things vanish completely; put it a little past the farthest thing that should still read. Ground fog is fog mode "height".
|
|
67
|
+
|
|
68
|
+
## Judging
|
|
69
|
+
|
|
70
|
+
Numbers first, then words. At each hero view: `nw_view { view: "free", position, lookAt, fov }` with the brief's numbers, then `look_compare { reference, views, palette }` against that view's reference. It waits for the space's files and judges no picture drawn before them, and it holds only at the reference's framing. It gives the palette distance (deltaE2000), mean brightness (L*), contrast and chroma ratios, warmth and tint, the shade and the lit against the reference's, clipping, a verdict (matches, close, far) and the look_apply values that would move it closer. Then judge what numbers cannot, in this order, because each one hides the next:
|
|
71
|
+
|
|
72
|
+
1. **Silhouette:** do the main shapes read against the background? Squint at the picture.
|
|
73
|
+
2. **Proportion:** measure against the visitor or a known object. Give the numbers.
|
|
74
|
+
3. **Value:** mean L*, contrast and thirds: are the darkest and lightest areas where the reference has them?
|
|
75
|
+
4. **Colour:** palette deltaE and each of the brief's colours (its nearest deltaE); the chroma ratio; the accents.
|
|
76
|
+
5. **Material:** roughness and detail at the visitor's distance, against the brief's materials (asset_inspect has their texel density).
|
|
77
|
+
6. **Light:** direction, warmth, shadow colour, glow, against the brief's light.
|
|
78
|
+
7. **Composition:** what the visitor sees first on arrival; foreground, middle, back.
|
|
79
|
+
|
|
80
|
+
Write the differences as a numbered list, biggest first, each with the hero view it shows in, its numbers against the reference or the brief, and the fix ("2. H1: mean L* <view> against <reference> (far); look.exposure <from> -> <to>"). Fix the first one, look again, compare again, and update the Differences section of brief.md. A round changes the space in answer to what you saw.
|
|
81
|
+
|
|
82
|
+
**Done** when look_compare says close or matches at every hero view with a reference (palette deltaE at most 10, clipping at most 2% unless the brief wants it), lookWarnings is empty, every hero asset matches in silhouette, proportion and palette in its close-up and at the hero views, the remaining differences are small and written down with their numbers, and the art-critic helper (when there is a reference) answers CLOSE or MATCHES.
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: asset-legality
|
|
3
|
+
description: What may be fetched, downloaded, generated and published, how the asset ledger (assets.lock.json) records it, and what publishing refuses. Load before using anything from the web or a generator.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Asset legality
|
|
7
|
+
|
|
8
|
+
A planet is published to everyone, so everything in it must be something the creator may publish. The studio keeps the record for you: every file that comes into the game goes through **asset_import**, which reads its licence, refuses what may not be used, and writes the file, its source and its licence into **assets.lock.json** (the ledger). CREDITS.md is generated from the ledger. When in doubt, leave a file out and say why. This is the studio's rule set, not legal advice; facts are as of 2026-10-20 and terms change.
|
|
9
|
+
|
|
10
|
+
## Never fetched, downloaded or fed to a model
|
|
11
|
+
|
|
12
|
+
These sites are for the creator's own eyes. Do not fetch their pages or images, do not download from them, and never give their images to any model (as input to an LLM, or to a generation API as a reference):
|
|
13
|
+
|
|
14
|
+
- **ArtStation**: NoAI is the default on every work since September 2026 (older works included), and its terms forbid scraping and using NoAI works as input to generative AI, which includes a tool like this one.
|
|
15
|
+
- **Pinterest**: no automated access without permission; its robots.txt blocks everything.
|
|
16
|
+
- **Behance**: its robots.txt blocks AI crawlers.
|
|
17
|
+
|
|
18
|
+
The studio blocks these hosts in WebFetch, the browser, downloads, asset_fetch (every redirect is checked), asset_import (a file recorded as coming from them is refused) and asset_generate (a picture from them is never sent). When the creator's reference comes from one of them, ask the creator to describe it, work from their words, and say so.
|
|
19
|
+
|
|
20
|
+
## The ledger
|
|
21
|
+
|
|
22
|
+
`assets.lock.json` sits at the project root and goes into git. One entry per file under `assets/` (what the game carries) and under `blender/` (what models are built from):
|
|
23
|
+
|
|
24
|
+
- **kind** (model, texture, hdri, audio, lut; blend and image for blender/ inputs), **bytes** and **sha256**
|
|
25
|
+
- **origin**: download (a library or the browser), generated (a paid generator), made (nw_blender), creator (a file the creator dropped in), legacy (in assets/ before the ledger existed; the creator's, as far as anyone knows)
|
|
26
|
+
- **license**: an SPDX id, its URL, the credit line, the day it was read
|
|
27
|
+
- **source** (library, id, page, author, title, host), **generation** (vendor, model, prompt, job, cost), **derivedFrom** (the blender/ inputs a GLB was baked from), **steps** (what was done to it)
|
|
28
|
+
|
|
29
|
+
Who writes it: asset_import, nw_blender (each export, with the licence derived from its inputs), nw_take_download (blender/ inputs) and the creator's drop. Nothing else, and never you by hand: a file you put in assets/ with Bash is unrecorded, and publishing refuses it. Read it with **asset_ledger**, which also lists what would stop a publish.
|
|
30
|
+
|
|
31
|
+
CREDITS.md has a generated section between `<!-- nowhere:credits -->` and `<!-- /nowhere:credits -->`; the creator's own text outside the markers is kept.
|
|
32
|
+
|
|
33
|
+
## Licences
|
|
34
|
+
|
|
35
|
+
| Licence | In the studio | Published |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| CC0, public domain | yes | yes |
|
|
38
|
+
| The creator's own, generated output the creator owns (Meshy and fal on a paid plan, Tripo on paid credits, World Labs) | yes | yes |
|
|
39
|
+
| Quaternius QAL | yes, inside one planet | yes; never in a template, an example or a shared library |
|
|
40
|
+
| CC BY 3.0 / 4.0 | yes, with a credit line | yes: the planet's page shows its credit line to visitors (publish contract 4) |
|
|
41
|
+
| CC BY-SA | only after the creator agrees (nw_ask kind choice), with a credit | yes, as CC BY |
|
|
42
|
+
| NC, ND, Editorial, NoAI, unknown, no licence | refused | refused |
|
|
43
|
+
|
|
44
|
+
- **ND** allows converting the file format and nothing else; reducing, retexturing or kitbashing is a derivative, so ND is refused outright.
|
|
45
|
+
- **CC BY-SA** puts the same licence on what is built from it. Ask the creator first, on a card in the screen language; only after a yes pass `confirmedShareAlike: true`.
|
|
46
|
+
- **The licence on the day of download applies.** The ledger keeps the day (and, when read, a hash of the licence text).
|
|
47
|
+
- **A mirror can label a file differently from its original** (Poly Pizza labels some Quaternius models CC BY; the original is QAL or CC0). The stricter one wins; the Poly Pizza adapter does this for you.
|
|
48
|
+
- A model built in Blender from inputs takes the **strictest** licence among them, and joins their credits: a CC BY texture on a model makes the model CC BY.
|
|
49
|
+
- **A scan** (a splat) is the creator's own only when they made it themselves: ask in an nw_ask choice card, in the screen language, whether they scanned it, and pass `capture: true` to asset_import only on a yes. `capture` is refused for a download: a scan someone else published is not the creator's, and takes the licence on its page.
|
|
50
|
+
|
|
51
|
+
## What publishing refuses
|
|
52
|
+
|
|
53
|
+
With a ledger, a planet carries every file the ledger records under assets/, the HDRI sky and LUT the config names, and every file the game's code names as a plain string (`ctx.assets.texture('assets/grass.png')`; a path built while the game runs is not seen, so name each file in full). Publishing refuses, with one sentence each:
|
|
54
|
+
|
|
55
|
+
- a file the scene, the config or the code names that the ledger does not know (`ledger:missing`): bring it in with asset_import. A file nothing names stays on the machine.
|
|
56
|
+
- an imported file changed since it was recorded (`ledger:bytes`, `ledger:sha`): import it again with `replace: true`. The creator's own files (their drops, and what sat in assets/ before the ledger) are measured again instead.
|
|
57
|
+
- a download given a licence only the studio records (LicenseRef-Own, LicenseRef-Creator-Declared, LicenseRef-Generated-Owned): asset_import refuses it; pass the licence on the file's page
|
|
58
|
+
- a refused licence, a CC BY file without its credit, CC BY-SA the creator has not agreed to
|
|
59
|
+
- CC BY to an Oda server or player from before publish contract 4, which cannot show credits: the Publish stops before uploading and says so. CC0 files are never held up.
|
|
60
|
+
- a file over its kind's ceiling (models 50 MB, textures 8 MB, HDRIs 24 MB, sounds 10 MB, LUTs 2 MB), more than 20 MB of sound, more than 100 MB in all
|
|
61
|
+
|
|
62
|
+
Without a ledger (a project that never imported anything), only the models scene.json places travel, as always; when the code loads a file the scene does not place, publishing starts the ledger first (what assets/ holds is recorded as the creator's), so the file travels.
|
|
63
|
+
|
|
64
|
+
Since publish contract 4 planets decode meshopt geometry and KTX2 textures (decision D1) and show their credits (decision D2):
|
|
65
|
+
|
|
66
|
+
- asset_import writes a material's maps and a model's textures as KTX2 (each map in the codec it holds up in) and a model's geometry meshopt-compressed, unless the last Publish found the live server or player without them; then it writes PNG or JPEG and plain geometry (normals and UVs quantized, positions kept in metres) and says why. A download with KTX2 textures is refused only then.
|
|
67
|
+
- CC BY and CC BY-SA publish with their credit line, which the planet's page shows. Keep the credit exactly as the source asks.
|
|
68
|
+
|
|
69
|
+
## Sources and what they need
|
|
70
|
+
|
|
71
|
+
- **Poly Haven** and **ambientCG** (CC0): through asset_search and asset_fetch, never by scraping the sites. Pick 1K or 2K sets; 8K sets are huge and no game needs them.
|
|
72
|
+
- **Kenney** (CC0), through **Poly Pizza**, with the creator's free key (connector polypizza).
|
|
73
|
+
- **Sketchfab**: downloads need the creator's own sign-in. If the creator downloads a model themselves, bring it in with asset_import and its licence (and Sketchfab Editorial is refused).
|
|
74
|
+
- **Freesound**: its API is non-commercial only, so it is not used.
|
|
75
|
+
- For references: **Openverse**, **Wikimedia Commons**, **The Met** open access, the **Smithsonian** open access and **NASA**. Check each item's own licence.
|
|
76
|
+
|
|
77
|
+
## Web references
|
|
78
|
+
|
|
79
|
+
- nw_find_pictures looks; nw_keep_pictures keeps the pictures you build from under refs/web/, each recorded in refs/board.json with its page, site, licence and use.
|
|
80
|
+
- They are to look at (use "look only"): never under assets/, never in the space's code, never imported and never a generator's input. asset_import, nw_take_download and the generators refuse them.
|
|
81
|
+
- A CC0 or public-domain one (use "look and generate") may also be a generator's input, or come in through asset_import with its licence.
|
|
82
|
+
- ArtStation, Pinterest and Behance are never searched or kept.
|
|
83
|
+
|
|
84
|
+
## Downloads from the browser
|
|
85
|
+
|
|
86
|
+
- A download lands in quarantine (`.nowhere/quarantine/`) and is checked (type, size, that it is not a web page). Read its licence page, then:
|
|
87
|
+
- for the game: **asset_import** from the download's id, with `license: { spdx, url, author, title, credit }`
|
|
88
|
+
- for nw_blender to build from: **nw_take_download** into blender/ with the same `license`
|
|
89
|
+
- An archive: asset_fetch unpacks a library's zips safely; a browser zip you unzip inside quarantine with Bash, then import the file you need.
|
|
90
|
+
- Never run a downloaded script, installer or add-on. Open a downloaded .blend only through nw_blender, which runs Blender with auto-run scripts off.
|
|
91
|
+
- Never get past a sign-in, a paywall or a CAPTCHA for the creator; ask them to do that part.
|
|
92
|
+
|
|
93
|
+
## Generation services
|
|
94
|
+
|
|
95
|
+
- Only after the creator approved a cost card (asset_generate estimate, then nw_ask kind cost, then submit); every job's cost goes into the spend.
|
|
96
|
+
- **Hunyuan3D** is refused: its open weights' licence does not cover Korea, the EU or the UK.
|
|
97
|
+
- **Meshy** (connector meshy, key MESHY_API_KEY) API output on a paid plan and **fal** TRELLIS.2 (connector fal, key FAL_KEY) output belong to the creator. A Meshy free plan's output would be CC BY 4.0, but a free plan has no API.
|
|
98
|
+
- **Tripo** (connector tripo, key TRIPO_API_KEY; text, one picture or several views to 3D) API output on paid credits belongs to the creator (API terms 5.2.2, last updated 2025-07-11). A Free User's output does not: Tripo keeps all rights to it (5.2.1), so nothing made on a free plan is used.
|
|
99
|
+
- **World Labs** Marble (connector worldlabs, key WORLDLABS_API_KEY; environment_generate, a whole splat environment, only when the creator asks for a generated world) API output belongs to the creator (terms of service 3.3(b), updated 2026-01-21), with attribution to World Labs on their request (3.7(b)), so its credit line always goes in.
|
|
100
|
+
- **ElevenLabs Music** needs a separate game licence, so it is not used. Sound effects come from CC0 libraries or are made in code.
|
|
101
|
+
- Never put a living artist's name, or a copyrighted character, in a generation prompt, and never send a grade C reference picture or one from the blocked sites.
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: asset-sources
|
|
3
|
+
description: Where a space's environment, props, materials, skies and sounds come from, best first (scanned CC0, Blender, paid generation for props only), each class's limits, checks against the brief, and ctx.assets in code. Load before making or fetching any asset.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Asset sources
|
|
7
|
+
|
|
8
|
+
A space looks as good as what is in it. Boxes and cylinders read as a blockout however well lit, so never make a hero asset from primitives. Get each thing from the best place first, and bring every file in through **asset_import**, which converts, optimises, sizes and records its licence (nowhere:asset-legality).
|
|
9
|
+
|
|
10
|
+
In the order for a space these are steps 4 to 6, after brief.json: **the environment** (code first, as procedural geometry and TSL; scanned CC0 libraries for what code cannot reach; an HDRI or a physical sky as the brief's light says), then **the props** (CC0 first, Blender for what is specific, a generated model only for a prop and delit, never the space itself), then **materials and compression** (asset_inspect against the brief's texel density, below).
|
|
11
|
+
|
|
12
|
+
## Best first
|
|
13
|
+
|
|
14
|
+
1. **Already in the project.** asset_ledger lists what assets/ holds and where each file came from.
|
|
15
|
+
2. **A CC0 library**, for anything common: rocks, trees, plants, furniture, props, ground and wall materials, skies.
|
|
16
|
+
- `asset_search` with a kind: `model`, `material` (a set of PBR maps) or `hdri` (a sky that lights the scene). Poly Haven and ambientCG need no key; `kenney` in the query finds Kenney's low-poly models on Poly Pizza (the free polypizza key: nw_ask kind key).
|
|
17
|
+
- The main surfaces (floor, walls), the sky and the hero props are the creator's to pick: offer the best 2 to 4 hits with **nw_ask_asset**, one card per role, never per prop or for a small prop. The pick comes back imported and inspected: never fetch it again. On "you choose" or no answer, import the best yourself and say which.
|
|
18
|
+
- `asset_fetch` any other id you picked into quarantine.
|
|
19
|
+
- `asset_import` it into assets/ with a class, and a size if it is not at real size.
|
|
20
|
+
3. **Blender**, for anything exact or specific to this space: a model of this shape and size, for this brief. Write a bpy script for that one asset and run it with nw_blender (nowhere:blender-modeling); read the sheets and the rubric after every run.
|
|
21
|
+
4. **Image to 3D**, for a prop only this space has (a hero prop, a form too irregular to script in time), never its ground, walls or architecture: from a picture of the object alone (the reference's crop, when it may be sent), or one made first with `image_generate` (Codex on the creator's ChatGPT plan, or a paid one after a cost card): one clean view, or 2 to 4 in this order: the front, its right side, the back, its left side (Tripo reads each view by its place). Then `asset_generate` estimate, nw_ask kind cost, submit; `asset_job` until done; `asset_import` the result, which Blender cleans up first (size, origin, triangles and textures to the class). It rebuilds one object, whole and alone: nothing in front of it, no lettering, a plain background. Its colour must be delit, or the space's light falls on shadows painted in: Meshy (not meshy-6-lite) and Tripo are asked to remove the lighting, fal TRELLIS.2 is not; asset_inspect says when shadow is baked into a model's colour.
|
|
22
|
+
5. **Code**, for what is procedural by nature: terrain, scatter, water, grass, particles, glow, effects, each with a TSL shader written for this brief (nowhere:tsl-r185 has the API).
|
|
23
|
+
|
|
24
|
+
Say in brief.md which way each asset came and why. In a team production the task names each asset's way (the director's method) with its first tool inputs: make it that way.
|
|
25
|
+
|
|
26
|
+
## Classes and budgets
|
|
27
|
+
|
|
28
|
+
Name a class on every model import: it sets the triangle budget (asset_import simplifies a model over it) and the longest texture side.
|
|
29
|
+
|
|
30
|
+
| class | triangles | texture px | for |
|
|
31
|
+
|---|---|---|---|
|
|
32
|
+
| small | 2,000 | 512 | cups, bolts, pickups, pebbles |
|
|
33
|
+
| prop | 5,000 | 1,024 | crates, barrels, chairs, lamps (the default) |
|
|
34
|
+
| large | 20,000 | 2,048 | cars, boats, big rocks, trees |
|
|
35
|
+
| hero | 50,000 | 2,048 | the thing the space is about, seen up close |
|
|
36
|
+
| character | 30,000 | 2,048 | people, creatures |
|
|
37
|
+
| building | 40,000 | 2,048 | houses, towers, lighthouses |
|
|
38
|
+
| terrain | 100,000 | 2,048 | a ground mesh |
|
|
39
|
+
|
|
40
|
+
A hero, character or building under 5% of its budget reads as a blockout. Many copies of one prop cost little: place them, or make them instances in code.
|
|
41
|
+
|
|
42
|
+
## Resolution and size
|
|
43
|
+
|
|
44
|
+
- Pick the resolution by **texel density**: the pixels per metre a surface needs at the distance the brief has the visitor stand. brief.json gives each material its `texelDensity` (`budget.texelDensity` for the rest); asset_search lists what 1k, 2k and 4k give at the item's real size. Fetch the lowest that meets it. Poly Haven and ambientCG go to 4k here; never 8K.
|
|
45
|
+
- Keep to the libraries the brief names in `sources.libraries` (asset_search asks them first): scans from one family match each other. asset_import records each pick in the brief.
|
|
46
|
+
- Give `size` in metres, one of `height`, `width`, `depth` or `longest` (`{ "height": <metres> }`), as the brief sizes the thing. The player is 1.75 m tall, eyes at 1.6 m. Poly Haven models are already in metres; leave size out for them unless you want another.
|
|
47
|
+
- `pivot: "base"` (the default) stands the model on y = 0, its footprint centred on the origin.
|
|
48
|
+
|
|
49
|
+
## Inspecting against the brief
|
|
50
|
+
|
|
51
|
+
- asset_import inspects everything it writes, and `asset_inspect` any file in assets/: the maps a material has and lacks (colour, normal, rough, ao, metal, displacement, opacity), the texel density at real size against the brief's target, the 2 x 2 seam score with the tiled picture, a model's untextured parts, its UV density over its triangles and shadow baked into its colour. Under half the target nothing is imported: fetch a higher resolution, let one tile cover less (`tileSize`), or correct the brief. A seam verdict of `joint` (the wrap steps as hard as the pattern's own joints: grout or a plank gap on the edge, or a seam): look at the 2 x 2 sheet before you keep it.
|
|
52
|
+
- One material name holds one set of maps: another set under a name already in assets/ is refused unless `replace: true`, which removes the old maps, their ledger entries and credits.
|
|
53
|
+
- A surface no library has: `image_generate` with kind `texture` (made seamless, its seam scored), `panorama` (a 2:1 sky) or `card` (a cut-out with alpha, on a key colour the subject does not have). They land in quarantine; asset_import them like a download. A panorama imported as `assets/<name>.hdr` becomes a sky the config reads (an 8-bit picture lights like an overcast sky; the sun is the config's). A scanned library comes first for anything real.
|
|
54
|
+
- asset_import writes textures as KTX2 (each map in the codec it holds up in; a single texture as `assets/<name>.ktx2`) and a model's geometry meshopt-compressed, since publish contract 4 planets decode both (its `ktx2` field says when it writes pictures instead, and how to measure). KTX2 cuts GPU memory to a quarter or less, but a scanned map as UASTC often downloads larger than its JPEG: the inspection says both; weigh them against the planet's 100 MB (`ktx2: "off"` keeps the picture). Blender reads neither: model from the inputs in blender/, never from a compressed assets/ GLB.
|
|
55
|
+
|
|
56
|
+
## Using what you imported
|
|
57
|
+
|
|
58
|
+
Every host passes `ctx.assets`; each call returns at once and fills in when the file has loaded, and `ctx.assets.problems()` lists what failed.
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
import * as THREE from 'three/webgpu'
|
|
62
|
+
import { World, type GameContext } from '@nowhere/sdk'
|
|
63
|
+
|
|
64
|
+
export function createGame(ctx: GameContext) {
|
|
65
|
+
const world = new World(ctx)
|
|
66
|
+
const a = ctx.assets!
|
|
67
|
+
// asset_import's material: _color is sRGB, the other maps data (color:
|
|
68
|
+
// false). repeat, the surface's metres over one tile's, keeps its real size.
|
|
69
|
+
const ground = new THREE.MeshStandardNodeMaterial({
|
|
70
|
+
map: a.texture('assets/forest_floor_color.jpg', { repeat: [8, 8] }),
|
|
71
|
+
normalMap: a.texture('assets/forest_floor_normal.jpg', { color: false, repeat: [8, 8] }),
|
|
72
|
+
})
|
|
73
|
+
world.add('ground', new THREE.Mesh(new THREE.PlaneGeometry(60, 60).rotateX(-Math.PI / 2), ground), { solid: true })
|
|
74
|
+
// A model in code: a new group each call; its children arrive later.
|
|
75
|
+
world.add('rock', a.model('assets/rock.glb'), { position: [4, 0, -6], solid: true })
|
|
76
|
+
return world.finish()
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
- Place models in scene.json when the creator should be able to move them; load them in code when the code decides where they go (scatter, spawns).
|
|
81
|
+
- **An HDRI sky** is the look's, not the code's (ambientCG's come as `.exr`, Poly Haven's as `.hdr`): asset_import measures its colours and answers the `look_apply` value, `{ "set": { "sky": { "kind": "hdri", "asset": "assets/sky.hdr", "top": "#...", "bottom": "#..." } } }`. It lights every material and paints the background; `"background": false` keeps the light and paints nothing. `a.hdri(path)` is for a material of your own.
|
|
82
|
+
- **A LUT** (.cube) is the look's grade: `{ "set": { "look": { "grade": { "lut": { "asset": "assets/film.cube" } } } } }`.
|
|
83
|
+
- **A splat environment** (a Gaussian splat, `.spz`) is a whole place as captured: the creator's phone or camera scan (a `.ply`, `.spz` or `.splat`; a studio drop waits in `.nowhere/quarantine/drop-<name>-<stamp>/`, copy any other into `.nowhere/quarantine/`; `capture: true` only as nowhere:asset-legality says), or, only when the creator asks for a generated world, `environment_generate` (World Labs Marble, after a cost card) and `environment_job`. `asset_import` as `assets/<name>.spz` turns it upright, into metres and onto y = 0, its collider beside it as `<name>_collider.glb` (upside down in nw_view: import it again with the other `orientation`). Draw it with `world.add('<name>', a.splat('assets/<name>.spz', { collider: 'assets/<name>_collider.glb', light: true }), { solid: true, climb: false })`, the config's ground `{ "kind": "none" }`. The import's answer says how far a walker gets from the spawn and where the collider's floor ends over nothing, where the walker is held (`edges: 'open'` lets it fall); nw_play reports a drop in `fell`. A scan without a collider needs one made over it (a floor and walls in Blender, imported with `colliderFrame: "space"`). Splats publish from contract 4 on.
|
|
84
|
+
|
|
85
|
+
## Sound
|
|
86
|
+
|
|
87
|
+
- From CC0 libraries or the creator's own files, through asset_import as `.ogg` (converted with ffmpeg when it is here), `.mp3` or `.wav`. At most 10 MB a sound, 20 MB in all.
|
|
88
|
+
- `const s = a.sound('assets/waves.ogg', { loop: true, volume: 0.5 }); s.play()`. `at: object` places a sound (a fire, a waterfall); `refDistance` and `rolloff` shape its fade.
|
|
89
|
+
- Browsers start sound only after the visitor's first key or click; the host resumes it then, so call play() whenever the space wants.
|
|
90
|
+
- Simple short effects (a beep, a whoosh) can be WebAudio in code.
|
|
91
|
+
|
|
92
|
+
## What the tools refuse, and what to do
|
|
93
|
+
|
|
94
|
+
| Refusal | Do instead |
|
|
95
|
+
|---|---|
|
|
96
|
+
| No web consent | Use what the project has, or ask the creator to allow the web |
|
|
97
|
+
| A missing key (polypizza, meshy, fal, tripo, worldlabs) | nw_ask kind key, with the connector id |
|
|
98
|
+
| NC, ND, Editorial, unknown licence | Pick a CC0 hit |
|
|
99
|
+
| CC BY without a credit | Pass license.credit; the planet's page shows it |
|
|
100
|
+
| CC BY-SA without agreement | nw_ask kind choice first, then confirmedShareAlike: true |
|
|
101
|
+
| A browser download without source.json | Read its licence page, pass license { spdx, url, author, title } |
|
|
102
|
+
| An FBX, OBJ or USD without Blender | Pick the GLB or glTF download |
|
|
103
|
+
| Units that do not look like metres | Pass size |
|
|
104
|
+
| An existing target | replace: true, or another name |
|
|
105
|
+
| Paid generation without an approved cost card | estimate, nw_ask kind cost, then submit |
|
|
106
|
+
| Hunyuan3D | Meshy, Tripo or TRELLIS.2 |
|
|
107
|
+
| Putting files in assets/ by hand or with nw_take_download | asset_import; publishing refuses unrecorded files |
|
|
108
|
+
|
|
109
|
+
## Checking the result
|
|
110
|
+
|
|
111
|
+
After an import, place or load the model, then nw_view the player's view: is it the right size beside the player, on the ground, its material reading in this light? asset_import's contact sheets and rubric (when Blender is here) show the model alone; the space's view shows it in place. Before you say you are done, asset_ledger must show no problems.
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: blender-modeling
|
|
3
|
+
description: Modelling one game asset in headless Blender for Oda with nw_blender and a bpy script written for that asset: how to decide its form from the brief, the bpy facts that reach a GLB, and the rubric and sheets every export is judged by. Load before writing any Blender script.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Modelling a game asset in Blender
|
|
7
|
+
|
|
8
|
+
nw_blender runs your bpy script in Blender without a window, exports a GLB into `assets/`, imports it again and renders two contact sheets (colour and clay) with the numbers, and scores the model: the **rubric**. You never see Blender; you see the sheets and the rubric.
|
|
9
|
+
|
|
10
|
+
There is no toolkit and no kit of parts: every asset is modelled for its own request. The script is plain `bpy` (and `bmesh`), written from what this asset must be.
|
|
11
|
+
|
|
12
|
+
## Decide the form first
|
|
13
|
+
|
|
14
|
+
Before the first line of the script, write down from the brief and the reference (in a comment at the top of the script):
|
|
15
|
+
|
|
16
|
+
- **What it is and what it is for** in this game: what the player does with it, how close they get, how long they look.
|
|
17
|
+
- **Its size in metres**, from the brief's `forms.scale`, against the 1.75 m player. A size the brief does not give is one you decide from what the thing is, and say so.
|
|
18
|
+
- **Its silhouette**: the outlines from the front, the side and above that make it recognisable in the reference, and which parts stand out of its bounding box.
|
|
19
|
+
- **Its parts**, biggest first, each with its size: the masses, then the secondary forms, then the detail that the player's distance can read.
|
|
20
|
+
- **Its surfaces**: which part has which of the brief's materials (its colours as hex, its roughness range, metal or not, the detail line).
|
|
21
|
+
- **Its class** for the triangle budget (below), and whether it is a hero.
|
|
22
|
+
|
|
23
|
+
Model what you wrote, not a generic version of the noun.
|
|
24
|
+
|
|
25
|
+
## The loop
|
|
26
|
+
|
|
27
|
+
1. **The masses at real size.** Run nw_blender. Check the size and the pivot in the answer, and the proportion beside the figure in the sheets.
|
|
28
|
+
2. **The secondary forms** your notes list. Run again.
|
|
29
|
+
3. **Edges and normals** where the form has them. Run again.
|
|
30
|
+
4. **Materials** per surface, from the brief's colours and roughness. Run again.
|
|
31
|
+
5. **Detail** where the close-up or the player's view shows it, and lighter copies when the budget asks.
|
|
32
|
+
|
|
33
|
+
Read the sheets and the rubric after every run. Write the differences down before fixing them, with numbers: "the roof is 1.2 m, the reference reads about 2.5 m". A hero asset gets at least three rounds and is done when the sheets show what your notes, the brief and the reference say. No rubric score is a pass mark: weigh each against this brief.
|
|
34
|
+
|
|
35
|
+
A round is a change to the model that answers what the sheets showed: write the differences, edit the script to fix the biggest, run. Rendering an unchanged script again with a closer `closeup` is a look, not a round; nw_blender's second line says which round this is, or that the script did not change since the last render.
|
|
36
|
+
|
|
37
|
+
## What nw_blender does around your script
|
|
38
|
+
|
|
39
|
+
- The scene is empty when your script starts, in metres. Do not reset it, read `sys.argv`, export, save or quit: nw_blender exports every visible mesh (or only `collection`), applies modifiers, and saves a .blend only when you pass `blend`.
|
|
40
|
+
- The working directory is the project root (`blender/textures/x.png` works as a path). Helpers of your own beside the script (`blender/lib.py`) import.
|
|
41
|
+
- Pass `class` (small, prop, large, hero, character, building, terrain) and `expect` ({height, width, depth} in metres) with every call: the rubric scores against them (prop when no class is given; no size check without `expect`).
|
|
42
|
+
- Every export is recorded in `assets.lock.json` as made by the project, with the licences of the project files the script read (images, linked .blend files); the images the run itself wrote (its bakes) are not inputs. Bring outside textures in with nw_take_download first, so the ledger knows them.
|
|
43
|
+
|
|
44
|
+
## bpy facts
|
|
45
|
+
|
|
46
|
+
- **Meshes.** `bpy.data.meshes.new(name)` with `mesh.from_pydata(verts, [], faces)`, or `bmesh` (`bmesh.new()`, `bmesh.ops.*`, then `bm.to_mesh(mesh)` and `bm.free()`); then `obj = bpy.data.objects.new(name, mesh)` and link it: `bpy.context.scene.collection.objects.link(obj)`, or a collection's `objects.link`. `bpy.ops.mesh.primitive_*_add(...)` works headless too, and makes the new object active and selected.
|
|
47
|
+
- **Shading.** `mesh.shade_smooth()`, `mesh.shade_flat()`, and `mesh.set_sharp_from_angle(angle=radians)` (Blender 4.1 and later: there is no auto smooth). Custom normals export.
|
|
48
|
+
- **Modifiers.** `obj.modifiers.new(name, type)`: `'BEVEL'` (`width`, `segments`, `limit_method` `'ANGLE'` with `angle_limit`, `harden_normals`), `'WEIGHTED_NORMAL'` (last in the stack, `keep_sharp`), `'SUBSURF'`, `'MIRROR'`, `'ARRAY'`, `'SOLIDIFY'`, `'BOOLEAN'` (`object` is the cutter; hide the cutter with `cutter.hide_set(True)` and `cutter.hide_render = True` so it is not exported), `'DISPLACE'`, `'DECIMATE'` (`ratio`). nw_blender applies every modifier on export.
|
|
49
|
+
- **Transforms.** Build the mesh around the origin you want, or move its vertices (`mesh.transform(Matrix.Translation(...))`). `bpy.ops.object.transform_apply(location=False, rotation=True, scale=True)` acts on the selected objects.
|
|
50
|
+
- **Materials.** `mat = bpy.data.materials.new(name)`; in Blender 5 it has a node tree with a Principled BSDF (`use_nodes` is deprecated). Its inputs: `'Base Color'` (linear RGBA: convert a brief hex from sRGB), `'Metallic'`, `'Roughness'`, `'Alpha'`, `'Normal'`, `'Emission Color'`, `'Emission Strength'`, `'Transmission Weight'`, `'Coat Weight'`. `obj.data.materials.append(mat)`; per face, `polygon.material_index`. Emission Strength above 1 is meaningful: the planet's bloom spreads it.
|
|
51
|
+
- **Images.** `bpy.data.images.load(path)` or `bpy.data.images.new(name, w, h)` with `image.pixels.foreach_set(...)` and `image.filepath_raw = path; image.file_format = 'PNG'; image.save()`. A `ShaderNodeTexImage` reads it; a data map (roughness, metallic, normal) needs `image.colorspace_settings.name = 'Non-Color'`, and a normal map goes through a `ShaderNodeNormalMap`.
|
|
52
|
+
- **UVs.** `mesh.uv_layers.new(name='UVMap')`, then set `uv_layer.data[i].uv` per loop, or `bmesh` (`bm.loops.layers.uv.verify()`); `bpy.ops.uv.smart_project()` and `cube_project()` need the object in edit mode with its faces selected. Every textured mesh needs UVs.
|
|
53
|
+
- **Baking.** Procedural nodes do not reach glTF; baking turns them into images. `scene.render.engine = 'CYCLES'`, `scene.cycles.device = 'CPU'` (headless has no GPU to rely on), an image node selected and active in each material, the object selected and active, then `bpy.ops.object.bake(type=...)`: `'DIFFUSE'` with `pass_filter={'COLOR'}` for colour, `'ROUGHNESS'`, `'NORMAL'`, or `'EMIT'` for any value routed through an Emission shader. Bake after the last change to the shapes, save the images under `blender/textures/`, then rewire the material to them.
|
|
54
|
+
- **Collections.** `bpy.data.collections.new(name)` and `scene.collection.children.link(coll)`. A collection excluded from the view layer is left out of the default export; nw_blender's `collection` exports exactly one (a lighter copy, for example).
|
|
55
|
+
|
|
56
|
+
## Materials that survive glTF
|
|
57
|
+
|
|
58
|
+
Only a Principled BSDF with plain values and image textures reaches the game (plus a Color Attribute multiplied into Base Color with a Mix node). Noise, Voronoi, Bump, Map Range and the rest are dropped on export: nw_blender lists them under "glTF dropped" until you bake them.
|
|
59
|
+
|
|
60
|
+
## The rubric
|
|
61
|
+
|
|
62
|
+
`rubric: silhouette 4/5 (...), bevel 2/5 (...), materials 3/5 (...), budget 5/5 (...)`, then `fix first:` (the lowest score and what it measured) and `checks:`.
|
|
63
|
+
|
|
64
|
+
| Score | What it measures | Low means | What changes it |
|
|
65
|
+
|---|---|---|---|
|
|
66
|
+
| silhouette | front, side and top outlines: fill, complexity, holes | it reads as a box from every side | the outline itself: the parts your notes say stand out, overhangs and openings the form has |
|
|
67
|
+
| bevel | share of hard edges that are razor sharp (75 degrees or more) | edges look cut from paper | bevelled geometry or a Bevel modifier on the edges the form has rounded, normals weighted after it |
|
|
68
|
+
| materials | distinct base colours, textures, normal maps | one flat colour | each surface its own material from the brief, and texture where the surface has it (baked when procedural) |
|
|
69
|
+
| budget | triangles against the class budget (small 2k, prop 5k, large 20k, hero 50k, character 30k, building 40k, terrain 100k) | over it: too heavy; a hero under 5%: a blockout | fewer segments and subdivision levels, a Decimate copy; or more of the form and detail your notes list |
|
|
70
|
+
|
|
71
|
+
Checks (not scored): the expected size within 5%, the pivot (base centre at the origin), open or non-manifold edges, faces wound against each other, UVs on textured meshes, texel density, nodes glTF dropped. A plain box is honest about itself: silhouette 1, bevel 1, materials 1. The rubric measures; it does not know what the asset should be. Your notes and the reference do: a one-colour marble statue, a chrome object or a black monolith scores materials low and is right; a faceted low-poly or papercraft brief scores bevel low and is right. "Low means" in the table is what the number says about the model, not that it is wrong for this request. The gate checks only the class budget, the size and the rounds; the critic weighs the numbers against the brief.
|
|
72
|
+
|
|
73
|
+
## Conventions
|
|
74
|
+
|
|
75
|
+
- Metres, Z up, the front facing -Y (glTF turns that into the studio's yaw 0 view). The origin at the base centre: the pivot check wants it, and the studio stands models on their origin.
|
|
76
|
+
- One asset per script, named after it; readable object names (`roof`, `door_frame`).
|
|
77
|
+
- Shared materials between objects; textures 1024 for a prop, 2048 at most.
|
|
78
|
+
|
|
79
|
+
## Reading the sheets
|
|
80
|
+
|
|
81
|
+
- Top row: front, side (+X), back, orthographic. Bottom row: three-quarter, top, close-up (the top third unless you pass `closeup`).
|
|
82
|
+
- Proportion against the 1.75 m figure beside the model.
|
|
83
|
+
- The clay sheet shows form without colour: if it reads as a blob in clay, colour will not save it.
|
|
84
|
+
- Trust the sheets over your script: they render the exported GLB.
|
|
85
|
+
|
|
86
|
+
## Placing the result
|
|
87
|
+
|
|
88
|
+
In a team task your task names a placement of the blockout: when the task ends, the director puts the model in the game there itself, where the stand-in stood (the model's base on the stand-in's base, or its top on the stand-in's top for a placement whose anchor is top), at the size you exported. Place nothing; the size you export is the size the game shows.
|
|
89
|
+
|
|
90
|
+
Working on your own, add a placement to scene.json with `"normalize": false`, so the studio keeps the size you modelled instead of auto-sizing anything over 12 m or under 0.375 m to 3 m:
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{ "id": "<asset>", "asset": "assets/<asset>.glb", "kind": "<asset>", "solid": true,
|
|
94
|
+
"position": [0, 0, 0], "rotation": [0, 0, 0], "scale": [1, 1, 1], "normalize": false }
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Then look at it in the game: an nw_view close-up and the player view.
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: look-dev
|
|
3
|
+
description: Setting a planet's look (sky, fog, light, tone curve, grade, glow, AO, vignette, grain) from brief.json's numbers with look_apply, and judging it at the brief's hero views against the references with look_compare and nw_compare. Load before touching the mood of a scene.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Look development
|
|
7
|
+
|
|
8
|
+
The look is data in game.config.json: `sky`, `fog`, `lighting`, `bloom` and the `look` block. The studio, the CLI preview and the planet's player page all draw it with the SDK's createLook: what you see in nw_view is what a visitor sees on a high-tier device. In the order for a space it is step 7, after brief.json and the space's files, and before any material is tuned by eye: a wrong sun or tone curve makes every material look wrong.
|
|
9
|
+
|
|
10
|
+
Never edit these fields by hand when look_apply can: it merges, validates the whole config and writes nothing when a value is out of range or a key is unknown.
|
|
11
|
+
|
|
12
|
+
## The loop
|
|
13
|
+
|
|
14
|
+
1. **The brief's numbers.** brief.json's palette, light (the sun's azimuth, elevation and colour, the sky's kind, the shadow colour, fog) and scale, and each reference's measured numbers (nw_reference: values, contrast, warmth, haze).
|
|
15
|
+
2. **From the brief to values** (below), written with `look_apply { set }`, and config.player from the brief's scale. There is no stock mood to start from: every value is this brief's. nw_status's lookWarnings names what is still left to the defaults; it must end empty.
|
|
16
|
+
3. **Look** with `nw_view` at the brief's hero views (`view: "free"` with each one's position, lookAt and fov) and the player view; `nw_compare` puts a view beside the reference.
|
|
17
|
+
4. **Compare**: `look_compare { reference, views, palette }` at each hero view, against the reference that view names, with the brief's palette. It waits for the space's files and judges no picture drawn before them; its verdict is the worse of the tone and the shade (the darkest fifth's colour). It holds only at the reference's framing, which is why the hero views are taken where the references' cameras stand.
|
|
18
|
+
5. **Adjust** with `look_apply { set }`: start from the suggestions look_compare prints (they are already set values), biggest difference first, one or two knobs a round.
|
|
19
|
+
6. Repeat 3 to 5 until the verdict is **close** or **matches** at every hero view, the palette deltaE is at most 10, and clipped highlights and crushed shadows are each at most 2% (unless the brief wants a blown sky or black shadows: say so in brief.md).
|
|
20
|
+
7. Write what still differs, with numbers, in brief.md's Differences section.
|
|
21
|
+
|
|
22
|
+
Stop after about eight rounds: what is left is in the scene (the models, their materials, the camera), not in the look.
|
|
23
|
+
|
|
24
|
+
## From the brief to values
|
|
25
|
+
|
|
26
|
+
Each step reads a number of the brief (which cites the references' facts) and turns it into a knob; the comparison then corrects it. Write in brief.md which fact each value came from.
|
|
27
|
+
|
|
28
|
+
- **Values to exposure.** The references' value key and L* percentiles give the range the frame should sit in. Start the exposure at 1, look, and read look_compare's mean L* against the reference: its suggestion turns the difference into EV. Lift the darks only when the reference's 5th percentile is higher than the view's.
|
|
29
|
+
- **Contrast.** The references' contrast against the view's (look_compare's contrast ratio) moves `look.grade.contrast`. Hard light also means a smaller `look.shadows.softness`; soft light a larger one.
|
|
30
|
+
- **Fog, when the brief has it.** No `light.fog` in the brief (clear air, a room): `fog: null`. With it, the fog's colour is the brief's (the farthest haze band's colour); `far` is where the farthest thing that must still read sits, a little past it; `near` is where the first layer starts to lift. Haze that sits low in the reference is `mode: "height"`.
|
|
31
|
+
- **The sun.** `light.sun.elevationDeg` comes from the shadows (elevation = atan(height / shadow length) on the ground); `light.sun.azimuthDeg` from where they fall. `lighting.sun.direction` is where the light travels: for azimuth A (clockwise from -Z toward +X) and elevation E it is [-sin A cos E, -sin E, cos A cos E]. Its colour is `light.sun.color`. Check in nw_view that shadows fall the way the reference's do.
|
|
32
|
+
- **Warmth and tint.** The reference's warmth (b*) against the view's, from look_compare, moves `look.grade.temperature`, and its tint (a*) `look.grade.tint`.
|
|
33
|
+
- **Saturation.** The view's chroma against the reference's (look_compare's chroma ratio) moves `look.grade.saturation`.
|
|
34
|
+
- **Shade.** look_compare's shade row is the darkest fifth of each picture against the reference's, and `light.shadowColor` is what the brief measured. Grey or crushed shadows where the reference's are coloured come from the fill (`lighting.ambient`, `look.environment`, the sky), the fog and the materials' own darks, not from exposure.
|
|
35
|
+
- **The sky.** `light.sky.kind` says which: an HDRI from asset_import (`hdri`, which also lights the scene), a `physical` sky lit by the sun, or a `gradient` whose top and bottom are the brief's sky colours.
|
|
36
|
+
|
|
37
|
+
## What each knob does
|
|
38
|
+
|
|
39
|
+
In the order the pipeline applies them. Scene-linear first (the light itself), then the curve, then display.
|
|
40
|
+
|
|
41
|
+
- `look.exposure` (0.05 to 8, default 1): a multiplier on all light before the curve. 2 is one stop brighter. Fix overall brightness here, not with the sun.
|
|
42
|
+
- `look.grade.temperature` (-1 cold to +1 warm) and `tint` (-1 green to +1 magenta): white balance. Grey keeps its brightness.
|
|
43
|
+
- `look.grade.cdl` `{ slope, offset, power }`, per channel: out = (in x slope + offset) ^ power. slope is gain, offset lifts blacks, power is a per-channel gamma.
|
|
44
|
+
- `look.grade.contrast` (0.5 to 1.5): around middle grey. Above 1 darks darker and lights lighter.
|
|
45
|
+
- `look.grade.saturation` (0 to 2): 0 is grey.
|
|
46
|
+
- `look.toneMapping`: `agx` (the default with a look block; rolls highlights off, saturated lights keep their colour), `neutral` (the Khronos PBR curve, closest to the materials' own colours; the default with no look block), `aces` (filmic: more contrast, shifts hues), `none` (a clamp).
|
|
47
|
+
- `look.grade.lut` `{ asset: "assets/x.cube", intensity }`: a 3D LUT over the display picture (bring .cube files in with asset_import). `null` removes it.
|
|
48
|
+
- `look.grade.posterize` (0 off, else steps per channel): banded colour.
|
|
49
|
+
- `look.vignette` `{ amount 0 to 1, smoothness 0.05 to 1 }`: darker corners.
|
|
50
|
+
- `look.grain` (0 to 0.3): film grain over the picture.
|
|
51
|
+
- `look.ao` `{ enabled, radius m, strength 0 to 1 }`: the dark where things meet. It is what puts objects ON the ground. Default 0.6 m at 0.85. Open flat ground gets none at any distance; it fades out from 25 m (25 x radius when the radius is above 1) to twice that, and where fog is.
|
|
52
|
+
- `look.shadows` `{ quality low|medium|high, softness m, cascades 0 to 4, distance m }`: the sun's map size (1024, 2048, 4096), its edge width in metres (0.07 when none is set), and cascades along the view (on by default past a 120 m map, to its diagonal) so distant walls keep the sun's shadow.
|
|
53
|
+
- `look.ssr` `{ enabled, distance m, thickness m, intensity }`: reflections of the world in polished and wet surfaces, high tier only. Off unless the brief has such surfaces.
|
|
54
|
+
- `look.gi` `{ kind: "probes", spacing m, box }`: bounced light, baked on load (DOCS.md: the box, what moves).
|
|
55
|
+
- `look.environment.intensity` (0 to 4): how much the sky lights the scene through reflections and fill. Default 1 under an HDRI or a physical sky (measured light), 0.4 under a painted one. Under those two the sky lights the shade itself: keep `lighting.ambient.intensity` near 0 (nw_check warns).
|
|
56
|
+
- `look.aa`: edge smoothing, technical (TRAA by default, FXAA on phones). Leave it.
|
|
57
|
+
- `bloom` `{ enabled, strength 0 to 3, radius 0 to 1, threshold 0 to 2 }`: only emissive surfaces glow. An emissiveIntensity above 1 blooms; the threshold keeps dim emissive from glowing. At threshold 0 everything emissive blooms in proportion to how bright it is.
|
|
58
|
+
- `fog` `{ color, near, far, mode, density, height, heightDensity }`: `range` (default: none at near, all at far, in metres), `exp2` (thickens with distance squared; density default 1.978 / far), `height` (range plus ground fog below `height` metres, `heightDensity` 0.01). `null` turns it off.
|
|
59
|
+
- `sky`: `gradient { top, bottom }`, `color`, `none` (the studio's glass, white on the planet: nw_check warns), `hdri { asset: "assets/x.hdr", top, bottom, intensity, rotation, blur, background, ground }` or `physical { turbidity, rayleigh }`. An HDRI both paints the sky and lights the scene; asset_import measures its top and bottom and look_apply fills them in. `ground { height }` lays its lower half on the ground (height: the camera's height when shot). nw_check measures the HDRI's sun and gives the `lighting.sun` direction and intensity (or the `rotation`) that match it. A physical sky is air lit by `lighting.sun` (turbidity 2 clear to 10 hazy), as bright as that sun; it publishes only to a player that offers `physical-sky` (oda check says).
|
|
60
|
+
|
|
61
|
+
Height fog thickens with depth below `height` AND with distance (the factor squares heightDensity x metres below x metres away), so small numbers go far. Fog on ground 2.3 m below the top:
|
|
62
|
+
|
|
63
|
+
| heightDensity | 5 m | 10 m | 20 m | 40 m | 80 m |
|
|
64
|
+
|---|---|---|---|---|---|
|
|
65
|
+
| 0.005 | 0.00 | 0.01 | 0.05 | 0.19 | 0.57 |
|
|
66
|
+
| 0.01 (default) | 0.01 | 0.05 | 0.19 | 0.57 | 0.97 |
|
|
67
|
+
| 0.08 | 0.57 | 0.97 | 1 | 1 | 1 |
|
|
68
|
+
|
|
69
|
+
Above 0.04 everything under the top is fog colour within a few metres; look_apply says so.
|
|
70
|
+
|
|
71
|
+
The sun and the sky fill are `lighting` (merged deep: `{ "sun": { "intensity": 4 } }` changes only that). A change to it restarts the running space (they are made at the start), so the next nw_view shows it.
|
|
72
|
+
|
|
73
|
+
## The drawing techniques (look.style)
|
|
74
|
+
|
|
75
|
+
From style.json's look, in this order; off when absent or null; sizes px at 1080 high:
|
|
76
|
+
- `paint { radius 1 to 6 }`: Kuwahara strokes; costly on the low tier.
|
|
77
|
+
- `bands { count 2 to 8, softness }`: flat steps of brightness, hue kept (cel).
|
|
78
|
+
- `hatch` and `halftone { amount, spacing, color, angle }`: strokes or dots that grow with the dark.
|
|
79
|
+
- `outline { width 0.5 to 8, color, depth, crease }`: lines at depth jumps and, with crease, at bends.
|
|
80
|
+
- `paper { amount, color, grain }` and `pixel { size 2 to 16 }`.
|
|
81
|
+
|
|
82
|
+
Shapes, materials and light must draw the same way too.
|
|
83
|
+
|
|
84
|
+
## Reading look_compare
|
|
85
|
+
|
|
86
|
+
- **palette deltaE** (CIEDE2000, share-weighted over the reference's colours): 6 or less matches, 10 or less is close, above that the main colours are different colours.
|
|
87
|
+
- **mean L\***: brightness, 0 to 100. A difference of 5 is visible, 10 is a different time of day. The suggestion converts it to exposure in EV.
|
|
88
|
+
- **contrast** (spread of L\*, as a ratio): above 1.15 the shot is harsher, below 0.85 flatter.
|
|
89
|
+
- **chroma** ratio: above 1 the shot is more colourful than the reference.
|
|
90
|
+
- **warmth b\*** and **tint a\***: positive warmth is yellower, positive tint more magenta.
|
|
91
|
+
- **clipped / crushed**: share of pure white and pure black pixels. Above 2% is lost detail.
|
|
92
|
+
- **thirds**: brightness of the top, middle and bottom of the frame. A dark top third and a bright bottom in the reference need a darker sky or a lighter ground, not exposure.
|
|
93
|
+
|
|
94
|
+
Numbers first, then words: what moved, by how much, after which knob, and what still differs ("palette <before> to <after> after <knob> <value>; the sky is still <n> L\* brighter than the reference").
|
|
95
|
+
|
|
96
|
+
## Tiers
|
|
97
|
+
|
|
98
|
+
The studio and the CLI always draw the **high** tier. A visitor's device picks its own: high (as in the studio), medium (4 cores or fewer: 2048 shadows, 3 cascades, 1.5 pixels, no reflections), low (phones and tablets: no AO, FXAA, no grain, 1024 shadows and no cascades, 256 probes at most, about 1.5 million pixels). `look.tiers.low` and `look.tiers.medium` can keep AO or grain on (`{ "ao": true }`) or drop bloom (`{ "bloom": false }`) for that tier. Judge the look at high; keep the mood carried by light, palette and fog, which every tier draws, rather than by AO or grain alone.
|
|
99
|
+
|
|
100
|
+
## What does not work here
|
|
101
|
+
|
|
102
|
+
- No EffectComposer, RenderPass, UnrealBloomPass or ShaderPass: the look is the post-processing. Do not build a second pipeline in the space's code.
|
|
103
|
+
- No tone mapping or exposure on a renderer in the space's code: it never has the renderer.
|
|
104
|
+
- The overview view never shows fog; judge mood from player and orbit views.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: playtesting
|
|
3
|
+
description: Walking an Oda space hands-free: nw_play scripts with valid goto, keys and look steps, expects read with nw_eval, reading the frames and the walk outcomes, and writing a bug with steps that reproduce it. Load before any walk-through.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Playtesting
|
|
7
|
+
|
|
8
|
+
A walk-through proves that what the creator asked for holds when a visitor walks the space: every place they named can be reached, what the visitor sees on the way is what the brief says, and nothing blocks, drops or breaks on the way. Code that compiles is not a space that can be walked; a picture that looks right from the overview is not a stair the visitor can climb.
|
|
9
|
+
|
|
10
|
+
## A script
|
|
11
|
+
|
|
12
|
+
One script tests one walk or one moment. It has:
|
|
13
|
+
- **steps**: the nw_play timeline (up to 60 s in all, up to 40 steps);
|
|
14
|
+
- **expects**: what must hold afterwards, each read from the running space with nw_eval.
|
|
15
|
+
|
|
16
|
+
nw_play starts the space fresh (the way a visitor arrives), runs the steps, and leaves the space in its end state, so the expects read the result of the run.
|
|
17
|
+
|
|
18
|
+
### Steps
|
|
19
|
+
|
|
20
|
+
Each step is one of:
|
|
21
|
+
- **Walk to a place**: `{ "goto": "<a placement id or kind in the space>", "seconds": 12 }`. goto takes a placement id or kind, a world kind, an object name (the nearest one, followed if it moves) or a point `[x, y, z]` in metres; never "player". `within` is how close counts as there (metres, default 0.5); `run: true` holds Shift. seconds is the most the walk may take: without it a walk gets 15 s, and up to 30 when the run's 60 s leave room. The visitor walks at 7 m/s unless config.player says otherwise, so 15 s is about 100 m.
|
|
22
|
+
- **Hold keys**: `{ "keys": ["KeyW", "ShiftLeft"], "seconds": 2 }`. KeyboardEvent.code names: KeyW, KeyA, KeyS, KeyD, Space, ShiftLeft, ArrowUp...
|
|
23
|
+
- **Turn**: `{ "keys": [], "seconds": 1, "look": { "yaw": 90, "pitch": 10 } }`: degrees to turn right and to look down over the step.
|
|
24
|
+
- **Act on arrival**: keys on a goto step are held on the way too, so press a key the space's code reads in its own step after the walk: `{ "keys": ["<the key the space's code reads>"], "seconds": 1 }`. Which key that is was decided for this space; read src/ for it. Most spaces read none beyond the walk.
|
|
25
|
+
|
|
26
|
+
A whole script for "the far end can be reached, and the visitor stands on it", in this space's own names:
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{ "steps": [{ "goto": "<a placement id or kind in the space>" }, { "keys": [], "seconds": 1, "look": { "yaw": 180, "pitch": 0 } }], "frames": 4, "watch": ["<the same id>"] }
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
with the expect `{ "code": "player[1]", "op": ">=", "value": <the floor's height there> }`.
|
|
33
|
+
|
|
34
|
+
### Expects
|
|
35
|
+
|
|
36
|
+
An expect is a JavaScript expression nw_eval runs in the space, an op and a value:
|
|
37
|
+
- `==` (equal, deep for arrays and objects), `>=`, `<=`, `between` (value is `[lo, hi]`), `truthy` (no value).
|
|
38
|
+
- In scope: `game`, `world`, `root`, `scene`, `camera`, `renderer`, `THREE`, `SDK`, `placed`, `player` (its position) and `pilot`.
|
|
39
|
+
- Good expects read where the visitor is and what the space holds: `player[1] > 0` (did not fall through), `player` near the point the walk aimed at, `world.find('<id>')[0].object.position.y`, `placed.filter(p => p.kind === '<kind>').length`, and `world.state.<the space's own value>` when its code keeps one.
|
|
40
|
+
- Read the value once with nw_eval before you write the expect, so the name exists and the number is the right kind.
|
|
41
|
+
|
|
42
|
+
## Running and reading
|
|
43
|
+
|
|
44
|
+
1. nw_play the steps. Read the reply: `goto` says how each walk went:
|
|
45
|
+
- `reached`: the player got there;
|
|
46
|
+
- `gone`: a rule removed the target on the way;
|
|
47
|
+
- `timeout`: still walking when the time ran out (too far for the time it had, or circling). Not a blocked way: give the step more seconds (up to 30), `run: true`, or a nearer goto first;
|
|
48
|
+
- `blocked`: something stopped the player (a wall, a gap, a slope too steep). A place the creator named that cannot be reached is a bug in itself.
|
|
49
|
+
2. Look at the frames: they are from the player's eyes, in time order. Does what the visitor sees match the brief and its hero views (the light, the scale against the 1.75 m visitor, what is in view)?
|
|
50
|
+
3. `start` and `end` give the player's position, the status line and world.state before and after; `errors` lists runtime errors during the run; `fps` its smoothness.
|
|
51
|
+
4. Run each expect with nw_eval and compare with its op and value.
|
|
52
|
+
5. nw_logs (level warn) for errors and asset problems during the run.
|
|
53
|
+
|
|
54
|
+
A script passes when every walk that should arrive is `reached`, every expect holds, and no runtime error appeared.
|
|
55
|
+
|
|
56
|
+
## What to test
|
|
57
|
+
|
|
58
|
+
- Every place the creator or the brief names (a doorway, a stair, the far end of a room, a lookout): walk there from the spawn, and look from there.
|
|
59
|
+
- The scale on the way: doors, steps and ceilings against the 1.75 m visitor, and the walk speed against the size of the space (config.player).
|
|
60
|
+
- The edges: walking off the map's edge, falling (`player[1]` far below the ground), getting stuck in a corner or on a step.
|
|
61
|
+
- Smoothness: an fps average far under the others' or a long frame during one step names the step that is heavy.
|
|
62
|
+
- On the WebGL 2 fallback (a preview without WebGPU) every shader is built while its frame waits: a large space's frames held for seconds, or a run that ran out of time, are its shaders being built, not its speed. Judge smoothness on WebGPU.
|
|
63
|
+
|
|
64
|
+
## A bug
|
|
65
|
+
|
|
66
|
+
- **title**: what is wrong, in one line ("the stair to the gallery cannot be climbed").
|
|
67
|
+
- **repro**: the exact nw_play input and the expect that failed, so anyone can run it again.
|
|
68
|
+
- **expected** and **actual**: from the brief's words and from what the run showed (numbers, walk outcomes, the frame that shows it).
|
|
69
|
+
- **severity**: blocker (the space cannot be walked: it throws, the player falls through the world, a place the creator named cannot be reached), major (a view or a place the brief names is wrong), minor (anything else).
|
|
70
|
+
- **owner**: builder (layout, colliders, state, integration), artist (the look, a material drawn black), modeller (an asset's size, shape or materials), sound (a sound that does not play or clips).
|
|
71
|
+
- **files**: the ones you suspect, from reading the source (src/world/ for layout, src/game/ for rules).
|
|
72
|
+
- **script**: the id of the script that shows it. Its fix is judged by walking that script again, so the script's expect must be what holds once the bug is gone.
|
|
73
|
+
|
|
74
|
+
Never put a probe in the source: read the space with nw_eval. As the builder, fix what the walk found and run the same script again until it passes. As a helper, report it with the script that shows it.
|