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.
- package/README.md +151 -2
- package/bin/nowhere.mjs +352 -0
- package/lib/account.mjs +57 -0
- package/lib/agentModules.mjs +57 -0
- package/lib/devServer.mjs +351 -0
- package/lib/headless.mjs +231 -0
- package/lib/headlessPreview.mjs +212 -0
- package/lib/keys.mjs +517 -0
- package/lib/make.mjs +855 -0
- package/lib/mcp.mjs +537 -0
- package/lib/open.mjs +22 -0
- package/lib/preview.mjs +87 -0
- package/lib/previewRpc.mjs +134 -0
- package/lib/project.mjs +359 -0
- package/lib/publishFlow.mjs +131 -0
- package/lib/resources.mjs +50 -0
- package/lib/rules.mjs +60 -0
- package/lib/scaffold.mjs +42 -0
- package/lib/setup.mjs +59 -0
- package/lib/tools.mjs +668 -0
- package/package.json +51 -4
- package/template/game.config.json +9 -0
- package/template/scene.json +4 -0
- package/template/src/main.ts +11 -0
- package/vendor/DOCS.md +447 -0
- package/vendor/agent/appRun.mjs +520 -0
- package/vendor/agent/assets/brief.mjs +242 -0
- package/vendor/agent/assets/collider.mjs +531 -0
- package/vendor/agent/assets/environments/index.mjs +12 -0
- package/vendor/agent/assets/environments/worldlabs.mjs +161 -0
- package/vendor/agent/assets/fetch.mjs +168 -0
- package/vendor/agent/assets/footprint.mjs +13 -0
- package/vendor/agent/assets/gltf.mjs +547 -0
- package/vendor/agent/assets/hdr.mjs +269 -0
- package/vendor/agent/assets/imageOps.mjs +171 -0
- package/vendor/agent/assets/images/codex.mjs +307 -0
- package/vendor/agent/assets/images/fal.mjs +75 -0
- package/vendor/agent/assets/images/gemini.mjs +84 -0
- package/vendor/agent/assets/images/index.mjs +25 -0
- package/vendor/agent/assets/images/openai.mjs +75 -0
- package/vendor/agent/assets/images/stability.mjs +71 -0
- package/vendor/agent/assets/images/views.mjs +31 -0
- package/vendor/agent/assets/import.mjs +1352 -0
- package/vendor/agent/assets/inspect.mjs +465 -0
- package/vendor/agent/assets/jobs.mjs +196 -0
- package/vendor/agent/assets/ktx2.mjs +290 -0
- package/vendor/agent/assets/ledger.mjs +466 -0
- package/vendor/agent/assets/net.mjs +254 -0
- package/vendor/agent/assets/prices.json +39 -0
- package/vendor/agent/assets/providers/fal.mjs +115 -0
- package/vendor/agent/assets/providers/index.mjs +22 -0
- package/vendor/agent/assets/providers/meshy.mjs +119 -0
- package/vendor/agent/assets/providers/tripo.mjs +188 -0
- package/vendor/agent/assets/sources/ambientcg.mjs +129 -0
- package/vendor/agent/assets/sources/index.mjs +23 -0
- package/vendor/agent/assets/sources/polyhaven.mjs +237 -0
- package/vendor/agent/assets/sources/polypizza.mjs +121 -0
- package/vendor/agent/assets/splat.mjs +631 -0
- package/vendor/agent/assets/targets.mjs +122 -0
- package/vendor/agent/assets/tile.mjs +261 -0
- package/vendor/agent/assets/unzip.mjs +180 -0
- package/vendor/agent/blender/cleanup.py +360 -0
- package/vendor/agent/blender/convert.py +167 -0
- package/vendor/agent/blender/find.mjs +192 -0
- package/vendor/agent/blender/nw_export.py +104 -0
- package/vendor/agent/blender/nw_rubric.py +426 -0
- package/vendor/agent/blender/run.mjs +193 -0
- package/vendor/agent/blender/runner.py +252 -0
- package/vendor/agent/blender/sheet.py +743 -0
- package/vendor/agent/depth.mjs +134 -0
- package/vendor/agent/director/board.mjs +451 -0
- package/vendor/agent/director/contracts.mjs +663 -0
- package/vendor/agent/director/director.mjs +2365 -0
- package/vendor/agent/director/estimate.mjs +200 -0
- package/vendor/agent/director/gate.mjs +802 -0
- package/vendor/agent/director/limits.json +16 -0
- package/vendor/agent/director/methods.mjs +457 -0
- package/vendor/agent/director/policy.json +33 -0
- package/vendor/agent/director/prompts.mjs +244 -0
- package/vendor/agent/director/reading.mjs +341 -0
- package/vendor/agent/director/router.mjs +184 -0
- package/vendor/agent/director/seams.mjs +243 -0
- package/vendor/agent/director/session.mjs +643 -0
- package/vendor/agent/director/store.mjs +119 -0
- package/vendor/agent/director/taskGate.mjs +110 -0
- package/vendor/agent/director/teamLedger.mjs +118 -0
- package/vendor/agent/director/triage.mjs +63 -0
- package/vendor/agent/downloads.cjs +363 -0
- package/vendor/agent/flow.mjs +78 -0
- package/vendor/agent/guard.mjs +613 -0
- package/vendor/agent/host.mjs +1736 -0
- package/vendor/agent/language.mjs +58 -0
- package/vendor/agent/ledger.mjs +360 -0
- package/vendor/agent/locale.cjs +186 -0
- package/vendor/agent/loop/capacity.mjs +74 -0
- package/vendor/agent/loop/compose.mjs +127 -0
- package/vendor/agent/loop/gate.mjs +205 -0
- package/vendor/agent/loop/judge.mjs +189 -0
- package/vendor/agent/loop/levels.mjs +273 -0
- package/vendor/agent/loop/state.mjs +358 -0
- package/vendor/agent/notes.cjs +278 -0
- package/vendor/agent/pace.mjs +258 -0
- package/vendor/agent/panels.mjs +431 -0
- package/vendor/agent/prompt.mjs +342 -0
- package/vendor/agent/reference/board.mjs +410 -0
- package/vendor/agent/reference/compose.mjs +364 -0
- package/vendor/agent/reference/decode.mjs +56 -0
- package/vendor/agent/reference/facts.mjs +1874 -0
- package/vendor/agent/reference/png.mjs +107 -0
- package/vendor/agent/reference/records.mjs +63 -0
- package/vendor/agent/reference/web.mjs +252 -0
- package/vendor/agent/roles/artist.mjs +69 -0
- package/vendor/agent/roles/builder.mjs +79 -0
- package/vendor/agent/roles/checks.mjs +223 -0
- package/vendor/agent/roles/common.mjs +188 -0
- package/vendor/agent/roles/critic.mjs +171 -0
- package/vendor/agent/roles/index.mjs +39 -0
- package/vendor/agent/roles/modeller.mjs +142 -0
- package/vendor/agent/roles/qa.mjs +58 -0
- package/vendor/agent/roles/rubrics.mjs +79 -0
- package/vendor/agent/roles/sound.mjs +69 -0
- package/vendor/agent/rounds.cjs +333 -0
- package/vendor/agent/shared.mjs +284 -0
- package/vendor/agent/stopGate.mjs +574 -0
- package/vendor/agent/subagents.mjs +129 -0
- package/vendor/agent/tools/assets.mjs +499 -0
- package/vendor/agent/tools/blender.mjs +754 -0
- package/vendor/agent/tools/cards.mjs +479 -0
- package/vendor/agent/tools/choices.mjs +479 -0
- package/vendor/agent/tools/compose.mjs +74 -0
- package/vendor/agent/tools/environment.mjs +488 -0
- package/vendor/agent/tools/eyes.mjs +733 -0
- package/vendor/agent/tools/generate.mjs +338 -0
- package/vendor/agent/tools/guide.mjs +46 -0
- package/vendor/agent/tools/harness.mjs +193 -0
- package/vendor/agent/tools/image.mjs +643 -0
- package/vendor/agent/tools/index.mjs +162 -0
- package/vendor/agent/tools/look.mjs +578 -0
- package/vendor/agent/tools/loop.mjs +858 -0
- package/vendor/agent/tools/others.mjs +123 -0
- package/vendor/agent/tools/pictures.mjs +535 -0
- package/vendor/agent/tools/reference.mjs +366 -0
- package/vendor/agent/transcripts.mjs +118 -0
- package/vendor/agent-loop.mjs +602 -0
- package/vendor/agent-plugin/.claude-plugin/plugin.json +5 -0
- package/vendor/agent-plugin/skills/art-direction/SKILL.md +82 -0
- package/vendor/agent-plugin/skills/asset-legality/SKILL.md +101 -0
- package/vendor/agent-plugin/skills/asset-sources/SKILL.md +111 -0
- package/vendor/agent-plugin/skills/blender-modeling/SKILL.md +97 -0
- package/vendor/agent-plugin/skills/look-dev/SKILL.md +104 -0
- package/vendor/agent-plugin/skills/playtesting/SKILL.md +74 -0
- package/vendor/agent-plugin/skills/reference-loop/SKILL.md +102 -0
- package/vendor/agent-plugin/skills/sound-design/SKILL.md +60 -0
- package/vendor/agent-plugin/skills/style/SKILL.md +35 -0
- package/vendor/agent-plugin/skills/tsl-r185/SKILL.md +107 -0
- package/vendor/auth.cjs +570 -0
- package/vendor/build.cjs +953 -0
- package/vendor/catalog.json +455 -0
- package/vendor/connectors.cjs +688 -0
- package/vendor/eyes.mjs +733 -0
- package/vendor/gameExports.json +1390 -0
- package/vendor/git.cjs +222 -0
- package/vendor/models.json +57 -0
- package/vendor/publish.cjs +1018 -0
- package/vendor/refBoard.cjs +301 -0
- package/vendor/schema/dist/assets.d.ts +335 -0
- package/vendor/schema/dist/assets.js +439 -0
- package/vendor/schema/dist/brief.d.ts +357 -0
- package/vendor/schema/dist/brief.js +302 -0
- package/vendor/schema/dist/common.d.ts +9 -0
- package/vendor/schema/dist/common.js +13 -0
- package/vendor/schema/dist/config.d.ts +406 -0
- package/vendor/schema/dist/config.js +355 -0
- package/vendor/schema/dist/contract.d.ts +599 -0
- package/vendor/schema/dist/contract.js +1146 -0
- package/vendor/schema/dist/index.d.ts +14 -0
- package/vendor/schema/dist/index.js +21 -0
- package/vendor/schema/dist/look.d.ts +463 -0
- package/vendor/schema/dist/look.js +681 -0
- package/vendor/schema/dist/lookStats.d.ts +230 -0
- package/vendor/schema/dist/lookStats.js +768 -0
- package/vendor/schema/dist/pilot.d.ts +32 -0
- package/vendor/schema/dist/pilot.js +44 -0
- package/vendor/schema/dist/publish.d.ts +214 -0
- package/vendor/schema/dist/publish.js +291 -0
- package/vendor/schema/dist/scene.d.ts +75 -0
- package/vendor/schema/dist/scene.js +120 -0
- package/vendor/schema/dist/skyLight.d.ts +141 -0
- package/vendor/schema/dist/skyLight.js +436 -0
- package/vendor/schema/dist/style.d.ts +131 -0
- package/vendor/schema/dist/style.js +155 -0
- package/vendor/schema/package.json +1 -0
- package/vendor/selectionPrompt.mjs +51 -0
- package/vendor/useTools.mjs +195 -0
- package/vendor/userMessage.mjs +26 -0
- package/web-dist/assets/GaussianSplatUtils-CptQkDVX.js +1 -0
- package/web-dist/assets/KTX2Loader-C53LJqss.js +2 -0
- package/web-dist/assets/SPZLoader-BQ3tjaTv.js +1 -0
- package/web-dist/assets/gaussianSplat-_9tcWegB.js +1 -0
- package/web-dist/assets/index-Baka-ZO7.js +693 -0
- package/web-dist/assets/index-CcjyyQco.css +1 -0
- package/web-dist/assets/meshopt_decoder.module-BvwdjiD3.js +1 -0
- package/web-dist/assets/zstddec.module-CfFeQW7d.js +1 -0
- package/web-dist/index.html +34 -0
package/vendor/eyes.mjs
ADDED
|
@@ -0,0 +1,733 @@
|
|
|
1
|
+
// The agent's eyes on the space: pictures of the canvas through cameras it
|
|
2
|
+
// chooses (nw_view), a hands-free walk with pictures from the visitor's eyes
|
|
3
|
+
// (nw_play), a value read off the running space (nw_eval), its console and
|
|
4
|
+
// the studio's notes about it (nw_logs), the live state of it all
|
|
5
|
+
// (nw_status, with the frame time at each tier: perf), and, for the
|
|
6
|
+
// studio's own interface only, a capture of the window
|
|
7
|
+
// (nw_studio_screenshot).
|
|
8
|
+
//
|
|
9
|
+
// Each handler asks main over ctx.rpc; main asks the viewport's probe
|
|
10
|
+
// (electron/agent/probe.cjs, src/three/agentProbe.ts), which answers from the
|
|
11
|
+
// canvas and the running space. Before a look, a project changed since the
|
|
12
|
+
// last build is built first, so a picture never shows the build before an
|
|
13
|
+
// edit.
|
|
14
|
+
|
|
15
|
+
import { createHash } from 'node:crypto'
|
|
16
|
+
import fsp from 'node:fs/promises'
|
|
17
|
+
import os from 'node:os'
|
|
18
|
+
import path from 'node:path'
|
|
19
|
+
import { z } from 'zod'
|
|
20
|
+
import { BRIEF_FILE, STYLE_FILE, lookAdvice, styleAdvice, validateBrief, validateStyle } from './schema/dist/index.js'
|
|
21
|
+
|
|
22
|
+
export const RPC_METHODS = ['build', 'status', 'view', 'play', 'eval', 'logs', 'screenshot', 'perf']
|
|
23
|
+
|
|
24
|
+
const VIEWS = ['player', 'orbit', 'closeup', 'overview', 'free']
|
|
25
|
+
const PLAY_MAX_SECONDS = 60
|
|
26
|
+
const DEG = Math.PI / 180
|
|
27
|
+
|
|
28
|
+
const vec3 = z.array(z.number()).length(3)
|
|
29
|
+
|
|
30
|
+
/** One camera, as nw_view takes it at the top level or in views[]. Ranges are
|
|
31
|
+
* clamped by the viewport rather than refused here, so a fov of 120 is a
|
|
32
|
+
* wide picture and not a failed call. */
|
|
33
|
+
const SHOT_FIELDS = {
|
|
34
|
+
target: z
|
|
35
|
+
.union([z.string(), vec3])
|
|
36
|
+
.optional()
|
|
37
|
+
.describe('orbit and closeup: "player", a placement id or kind, a world kind, an object name in the scene, or [x, y, z]. Default: the whole space.'),
|
|
38
|
+
yaw: z.number().optional().describe('Degrees around the target: 0 looks from +Z toward -Z, 90 from +X.'),
|
|
39
|
+
pitch: z.number().optional().describe('Degrees above the horizon, -89 to 89 (89 is nearly straight down).'),
|
|
40
|
+
distance: z.number().optional().describe('Metres from the target. Default: fitted to the target\'s size.'),
|
|
41
|
+
fov: z.number().optional().describe('Vertical field of view in degrees, 20 to 100. Default 50; player 55 or the space\'s own (config.player.fov).'),
|
|
42
|
+
position: vec3.optional().describe('free: where the camera stands, [x, y, z].'),
|
|
43
|
+
lookAt: vec3.optional().describe('free: the point it looks at, [x, y, z].'),
|
|
44
|
+
fog: z.boolean().optional().describe('Draw the world\'s fog. Default on, off for closeup and overview.'),
|
|
45
|
+
longEdge: z.number().int().optional().describe('The picture\'s long side in pixels, 256 to 1568. Default 1024.'),
|
|
46
|
+
aspect: z.enum(['wide', 'square', 'tall']).optional().describe('wide is 16:9 (the default), tall is 9:16.'),
|
|
47
|
+
}
|
|
48
|
+
const viewEnum = z.enum(VIEWS)
|
|
49
|
+
const shotSpec = z.object({ view: viewEnum, ...SHOT_FIELDS })
|
|
50
|
+
|
|
51
|
+
const VIEW_SHAPE = {
|
|
52
|
+
views: z.array(shotSpec).min(1).max(6).optional().describe('Several cameras in one call, up to 6, each with the fields below.'),
|
|
53
|
+
view: viewEnum.optional().describe('One camera: player, orbit, closeup, overview or free. Leave out (and views too) for a player view and an overview.'),
|
|
54
|
+
...SHOT_FIELDS,
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
const PLAY_SHAPE = {
|
|
58
|
+
steps: z
|
|
59
|
+
.array(
|
|
60
|
+
z.object({
|
|
61
|
+
keys: z.array(z.string()).max(8).default([]).describe('KeyboardEvent.code names held for the step, e.g. ["KeyW", "ShiftLeft"]. With goto: held as well on the way, e.g. ["KeyE"] (the movement keys are the walk\'s own).'),
|
|
62
|
+
seconds: z.number().min(0.1).max(30).optional().describe('How long the step lasts (default 3). With goto: the most the walk may take (default 15, and up to 30 when the run\'s 60 s leave room); it ends sooner when it gets there.'),
|
|
63
|
+
look: z
|
|
64
|
+
.object({
|
|
65
|
+
yaw: z.number().default(0).describe('Degrees to turn right over the step (negative turns left).'),
|
|
66
|
+
pitch: z.number().default(0).describe('Degrees to look down over the step (negative looks up).'),
|
|
67
|
+
})
|
|
68
|
+
.optional(),
|
|
69
|
+
goto: z
|
|
70
|
+
.union([z.string(), vec3])
|
|
71
|
+
.optional()
|
|
72
|
+
.describe('Walk the player there instead of holding keys: a placement id or kind, a world kind or an object name (the nearest one, followed if it moves), or [x, y, z]. It turns to face the target and walks along the ground, steps round what blocks it, and reports how it went (reached, gone when a rule removed the target, timeout, blocked).'),
|
|
73
|
+
within: z.number().min(0.2).max(20).optional().describe('goto: metres along the ground from the target\'s footprint that count as there. Default 0.5.'),
|
|
74
|
+
run: z.boolean().optional().describe('goto: run (Shift) on the way, twice the walk. Default false.'),
|
|
75
|
+
}),
|
|
76
|
+
)
|
|
77
|
+
.max(40)
|
|
78
|
+
.optional()
|
|
79
|
+
.describe('The run as a timeline, up to 60 s in all.'),
|
|
80
|
+
seconds: z.number().min(0.5).max(60).optional().describe('Without steps: how long to hold keys. Default 3.'),
|
|
81
|
+
keys: z.array(z.string()).optional().describe('Without steps: the keys held for the whole run.'),
|
|
82
|
+
frames: z.number().int().min(0).max(12).default(4).describe('Pictures from the player\'s eyes, spread evenly over the run.'),
|
|
83
|
+
longEdge: z.number().int().min(256).max(1280).default(768).describe('Their long side in pixels.'),
|
|
84
|
+
watch: z.array(z.string()).max(8).default([]).describe('Things to track through the run: placement ids or kinds, world kinds, object names.'),
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
const EVAL_SHAPE = {
|
|
88
|
+
code: z.string().min(1).max(4000).describe('An expression, or statements ending in return.'),
|
|
89
|
+
timeoutMs: z.number().int().min(100).max(5000).default(2000).describe('How long to wait for it, at most 5000 ms.'),
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
const LOGS_SHAPE = {
|
|
93
|
+
since: z.number().int().optional().describe('The next value from your last call: only what came after it.'),
|
|
94
|
+
level: z.enum(['all', 'warn', 'error']).default('all').describe('warn: warnings and errors; error: errors only.'),
|
|
95
|
+
source: z.enum(['all', 'game', 'runtime', 'asset', 'studio', 'shader']).default('all'),
|
|
96
|
+
limit: z.number().int().min(1).max(200).default(80),
|
|
97
|
+
clear: z.boolean().default(false).describe('Empty the log after reading it.'),
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
// ---- helpers ----------------------------------------------------------------
|
|
101
|
+
|
|
102
|
+
const firstLine = (text) => String(text ?? 'it did not say why').split('\n').find((l) => l.trim()) ?? 'it did not say why'
|
|
103
|
+
const fmt = (n) => (typeof n === 'number' && Number.isFinite(n) ? String(Math.round(n * 100) / 100) : '?')
|
|
104
|
+
const vec = (v) => (Array.isArray(v) ? `[${v.map(fmt).join(', ')}]` : '?')
|
|
105
|
+
const json = (v) => JSON.stringify(v, null, 2) ?? 'undefined'
|
|
106
|
+
|
|
107
|
+
/** The rpc, or one that says the studio is not there (a check's bare ctx). */
|
|
108
|
+
const rpcOf = (ctx) =>
|
|
109
|
+
typeof ctx?.rpc === 'function' ? ctx.rpc : async () => ({ ok: false, error: 'The studio is not connected.' })
|
|
110
|
+
|
|
111
|
+
/** Builds first when the project changed since the last build (2.2.2), so a
|
|
112
|
+
* look after an edit never shows the build before it. failed: the build's
|
|
113
|
+
* first error line; held: it passed, but the viewport keeps it until the
|
|
114
|
+
* creator stops playing, so the game on screen is the one before the edit,
|
|
115
|
+
* or (safe: true) until the creator starts it after the studio froze or
|
|
116
|
+
* crashed with it running, with main's word on what to look for. */
|
|
117
|
+
async function buildIfNeeded(ctx) {
|
|
118
|
+
let needed = false
|
|
119
|
+
try {
|
|
120
|
+
needed = Boolean(await ctx?.run?.needsBuild?.())
|
|
121
|
+
} catch {
|
|
122
|
+
needed = false
|
|
123
|
+
}
|
|
124
|
+
if (!needed) return {}
|
|
125
|
+
const r = await rpcOf(ctx)('build')
|
|
126
|
+
// running: the check failed on something the game runs through (a
|
|
127
|
+
// material drawn flat black, a file that did not load): it is on screen.
|
|
128
|
+
if (!r?.ok) return { failed: firstLine(r?.error), running: r?.running === true }
|
|
129
|
+
if (!r.held) return {}
|
|
130
|
+
return r.reason === 'safe' ? { held: true, safe: true, note: typeof r.note === 'string' ? r.note : null } : { held: true }
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
const buildFailed = (built) => {
|
|
134
|
+
const said = String(built.failed).replace(/[\s:.]+$/, '')
|
|
135
|
+
return built.running
|
|
136
|
+
? `The game is running, but its check failed: ${said}. Fix it, run nw_check, then look again.`
|
|
137
|
+
: `The build failed, so no game is running: ${said}. Fix it, run nw_check, then look again.`
|
|
138
|
+
}
|
|
139
|
+
const BUILD_HELD =
|
|
140
|
+
'The creator is playing the game, so your latest edit has not run yet: these pictures show the version before it. Do not judge the edit from them; look again once they stop.'
|
|
141
|
+
const BUILD_HELD_SAFE =
|
|
142
|
+
'It compiles. The studio froze or crashed while the game ran, so the game waits for the creator to start it; it has not run yet. Look for an endless loop or a runaway allocation before they do.'
|
|
143
|
+
/** What a held build is said as: why it waits, and what to do meanwhile. */
|
|
144
|
+
const heldNote = (built) => (built.safe ? built.note || BUILD_HELD_SAFE : BUILD_HELD)
|
|
145
|
+
|
|
146
|
+
/** Drops the keys a model left undefined, so a spec compares the same way in
|
|
147
|
+
* every call (the probe's sameAsLast keys on it). */
|
|
148
|
+
const clean = (spec) => Object.fromEntries(Object.entries(spec).filter(([, v]) => v !== undefined))
|
|
149
|
+
|
|
150
|
+
/** The cameras a call asks for: views[], or the one at the top level, or a
|
|
151
|
+
* player view and an overview. */
|
|
152
|
+
export function shotsFor(args = {}) {
|
|
153
|
+
const { views, view, ...single } = args
|
|
154
|
+
if (Array.isArray(views) && views.length > 0) return views.slice(0, 6).map(clean)
|
|
155
|
+
if (view) return [clean({ view, ...single })]
|
|
156
|
+
// Settings that make sense for any picture carry over to the default pair.
|
|
157
|
+
const common = clean({ longEdge: single.longEdge, aspect: single.aspect })
|
|
158
|
+
return [{ view: 'player', ...common }, { view: 'overview', ...common }]
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/** The rpc timeout for a view: the viewport serves one shot per frame, and
|
|
162
|
+
* waits up to 4 s for each before it says it is not drawing. */
|
|
163
|
+
export const viewTimeout = (count) => 15_000 + 3_000 * count
|
|
164
|
+
|
|
165
|
+
/** What was still on its way into the space when a picture was drawn, as a
|
|
166
|
+
* sentence, or '' when it had all arrived (createPreviewScene LoadingReport). */
|
|
167
|
+
export function loadingLine(loading) {
|
|
168
|
+
if (!loading || !loading.mounted || loading.settled) return ''
|
|
169
|
+
const out = stillOut(loading)
|
|
170
|
+
return out
|
|
171
|
+
? `still loading when it was drawn: ${out}. It may be missing what they bring.`
|
|
172
|
+
: `drawn ${loading.quietMs} ms after the last file arrived; a space that asks for more in its first frames may not have it yet.`
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/** What a loading report has still on its way, in words, or ''. */
|
|
176
|
+
export function stillOut(loading) {
|
|
177
|
+
const out = []
|
|
178
|
+
if (loading.files > 0) out.push(`${loading.files} of its files (${(loading.names ?? []).join(', ') || 'unnamed'})`)
|
|
179
|
+
const look = Array.isArray(loading.look) ? loading.look : []
|
|
180
|
+
if (look.length > 0) out.push(`the look's ${look.length === 1 ? 'file' : 'files'} (${look.join(', ')}), drawn without ${look.length === 1 ? 'it' : 'them'} until then`)
|
|
181
|
+
if (loading.placements > 0) out.push(`${loading.placements} placed model${loading.placements === 1 ? '' : 's'}`)
|
|
182
|
+
if (loading.remount) out.push('the remount that follows the placed models')
|
|
183
|
+
if (loading.mounting) out.push('a new build, still mounting (the picture is of the space before it)')
|
|
184
|
+
return out.join(', ')
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
// ---- untextured surfaces (nw_check) -------------------------------------------
|
|
188
|
+
// A surface with no texture on it reads as a CG primitive whatever the light
|
|
189
|
+
// does: the Red Arch's six models and the template's Stonehenge were all one
|
|
190
|
+
// colour per material, and nothing said so. nw_check looks at the player's
|
|
191
|
+
// view once the space's files have arrived (untextured.ts says how the share
|
|
192
|
+
// is measured) and warns above these lines. They are a check's thresholds,
|
|
193
|
+
// not a look: what replaces a flat surface comes from the brief.
|
|
194
|
+
|
|
195
|
+
/** How long nw_check waits for the space's files before it measures. */
|
|
196
|
+
export const SURFACE_SETTLE_MS = 10_000
|
|
197
|
+
/** One surface without a colour texture covering this share of the
|
|
198
|
+
* player's view, or all of them together this much, is warned about. */
|
|
199
|
+
export const UNTEXTURED_ONE = 0.1
|
|
200
|
+
export const UNTEXTURED_ALL = 0.25
|
|
201
|
+
|
|
202
|
+
const SURFACE_KINDS = {
|
|
203
|
+
flat: 'one flat colour',
|
|
204
|
+
'vertex colours': 'vertex colours only',
|
|
205
|
+
procedural: 'a colour graph with no texture in it',
|
|
206
|
+
'detail maps only': 'normal, roughness or occlusion maps over one flat colour',
|
|
207
|
+
}
|
|
208
|
+
const pct = (v) => `${Math.round(v * 100)}%`
|
|
209
|
+
|
|
210
|
+
/** The warning for one view's surface report (untextured.ts SurfaceReport),
|
|
211
|
+
* or '' when no surface without a colour texture is large enough to say. */
|
|
212
|
+
export function untexturedWarning(report, loading) {
|
|
213
|
+
if (!report || !Array.isArray(report.untextured)) return ''
|
|
214
|
+
const counted = report.untextured.filter((s) => s.kind !== 'unknown')
|
|
215
|
+
const lines = []
|
|
216
|
+
if (counted.some((s) => s.share >= UNTEXTURED_ONE) || report.share >= UNTEXTURED_ALL) {
|
|
217
|
+
lines.push(`Warning: surfaces with no colour texture are ${pct(report.share)} of the player's view.`)
|
|
218
|
+
for (const s of counted.slice(0, 5)) {
|
|
219
|
+
const on = s.meshes > 1 ? `on ${s.name} and ${s.meshes - 1} more` : `on ${s.name}`
|
|
220
|
+
lines.push(`- ${s.material} ${on} (${SURFACE_KINDS[s.kind] ?? s.kind}): ${pct(s.share)}`)
|
|
221
|
+
}
|
|
222
|
+
lines.push(
|
|
223
|
+
`A surface with no picture on it reads as a CG primitive whatever the light does. Give the large ones a material made for the brief: a scanned set (asset_search, then asset_import) or a texture made for that surface. Measured with ${report.method}${report.partial ? '; the scene was past the check\'s budget, so some meshes were left out' : ''}.`,
|
|
224
|
+
)
|
|
225
|
+
// The plate can only ever be one colour: the way out is a ground of the space's own.
|
|
226
|
+
if (counted.some((s) => s.name.startsWith('the ground plate') && s.share >= UNTEXTURED_ONE)) {
|
|
227
|
+
lines.push('The ground plate is game.config.json\'s ground, one colour by design: give the space a ground of its own with a material made for it, and set ground to { "kind": "none" }.')
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
const unseen = report.untextured.filter((s) => s.kind === 'unknown' && s.share >= UNTEXTURED_ONE)
|
|
231
|
+
if (unseen.length > 0) lines.push(`Not counted: ${unseen.map((s) => s.name).join(', ')} draw${unseen.length === 1 ? 's' : ''} through a node graph this check could not build to see its textures.`)
|
|
232
|
+
if (lines.length > 0 && loading && loading.mounted && !loading.settled) {
|
|
233
|
+
lines.push(`This was measured before the space had finished loading (${stillOut(loading) || 'its last file had only just arrived'}); what had not arrived was not looked at.`)
|
|
234
|
+
}
|
|
235
|
+
return lines.join('\n')
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/** nw_check's look for untextured surfaces: the player's view, once the
|
|
239
|
+
* space's files have arrived. '' when there is nothing to warn about, or no
|
|
240
|
+
* view to measure (nw_check never fails on it). */
|
|
241
|
+
export async function untexturedNote(rpc) {
|
|
242
|
+
try {
|
|
243
|
+
// record: false, so the agent's next nw_view is still compared with its
|
|
244
|
+
// own last one, not with this picture it never saw.
|
|
245
|
+
const r = await rpc('view', { shots: [{ view: 'player', longEdge: 256, surfaces: true }], settle: { waitMs: SURFACE_SETTLE_MS }, record: false }, viewTimeout(1) + SURFACE_SETTLE_MS)
|
|
246
|
+
const shot = r?.ok && Array.isArray(r.shots) ? r.shots[0] : null
|
|
247
|
+
return shot?.ok && shot.surfaces ? untexturedWarning(shot.surfaces, shot.loading) : ''
|
|
248
|
+
} catch {
|
|
249
|
+
return ''
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/** A walk's defaults (agentProbe.ts GOTO_WITHIN, GOTO_SECONDS, GOTO_LONGEST)
|
|
254
|
+
* and the keys it steers with itself. A walk without seconds gets 15, then
|
|
255
|
+
* up to 30 from what the run's 60 s leave: at the visitor's 7 m/s walk 15 s
|
|
256
|
+
* is about 100 m (it was 50 m at 3.5 m/s, until 2026-11-11), and a walk that runs
|
|
257
|
+
* out of time reads as a blocked route. It ends when it gets there, so the
|
|
258
|
+
* longer limit costs nothing on a walk that arrives. */
|
|
259
|
+
const GOTO_WITHIN = 0.5
|
|
260
|
+
const GOTO_SECONDS = 15
|
|
261
|
+
const GOTO_LONGEST = 30
|
|
262
|
+
const MOVE_KEYS = new Set(['KeyW', 'KeyA', 'KeyS', 'KeyD', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'])
|
|
263
|
+
|
|
264
|
+
/** A step's walk made whole, { target, within, run }, null for a step
|
|
265
|
+
* without one, or { error } when it cannot be one. This side owns the
|
|
266
|
+
* normalising: the probe (agentProbe.ts gotoOf) takes this shape as it is. */
|
|
267
|
+
export function gotoOf(s = {}) {
|
|
268
|
+
const target = s.goto
|
|
269
|
+
if (target === undefined || target === null) return null
|
|
270
|
+
const within = Math.min(20, Math.max(0.2, typeof s.within === 'number' && Number.isFinite(s.within) ? s.within : GOTO_WITHIN))
|
|
271
|
+
const run = s.run === true
|
|
272
|
+
if (Array.isArray(target)) {
|
|
273
|
+
if (target.length !== 3 || !target.every((n) => typeof n === 'number' && Number.isFinite(n))) return { error: 'goto takes a name or a point [x, y, z] in metres.' }
|
|
274
|
+
return { target: [...target], within, run }
|
|
275
|
+
}
|
|
276
|
+
const name = typeof target === 'string' ? target.trim() : ''
|
|
277
|
+
if (!name) return { error: 'goto takes a name (a placement id or kind, a world kind, an object name) or a point [x, y, z].' }
|
|
278
|
+
if (name === 'player') return { error: 'goto "player" is where the player already is. Name a thing to walk to, or give [x, y, z].' }
|
|
279
|
+
return { target: name.slice(0, 120), within, run }
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/** A playtest's parameters as the probe takes them (agentProbe.ts
|
|
283
|
+
* PlayParams), or the reason they cannot be: one step for the v1 shorthand,
|
|
284
|
+
* 60 s at most in all, look in radians. */
|
|
285
|
+
export function playParams(args = {}) {
|
|
286
|
+
const given =
|
|
287
|
+
Array.isArray(args.steps) && args.steps.length > 0 ? args.steps : [{ keys: args.keys ?? [], seconds: args.seconds ?? 3 }]
|
|
288
|
+
const steps = []
|
|
289
|
+
/** The walks given no seconds, which share what the run has left. */
|
|
290
|
+
const open = []
|
|
291
|
+
let left = PLAY_MAX_SECONDS
|
|
292
|
+
for (const s of given) {
|
|
293
|
+
if (left <= 1e-9) break
|
|
294
|
+
let keys = (s.keys ?? []).map(String)
|
|
295
|
+
const bad = keys.find((k) => !/^[A-Za-z0-9]+$/.test(k))
|
|
296
|
+
if (bad !== undefined) {
|
|
297
|
+
return { ok: false, error: `"${bad}" is not a key name. Use KeyboardEvent.code names such as KeyW, Space, ShiftLeft or ArrowUp.` }
|
|
298
|
+
}
|
|
299
|
+
const walk = gotoOf(s)
|
|
300
|
+
if (walk?.error) return { ok: false, error: walk.error }
|
|
301
|
+
if (walk) keys = keys.filter((k) => !MOVE_KEYS.has(k))
|
|
302
|
+
const seconds = Math.min(left, Math.max(0.1, Number(s.seconds) || (walk ? GOTO_SECONDS : 3)))
|
|
303
|
+
left -= seconds
|
|
304
|
+
if (walk && !(Number(s.seconds) > 0)) open.push(steps.length)
|
|
305
|
+
steps.push({
|
|
306
|
+
keys,
|
|
307
|
+
seconds,
|
|
308
|
+
look: walk ? { yaw: 0, pitch: 0 } : { yaw: (Number(s.look?.yaw) || 0) * DEG, pitch: (Number(s.look?.pitch) || 0) * DEG },
|
|
309
|
+
...(walk ? { goto: walk } : {}),
|
|
310
|
+
})
|
|
311
|
+
}
|
|
312
|
+
for (const i of open) {
|
|
313
|
+
const more = Math.max(0, Math.min(GOTO_LONGEST - steps[i].seconds, left))
|
|
314
|
+
steps[i].seconds += more
|
|
315
|
+
left -= more
|
|
316
|
+
}
|
|
317
|
+
return {
|
|
318
|
+
ok: true,
|
|
319
|
+
params: {
|
|
320
|
+
steps,
|
|
321
|
+
frames: Math.min(12, Math.max(0, Math.floor(args.frames ?? 4))),
|
|
322
|
+
longEdge: Math.min(1280, Math.max(256, Math.floor(args.longEdge ?? 768))),
|
|
323
|
+
watch: (args.watch ?? []).slice(0, 8).map(String),
|
|
324
|
+
},
|
|
325
|
+
}
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
// ---- frame time (perf) -----------------------------------------------------
|
|
329
|
+
// The space is walked in real time, so what a frame costs at each tier is
|
|
330
|
+
// part of whether it is done (REFERENCE_LOOP.md 2.6, 4): nw_check measures
|
|
331
|
+
// it and carries it as perf, nw_status carries what was kept, the stop gate
|
|
332
|
+
// and the approval card read it. The viewport measures it
|
|
333
|
+
// (createPreviewScene measurePerf): the spawn view and each hero view of
|
|
334
|
+
// brief.json at each tier's look and pixel count, warmed up, then sampled,
|
|
335
|
+
// each frame timed to the GPU's finish; a tier is its worst view. It takes
|
|
336
|
+
// some seconds, in the studio's own viewport, so it is kept until the
|
|
337
|
+
// project changes: in memory, and in .nowhere/perf.json with the stamp of
|
|
338
|
+
// the files and the hero views it was measured on. A measurement is not
|
|
339
|
+
// kept when it is unsure: taken before the space finished loading, or over
|
|
340
|
+
// a line while the frames were uneven or the GPU was busy with other work
|
|
341
|
+
// (another app's frames are not the space's). The next nw_check measures
|
|
342
|
+
// again. This file is vendored alone into the CLI, so the stamp is its own
|
|
343
|
+
// here (the same sizes and times the stop gate's fingerprint reads), and so
|
|
344
|
+
// is the time a measurement may take (the SDK's perfMaxMs, kept in step).
|
|
345
|
+
|
|
346
|
+
/** Where the last measurement is kept, beside the files it was measured on. */
|
|
347
|
+
export const PERF_FILE = '.nowhere/perf.json'
|
|
348
|
+
const PERF_TIER_NAMES = ['high', 'medium', 'low']
|
|
349
|
+
const PERF_DEFAULT = ['high', 'low']
|
|
350
|
+
const PERF_SETTLE_MS = 15_000
|
|
351
|
+
/** How long the viewport may take: the SDK's perfMaxMs (perf.ts), the same
|
|
352
|
+
* sums. Main and this tool each wait a little longer than the one below. */
|
|
353
|
+
export function perfMaxMs({ tiers = 2, views = 1, settleMs = PERF_SETTLE_MS, warmMs = 800 } = {}) {
|
|
354
|
+
const viewMaxMs = views <= 1 ? 6000 : 2500
|
|
355
|
+
const perTier = Math.max(warmMs, 5000) + Math.max(1, views) * (1500 + viewMaxMs)
|
|
356
|
+
return Math.round(settleMs + 2000 + Math.max(1, tiers) * perTier * 2 + 8000)
|
|
357
|
+
}
|
|
358
|
+
const STAMP_DIRS = ['src', 'assets']
|
|
359
|
+
const STAMP_FILES = ['game.config.json', 'scene.json']
|
|
360
|
+
const STAMP_SKIP = new Set(['node_modules', '.git', '.nowhere', 'dist', '.DS_Store'])
|
|
361
|
+
|
|
362
|
+
/** sha1 over "path:size:mtime" of the space's files: what changes when the project does. */
|
|
363
|
+
export async function projectStamp(root) {
|
|
364
|
+
const files = []
|
|
365
|
+
const walk = async (rel) => {
|
|
366
|
+
let entries
|
|
367
|
+
try {
|
|
368
|
+
entries = await fsp.readdir(path.join(root, rel), { withFileTypes: true })
|
|
369
|
+
} catch {
|
|
370
|
+
return
|
|
371
|
+
}
|
|
372
|
+
for (const e of entries) {
|
|
373
|
+
if (STAMP_SKIP.has(e.name) || files.length > 20_000) continue
|
|
374
|
+
const child = `${rel}/${e.name}`
|
|
375
|
+
if (e.isDirectory()) await walk(child)
|
|
376
|
+
else if (e.isFile()) files.push(child)
|
|
377
|
+
}
|
|
378
|
+
}
|
|
379
|
+
for (const dir of STAMP_DIRS) await walk(dir)
|
|
380
|
+
files.push(...STAMP_FILES)
|
|
381
|
+
const lines = []
|
|
382
|
+
for (const rel of files.sort()) {
|
|
383
|
+
try {
|
|
384
|
+
const st = await fsp.stat(path.join(root, rel))
|
|
385
|
+
lines.push(`${rel}:${st.size}:${st.mtimeMs}`)
|
|
386
|
+
} catch {
|
|
387
|
+
// not there
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
return createHash('sha1').update(lines.join('\n')).digest('hex')
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
const isVec3 = (v) => Array.isArray(v) && v.length === 3 && v.every((n) => typeof n === 'number' && Number.isFinite(n))
|
|
394
|
+
|
|
395
|
+
/** The hero views of brief.json as the viewport times them ({ id,
|
|
396
|
+
* position, lookAt, fov }), read loosely: a brief that does not validate
|
|
397
|
+
* yet still names where its views stand. At most six. */
|
|
398
|
+
export async function heroViewsOf(projectRoot) {
|
|
399
|
+
if (!projectRoot) return []
|
|
400
|
+
let raw
|
|
401
|
+
try {
|
|
402
|
+
raw = JSON.parse(await fsp.readFile(path.join(projectRoot, BRIEF_FILE), 'utf8'))
|
|
403
|
+
} catch {
|
|
404
|
+
return []
|
|
405
|
+
}
|
|
406
|
+
const out = []
|
|
407
|
+
for (const v of Array.isArray(raw?.heroViews) ? raw.heroViews : []) {
|
|
408
|
+
if (!v || !/^H[1-6]$/.test(String(v.id)) || !isVec3(v.position) || !isVec3(v.lookAt) || out.some((w) => w.id === v.id)) continue
|
|
409
|
+
out.push({ id: v.id, position: v.position, lookAt: v.lookAt, fov: typeof v.fov === 'number' && Number.isFinite(v.fov) ? v.fov : 55 })
|
|
410
|
+
if (out.length >= 6) break
|
|
411
|
+
}
|
|
412
|
+
return out
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
/** The key a measurement is kept under: the files' stamp and the views it timed. */
|
|
416
|
+
const perfKey = (stamp, views) => (stamp ? `${stamp}:${createHash('sha1').update(JSON.stringify(views)).digest('hex').slice(0, 12)}` : null)
|
|
417
|
+
|
|
418
|
+
/** The kept measurement ({ stamp, perf }), or null. */
|
|
419
|
+
export async function readPerf(projectRoot) {
|
|
420
|
+
if (!projectRoot) return null
|
|
421
|
+
try {
|
|
422
|
+
const kept = JSON.parse(await fsp.readFile(path.join(projectRoot, PERF_FILE), 'utf8'))
|
|
423
|
+
return kept && typeof kept.stamp === 'string' && kept.perf && typeof kept.perf === 'object' ? kept : null
|
|
424
|
+
} catch {
|
|
425
|
+
return null
|
|
426
|
+
}
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
/** Why a measurement is not kept, or null when it may be: one taken before
|
|
430
|
+
* the space finished loading, or a tier over its line whose frames were
|
|
431
|
+
* uneven or measured while the GPU was busy. A within is kept: the
|
|
432
|
+
* machine's other work only ever adds time. */
|
|
433
|
+
export function perfUnkept(perf) {
|
|
434
|
+
if (!perf?.tiers || Object.keys(perf.tiers).length === 0) return 'no tier was measured'
|
|
435
|
+
if (perf.loaded === false || Object.values(perf.tiers).some((t) => t?.unsure)) return 'it was taken before the space finished loading'
|
|
436
|
+
const shaky = Object.entries(perf.tiers).filter(([, t]) => t && t.ok === false && t.steady === false)
|
|
437
|
+
if (shaky.length) return `${shaky.map(([tier]) => tier).join(' and ')} was over its line while the frames were uneven or the GPU was busy with other work, which may be the machine's and not the space's`
|
|
438
|
+
return null
|
|
439
|
+
}
|
|
440
|
+
|
|
441
|
+
/** What was measured last, by project, while this process runs. */
|
|
442
|
+
const perfKept = new Map()
|
|
443
|
+
const covers = (perf, tiers) => !!perf?.tiers && (tiers ?? PERF_DEFAULT).every((t) => perf.tiers[t])
|
|
444
|
+
|
|
445
|
+
/**
|
|
446
|
+
* perf for the project as it is now: the kept measurement when the files
|
|
447
|
+
* and hero views have not changed since it, else (measure: true, as
|
|
448
|
+
* nw_check) a new one from the viewport. nw_status passes measure: false
|
|
449
|
+
* and only reads what was kept, so it never takes the viewport over.
|
|
450
|
+
* Answers { perf, cached } or { error }. fresh: measure whatever is kept.
|
|
451
|
+
*/
|
|
452
|
+
export async function perfFor(ctx, { fresh = false, tiers, measure = true } = {}) {
|
|
453
|
+
const root = ctx?.projectRoot ?? null
|
|
454
|
+
const asked = Array.isArray(tiers) ? [...new Set(tiers.filter((t) => PERF_TIER_NAMES.includes(t)))] : null
|
|
455
|
+
const views = await heroViewsOf(root)
|
|
456
|
+
const key = perfKey(root ? await projectStamp(root) : null, views)
|
|
457
|
+
if (!fresh && key) {
|
|
458
|
+
const mem = perfKept.get(root)
|
|
459
|
+
if (mem?.stamp === key && covers(mem.perf, asked)) return { perf: mem.perf, cached: true }
|
|
460
|
+
const disk = await readPerf(root)
|
|
461
|
+
if (disk?.stamp === key && covers(disk.perf, asked)) {
|
|
462
|
+
perfKept.set(root, disk)
|
|
463
|
+
return { perf: disk.perf, cached: true }
|
|
464
|
+
}
|
|
465
|
+
}
|
|
466
|
+
if (!measure) return { error: 'it has not been measured since the space last changed (nw_check measures it)' }
|
|
467
|
+
const maxMs = perfMaxMs({ tiers: (asked ?? PERF_DEFAULT).length, views: 1 + views.length })
|
|
468
|
+
const params = { ...(asked ? { tiers: asked } : {}), ...(views.length ? { views } : {}), maxMs }
|
|
469
|
+
// What can be known of the machine's load from here: the processor's,
|
|
470
|
+
// beside the GPU's empty frame the viewport times.
|
|
471
|
+
const cpu = { cpu1m: Math.round(os.loadavg()[0] * 100) / 100, cores: os.cpus().length }
|
|
472
|
+
const r = await rpcOf(ctx)('perf', params, maxMs + 8000)
|
|
473
|
+
if (!r?.ok) return { error: firstLine(r?.error ?? 'the viewport did not answer.') }
|
|
474
|
+
const { ok: _ok, ...measured } = r
|
|
475
|
+
const perf = { ...measured, load: { ...(measured.load ?? {}), ...cpu } }
|
|
476
|
+
const unkept = perfUnkept(perf)
|
|
477
|
+
if (unkept) return { perf, cached: false, unkept }
|
|
478
|
+
// Kept against the stamp from before it was measured: an edit made
|
|
479
|
+
// meanwhile makes the next call measure again.
|
|
480
|
+
if (key) {
|
|
481
|
+
perfKept.set(root, { stamp: key, perf })
|
|
482
|
+
try {
|
|
483
|
+
// Inside a project that is there: .nowhere/ is made in it, never the project.
|
|
484
|
+
await fsp.mkdir(path.join(root, '.nowhere')).catch((err) => {
|
|
485
|
+
if (err?.code !== 'EEXIST') throw err
|
|
486
|
+
})
|
|
487
|
+
await fsp.writeFile(path.join(root, PERF_FILE), `${JSON.stringify({ stamp: key, perf }, null, 1)}\n`)
|
|
488
|
+
} catch {
|
|
489
|
+
// kept in memory only
|
|
490
|
+
}
|
|
491
|
+
}
|
|
492
|
+
return { perf, cached: false }
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
/** perf in words, a line a tier: p95 against its limit, the view it was
|
|
496
|
+
* worst at, and the counts. */
|
|
497
|
+
export function perfLines(perf) {
|
|
498
|
+
const lines = []
|
|
499
|
+
for (const tier of PERF_TIER_NAMES) {
|
|
500
|
+
const t = perf?.tiers?.[tier]
|
|
501
|
+
if (!t) continue
|
|
502
|
+
const verdict = t.unsure ? 'UNSURE (not loaded yet)' : t.ok ? 'within it' : t.steady === false ? 'OVER IT, but the frames were uneven (measured again next time)' : 'OVER IT'
|
|
503
|
+
const at = t.view ? ` at ${t.view === 'spawn' ? 'the spawn view' : t.view}` : ''
|
|
504
|
+
lines.push(`${tier}: p95 ${fmt(t.frameMsP95)} ms (p50 ${fmt(t.frameMsP50)})${at} against ${fmt(t.budgetMs)} ms, ${verdict}; ${t.drawCalls} draw calls, ${t.triangles} triangles, ${fmt(t.gpuMemMB)} MB on the GPU`)
|
|
505
|
+
const others = Object.entries(perf?.views?.[tier] ?? {}).filter(([id]) => id !== t.view)
|
|
506
|
+
if (others.length) lines.push(`${tier}, the other views: ${others.map(([id, v]) => `${id} p95 ${fmt(v.frameMsP95)} ms`).join(', ')}`)
|
|
507
|
+
}
|
|
508
|
+
for (const note of perf?.notes ?? []) lines.push(`note: ${note}`)
|
|
509
|
+
return lines
|
|
510
|
+
}
|
|
511
|
+
|
|
512
|
+
/** Whether every measured tier is within its limit. */
|
|
513
|
+
export const perfWithin = (perf) => {
|
|
514
|
+
const tiers = Object.values(perf?.tiers ?? {})
|
|
515
|
+
return tiers.length > 0 && tiers.every((t) => t?.ok === true)
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
// ---- the tools --------------------------------------------------------------
|
|
519
|
+
|
|
520
|
+
const nwView = {
|
|
521
|
+
name: 'nw_view',
|
|
522
|
+
description:
|
|
523
|
+
'Looks at the running space, canvas only (no studio UI), through cameras you choose, and returns the pictures. Views: "player" (what the visitor sees: the space\'s own play camera, or behind the visitor when its code sets none); "orbit" (around a target at yaw, pitch and distance in degrees and metres); "closeup" (fitted tight to a target, for judging an asset\'s shape, detail and materials); "overview" (the whole world from the studio\'s standard 45 degree view; on an older planet with an edge it is cut there, so scenery beyond shows only in the player, orbit and free views); "free" (position and lookAt). target is "player", a placement id or kind, a world kind, an object name in the scene, or [x, y, z]. yaw 0 looks from +Z toward -Z, 90 from +X. Up to 6 views per call. Each picture comes with its camera, the frame counter, the code\'s own frame counter (`game frame` in its line) and fps: when the counters do not move between calls the preview is frozen, so say so instead of judging the picture. A picture that comes back empty is drawn again, then off-screen (said in its notes: no glow there); when none of that works, the reason comes instead of a picture. The pictures show the world as a visitor sees it: the editor\'s grid and map outline are left out. Look after every visual change, and compare close-ups and the player view with the reference.',
|
|
524
|
+
shape: VIEW_SHAPE,
|
|
525
|
+
readOnly: true,
|
|
526
|
+
verifies: 'view',
|
|
527
|
+
async handler(args, ctx) {
|
|
528
|
+
const shots = shotsFor(args ?? {})
|
|
529
|
+
const lines = []
|
|
530
|
+
const built = await buildIfNeeded(ctx)
|
|
531
|
+
if (built.failed) lines.push(buildFailed(built))
|
|
532
|
+
if (built.held) lines.push(heldNote(built))
|
|
533
|
+
const r = await rpcOf(ctx)('view', { shots }, viewTimeout(shots.length))
|
|
534
|
+
if (!r?.ok || !Array.isArray(r.shots)) {
|
|
535
|
+
lines.push(`No pictures: ${r?.error ?? 'the viewport did not answer.'}`)
|
|
536
|
+
return { text: lines.join('\n'), isError: true }
|
|
537
|
+
}
|
|
538
|
+
const images = []
|
|
539
|
+
r.shots.forEach((s, i) => {
|
|
540
|
+
const n = `${i + 1}. ${s.view ?? shots[i]?.view ?? 'view'}`
|
|
541
|
+
if (!s.ok || !s.image) {
|
|
542
|
+
lines.push(`${n}: no picture: ${s.error ?? 'nothing came back.'}`)
|
|
543
|
+
return
|
|
544
|
+
}
|
|
545
|
+
images.push({ data: s.image.data, mime: s.image.mime ?? 'image/jpeg' })
|
|
546
|
+
const c = s.camera
|
|
547
|
+
const lens = c?.projection === 'orthographic' ? 'orthographic' : `fov ${fmt(c?.fov)}`
|
|
548
|
+
lines.push(
|
|
549
|
+
`${n}: camera ${vec(c?.position)} -> ${vec(c?.lookAt)}, ${lens}, frame ${s.frame}, game frame ${s.gameFrame}, ${fmt(s.fps)} fps`,
|
|
550
|
+
)
|
|
551
|
+
if (s.target) lines.push(` target ${s.target.name}: centre ${vec(s.target.centre)}, size ${vec(s.target.size)} m`)
|
|
552
|
+
for (const note of s.notes ?? []) lines.push(` note: ${note}`)
|
|
553
|
+
const loading = loadingLine(s.loading)
|
|
554
|
+
if (loading) lines.push(` note: ${loading}`)
|
|
555
|
+
})
|
|
556
|
+
if (r.frozen) {
|
|
557
|
+
lines.push(
|
|
558
|
+
`The preview drew no frame in the last ${(r.frozen.msSinceLast / 1000).toFixed(1)} s: it is frozen. Do not judge these pictures; check nw_status.`,
|
|
559
|
+
)
|
|
560
|
+
}
|
|
561
|
+
;(r.sameAsLast ?? []).forEach((same, i) => {
|
|
562
|
+
if (same) lines.push(`Picture ${i + 1} is byte-identical to the same view in your last call: nothing in it has changed.`)
|
|
563
|
+
})
|
|
564
|
+
// A frozen preview is not a look at the space as it is now, and every
|
|
565
|
+
// picture failing is no look at all; a held build's pictures are of the
|
|
566
|
+
// space before the edit, so they are no look at it either.
|
|
567
|
+
const isError = Boolean(r.frozen) || images.length === 0
|
|
568
|
+
return { text: lines.join('\n'), images, ...(isError ? { isError: true } : built.held ? { verifies: null } : {}) }
|
|
569
|
+
},
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
const nwPlay = {
|
|
573
|
+
name: 'nw_play',
|
|
574
|
+
description:
|
|
575
|
+
'Walks the space hands-free from a fresh start, the way a visitor arrives: a timeline of steps, each holding keys (KeyboardEvent.code names, e.g. KeyW, Space) for some seconds while turning the view (look: degrees to turn right and to look down over the step), up to 60 s in all. A step with goto walks the player to a thing (a placement id or kind, a world kind, an object name: the nearest one) or to [x, y, z] instead, steering along the ground with a time limit, so a walk-through can reach a doorway, a stair or the far end of a room and see what the visitor sees on the way; goto in the reply says how each walk went (reached, gone: a rule removed the target, timeout: the time ran out, which is not a blocked route, blocked) with the distance and the path. A goto without seconds gets 15 s, and up to 30 when the run\'s 60 s leave room: at the 7 m/s walk that is about 100 to 200 m, twice that with run. Returns where the player started and ended, the status line, world.state, new errors, fps (average, minimum, 5th percentile) and pictures from the player\'s eyes taken during the run (frames). watch names things to track (placement ids, kinds, object names). fell says when the player fell off the world (nothing under it, down past y = -60) and where it last stood. Use it to check that the visitor can walk where the creator named, that nothing blocks or drops them, and that it runs smoothly. While the creator is walking the space themselves (Play) it does not run and says so: check with nw_status and nw_view instead.',
|
|
576
|
+
shape: PLAY_SHAPE,
|
|
577
|
+
readOnly: true,
|
|
578
|
+
async handler(args, ctx) {
|
|
579
|
+
const p = playParams(args ?? {})
|
|
580
|
+
if (!p.ok) return { text: p.error, isError: true }
|
|
581
|
+
const total = p.params.steps.reduce((s, step) => s + step.seconds, 0)
|
|
582
|
+
const built = await buildIfNeeded(ctx)
|
|
583
|
+
if (built.failed) return { text: buildFailed(built), isError: true }
|
|
584
|
+
const r = await rpcOf(ctx)('play', p.params, (total + 45) * 1000)
|
|
585
|
+
if (!r?.ok) return { text: `The playtest did not run: ${r?.error ?? 'the viewport did not answer.'}`, isError: true }
|
|
586
|
+
if (r.skipped) return { text: r.note ?? 'Not run.' }
|
|
587
|
+
const images = []
|
|
588
|
+
const frames = (r.frames ?? []).map(({ image, ...rest }) => {
|
|
589
|
+
if (image) images.push({ data: image.data, mime: image.mime ?? 'image/jpeg' })
|
|
590
|
+
return image ? rest : { ...rest, picture: 'none' }
|
|
591
|
+
})
|
|
592
|
+
const lines = [`${json({ ...r, frames })}${images.length ? `\nThe ${images.length} pictures below are in time order.` : ''}`]
|
|
593
|
+
// A fall, the walks and the missing pictures, said plainly after the numbers.
|
|
594
|
+
if (r.fell) lines.push(String(r.fell))
|
|
595
|
+
for (const w of r.goto ?? []) lines.push(`Walk ${w.step + 1} to ${w.target}: ${w.outcome}. ${w.note ?? ''}`.trim())
|
|
596
|
+
// A walk that ran out of time is not a route that is blocked.
|
|
597
|
+
if ((r.goto ?? []).some((w) => w.outcome === 'timeout')) {
|
|
598
|
+
lines.push('A timeout means the time ran out, not that the way is blocked: give that step more seconds (up to 30), run: true, or a nearer goto first.')
|
|
599
|
+
}
|
|
600
|
+
const missing = (r.frames ?? []).filter((f) => !f.image)
|
|
601
|
+
if (missing.length > 0) {
|
|
602
|
+
lines.push(`${missing.length} of ${(r.frames ?? []).length} pictures did not come back: ${firstLine(missing[0].error ?? 'no reason given')}`)
|
|
603
|
+
}
|
|
604
|
+
const text = lines.join('\n')
|
|
605
|
+
// Only a run that brought back pictures counts as a look at the space.
|
|
606
|
+
return { text, images, ...(images.length > 0 ? { verifies: 'view' } : {}) }
|
|
607
|
+
},
|
|
608
|
+
}
|
|
609
|
+
|
|
610
|
+
const nwEval = {
|
|
611
|
+
name: 'nw_eval',
|
|
612
|
+
description:
|
|
613
|
+
'Runs a short JavaScript snippet inside the running space and returns its value as JSON: an expression ("world.find(\'lamp\').length", "placed.map(p => p.id)") or statements ending in return. In scope: `game` (what createGame returned), world (the SDK World, when the code made one), root, scene, camera, renderer, THREE, SDK, placed (the creator\'s placed objects), player (its position) and pilot. Read values with it instead of adding probes or logs to the source. What it changes is not saved and is gone at the next rebuild, so never use it to change the space the creator sees. 5 seconds at most; a snippet that never returns hangs the studio.',
|
|
614
|
+
shape: EVAL_SHAPE,
|
|
615
|
+
readOnly: true,
|
|
616
|
+
async handler(args, ctx) {
|
|
617
|
+
const code = String(args?.code ?? '')
|
|
618
|
+
const timeoutMs = Math.min(5000, Math.max(100, Math.floor(args?.timeoutMs ?? 2000)))
|
|
619
|
+
const r = await rpcOf(ctx)('eval', { code, timeoutMs }, 12_000)
|
|
620
|
+
if (!r?.ok) return { text: `Error: ${r?.error ?? 'the viewport did not answer.'}${r?.stack ? `\n${r.stack}` : ''}`, isError: true }
|
|
621
|
+
const body = r.truncated && typeof r.value === 'string' ? r.value : json(r.value)
|
|
622
|
+
return { text: `${r.type}${r.truncated ? ' (cut at 20000 characters of JSON)' : ''}:\n${body}` }
|
|
623
|
+
},
|
|
624
|
+
}
|
|
625
|
+
|
|
626
|
+
const nwLogs = {
|
|
627
|
+
name: 'nw_logs',
|
|
628
|
+
description:
|
|
629
|
+
'The running space\'s console and the studio\'s notes about it, oldest first: its own code\'s console output (source "game"), uncaught errors (runtime), model load errors and auto-size notices such as a 43 m model shown at 3 m (asset), builds and mounts (studio), and materials (shader): one that failed to build and is drawn flat black, with its mesh and the line, a pipeline the GPU refused with the WGSL line, and WebGL habits such as onBeforeCompile that do nothing here. Pass the next value from your last call as since to read only what is new.',
|
|
630
|
+
shape: LOGS_SHAPE,
|
|
631
|
+
readOnly: true,
|
|
632
|
+
async handler(args, ctx) {
|
|
633
|
+
const params = clean({
|
|
634
|
+
since: args?.since,
|
|
635
|
+
level: args?.level ?? 'all',
|
|
636
|
+
source: args?.source ?? 'all',
|
|
637
|
+
limit: args?.limit ?? 80,
|
|
638
|
+
clear: args?.clear ?? false,
|
|
639
|
+
})
|
|
640
|
+
const r = await rpcOf(ctx)('logs', params, 8_000)
|
|
641
|
+
if (!r?.ok) return { text: `No log: ${r?.error ?? 'the viewport did not answer.'}`, isError: true }
|
|
642
|
+
const lines = (r.entries ?? []).map((e) => `[${e.seq}] +${(e.t / 1000).toFixed(1)}s ${e.level} ${e.source}: ${e.text}`)
|
|
643
|
+
if (lines.length === 0) lines.push(params.since !== undefined ? 'Nothing new.' : 'The log is empty.')
|
|
644
|
+
lines.push(`next: ${r.next}`)
|
|
645
|
+
if (r.dropped > 0) lines.push(`dropped: ${r.dropped} older entries fell out of the log before you read them.`)
|
|
646
|
+
return { text: lines.join('\n') }
|
|
647
|
+
},
|
|
648
|
+
}
|
|
649
|
+
|
|
650
|
+
/** What the look leaves to the engine, read from the config on disk (schema
|
|
651
|
+
* lookAdvice): nw_check's look lines, without the HDRI's sun, which reads
|
|
652
|
+
* the whole picture and is nw_check's alone. A sky of none is no warning
|
|
653
|
+
* when the brief itself picks none, as nw_check reads it
|
|
654
|
+
* (assets/brief.mjs adviceUnderBrief): read here from the schema alone,
|
|
655
|
+
* since the CLI vendors this file by itself, with no folder around it. */
|
|
656
|
+
async function lookLeft(projectRoot) {
|
|
657
|
+
const lines = await lookLeftAlone(projectRoot)
|
|
658
|
+
// Where the look draws otherwise than style.json says (as assets/brief.mjs
|
|
659
|
+
// adviceUnderBrief has it; this file is copied alone into the CLI).
|
|
660
|
+
try {
|
|
661
|
+
const style = validateStyle(JSON.parse(await fsp.readFile(path.join(projectRoot, STYLE_FILE), 'utf8')))
|
|
662
|
+
if (style.ok) lines.push(...styleAdvice(style.style, JSON.parse(await fsp.readFile(path.join(projectRoot, 'game.config.json'), 'utf8'))))
|
|
663
|
+
} catch {
|
|
664
|
+
// no style.json, or one nw_check reports
|
|
665
|
+
}
|
|
666
|
+
return lines
|
|
667
|
+
}
|
|
668
|
+
|
|
669
|
+
async function lookLeftAlone(projectRoot) {
|
|
670
|
+
if (!projectRoot) return []
|
|
671
|
+
let lines
|
|
672
|
+
try {
|
|
673
|
+
lines = lookAdvice(JSON.parse(await fsp.readFile(path.join(projectRoot, 'game.config.json'), 'utf8')))
|
|
674
|
+
} catch {
|
|
675
|
+
// A config that cannot be read is the build's to say.
|
|
676
|
+
return []
|
|
677
|
+
}
|
|
678
|
+
const none = (l) => /^sky is none\b/.test(String(l))
|
|
679
|
+
if (!lines.some(none)) return lines
|
|
680
|
+
try {
|
|
681
|
+
const brief = validateBrief(JSON.parse(await fsp.readFile(path.join(projectRoot, BRIEF_FILE), 'utf8')))
|
|
682
|
+
if (brief.ok && brief.brief.light.sky.kind === 'none') return lines.filter((l) => !none(l))
|
|
683
|
+
} catch {
|
|
684
|
+
// no brief, or one that does not parse: the sky is a warning as it is
|
|
685
|
+
}
|
|
686
|
+
return lines
|
|
687
|
+
}
|
|
688
|
+
|
|
689
|
+
const nwStatus = {
|
|
690
|
+
name: 'nw_status',
|
|
691
|
+
description:
|
|
692
|
+
'What the running space reports right now: the build and mount state, runtime errors, materials (how many were built, and every one that failed to build and is drawn flat black, or uses a WebGL habit that does nothing here), the files it loads through ctx.assets that failed (assets: a missing path, or one that would not decode), what is still loading (loading: its files, the look\'s HDRI sky and LUT, placed models and a build still mounting, and whether it has settled), whether the creator is playing, the frame counters and fps, the player\'s position, the status line, the world\'s size, triangles and draw calls, the look, every placed model with its size in metres and whether the studio auto-sized it, lookWarnings: what the look leaves to the defaults (a sky of none, look values and light not set from the brief), as nw_check says it, and perf: the frame time nw_check last measured for the space as it is now (the spawn view and each hero view at each tier, the worst view\'s numbers, against its limit: high a 1080p screen, 16.7 ms at p95; low a phone\'s pixels, 33 ms), with draw calls, triangles and GPU memory. nw_status never measures: when the space changed since, perfError says so and nw_check measures it.',
|
|
693
|
+
shape: {},
|
|
694
|
+
readOnly: true,
|
|
695
|
+
async handler(_args, ctx) {
|
|
696
|
+
const built = await buildIfNeeded(ctx)
|
|
697
|
+
const r = await rpcOf(ctx)('status', {}, 10_000)
|
|
698
|
+
if (!r || (r.ok === false && r.build === undefined)) {
|
|
699
|
+
return { text: `No status: ${r?.error ?? 'the studio did not answer.'}`, isError: true }
|
|
700
|
+
}
|
|
701
|
+
const { build, runtime, live, liveError } = r
|
|
702
|
+
const { ok: _ok, ...liveFields } = live && typeof live === 'object' ? live : {}
|
|
703
|
+
const lookWarnings = await lookLeft(ctx?.projectRoot)
|
|
704
|
+
// Frame time as nw_check kept it for the space as it is now; nw_status
|
|
705
|
+
// never measures, so asking for the state never takes the viewport over.
|
|
706
|
+
const timed = await perfFor(ctx, { measure: false })
|
|
707
|
+
const merged = {
|
|
708
|
+
build,
|
|
709
|
+
runtime,
|
|
710
|
+
...liveFields,
|
|
711
|
+
...(live ? {} : { liveError: liveError ?? live?.error ?? 'The viewport did not answer, so there are no live numbers.' }),
|
|
712
|
+
...(lookWarnings.length ? { lookWarnings } : {}),
|
|
713
|
+
...(timed.perf ? { perf: timed.perf } : { perfError: timed.error }),
|
|
714
|
+
}
|
|
715
|
+
const note = built.failed ? `${buildFailed(built)}\n` : built.held ? `${built.safe ? heldNote(built) : 'The creator is playing, so your latest edit has not run yet.'}\n` : ''
|
|
716
|
+
return { text: `${note}${json(merged)}`, ...(timed.perf ? { perf: timed.perf } : {}) }
|
|
717
|
+
},
|
|
718
|
+
}
|
|
719
|
+
|
|
720
|
+
const nwStudioScreenshot = {
|
|
721
|
+
name: 'nw_studio_screenshot',
|
|
722
|
+
description:
|
|
723
|
+
'A screenshot of the whole studio window, chat panel and all. Only for checking the studio\'s own interface; to see the space, use nw_view.',
|
|
724
|
+
shape: {},
|
|
725
|
+
readOnly: true,
|
|
726
|
+
async handler(_args, ctx) {
|
|
727
|
+
const r = await rpcOf(ctx)('screenshot', {}, 30_000)
|
|
728
|
+
if (!r?.ok || !r.base64) return { text: r?.error ?? 'No screenshot came back.', isError: true }
|
|
729
|
+
return { text: 'The studio window.', images: [{ data: r.base64, mime: 'image/png' }] }
|
|
730
|
+
},
|
|
731
|
+
}
|
|
732
|
+
|
|
733
|
+
export const TOOLS = [nwView, nwPlay, nwEval, nwLogs, nwStatus, nwStudioScreenshot]
|