Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.js
index 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.mjs
new file mode 100644
index 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.js
index 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.js
index 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: pr
const { 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.js
index 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);