3D engine that AI agents drive
WIP addon allowlist
Nguyen Xuan An278371df4228
diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.jsindex c2705229..9450de09 100644--- a/scripts/agent-preview-browser.js+++ b/scripts/agent-preview-browser.js@@ -10,6 +10,7 @@ import { installMeshBlend, normalizeBlend } from '../src/mesh-blend.js';import { installCoplanarDiagnostics } from '../src/coplanar-overlap.js';import { applyProjection } from '../src/camera.js';import { mat4 } from 'gl-matrix';+import { listControllerKinds, listCameraRigKinds, unregisterControllerKind, unregisterCameraRigKind } from '../src/player.js';import { resolveAgentShadow, agentEnvironmentMap } from '../src/agent-look.js';import { agentSceneModule, agentSceneModuleLoaded } from '../src/agent-scene-modules.js';import { agentGroundPlacement, createAgentGround, placeAgentGround, FLOOR_COLOR } from '../src/agent-ground.js';@@ -829,7 +830,42 @@ function paintLabels(context, labels, offsetX, offsetY) {}}+// Kinds an addon registers are checked against what its package.json declared; one it did not declare is taken back.+const ADDON_KIND_REGISTRIES = [+ { point: 'registerController', field: 'controllers', list: listControllerKinds, remove: unregisterControllerKind },+ { point: 'registerCameraRig', field: 'cameraRigs', list: listCameraRigKinds, remove: unregisterCameraRigKind },+];++function takeBackKinds(before, registries) {+ for (const registry of registries) {+ for (const kind of registry.list()) if (!before[registry.field].includes(kind)) registry.remove(kind);+ }+}++async function loadAddonModule({ url, name, extensionPoints }) {+ const before = Object.fromEntries(ADDON_KIND_REGISTRIES.map(registry => [registry.field, registry.list()]));+ try {+ const entry = await import(/* @vite-ignore */ url);+ if (typeof entry.registerAddon !== 'function') {+ throw new TypeError(`${name} does not export a registerAddon function. Export registerAddon() that registers its kinds (docs/addons.md).`);+ }+ entry.registerAddon();+ } catch (error) {+ takeBackKinds(before, ADDON_KIND_REGISTRIES);+ throw error;+ }+ const added = Object.fromEntries(ADDON_KIND_REGISTRIES.map(registry => [registry.field, registry.list().filter(kind => !before[registry.field].includes(kind))]));+ const undeclared = ADDON_KIND_REGISTRIES.filter(registry => added[registry.field].length > 0 && !extensionPoints.includes(registry.point));+ if (undeclared.length > 0) {+ takeBackKinds(before, ADDON_KIND_REGISTRIES);+ const used = undeclared.map(registry => `${registry.point} (${added[registry.field].join(', ')})`).join(', ');+ throw new RangeError(`${name} registered ${used} but its package.json "67js".extensionPoints does not declare it. Add the point to extensionPoints, or stop registering it.`);+ }+ return added;+}+window.__agentPreview = {+ loadAddon: loadAddonModule,reviewBegin({ width, height }) {reviewGrid = document.createElement('canvas');reviewGrid.width = width;diff --git a/scripts/mcp-addons.mjs b/scripts/mcp-addons.mjsnew file mode 100644index 00000000..ffa78105--- /dev/null+++ b/scripts/mcp-addons.mjs@@ -0,0 +1,118 @@+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';+import { isAbsolute, join, relative, resolve, sep } from 'node:path';+import { checkAddon, CORE_PACKAGE } from '../bin/67js-addon-check.mjs';++// Addons the person who starts the MCP server allows. Only startup options choose them (--addons, --allow-addon); no tool+// call can name one. Each is looked up in <folder>/node_modules/<name> and must pass the addon contract (docs/addons.md).++export const MAXIMUM_ADDON_BUNDLE_BYTES = 2 * 1024 * 1024;+export const MAXIMUM_ALLOWED_ADDONS = 16;+const PACKAGE_NAME = /^(?:@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/;++function isInside(folder, path) {+ const inside = relative(folder, path);+ return inside !== '' && !inside.startsWith('..') && !isAbsolute(inside);+}++function entryOf(pack) {+ return typeof pack.main === 'string' ? pack.main : pack.exports;+}++function loadOne(name, addonsFolder, version) {+ if (!PACKAGE_NAME.test(name)) {+ return { reason: `"${name}" is not an npm package name. Pass the name as installed, such as my-addon or @scope/my-addon.` };+ }+ const packageFolder = join(addonsFolder, 'node_modules', ...name.split('/'));+ if (!existsSync(packageFolder)) {+ return { reason: `${name} is listed with --allow-addon but is not installed in ${join(addonsFolder, 'node_modules')}. Run npm install ${name} in ${addonsFolder}.` };+ }+ const realFolder = realpathSync(packageFolder);+ if (!isInside(addonsFolder, realFolder)) {+ return { reason: `${name} resolves to ${realFolder}, outside the addons folder ${addonsFolder}. Install the package inside that folder instead of linking it from elsewhere.` };+ }+ const { errors } = checkAddon(realFolder, { version });+ if (errors.length > 0) return { reason: `${name} fails the addon contract: ${errors.join(' ')}` };+ const pack = JSON.parse(readFileSync(join(realFolder, 'package.json'), 'utf8'));+ if (pack.name !== name) return { reason: `${name} has package name "${pack.name}" in its package.json. Install the package under its own name.` };+ if (pack['67js'].bundleBytes > MAXIMUM_ADDON_BUNDLE_BYTES) {+ return { reason: `${name} declares bundleBytes ${pack['67js'].bundleBytes}, above the server bound of ${MAXIMUM_ADDON_BUNDLE_BYTES} bytes (2 MiB). Ship a smaller entry file.` };+ }+ const entryPath = resolve(realFolder, entryOf(pack));+ const realEntry = realpathSync(entryPath);+ if (!isInside(realFolder, realEntry)) return { reason: `${name} entry file resolves outside the package folder. Point main or exports inside the package.` };+ if (!/\.m?js$/.test(realEntry)) return { reason: `${name} entry file ${entryOf(pack)} must be an ES module ending in .js or .mjs.` };+ if (statSync(realEntry).size > MAXIMUM_ADDON_BUNDLE_BYTES) return { reason: `${name} entry file is above 2 MiB.` };+ return {+ addon: {+ name,+ version: pack.version ?? 'unknown',+ folder: realFolder,+ entry: relative(realFolder, realEntry).split(sep).join('/'),+ extensionPoints: [...pack['67js'].extensionPoints],+ },+ };+}++/**+ * Resolve the allowlisted addons. Returns { addons, skipped } where each skipped item is { name, reason }. A missing or failing+ * addon is skipped and never stops the server. The folder must be an absolute path to an existing directory.+ */+export function resolveAddons({ folder, names = [], version }) {+ if (folder === undefined) {+ if (names.length > 0) throw new Error(`--allow-addon needs --addons <absolute folder> that holds node_modules. Add it, or remove ${names.map(name => `--allow-addon ${name}`).join(' ')}.`);+ return { addons: [], skipped: [] };+ }+ if (typeof folder !== 'string' || !isAbsolute(folder) || !existsSync(folder) || !statSync(folder).isDirectory()) {+ throw new Error('--addons must be an absolute path to an existing folder that holds node_modules.');+ }+ if (names.length > MAXIMUM_ALLOWED_ADDONS) throw new Error(`--allow-addon may be given at most ${MAXIMUM_ALLOWED_ADDONS} times.`);+ const addonsFolder = realpathSync(folder);+ const addons = [];+ const skipped = [];+ for (const name of [...new Set(names)]) {+ const { addon, reason } = loadOne(name, addonsFolder, version);+ if (addon) addons.push(addon);+ else skipped.push({ name, reason });+ }+ return { addons, skipped };+}++/** The file inside an allowlisted addon that a page request names, or null. Checks the real path on every call, so a link swapped in later fails. */+export function addonFileFor(addons, requestPath) {+ const match = /^\/addons\/(\d+)\/(.+)$/.exec(requestPath);+ const addon = match ? addons[Number(match[1])] : undefined;+ if (!addon) return null;+ let decoded;+ try {+ decoded = decodeURIComponent(match[2]);+ } catch {+ return null;+ }+ if (!/\.m?js$/.test(decoded) || decoded.includes('\0') || decoded.includes('\\')) return null;+ try {+ const real = realpathSync(resolve(addon.folder, decoded));+ return isInside(addon.folder, real) ? real : null;+ } catch {+ return null;+ }+}++/** The import map that points the host package specifiers at the page's own engine modules, so an addon shares them. */+export function addonImportMap(exportsField) {+ const imports = {};+ for (const [subpath, target] of Object.entries(exportsField)) {+ if (subpath !== '.' && !subpath.startsWith('./addons/')) continue;+ if (typeof target !== 'string' || !target.startsWith('./build/')) continue;+ imports[subpath === '.' ? CORE_PACKAGE : `${CORE_PACKAGE}/${subpath.slice(2)}`] = `/${target.slice('./build/'.length)}`;+ }+ return { imports };+}++export function addonCapabilities({ addons = [], skipped = [], registered = {}, refused = [] }) {+ return {+ configured: addons.length + skipped.length > 0,+ loaded: addons.map(addon => ({ name: addon.name, version: addon.version, extensionPoints: addon.extensionPoints, registered: registered[addon.name] ?? { controllers: [], cameraRigs: [] } })),+ skipped: [...skipped, ...refused],+ use: 'Set game.player.controller or game.camera to a registered kind name. Addons are chosen by whoever starts the server; no tool loads one.',+ };+}diff --git a/src/game-setup.js b/src/game-setup.jsindex c88ec58b..757f1a75 100644--- a/src/game-setup.js+++ b/src/game-setup.js@@ -1,5 +1,6 @@import { validateGameRules } from './game-rules.js';import { normalizeGameAnimation } from './game-animation.js';+import { listControllerKinds, listCameraRigKinds } from './player.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.@@ -18,6 +19,10 @@ export const GAME_SETUP_LIMITS = Object.freeze({maxPathPoints: 256,});+// The fixed names, then any kind an allowlisted addon registered at runtime (see docs/addons.md).+export const gameControllerNames = () => [...new Set([...GAME_CONTROLLERS, ...listControllerKinds()])];+export const gameCameraNames = () => [...new Set([...GAME_CAMERAS, ...listCameraRigKinds()])];+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'];@@ -59,7 +64,7 @@ function normalizePlayer(player, nodeIds, nodes) {}const normalized = {node: player.node,- controller: chooseName(player.controller, GAME_CONTROLLERS, 'character', 'player.controller'),+ controller: chooseName(player.controller, gameControllerNames(), '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'),@@ -144,7 +149,7 @@ export function normalizeGameSetup(game, nodeSource) {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, GAME_CAMERAS, 'follow', 'camera'),+ camera: chooseName(game.camera, gameCameraNames(), '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'),diff --git a/src/game.js b/src/game.jsindex 452fceec..80f7a5be 100644--- a/src/game.js+++ b/src/game.js@@ -6,7 +6,7 @@ import { groundBounceEnvironment } from './ground-bounce.js';import { createRuntime } from './runtime.js';import { createInput, gamepadSource, keyboardSource } from './input.js';import { replaySource, touchSource } from './input-sources.js';-import { createCharacterController, createChaseCamera, createFirstPersonCamera, createFollowCamera, createTopDownCamera, createVehicleController } from './player.js';+import { createCharacterController, createChaseCamera, createController, createCameraRigOfKind, createFirstPersonCamera, createFollowCamera, createTopDownCamera, createVehicleController } from './player.js';import { createGameRules } from './game-rules.js';// Plays the `game` section of a scene recipe in a page: the scene, the input preset, the character controller, the camera rig@@ -51,6 +51,7 @@ function cameraRigFor(kind, controller, input) {if (kind === 'first-person') return createFirstPersonCamera(rigOptions);if (kind === 'top-down') return createTopDownCamera(rigOptions);if (kind === 'chase') return createChaseCamera(rigOptions);+ if (kind !== 'follow') return createCameraRigOfKind(kind, rigOptions);return createFollowCamera(rigOptions);}@@ -169,7 +170,11 @@ async function buildGame(canvas, recipe, { replay, showStatus = true, assets: prconst { createGameAnimation, createPathFollower } = hasAnimation ? await loadAnimationRuntime() : {};const playerAnimation = game.player.animation ? createGameAnimation(game.player.animation, recipe.nodes, game.player.node, { assets }) : null;const startPosition = [start[0], start[1] - footOffset, start[2]];- const controller = game.player.controller === 'vehicle'+ // Any other name is a kind a host registered with registerController, such as one from an allowlisted addon.+ const customKind = !['character', 'vehicle'].includes(game.player.controller);+ const controller = customKind+ ? createController(game.player.controller, { input, position: startPosition, ground: game.ground, node: body })+ : game.player.controller === 'vehicle'? createVehicleController({ input, position: startPosition, ground: game.ground, maximumSpeed: game.player.maximumSpeed, node: body }): createCharacterController({input,diff --git a/src/player.js b/src/player.jsindex 3c98a85d..a49a415b 100644--- a/src/player.js+++ b/src/player.js@@ -798,6 +798,9 @@ const rigFactories = new Map([['sideScroller', createSideScrollerCamera],]);+const BUILT_IN_CONTROLLERS = new Set(controllerFactories.keys());+const BUILT_IN_RIGS = new Set(rigFactories.keys());+function register(owner, registry, kind, factory) {if (typeof kind !== 'string' || kind.length === 0 || kind.length > 64) {throw new TypeError(`${owner} kind must be a non-empty string of at most 64 characters, such as "boat", got ${describe(kind)}.`);@@ -834,6 +837,21 @@ export function listCameraRigKinds() {return [...rigFactories.keys()];}+function unregister(owner, registry, builtIn, kind) {+ if (builtIn.has(kind)) throw new RangeError(`${owner} cannot remove the built-in kind "${kind}".`);+ return registry.delete(kind);+}++// Take back a kind a host refused (the MCP server does this for an addon that registered a point it did not declare).+// Built-in kinds stay. Returns whether a kind was removed.+export function unregisterControllerKind(kind) {+ return unregister('unregisterControllerKind', controllerFactories, BUILT_IN_CONTROLLERS, kind);+}++export function unregisterCameraRigKind(kind) {+ return unregister('unregisterCameraRigKind', rigFactories, BUILT_IN_RIGS, kind);+}+export function createController(kind, options = {}) {const controller = build('createController', controllerFactories, kind, options);const hasState = controller?.state && Array.isArray(controller.state.position);