@driftengine/script

The drift/* capability bindings: what this engine provides to DriftScript, and the only place the two are coupled.

Cost: 36.9 KB gzipped on top of core. Measured by scripts/size-gate.test.mjs, which fails if it drifts more than 3% — the number is derived from the same floors that gate asserts, so a README quoting a stale one is a red suite rather than a thing somebody notices.

What it is

driftscript is a language and knows nothing about this engine: no scene, no mesh, no mix bus. This package is the other half — it describes each engine subsystem as capabilities a script may call, and supplies the implementations at link time.

Twelve modules are bound: drift/animation, audio, camera, ecs, events, input, persistence, physics, prefab, random, scene and time. drift/core is deliberately unbound, because its provider is startLoop, which drives a script rather than being called by one.

Four of drift/ecs's capabilities are ones nobody writes by hand. query, next, view and without are what a for … in query<…>() loop compiles to, so their documentation describes the shape of generated code rather than how to call them. They are capabilities rather than a second bind hook, so generated code reaches them exactly as it reaches everything else.

registerEntityModule turns a compiled module's declarations into the engine's own objects — a ComponentType per component, a Prefab per prefab, a SystemDefinition per system — and assertHostShapes checks every component X from host against what this host registered.

Reaching this package from a bundler config — you cannot, and do not need to

import { engineRegistry } from '@driftengine/script' fails inside a vite.config.ts, with ERR_MODULE_NOT_FOUND on a path like @driftengine/audio/src/registry. A bundler config is loaded by Node; engine packages use extensionless relative imports that only a bundler resolves. That is this engine's module layout and not a bug in the config.

Pass the data instead. This package ships it:

import { fileURLToPath } from 'node:url';
import { driftScript } from 'driftscript/vite';

driftScript({
  capabilities: fileURLToPath(import.meta.resolve('@driftengine/script/capabilities.json')),
  manifest: { name: 'my-game', provides: ['drift/ecs', 'drift/audio'] },
});

capabilities.json is regenerated by npm run capabilities and gated by npm run capabilities:check, so it cannot drift from the bindings above it. The DriftScript language server reads the same file for the same reason — see the next section for why a registry can cross a process boundary at all.

The registry describes and never invokes

A definition names its implementation as a string. The host supplies the functions when a module links. That is what keeps the language package host-neutral, and it is also what lets the language server read capabilities.json in a process that cannot import this engine at all.

Adding a binding

The five steps are at the top of src/host.ts, beside the code that does them. Two of them are the ones that get missed:

A capability that lands unbound is one DriftScript cannot reach, and nothing fails to say so. The linker refuses an unbound module by naming the track it waits on — so a script author hits a refusal that reads exactly like a track that has not shipped, and concludes it has not. The capability exists, is finished, is tested, and is unreachable.

Check whether an optional parameter must become required at the language boundary. A TypeScript signature may make one optional because its caller has the context to know when to pass it. A script author is further from the subsystem, meets the trap first, and gets a wrong result rather than an error. src/bindings/animation.ts is the worked example.

Write a binding from the source, never from a description of it. Two were written from a paraphrase and both were wrong — one named two methods the class does not have, reached through an optional-call cast, so a script calling it compiled, linked, ran and did nothing. src/host.test.ts now refuses ?.( and as unknown as anywhere under bindings/.

Part of DriftEngine. See docs/ARCHITECTURE.md for how the packages divide, and why some features are compiled into core on demand instead.