3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
// Which game fields and MCP tool fields the last npm release accepts, and which guide text names a newer one without a
// version tag. The site deploys from main, so its guides run ahead of the install line (#1131).
//
// node scripts/guide-fields.mjs snapshot [--tag v0.20.0] write bench/guide-fields/released.json
// node scripts/guide-fields.mjs check list newer fields a guide does not tag
//
// A guide marks a newer field with `{since 0.21.0}` in the same table row, bullet or paragraph. The site draws the mark as a
// small tag; the plain-text guide keeps it as written.
import { execFileSync } from 'node:child_process';
import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
const REPOSITORY_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
export const RELEASED_FIELDS_PATH = join(REPOSITORY_ROOT, 'bench', 'guide-fields', 'released.json');
export const GUIDE_PATHS = Object.freeze(['docs/game.md', 'docs/mcp.md']);
export const SINCE_MARK = /\{since (\d+\.\d+\.\d+)\}/;
const MAXIMUM_SCHEMA_DEPTH = 8;
/** The game setup fields as dotted paths: `camera`, `player.animation`, `npcs[].path`. Read from the source text so an old checkout works too. */
export function collectGameFields(root = REPOSITORY_ROOT) {
const source = readFileSync(join(root, 'src', 'game-setup.js'), 'utf8');
const namesOf = constantName => {
const match = source.match(new RegExp(`const ${constantName} = \\[([^\\]]*)\\]`));
if (!match) throw new Error(`src/game-setup.js has no ${constantName} list; update scripts/guide-fields.mjs.`);
return [...match[1].matchAll(/'([^']+)'/g)].map(entry => entry[1]);
};
return [
...namesOf('SETUP_FIELDS'),
...namesOf('PLAYER_FIELDS').map(name => `player.${name}`),
...namesOf('NPC_FIELDS').map(name => `npcs[].${name}`),
];
}
function walkSchema(schema, path, found, depth) {
if (!schema || typeof schema !== 'object' || depth > MAXIMUM_SCHEMA_DEPTH) return;
for (const [name, child] of Object.entries(schema.properties ?? {})) {
const childPath = path ? `${path}.${name}` : name;
found.add(childPath);
walkSchema(child, childPath, found, depth + 1);
}
if (schema.items) walkSchema(schema.items, `${path}[]`, found, depth + 1);
for (const key of ['anyOf', 'oneOf', 'allOf']) {
for (const variant of schema[key] ?? []) walkSchema(variant, path, found, depth + 1);
}
}
/** Every input property of every MCP tool as `tool path`, such as `scene_render_submit settings.multilayer`. */
export async function collectToolFields() {
const { Client } = await import('@modelcontextprotocol/client');
const { InMemoryTransport } = await import('@modelcontextprotocol/server');
const { createAgentMcpServer } = await import('./mcp-server.mjs');
const server = createAgentMcpServer({ async close() {} });
const client = new Client({ name: 'guide-fields', version: '1' });
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
await server.connect(serverTransport);
await client.connect(clientTransport);
try {
const { tools } = await client.listTools();
const fields = [];
for (const tool of tools) {
const found = new Set();
walkSchema(tool.inputSchema, '', found, 0);
fields.push(...[...found].map(path => `${tool.name} ${path}`));
}
return fields;
} finally {
await client.close();
await server.close();
}
}
export async function collectFields(root = REPOSITORY_ROOT) {
return {
game: collectGameFields(root).sort(),
tools: (await collectToolFields()).sort(),
};
}
export function readReleasedFields() {
return JSON.parse(readFileSync(RELEASED_FIELDS_PATH, 'utf8'));
}
function lastSegment(path) {
return path.split('.').pop().replace(/\[\]$/, '');
}
/** The fields the current source accepts that the release did not: `{ game: [...], tools: [...] }`. */
export function newerFields(current, released) {
const releasedGame = new Set(released.game);
const releasedToolFields = new Set(released.tools);
return {
game: current.game.filter(path => !releasedGame.has(path)),
tools: current.tools.filter(entry => !releasedToolFields.has(entry)),
};
}
// A guide line is a table row, a bullet, or the blank-line-separated paragraph around it.
function guideBlocks(text) {
const blocks = [];
let paragraph = [];
const flush = () => {
if (paragraph.length) blocks.push(paragraph.join('\n'));
paragraph = [];
};
for (const line of text.replace(/\r\n/g, '\n').split('\n')) {
if (line.trim() === '') flush();
else if (/^\s*(\||[-*] )/.test(line)) {
flush();
blocks.push(line);
} else paragraph.push(line);
}
flush();
return blocks;
}
function escapeRegExp(text) {
return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}
// True when the block names the field in backticks, alone or followed by `.` or `[` (a longer path under it).
export function mentions(block, name) {
return block.includes(`\`${name}\``) || new RegExp(`\`${escapeRegExp(name)}[\`.\\[]`).test(block);
}
/**
* Newer fields a guide names without a `{since X.Y.Z}` mark. A game field is matched by its dotted path (`player.animation`,
* `npcs[].path`, or the bare name for a top-level one). A tool field is matched by its last name only when no released field
* carries that name, so a common word such as `id` or `note` never trips it.
*/
export function findUnmarkedFields({ guides, newer, released }) {
const releasedLeaves = new Set(released.tools.map(entry => lastSegment(entry.split(' ')[1])));
const gameNames = newer.game;
const toolNames = [...new Set(newer.tools.map(entry => lastSegment(entry.split(' ')[1])))].filter(name => !releasedLeaves.has(name));
const problems = [];
for (const [guide, text] of Object.entries(guides)) {
for (const block of guideBlocks(text)) {
if (SINCE_MARK.test(block)) continue;
for (const name of [...gameNames, ...toolNames]) {
if (mentions(block, name)) problems.push({ guide, name, line: block.split('\n')[0].slice(0, 100) });
}
}
}
return problems;
}
export function readGuides(root = REPOSITORY_ROOT) {
return Object.fromEntries(GUIDE_PATHS.map(path => [path, readFileSync(join(root, path), 'utf8')]));
}
function buildTaggedSnapshot(tag) {
const folder = mkdtempSync(join(tmpdir(), 'crucible-guide-fields-'));
try {
const archive = execFileSync('git', ['archive', tag], { cwd: REPOSITORY_ROOT, maxBuffer: 1 << 30 });
execFileSync('tar', ['-x'], { cwd: folder, input: archive });
symlinkSync(join(REPOSITORY_ROOT, 'node_modules'), join(folder, 'node_modules'), 'junction');
copyFileSync(fileURLToPath(import.meta.url), join(folder, 'scripts', 'guide-fields.mjs'));
const output = execFileSync(process.execPath, [join(folder, 'scripts', 'guide-fields.mjs'), 'print'], { cwd: folder, encoding: 'utf8', maxBuffer: 1 << 28 });
return JSON.parse(output);
} finally {
rmSync(folder, { recursive: true, force: true });
}
}
async function main(argumentsList) {
const [command, ...rest] = argumentsList;
if (command === 'print') {
process.stdout.write(JSON.stringify(await collectFields()));
return 0;
}
if (command === 'snapshot') {
const tagIndex = rest.indexOf('--tag');
const tag = tagIndex >= 0 ? rest[tagIndex + 1] : null;
const fields = tag ? buildTaggedSnapshot(tag) : await collectFields();
const release = tag ? tag.replace(/^v/, '') : JSON.parse(readFileSync(join(REPOSITORY_ROOT, 'package.json'), 'utf8')).version;
mkdirSync(dirname(RELEASED_FIELDS_PATH), { recursive: true });
writeFileSync(RELEASED_FIELDS_PATH, `${JSON.stringify({ release, ...fields }, null, 1)}\n`);
console.log(`Wrote ${RELEASED_FIELDS_PATH} for ${release}: ${fields.game.length} game fields, ${fields.tools.length} tool fields.`);
return 0;
}
if (command === 'check') {
const released = readReleasedFields();
const newer = newerFields(await collectFields(), released);
const problems = findUnmarkedFields({ guides: readGuides(), newer, released });
for (const problem of problems) console.log(`${problem.guide}: \`${problem.name}\` is newer than ${released.release} and needs {since X.Y.Z}: ${problem.line}`);
console.log(problems.length ? `${problems.length} unmarked.` : `clean (${newer.game.length} newer game fields, ${newer.tools.length} newer tool fields).`);
return problems.length ? 1 : 0;
}
console.error('Usage: node scripts/guide-fields.mjs snapshot [--tag v0.20.0] | check');
return 2;
}
if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
process.exitCode = await main(process.argv.slice(2));
}