3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { validateGameRules } from './game-rules.js';
import { normalizeGameAnimation } from './game-animation.js';
import { parentTranslation } from './game-needs.js';
// The `game` section of a scene recipe: which node the player controls, how, with what camera and input, and the rules
// that decide when the game is won. It is plain data. The runtime in src/game.js reads it; nothing in it is code.
export const GAME_CAMERAS = Object.freeze(['follow', 'first-person', 'top-down', 'chase']);
export const GAME_INPUT_PRESETS = Object.freeze(['keyboard', 'gamepad', 'touch']);
export const GAME_CONTROLLERS = Object.freeze(['character', 'vehicle']);
// The actions startGame binds for every input preset (src/game.js); a rules input trigger can only name these.
export const GAME_INPUT_ACTIONS = Object.freeze(['jump', 'run']);
export const GAME_SETUP_LIMITS = Object.freeze({
maxSpeed: 100,
maxJumpSpeed: 100,
maxVehicleSpeed: 100,
maxFootOffset: 100,
maxGround: 10000,
maxNpcs: 16,
maxPathPoints: 256,
});
// The fixed names, then any kind a host registered at runtime, such as an allowlisted addon (docs/addons.md). The host gives
// a function returning { controllers, cameraRigs } here, so this module does not pull the player code with it.
let addedKinds = () => ({});
export function setAddedGameKinds(source) {
addedKinds = source;
}
const withAdded = (fixed, added = []) => [...new Set([...fixed, ...added])];
const SETUP_FIELDS = ['player', 'camera', 'input', 'physics', 'ground', 'rules', 'npcs'];
const PLAYER_FIELDS = ['node', 'controller', 'walkSpeed', 'runSpeed', 'jumpSpeed', 'maximumSpeed', 'footOffset', 'animation'];
const NPC_FIELDS = ['node', 'path', 'cruiseSpeed', 'footOffset', 'yaw', 'animation'];
function fail(path, problem) {
throw new RangeError(`Game setup ${path} ${problem}`);
}
function requireRecord(value, path) {
if (!value || typeof value !== 'object' || Array.isArray(value)) fail(path, 'must be an object, such as { "node": "creature" }.');
}
function rejectUnknownFields(record, allowed, path) {
for (const key of Object.keys(record)) {
if (!allowed.includes(key)) fail(`${path}.${key}`, `is not a field. Use one of: ${allowed.join(', ')}.`);
}
}
function chooseName(value, choices, fallback, path) {
if (value === undefined) return fallback;
if (!choices.includes(value)) fail(path, `is ${JSON.stringify(value)}. Use one of: ${choices.join(', ')}.`);
return value;
}
function boundedNumber(value, fallback, minimum, maximum, path) {
if (value === undefined) return fallback;
if (typeof value !== 'number' || !Number.isFinite(value) || value < minimum || value > maximum) {
fail(path, `must be a number from ${minimum} to ${maximum}, got ${JSON.stringify(value)}.`);
}
return value;
}
function normalizePlayer(player, nodeIds, nodes, controllerNames) {
requireRecord(player, 'player');
rejectUnknownFields(player, PLAYER_FIELDS, 'player');
if (typeof player.node !== 'string' || !nodeIds.has(player.node)) {
const known = [...nodeIds].slice(0, 12).join(', ') || 'none yet; add the node first';
fail('player.node', `names ${JSON.stringify(player.node)}, which is not a node of the scene. Use one of: ${known}.`);
}
parentTranslation(nodes, player.node, 'game.player.node');
const normalized = {
node: player.node,
controller: chooseName(player.controller, controllerNames, 'character', 'player.controller'),
walkSpeed: boundedNumber(player.walkSpeed, 3, 0, GAME_SETUP_LIMITS.maxSpeed, 'player.walkSpeed'),
runSpeed: boundedNumber(player.runSpeed, 6, 0, GAME_SETUP_LIMITS.maxSpeed, 'player.runSpeed'),
jumpSpeed: boundedNumber(player.jumpSpeed, 7, 0, GAME_SETUP_LIMITS.maxJumpSpeed, 'player.jumpSpeed'),
maximumSpeed: boundedNumber(player.maximumSpeed, 20, 0, GAME_SETUP_LIMITS.maxVehicleSpeed, 'player.maximumSpeed'),
footOffset: boundedNumber(player.footOffset, 0, -GAME_SETUP_LIMITS.maxFootOffset, GAME_SETUP_LIMITS.maxFootOffset, 'player.footOffset'),
};
if (player.animation !== undefined) normalized.animation = normalizeGameAnimation(player.animation, nodes, player.node, { path: 'player.animation', controller: normalized.controller });
return normalized;
}
function isAncestor(nodes, ancestorId, nodeId) {
const parentById = new Map(nodes.map(node => [node.id, node.parent]));
const visited = new Set([nodeId]);
for (let id = parentById.get(nodeId); id !== undefined && !visited.has(id); id = parentById.get(id)) {
if (id === ancestorId) return true;
visited.add(id);
}
return false;
}
function normalizePath(path, label) {
const valid = Array.isArray(path) && path.length >= 1 && path.length <= GAME_SETUP_LIMITS.maxPathPoints
&& path.every(point => Array.isArray(point) && (point.length === 2 || point.length === 3) && point.every(Number.isFinite));
if (!valid) fail(`${label}.path`, `must be 1 to ${GAME_SETUP_LIMITS.maxPathPoints} waypoints, each [x, z] in metres, such as [[0, -4], [6, -4]].`);
return path.map(point => [point[0], point[point.length - 1]]);
}
function normalizeNpc(npc, index, { nodeIds, nodes, taken }) {
const label = `npcs[${index}]`;
requireRecord(npc, label);
rejectUnknownFields(npc, NPC_FIELDS, label);
if (typeof npc.node !== 'string' || !nodeIds.has(npc.node)) {
fail(`${label}.node`, `names ${JSON.stringify(npc.node)}, which is not a node of the scene. Use one of: ${[...nodeIds].slice(0, 12).join(', ')}.`);
}
for (const other of taken) {
if (other === npc.node || isAncestor(nodes, other, npc.node) || isAncestor(nodes, npc.node, other)) {
fail(`${label}.node`, `is "${npc.node}", which overlaps the character "${other}" (same node, or one inside the other). Give each character its own separate node.`);
}
}
parentTranslation(nodes, npc.node, 'game.npcs[].node');
taken.push(npc.node);
if (npc.animation === undefined) fail(`${label}.animation`, 'is required: an NPC walks through an animation graph with rootMotion and a number parameter "speed". See scene_capabilities topic game.');
const animation = normalizeGameAnimation(npc.animation, nodes, npc.node, { path: `${label}.animation`, driven: false });
if (!animation.rootMotion) fail(`${label}.animation.rootMotion`, 'is required for an NPC: the follower moves by the root motion of the clips. Add { "bone": "<child node id the walk clip translates>" }.');
if (animation.parameters?.speed?.type !== 'number') fail(`${label}.animation.parameters.speed`, 'must be declared as { "type": "number" }: the follower sets it to blend idle, walk and run.');
return {
node: npc.node,
path: normalizePath(npc.path, label),
cruiseSpeed: boundedNumber(npc.cruiseSpeed, 2.2, 0.01, GAME_SETUP_LIMITS.maxSpeed, `${label}.cruiseSpeed`),
footOffset: boundedNumber(npc.footOffset, 0, -GAME_SETUP_LIMITS.maxFootOffset, GAME_SETUP_LIMITS.maxFootOffset, `${label}.footOffset`),
yaw: boundedNumber(npc.yaw, 0, -2 * Math.PI, 2 * Math.PI, `${label}.yaw`),
animation,
};
}
function normalizeNpcs(npcs, context) {
if (!Array.isArray(npcs) || npcs.length > GAME_SETUP_LIMITS.maxNpcs) fail('npcs', `must be a list of at most ${GAME_SETUP_LIMITS.maxNpcs} NPCs, each { node, path, animation }.`);
return npcs.map((npc, index) => normalizeNpc(npc, index, context));
}
function normalizeRules(rules, playerNode) {
let checked;
try {
checked = validateGameRules(rules, { hasInput: true });
} catch (error) {
throw new RangeError(`Game setup rules: ${error.message}`);
}
checked.rules.forEach((rule, index) => {
if (rule.when.type === 'input' && !GAME_INPUT_ACTIONS.includes(rule.when.action)) {
fail(`rules.rules[${index}].when.action`, `is ${JSON.stringify(rule.when.action)}, which the game does not bind. Use one of: ${GAME_INPUT_ACTIONS.join(', ')}.`);
}
});
if (!checked.parts.some(part => part.id === playerNode)) {
fail('rules.parts', `has no part "${playerNode}", the player node. Add { "id": "${playerNode}", "tags": ["player"] } so zones can see the player.`);
}
// Keep the document as written: validateGameRules fills fields (such as a null position) that it does not accept back.
return structuredClone(rules);
}
/**
* Check a recipe `game` section against the recipe nodes (a list of nodes, or a Set of node ids when there is no animation) and return
* a normalised copy with every default filled in. The rules document is checked by validateGameRules. Errors name the field and say what to pass.
*/
export function normalizeGameSetup(game, nodeSource) {
const added = addedKinds();
const nodes = Array.isArray(nodeSource) ? nodeSource : [];
const nodeIds = Array.isArray(nodeSource) ? new Set(nodeSource.map(node => node.id)) : nodeSource;
requireRecord(game, 'game');
rejectUnknownFields(game, SETUP_FIELDS, 'game');
const player = normalizePlayer(game.player, nodeIds, nodes, withAdded(GAME_CONTROLLERS, added.controllers));
if (game.physics !== undefined && typeof game.physics !== 'boolean') fail('physics', `must be true or false, got ${JSON.stringify(game.physics)}.`);
const normalized = {
player,
camera: chooseName(game.camera, withAdded(GAME_CAMERAS, added.cameraRigs), 'follow', 'camera'),
input: chooseName(game.input, GAME_INPUT_PRESETS, 'keyboard', 'input'),
physics: game.physics ?? false,
ground: boundedNumber(game.ground, 0, -GAME_SETUP_LIMITS.maxGround, GAME_SETUP_LIMITS.maxGround, 'ground'),
};
if (game.npcs !== undefined) normalized.npcs = normalizeNpcs(game.npcs, { nodeIds, nodes, taken: [player.node] });
if (game.rules !== undefined) normalized.rules = normalizeRules(game.rules, player.node);
return normalized;
}