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
@@ -0,0 +1,134 @@
1
+ // The studio's rpc, as the agent's tools call it (ctx.rpc: build, status,
2
+ // view, play, eval, logs, pixels, perf), answered by a CLI preview page instead of
3
+ // the studio's window: the build by the same check as nw_check (the project
4
+ // checked as publishing checks it, then mounted in the page, then the page's
5
+ // verdict on what it threw, which materials failed and which files did not
6
+ // load), the rest by the page's probe (the studio viewport's agentProbe.ts)
7
+ // as `probe:*` requests.
8
+ //
9
+ // The MCP server (mcp.mjs) and the runner (make.mjs) both answer the eyes
10
+ // through this, so an agent sees a game the same way in either.
11
+
12
+ import { mountFailure } from './preview.mjs'
13
+ import { checkProject, fingerprint } from './project.mjs'
14
+
15
+ /** What this answers; any other method goes to the page's probe as is. */
16
+ export const PREVIEW_METHODS = ['build', 'status', 'view', 'play', 'eval', 'logs', 'pixels', 'perf']
17
+
18
+ /** A page from an older nowhere-engine has no probe: say how to get one. */
19
+ export function probeError(err) {
20
+ const message = err?.message ?? String(err)
21
+ return /Unknown request probe:/.test(message)
22
+ ? 'The preview page is from an older oda-engine and cannot answer this. Stop `oda dev` and start it again (or close the page) so the current one opens.'
23
+ : message
24
+ }
25
+
26
+ const defaultNoPage = (p) => `The preview page did not open. Open ${p.url} in a browser with WebGPU (Chrome or Edge), then try again.`
27
+
28
+ /**
29
+ * @param {{ root: string | (() => string | null), preview: object | (() => Promise<object>),
30
+ * pageWaitMs?: number, noProject?: () => string, noPage?: (preview: object) => string }} options
31
+ * root: the project (a getter where it can change, as nw_new does);
32
+ * preview: the preview (connectPreview's shape: url, request, ensurePage),
33
+ * or a getter that makes it the first time it is needed.
34
+ * @returns {{ rpc: (method: string, params?: object, timeoutMs?: number) => Promise<any>,
35
+ * checkAndMount: () => Promise<object>, livePage: () => Promise<{ p?: object, reason?: string }>,
36
+ * needsBuild: () => Promise<boolean>, reset: () => void }}
37
+ */
38
+ export function createPreviewRpc({ root, preview, pageWaitMs = 25_000, noProject, noPage = defaultNoPage }) {
39
+ const rootNow = typeof root === 'function' ? root : () => root
40
+ const previewNow = typeof preview === 'function' ? preview : async () => preview
41
+ const needRoot = () => {
42
+ const r = rootNow()
43
+ if (!r) throw new Error(noProject?.() ?? 'There is no Oda project here.')
44
+ return r
45
+ }
46
+
47
+ // The last build this answered (a build, or a look after an edit), and the
48
+ // project's files as they were when it started: a look at a project that
49
+ // changed since builds first, so it never shows the game before an edit.
50
+ let lastBuild = null
51
+ let builtAt = null
52
+
53
+ /** The preview, once its page is open, or the reason it is not. */
54
+ async function livePage() {
55
+ const p = await previewNow()
56
+ const ok = await p.ensurePage(pageWaitMs)
57
+ return ok ? { p } : { reason: noPage(p) }
58
+ }
59
+
60
+ /** Builds and checks the project as publishing does, then mounts it in the
61
+ * preview and waits for its first frames. */
62
+ async function checkAndMount() {
63
+ const r = needRoot()
64
+ const before = await fingerprint(r)
65
+ const checked = await checkProject(r)
66
+ if (!checked.bundle) {
67
+ lastBuild = { ok: false, error: `The game does not build: ${checked.problems.join('\n')}` }
68
+ return { checked, ran: null, live: null }
69
+ }
70
+ const live = await livePage()
71
+ const ran = live.p ? await live.p.request('mount', { code: checked.bundle }, 30_000) : null
72
+ // What the page says went wrong (preview.mjs mountFailure): a throw, and
73
+ // also what the SDK's material watch found (a material drawn flat black)
74
+ // and the files it loads through ctx.assets that failed.
75
+ const failure = mountFailure(ran)
76
+ // A failure the game still runs through: it is on screen, wrong.
77
+ lastBuild = failure ? { ok: false, error: failure, running: ran?.mounted === true } : { ok: true }
78
+ if (ran && !failure) builtAt = before
79
+ return { checked, ran, live, failure }
80
+ }
81
+
82
+ /** The studio's rpc, answered here. Never rejects. */
83
+ async function rpc(method, params, timeoutMs) {
84
+ try {
85
+ if (method === 'build') {
86
+ const { checked, ran, live, failure } = await checkAndMount()
87
+ if (!checked.bundle) return { ok: false, error: checked.problems.join('\n') }
88
+ if (!ran) return { ok: false, error: live?.reason ?? 'The preview page did not open.' }
89
+ return failure ? { ok: false, error: failure, running: ran.mounted === true } : { ok: true, ran: true }
90
+ }
91
+ // No Electron here: the asset tools resize pictures with sharp instead.
92
+ if (method === 'image-resize') return { ok: false, error: 'The CLI has no image-resize; sharp resizes.' }
93
+ const live = await livePage()
94
+ if (!live.p) return { ok: false, error: live.reason }
95
+ if (method === 'status') {
96
+ // The page's own report (mounted, errors, the status line, the pilot)
97
+ // and the probe's live numbers, as the studio merges them.
98
+ const runtime = await live.p.request('status', {}, 10_000).catch((err) => ({ error: err?.message ?? String(err) }))
99
+ const probe = await live.p.request('probe:status', {}, 4000).catch((err) => ({ ok: false, error: probeError(err) }))
100
+ const answered = !!probe && typeof probe === 'object' && probe.ok !== false
101
+ return {
102
+ build: lastBuild ?? { ok: false, error: 'not built yet' },
103
+ runtime,
104
+ live: answered ? probe : null,
105
+ ...(answered ? {} : { liveError: probe?.error ?? 'The preview page did not answer.' }),
106
+ }
107
+ }
108
+ // view, play, eval, logs, pixels (a picture decoded to RGBA by the
109
+ // page, for the reference tools where sharp is missing) and perf (the
110
+ // frame time at each tier): the probe's.
111
+ // A second less than the tool waits, so the page's own message wins.
112
+ const wait = Math.max(1000, (Number(timeoutMs) || 30_000) - 1000)
113
+ return await live.p.request(`probe:${method}`, params ?? {}, wait)
114
+ } catch (err) {
115
+ return { ok: false, error: probeError(err) }
116
+ }
117
+ }
118
+
119
+ return {
120
+ rpc,
121
+ checkAndMount,
122
+ livePage,
123
+ /** Whether the game changed since the last build answered here. */
124
+ needsBuild: async () => {
125
+ const r = rootNow()
126
+ return !builtAt || !r || (await fingerprint(r)) !== builtAt
127
+ },
128
+ /** Another project: nothing built yet. */
129
+ reset() {
130
+ lastBuild = null
131
+ builtAt = null
132
+ },
133
+ }
134
+ }
@@ -0,0 +1,359 @@
1
+ // A nowhere game project on disk: finding it, reading its documents, building
2
+ // it, and checking it the way publishing will (the same schema and gates the
3
+ // studio and the server use, from vendor/).
4
+
5
+ import { createHash } from 'node:crypto'
6
+ import fs from 'node:fs'
7
+ import fsp from 'node:fs/promises'
8
+ import path from 'node:path'
9
+ import { schema, vendor } from './resources.mjs'
10
+
11
+ /** A folder is a project when it has a game.config.json and src/main.ts. */
12
+ export function isProject(dir) {
13
+ return fs.existsSync(path.join(dir, 'game.config.json')) && fs.existsSync(path.join(dir, 'src', 'main.ts'))
14
+ }
15
+
16
+ /** The project `start` is in (it or a folder above it), or null. */
17
+ export function findProject(start = process.cwd()) {
18
+ let dir = path.resolve(start)
19
+ for (;;) {
20
+ if (isProject(dir)) return dir
21
+ const up = path.dirname(dir)
22
+ if (up === dir) return null
23
+ dir = up
24
+ }
25
+ }
26
+
27
+ /** The project for a command, or a sentence saying how to get one. */
28
+ export function requireProject(start) {
29
+ const root = findProject(start)
30
+ if (!root) {
31
+ throw new Error(
32
+ `${path.resolve(start ?? process.cwd())} is not inside an Oda project (no game.config.json and src/main.ts). Make one with: oda new <folder>`,
33
+ )
34
+ }
35
+ return root
36
+ }
37
+
38
+ async function readJson(file) {
39
+ try {
40
+ return { ok: true, value: JSON.parse(await fsp.readFile(file, 'utf8')) }
41
+ } catch (err) {
42
+ return { ok: false, missing: err.code === 'ENOENT', error: err.message }
43
+ }
44
+ }
45
+
46
+ /** The raw documents, as the preview page wants them (it validates them). */
47
+ export async function readDocs(root) {
48
+ const config = await readJson(path.join(root, 'game.config.json'))
49
+ const scene = await readJson(path.join(root, 'scene.json'))
50
+ return {
51
+ config: config.ok ? config.value : { __parseError: config.missing ? 'game.config.json is missing' : config.error },
52
+ scene: scene.ok ? scene.value : scene.missing ? null : { __parseError: scene.error },
53
+ }
54
+ }
55
+
56
+ /** src/main.ts bundled as the studio bundles it: three and the SDK left to
57
+ * the page that runs it, with the source map the preview reads an error's
58
+ * file and line from. */
59
+ export async function buildBundle(root) {
60
+ const { buildGame } = vendor('build.cjs')
61
+ return buildGame(root, { sourcemap: true })
62
+ }
63
+
64
+ /** A bundle as it ships: without the inline source map buildBundle adds,
65
+ * which publishing leaves out (publish.cjs). It roughly doubles the size, and
66
+ * its base64 could read as a secret to the gates. */
67
+ export const shippedCode = (code) => code.replace(/\n\/\/# sourceMappingURL=data:[^\n]*\s*$/, '\n')
68
+
69
+ const lines = (findings) => (findings ?? []).map((f) => `${f.path ? `${f.path}: ` : ''}${f.message}`)
70
+
71
+ // What this side calls itself when the live server or player is older.
72
+ const CLIENT = 'this Oda CLI'
73
+
74
+ /** The studio's publish module (vendor/publish.cjs), speaking as the CLI:
75
+ * its sentences about an older server or player say "this nowhere CLI". */
76
+ export function publishModule() {
77
+ const publish = vendor('publish.cjs')
78
+ publish.configure({ clientName: CLIENT })
79
+ return publish
80
+ }
81
+
82
+ /** One pre-flight finding as a line: where (when the sentence does not say
83
+ * it already), then the sentence. */
84
+ function findingLine(f) {
85
+ const where = String(f.error ?? '').startsWith('contract:') ? 'planet contract' : f.path && !f.message.includes(f.path) ? f.path : ''
86
+ return `${where ? `${where}: ` : ''}${f.message}`
87
+ }
88
+
89
+ /**
90
+ * Everything publishing checks before anything leaves the machine, short of
91
+ * running the game, with the studio's own pre-flight (vendor/publish.cjs
92
+ * preflight, which is @nowhere/schema's preparePublish, the same checkPublish
93
+ * the server runs): the config against its schema, the build, the planet
94
+ * contract's gates on the bundle, the scene, the ledger and its licences,
95
+ * which files travel, every size, and what the planet needs of the server
96
+ * and the player. Nothing in the project is written: a ledger a publish
97
+ * would start, or measure again, is made in memory.
98
+ *
99
+ * { ok, problems: string[], notes: string[], bundle?, shipped?, config,
100
+ * prepared? }: `bundle` keeps its source map for the preview page, `shipped`
101
+ * is the code as it goes up, `prepared` the pre-flight's verdict.
102
+ */
103
+ export async function checkProject(root) {
104
+ const s = await schema()
105
+ const problems = []
106
+ const notes = []
107
+
108
+ const docs = await readDocs(root)
109
+ let config = null
110
+ if (docs.config?.__parseError) problems.push(`game.config.json: ${docs.config.__parseError}`)
111
+ else {
112
+ const checked = s.validateConfig(docs.config)
113
+ if (!checked.ok || !checked.config) problems.push(...lines(checked.findings).map((l) => `game.config.json: ${l}`))
114
+ else config = checked.config
115
+ }
116
+
117
+ const built = await buildBundle(root)
118
+ let shipped = null
119
+ let prepared = null
120
+ if (!built.ok) problems.push(`The game does not build:\n${built.error}`)
121
+ else {
122
+ // What the build let through but may throw once that code runs.
123
+ for (const w of built.warnings ?? []) notes.push(`Warning (the game builds; fix this too): ${w}`)
124
+ // Judged as it will ship; the bundle handed back keeps its map for the
125
+ // preview page, which names a thrown error's file and line from it.
126
+ shipped = shippedCode(built.code)
127
+ if (config) {
128
+ const pre = await publishModule().preflight(root, { code: shipped, write: false })
129
+ if (pre.error) problems.push(pre.error, ...lines(pre.findings))
130
+ else {
131
+ prepared = pre.prepared
132
+ problems.push(...prepared.findings.map(findingLine))
133
+ const startsLedger = pre.lock && !fs.existsSync(path.join(root, s.LEDGER_FILE))
134
+ if (startsLedger) notes.push(`The game's code loads files only ${s.LEDGER_FILE} can carry: publishing starts it (every file in assets/ recorded as yours), and this check judged the planet with it.`)
135
+ if (prepared.unknownKeys.length > 0) {
136
+ notes.push(`${prepared.unknownKeys.join(', ')}: not ${prepared.unknownKeys.length === 1 ? 'a setting' : 'settings'} this version of Oda knows, so publishing leaves ${prepared.unknownKeys.length === 1 ? 'it' : 'them'} out.`)
137
+ }
138
+ if (prepared.absent.length > 0) notes.push(`In ${s.LEDGER_FILE} but not in the project, so left out: ${prepared.absent.join(', ')}.`)
139
+ if (prepared.left.length > 0) {
140
+ const shown = prepared.left.slice(0, 6).join(', ')
141
+ notes.push(`${prepared.left.length} file${prepared.left.length === 1 ? '' : 's'} in assets/ stay${prepared.left.length === 1 ? 's' : ''} on this machine (nothing places, records or names ${prepared.left.length === 1 ? 'it' : 'them'}): ${shown}${prepared.left.length > 6 ? ', ...' : ''}.`)
142
+ }
143
+ }
144
+ } else {
145
+ // Without a valid config the rest cannot be judged; the bundle's own
146
+ // gates still can.
147
+ const gates = s.checkBundle(shipped)
148
+ if (!gates.ok) problems.push(...lines(gates.findings).map((l) => `planet contract: ${l}`))
149
+ }
150
+ }
151
+ // The space brief, when there is one: the asset tools hold the work to
152
+ // it, so one that does not pass its schema is a problem like a config's.
153
+ const brief = await readJson(path.join(root, s.BRIEF_FILE))
154
+ if (brief.ok) {
155
+ const checkedBrief = s.validateBrief(brief.value)
156
+ if (!checkedBrief.ok) problems.push(...lines(checkedBrief.findings))
157
+ else {
158
+ const count = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`
159
+ notes.push(`${s.BRIEF_FILE} passes its schema: ${count(checkedBrief.brief.materials.length, 'material')}, ${count(checkedBrief.brief.heroViews.length, 'hero view')}.`)
160
+ }
161
+ } else if (!brief.missing) problems.push(`${s.BRIEF_FILE}: ${brief.error}`)
162
+ if (!fs.existsSync(path.join(root, '.nowhere', 'preview.png'))) {
163
+ notes.push('There is no preview picture yet: it is taken by the preview page (oda dev) once the game runs.')
164
+ }
165
+ if (!docs.config?.__parseError) notes.push(...(await lookNotes(root, docs.config, config, s)))
166
+ notes.push(...splatNotes(root, s))
167
+ return { ok: problems.length === 0, problems, notes, bundle: built.ok ? built.code : null, shipped, config, prepared }
168
+ }
169
+
170
+ /**
171
+ * A planet's splat environments, as warnings (schema splatAdvice): more
172
+ * splats in all than a planet may draw, and a planet with splats past the
173
+ * size it aims for. The studio's nw_check says the same (tools/harness.mjs).
174
+ */
175
+ function splatNotes(root, s) {
176
+ if (typeof s.splatAdvice !== 'function') return []
177
+ let files
178
+ try {
179
+ files = JSON.parse(fs.readFileSync(path.join(root, s.LEDGER_FILE), 'utf8'))?.files
180
+ } catch {
181
+ return []
182
+ }
183
+ let bytes = 0
184
+ const dir = path.join(root, 'assets')
185
+ for (const name of fs.existsSync(dir) ? fs.readdirSync(dir) : []) {
186
+ if (!s.isPublishablePath(`assets/${name}`)) continue
187
+ try {
188
+ bytes += fs.statSync(path.join(dir, name)).size
189
+ } catch {
190
+ // gone since the listing
191
+ }
192
+ }
193
+ return s.splatAdvice(files, bytes).map((line) => `Warning (splats): ${line}`)
194
+ }
195
+
196
+ /**
197
+ * What the look leaves to the engine, as warnings: look values and light left
198
+ * to their defaults, a sky of kind none (schema lookAdvice), and, under an
199
+ * HDRI, how far lighting.sun stands from the sun measured in the picture
200
+ * (skySunAdvice). Each says to set the value from the brief. Never a
201
+ * problem: a space may mean every one of them.
202
+ */
203
+ export async function lookNotes(root, raw, config, s) {
204
+ const out = s.lookAdvice(raw).map((line) => `Warning (look): ${line}`)
205
+ const sky = raw?.sky
206
+ if (sky?.kind === 'hdri' && typeof sky.asset === 'string' && /\.hdr$/i.test(sky.asset)) {
207
+ try {
208
+ const picture = s.decodeRadiance(new Uint8Array(await fsp.readFile(path.join(root, sky.asset))))
209
+ if (picture) {
210
+ const sun = s.measureSkySun({ ...picture, channels: 3, topRowFirst: true })
211
+ const light = s.resolveLook(config ?? raw).environment.intensity
212
+ out.push(...s.skySunAdvice(raw, sun, light).map((line) => `Warning (look): ${line}`))
213
+ }
214
+ } catch {
215
+ // A sky that cannot be read is the build's and the ledger's to say.
216
+ }
217
+ }
218
+ return out
219
+ }
220
+
221
+ /**
222
+ * What the live nowhere says about this project, without publishing it:
223
+ * what its server takes and its site's player plays (and what that player's
224
+ * SDK exports), and, when the server does dry runs, its verdict on the
225
+ * request this project would send, with the files as descriptors (nothing is
226
+ * uploaded or recorded). Asked with the public key: no account is needed.
227
+ *
228
+ * `checked` is checkProject's. Answers { ok, lines }: ok is true only when
229
+ * the live server answered a dry run with yes and neither side lacks what
230
+ * the planet needs, false when one of them said no, and null when production
231
+ * could not be asked, which is never a pass (checkExitCode). `using` swaps
232
+ * the publish module, the schema and git for a check script's: publish-check
233
+ * points them at its stand-in for production.
234
+ */
235
+ export async function checkProduction(root, checked, using = {}) {
236
+ const publish = using.publish ?? publishModule()
237
+ const s = using.schema ?? (await schema())
238
+ const out = []
239
+ const sides = await publish.readSides({})
240
+ const where = publish.infoUrls()
241
+ const unknown = Object.entries(sides).filter(([, r]) => r.state === 'unknown')
242
+ for (const [side, reading] of unknown) {
243
+ out.push(`· Not checked against production: the live ${side === 'server' ? 'server' : "site's player"} did not answer (${where[side]}: ${reading.reason}).`)
244
+ }
245
+ const prepared = checked.prepared
246
+ if (!prepared || !checked.ok) {
247
+ out.push('· Not asked the live server about this planet: fix the problems above first.')
248
+ return { ok: null, lines: out }
249
+ }
250
+
251
+ const exported = s.playerSdkOf(sides.player)
252
+ const missing = {
253
+ server: sides.server.state === 'unknown' ? [] : s.missingCapabilities(prepared.needs, sides.server.capabilities),
254
+ player: sides.player.state === 'unknown' ? [] : s.missingCapabilities(prepared.needs, sides.player.capabilities),
255
+ sdk: exported ? s.missingSdkExports(prepared.sdk ?? [], exported) : [],
256
+ }
257
+ if (missing.server.length > 0 || missing.player.length > 0 || missing.sdk.length > 0) {
258
+ out.unshift(`✗ Production: ${publish.olderSentences(missing, { nothingUploaded: false })}`)
259
+ return { ok: false, lines: out }
260
+ }
261
+
262
+ let ok = unknown.length === 0 ? true : null
263
+ const needs = prepared.needs.length > 0 ? prepared.needs.map(s.capabilityName).join(', ') : 'nothing beyond code'
264
+ if (sides.server.state === 'legacy') {
265
+ // 'legacy' is a server that says nothing about itself: one from before
266
+ // contract 3, which brought the info and the dry run together.
267
+ out.push(`· The live server is from before publish contract 3 and does no dry runs: it takes models only, which covers what this planet needs (${needs}), but it was not asked about this planet.`)
268
+ ok = null
269
+ } else if (sides.server.state === 'current' && !sides.server.capabilities.includes('dry-run')) {
270
+ out.push('· The live server does no dry runs, so it was not asked about this planet.')
271
+ ok = null
272
+ } else if (sides.server.state === 'current') {
273
+ const git = using.git ?? vendor('git.cjs')
274
+ const [repoKey, sha] = await Promise.all([git.rootCommitSha(root).catch(() => null), git.headSha(root).catch(() => null)])
275
+ const ran = await publish.dryRun(prepared, { bundle: checked.shipped, repoKey, sha })
276
+ if (ran.state === 'answered' && ran.answer.ok) {
277
+ const files = ran.answer.uploads.length
278
+ out.unshift(
279
+ `✓ The live server would take this planet: a dry run of the request (publish contract ${ran.answer.contract}, ${files} file${files === 1 ? '' : 's'} as descriptors) passed, needing ${needs}.`,
280
+ )
281
+ } else if (ran.state === 'answered') {
282
+ ok = false
283
+ out.unshift('✗ The live server would not take this planet:', ...ran.answer.findings.map((f) => ` - ${findingLine(f)}`))
284
+ } else if (ran.state === 'refused') {
285
+ ok = false
286
+ out.unshift(`✗ The live server refused the dry run: ${ran.error}`, ...ran.findings.map((f) => ` - ${findingLine(f)}`))
287
+ } else {
288
+ ok = null
289
+ out.push(`· Not checked against production: the live server's dry run got no answer (${ran.reason}).`)
290
+ }
291
+ }
292
+ if (ok !== false && sides.player.state !== 'unknown') {
293
+ out.push(`· The live site's player ${sides.player.state === 'current' ? `speaks publish contract ${sides.player.info.contract} and ` : ''}plays everything this planet needs.`)
294
+ if (!exported) out.push("· The live site's player does not list what its @nowhere/sdk exports, so the names this planet's code reads from it were not compared.")
295
+ }
296
+ return { ok, lines: out }
297
+ }
298
+
299
+ /**
300
+ * What `nowhere check` exits with, so a script that reads only the code is
301
+ * not told "pass" by a check that never reached production:
302
+ *
303
+ * 0 every check passed: the project, the preview when one is open, and
304
+ * the live nowhere's answer (or --offline, which asked it not to ask)
305
+ * 1 something is wrong with the project, in the preview, or the live
306
+ * nowhere said it would not take this planet
307
+ * 2 the project passed everything here, but the live nowhere was not
308
+ * asked or did not answer (no network, a server from before the dry
309
+ * run): not a problem with the game, and not a pass either
310
+ *
311
+ * `ok` is the project's own verdict and the preview's; `live` is
312
+ * checkProduction's answer, or null under --offline.
313
+ */
314
+ export function checkExitCode(ok, live) {
315
+ if (!ok || live?.ok === false) return 1
316
+ if (live && live.ok !== true) return 2
317
+ return 0
318
+ }
319
+
320
+ // What a look compares to tell whether the game changed since it was last
321
+ // built (the studio's stop gate measures it the same way): every file under
322
+ // src/ and assets/, game.config.json and scene.json, by size and time.
323
+ const TRACKED_DIRS = ['src', 'assets']
324
+ const TRACKED_FILES = ['game.config.json', 'scene.json']
325
+ const UNTRACKED = new Set(['node_modules', '.git', '.nowhere', 'dist', '.DS_Store'])
326
+
327
+ async function filesUnder(root, rel, out) {
328
+ let entries
329
+ try {
330
+ entries = await fsp.readdir(path.join(root, rel), { withFileTypes: true })
331
+ } catch {
332
+ return out
333
+ }
334
+ for (const e of entries) {
335
+ if (UNTRACKED.has(e.name)) continue
336
+ const child = `${rel}/${e.name}`
337
+ if (e.isDirectory()) await filesUnder(root, child, out)
338
+ else if (e.isFile()) out.push(child)
339
+ if (out.length > 20_000) break
340
+ }
341
+ return out
342
+ }
343
+
344
+ /** sha1 over the sorted "path:size:mtime" of the game's files. */
345
+ export async function fingerprint(root) {
346
+ const files = []
347
+ for (const dir of TRACKED_DIRS) await filesUnder(root, dir, files)
348
+ files.push(...TRACKED_FILES)
349
+ const lines = []
350
+ for (const rel of files.sort()) {
351
+ try {
352
+ const s = await fsp.stat(path.join(root, rel))
353
+ lines.push(`${rel}:${s.size}:${s.mtimeMs}`)
354
+ } catch {
355
+ // not there
356
+ }
357
+ }
358
+ return createHash('sha1').update(lines.join('\n')).digest('hex')
359
+ }
@@ -0,0 +1,131 @@
1
+ // Publishing from the CLI or the MCP server: the studio's own sequence
2
+ // (vendor/publish.cjs: schema, build, gates, budgets, what the live server
3
+ // and player can do, a commit, one request),
4
+ // signed in through account.mjs. The planet's picture and splat come from the
5
+ // preview page, as the studio takes them from its viewport.
6
+ //
7
+ // A planet goes up with its splat or not at all (the creator, 2026-11-15):
8
+ // the web world shows a planet only as the splat inside its glass. The splat
9
+ // is baked from the space running in the preview, so with no preview there
10
+ // is no publish, and a bake that gives nothing three times publishes nothing.
11
+
12
+ import fsp from 'node:fs/promises'
13
+ import path from 'node:path'
14
+ import { account } from './account.mjs'
15
+ import { publishModule } from './project.mjs'
16
+ import { schema } from './resources.mjs'
17
+
18
+ /** Long edges the planet's picture is tried at, largest first, and the
19
+ * server's budget for it (LIMITS.previewKb in @nowhere/schema). */
20
+ const PICTURE_EDGES = [2560, 1600, 1024, 768, 512]
21
+ const PREVIEW_BYTES = 1024 * 1024
22
+ /** Times the preview is asked for a still before it is given up on. */
23
+ const PICTURE_TRIES = 5
24
+ /** Bakes of the splat before the publish is given up on, and the wait
25
+ * between two: a space still bringing its files in can come out empty
26
+ * (as the studio does, store.ts runPublish). */
27
+ export const SPLAT_TRIES = 3
28
+ export const SPLAT_RETRY_MS = 2500
29
+ /** How long one bake is waited for: the bake's own limit is a minute. */
30
+ const BAKE_WAIT_MS = 120_000
31
+
32
+ /** What the publish says when there is no preview to bake the splat in. */
33
+ export const NO_PREVIEW_SPLAT =
34
+ "A planet is published with its splat, and the splat is baked from the space running in the preview, which could not be opened here (it runs in Google Chrome or Chromium). Open the preview (oda dev) and publish again; nothing was published."
35
+ /** What the publish says when the preview gave no splat. */
36
+ export const NO_SPLAT =
37
+ "The planet's world (its splat) could not be made in the preview, so nothing was published. Let the space finish showing in the preview, then publish again."
38
+
39
+ const SAY = {
40
+ checking: 'Checking the project…',
41
+ committing: 'Committing it…',
42
+ uploading: 'Uploading…',
43
+ verifying: 'Oda is checking it…',
44
+ }
45
+
46
+ /**
47
+ * { state: 'done', result } or { state: 'failed' | 'signin', error, findings }.
48
+ * `using` stands in for the account, the publish module, the schema and the
49
+ * wait between bakes (a check's fakes); left out, the real ones.
50
+ */
51
+ export async function publishProject(root, { preview = null, say = () => {}, using = {} } = {}) {
52
+ // Signed in first: there is no point taking pictures for a publish that
53
+ // cannot happen.
54
+ if (!(await (using.account ?? account()).getAccessToken())) return { state: 'signin', error: 'Not signed in to Oda.' }
55
+ const publish = using.publish ?? publishModule()
56
+ const wait = using.wait ?? ((ms) => new Promise((r) => setTimeout(r, ms)))
57
+
58
+ if (!preview || !(await preview.ensurePage(20_000).catch(() => false))) {
59
+ return { state: 'failed', error: NO_PREVIEW_SPLAT }
60
+ }
61
+
62
+ say('Taking the planet’s picture and its splat from the preview…')
63
+ try {
64
+ // As the studio does (splatBaker.ts): smaller until it fits the server's
65
+ // budget, since one over it goes up with no picture at all.
66
+ let m = null
67
+ for (const longEdge of PICTURE_EDGES) {
68
+ // A page that has only just mounted the game answers no still for a
69
+ // few seconds; asked once, the picture already on disk went up.
70
+ for (let tries = 0; tries < PICTURE_TRIES && !m; tries++) {
71
+ if (tries) await wait(2000)
72
+ const { png } = await preview.request('preview', { longEdge }, 30_000)
73
+ m = /^data:image\/png;base64,(.+)$/.exec(png ?? '')
74
+ }
75
+ if (!m) {
76
+ say('(the preview gave no picture; the one already on disk goes up)')
77
+ break
78
+ }
79
+ if (Buffer.byteLength(m[1], 'base64') <= PREVIEW_BYTES) break
80
+ if (longEdge === PICTURE_EDGES[PICTURE_EDGES.length - 1]) break
81
+ m = null
82
+ say(`(the picture at ${longEdge} px is over ${PREVIEW_BYTES / 1024} KB; taking it smaller)`)
83
+ }
84
+ if (m && Buffer.byteLength(m[1], 'base64') <= PREVIEW_BYTES) {
85
+ await fsp.mkdir(path.join(root, '.nowhere'), { recursive: true })
86
+ await fsp.writeFile(path.join(root, '.nowhere', 'preview.png'), Buffer.from(m[1], 'base64'))
87
+ }
88
+ } catch (err) {
89
+ say(`(no new picture: ${err.message})`)
90
+ }
91
+ // The splat, checked as the server will check it: one that would not be
92
+ // taken is no splat.
93
+ const { checkSplat } = using.schema ?? (await schema())
94
+ let bytes = null
95
+ let why = null
96
+ for (let attempt = 0; attempt < SPLAT_TRIES && !bytes; attempt++) {
97
+ if (attempt > 0) {
98
+ say(`(no splat yet${why ? `: ${why}` : ''}; baking again)`)
99
+ await wait(SPLAT_RETRY_MS)
100
+ }
101
+ try {
102
+ const { splat } = await preview.request('bake', {}, BAKE_WAIT_MS)
103
+ const baked = splat ? Buffer.from(splat, 'base64') : null
104
+ const verdict = baked ? checkSplat(new Uint8Array(baked.buffer, baked.byteOffset, baked.byteLength)) : null
105
+ if (verdict?.ok) bytes = baked
106
+ else why = baked ? `the bake is ${verdict?.error ?? 'not a splat'}` : 'the bake gave nothing'
107
+ } catch (err) {
108
+ why = err.message
109
+ }
110
+ }
111
+ if (!bytes) return { state: 'failed', error: why ? `${NO_SPLAT} (Last try: ${String(why).replace(/\.$/, '')}.)` : NO_SPLAT }
112
+ await publish.writeSplat(root, bytes)
113
+
114
+ return publish.run({
115
+ root,
116
+ onProgress: (p) => {
117
+ if (SAY[p.state]) say(SAY[p.state])
118
+ },
119
+ })
120
+ }
121
+
122
+ /** The outcome as lines for a terminal or a tool reply. */
123
+ export function describeOutcome(outcome) {
124
+ if (outcome.state === 'done') {
125
+ const r = outcome.result ?? {}
126
+ return { ok: true, text: `Published "${r.title}" (version ${r.version}). It is a planet now: ${r.url}` }
127
+ }
128
+ if (outcome.state === 'signin') return { ok: false, text: 'Not signed in to Oda. Run `oda login` (it opens the browser), then publish again.' }
129
+ const findings = (outcome.findings ?? []).map((f) => `- ${f.path ? `${f.path}: ` : ''}${f.message}`)
130
+ return { ok: false, text: [outcome.error ?? 'Publishing failed.', ...findings].join('\n') }
131
+ }
@@ -0,0 +1,50 @@
1
+ // Where the package keeps what it ships beside its code. scripts/build.mjs
2
+ // fills these from the rest of the engine before a release:
3
+ //
4
+ // vendor/ the studio's own build, sign-in and publish modules
5
+ // (apps/studio/electron), with the list of what three and
6
+ // the SDK export that the build checks imports against
7
+ // (gameExports.json), the agent's eyes (eyes.mjs, the
8
+ // studio agent's nw_view, nw_play, nw_eval, nw_logs and
9
+ // nw_status), the schema package's build, and the SDK's guide,
10
+ // so a game made here is checked, seen and published by
11
+ // exactly the code the studio uses
12
+ // web-dist/ the preview page (web/), built
13
+ // template/ the starter project (apps/studio/templates/blank)
14
+
15
+ import { createRequire } from 'node:module'
16
+ import { existsSync } from 'node:fs'
17
+ import path from 'node:path'
18
+ import { fileURLToPath, pathToFileURL } from 'node:url'
19
+
20
+ const here = path.dirname(fileURLToPath(import.meta.url))
21
+ export const PKG = path.resolve(here, '..')
22
+ export const VENDOR = path.join(PKG, 'vendor')
23
+ export const WEB = path.join(PKG, 'web-dist')
24
+ export const TEMPLATE = path.join(PKG, 'template')
25
+ export const DOCS = path.join(VENDOR, 'DOCS.md')
26
+
27
+ const require = createRequire(import.meta.url)
28
+
29
+ /** A vendored CommonJS module (auth.cjs, publish.cjs, git.cjs, build.cjs). */
30
+ export function vendor(name) {
31
+ const file = path.join(VENDOR, name)
32
+ if (!existsSync(file)) throw new Error(`This copy of oda-engine is missing ${path.join('vendor', name)}. Reinstall it, or run its build in a checkout.`)
33
+ return require(file)
34
+ }
35
+
36
+ /** A vendored ES module (eyes.mjs). */
37
+ export async function vendorModule(name) {
38
+ const file = path.join(VENDOR, name)
39
+ if (!existsSync(file)) throw new Error(`This copy of oda-engine is missing ${path.join('vendor', name)}. Reinstall it, or run its build in a checkout.`)
40
+ return import(pathToFileURL(file).href)
41
+ }
42
+
43
+ let schemaModule = null
44
+ /** The schema package: validation, defaults, the JSON Schema, the publish gates. */
45
+ export async function schema() {
46
+ schemaModule ??= import(pathToFileURL(path.join(VENDOR, 'schema', 'dist', 'index.js')).href)
47
+ return schemaModule
48
+ }
49
+
50
+ export const VERSION = JSON.parse((await import('node:fs')).readFileSync(path.join(PKG, 'package.json'), 'utf8')).version