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/lib/rules.mjs
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
// What an agent working in a nowhere project needs to know, written into the
|
|
2
|
+
// project as AGENTS.md (Codex and most agents) and CLAUDE.md (Claude Code) by
|
|
3
|
+
// `nowhere new`, and handed to MCP clients as the server's instructions. The
|
|
4
|
+
// same rules the studio's own agent works by (apps/studio/electron/agent/prompt.mjs).
|
|
5
|
+
|
|
6
|
+
export const RULES = `# This is an Oda space
|
|
7
|
+
|
|
8
|
+
An Oda space is a 3D place on the web, drawn in its own style (a photograph, a painting, an ink drawing, a cartoon, a print, pixels: whatever the request is), published as a planet in the Oda universe (https://nowhere-psi.vercel.app): visitors fly in from space, walk around inside it and leave. This folder is a real TypeScript project, and all of it is yours to write.
|
|
9
|
+
|
|
10
|
+
## The contract
|
|
11
|
+
- \`src/main.ts\` exports \`createGame(ctx)\` returning \`{ root, update(dt), dispose() }\`. That contract is the only hard rule; it is what lets the universe host the space.
|
|
12
|
+
- \`import * as THREE from 'three'\` (also \`'three/webgpu'\` and \`'three/tsl'\`) and \`import { World } from '@nowhere/sdk'\` freely. Both are provided by the host at run time; do not install or bundle them.
|
|
13
|
+
- The renderer is three r186's WebGPURenderer: materials are node materials and shaders are TSL. The SDK has no ready-made materials: write every material and shader for this space's brief (\`nw_guide\` name "tsl-r185" has the API, and nothing to copy). \`onBeforeCompile\`, \`ShaderMaterial\` and \`EffectComposer\` do nothing here; \`nw_check\` and \`nw_status\` name any material that failed to build, its mesh and the line, and such a material is drawn flat black until you fix it.
|
|
14
|
+
- No \`requestAnimationFrame\` of your own: all motion happens in \`update(dt)\`.
|
|
15
|
+
- Everything you create lives under the returned \`root\` group, and \`dispose()\` frees what you made.
|
|
16
|
+
- Read input only through \`ctx.input.pressed(code)\` (KeyboardEvent.code names).
|
|
17
|
+
|
|
18
|
+
## The files
|
|
19
|
+
- \`style.json\`: how the space is drawn (\`nw_schema\` kind "style"), written before any picture: its medium, the works it is read from, shape, line, shading, surface, palette, rules, and the look's drawing techniques.
|
|
20
|
+
- \`game.config.json\`: the planet-level knobs (sky, fog, lighting, ground, bloom, and the look: tone mapping, exposure, grade, AO, vignette, grain, and its drawing techniques in look.style: outline, bands, hatch, halftone, paint, paper, pixel). A world has no edge and no size limit: lay it out around the origin as large as the place needs.
|
|
21
|
+
- \`scene.json\`: models placed by hand, each with an id, a kind and a solid flag. Your code sees them: \`ctx.placed\`, \`world.placed('door')\`, \`onTouch('door')\`, \`world.find('door')\`. Build the space around them where they exist, and never dispose or reparent them. To move one, edit scene.json.
|
|
22
|
+
- \`assets/\`: the space's files (models that scene.json places or code loads, textures, HDRIs, sounds, LUTs), each recorded with its licence in \`assets.lock.json\`; in code, \`ctx.assets\` loads them (\`texture\`, \`hdri\`, \`model\`, \`sound\`). A planet carries 100 MB at most. One unit is one metre and the visitor is 1.75 m tall: a model whose largest side is over 12 m or under 0.375 m is auto-sized to 3 m when it loads, unless its placement sets \`"normalize": false\` (what you want for anything made or imported to scale).
|
|
23
|
+
- Where the visitor starts is \`config.player.spawn\`; leave spawnPlayer's position out so it is honoured. The visitor walks at 7 m/s and runs at twice that; \`config.player\` sets \`speed\`, \`run\`, \`eyeHeight\` and \`fov\`, which come from the brief's scale.
|
|
24
|
+
|
|
25
|
+
## The SDK
|
|
26
|
+
The SDK's World class is the fast path: its objects and rules, and its visitor with WASD, run, jump, climbing and collisions for free. Read its guide before writing code for the first time (\`nw_docs\`, or \`oda docs\`). Drop to raw three.js wherever the SDK is too small for the idea.
|
|
27
|
+
|
|
28
|
+
## The order for a space
|
|
29
|
+
A new space, or a large change, is a loop against target pictures (\`nw_guide\` name "reference-loop" has it in full). Begin each step by recalling the bar and the time the creator gave it. Under a speed level, finishing before the time floor means something is missing. Under a quality step there is no floor: the time cap is the time you have. At the bar after the least rounds the approval card may be shown; while a round still raises the score and time and rounds are left, run one more first.
|
|
30
|
+
1. **The kickoff.** Before any other tool, ask the creator once, in one message: up to four questions that change the space, how the environment is made (built in 3D, a file of their own, or Marble, which is paid), and the speed level: quick (up to 30 minutes, 2 rounds, a bar of 8.0 out of 10), standard (1 to 3 hours, 8 rounds, 9.0) or deep (4 to 12 hours, 24 rounds, 9.2), with what each would cost; or, when a quality step was set (\`oda make --quality\`), that step instead, with no floor: 1 Quick (Sonnet 5.5 at medium effort, bar 8.0, 1 to 2 rounds, 30 minutes), 2 Standard (Sonnet 5.5 at xhigh, 8.5, 2 to 5 rounds, 90 minutes), 3 Careful (Opus 5.5 at xhigh, 9.0, 3 to 10 rounds, 240 minutes), 4 High (Opus 5.5 at max, 9.1, 5 to 16 rounds, 360 minutes) or 5 Max (Fable 5.2 at max, 9.2, 8 to 24 rounds, 720 minutes). With no answer, go on at standard, built in 3D, with nothing paid until they approve a cost. After it, ask nothing more that waits on them: choose, and say what you chose.
|
|
31
|
+
2. **The style, before any picture.** \`style.json\` (\`nw_schema\` kind "style"). A photograph is one style among the others, never the default, and no space starts from another space's look. When the creator attached pictures or named a style (an artist, a film, a print, an animation, a movement), analyse how they are drawn, not what they show: shape language and proportions, how much detail and where, the line, how light turns to shade, the surface, the palette and how it is used; write that with from "attached" or "named", citing each one. Otherwise research: search the web for concept artists, illustrators, printmakers, films, animation and art movements whose way of drawing suits the request, look at the creator's other spaces (\`nw_others\`), propose three directions that differ from each other and from all of those, draw one sample each (\`image_generate\` kind "direction"), show them, and write the creator's pick with from "chosen" (or, with no answer, the one least like the other spaces, from "researched"). Then the rules modelling, materials and light must keep to, and look: the drawing techniques for it, or null for a style the light and materials draw alone.
|
|
32
|
+
3. **The targets.** Four or more photos from the creator are the targets; otherwise plan 4 to 6 hero views with their cameras and draw them with \`image_generate\` kind "target" (once the creator agrees to its cost), show them, and draw again by the creator's notes, three times at most. They join the reference board (\`refs/\`), which \`nw_reference\` with \`board: true\` measures.
|
|
33
|
+
4. **The brief, before anything visual:** \`brief.json\` (\`nw_schema\` kind "brief": the targets as references with their numbers, palette, light, the visitor's scale, materials with their texel density, hero views H1 to H6 each citing its target from its camera, what the files may weigh, sources, the level and the bar) and \`brief.md\`, the same in words. No value is a default to keep: every colour, light, fog and size comes from the brief, which comes from the request and the targets, and every shape, material and sound is made for this request; there is no kit of parts to combine.
|
|
34
|
+
5. **The environment, code first.** Get things from the best place first: terrain, buildings, rocks, trees, water, sky and surfaces as procedural geometry and TSL in code; a scanned CC0 library (\`asset_search\`, \`asset_fetch\`, \`asset_import\`: Poly Haven, ambientCG) only for what code cannot bring to the targets; an HDRI or a physical sky as the brief's light says. Code weighs nothing in files but costs frame time. A splat environment is the creator's own file, or \`environment_generate\` only when they chose Marble, after they approve its cost.
|
|
35
|
+
6. **Props.** Code or a CC0 library first (Kenney through Poly Pizza too); a Blender model you script for this asset in bpy (\`nw_blender\`, \`nw_guide\` name "blender-modeling"), which scores every export (silhouette, bevel, materials, triangles) and says what to fix first; a paid generation, delit, only for a prop and only after the creator approves its cost in the conversation (\`asset_generate\` estimate, then submit with \`confirm\` set to the estimate's id; then \`asset_job\`), never for the space itself (a generated world the creator chose aside); and never make a hero asset from boxes and cylinders. \`asset_import\` is the only way a file from outside comes into \`assets/\`, and it records the licence in \`assets.lock.json\`: CC0 and public domain are fine, CC BY needs a credit, anything NC, ND or without a licence stays out, and nothing comes from ArtStation, Pinterest or Behance.
|
|
36
|
+
7. **Materials and compression.** \`asset_inspect\` every material and model against the brief's texel density (and what KTX2 would make of it), and fix what it says.
|
|
37
|
+
8. **The look.** Every look value from the brief's numbers with \`look_apply\` (sky, sun, fog, tone mapping, exposure, grade, bloom, AO, vignette), the drawing techniques from style.json's look (look.style), and \`config.player\` from its scale; \`nw_status\`'s \`lookWarnings\` must end empty. The preview and the planet draw the same pipeline, so what you see is what is published.
|
|
38
|
+
9. **Rounds at the hero views.** After each batch of changes, \`nw_view\` at each of H1 to H6 from its target's camera, \`look_compare\` against that target once the space has loaded (or \`nw_compare\`: the view beside it, with the differences in numbers), and a score out of 10 from a judge with no context (a helper given only the targets, the views and the rubric in "reference-loop", never your notes). Plan the next round on its top three differences, until it says close or matches and the score reaches the bar past the time floor, or the time or the rounds run out. Loop on every hero asset at least three times the same way: a round changes the asset in answer to what you saw.
|
|
39
|
+
10. **The approval and the stop gate.** Show the creator the last views beside the targets, the scores round by round, what the files weigh and the frame time; publish only when they say so; and step 5 of the checks below, every time.
|
|
40
|
+
|
|
41
|
+
Never in a space: decorative lettering (eyebrow labels, monospace capitals, a stray serif, 01/02/03 counters used as ornament), glowing orbs, shockwave rings, a beige wash, colour gone grey or oversaturated, copy-pasted repeats, bare single-colour surfaces where the style gives its surfaces texture, an empty sky, mush in the distance; and no em dashes in any text. A game's score, timer and rule signs that the request needs are not slop: draw them inside the world in the space's style.
|
|
42
|
+
|
|
43
|
+
The guides, with \`nw_guide\`: "reference-loop" for the loop, "art-direction" for the brief, "look-dev" before the look, "asset-sources" before making or fetching an asset, "tsl-r185" before any material or shader, "blender-modeling" before a Blender script, "asset-legality" for licences, "sound-design" before synthesising sounds, "playtesting" before writing \`nw_play\` scripts.
|
|
44
|
+
|
|
45
|
+
## How to check your work, every time
|
|
46
|
+
With the Oda MCP server connected (\`oda mcp\`), use its tools:
|
|
47
|
+
1. \`nw_check\` after edits: builds the space, mounts it in the preview and reports compile errors and anything it threw while running. Never say you are done while it fails.
|
|
48
|
+
2. \`nw_view\` to see the result: the visitor's view, an orbit or a close-up of any placement, kind or object, the whole map, or a camera you place. Code that compiles is not a space that looks right, so look after every visual change, close up and from the visitor's eyes.
|
|
49
|
+
3. \`nw_play\` to walk through it hands-free when movement or the layout changed: a timeline of held keys and mouse look, with pictures from the visitor's eyes, \`world.state\` and the frame rate. Walk to each place the creator named (a doorway, a stair, the far end of a room) with an \`nw_play\` step \`{ goto: "<its name>" }\`, and check that the visitor gets there and what they see on the way.
|
|
50
|
+
4. \`nw_eval\` to read a value from the running space, \`nw_logs\` for its console, load errors and materials, and \`nw_status\` for its state, instead of adding probes or logs to the source.
|
|
51
|
+
5. Before you say you are done: every element the creator asked for meets the acceptance line you wrote for it from the request (what a view or a walk must show); \`brief.json\` passes its schema (\`nw_check\` checks it) and \`lookWarnings\` is empty; with a reference, \`look_compare\` says close or matches at the hero views (or you say why not); \`nw_status\` shows no material errors; \`asset_ledger\` shows no problems.
|
|
52
|
+
6. \`nw_publish\` only when the creator asks for the space to be published.
|
|
53
|
+
|
|
54
|
+
Without it, from a terminal: \`oda tool <name>\` runs any of these tools with no window (\`oda tools\` lists them; the fields are flags, \`--<field> <value>\`, or \`--json\`), with the short forms \`oda view\`, \`oda play\`, \`oda eval\`, \`oda logs\`, \`oda status\`, \`oda look apply|compare\`, \`oda reference\`, \`oda compare\`, \`oda asset search|fetch|import|generate|job|ledger\`, \`oda blender\`, \`oda guide\`; the preview runs in headless Chrome and every picture lands in \`.nowhere/shots/\` with its path printed. Also \`oda check\` (build, schema and the planet's gates), \`oda dev\` (a live preview in the browser that reloads on every save; \`--headless\` keeps one open for the tool commands), \`oda publish\`.
|
|
55
|
+
|
|
56
|
+
## Games
|
|
57
|
+
When the creator asks for a game, build the game: a goal a visitor understands without being told, rules kept in \`world.state\` as phases, something that answers every act, losing as clear as winning, and a restart. Before you stop, play it through from the spawn with \`nw_play\` using only the visitor's keys, and read \`world.state\` with \`nw_eval\`: the goal reached, the count counted, the loss and the restart. A play is 60 s at most and starts afresh each time: play a longer game rule by rule, read the rest with \`nw_eval\`, and say which was played and which was read. \`world.damage\`, \`world.heal\`, \`hurtOnTouch\` and \`healOnTouch\` change the visitor's own HP, which nothing draws and which they carry to other planets; at 0 the run ends (on a published planet, the visit). So keep a game's stakes in \`world.state\`, and use HP only when the request asks for danger. Items: list what a visitor can find or keep under items in game.config.json and give only those (world.give, world.pickUpOnTouch).
|
|
58
|
+
`
|
|
59
|
+
|
|
60
|
+
export const MCP_INSTRUCTIONS = `Tools for making an Oda space (a 3D place drawn in its own style, published as a planet in the Oda universe, which visitors walk through) in the current project. Read nw_docs before writing code for the first time. Materials are TSL node materials on three r186's WebGPU renderer: write each one for the space's brief (nw_guide "tsl-r185" has the API; the SDK has no ready-made ones); onBeforeCompile, ShaderMaterial and EffectComposer do nothing, and nw_check names a material that failed to build. A new space is a loop against target pictures (nw_guide "reference-loop"), in this order: the kickoff, one message to the creator before any other tool (up to four questions, how the environment is made, and the speed level: quick, standard or deep, with its time, rounds, bar and cost, unless a quality step 1 to 5 set the model, effort, bar, rounds and minutes, with no floor), after which nothing waits on them; style.json, how the space is drawn (nw_guide "style": analysed from the creator's pictures or a named style, or researched, three directions drawn with image_generate kind "direction" and the creator's pick), a photograph only when that is the style; the target pictures (four or more photos from the creator, or image_generate kind "target" at 4 to 6 planned hero views, drawn in that style) on the reference board, which nw_reference with board true measures; brief.json (nw_schema kind "brief") and brief.md from those numbers, before anything visual, its hero views citing the targets; the environment in code first (procedural geometry and TSL), a scanned CC0 library (asset_search, asset_fetch, asset_import: Poly Haven, ambientCG) only for what code cannot reach, with an HDRI or a physical sky; the props (a CC0 library, a Blender model scripted for it in bpy with nw_blender, or a paid generation, delit, for a prop only after the creator approves its cost: asset_generate estimate, then submit with confirm); asset_inspect against the brief's texel density; every look value from the brief with look_apply, until nw_status's lookWarnings is empty; rounds at the brief's hero views H1 to H6: nw_view from each target's camera, look_compare (or nw_compare) against it once the space has loaded and a judge with no context scoring 0 to 10, each round fixing the top differences until look_compare says close or matches and the score reaches the bar past the time floor, or the time or rounds run out; then the approval (the last views, scores, weight and frame time, for the creator to say publish) and the stop gate: nw_check passing after the last edit, brief.json passing its schema, lookWarnings empty. No value is a default to keep: every colour, light, fog and size comes from the brief, which comes from the request and the targets, and every shape, material and sound is made for this request; the preview and the planet draw the same pipeline. Never in a space: decorative lettering used as ornament (a game's score, timer and rule signs the request needs are not slop: draw them in the world, in its style), glowing orbs, shockwave rings, a beige wash, greyed-out or oversaturated colour, copy-pasted repeats, bare single-colour surfaces where the style gives its surfaces texture, an empty sky, mush in the distance. Never make a hero asset from boxes and cylinders, and bring every outside file in through asset_import, which records its licence. After every batch of edits run nw_check, then look with nw_view (the visitor's view and close-ups); walk through it with nw_play, and read the running space with nw_eval, nw_logs and nw_status instead of adding probes to the source. Publish with nw_publish only when the creator asks. The project rules: src/main.ts exports createGame(ctx) returning { root, update(dt), dispose() }; three and @nowhere/sdk are provided by the host; no requestAnimationFrame of your own; everything under root; input only through ctx.input.pressed(code); the visitor walks at 7 m/s and runs at twice that unless config.player says otherwise. If there is no project yet, nw_new makes one. Items are on: list what a visitor can take away under items in game.config.json and give only those (world.give, world.pickUpOnTouch). Games: when the creator asks for a game, build the game (a goal a visitor understands untold, rules in world.state as phases, an answer to every act, losing as clear as winning, a restart), and before stopping play it through from the spawn with nw_play using only the visitor's keys and read world.state with nw_eval (the goal reached, the count counted, the loss, the restart). world.damage, world.heal, hurtOnTouch and healOnTouch change the visitor's own HP, which nothing draws; at 0 the run ends: keep a game's stakes in world.state and use HP only when the request asks for danger.`
|
package/lib/scaffold.mjs
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
// A new project: the studio's starter (template/), the agent rules beside it,
|
|
2
|
+
// and a git repository, so the project can be published (publishing commits
|
|
3
|
+
// it, and its first commit is what keeps it the same planet everywhere).
|
|
4
|
+
|
|
5
|
+
import fs from 'node:fs'
|
|
6
|
+
import fsp from 'node:fs/promises'
|
|
7
|
+
import path from 'node:path'
|
|
8
|
+
import { RULES } from './rules.mjs'
|
|
9
|
+
import { TEMPLATE, vendor } from './resources.mjs'
|
|
10
|
+
|
|
11
|
+
const GITIGNORE = ['node_modules/', '.nowhere/', 'dist/', '.DS_Store'].join('\n') + '\n'
|
|
12
|
+
|
|
13
|
+
/** Makes a project at `dir` (which must not exist, or be empty) titled
|
|
14
|
+
* `title`. Returns its absolute path. */
|
|
15
|
+
export async function createProject(dir, title) {
|
|
16
|
+
const root = path.resolve(dir)
|
|
17
|
+
if (fs.existsSync(root) && fs.readdirSync(root).length > 0) {
|
|
18
|
+
throw new Error(`${root} already exists and is not empty. Choose another folder.`)
|
|
19
|
+
}
|
|
20
|
+
await fsp.mkdir(root, { recursive: true })
|
|
21
|
+
await fsp.cp(TEMPLATE, root, { recursive: true })
|
|
22
|
+
|
|
23
|
+
const name = title?.trim() || path.basename(root).replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())
|
|
24
|
+
const configFile = path.join(root, 'game.config.json')
|
|
25
|
+
try {
|
|
26
|
+
const config = JSON.parse(await fsp.readFile(configFile, 'utf8'))
|
|
27
|
+
config.title = name.slice(0, 80)
|
|
28
|
+
await fsp.writeFile(configFile, `${JSON.stringify(config, null, 2)}\n`)
|
|
29
|
+
} catch {
|
|
30
|
+
// the template's own title stays
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
await fsp.writeFile(path.join(root, 'AGENTS.md'), RULES)
|
|
34
|
+
await fsp.writeFile(path.join(root, 'CLAUDE.md'), RULES)
|
|
35
|
+
await fsp.writeFile(path.join(root, '.gitignore'), GITIGNORE)
|
|
36
|
+
try {
|
|
37
|
+
await vendor('git.cjs').ensureRepo(root, name)
|
|
38
|
+
} catch {
|
|
39
|
+
// git is for publishing; the project works without it until then
|
|
40
|
+
}
|
|
41
|
+
return root
|
|
42
|
+
}
|
package/lib/setup.mjs
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
// `nowhere setup claude|codex`: registers the MCP server with an agent the
|
|
2
|
+
// creator already uses, for every project (user scope).
|
|
3
|
+
//
|
|
4
|
+
// Claude Code claude mcp add --scope user nowhere -- <command>
|
|
5
|
+
// Codex [mcp_servers.oda] in ~/.codex/config.toml
|
|
6
|
+
//
|
|
7
|
+
// <command> is `npx -y nowhere-engine@<version> mcp` for an installed package,
|
|
8
|
+
// and this very file's `node .../bin/nowhere.mjs mcp` for a checkout, so a
|
|
9
|
+
// development copy can be tried without publishing it.
|
|
10
|
+
|
|
11
|
+
import { execFileSync } from 'node:child_process'
|
|
12
|
+
import fs from 'node:fs'
|
|
13
|
+
import os from 'node:os'
|
|
14
|
+
import path from 'node:path'
|
|
15
|
+
import { PKG, VERSION } from './resources.mjs'
|
|
16
|
+
|
|
17
|
+
function serverCommand() {
|
|
18
|
+
const installed = PKG.split(path.sep).includes('node_modules')
|
|
19
|
+
return installed
|
|
20
|
+
? { command: 'npx', args: ['-y', `oda-engine@${VERSION}`, 'mcp'] }
|
|
21
|
+
: { command: process.execPath, args: [path.join(PKG, 'bin', 'nowhere.mjs'), 'mcp'] }
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
const quote = (s) => (/^[\w./@:=-]+$/.test(s) ? s : JSON.stringify(s))
|
|
25
|
+
|
|
26
|
+
export function setupClaude() {
|
|
27
|
+
const { command, args } = serverCommand()
|
|
28
|
+
const argv = ['mcp', 'add', '--scope', 'user', 'oda', '--', command, ...args]
|
|
29
|
+
try {
|
|
30
|
+
execFileSync('claude', argv, { stdio: 'inherit' })
|
|
31
|
+
return `Added the Oda MCP server to Claude Code. Open Claude Code in a game folder (or an empty one) and ask it to make a game; \`claude mcp list\` shows it.`
|
|
32
|
+
} catch (err) {
|
|
33
|
+
const line = `claude ${argv.map(quote).join(' ')}`
|
|
34
|
+
if (err.code === 'ENOENT') return `Claude Code (the claude command) is not installed here. With it installed, run:\n ${line}`
|
|
35
|
+
return `That did not work (${err.message}). It may already be added (\`claude mcp list\`); otherwise run:\n ${line}`
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export function setupCodex() {
|
|
40
|
+
const { command, args } = serverCommand()
|
|
41
|
+
const dir = process.env.CODEX_HOME || path.join(os.homedir(), '.codex')
|
|
42
|
+
const file = path.join(dir, 'config.toml')
|
|
43
|
+
const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : ''
|
|
44
|
+
if (/^\[mcp_servers\.oda\]/m.test(current)) return `${file} already has [mcp_servers.oda]. Edit it there if it needs to change.`
|
|
45
|
+
const block = [
|
|
46
|
+
'',
|
|
47
|
+
'# nowhere: make and publish Oda games (oda-engine)',
|
|
48
|
+
'[mcp_servers.oda]',
|
|
49
|
+
`command = ${JSON.stringify(command)}`,
|
|
50
|
+
`args = [${args.map((a) => JSON.stringify(a)).join(', ')}]`,
|
|
51
|
+
// The first npx run downloads the package.
|
|
52
|
+
'startup_timeout_sec = 120',
|
|
53
|
+
'tool_timeout_sec = 300',
|
|
54
|
+
'',
|
|
55
|
+
].join('\n')
|
|
56
|
+
fs.mkdirSync(dir, { recursive: true })
|
|
57
|
+
fs.appendFileSync(file, block)
|
|
58
|
+
return `Added the Oda MCP server to Codex (${file}). Start Codex in a game folder (or an empty one) and ask it to make a game.`
|
|
59
|
+
}
|