oda-engine 0.0.0-stage → 0.1.1

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.
Files changed (204) hide show
  1. package/README.md +151 -2
  2. package/bin/nowhere.mjs +352 -0
  3. package/lib/account.mjs +57 -0
  4. package/lib/agentModules.mjs +57 -0
  5. package/lib/devServer.mjs +351 -0
  6. package/lib/headless.mjs +231 -0
  7. package/lib/headlessPreview.mjs +212 -0
  8. package/lib/keys.mjs +517 -0
  9. package/lib/make.mjs +855 -0
  10. package/lib/mcp.mjs +537 -0
  11. package/lib/open.mjs +22 -0
  12. package/lib/preview.mjs +87 -0
  13. package/lib/previewRpc.mjs +134 -0
  14. package/lib/project.mjs +359 -0
  15. package/lib/publishFlow.mjs +131 -0
  16. package/lib/resources.mjs +50 -0
  17. package/lib/rules.mjs +60 -0
  18. package/lib/scaffold.mjs +42 -0
  19. package/lib/setup.mjs +59 -0
  20. package/lib/tools.mjs +668 -0
  21. package/package.json +51 -4
  22. package/template/game.config.json +9 -0
  23. package/template/scene.json +4 -0
  24. package/template/src/main.ts +11 -0
  25. package/vendor/DOCS.md +447 -0
  26. package/vendor/agent/appRun.mjs +520 -0
  27. package/vendor/agent/assets/brief.mjs +242 -0
  28. package/vendor/agent/assets/collider.mjs +531 -0
  29. package/vendor/agent/assets/environments/index.mjs +12 -0
  30. package/vendor/agent/assets/environments/worldlabs.mjs +161 -0
  31. package/vendor/agent/assets/fetch.mjs +168 -0
  32. package/vendor/agent/assets/footprint.mjs +13 -0
  33. package/vendor/agent/assets/gltf.mjs +547 -0
  34. package/vendor/agent/assets/hdr.mjs +269 -0
  35. package/vendor/agent/assets/imageOps.mjs +171 -0
  36. package/vendor/agent/assets/images/codex.mjs +307 -0
  37. package/vendor/agent/assets/images/fal.mjs +75 -0
  38. package/vendor/agent/assets/images/gemini.mjs +84 -0
  39. package/vendor/agent/assets/images/index.mjs +25 -0
  40. package/vendor/agent/assets/images/openai.mjs +75 -0
  41. package/vendor/agent/assets/images/stability.mjs +71 -0
  42. package/vendor/agent/assets/images/views.mjs +31 -0
  43. package/vendor/agent/assets/import.mjs +1352 -0
  44. package/vendor/agent/assets/inspect.mjs +465 -0
  45. package/vendor/agent/assets/jobs.mjs +196 -0
  46. package/vendor/agent/assets/ktx2.mjs +290 -0
  47. package/vendor/agent/assets/ledger.mjs +466 -0
  48. package/vendor/agent/assets/net.mjs +254 -0
  49. package/vendor/agent/assets/prices.json +39 -0
  50. package/vendor/agent/assets/providers/fal.mjs +115 -0
  51. package/vendor/agent/assets/providers/index.mjs +22 -0
  52. package/vendor/agent/assets/providers/meshy.mjs +119 -0
  53. package/vendor/agent/assets/providers/tripo.mjs +188 -0
  54. package/vendor/agent/assets/sources/ambientcg.mjs +129 -0
  55. package/vendor/agent/assets/sources/index.mjs +23 -0
  56. package/vendor/agent/assets/sources/polyhaven.mjs +237 -0
  57. package/vendor/agent/assets/sources/polypizza.mjs +121 -0
  58. package/vendor/agent/assets/splat.mjs +631 -0
  59. package/vendor/agent/assets/targets.mjs +122 -0
  60. package/vendor/agent/assets/tile.mjs +261 -0
  61. package/vendor/agent/assets/unzip.mjs +180 -0
  62. package/vendor/agent/blender/cleanup.py +360 -0
  63. package/vendor/agent/blender/convert.py +167 -0
  64. package/vendor/agent/blender/find.mjs +192 -0
  65. package/vendor/agent/blender/nw_export.py +104 -0
  66. package/vendor/agent/blender/nw_rubric.py +426 -0
  67. package/vendor/agent/blender/run.mjs +193 -0
  68. package/vendor/agent/blender/runner.py +252 -0
  69. package/vendor/agent/blender/sheet.py +743 -0
  70. package/vendor/agent/depth.mjs +134 -0
  71. package/vendor/agent/director/board.mjs +451 -0
  72. package/vendor/agent/director/contracts.mjs +663 -0
  73. package/vendor/agent/director/director.mjs +2365 -0
  74. package/vendor/agent/director/estimate.mjs +200 -0
  75. package/vendor/agent/director/gate.mjs +802 -0
  76. package/vendor/agent/director/limits.json +16 -0
  77. package/vendor/agent/director/methods.mjs +457 -0
  78. package/vendor/agent/director/policy.json +33 -0
  79. package/vendor/agent/director/prompts.mjs +244 -0
  80. package/vendor/agent/director/reading.mjs +341 -0
  81. package/vendor/agent/director/router.mjs +184 -0
  82. package/vendor/agent/director/seams.mjs +243 -0
  83. package/vendor/agent/director/session.mjs +643 -0
  84. package/vendor/agent/director/store.mjs +119 -0
  85. package/vendor/agent/director/taskGate.mjs +110 -0
  86. package/vendor/agent/director/teamLedger.mjs +118 -0
  87. package/vendor/agent/director/triage.mjs +63 -0
  88. package/vendor/agent/downloads.cjs +363 -0
  89. package/vendor/agent/flow.mjs +78 -0
  90. package/vendor/agent/guard.mjs +613 -0
  91. package/vendor/agent/host.mjs +1736 -0
  92. package/vendor/agent/language.mjs +58 -0
  93. package/vendor/agent/ledger.mjs +360 -0
  94. package/vendor/agent/locale.cjs +186 -0
  95. package/vendor/agent/loop/capacity.mjs +74 -0
  96. package/vendor/agent/loop/compose.mjs +127 -0
  97. package/vendor/agent/loop/gate.mjs +205 -0
  98. package/vendor/agent/loop/judge.mjs +189 -0
  99. package/vendor/agent/loop/levels.mjs +273 -0
  100. package/vendor/agent/loop/state.mjs +358 -0
  101. package/vendor/agent/notes.cjs +278 -0
  102. package/vendor/agent/pace.mjs +258 -0
  103. package/vendor/agent/panels.mjs +431 -0
  104. package/vendor/agent/prompt.mjs +342 -0
  105. package/vendor/agent/reference/board.mjs +410 -0
  106. package/vendor/agent/reference/compose.mjs +364 -0
  107. package/vendor/agent/reference/decode.mjs +56 -0
  108. package/vendor/agent/reference/facts.mjs +1874 -0
  109. package/vendor/agent/reference/png.mjs +107 -0
  110. package/vendor/agent/reference/records.mjs +63 -0
  111. package/vendor/agent/reference/web.mjs +252 -0
  112. package/vendor/agent/roles/artist.mjs +69 -0
  113. package/vendor/agent/roles/builder.mjs +79 -0
  114. package/vendor/agent/roles/checks.mjs +223 -0
  115. package/vendor/agent/roles/common.mjs +188 -0
  116. package/vendor/agent/roles/critic.mjs +171 -0
  117. package/vendor/agent/roles/index.mjs +39 -0
  118. package/vendor/agent/roles/modeller.mjs +142 -0
  119. package/vendor/agent/roles/qa.mjs +58 -0
  120. package/vendor/agent/roles/rubrics.mjs +79 -0
  121. package/vendor/agent/roles/sound.mjs +69 -0
  122. package/vendor/agent/rounds.cjs +333 -0
  123. package/vendor/agent/shared.mjs +284 -0
  124. package/vendor/agent/stopGate.mjs +574 -0
  125. package/vendor/agent/subagents.mjs +129 -0
  126. package/vendor/agent/tools/assets.mjs +499 -0
  127. package/vendor/agent/tools/blender.mjs +754 -0
  128. package/vendor/agent/tools/cards.mjs +479 -0
  129. package/vendor/agent/tools/choices.mjs +479 -0
  130. package/vendor/agent/tools/compose.mjs +74 -0
  131. package/vendor/agent/tools/environment.mjs +488 -0
  132. package/vendor/agent/tools/eyes.mjs +733 -0
  133. package/vendor/agent/tools/generate.mjs +338 -0
  134. package/vendor/agent/tools/guide.mjs +46 -0
  135. package/vendor/agent/tools/harness.mjs +193 -0
  136. package/vendor/agent/tools/image.mjs +643 -0
  137. package/vendor/agent/tools/index.mjs +162 -0
  138. package/vendor/agent/tools/look.mjs +578 -0
  139. package/vendor/agent/tools/loop.mjs +858 -0
  140. package/vendor/agent/tools/others.mjs +123 -0
  141. package/vendor/agent/tools/pictures.mjs +535 -0
  142. package/vendor/agent/tools/reference.mjs +366 -0
  143. package/vendor/agent/transcripts.mjs +118 -0
  144. package/vendor/agent-loop.mjs +602 -0
  145. package/vendor/agent-plugin/.claude-plugin/plugin.json +5 -0
  146. package/vendor/agent-plugin/skills/art-direction/SKILL.md +82 -0
  147. package/vendor/agent-plugin/skills/asset-legality/SKILL.md +101 -0
  148. package/vendor/agent-plugin/skills/asset-sources/SKILL.md +111 -0
  149. package/vendor/agent-plugin/skills/blender-modeling/SKILL.md +97 -0
  150. package/vendor/agent-plugin/skills/look-dev/SKILL.md +104 -0
  151. package/vendor/agent-plugin/skills/playtesting/SKILL.md +74 -0
  152. package/vendor/agent-plugin/skills/reference-loop/SKILL.md +102 -0
  153. package/vendor/agent-plugin/skills/sound-design/SKILL.md +60 -0
  154. package/vendor/agent-plugin/skills/style/SKILL.md +35 -0
  155. package/vendor/agent-plugin/skills/tsl-r185/SKILL.md +107 -0
  156. package/vendor/auth.cjs +570 -0
  157. package/vendor/build.cjs +953 -0
  158. package/vendor/catalog.json +455 -0
  159. package/vendor/connectors.cjs +688 -0
  160. package/vendor/eyes.mjs +733 -0
  161. package/vendor/gameExports.json +1390 -0
  162. package/vendor/git.cjs +222 -0
  163. package/vendor/models.json +57 -0
  164. package/vendor/publish.cjs +1018 -0
  165. package/vendor/refBoard.cjs +301 -0
  166. package/vendor/schema/dist/assets.d.ts +335 -0
  167. package/vendor/schema/dist/assets.js +439 -0
  168. package/vendor/schema/dist/brief.d.ts +357 -0
  169. package/vendor/schema/dist/brief.js +302 -0
  170. package/vendor/schema/dist/common.d.ts +9 -0
  171. package/vendor/schema/dist/common.js +13 -0
  172. package/vendor/schema/dist/config.d.ts +406 -0
  173. package/vendor/schema/dist/config.js +355 -0
  174. package/vendor/schema/dist/contract.d.ts +599 -0
  175. package/vendor/schema/dist/contract.js +1146 -0
  176. package/vendor/schema/dist/index.d.ts +14 -0
  177. package/vendor/schema/dist/index.js +21 -0
  178. package/vendor/schema/dist/look.d.ts +463 -0
  179. package/vendor/schema/dist/look.js +681 -0
  180. package/vendor/schema/dist/lookStats.d.ts +230 -0
  181. package/vendor/schema/dist/lookStats.js +768 -0
  182. package/vendor/schema/dist/pilot.d.ts +32 -0
  183. package/vendor/schema/dist/pilot.js +44 -0
  184. package/vendor/schema/dist/publish.d.ts +214 -0
  185. package/vendor/schema/dist/publish.js +291 -0
  186. package/vendor/schema/dist/scene.d.ts +75 -0
  187. package/vendor/schema/dist/scene.js +120 -0
  188. package/vendor/schema/dist/skyLight.d.ts +141 -0
  189. package/vendor/schema/dist/skyLight.js +436 -0
  190. package/vendor/schema/dist/style.d.ts +131 -0
  191. package/vendor/schema/dist/style.js +155 -0
  192. package/vendor/schema/package.json +1 -0
  193. package/vendor/selectionPrompt.mjs +51 -0
  194. package/vendor/useTools.mjs +195 -0
  195. package/vendor/userMessage.mjs +26 -0
  196. package/web-dist/assets/GaussianSplatUtils-CptQkDVX.js +1 -0
  197. package/web-dist/assets/KTX2Loader-C53LJqss.js +2 -0
  198. package/web-dist/assets/SPZLoader-BQ3tjaTv.js +1 -0
  199. package/web-dist/assets/gaussianSplat-_9tcWegB.js +1 -0
  200. package/web-dist/assets/index-Baka-ZO7.js +693 -0
  201. package/web-dist/assets/index-CcjyyQco.css +1 -0
  202. package/web-dist/assets/meshopt_decoder.module-BvwdjiD3.js +1 -0
  203. package/web-dist/assets/zstddec.module-CfFeQW7d.js +1 -0
  204. package/web-dist/index.html +34 -0
package/package.json CHANGED
@@ -1,6 +1,53 @@
1
1
  {
2
2
  "name": "oda-engine",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Make Oda games from your own tools: a CLI and an MCP server for Claude Code, Codex and any other agent, with a live preview in the browser and publishing to the Oda universe.",
5
+ "type": "module",
6
+ "bin": {
7
+ "oda": "bin/nowhere.mjs"
8
+ },
9
+ "files": [
10
+ "bin",
11
+ "lib",
12
+ "vendor",
13
+ "web-dist",
14
+ "template",
15
+ "README.md"
16
+ ],
17
+ "engines": {
18
+ "node": ">=20"
19
+ },
20
+ "scripts": {
21
+ "build": "node scripts/build.mjs",
22
+ "prepublishOnly": "node scripts/build.mjs"
23
+ },
24
+ "dependencies": {
25
+ "@gltf-transform/core": "4.5.1",
26
+ "@gltf-transform/extensions": "4.5.1",
27
+ "@gltf-transform/functions": "4.5.1",
28
+ "@modelcontextprotocol/sdk": "^1.30.0",
29
+ "@supabase/supabase-js": "^2.115.0",
30
+ "esbuild": "^0.28.2",
31
+ "fflate": "0.8.3",
32
+ "gltf-validator": "2.0.0-dev.3.10",
33
+ "isomorphic-git": "^1.41.9",
34
+ "ktx2-encoder": "0.6.0",
35
+ "meshoptimizer": "1.1.1",
36
+ "zod": "^4.4.3"
37
+ },
38
+ "optionalDependencies": {
39
+ "@anthropic-ai/claude-agent-sdk": "0.3.290"
40
+ },
41
+ "license": "MIT",
42
+ "author": "Oda",
43
+ "homepage": "https://nowhere-studio.vercel.app",
44
+ "keywords": [
45
+ "oda",
46
+ "game",
47
+ "three.js",
48
+ "webgpu",
49
+ "mcp",
50
+ "claude",
51
+ "codex"
52
+ ]
53
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "schema": "nowhere/config@1",
3
+ "id": "untitled-game",
4
+ "title": "Untitled Game",
5
+ "sky": { "kind": "none" },
6
+ "fog": null,
7
+ "lighting": { "ambient": {} },
8
+ "look": {}
9
+ }
@@ -0,0 +1,4 @@
1
+ {
2
+ "schema": "nowhere/scene@1",
3
+ "objects": []
4
+ }
@@ -0,0 +1,11 @@
1
+ import { World, type GameContext, type GameHandle } from '@nowhere/sdk'
2
+
3
+ // Your game. Describe what you want in the studio chat and the agent builds it
4
+ // here; this file is real code and everything in it is yours to change.
5
+
6
+ export function createGame(ctx: GameContext): GameHandle {
7
+ const world = new World(ctx)
8
+
9
+ return world.finish()
10
+ }
11
+
package/vendor/DOCS.md ADDED
@@ -0,0 +1,447 @@
1
+ # @nowhere/sdk guide
2
+
3
+ A space is code. The only hard contract:
4
+
5
+ ```ts
6
+ import type { GameContext, GameHandle } from '@nowhere/sdk'
7
+ export function createGame(ctx: GameContext): GameHandle
8
+ // GameHandle = { root: THREE.Group, update(dt): void, dispose(): void, ... }
9
+ ```
10
+
11
+ `ctx.config` is the parsed game.config.json. `ctx.input.pressed('KeyW')` is the
12
+ keyboard (only source of input allowed). `ctx.assets` loads the project's own
13
+ files (see Files in code). Never run your own render loop; put all motion in
14
+ update(dt). The host paints sky, fog and ground, finishes the picture (see The
15
+ look) and shows the creator's placed objects (see below); your code makes the
16
+ rest, with materials and models made for this space's brief, not bare boxes.
17
+
18
+ ## World (the fast path)
19
+
20
+ ```ts
21
+ import * as THREE from 'three'
22
+ import { World, type GameContext } from '@nowhere/sdk'
23
+
24
+ // The API, not a game: every name, count, size, position and rule here is
25
+ // a placeholder for this game's own, from the brief and its layout.
26
+ const KIND = '<kind>' // the brief's name for the thing
27
+ const COUNT = 0, SIZE_M = 1 // the brief's count and size (m)
28
+ const POSITIONS: [number, number, number][] = [] // <positions from the layout>
29
+ const COUNTER = '<the game\'s own counter>'
30
+
31
+ export function createGame(ctx: GameContext) {
32
+ const world = new World(ctx) // adds config lighting automatically
33
+
34
+ // Objects: add(id, object3d, opts). Same id groups instances in the panel.
35
+ // One node material for all (see Materials): its colour, roughness, glow
36
+ // and the geometry's form are what the brief says the thing is.
37
+ const geo = new THREE.BoxGeometry(SIZE_M, SIZE_M, SIZE_M)
38
+ const mat = new THREE.MeshStandardNodeMaterial({ name: KIND })
39
+ for (const position of POSITIONS.slice(0, COUNT)) world.add(KIND, new THREE.Mesh(geo, mat), { position })
40
+ // A real model (asset_import or nw_blender made it at its real size), loaded in code.
41
+ world.add('<model id>', ctx.assets!.model('assets/<model>.glb'),
42
+ { position: [0, 0, 0], solid: true }) // solid: blocks + can stand on
43
+
44
+ // Player: WASD/arrows + Space jump, gravity, collides with ground/solids/edge.
45
+ // No options: config.player carries the brief's walk speed and eye height,
46
+ // where the creator can tune them; an option here only forces one in code.
47
+ world.spawnPlayer()
48
+
49
+ // State + rules. onTouch fires when the player touches a live instance;
50
+ // what it does is the brief's rule (here: removed and counted).
51
+ world.state[COUNTER] = 0
52
+ world.onTouch(KIND, (thing, w) => {
53
+ w.remove(thing)
54
+ w.state[COUNTER] = (w.state[COUNTER] as number) + 1
55
+ }, '<the rule, in the brief\'s words>')
56
+
57
+ // Per-frame logic. desc makes it show in the Rules panel.
58
+ world.onUpdate((dt, w) => {
59
+ for (const thing of w.find(KIND)) thing.object.rotation.y += dt * 0 // <what the brief has it do each frame>
60
+ }, '<what it does each frame>')
61
+
62
+ return world.finish() // ALWAYS return this
63
+ }
64
+ ```
65
+
66
+ Useful bits: `world.time` (seconds), A world has no edge and no size limit: place
67
+ things wherever the place needs them, around the origin. (`world.halfSize` and
68
+ `tiles` belong to planets made before this; on those, the map is a square at the
69
+ origin.) `world.find(id)`, `world.remove(inst)`,
70
+ `world.placed(kind?)` (the creator's placed objects), `world.root` (add raw
71
+ three objects yourself). Tiles are UNITLESS: never speak in metres.
72
+
73
+ Everything the world hands you is an `Instance`: `{ id, object, solid, alive, owned,
74
+ placement?, asset? }`. `world.add()`, `world.find()`, `world.placed()`, `onTouch`'s
75
+ argument and the player all share that one shape, so `inst.object` is always the
76
+ three.js object. `owned` is true for what your code added and false for the
77
+ creator's placed objects (see below), whose `placement` is their id in scene.json
78
+ and `asset` the model they show.
79
+
80
+ Reading keys inside a rule: `world.input.pressed('Space')`, the same input
81
+ object createGame was handed. There is no key-down event, only "held now", so
82
+ edge detection is yours to keep (remember last frame's value).
83
+
84
+ A rule that throws loses that one call, and the rest of the game runs on; the
85
+ studio shows the error with the file and line. One that throws 3 calls in a
86
+ row (or 5 times in 2 s) is switched off for the rest of the run, which the
87
+ studio says too. A throw from your own `update()` or `camera()` outside World
88
+ is skipped the same way, but if it keeps throwing the game stops and Play says
89
+ why. Code that loops forever cannot be stopped: it freezes the studio.
90
+
91
+ Every world gets a player whether you ask for one or not: if `createGame`
92
+ returns without calling `spawnPlayer`, `finish()` spawns the default. Somewhere
93
+ you can stand is the baseline, not a feature. Call `spawnPlayer` yourself only
94
+ to choose where they start, how fast they move, or what they look like.
95
+
96
+ Play is THIRD PERSON. The player is the Oda pilot on foot, the figure the
97
+ Oda world flies, and it walks, runs and jumps with its own animation as it
98
+ moves: nothing to load or wire up. The camera rides behind and a little above
99
+ its head at a fixed 5.4 m from the view target. Walls, climbing surfaces and
100
+ height changes never shorten the camera arm or rotate it automatically. The
101
+ mouse orbits it (the studio captures the pointer on Play,
102
+ Escape gives it back). W is the way the CAMERA looks, not a world axis, and the
103
+ figure turns to face wherever it walks; `spawnPlayer` handles all of it. The
104
+ figure is about 1.75 tall with its soles on the ground; for collisions it is
105
+ still the 0.8 by 1.6 box the capsule was.
106
+
107
+ `spawnPlayer({ view: 'first' })` puts the camera in the head instead (a
108
+ first-person game; the body is then a plain capsule nobody sees), and
109
+ `spawnPlayer({ figure: false })` keeps the capsule in third person. `color`
110
+ lights the strips on the figure's pack. `world.input.look()` is the raw
111
+ per-frame turn in radians if you want it, but reading it consumes it, so leave
112
+ it alone unless the player is yours rather than World's.
113
+
114
+ Light is done for you. World lights every game from game.config.json: the sun
115
+ (a soft-edged shadow, sharp enough to read and never razor-cut) and the sky's
116
+ own light, blue from above and the ground's colour from below. The host adds
117
+ the sky as an environment, so glossy and metal materials reflect it, and
118
+ ambient occlusion where things meet the ground. Everything you `world.add`, and
119
+ anything else under `world.root`, casts and receives shadows automatically; a
120
+ mesh that should not cast one sets `mesh.userData.shadow = false`. See-through
121
+ materials (opacity below 0.6) receive but do not cast. An imported model keeps
122
+ its own materials; every other material's colour, roughness and metalness come
123
+ from the brief's materials, written for this game (see Materials). Do not add
124
+ your own ambient or directional light to fix a dark scene: change the config's
125
+ lighting and the look from the brief's numbers (see The look).
126
+
127
+ The player: `world.spawnPlayer(opts)` returns its Instance, `world.player` is
128
+ that same Instance (or null before it is spawned), and `world.movePlayer([x, y,
129
+ z])` teleports it AND stops its fall. Movement is WASD at a fast 7 m/s,
130
+ Shift to run at twice that, Space to jump, all of it built in (the player block
131
+ below sets the scale). Use movePlayer to respawn or reset: writing
132
+ `player.object.position` directly leaves gravity mid-swing.
133
+ There is no velocity field to write.
134
+
135
+ Climbing and water. World's player climbs: walking into the side of any
136
+ solid and pushing on for a moment takes hold of it (W and S go up and down
137
+ it, A and D across, it stands up on top, Space springs off). A solid that
138
+ should be a wall to walk round, not up (a lighthouse, a cliff at the edge of
139
+ the level), takes `climb: false`:
140
+
141
+ ```ts
142
+ world.add('lighthouse', tower, { solid: true, climb: false })
143
+ ```
144
+
145
+ The config's flat ground plate is a floor across the whole map, and so is
146
+ anything solid: a sea painted by the plate, or by a mesh of your own, is
147
+ walked on like dry land. Water the player must not walk on is marked
148
+ `water: true`. Lay its surface where the water is, at or a little above the
149
+ ground under it; the land around it is the plate where no water is laid, or
150
+ solid meshes that rise above the water's surface. The player cannot step onto
151
+ it: its shore stops them like a wall that is never climbed, a jump does not
152
+ carry them out over it, and a player put down in it (movePlayer, a fall) goes
153
+ back to the last dry ground they stood on. Water is never solid.
154
+
155
+ ```ts
156
+ // An island on a sea: the sea runs past the view, the island stands above it.
157
+ const sea = new THREE.Mesh(new THREE.PlaneGeometry(4000, 4000), seaMat)
158
+ sea.rotation.x = -Math.PI / 2
159
+ world.add('sea', sea, { position: [0, 0.02, 0], water: true })
160
+ world.add('island', islandMesh, { solid: true }) // its beach rises out of the water
161
+ ```
162
+
163
+ Coming in and going out are the host's. On an Oda planet the visitor
164
+ arrives from the universe in one continuous shot: World's player starts high
165
+ above its spawn, already falling at the speed the visitor dived in with, and
166
+ lands; the figure falls in prone, in the pilot's own flying pose, and swings
167
+ its feet under it just before the ground. When they leave, the host carries the body
168
+ up and out: while it does, nothing in the game moves the player, the keys do
169
+ nothing and no touch rule fires; your updaters keep running. All of this comes
170
+ in `ctx.arrival` and `ctx.departure`, which only the host sets: never set them,
171
+ never read them, and never move the player because of them. Let the player
172
+ fall in from where it spawns: a game that moves it in its first update
173
+ (`movePlayer` to a start of its own) drags the visitor's view with it, so
174
+ choose the start with `spawnPlayer({ position })` or the config spawn instead.
175
+ `GameHandle.visitorBody()` is how the host learns what the player looks like
176
+ (figure or capsule, its height, skin and trim) to draw the same body on its
177
+ side; `finish()` provides it, and a hand-written game need not. In the studio
178
+ there is no arrival and no departure: Play starts on the spawn, as always.
179
+
180
+ Other visitors on a published planet appear on their own: up to 30 per room see
181
+ each other move, with a generated name overhead, drawn by the SDK from
182
+ `visitorBody()`. Your code cannot list, touch or collide with them. A planet meant
183
+ to be played alone returns `{ ...world.finish(), rooms: false }`. A game with no
184
+ World player shows nobody. `createPeerLayer` is for hosts, not games.
185
+
186
+ You may bypass World entirely with raw three.js as long as you honour the
187
+ contract. Registered ids/rules are what the studio's Objects/Rules panels show,
188
+ so prefer World for things the creator should see listed.
189
+
190
+ ## The look
191
+
192
+ The finish of the picture is data in game.config.json: `sky` (a colour, a
193
+ gradient, an HDRI from asset_import, laid on the ground with `ground`, or a
194
+ `physical` sky lit by `lighting.sun`; each lights every material, and the last
195
+ two light the shade at their own strength, so keep `lighting.ambient` near 0
196
+ under them), `fog`, `lighting`, `bloom` and the `look` block (tone mapping,
197
+ exposure, grade, a LUT, AO, shadows in cascades, reflections, probe GI,
198
+ vignette, grain; edges smoothed by TRAA). The studio, the CLI preview and the
199
+ planet's player page draw it through one pipeline, the SDK's createLook, so
200
+ what you see is what a visitor sees (a phone drops AO and grain). Set it with
201
+ `look_apply` from the brief (no stock mood); nw_check names what is left to the
202
+ defaults. Judge with `nw_view`, `look_compare` and `nw_compare`. Never add an
203
+ EffectComposer, a bloom pass or a tone curve of your own: the look has them.
204
+ Probe GI (`look.gi`) bakes the light round the shade once the space stands
205
+ still. Draw its `box` round the open air, its faces on a room's walls: past it
206
+ the sky lights things as without probes. Placed models (scene.json) are baked
207
+ too; mark what moves `userData.gi = false`. A probe in rock darkens what is
208
+ near it, a wall in the box thinner than `spacing` leaks light, and a shot taken
209
+ mid-bake finishes it at once (about 10 s for 1700 probes).
210
+
211
+ ## Materials (TSL)
212
+
213
+ The renderer is three r186's WebGPURenderer: materials are node materials and
214
+ shaders are TSL (`three/tsl`). The SDK has no ready-made materials: write each
215
+ shader for this game's brief, in its own module, from the node slots of a
216
+ `Mesh*NodeMaterial` (`colorNode`, `emissiveNode`, `roughnessNode`,
217
+ `normalNode`, `positionNode`, `opacityNode`). The nowhere:tsl-r185 guide has
218
+ the facts: which names r186 exports, the slots and their inputs, and what the
219
+ studio reports when a material fails. Share one material between every mesh
220
+ that looks the same, and change a `uniform(...)`'s `.value` in an updater
221
+ rather than building a new graph (that never recompiles).
222
+
223
+ What does nothing on WebGPU, and the way that works:
224
+
225
+ | Habit | Instead |
226
+ |---|---|
227
+ | `material.onBeforeCompile` | the node slots of a `Mesh*NodeMaterial` (`colorNode`, `normalNode`, `positionNode`, `emissiveNode`, `roughnessNode`, `opacityNode`) |
228
+ | `ShaderMaterial`, `RawShaderMaterial` | `MeshBasicNodeMaterial` with `colorNode`, or `NodeMaterial` with `fragmentNode` / `vertexNode` |
229
+ | `ShaderChunk`, `#include <...>`, `gl_FragColor`, `EffectComposer` | TSL nodes (`Fn`, `vec3`, `mix`); the look (`look_apply`) for post |
230
+
231
+ A TSL graph that throws while it builds is drawn flat black. The host names
232
+ it: nw_check fails with the material, its mesh and your line
233
+ (`src/water.ts:42`), nw_status lists it under `materials`, nw_logs has it as
234
+ source `shader`; the build warns about each habit above at its `file:line`.
235
+
236
+ ## Files in code
237
+
238
+ `ctx.assets` is the planet's own files under `assets/`, as every host serves
239
+ them (the studio, the CLI preview and the planet). Each call returns at once
240
+ and fills in when the file has loaded, so build the whole scene in createGame:
241
+
242
+ ```ts
243
+ const a = ctx.assets!
244
+ const rock = new THREE.MeshStandardNodeMaterial({
245
+ map: a.texture('assets/rock_color.jpg', { repeat: [4, 4] }), // colour: sRGB
246
+ normalMap: a.texture('assets/rock_normal.jpg', { color: false, repeat: [4, 4] }), // data
247
+ })
248
+ world.add('barrel', a.model('assets/barrel.glb'), { position: [3, 0, -2], solid: true })
249
+ const surf = a.sound('assets/waves.ogg', { loop: true, volume: 0.5 }); surf.play()
250
+ world.add('room', a.splat('assets/room.spz', { collider: 'assets/room_collider.glb', light: true }), { solid: true, climb: false })
251
+ ```
252
+
253
+ Also `hdri(path)`, `bytes(path)`, `ready()` and `problems()` (what failed); a
254
+ sound starts after the visitor's first key or click. `splat` draws a splat
255
+ environment (a scan, or a world from `environment_generate`) under the config's
256
+ ground `{ "kind": "none" }`: its collider is solid and drawn by nothing,
257
+ `light` a LightProbe measured from the splat, and where its floor ends the
258
+ walker is held (`edges: 'open'` lets it fall); nowhere:asset-sources has more.
259
+ For mesh props in that space, wait for `await a.ready()`, then use
260
+ `world.groundObject(prop)` to put the prop's lowest point on the collider.
261
+ `world.moveBody(prop, [vx * dt, vy * dt, vz * dt])` moves an upright capsule
262
+ proxy against all solid meshes, including the hidden environment collider.
263
+ Apply gravity to `vy` and reset it when the result's `grounded` is true.
264
+ `waiting` means a collider is still loading; keep the prop in place then.
265
+ This foundation does not simulate torque or rigid-body stacking. The Gaussian
266
+ visual is static; collision is calculated against its aligned mesh.
267
+
268
+ A file is published with the planet when assets.lock.json records it, which
269
+ asset_import does (CC0, and CC BY with the credit line the planet's page
270
+ shows). A `.ktx2` texture is stored bottom row first, so it draws on the same
271
+ UVs as the PNG it replaces; `flipY` does nothing to it.
272
+
273
+ ## Where models come from
274
+
275
+ Best first: what the project has (asset_ledger); a CC0 library
276
+ (`asset_search`, `asset_fetch`, `asset_import`: Poly Haven, ambientCG, Kenney
277
+ through Poly Pizza); a model you build in Blender with a bpy script written
278
+ for it (`nw_blender`, which scores silhouette, bevels, materials and
279
+ triangles); a paid generation after
280
+ the creator approves its cost (`asset_generate`, `asset_job`). Code builds
281
+ what is procedural by nature (terrain, scatter, water, effects); a hero asset
282
+ is never boxes and cylinders. `asset_import` is the one way in for a file from
283
+ outside: it converts, validates, sizes and simplifies it, and records its licence.
284
+
285
+ ## Building blocks (code)
286
+
287
+ Tools, not looks: every height, spacing, distance and material is this space's own, from its brief.
288
+
289
+ ```ts
290
+ import { createNoise, fbm3Node, createTerrain, scatterArea, fieldInstances, createInstancedField, createImpostor } from '@nowhere/sdk'
291
+ const field = createNoise(SEED), height = (x: number, z: number) => field.fbm(x * FREQ, z * FREQ) * RELIEF_M
292
+ groundMat.colorNode = /* the brief's ground, varied by */ fbm3Node(positionWorld.mul(FREQ), SEED)
293
+ const ground = createTerrain({ height, material: groundMat, size: SIDE_M }) // ground.heightAt(x, z) is exact
294
+ const points = scatterArea({ seed: SEED, area: [X0, Z0, X1, Z1], spacing: SPACING_M, height, density: (x, z) => DENSITY })
295
+ const trees = createInstancedField({ instances: fieldInstances(points), levels: [{ object: tree, distance: 0 }, { impostor: createImpostor(tree), distance: FAR_M }] })
296
+ ```
297
+
298
+ `noise3Node`, `fbm3Node` and `ridged3Node` are the CPU field in TSL, same seed same value; `scatterSurface(mesh, ...)` scatters over a mesh. Levels switch per chunk by the visitor's eye, and a chunk out of view is not drawn; a field's root may move or scale, never turn. An impostor takes its pictures on its first frame and casts no shadow; it bakes colour where it draws them, so its model is coloured by `positionLocal` or attributes, not `positionWorld`, and has no emissive. Code saves texture megabytes but costs frame time: nw_check's `perf` is the worst of the spawn and hero views at high (1080p, 16.7 ms at p95) and low (a phone's pixels, 33 ms).
299
+
300
+ ## scene.json: objects the creator placed
301
+
302
+ Next to `game.config.json` a project may have a `scene.json`: models the creator
303
+ dragged into the studio and arranged with the gizmo. You can read and write it
304
+ like any other file, and the viewport reloads the moment you save.
305
+
306
+ ```json
307
+ {
308
+ "schema": "nowhere/scene@1",
309
+ "objects": [
310
+ { "id": "oak", "asset": "assets/oak.glb", "kind": "oak", "solid": true,
311
+ "position": [4, 0, -2], "rotation": [0, 1.57, 0], "scale": [1, 1, 1] },
312
+ { "id": "lighthouse", "asset": "assets/lighthouse.glb", "kind": "lighthouse", "solid": true,
313
+ "position": [12, 0, -30], "rotation": [0, 0, 0], "scale": [1, 1, 1], "normalize": false }
314
+ ]
315
+ }
316
+ ```
317
+
318
+ `id` is unique and is the name the Objects panel shows. `asset` is a
319
+ project-relative path under `assets/` (.glb .gltf .obj .fbx .stl .ply .dae .3mf).
320
+ `rotation` is XYZ Euler angles in RADIANS. One unit is one metre and the player
321
+ is 1.75 m tall. A model whose largest side is over 12 m or under 0.375 m is
322
+ auto-sized to 3 m when it loads; any model is stood on y = 0 and centred on its
323
+ own footprint. Set `"normalize": false` on a placement to keep the model's real
324
+ size (it is still stood on y = 0 and centred), which is what you want for a
325
+ model made to scale. `kind` is what your code calls it (see below) and defaults
326
+ to the id with a trailing `-<number>` removed, so a file named `house-2.glb`
327
+ lands as kind `house`: write the kind out when the default would lie. `solid`
328
+ defaults to true.
329
+
330
+ Call `nw_schema` with kind "scene" for the exact schema. Move, rotate, duplicate
331
+ or delete these by editing the file; the creator can do the same by hand at the
332
+ same time, so read it before you write it. Models live in `assets/`. The creator
333
+ drops them into the studio; you bring them in with `asset_import` (from a
334
+ library, a download or a generation) or export your own with `nw_blender`;
335
+ `nw_take_download` moves a checked download that Blender needs (a texture, an
336
+ HDRI, a .blend) into `blender/`. Add a placement to scene.json for a model you
337
+ made or imported; leave the creator's placements as they are unless asked.
338
+
339
+ ## Placed objects in your code
340
+
341
+ The creator's placed objects are not decoration. Every placement in scene.json is
342
+ handed to `createGame` as `ctx.placed` (a `PlacedHandle[]`, in file order), and a
343
+ `World` registers each one as an Instance under its KIND with `owned: false`:
344
+
345
+ ```ts
346
+ export function createGame(ctx: GameContext) {
347
+ const world = new World(ctx)
348
+ // Every placed object of a kind is one (no world.add); kinds and rules are the brief's.
349
+ const KIND = '<kind>'
350
+ world.state.left = world.placed(KIND).length
351
+ world.onTouch(KIND, (thing, w) => {
352
+ w.remove(thing) // hides it and takes it out of the rules
353
+ w.state.left = (w.state.left as number) - 1
354
+ }, '<the rule, in the brief\'s words>')
355
+ // A placed "<other kind>" that moves when the player is near.
356
+ const NEAR_M = 0, MOVE_M = 0, RATE = 0 // <the brief's distance, travel and speed>
357
+ world.onUpdate((dt, w) => {
358
+ for (const p of w.placed('<other kind>')) {
359
+ const near = p.object.position.distanceTo(w.player!.object.position) < NEAR_M
360
+ p.object.position.y += ((near ? MOVE_M : 0) - p.object.position.y) * Math.min(1, dt * RATE)
361
+ }
362
+ })
363
+ return world.finish()
364
+ }
365
+ ```
366
+
367
+ What a placement is to your code:
368
+ - `kind` groups them: scene.json `kind`, defaulting to the id with its `-2`/`-3`
369
+ suffix removed (`oak`, `oak-2`, `oak-3` are all `oak`). The creator edits it in the
370
+ Objects panel. `onTouch(kind)`, `world.find(kind)` and `world.placed(kind)` all
371
+ use it; `find` also returns anything your code added under the same id, `placed`
372
+ returns only the creator's.
373
+ - `solid` (default true) makes it block the player and be standable, with no code.
374
+ - `inst.object` is a Group carrying the placement's transform; the model is its
375
+ child and may still be loading during `createGame` (no children yet, empty
376
+ bounding box, so it neither blocks nor touches until it arrives). Measure it in a
377
+ rule, not in `createGame`, and never cast it to a Mesh: traverse for its meshes.
378
+ - Those meshes' geometry and materials are SHARED with every placement of the same
379
+ file and with the studio's own cache, and the studio never undoes an edit to
380
+ them. Treat them as read-only. To tint one placement, give its mesh a copy first
381
+ (`mesh.material = (mesh.material as THREE.Material).clone()`) and change that; a
382
+ change to the shared material leaks to every placement and outlives the game.
383
+ - `ctx.placed[i]` also carries `asset` (the model path) if you need to tell placements
384
+ apart by what they are rather than by kind.
385
+
386
+ They are the creator's, not yours:
387
+ - Never dispose, detach or reparent a placed object. `world.remove()` on one hides it
388
+ and drops it from the rules; it comes back when the game is rebuilt (Play, Stop,
389
+ a playtest, a code save, or a change to scene.json). Your `dispose()` must not
390
+ touch them (World's does the right thing).
391
+ - You may move, rotate, scale or hide them, but only a run sees it: nothing you do
392
+ is saved, and while the creator is editing rather than playing the studio holds
393
+ every placed object at its scene.json state each frame, so a rule's moves and
394
+ hides show during Play and playtests and nowhere else. A scene.json change
395
+ mid-play snaps them back too. To change where one sits, or its kind or solid
396
+ flag, edit scene.json.
397
+ - Every Play, every Stop and every playtest rebuilds the game from the document,
398
+ so a run never starts with what the previous run removed already gone.
399
+ - Adding, removing or re-kinding a placement rebuilds the game (the same way a code
400
+ save does), so `createGame` may read `ctx.placed` once and trust it for that run.
401
+ - A placed object never shows under "From the code" in the Objects panel; the
402
+ registry counts only what `world.add` made.
403
+
404
+ The player block: `game.config.json` may carry `player: { spawn: [x, y, z], yaw,
405
+ speed, run, eyeHeight, fov }`. The creator sets the spawn from the Map panel;
406
+ `finish()`'s automatic player and `spawnPlayer()` without a `position` start
407
+ there (and respawn there after a fall). The rest is the space's scale, from its
408
+ brief: `speed` is the walk in m/s (7 when absent), `run` what Shift multiplies
409
+ it by (2), `eyeHeight` the view's height above the feet (1.4 m in first person,
410
+ 1.5 m in third) and `fov` the play camera's vertical degrees (20 to 100, the
411
+ host's own when absent). `spawnPlayer`'s options of the same names win over
412
+ all of them. A planet that sets any of the four needs a live Oda on
413
+ publish contract 4 (the 'player-scale' capability); until then its publish
414
+ stops before anything is uploaded and says so.
415
+
416
+ ## Items a visitor can take away
417
+
418
+ A visitor carries a bag from planet to planet, and a planet puts in it only what its `game.config.json` lists under `items`, such as `"items": [{ "id": "moon-shell", "name": "Moon shell", "description": "Found on the night beach.", "color": "#cfe8ff", "icon": "assets/moon-shell.png", "max": 5 }]`: `id` is lowercase letters, digits and dashes (up to 32) and is what the bag knows an item by, so renaming one keeps the copies visitors carry; `name` (up to 40, no two the same) and `description` (up to 200) are what the bag shows, `icon` is a square .png, .jpg or .webp of the planet's own directly inside assets/, `color` tints an icon without one, and `max` is the most one visitor may carry (999 when absent). `world.give("moon-shell")` or `world.give("moon-shell", 3)` resolves `false` when the item is not listed, would pass `max`, or the bag is full. `world.pickUpOnTouch(kind, { item: "moon-shell" })` (`item` defaults to the kind) hides a touched instance and removes it once the bag took it, under the declared name. `world.carrying(id)`, `world.take(id, n)` and `world.items()` read the bag and take back this planet's own. Make items only when the request has something to find, collect or keep; a pick-up that only counts toward this planet's score is an `onTouch` that counts in `world.state`. When the visitor falls, the bag empties. A signed-in visitor's bag is kept by the server, held to this list and its `max`.
419
+
420
+ ## Oda platform rules
421
+
422
+ These make a space hostable as a planet in the Oda universe: no own rAF
423
+ loop, everything under root, dispose() frees resources, input only via
424
+ ctx.input, config knobs stay in game.config.json, the look stays in the config (no
425
+ post passes of your own), and files from outside come in through asset_import
426
+ with their licence recorded.
427
+
428
+ ## Games: the visitor's HP and hazards
429
+
430
+ A game keeps its own stakes (a score, a timer, lives, a phase) in `world.state`. The visitor's HP is for a game whose request asks for danger; what a visitor can take away is under "Items a visitor can take away", above.
431
+
432
+ ### The visitor: HP
433
+
434
+ Whoever plays your planet plays it as their pilot, and the pilot has HP. It belongs to the visitor, not to your planet: it arrives with the visitor, leaves with them, and stays as your planet left it, on the next planet and back in the universe. A wound taken here is still there on the next planet. `world.pilot` is that pilot (`ctx.pilot`, which every nowhere host passes; where one is missing World makes a stand-in of its own, whose changes go nowhere).
435
+
436
+ - HP runs from 0 to `world.maxHp` (100), and `world.hp` reads it. `world.damage(n)` and `world.heal(n)` take any finite amount of 0 or more (anything else is ignored), as often as the game likes. There are no limits: how hard a planet is, is the planet's own business, and an instant kill is allowed.
437
+ - At 0 HP the pilot falls. The host ends the visit, sends the visitor back to the start of the universe and starts the pilot over at full HP. There is no death hook and no game over of yours to show: the game may run a moment longer, and every damage and heal after that is ignored.
438
+
439
+ A hazard and a heal spot are onTouch rules, so they show in the Rules panel (each also takes a `desc` for its line; one is written from the numbers otherwise), and onTouch fires every frame, so each waits between hits:
440
+ - `world.hurtOnTouch(kind, amount, { every = 0.5 })`: the wait is per instance, so two enemies touching at once hit twice.
441
+ - `world.healOnTouch(kind, amount, { every = 0.5, once = false })`: `once` removes each instance after a heal that counted.
442
+
443
+ Nothing draws the visitor's HP, in the studio, the CLI preview or on a planet: a game that shows it reads `world.hp` in `onUpdate` and draws it inside the world (`world.pilot.onChange(fn)` outlives the game unless the unsubscribe it returns runs in your dispose()).
444
+
445
+ Use `world.damage` for whatever hurts the VISITOR, never a `world.state.health` of your own standing in for theirs: a private number means nothing on any other planet and never ends a visit. Health that belongs to the game's own things (an enemy's hit points, a base under siege) stays in `world.state`, and the game may end its own rounds over it.
446
+
447
+ Every entry is a fresh run, as every Play is: only the visitor's HP comes in from before. In the studio the pilot is a stand-in, full at every Play and playtest; at 0 HP Play (or the playtest) stops with a notice, and nw_play reports it as `pilot` in its `start` and `end`, and a fall as `fell`.