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,599 @@
1
+ import { z } from 'zod';
2
+ import { type GameConfigT } from './config.js';
3
+ import { type SceneDocT } from './scene.js';
4
+ import { type AssetKind, type AssetLockT, type PublishLockT } from './assets.js';
5
+ import { type SplatCheck } from './publish.js';
6
+ /** The publish contract this package speaks. */
7
+ export declare const PUBLISH_CONTRACT = 4;
8
+ /** The contract that first takes config.player's scale (speed, run,
9
+ * eyeHeight, fov). A server from before it refuses the fields as unknown,
10
+ * and a player from before it walks at its own 8 m/s whatever they say, so
11
+ * nobody offers 'player-scale' until PUBLISH_CONTRACT reaches it: until then
12
+ * a planet that sets them is refused before anything is uploaded, with words
13
+ * that say why, instead of by the function as a field it does not know. */
14
+ export declare const PLAYER_SCALE_CONTRACT = 4;
15
+ /** The fields of config.player that make a planet need 'player-scale'. */
16
+ export declare const PLAYER_SCALE_KEYS: readonly ["speed", "run", "eyeHeight", "fov"];
17
+ /** The contract that first takes a splat environment (a .spz file, which the
18
+ * game's code draws with ctx.assets.splat). A server from before it refuses
19
+ * the file as a kind it does not know, and a player from before it has no
20
+ * GaussianSplat to draw it with (three r186, in the player's loader@1.js),
21
+ * so nobody offers 'splats' until PUBLISH_CONTRACT reaches it: until then a
22
+ * planet that carries one is refused before anything is uploaded, in words
23
+ * that say why. */
24
+ export declare const SPLATS_CONTRACT = 4;
25
+ /** Everything a side of the contract may be able to do. A closed list: the
26
+ * kinds of file, and the decoders some of them need beyond the kind's own
27
+ * (meshopt beside models, KTX2 beside textures), the config features an
28
+ * older side drops, the physical sky, which an older side's schema refuses
29
+ * and its player cannot draw, the credits a CC BY file needs shown, and the
30
+ * server's dry run. */
31
+ export declare const CAPABILITIES: readonly ["models", "meshopt", "textures", "ktx2", "hdri", "audio", "lut", "splats", "ledger", "look", "player-scale", "physical-sky", "open-world", "drawn-look", "items", "credits", "dry-run"];
32
+ export type Capability = (typeof CAPABILITIES)[number];
33
+ /** The capability a file of each kind needs. A .ktx2 texture needs 'ktx2'
34
+ * as well, since it takes a transcoder the other textures do not, and a
35
+ * model that requires a decoder (GLTF_EXTENSION_CAPABILITY) needs that. */
36
+ export declare const KIND_CAPABILITY: Record<AssetKind, Capability>;
37
+ /** What a server built from this package takes. KTX2 and meshopt only where
38
+ * its player decodes them (DECODERS_LIVE, decision D1): without the decoder
39
+ * a planet of them would publish and draw nothing, so nobody offers them.
40
+ * The player's scale only from PLAYER_SCALE_CONTRACT on, and splats from
41
+ * SPLATS_CONTRACT on. Credits only where the planet page shows them
42
+ * (CREDITS_SHOWN, decision D2). A physical sky is offered by a server and a
43
+ * player built from this package, which draws it. A side built before any
44
+ * of these does not list it, and a client refuses a planet that needs it
45
+ * with the older-side sentence before anything is uploaded. */
46
+ export declare const SERVER_CAPABILITIES: readonly Capability[];
47
+ /** What a player built from this package plays: everything the server takes
48
+ * but the dry run. 'ledger' here is the files the ledger lets travel, served
49
+ * to the game's own code (ctx.assets) from the manifest's list; 'credits'
50
+ * is the manifest's credit lines, shown on the planet's page. */
51
+ export declare const PLAYER_CAPABILITIES: readonly Capability[];
52
+ /** What to assume of a server or a player that says nothing about itself:
53
+ * one from before contract 3, which takes the models a scene places and
54
+ * nothing else for certain. */
55
+ export declare const LEGACY_CAPABILITIES: readonly Capability[];
56
+ /** The glTF extensions a player needs a decoder for, and the capability
57
+ * each one needs. KHR_meshopt_compression is EXT_meshopt_compression as
58
+ * Khronos ratified it; three's GLTFLoader reads both with the one decoder. */
59
+ export declare const GLTF_EXTENSION_CAPABILITY: Readonly<Record<string, Capability>>;
60
+ /**
61
+ * The glTF extensions a model file requires (its extensionsRequired), read
62
+ * from a GLB's JSON chunk or a .gltf's text: what a player must decode to
63
+ * draw it at all. An extension a file only uses is not here: glTF says such
64
+ * a file carries a fallback (a PNG beside the KTX2, plain geometry beside
65
+ * the compressed), which a player without the decoder draws instead.
66
+ *
67
+ * A GLB needs only its first 20 bytes and its JSON chunk, so a caller may
68
+ * pass that much of it rather than the whole file. Answers null for bytes
69
+ * that are not glTF (an OBJ, an FBX, a GLB cut short inside its JSON), and
70
+ * the names it found, each once, for one that is: at most 32, those that
71
+ * need a decoder (GLTF_EXTENSION_CAPABILITY) first.
72
+ */
73
+ export declare function gltfExtensionsRequired(input: Uint8Array | ArrayBuffer): string[] | null;
74
+ /** The capabilities a model's required extensions need, in CAPABILITIES
75
+ * order. An extension three's loader reads without a decoder of its own
76
+ * (KHR_mesh_quantization, KHR_texture_transform, the KHR_materials_*) is
77
+ * not one. */
78
+ export declare function extensionNeeds(extensionsRequired: readonly string[] | null | undefined): Capability[];
79
+ export interface NeedsInput {
80
+ /** The files that travel with the planet: paths, or admitted files with
81
+ * the reason each one travels (admitUploads) and, for a model, the glTF
82
+ * extensions it requires (gltfExtensionsRequired). */
83
+ uploads?: readonly (string | {
84
+ path: string;
85
+ reason?: string;
86
+ extensionsRequired?: readonly string[];
87
+ })[];
88
+ /** game.config.json, validated or not: it is read by plain property access. */
89
+ config?: unknown;
90
+ /** The ledger that travels with it, if one does: any value but null and
91
+ * undefined counts as one. */
92
+ ledger?: unknown;
93
+ /** The game's code, for the files it loads by name (collectCodeAssets). */
94
+ code?: string | null;
95
+ }
96
+ /**
97
+ * What a planet needs of the server that takes it and the player that plays
98
+ * it, in CAPABILITIES order: one per kind of file it carries ('splats' for a
99
+ * .spz splat environment), 'ktx2' for a KTX2 texture, 'hdri' for an HDRI
100
+ * sky, 'lut' for a LUT, and:
101
+ *
102
+ * ledger a ledger travels with it and a file goes up because of it: one
103
+ * the scene does not place and the config does not name, or one
104
+ * the game's code loads. Those reach the code through ctx.assets,
105
+ * which a player from before contract 2 does not have, and a
106
+ * server from before it refuses them. A ledger beside nothing but
107
+ * placed models needs nothing of either side: an older server
108
+ * takes the models without reading it, and the player draws them
109
+ * without ctx.assets. An upload given as a bare path has no
110
+ * reason, so it counts.
111
+ * look a look block with anything in it, or a fog mode, density or
112
+ * height, which an older side would drop. An empty look block (the
113
+ * blank template's) is not a need: all it changes is the tone curve
114
+ * (AgX, where no block draws Neutral), and an older side shows the
115
+ * planet the way it shows every planet from before the look.
116
+ * player-scale config.player with a speed, run, eyeHeight or fov. A
117
+ * spawn and a yaw alone are not one: every side has taken those.
118
+ * physical-sky
119
+ * a sky of kind physical: a server from before it refuses the
120
+ * config, and a player from before it cannot draw it.
121
+ * drawn-look
122
+ * a look that draws with a technique of look.style (an outline,
123
+ * bands, hatching, halftone, paint, paper, pixels): a server from
124
+ * before it refuses the config, and a player from before it would
125
+ * show the planet as a photograph of itself.
126
+ * items
127
+ * a list of items a visitor can take away: a server from before it
128
+ * refuses the config, and a player from before it gives nothing.
129
+ * ktx2, meshopt
130
+ * a .ktx2 texture, or a model that requires KHR_texture_basisu
131
+ * (ktx2) or EXT_ or KHR_meshopt_compression (meshopt): a player
132
+ * from before contract 4 has no decoder for them and draws the
133
+ * model as nothing. A model's extensions are read from its bytes
134
+ * (gltfExtensionsRequired) by whoever has them: the client on its
135
+ * disk, the function on what it was sent; a path alone says none.
136
+ * credits a file that travels whose licence asks for a visible credit (CC
137
+ * BY), by the ledger that travels with it: a server from before
138
+ * contract 4 refuses the file, and a player from before it does
139
+ * not show the credit.
140
+ */
141
+ export declare function planetNeeds(input: NeedsInput): Capability[];
142
+ /** The needs the other side does not offer, in the order they were needed,
143
+ * each once. Strings, not Capability: a newer side may name one this
144
+ * package has never heard of, and that one is missing too. */
145
+ export declare function missingCapabilities(needs: readonly string[], offered: readonly string[]): string[];
146
+ /** A capability in words ("textures", "an asset ledger"); one this package
147
+ * does not know is its own name. */
148
+ export declare function capabilityName(capability: string): string;
149
+ export interface OlderSentenceOptions {
150
+ /** Who is newer: "this studio" unless given ("the nowhere CLI"). */
151
+ than?: string;
152
+ /** false leaves off "Nothing was uploaded.", for a check that never meant to. */
153
+ nothingUploaded?: boolean;
154
+ }
155
+ /** The sentence a creator reads when the server or the player is older than
156
+ * what they are publishing with:
157
+ *
158
+ * The nowhere server is older than this studio: it does not take textures
159
+ * yet. Nothing was uploaded.
160
+ * The nowhere player is older than this studio: a planet with textures or
161
+ * look settings would not play there yet. Nothing was uploaded. */
162
+ export declare function olderSentence(side: 'server' | 'player', missing: readonly string[], opts?: OlderSentenceOptions): string;
163
+ /** What the player shows in place of a planet that needs more than it plays:
164
+ * "This planet needs a newer nowhere player: textures." */
165
+ export declare function playerNotice(missing: readonly string[]): string;
166
+ /** What @nowhere/sdk exports in the player of a site from before contract 3:
167
+ * /play/sdk@1.js as world 0de0986 serves it (read 2026-10-23). It is what a
168
+ * player that says nothing about itself is taken to have, as
169
+ * LEGACY_CAPABILITIES is for what it plays. It lacks seven names the SDK
170
+ * has gained since (createAssetHost, createLook, listenToThree, pickTier,
171
+ * watchMaterials, LOOK_PIPELINE_VERSION, WEBGL_ONLY) and still has DAYLIGHT,
172
+ * which the SDK no longer exports: the surface shrinks as well as grows, so
173
+ * it is compared name by name, never by a count or a level. Marked pure so
174
+ * the player's sdk@1.js, which bundles this package, leaves it out. */
175
+ export declare const LEGACY_SDK_EXPORTS: readonly string[];
176
+ /** The names a planet's code reads from @nowhere/sdk (checkBundle's sdk)
177
+ * that the player's SDK does not export, in the order they were read, each
178
+ * once. */
179
+ export declare function missingSdkExports(used: readonly string[], exported: readonly string[]): string[];
180
+ /** The sentence a creator reads when the player's SDK lacks names the
181
+ * planet's code reads:
182
+ *
183
+ * The nowhere player is older than this studio: its @nowhere/sdk has no
184
+ * listenToThree yet, which this planet's code uses. Nothing was uploaded. */
185
+ export declare function olderSdkSentence(missing: readonly string[], opts?: OlderSentenceOptions): string;
186
+ /** GET on the publish function. Capabilities are plain strings so a newer
187
+ * server's list still parses here; what this side does not know is simply
188
+ * never needed by it. */
189
+ export declare const PublishInfo: z.ZodObject<{
190
+ schema: z.ZodLiteral<"nowhere/publish-info@1">;
191
+ contract: z.ZodNumber;
192
+ capabilities: z.ZodArray<z.ZodString>;
193
+ limits: z.ZodRecord<z.ZodString, z.ZodNumber>;
194
+ build: z.ZodObject<{
195
+ engine: z.ZodString;
196
+ world: z.ZodString;
197
+ }, z.core.$strip>;
198
+ }, z.core.$strip>;
199
+ export type PublishInfoT = z.infer<typeof PublishInfo>;
200
+ /** /play/capabilities.json on the site: what its player plays. */
201
+ export declare const PlayerInfo: z.ZodObject<{
202
+ schema: z.ZodLiteral<"nowhere/player-info@1">;
203
+ contract: z.ZodNumber;
204
+ capabilities: z.ZodArray<z.ZodString>;
205
+ sdk: z.ZodOptional<z.ZodArray<z.ZodString>>;
206
+ build: z.ZodObject<{
207
+ engine: z.ZodString;
208
+ world: z.ZodString;
209
+ }, z.core.$strip>;
210
+ }, z.core.$strip>;
211
+ export type PlayerInfoT = z.infer<typeof PlayerInfo>;
212
+ /** The numbers a server enforces, flat: LIMITS and every kind's ceiling. */
213
+ export declare function publishLimits(): Record<string, number>;
214
+ /** The publish function's answer to GET, for this contract. */
215
+ export declare function publishInfo(build?: {
216
+ engine?: string;
217
+ world?: string;
218
+ }): PublishInfoT;
219
+ /** The site's /play/capabilities.json, for this contract. `sdk` is what the
220
+ * site's sdk@1.js exports (read from the chunk it serves), left out when
221
+ * not given. */
222
+ export declare function playerInfo(build?: {
223
+ engine?: string;
224
+ world?: string;
225
+ }, extra?: {
226
+ sdk?: readonly string[];
227
+ }): PlayerInfoT;
228
+ export declare function parsePublishInfo(raw: unknown): PublishInfoT | null;
229
+ export declare function parsePlayerInfo(raw: unknown): PlayerInfoT | null;
230
+ /** What one GET found out about the other side:
231
+ * current it answered with its info
232
+ * legacy it answered, without info: a side from before contract 3
233
+ * (the function's 405, a missing file's 404, a site that
234
+ * rewrote the path to its page), which takes LEGACY_CAPABILITIES
235
+ * unknown nothing to go on (no network, a gateway's 401, a 5xx): the
236
+ * caller goes on as it did before there was a handshake, and
237
+ * says the check was not made */
238
+ export type InfoReading<T> = {
239
+ state: 'current';
240
+ info: T;
241
+ capabilities: readonly string[];
242
+ } | {
243
+ state: 'legacy';
244
+ capabilities: readonly string[];
245
+ } | {
246
+ state: 'unknown';
247
+ reason: string;
248
+ };
249
+ /** A reply to GET on the publish function (status, and its JSON or null). */
250
+ export declare function readPublishInfoReply(status: number, body: unknown): InfoReading<PublishInfoT>;
251
+ /** A reply to GET /play/capabilities.json (status, and its JSON or null). */
252
+ export declare function readPlayerInfoReply(status: number, body: unknown): InfoReading<PlayerInfoT>;
253
+ /** What @nowhere/sdk exports in a player, by what it said about itself: its
254
+ * info's list, LEGACY_SDK_EXPORTS for a site from before contract 3, and
255
+ * null when it is not known (no answer, or a player that does not list
256
+ * them), which compares nothing. */
257
+ export declare function playerSdkOf(reading: InfoReading<PlayerInfoT> | null | undefined): readonly string[] | null;
258
+ /** A file under assets/: its path, its size and, when the sender knows it,
259
+ * its SHA-256 (checkLedger compares it with the ledger's when given) and,
260
+ * for a model, the glTF extensions it requires (gltfExtensionsRequired),
261
+ * which say whether it needs 'ktx2' or 'meshopt' of the player. */
262
+ export interface AssetFile {
263
+ path: string;
264
+ bytes: number;
265
+ sha256?: string;
266
+ extensionsRequired?: string[];
267
+ }
268
+ /** Why a file travels, first match in this order: the scene places it, the
269
+ * ledger lists it for publishing, the config names it (an HDRI sky, a LUT),
270
+ * the game's code names it. */
271
+ export type AdmitReason = 'scene' | 'ledger' | 'config' | 'code';
272
+ export interface AdmittedFile extends AssetFile {
273
+ kind: AssetKind;
274
+ reason: AdmitReason;
275
+ }
276
+ export interface AdmitProblem {
277
+ code: 'admit:path' | 'admit:duplicate' | 'admit:not-model' | 'admit:missing' | 'admit:unnamed' | 'admit:unrecorded';
278
+ path: string;
279
+ message: string;
280
+ }
281
+ /** What admission reads of a ledger: the full one (the studio's) and its
282
+ * publish view (what reaches the server) both fit. */
283
+ export interface LedgerFilesLike {
284
+ files: Record<string, {
285
+ kind?: string;
286
+ origin?: string;
287
+ publish?: boolean;
288
+ } | undefined>;
289
+ }
290
+ export interface AdmitInput {
291
+ /** 'pick': a client choosing, from the project's files, what to send (the
292
+ * studio, the CLI). 'check': a server judging what was sent. */
293
+ mode?: 'pick' | 'check';
294
+ /** scene.json as read or as sent, validated or not; undefined when there
295
+ * is none. */
296
+ scene?: unknown;
297
+ /** game.config.json, validated or not. */
298
+ config?: unknown;
299
+ /** The ledger, or null when the project keeps none (or none was sent). */
300
+ ledger?: LedgerFilesLike | null;
301
+ /** pick: the built bundle, for the 'assets/...' names its code loads. */
302
+ code?: string | null;
303
+ /** pick: every file under assets/. check: every part that was sent under
304
+ * assets/, in the order it came. */
305
+ files: readonly AssetFile[];
306
+ }
307
+ export interface AdmitResult {
308
+ /** What travels, in the order it was admitted. */
309
+ uploads: AdmittedFile[];
310
+ /** Each reason the set cannot go up as it is. Empty when it can. */
311
+ problems: AdmitProblem[];
312
+ /** pick: files under assets/ that nothing names, which stay on the machine. */
313
+ left: string[];
314
+ /** pick: files the ledger lists for publishing that are not in the
315
+ * project. Left out rather than refused: a deleted import is not the
316
+ * planet's problem. */
317
+ absent: string[];
318
+ /** The models the scene places (collectSceneAssets). */
319
+ sceneAssets: string[];
320
+ }
321
+ /** The files the game's code names as plain strings ('assets/grass.png'),
322
+ * which it loads through ctx.assets: paths a planet may carry, sorted, each
323
+ * once. A path the code builds while it runs is not seen here. */
324
+ export declare function collectCodeAssets(code: string): string[];
325
+ /**
326
+ * Which files travel with a publish: the one rule, for the client that picks
327
+ * them and the server that takes them.
328
+ *
329
+ * a model when the scene places it, or the ledger records it
330
+ * any other when the ledger records it, or the config names it
331
+ *
332
+ * A client picks, on top of that, every file the ledger lists for publishing
333
+ * (publish not false) except the 'legacy' ones, the files that sat in
334
+ * assets/ before the ledger began: those travel only when the scene, the
335
+ * config or the code names them, so starting a ledger never adds files an
336
+ * older planet did not use. A file the code names travels when the ledger
337
+ * records it; one it does not record is a problem (a project with no ledger
338
+ * at all starts one, which records it). A server takes what was sent when
339
+ * the rule above admits it, and refuses the rest: a part nothing names is a
340
+ * stranger's file in a public bucket.
341
+ *
342
+ * Both refuse a scene that places something other than a model, and a path
343
+ * that could climb out of assets/ (isPublishablePath). Sizes are
344
+ * assetSizeProblems' business and licences checkLedger's.
345
+ */
346
+ export declare function admitUploads(input: AdmitInput): AdmitResult;
347
+ /** The publish view of a ledger (publishLock), cut to the files that travel:
348
+ * what the server is sent beside them. */
349
+ export declare function publishLockFor(lock: AssetLockT, paths: Iterable<string>): PublishLockT;
350
+ /** Keys the config schema once had and drops on purpose, so a project from
351
+ * before still opens: the deploy block, and look.preset from before there
352
+ * were no presets. Never reported as unknown. */
353
+ export declare const RETIRED_CONFIG_KEYS: readonly string[];
354
+ /** The keys a zod parse dropped: every key of an object in `raw` that is
355
+ * missing from the same object in `parsed`, at any depth (look, fog, sky,
356
+ * player, a scene's objects), as dotted paths ("look.toneMap",
357
+ * "objects.3.tint"). Keys the parse added (defaults) are not reported.
358
+ * `ignore` takes dotted paths, with * standing for any array index. */
359
+ export declare function strippedKeys(raw: unknown, parsed: unknown, opts?: {
360
+ ignore?: readonly string[];
361
+ }): string[];
362
+ /** The keys of a game.config.json this schema does not know, retired ones
363
+ * aside. Empty for a config that does not parse: its findings say more. */
364
+ export declare function unknownConfigKeys(raw: unknown): string[];
365
+ /** The same for scene.json, against the parse before validateScene fills in
366
+ * kinds and drops a normalize that is not false. One path per key, with *
367
+ * for the object's index, so two thousand placements say it once. */
368
+ export declare function unknownSceneKeys(raw: unknown): string[];
369
+ /** One publish request, as the function reads it: the documents parsed from
370
+ * JSON (the function answers JSON that does not parse itself), the files
371
+ * under assets/ as their names and sizes. A dry run sends the same thing
372
+ * with the files as descriptors instead of bytes. */
373
+ export interface PublishRequest {
374
+ /** game.config.json, parsed. */
375
+ config: unknown;
376
+ /** Its size as it travels, in bytes. Default: the validated config as the
377
+ * studio sends it (JSON.stringify(config, null, 2)). */
378
+ configBytes?: number;
379
+ /** main.js. */
380
+ bundle: string;
381
+ /** Its size as it travels. Default: the UTF-8 length of `bundle`. */
382
+ bundleBytes?: number;
383
+ /** scene.json, parsed; undefined when none was sent. */
384
+ scene?: unknown;
385
+ /** assets.lock.json's publish view, parsed; undefined when none was sent. */
386
+ ledger?: unknown;
387
+ ledgerBytes?: number;
388
+ /** The parts under assets/, in the order they came. */
389
+ files: readonly AssetFile[];
390
+ /** preview.png: its size, and false when it does not start like a PNG. */
391
+ preview?: {
392
+ bytes: number;
393
+ png?: boolean;
394
+ } | null;
395
+ /** splat.bin: its size, and checkSplat's verdict when the bytes are there. */
396
+ splat?: {
397
+ bytes: number;
398
+ verdict?: SplatCheck;
399
+ } | null;
400
+ }
401
+ export interface PublishCheckOptions {
402
+ /** What this server offers (SERVER_CAPABILITIES). Given, a planet that
403
+ * needs more is refused with contract_mismatch; the function gives it for
404
+ * a request that states its contract, and leaves it out for one from a
405
+ * studio before contract 3, which is judged exactly as before. */
406
+ offered?: readonly string[];
407
+ /** The needs the request states (its 'needs' field). */
408
+ declaredNeeds?: readonly string[];
409
+ /** 'refuse' (the default): a config or scene key this schema does not know
410
+ * is refused with unknown_fields, since taking the planet would publish
411
+ * less of it than was sent. 'ignore' drops them, as before. */
412
+ unknownFields?: 'refuse' | 'ignore';
413
+ }
414
+ /** One problem with a request. `error` is the code the function answers
415
+ * with (bad_request, budget_exceeded, schema, ledger, contract:*,
416
+ * unknown_fields, contract_mismatch); `code` the finer one. */
417
+ export interface PublishFinding {
418
+ error: string;
419
+ code: string;
420
+ path?: string;
421
+ message: string;
422
+ }
423
+ /** What the function answers a refused request with. */
424
+ export interface PublishRefusal {
425
+ status: number;
426
+ body: {
427
+ error: string;
428
+ } & Record<string, unknown>;
429
+ }
430
+ export interface PublishVerdict {
431
+ ok: boolean;
432
+ /** The first refusal in the function's order, as it answers it. */
433
+ refusal: PublishRefusal | null;
434
+ /** Every problem found, in that order, for a dry run or `nowhere check`. */
435
+ findings: PublishFinding[];
436
+ /** The validated config: what is stored. */
437
+ config: GameConfigT | null;
438
+ /** The validated scene, when one was sent and it is valid. */
439
+ scene: SceneDocT | null;
440
+ sceneSent: boolean;
441
+ /** The publish view, when one was sent and it parses. */
442
+ lock: PublishLockT | null;
443
+ sceneAssets: string[];
444
+ uploads: AdmittedFile[];
445
+ /** What this planet needs (planetNeeds on what was sent). */
446
+ needs: Capability[];
447
+ /** The shim keys the bundle reaches for (checkBundle). */
448
+ requires: string[];
449
+ /** The names the bundle reads from @nowhere/sdk (checkBundle). */
450
+ sdk: string[];
451
+ /** Config and scene keys this schema does not know, retired ones aside. */
452
+ unknownFields: string[];
453
+ /** Every byte under assets/ that was sent. */
454
+ assetBytes: number;
455
+ }
456
+ /** The UTF-8 length of a string, without TextEncoder (this package's lib is
457
+ * ES2022 alone, and it runs in Deno, Node and the browser). */
458
+ export declare function utf8Bytes(text: string): number;
459
+ /**
460
+ * Everything the publish function checks on a request before it records
461
+ * anything, in the order it checks it, as a pure function of the request.
462
+ * The function answers `refusal` when there is one, its dry run answers
463
+ * `findings`, and a client runs it on the request it is about to send. The
464
+ * sentences are the function's, word for word, so a studio from before this
465
+ * file reads the same answers it always has.
466
+ *
467
+ * needs the request states that this server does not offer contract_mismatch
468
+ * a part's path, a part sent twice bad_request
469
+ * one file over its kind's ceiling budget_exceeded
470
+ * main.js, game.config.json, preview.png, splat.bin sizes budget_exceeded
471
+ * splat.bin's header schema
472
+ * the config schema
473
+ * a config key this schema does not know unknown_fields
474
+ * the ledger's size and its publish view budget_exceeded, schema
475
+ * the scene, then a scene key it does not know schema, unknown_fields
476
+ * which files may travel (admitUploads) bad_request
477
+ * the ledger's verdict on each ledger
478
+ * the sounds and the files in total budget_exceeded
479
+ * the bundle's gates contract:*
480
+ * needs this planet has that this server does not offer contract_mismatch
481
+ */
482
+ export declare function checkPublish(req: PublishRequest, opts?: PublishCheckOptions): PublishVerdict;
483
+ /** The 'files' part of a dry run: the files under assets/ as descriptors,
484
+ * so a client can ask whether a planet would be taken without sending it.
485
+ * A model's descriptor may say the glTF extensions it requires, which the
486
+ * dry run takes at its word, as it takes the bytes: a real publish reads
487
+ * them from the file. A server from before contract 4 drops the field. */
488
+ export declare const FileDescriptors: z.ZodArray<z.ZodObject<{
489
+ path: z.ZodString;
490
+ bytes: z.ZodNumber;
491
+ sha256: z.ZodOptional<z.ZodString>;
492
+ extensionsRequired: z.ZodOptional<z.ZodArray<z.ZodString>>;
493
+ }, z.core.$strip>>;
494
+ export type FileDescriptorsT = z.infer<typeof FileDescriptors>;
495
+ export declare function parseFileDescriptors(raw: unknown): {
496
+ ok: true;
497
+ files: FileDescriptorsT;
498
+ } | {
499
+ ok: false;
500
+ error: string;
501
+ };
502
+ /** What the function answers a dry run: the verdict a real publish of the
503
+ * same request would get, and nothing written. */
504
+ export declare const DryRunAnswer: z.ZodObject<{
505
+ ok: z.ZodBoolean;
506
+ contract: z.ZodNumber;
507
+ needs: z.ZodArray<z.ZodString>;
508
+ uploads: z.ZodArray<z.ZodObject<{
509
+ path: z.ZodString;
510
+ kind: z.ZodString;
511
+ reason: z.ZodString;
512
+ bytes: z.ZodNumber;
513
+ }, z.core.$strip>>;
514
+ findings: z.ZodArray<z.ZodObject<{
515
+ error: z.ZodString;
516
+ code: z.ZodString;
517
+ path: z.ZodOptional<z.ZodString>;
518
+ message: z.ZodString;
519
+ }, z.core.$strip>>;
520
+ refusal: z.ZodNullable<z.ZodObject<{
521
+ status: z.ZodNumber;
522
+ body: z.ZodRecord<z.ZodString, z.ZodUnknown>;
523
+ }, z.core.$strip>>;
524
+ }, z.core.$strip>;
525
+ export type DryRunAnswerT = z.infer<typeof DryRunAnswer>;
526
+ export declare function dryRunAnswer(verdict: PublishVerdict): DryRunAnswerT;
527
+ export declare function parseDryRunAnswer(raw: unknown): DryRunAnswerT | null;
528
+ /** A project as a client finds it on disk, after the build. */
529
+ export interface ProjectInput {
530
+ /** game.config.json as read. */
531
+ config: unknown;
532
+ /** scene.json as read; undefined when the project has none. */
533
+ scene?: unknown;
534
+ /** assets.lock.json as read (the full ledger); undefined or null when the
535
+ * project keeps none. */
536
+ ledger?: unknown;
537
+ /** The built main.js. */
538
+ bundle: string;
539
+ /** Every file under assets/, with its SHA-256 where it is known (the
540
+ * ledger's check compares it) and each model's required glTF extensions
541
+ * (gltfExtensionsRequired), without which a model that needs a decoder
542
+ * is taken for one that does not. */
543
+ files: readonly AssetFile[];
544
+ /** What the server offers, from its info (or LEGACY_CAPABILITIES); left
545
+ * out, the server is not asked about. */
546
+ server?: readonly string[];
547
+ /** What the site's player plays, the same way. */
548
+ player?: readonly string[];
549
+ /** What the player's @nowhere/sdk exports (playerSdkOf); left out or null,
550
+ * the names the code reads are not compared. */
551
+ playerSdk?: readonly string[] | null;
552
+ }
553
+ export interface PreparedPublish {
554
+ ok: boolean;
555
+ /** Everything in the way, in the order a creator meets it: the project's
556
+ * own documents, then which files travel, then the server's check on the
557
+ * request this would send, then the player. */
558
+ findings: PublishFinding[];
559
+ config: GameConfigT | null;
560
+ /** game.config.json as it goes up: the validated config, with defaults. */
561
+ configText: string | null;
562
+ scene: SceneDocT | null;
563
+ /** scene.json as it goes up, or null when there is none. */
564
+ sceneText: string | null;
565
+ /** The ledger's publish view as it goes up, cut to what travels; null for
566
+ * a project without a ledger. */
567
+ ledgerText: string | null;
568
+ uploads: AdmittedFile[];
569
+ left: string[];
570
+ absent: string[];
571
+ needs: Capability[];
572
+ requires: string[];
573
+ /** The names the code reads from @nowhere/sdk. */
574
+ sdk: string[];
575
+ /** Keys in the project's config and scene this schema does not know: they
576
+ * are dropped from what goes up, so a client may want to say so. */
577
+ unknownKeys: string[];
578
+ /** What the server and the player lack of the planet's needs, and the
579
+ * names its code reads that the player's SDK does not export. */
580
+ missing: {
581
+ server: string[];
582
+ player: string[];
583
+ sdk: string[];
584
+ };
585
+ /** The code loads files only a ledger can carry and the project keeps
586
+ * none: the studio starts one (which records them) and prepares again. */
587
+ needsLedger: boolean;
588
+ /** The server's own check on the request this would send. */
589
+ verdict: PublishVerdict | null;
590
+ }
591
+ /**
592
+ * A client's pre-flight on a project: the documents, which files travel
593
+ * (admitUploads), the request that would go up, and checkPublish on that
594
+ * request, the very check the function will run. The studio's Publish
595
+ * button and `nowhere check` both run this, so they cannot say different
596
+ * things about the same project. Pure: reading the disk, hashing the files
597
+ * and starting a ledger are the caller's.
598
+ */
599
+ export declare function preparePublish(project: ProjectInput): PreparedPublish;