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.
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 +90 -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-CB77cP9U.js +1 -0
  197. package/web-dist/assets/KTX2Loader-6OIWUF7s.js +2 -0
  198. package/web-dist/assets/SPZLoader-zYj0Alfv.js +1 -0
  199. package/web-dist/assets/gaussianSplat-CJTI1sEh.js +1 -0
  200. package/web-dist/assets/index-CcjyyQco.css +1 -0
  201. package/web-dist/assets/index-DMyJcoZJ.js +693 -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
@@ -0,0 +1,355 @@
1
+ import { z } from 'zod';
2
+ import { Hex, Id, Vec3 } from './common.js';
3
+ import { LookSpec, OPEN_WORLD_SIDE } from './look.js';
4
+ // game.config.json: the only document the studio's panels edit directly.
5
+ // Everything else about a game is CODE (src/**), which the agent owns; these
6
+ // are the planet-level knobs that must stay hand-adjustable without an LLM
7
+ // call, so they live as validated data.
8
+ /**
9
+ * World-space span of one tile. An arbitrary internal constant, chosen only so
10
+ * authored coordinates land in a comfortable range; it carries no real-world
11
+ * meaning and is never shown to the creator.
12
+ */
13
+ export const UNITS_PER_TILE = 100;
14
+ /** The largest planet: 64 x 64 tiles, a map 6.4 km a side. Any whole number
15
+ * of tiles up to it is a valid size; PLANET_SIZES are the named steps. */
16
+ export const MAX_TILES = 4096;
17
+ /** A flat ground in a world with no edge: far past anything a camera draws. */
18
+ export const OPEN_GROUND_SIDE = 20000;
19
+ /** Side length of the square map, in world units: its area is `tiles` tiles.
20
+ * A world with no `tiles` has no map; this is then only the size it is taken
21
+ * to be where something needs a number (OPEN_WORLD_SIDE), never an edge. */
22
+ export function mapSide(tiles) {
23
+ return tiles ? UNITS_PER_TILE * Math.sqrt(tiles) : OPEN_WORLD_SIDE;
24
+ }
25
+ /** True when world-space (x, z) lies on the map square (centred at origin). */
26
+ export function isOnMap(tiles, x, z) {
27
+ if (!tiles)
28
+ return true;
29
+ const half = mapSide(tiles) / 2;
30
+ return Math.abs(x) <= half && Math.abs(z) <= half;
31
+ }
32
+ /**
33
+ * Pulls a position onto the map, for a planet that has one (it names `tiles`,
34
+ * as every planet made before worlds went open does). With no `tiles` there is
35
+ * no edge and the position stands where it is.
36
+ */
37
+ export function clampToMap(tiles, position) {
38
+ if (!tiles)
39
+ return [position[0], position[1], position[2]];
40
+ const half = mapSide(tiles) / 2;
41
+ return [
42
+ Math.max(-half, Math.min(half, position[0])),
43
+ // Height is deliberately free: a game may float things above the map or
44
+ // bury them beneath it.
45
+ position[1],
46
+ Math.max(-half, Math.min(half, position[2])),
47
+ ];
48
+ }
49
+ /**
50
+ * The planet sizes the studio offers by name. Each step quadruples the area (a
51
+ * doubling of the map's side), so the ladder reads as a real jump in scale.
52
+ * They are sizes to start from, not the only ones: `tiles` is any whole number from 1 to MAX_TILES, so a planet
53
+ * grows by as much as it is asked to. Tiles are UNITLESS: a count, not
54
+ * metres, so the same ladder serves a game about a cell and one about a galaxy.
55
+ */
56
+ export const PLANET_SIZES = [
57
+ { id: 'S', tiles: 1 },
58
+ { id: 'M', tiles: 4 },
59
+ { id: 'L', tiles: 16 },
60
+ { id: 'XL', tiles: 64 },
61
+ ];
62
+ export function planetSizeOf(tiles) {
63
+ return PLANET_SIZES.find((s) => s.tiles === tiles)?.id ?? null;
64
+ }
65
+ /** Index of the nearest rung, so stepping from an off-ladder count still works. */
66
+ export function nearestSizeIndex(tiles) {
67
+ let best = 0;
68
+ for (let i = 1; i < PLANET_SIZES.length; i++) {
69
+ if (Math.abs(PLANET_SIZES[i].tiles - tiles) < Math.abs(PLANET_SIZES[best].tiles - tiles))
70
+ best = i;
71
+ }
72
+ return best;
73
+ }
74
+ // ---- environment values (global, plain three.js settings) ----
75
+ export const Sky = z.discriminatedUnion('kind', [
76
+ // Transparent: nothing painted behind the scene, so the studio's glass (or a
77
+ // host world's own sky) shows through. The default.
78
+ z.object({ kind: z.literal('none') }),
79
+ z.object({ kind: z.literal('color'), color: Hex }),
80
+ z.object({ kind: z.literal('gradient'), top: Hex, bottom: Hex }),
81
+ // A picture of the whole sky (an equirectangular .hdr or .exr under assets/):
82
+ // what is painted behind the world and what lights it. It carries the two
83
+ // colours too, because every consumer that only knows gradients (the SDK's
84
+ // glowFor, the universe's globe, the splat) reads top and bottom, and they
85
+ // are what is painted until the picture has loaded. asset_import measures them.
86
+ z.object({
87
+ kind: z.literal('hdri'),
88
+ asset: z.string().regex(/^assets\/[^/]+\.(hdr|exr)$/, 'must be an .hdr or .exr file directly inside assets/'),
89
+ top: Hex,
90
+ bottom: Hex,
91
+ /** How bright the painted sky is; 1 as the file has it. */
92
+ intensity: z.number().min(0).max(8).optional(),
93
+ /** Radians about +Y, for the sun in the picture to sit where the config's sun is. */
94
+ rotation: z.number().optional(),
95
+ /** 0 is the picture sharp, 1 a soft wash of its colours. */
96
+ blur: z.number().min(0).max(1).optional(),
97
+ /** false: the picture lights the world but nothing is painted behind it. */
98
+ background: z.boolean().optional(),
99
+ /** The picture's lower half laid on the ground instead of on a dome
100
+ * (three's GroundedSkybox), so the world stands on the ground the
101
+ * photograph was taken over. height: how far above that ground the
102
+ * camera was, metres (a person's eye is about 1.7, a mast 10 to 20);
103
+ * radius: how far the projected ground reaches, metres (default: the
104
+ * map's side). */
105
+ ground: z.object({ height: z.number().min(0.1).max(500), radius: z.number().min(10).max(20000).optional() }).optional(),
106
+ }),
107
+ // Air lit by the config's own sun (three's SkyMesh, Preetham's daylight
108
+ // model): its colour, its haze and the glow round the sun come from these
109
+ // numbers and from where lighting.sun is, so the sky and the sun cannot
110
+ // disagree. It lights the world with the same model, scaled so the sun the
111
+ // model has is lighting.sun's intensity; its disc is drawn but its light
112
+ // is lighting.sun's. top and bottom are its colours for what reads a sky
113
+ // by two (look_apply fills them from the model when left out).
114
+ z.object({
115
+ kind: z.literal('physical'),
116
+ /** Haze: about 2 on a clear mountain day, 3 to 5 a clear lowland one, 10
117
+ * a hazy city, 20 dust or smog. */
118
+ turbidity: z.number().min(1).max(20),
119
+ /** How strongly the air scatters blue: 1 is Earth's; above it a deeper
120
+ * blue and a redder low sun, below it a paler sky. */
121
+ rayleigh: z.number().min(0).max(4),
122
+ /** Aerosol scattering, and how forward it throws light (the glow round
123
+ * the sun). Default the model's own, 0.005 and 0.8. */
124
+ mieCoefficient: z.number().min(0).max(0.1).optional(),
125
+ mieDirectionalG: z.number().min(0).max(0.999).optional(),
126
+ /** false: no disc painted where the sun is. */
127
+ sunDisc: z.boolean().optional(),
128
+ top: Hex,
129
+ bottom: Hex,
130
+ }),
131
+ ]);
132
+ export const Fog = z.object({
133
+ color: Hex,
134
+ near: z.number().min(0),
135
+ far: z.number().positive(),
136
+ /** Absent: range, exactly as before (none at near, all at far). exp2 thickens
137
+ * with the square of the distance; height adds ground fog below `height`. */
138
+ mode: z.enum(['range', 'exp2', 'height']).optional(),
139
+ /** exp2: how fast it thickens. Default 1.978 / far, which is 98% at far. */
140
+ density: z.number().min(0).max(1).optional(),
141
+ /** height: the y below which the ground fog lies. Default 0. */
142
+ height: z.number().optional(),
143
+ /** height: how thick the ground fog is. Default 0.08. */
144
+ heightDensity: z.number().min(0).max(1).optional(),
145
+ });
146
+ export const Lighting = z.object({
147
+ ambient: z.object({
148
+ color: Hex.default('#d6e4f2'),
149
+ intensity: z.number().min(0).max(10).default(0.55),
150
+ }),
151
+ sun: z
152
+ .object({
153
+ color: Hex.default('#fff2e0'),
154
+ intensity: z.number().min(0).max(10).default(3.4),
155
+ direction: Vec3.default([0.85, -1, -0.35]),
156
+ shadows: z.boolean().default(true),
157
+ })
158
+ .nullable()
159
+ .default({ color: '#fff2e0', intensity: 3.4, direction: [0.85, -1, -0.35], shadows: true }),
160
+ });
161
+ /** Ground covers exactly the map square; there is no floor beyond it. */
162
+ export const Ground = z.discriminatedUnion('kind', [
163
+ z.object({ kind: z.literal('none') }),
164
+ z.object({
165
+ kind: z.literal('flat'),
166
+ color: Hex.default('#ffffff'),
167
+ roughness: z.number().min(0).max(1).default(0.95),
168
+ /** Below 1 the plate reads as translucent over the host backdrop. */
169
+ opacity: z.number().min(0).max(1).default(0.16),
170
+ }),
171
+ ]);
172
+ /**
173
+ * Glow. An emissive material paints light INTO the frame; bloom is that light
174
+ * spilling past the edge of the thing emitting it, which is what makes a
175
+ * crystal read as lit rather than as a pale blue box. Only the emissive
176
+ * channel blooms, so a wall in full sun stays a wall.
177
+ */
178
+ export const Bloom = z.object({
179
+ enabled: z.boolean().default(true),
180
+ /** How much of the emissive light spills. 0 is off in all but name. */
181
+ strength: z.number().min(0).max(3).default(0.9),
182
+ /** How far it spreads: 0 is a tight halo, 1 a wide wash. */
183
+ radius: z.number().min(0).max(1).default(0.4),
184
+ /** Emissive brightness a surface has to reach before it spills at all. 0 lets
185
+ * every emissive surface glow in proportion to how bright it already is,
186
+ * which is what game code expects when it animates emissiveIntensity. */
187
+ threshold: z.number().min(0).max(2).default(0),
188
+ });
189
+ /** Where play begins and how the visitor moves through the space. Absent, the
190
+ * SDK spawns at the origin facing -Z, walking at 7 m/s and running at twice
191
+ * that. The creator sets the spawn by hand (the Map panel); the scale (speed,
192
+ * run, eye height, field of view) comes from the space's brief, so a cathedral
193
+ * and a cupboard are not walked the same way. Each is a default spawnPlayer's
194
+ * own options still override. */
195
+ export const Player = z.object({
196
+ spawn: Vec3.optional().describe('World position the player starts at, and returns to after falling off the map. y is height: 1 stands on the ground.'),
197
+ yaw: z
198
+ .number()
199
+ .optional()
200
+ .describe('Which way the player faces at the start, in radians around the vertical axis. 0 faces -Z; positive turns left (towards -X).'),
201
+ speed: z
202
+ .number()
203
+ .positive()
204
+ .max(50)
205
+ .optional()
206
+ .describe('Walking speed in metres per second. Absent: 7, which the third-person figure plays as its run (an everyday walk is about 1.4).'),
207
+ run: z
208
+ .number()
209
+ .min(1)
210
+ .max(5)
211
+ .optional()
212
+ .describe('How many times faster the walk is while Shift is held. Absent: 2.'),
213
+ eyeHeight: z
214
+ .number()
215
+ .min(0.2)
216
+ .max(10)
217
+ .optional()
218
+ .describe('Where the view is taken from, in metres above the feet: the eye in first person, the point the follow camera circles in third. Absent: the SDK\'s own (1.4 in first person, 1.5 in third).'),
219
+ // 100 at most: nw_view's player shots stop there (SHOT_LIMITS.fov), so the
220
+ // agent judges the frame the visitor sees.
221
+ fov: z
222
+ .number()
223
+ .min(20)
224
+ .max(100)
225
+ .optional()
226
+ .describe('The play camera\'s vertical field of view in degrees, 20 to 100. Absent: the host\'s own (55 in the studio).'),
227
+ });
228
+ // eslint-disable-next-line no-control-regex
229
+ const CONTROL = /[\u0000-\u001f\u007f]/g;
230
+ /** A declared name as the bag keeps it (the SDK pilot's cleanName): each
231
+ * control character a space, then trimmed. */
232
+ const bagName = (name) => name.replace(CONTROL, ' ').trim();
233
+ /** One thing a visitor can carry away from this planet. A planet gives only
234
+ * what its config lists: world.give and pickUpOnTouch name an `id` from here,
235
+ * and the server holds a signed-in visitor's bag to the same list. */
236
+ export const ItemDecl = z.object({
237
+ id: z
238
+ .string()
239
+ .regex(/^[a-z0-9][a-z0-9-]{0,31}$/, 'lowercase letters, digits and dashes, up to 32')
240
+ .describe('What the code calls it: world.give("<id>"), pickUpOnTouch(kind, { item: "<id>" }).'),
241
+ name: z
242
+ .string()
243
+ .min(1)
244
+ .max(40)
245
+ // A refine, not a trim: hosts and the server read the stored config as it is.
246
+ .refine((s) => bagName(s).length > 0, 'a name needs a visible character')
247
+ .describe('What the visitor sees in their bag.'),
248
+ description: z.string().max(200).optional().describe('One line about it, shown in the bag.'),
249
+ color: Hex.optional().describe("The icon's colour when it has no picture."),
250
+ icon: z
251
+ .string()
252
+ // The picture kinds a planet may publish (ASSET_KINDS.texture, less .ktx2).
253
+ .regex(/^assets\/[^/]+\.(png|jpg|webp)$/, 'must be a .png, .jpg or .webp directly inside assets/')
254
+ .optional()
255
+ .describe("A square picture of it for the bag, one of the planet's own files."),
256
+ max: z.number().int().min(1).max(999).optional().describe('The most one visitor may carry. Absent: 999.'),
257
+ });
258
+ export const GameConfig = z.object({
259
+ schema: z.literal('nowhere/config@1'),
260
+ id: Id,
261
+ title: z.string().min(1).max(80),
262
+ /** A square edge for the planet. New worlds leave it out and have no edge;
263
+ * the planets made before that keep the edge they were built for. */
264
+ tiles: z.number().int().min(1).max(MAX_TILES).optional(),
265
+ sky: Sky,
266
+ fog: Fog.nullable().default(null),
267
+ lighting: Lighting,
268
+ ground: Ground.default({ kind: 'flat', color: '#ffffff', roughness: 0.95, opacity: 0.16 }),
269
+ bloom: Bloom.default({ enabled: true, strength: 0.9, radius: 0.4, threshold: 0 }),
270
+ player: Player.optional(),
271
+ /** How the picture is finished: tone mapping, exposure, grade, AO, shadows,
272
+ * vignette and grain (look.ts). Absent is the studio's look from before
273
+ * there was one (Neutral); every host draws it through the SDK's createLook. */
274
+ look: LookSpec.optional(),
275
+ /** What a visitor can take away from here, and nothing else (ItemDecl). */
276
+ items: z
277
+ .array(ItemDecl)
278
+ .max(64)
279
+ .refine((list) => new Set(list.map((i) => i.id)).size === list.length, 'two items share an id')
280
+ // The bag shows names: two the same would be two items nobody can tell apart.
281
+ .refine((list) => new Set(list.map((i) => bagName(i.name))).size === list.length, 'two items share a name')
282
+ .optional(),
283
+ });
284
+ // Text a planet's record cannot keep. The config is stored as jsonb and its
285
+ // title as text, and Postgres refuses U+0000 in both and half of a surrogate
286
+ // pair in jsonb. Such a config passed every check here and was then refused
287
+ // by the database, after its files had gone up, every time it was sent.
288
+ const NUL = '\u0000';
289
+ const LONE_SURROGATE = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/;
290
+ function whyUnstorable(text) {
291
+ if (text.includes(NUL))
292
+ return 'U+0000 (a null character)';
293
+ if (LONE_SURROGATE.test(text))
294
+ return 'half of a surrogate pair (U+D800 to U+DFFF on its own)';
295
+ return null;
296
+ }
297
+ /** Where a value holds text nowhere cannot store (U+0000, or half of a
298
+ * surrogate pair), in a string or in an object's key, as dotted paths ("" is
299
+ * the value itself), each with a sentence. Empty for a value without any. */
300
+ export function unstorableText(value) {
301
+ const out = [];
302
+ const walk = (v, path) => {
303
+ if (typeof v === 'string') {
304
+ const why = whyUnstorable(v);
305
+ if (why)
306
+ out.push({ path, message: `${path || 'the value'} holds ${why}, which Oda cannot store` });
307
+ return;
308
+ }
309
+ if (Array.isArray(v)) {
310
+ v.forEach((item, i) => walk(item, path ? `${path}.${i}` : String(i)));
311
+ return;
312
+ }
313
+ if (v === null || typeof v !== 'object')
314
+ return;
315
+ for (const [key, item] of Object.entries(v)) {
316
+ const at = path ? `${path}.${key}` : key;
317
+ const why = whyUnstorable(key);
318
+ if (why)
319
+ out.push({ path: at, message: `a key ${path ? `in ${path} ` : ''}holds ${why}, which Oda cannot store` });
320
+ walk(item, at);
321
+ }
322
+ };
323
+ walk(value, '');
324
+ return out;
325
+ }
326
+ /** Validates a raw game.config.json value into findings the agent (and the
327
+ * panel's dry-run) can act on. A config the schema takes is refused still
328
+ * when it holds text nowhere cannot store (unstorableText). */
329
+ export function validateConfig(raw) {
330
+ const parsed = GameConfig.safeParse(raw);
331
+ if (parsed.success) {
332
+ const unstorable = unstorableText(parsed.data);
333
+ if (unstorable.length === 0)
334
+ return { ok: true, config: parsed.data, findings: [] };
335
+ return {
336
+ ok: false,
337
+ findings: unstorable.map((u) => ({
338
+ path: `game.config.json${u.path ? ':' + u.path : ''}`,
339
+ code: 'schema',
340
+ message: u.message,
341
+ hint: 'Take the character out: it is invisible, and usually comes in with pasted text.',
342
+ })),
343
+ };
344
+ }
345
+ return {
346
+ ok: false,
347
+ findings: parsed.error.issues.map((i) => ({
348
+ path: `game.config.json${i.path.length ? ':' + i.path.join('.') : ''}`,
349
+ code: 'schema',
350
+ message: i.message,
351
+ hint: 'Call nw_schema with kind "config" to see the exact allowed shape.',
352
+ })),
353
+ };
354
+ }
355
+ export * from './look.js';