3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
// scene_capabilities answers with a short index and serves the detail by topic, so the tool schemas stay small.
// A topic is a key of the scene capabilities, a runtime section (jobs, assets, ...) or the outline of a full input schema
// (motion, environment, meshEdit, ...). A union such as meshEdit takes a branch: meshEdit.bevel.
import * as z from 'zod/v4';
import { compactType, outlineSchema, unionBranches } from './schema-outline.mjs';
import { AGENT_TOOL_EXAMPLES } from './tool-examples.mjs';
const RUNTIME_SECTIONS = ['sceneLimits', 'preview', 'review', 'assets', 'packs', 'jobs', 'addons', 'unsupported'];
const SUMMARY_LENGTH = 110;
// Scalars (booleans and numbers) of the scene capabilities share one topic instead of one each.
const FLAGS_TOPIC = 'flags';
function isScalar(value) {
return typeof value === 'boolean' || typeof value === 'number';
}
function firstSentence(text = '') {
const sentence = text.split(/\.\s/)[0].replace(/\.$/, '');
return sentence.length > SUMMARY_LENGTH ? `${sentence.slice(0, SUMMARY_LENGTH - 1)}…` : sentence;
}
function sceneTopics(scene) {
const topics = new Map();
const flags = {};
for (const [name, value] of Object.entries(scene)) {
if (isScalar(value)) flags[name] = value;
else topics.set(name, value);
}
topics.set('examples', AGENT_TOOL_EXAMPLES);
topics.set(FLAGS_TOPIC, flags);
return topics;
}
function inputJsonSchema(schema) {
return z.toJSONSchema(schema, { io: 'input', unrepresentable: 'any' });
}
const RULE_KINDS = /^(Face|Edge|Vertex) rule/;
/** A rule argument (select, edges, verts) is typed faceRule, edgeRule or vertexRule, so the answer can state each rule once. */
function argumentType(property, definitions) {
const kind = RULE_KINDS.exec(property.description ?? '');
return kind ? `${kind[1].toLowerCase()}Rule` : compactType(property, definitions);
}
/** One line of arguments for a branch: "width:number, segments?:int[1..16]"; ? marks an optional one, the discriminator is left out. */
function branchArguments(branch, definitions) {
const required = new Set(branch.required ?? []);
return Object.entries(branch.properties ?? {})
.filter(([, property]) => property.const === undefined)
.map(([name, property]) => `${name}${required.has(name) ? '' : '?'}:${argumentType(property, definitions)}`)
.join(', ');
}
function branchSummary(branch, definitions) {
return { args: branchArguments(branch, definitions), ...(branch.description ? { note: firstSentence(branch.description) } : {}) };
}
/** Each rule type once, from the first branch that spells it out, so a rule is not repeated for every op that takes it. */
function ruleLegend(branches) {
const legend = {};
for (const branch of branches.values()) {
for (const property of Object.values(branch.properties ?? {})) {
const kind = /^(Face|Edge|Vertex) rule:/.exec(property.description ?? '');
const name = kind ? `${kind[1].toLowerCase()}Rule` : undefined;
if (name && legend[name] === undefined) legend[name] = property.description;
}
}
return legend;
}
function unionIndex(topic, branches, definitions = {}) {
const entries = {};
for (const [name, branch] of branches) entries[name] = branchSummary(branch, definitions);
const rules = ruleLegend(branches);
return {
branches: entries,
...(Object.keys(rules).length ? { rules } : {}),
use: `args are name:type, ? marks optional; topic ${topic}.<name> for the notes of every field of one branch; modifier ops not listed here are in meshModifiers`,
};
}
function outlineAnswer(topic, branchName, schema) {
const jsonSchema = inputJsonSchema(schema);
const branches = unionBranches(jsonSchema);
const withDefinitions = part => ({ ...part, ...(jsonSchema.$defs ? { $defs: jsonSchema.$defs } : {}) });
if (!branchName) return branches ? unionIndex(topic, branches, jsonSchema.$defs) : outlineSchema(jsonSchema);
if (branches?.has(branchName)) return outlineSchema(withDefinitions(branches.get(branchName)));
// A short name such as inset or extrude stands for every branch that starts with it: inset_region and inset_individual.
const prefixed = branches ? [...branches].filter(([name]) => name.startsWith(`${branchName}_`)) : [];
if (prefixed.length === 1) return outlineSchema(withDefinitions(prefixed[0][1]));
if (prefixed.length > 1) return unionIndex(topic, new Map(prefixed), jsonSchema.$defs);
// A dotted field of a plain topic, such as environment.spotLights, is that field's outline.
const ownProperties = jsonSchema.properties ?? {};
if (!branches && Object.hasOwn(ownProperties, branchName)) return outlineSchema(withDefinitions(ownProperties[branchName]));
const known = branches ? [...branches.keys()] : Object.keys(ownProperties);
const sharedField = branches && [...branches.values()].some(branch => Object.hasOwn(branch.properties ?? {}, branchName));
const fieldNote = sharedField ? ` ${branchName} is a field of those branches, not a branch: open one branch to see it.` : '';
throw new TopicEntryError(`Topic ${topic} has no ${branches ? 'branch' : 'field'} ${branchName}. ${branches ? 'Branches' : 'Fields'}: ${known.join(', ') || 'none'}.${fieldNote}`);
}
/** A near miss of a topic name: a leading "scene." is dropped, and a name that contains or is contained by exactly one topic (uvs for meshUv) stands for it. */
function closestTopic(name, allNames) {
if (allNames.includes(name)) return name;
const stem = name.toLowerCase().replace(/s$/, '');
const near = stem.length < 2 ? [] : allNames.filter(candidate => {
const lowered = candidate.toLowerCase();
return lowered.includes(stem) || (lowered.length > 2 && stem.includes(lowered));
});
return near.length === 1 ? near[0] : undefined;
}
// Words an agent reaches for that stand for a topic under another name.
const TOPIC_ALIASES = Object.freeze({ render: 'jobs', renders: 'jobs', renderjobs: 'jobs' });
function editDistance(first, second) {
let previousRow = Array.from({ length: second.length + 1 }, (_, index) => index);
for (let row = 1; row <= first.length; row++) {
const currentRow = [row];
for (let column = 1; column <= second.length; column++) {
const substitution = previousRow[column - 1] + (first[row - 1] === second[column - 1] ? 0 : 1);
currentRow.push(Math.min(previousRow[column] + 1, currentRow[column - 1] + 1, substitution));
}
previousRow = currentRow;
}
return previousRow[second.length];
}
/** The topics worth suggesting for an unknown name: an alias first, then names within two edits or sharing a stem. */
function suggestTopics(name, allNames) {
const lowered = name.toLowerCase();
const aliased = TOPIC_ALIASES[lowered];
if (aliased && allNames.includes(aliased)) return [aliased];
const stem = lowered.replace(/(ies|y|s)$/, '');
return allNames.filter(candidate => {
const candidateLowered = candidate.toLowerCase();
return editDistance(lowered, candidateLowered) <= 2 || (stem.length >= 4 && candidateLowered.includes(stem));
}).slice(0, 3);
}
/** The dotted topics (meshEdit.uv_unwrap) whose branch is the given name, for a bare op name or the wrong plural form. */
function branchTopicsNamed(branchName, outlineSources) {
const found = [];
for (const [topic, schema] of outlineSources) {
const branches = unionBranches(inputJsonSchema(schema));
if (branches?.has(branchName)) found.push(`${topic}.${branchName}`);
}
return found.slice(0, MAX_SUGGESTIONS);
}
/** The topics a caller can ask for, by name. */
export function capabilityTopicNames(capabilities, outlineSources) {
const names = {
scene: [...sceneTopics(capabilities.scene).keys()],
runtime: RUNTIME_SECTIONS,
schemas: [...outlineSources.keys()],
};
return names;
}
/** The most topics one scene_capabilities call may list. */
export const MAX_TOPICS_PER_CALL = 8;
/** The most unknown entries a partial list answer reports, and the most suggestions each one carries. */
const MAX_REPORTED_UNKNOWN = 4;
const MAX_SUGGESTIONS = 3;
/** Thrown when one entry of a topic request cannot be answered; the note says why and what it may have meant. */
class TopicEntryError extends Error {
constructor(note, suffix = '') {
super(`${note}${suffix}`);
this.note = note;
}
}
/** Thrown when a topic name matches nothing; the message also lists every topic. */
class UnknownTopicError extends TopicEntryError {
constructor(note, allNames) {
super(note, ` Topics: ${allNames.join(', ')}.`);
}
}
const GROUP_NAMES = ['scene', 'runtime', 'schemas'];
function indexAnswer(capabilities, names) {
return {
format: capabilities.scene.format, schemaVersion: capabilities.scene.schemaVersion,
phase: capabilities.phase, availableIn: capabilities.availableIn,
how: `Call scene_capabilities with topic set to a name below, or to a list of up to ${MAX_TOPICS_PER_CALL} names to read several at once. Tools list common fields; each name in topics.schemas gives the full field list of a recipe part, and the group names scene, runtime and schemas list their topics (meshEdit and meshStack also take <name>.<op>, geometries takes geometries.<type>). examples.<tool> is one complete call.`,
topics: names,
};
}
function answerOneTopic(capabilities, topic, names, outlineSources) {
const allNames = [...names.scene, ...names.runtime, ...names.schemas];
// A group name is not a topic, but an agent that read the index asks for it: answer with the topics it holds.
if (GROUP_NAMES.includes(topic) && !allNames.includes(topic)) {
return { topic, value: { topics: names[topic], use: `${topic} is a group of topics; ask for one of its names, or ${topic}.<name>.` } };
}
const parts = topic.split('.');
// The index groups topics under scene, runtime and schemas; a caller may repeat the group as a prefix (schemas.geometries).
if (GROUP_NAMES.includes(parts[0]) && parts.length > 1) parts.shift();
const [requestedName, branchName] = parts;
const aliased = TOPIC_ALIASES[requestedName.toLowerCase()];
const name = closestTopic(requestedName, allNames) ?? (allNames.includes(aliased) ? aliased : requestedName);
const notes = sceneTopics(capabilities.scene).get(name);
const runtime = RUNTIME_SECTIONS.includes(name) ? capabilities[name] : undefined;
const source = outlineSources.get(name);
const found = [notes, runtime, source].some(value => value !== undefined);
if (!found) {
const suggestions = [...new Set([...suggestTopics(requestedName, allNames), ...branchTopicsNamed(requestedName, outlineSources)])].slice(0, MAX_SUGGESTIONS);
const didYouMean = suggestions.length ? ` Did you mean ${suggestions.join(' or ')}?` : '';
throw new UnknownTopicError(`Unknown topic ${topic}.${didYouMean}`, allNames);
}
const answeredTopic = [name, branchName].filter(Boolean).join('.');
if (source) return { topic: answeredTopic, ...(notes === undefined ? {} : { notes }), fields: outlineAnswer(name, branchName, source) };
// A dotted name picks one entry of a plain topic: examples.scene_apply.
const content = notes ?? runtime;
if (branchName === undefined) return { topic: answeredTopic, value: content };
const entries = content !== null && typeof content === 'object' ? content : {};
if (!Object.hasOwn(entries, branchName)) {
const opTopics = branchTopicsNamed(branchName, outlineSources);
const opHint = opTopics.length ? ` ${branchName} is a branch: ask ${opTopics.join(' or ')}.` : '';
throw new TopicEntryError(`Topic ${name} has no entry ${branchName}. Entries: ${Object.keys(entries).join(', ') || 'none'}.${opHint}`);
}
return { topic: answeredTopic, value: entries[branchName] };
}
function checkTopicList(topics) {
if (topics.length === 0 || topics.length > MAX_TOPICS_PER_CALL) {
throw new Error(`topic list has ${topics.length} entries; pass 1 to ${MAX_TOPICS_PER_CALL} names, or one string.`);
}
const repeated = topics.filter((topic, position) => topics.indexOf(topic) !== position);
if (repeated.length) throw new Error(`topic list repeats ${[...new Set(repeated)].join(', ')}; name each topic once.`);
const notStrings = topics.filter(topic => typeof topic !== 'string' || topic.length === 0 || topic.length > 64);
if (notStrings.length) throw new Error('topic list entries must be strings of 1 to 64 characters.');
}
function answerTopicList(capabilities, topics, names, outlineSources) {
checkTopicList(topics);
const answers = {};
const unanswered = [];
for (const topic of topics) {
try {
answers[topic] = answerOneTopic(capabilities, topic, names, outlineSources);
} catch (error) {
if (!(error instanceof TopicEntryError)) throw error;
unanswered.push(error.note);
}
}
if (unanswered.length === 0) return { answers };
// One bad name does not fail the call: the valid topics answer and the rest are listed beside them.
if (Object.keys(answers).length > 0) {
return { answers, unknown: unanswered.slice(0, MAX_REPORTED_UNKNOWN), ...(unanswered.length > MAX_REPORTED_UNKNOWN ? { moreUnknown: unanswered.length - MAX_REPORTED_UNKNOWN } : {}), use: 'Call scene_capabilities with no topic for the list of topic names.' };
}
const allNames = [...names.scene, ...names.runtime, ...names.schemas];
throw new Error(`${unanswered.join(' ')} Topics: ${allNames.join(', ')}.`);
}
/** The index with no topic, the detail of one topic, or { answers } keyed by name for a list of topics. */
export function answerCapabilities(capabilities, topic, outlineSources) {
const names = capabilityTopicNames(capabilities, outlineSources);
if (topic === undefined) return indexAnswer(capabilities, names);
if (Array.isArray(topic)) return answerTopicList(capabilities, topic, names, outlineSources);
return answerOneTopic(capabilities, topic, names, outlineSources);
}