Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add the third-party addon contract and starter (#985)

Nguyen Xuan Ane0628ee2e55d
diff --git a/changes/985.md b/changes/985.md
new file mode 100644
index 00000000..ab93751d
--- /dev/null
+++ b/changes/985.md
@@ -0,0 +1 @@
+- Third-party addons have a contract, a checker (`scripts/addon-check.mjs`), a guide (`docs/addons.md`) and a starter template (#985)
diff --git a/docs/addons.md b/docs/addons.md
new file mode 100644
index 00000000..fc986e97
--- /dev/null
+++ b/docs/addons.md
@@ -0,0 +1,60 @@
+# Addons from other people
+
+A code addon is an npm package that extends 67js through the extension points it already has. 67js's own addons (`67js/addons/*`) are first-party; this page is the contract for third-party ones.
+
+## Security
+
+A code addon runs with the full rights of your page or Node process: it can read files, use the network and change anything in the scene. The MCP server never loads one from a tool call. Install only addons you trust, and read what an addon does before you add it.
+
+## The contract
+
+An addon package:
+
+- lists `@codepawlhq/67js` under `peerDependencies`, so it shares the host's copy instead of bundling its own;
+- has `67js-addon` in `keywords`, so a search by that keyword finds it;
+- has a SPDX `license`;
+- has a `67js` field in `package.json` that states what the addon needs:
+
+```json
+"67js": {
+ "range": ">=0.19.0 <1.0.0",
+ "extensionPoints": ["registerController"],
+ "bundleBytes": 2048
+}
+```
+
+`range` is the 67js versions it was tested with (comparators such as `>=0.19.0 <1.0.0`, or `^0.19.0`). `extensionPoints` lists every point it uses. `bundleBytes` is the size of the entry file named by `main` or `exports`.
+
+The manifest lives in `package.json` rather than a separate `67js-addon.json` because the npm registry returns the whole `package.json` of each version, so a listing can read the range and points without unpacking the tarball, and there is no second file to forget to publish.
+
+## Extension points
+
+These are the ways code can extend 67js today, and the only names the `extensionPoints` list accepts:
+
+| Name | What the addon calls | Import |
+| --- | --- | --- |
+| `registerController` | `registerController(kind, factory)`: a controller kind (a boat, a ball) | `67js/addons/player` |
+| `registerCameraRig` | `registerCameraRig(kind, factory)`: a camera rig kind | `67js/addons/player` |
+| `userPass` | a GLSL `userPass(vec2 uv)` fragment set on `renderer.userPasses` ([user passes](user-passes.md)) | `67js/addons/user-pass` |
+| `streamingLoader` | `registerLoader(format, loader)` on a streaming instance ([streaming](streaming.md)) | `67js/addons/streaming` |
+| `runtimeSystem` | `runtime.addSystem(system)` ([runtime](runtime.md)) | `67js/addons/runtime` |
+
+Kinds and formats cannot be replaced once registered, so pick a name that is unlikely to clash, such as a prefix with your package name.
+
+## Write one
+
+Copy [templates/addon-starter](https://github.com/codepawl/67.js/tree/main/templates/addon-starter). It registers a `hover` controller kind, has a test written with `node:test`, and passes the check below. Export a function that registers, rather than registering on import, so the host decides when.
+
+## Test one
+
+Run your own tests with `@codepawlhq/67js` installed as a dev dependency next to the peer entry. Then check the contract:
+
+```sh
+node node_modules/@codepawlhq/67js/scripts/addon-check.mjs . --version 0.19.0
+```
+
+The check says what failed and what to pass instead. It tests the keyword, the peer dependency, the license, the `67js` field, the entry size, and that the range allows the version you pass.
+
+## Publish one
+
+`npm publish` the package. Keep `67js-addon` in the keywords and bump the `range` after you test against a new 67js release.
diff --git a/docs/guide.md b/docs/guide.md
index 3492e57e..c73d03db 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -84,6 +84,8 @@ Core exports are available from `67js`:
`67js/addons/canvas2d`: 2D recipes. `67js/addons/gltf`: optional asset decoding. These are separate imports to keep the core smaller.
+Other people's addons follow the [addon contract](addons.md): a peer dependency on 67js, the `67js-addon` keyword and a `67js` manifest.
+
67js targets WebGL2. Version `0.4.0` includes the APIs below. Check the installed package version and release metadata before using them.
## Release and source availability
diff --git a/package.json b/package.json
index c9d4bcd7..26b8825b 100644
--- a/package.json
+++ b/package.json
@@ -55,6 +55,8 @@
"docs/game.md",
"docs/scene-query.md",
"docs/user-passes.md",
+ "docs/addons.md",
+ "scripts/addon-check.mjs",
"docs/skeleton-pose.md",
"docs/verification.md"
],
diff --git a/scripts/addon-check.mjs b/scripts/addon-check.mjs
new file mode 100644
index 00000000..dbd15151
--- /dev/null
+++ b/scripts/addon-check.mjs
@@ -0,0 +1,169 @@
+// Checks a folder against the 67js third-party addon contract (docs/addons.md).
+// Usage: node scripts/addon-check.mjs <addon-folder> [--version <67js version>]
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const ADDON_KEYWORD = '67js-addon';
+export const CORE_PACKAGE = '@codepawlhq/67js';
+export const EXTENSION_POINTS = Object.freeze({
+ registerController: 'registerController(kind, factory) from 67js/addons/player',
+ registerCameraRig: 'registerCameraRig(kind, factory) from 67js/addons/player',
+ userPass: 'a user GLSL pass given to renderer.userPasses.set (67js/addons/user-pass)',
+ streamingLoader: 'registerLoader(format, loader) on a streaming instance (67js/addons/streaming)',
+ runtimeSystem: 'runtime.addSystem(system) on a runtime (67js/addons/runtime)',
+});
+
+const VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/;
+const COMPARATOR_PATTERN = /^(>=|<=|>|<|=|\^)?(\d+\.\d+\.\d+)$/;
+const POINT_NAMES = Object.keys(EXTENSION_POINTS).join(', ');
+
+function parseVersion(text) {
+ const match = VERSION_PATTERN.exec(text);
+ return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+
+function compareVersions(left, right) {
+ for (let index = 0; index < 3; index += 1) {
+ if (left[index] !== right[index]) return left[index] < right[index] ? -1 : 1;
+ }
+ return 0;
+}
+
+function caretUpperBound([major, minor, patch]) {
+ if (major > 0) return [major + 1, 0, 0];
+ if (minor > 0) return [0, minor + 1, 0];
+ return [0, 0, patch + 1];
+}
+
+// Parses a range such as ">=0.19.0 <1.0.0" or "^0.19.0" into [operator, version] pairs, or null when it is not one.
+export function parseRange(range) {
+ if (typeof range !== 'string' || range.trim() === '') return null;
+ const comparators = [];
+ for (const part of range.trim().split(/\s+/)) {
+ const match = COMPARATOR_PATTERN.exec(part);
+ if (!match) return null;
+ const version = parseVersion(match[2]);
+ if (match[1] === '^') {
+ comparators.push(['>=', version], ['<', caretUpperBound(version)]);
+ } else {
+ comparators.push([match[1] ?? '=', version]);
+ }
+ }
+ return comparators;
+}
+
+export function rangeAllows(range, version) {
+ const comparators = parseRange(range);
+ const parsed = parseVersion(version);
+ if (!comparators || !parsed) return false;
+ return comparators.every(([operator, bound]) => {
+ const order = compareVersions(parsed, bound);
+ return { '>=': order >= 0, '<=': order <= 0, '>': order > 0, '<': order < 0, '=': order === 0 }[operator];
+ });
+}
+
+function readPackage(folder, errors) {
+ const path = join(folder, 'package.json');
+ if (!existsSync(path)) {
+ errors.push(`No package.json in ${folder}. Run the check on the addon package folder.`);
+ return null;
+ }
+ try {
+ return JSON.parse(readFileSync(path, 'utf8'));
+ } catch (error) {
+ errors.push(`package.json is not valid JSON (${error.message}). Fix the syntax.`);
+ return null;
+ }
+}
+
+function checkManifest(manifest, errors) {
+ if (manifest === undefined || manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) {
+ errors.push('package.json has no "67js" field. Add "67js": { "range": ">=0.19.0 <1.0.0", "extensionPoints": ["registerController"], "bundleBytes": 2048 }.');
+ return;
+ }
+ if (!parseRange(manifest.range)) {
+ errors.push(`"67js".range must be a version range such as ">=0.19.0 <1.0.0" or "^0.19.0", got ${JSON.stringify(manifest.range)}.`);
+ }
+ const points = manifest.extensionPoints;
+ if (!Array.isArray(points) || points.length === 0) {
+ errors.push(`"67js".extensionPoints must list at least one of: ${POINT_NAMES}.`);
+ } else {
+ for (const point of points) {
+ if (!Object.hasOwn(EXTENSION_POINTS, point)) {
+ errors.push(`"67js".extensionPoints names unknown point ${JSON.stringify(point)}. Use one of: ${POINT_NAMES}.`);
+ }
+ }
+ }
+ if (!Number.isInteger(manifest.bundleBytes) || manifest.bundleBytes <= 0) {
+ errors.push(`"67js".bundleBytes must be a positive whole number of bytes for the entry file, got ${JSON.stringify(manifest.bundleBytes)}.`);
+ }
+}
+
+function checkEntrySize(folder, pack, errors) {
+ const manifest = pack['67js'];
+ const entry = typeof pack.main === 'string' ? pack.main : typeof pack.exports === 'string' ? pack.exports : null;
+ if (entry === null || !Number.isInteger(manifest?.bundleBytes)) return;
+ const path = resolve(folder, entry);
+ if (!existsSync(path)) {
+ errors.push(`The entry file ${entry} does not exist. Point "main" or "exports" at a file that is published.`);
+ return;
+ }
+ const actual = statSync(path).size;
+ if (actual > manifest.bundleBytes) {
+ errors.push(`${entry} is ${actual} bytes but "67js".bundleBytes says ${manifest.bundleBytes}. Raise bundleBytes to at least ${actual}.`);
+ }
+}
+
+function checkPeer(pack, errors, warnings) {
+ const peerRange = pack.peerDependencies?.[CORE_PACKAGE];
+ if (peerRange === undefined) {
+ errors.push(`package.json "peerDependencies" must list ${CORE_PACKAGE} so the addon shares the host's copy. Add "${CORE_PACKAGE}": ">=0.19.0 <1.0.0".`);
+ } else if (!parseRange(peerRange)) {
+ errors.push(`peerDependencies.${CORE_PACKAGE} must be a version range such as ">=0.19.0 <1.0.0", got ${JSON.stringify(peerRange)}.`);
+ }
+ if (pack.dependencies?.[CORE_PACKAGE] !== undefined) {
+ warnings.push(`${CORE_PACKAGE} is in dependencies. Move it to peerDependencies so hosts do not get two copies.`);
+ }
+}
+
+// Returns { errors, warnings } for the addon package in `folder`. `version` is a 67js version the declared range must allow.
+export function checkAddon(folder, { version } = {}) {
+ const errors = [];
+ const warnings = [];
+ const pack = readPackage(folder, errors);
+ if (pack === null) return { errors, warnings };
+ if (typeof pack.name !== 'string' || pack.name === '') errors.push('package.json needs a "name".');
+ if (!Array.isArray(pack.keywords) || !pack.keywords.includes(ADDON_KEYWORD)) {
+ errors.push(`package.json "keywords" must include "${ADDON_KEYWORD}" so the listing finds the addon. Add it.`);
+ }
+ checkPeer(pack, errors, warnings);
+ if (typeof pack.license !== 'string' || pack.license === '') {
+ errors.push('package.json "license" must be an SPDX identifier such as "MIT".');
+ }
+ checkManifest(pack['67js'], errors);
+ checkEntrySize(folder, pack, errors);
+ const declaredRange = pack['67js']?.range;
+ if (version && parseRange(declaredRange) && !rangeAllows(declaredRange, version)) {
+ errors.push(`"67js".range ${declaredRange} does not allow 67js ${version}. Widen the range or test the addon against ${version}.`);
+ }
+ return { errors, warnings };
+}
+
+function main(argumentsList) {
+ const versionIndex = argumentsList.indexOf('--version');
+ const version = versionIndex >= 0 ? argumentsList[versionIndex + 1] : undefined;
+ const valueIndex = versionIndex >= 0 ? versionIndex + 1 : -1;
+ const folder = argumentsList.find((value, index) => !value.startsWith('--') && index !== valueIndex);
+ if (!folder) {
+ console.error('Pass the addon package folder: node scripts/addon-check.mjs <addon-folder> [--version <67js version>]');
+ return 2;
+ }
+ const { errors, warnings } = checkAddon(resolve(folder), { version });
+ for (const warning of warnings) console.warn(`warning: ${warning}`);
+ for (const error of errors) console.error(`error: ${error}`);
+ console.log(errors.length === 0 ? 'addon contract: ok' : `addon contract: ${errors.length} problem(s)`);
+ return errors.length === 0 ? 0 : 1;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = main(process.argv.slice(2));
diff --git a/templates/addon-starter/README.md b/templates/addon-starter/README.md
new file mode 100644
index 00000000..f028e2da
--- /dev/null
+++ b/templates/addon-starter/README.md
@@ -0,0 +1,12 @@
+# 67js addon starter
+
+A minimal 67js addon. It registers a `hover` controller kind through `registerController`.
+
+1. Copy this folder, then rename the package in `package.json`.
+2. `npm install`, then `npm test`.
+3. Check the contract: `node node_modules/@codepawlhq/67js/scripts/addon-check.mjs .`
+4. `npm publish`. The `67js-addon` keyword is how the addon is found.
+
+Keep `@codepawlhq/67js` a peer dependency, list every extension point you use in the `67js` field, and keep `bundleBytes` at least the size of the entry file. The full guide is [docs/addons.md](https://github.com/codepawl/67.js/blob/main/docs/addons.md).
+
+Install only addons you trust: a code addon runs with the full rights of your page or Node process.
diff --git a/templates/addon-starter/package.json b/templates/addon-starter/package.json
new file mode 100644
index 00000000..6a202f97
--- /dev/null
+++ b/templates/addon-starter/package.json
@@ -0,0 +1,25 @@
+{
+ "name": "67js-addon-starter",
+ "version": "0.1.0",
+ "description": "A starter for a 67js addon: registers a hover controller kind.",
+ "type": "module",
+ "main": "./src/index.js",
+ "exports": "./src/index.js",
+ "files": ["src"],
+ "license": "MIT",
+ "keywords": ["67js-addon", "67js", "three-d"],
+ "scripts": {
+ "test": "node --test tests/starter.spec.js"
+ },
+ "67js": {
+ "range": ">=0.19.0 <1.0.0",
+ "extensionPoints": ["registerController"],
+ "bundleBytes": 2048
+ },
+ "peerDependencies": {
+ "@codepawlhq/67js": ">=0.19.0 <1.0.0"
+ },
+ "devDependencies": {
+ "@codepawlhq/67js": "^0.19.0"
+ }
+}
diff --git a/templates/addon-starter/src/index.js b/templates/addon-starter/src/index.js
new file mode 100644
index 00000000..4f035168
--- /dev/null
+++ b/templates/addon-starter/src/index.js
@@ -0,0 +1,29 @@
+import { registerController } from '@codepawlhq/67js/addons/player';
+
+const DEFAULT_HOVER_HEIGHT = 1.5;
+const DEFAULT_SPEED = 4;
+
+// A controller kind that holds a body at a fixed height and moves it with two input axes.
+function createHoverController(options = {}) {
+ const hoverHeight = options.hoverHeight ?? DEFAULT_HOVER_HEIGHT;
+ const speed = options.speed ?? DEFAULT_SPEED;
+ const state = { position: [0, hoverHeight, 0] };
+ return {
+ name: options.name ?? 'player',
+ kind: 'hover',
+ state,
+ fixedUpdate(stepSeconds) {
+ const sideways = options.input?.getAxis('moveX') ?? 0;
+ const forward = options.input?.getAxis('moveForward') ?? 0;
+ state.position[0] += sideways * speed * stepSeconds;
+ state.position[2] -= forward * speed * stepSeconds;
+ state.position[1] = hoverHeight;
+ },
+ };
+}
+
+// Call once per page or process: a kind name can be registered only one time.
+export function registerHoverController(kind = 'hover') {
+ registerController(kind, createHoverController);
+ return kind;
+}
diff --git a/templates/addon-starter/tests/starter.spec.js b/templates/addon-starter/tests/starter.spec.js
new file mode 100644
index 00000000..b716096f
--- /dev/null
+++ b/templates/addon-starter/tests/starter.spec.js
@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createController, listControllerKinds } from '@codepawlhq/67js/addons/player';
+import { registerHoverController } from '../src/index.js';
+
+test('the hover kind is registered and holds its height while moving', () => {
+ registerHoverController('hover');
+ assert.ok(listControllerKinds().includes('hover'));
+ const input = { getAxis: name => (name === 'moveX' ? 1 : 0) };
+ const controller = createController('hover', { input, hoverHeight: 2, speed: 3 });
+ controller.fixedUpdate(0.5);
+ assert.deepEqual(controller.state.position, [1.5, 2, 0]);
+});
+
+test('registering the same kind twice names the clash', () => {
+ assert.throws(() => registerHoverController('hover'), /already registered/);
+});
diff --git a/tests/addon-starter.test.js b/tests/addon-starter.test.js
new file mode 100644
index 00000000..9a721c7b
--- /dev/null
+++ b/tests/addon-starter.test.js
@@ -0,0 +1,105 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { register } from 'node:module';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { checkAddon, parseRange, rangeAllows } from '../scripts/addon-check.mjs';
+import { VERSION } from '../src/version.js';
+
+const root = fileURLToPath(new URL('..', import.meta.url));
+const starterFolder = join(root, 'templates', 'addon-starter');
+const PEER_PREFIX = '@codepawlhq/67js/addons/';
+
+// Resolves the peer package's addon subpaths to this checkout's source, as the built package would.
+const resolveHooks = `
+export async function resolve(specifier, context, next) {
+ if (specifier.startsWith(${JSON.stringify(PEER_PREFIX)})) {
+ const name = specifier.slice(${PEER_PREFIX.length});
+ return { url: new URL('src/' + name + '.js', ${JSON.stringify(pathToFileURL(root + '/').href)}).href, shortCircuit: true };
+ }
+ return next(specifier, context);
+}
+`;
+const hooksUrl = `data:text/javascript,${encodeURIComponent(resolveHooks)}`;
+register(hooksUrl);
+
+function copyStarter(change) {
+ const folder = mkdtempSync(join(tmpdir(), 'addon-starter-'));
+ cpSync(starterFolder, folder, { recursive: true });
+ const path = join(folder, 'package.json');
+ const pack = JSON.parse(readFileSync(path, 'utf8'));
+ change(pack);
+ writeFileSync(path, JSON.stringify(pack));
+ return folder;
+}
+
+function errorsFor(change, options) {
+ const folder = copyStarter(change);
+ try {
+ return checkAddon(folder, options).errors;
+ } finally {
+ rmSync(folder, { recursive: true, force: true });
+ }
+}
+
+test('the starter template passes the contract for the current 67js version', () => {
+ const { errors, warnings } = checkAddon(starterFolder, { version: VERSION });
+ assert.deepEqual(errors, []);
+ assert.deepEqual(warnings, []);
+});
+
+test('the starter registers its controller kind against the local 67js source', async () => {
+ const { registerHoverController } = await import(pathToFileURL(join(starterFolder, 'src', 'index.js')).href);
+ const { createController } = await import('../src/player.js');
+ assert.equal(registerHoverController('starter-hover'), 'starter-hover');
+ const controller = createController('starter-hover', { hoverHeight: 3 });
+ assert.deepEqual(controller.state.position, [0, 3, 0]);
+});
+
+test('the starter own tests pass against the local 67js source', () => {
+ const result = spawnSync(process.execPath, ['--import', hooksUrl, '--test', join(starterFolder, 'tests', 'starter.spec.js')], { encoding: 'utf8' });
+ assert.equal(result.status, 0, result.stdout + result.stderr);
+});
+
+test('a missing keyword is refused with the fix', () => {
+ const errors = errorsFor(pack => { pack.keywords = ['three-d']; });
+ assert.match(errors.join('\n'), /must include "67js-addon".*Add it/);
+});
+
+test('a missing peer dependency is refused with the fix', () => {
+ const errors = errorsFor(pack => { delete pack.peerDependencies; });
+ assert.match(errors.join('\n'), /peerDependencies" must list @codepawlhq\/67js/);
+});
+
+test('a bad range, unknown point and missing manifest are refused', () => {
+ assert.match(errorsFor(pack => { pack['67js'].range = 'latest'; }).join('\n'), /"67js".range must be a version range/);
+ assert.match(errorsFor(pack => { pack['67js'].extensionPoints = ['hackTheGibson']; }).join('\n'), /unknown point "hackTheGibson"/);
+ assert.match(errorsFor(pack => { delete pack['67js']; }).join('\n'), /no "67js" field/);
+});
+
+test('a range that excludes the running version and an oversized entry are refused', () => {
+ assert.match(errorsFor(pack => { pack['67js'].range = '>=9.0.0'; }, { version: VERSION }).join('\n'), /does not allow 67js/);
+ assert.match(errorsFor(pack => { pack['67js'].bundleBytes = 10; }).join('\n'), /raise bundleBytes|Raise bundleBytes/i);
+});
+
+test('the command line exits non-zero for a folder that breaks the contract', () => {
+ const folder = copyStarter(pack => { pack.keywords = []; });
+ try {
+ const result = spawnSync(process.execPath, [join(root, 'scripts', 'addon-check.mjs'), folder], { encoding: 'utf8' });
+ assert.equal(result.status, 1);
+ assert.match(result.stderr, /error: /);
+ } finally {
+ rmSync(folder, { recursive: true, force: true });
+ }
+});
+
+test('ranges parse caret and comparator forms', () => {
+ assert.ok(parseRange('^0.19.0'));
+ assert.equal(parseRange('wat'), null);
+ assert.equal(rangeAllows('^0.19.0', '0.19.4'), true);
+ assert.equal(rangeAllows('^0.19.0', '0.20.0'), false);
+ assert.equal(rangeAllows('>=0.19.0 <1.0.0', '0.20.0'), true);
+});