@driftengine/script 4.8.1 → 4.8.3

package/README.md

@@ -3,7 +3,7 @@
 The `drift/*` capability bindings: what this engine provides to DriftScript, and **the only place the
 two are coupled**.
 
-**Cost: 37.3 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it
+**Cost: 40.3 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.
 

package/capabilities.json

@@ -2704,7 +2704,8 @@
         },
         {
           "name": "component",
-          "type": "String"
+          "type": "String",
+          "component": "read"
         }
       ],
       "returns": "bool",
@@ -2730,7 +2731,8 @@
         },
         {
           "name": "component",
-          "type": "String"
+          "type": "String",
+          "component": "write"
         }
       ],
       "returns": "void",
@@ -2756,7 +2758,8 @@
         },
         {
           "name": "component",
-          "type": "String"
+          "type": "String",
+          "component": "write"
         }
       ],
       "returns": "bool",
@@ -2782,7 +2785,8 @@
         },
         {
           "name": "component",
-          "type": "String"
+          "type": "String",
+          "component": "read"
         },
         {
           "name": "field",
@@ -2812,7 +2816,8 @@
         },
         {
           "name": "component",
-          "type": "String"
+          "type": "String",
+          "component": "write"
         },
         {
           "name": "field",
@@ -2842,7 +2847,8 @@
         },
         {
           "name": "component",
-          "type": "String"
+          "type": "String",
+          "component": "read"
         }
       ],
       "returns": "u32",
@@ -2864,7 +2870,8 @@
         },
         {
           "name": "component",
-          "type": "String"
+          "type": "String",
+          "component": "read"
         },
         {
           "name": "index",
@@ -2890,7 +2897,8 @@
         },
         {
           "name": "component",
-          "type": "String"
+          "type": "String",
+          "component": "read"
         },
         {
           "name": "fieldX",
@@ -4104,19 +4112,23 @@
         },
         {
           "name": "a",
-          "type": "String"
+          "type": "String",
+          "component": "read"
         },
         {
           "name": "b",
-          "type": "String"
+          "type": "String",
+          "component": "read"
         },
         {
           "name": "c",
-          "type": "String"
+          "type": "String",
+          "component": "read"
         },
         {
           "name": "d",
-          "type": "String"
+          "type": "String",
+          "component": "read"
         }
       ],
       "returns": "Cursor",
@@ -4178,7 +4190,8 @@
         },
         {
           "name": "component",
-          "type": "String"
+          "type": "String",
+          "component": "read"
         },
         {
           "name": "forWriting",

package/dist/bindings/entities.js

@@ -26,7 +26,7 @@
  * should walk backwards, and the doc on `at` says so.
  */
 import { ENTITY_INDEX_CEILING, instantiate, } from '@driftengine/entities';
-import { defineCapability } from 'driftscript';
+import { defineCapability, } from 'driftscript';
 export const ECS_MODULE = 'drift/ecs';
 const define = (module, name, params, returns, effects, deterministic, doc) => defineCapability({
     module,
@@ -74,6 +74,15 @@ export const ENTITY_TYPES = [
  * **`read` still answers `f64`**, and that is not an oversight: it reads a component *field*, which
  * is a number, and typing it as a handle would be the same mistake in the other direction.
  */
+/*
+ * **A parameter that names a component says so, and how** (`component: 'read' | 'write'`), so the
+ * compiler counts `ecs.count(world, "Hunger")` as a read of Hunger exactly as the schedule does when
+ * the system runs: without it the declaration the host demands was called unused (DS0291), and
+ * leaving it out compiled clean and was refused per tick. `without` names one and is not marked —
+ * an exclusion never looks inside the component, which is the host's rule and the compiler's. `view`
+ * is marked a read: whether it asks to write is a runtime flag, and the write it would need is a
+ * declaration the host still checks.
+ */
 export const ECS_CAPABILITIES = [
     define(ECS_MODULE, 'create', [{ name: 'world', type: 'World' }], 'Entity', ['ecs.write'], false, 'A fresh entity with nothing on it. The handle is exact; do not put one in an `f32`.'),
     define(ECS_MODULE, 'destroy', [
@@ -87,38 +96,38 @@ export const ECS_CAPABILITIES = [
     define(ECS_MODULE, 'has', [
         { name: 'world', type: 'World' },
         { name: 'entity', type: 'Entity' },
-        { name: 'component', type: 'String' },
+        { name: 'component', type: 'String', component: 'read' },
     ], 'bool', ['ecs.read'], true, 'Whether an entity carries a component.'),
     define(ECS_MODULE, 'attach', [
         { name: 'world', type: 'World' },
         { name: 'entity', type: 'Entity' },
-        { name: 'component', type: 'String' },
+        { name: 'component', type: 'String', component: 'write' },
     ], 'void', ['ecs.write'], false, 'Give an entity a component, every field at the zero for its type. Set them with `write`.'),
     define(ECS_MODULE, 'detach', [
         { name: 'world', type: 'World' },
         { name: 'entity', type: 'Entity' },
-        { name: 'component', type: 'String' },
+        { name: 'component', type: 'String', component: 'write' },
     ], 'bool', ['ecs.write'], false, 'Take a component away. False when it did not have one.'),
     define(ECS_MODULE, 'read', [
         { name: 'world', type: 'World' },
         { name: 'entity', type: 'Entity' },
-        { name: 'component', type: 'String' },
+        { name: 'component', type: 'String', component: 'read' },
         { name: 'field', type: 'String' },
     ], 'f64', ['ecs.read'], true, 'One numeric field. Reading a field of a component an entity does not have is 0.'),
     define(ECS_MODULE, 'write', [
         { name: 'world', type: 'World' },
         { name: 'entity', type: 'Entity' },
-        { name: 'component', type: 'String' },
+        { name: 'component', type: 'String', component: 'write' },
         { name: 'field', type: 'String' },
         { name: 'value', type: 'f64' },
     ], 'void', ['ecs.write'], false, 'Set one numeric field.'),
     define(ECS_MODULE, 'count', [
         { name: 'world', type: 'World' },
-        { name: 'component', type: 'String' },
+        { name: 'component', type: 'String', component: 'read' },
     ], 'u32', ['ecs.read'], true, 'How many entities carry a component.'),
     define(ECS_MODULE, 'at', [
         { name: 'world', type: 'World' },
-        { name: 'component', type: 'String' },
+        { name: 'component', type: 'String', component: 'read' },
         { name: 'index', type: 'u32' },
     ], 'Entity', ['ecs.read'], true, 'The nth entity carrying a component. **The order is insertion modified by swap-removal**, so a walk that removes should count downwards — removing moves the last entity into a position already passed.'),
     /*
@@ -137,7 +146,7 @@ export const ECS_CAPABILITIES = [
      */
     define(ECS_MODULE, 'findNearest', [
         { name: 'world', type: 'World' },
-        { name: 'component', type: 'String' },
+        { name: 'component', type: 'String', component: 'read' },
         { name: 'fieldX', type: 'String' },
         { name: 'fieldY', type: 'String' },
         { name: 'fieldZ', type: 'String' },
@@ -169,10 +178,10 @@ export const ECS_CAPABILITIES = [
 export const QUERY_CAPABILITIES = [
     define(ECS_MODULE, 'query', [
         { name: 'world', type: 'World' },
-        { name: 'a', type: 'String' },
-        { name: 'b', type: 'String' },
-        { name: 'c', type: 'String' },
-        { name: 'd', type: 'String' },
+        { name: 'a', type: 'String', component: 'read' },
+        { name: 'b', type: 'String', component: 'read' },
+        { name: 'c', type: 'String', component: 'read' },
+        { name: 'd', type: 'String', component: 'read' },
     ], 'Cursor', ['ecs.read'], true, 'Open a walk over everything carrying these components. The cursor is borrowed from the world’s pool; ending the walk gives it back.'),
     define(ECS_MODULE, 'without', [
         { name: 'cursor', type: 'Cursor' },
@@ -181,7 +190,7 @@ export const QUERY_CAPABILITIES = [
     define(ECS_MODULE, 'next', [{ name: 'cursor', type: 'Cursor' }], 'Entity', ['ecs.read'], true, 'The next entity, or a **negative** number when the walk is done — which also gives the cursor back. Negative rather than zero, because zero is a legal handle.'),
     define(ECS_MODULE, 'view', [
         { name: 'world', type: 'World' },
-        { name: 'component', type: 'String' },
+        { name: 'component', type: 'String', component: 'read' },
         { name: 'forWriting', type: 'bool' },
     ], 'View', ['ecs.read'], true, 'A component’s live columns. `forWriting` decides which of a system’s declarations is checked — a loop that only reads takes a readable view, and asking for more than the system declared is refused.'),
 ];

package/dist/index.d.ts

@@ -18,4 +18,5 @@ export { CHEMISTRY_CAPABILITIES, CHEMISTRY_COMPONENT, CHEMISTRY_MODULE, CHEMISTR
 export type { ComponentRegistry, RegisteredModule } from './entityHost.ts';
 export { assertHostShapes, registerEntityModule } from './entityHost.ts';
 export type { BindResult, HostServices } from './host.ts';
+export type { XrRuntime } from './bindings/xr.ts';
 export { ENGINE_MODULES, bindModule, engineImplementations, engineRegistry, engineTarget, } from './host.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/script",
-  "version": "4.8.1",
+  "version": "4.8.3",
   "description": "The drift/* capability bindings: what this engine provides to DriftScript, and the only place the two are coupled",
   "license": "Apache-2.0",
   "type": "module",
@@ -28,20 +28,20 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "driftscript": "1.16.0"
+    "driftscript": "1.17.0"
   },
   "peerDependencies": {
-    "@driftengine/ai": "4.8.1",
-    "@driftengine/animation": "4.8.1",
-    "@driftengine/audio": "4.8.1",
-    "@driftengine/chemistry": "4.8.1",
-    "@driftengine/core": "4.8.1",
-    "@driftengine/editor": "4.8.1",
-    "@driftengine/entities": "4.8.1",
-    "@driftengine/network": "4.8.1",
-    "@driftengine/terrain": "4.8.1",
-    "@driftengine/ui2d": "4.8.1",
-    "@driftengine/xr": "4.8.1"
+    "@driftengine/ai": "4.8.3",
+    "@driftengine/animation": "4.8.3",
+    "@driftengine/audio": "4.8.3",
+    "@driftengine/chemistry": "4.8.3",
+    "@driftengine/core": "4.8.3",
+    "@driftengine/editor": "4.8.3",
+    "@driftengine/entities": "4.8.3",
+    "@driftengine/network": "4.8.3",
+    "@driftengine/terrain": "4.8.3",
+    "@driftengine/ui2d": "4.8.3",
+    "@driftengine/xr": "4.8.3"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/bindings/entities.ts

@@ -36,14 +36,19 @@ import {
   type World,
   instantiate,
 } from '@driftengine/entities';
-import { type CapabilityDefinition, type OpaqueType, defineCapability } from 'driftscript';
+import {
+  type CapabilityDefinition,
+  type CapabilityParam,
+  type OpaqueType,
+  defineCapability,
+} from 'driftscript';
 
 export const ECS_MODULE = 'drift/ecs';
 
 const define = (
   module: string,
   name: string,
-  params: readonly { name: string; type: string }[],
+  params: readonly CapabilityParam[],
   returns: string,
   effects: CapabilityDefinition['effects'],
   deterministic: boolean,
@@ -97,6 +102,15 @@ export const ENTITY_TYPES: readonly OpaqueType[] = [
  * **`read` still answers `f64`**, and that is not an oversight: it reads a component *field*, which
  * is a number, and typing it as a handle would be the same mistake in the other direction.
  */
+/*
+ * **A parameter that names a component says so, and how** (`component: 'read' | 'write'`), so the
+ * compiler counts `ecs.count(world, "Hunger")` as a read of Hunger exactly as the schedule does when
+ * the system runs: without it the declaration the host demands was called unused (DS0291), and
+ * leaving it out compiled clean and was refused per tick. `without` names one and is not marked —
+ * an exclusion never looks inside the component, which is the host's rule and the compiler's. `view`
+ * is marked a read: whether it asks to write is a runtime flag, and the write it would need is a
+ * declaration the host still checks.
+ */
 export const ECS_CAPABILITIES: readonly CapabilityDefinition[] = [
   define(
     ECS_MODULE,
@@ -137,7 +151,7 @@ export const ECS_CAPABILITIES: readonly CapabilityDefinition[] = [
     [
       { name: 'world', type: 'World' },
       { name: 'entity', type: 'Entity' },
-      { name: 'component', type: 'String' },
+      { name: 'component', type: 'String', component: 'read' },
     ],
     'bool',
     ['ecs.read'],
@@ -150,7 +164,7 @@ export const ECS_CAPABILITIES: readonly CapabilityDefinition[] = [
     [
       { name: 'world', type: 'World' },
       { name: 'entity', type: 'Entity' },
-      { name: 'component', type: 'String' },
+      { name: 'component', type: 'String', component: 'write' },
     ],
     'void',
     ['ecs.write'],
@@ -163,7 +177,7 @@ export const ECS_CAPABILITIES: readonly CapabilityDefinition[] = [
     [
       { name: 'world', type: 'World' },
       { name: 'entity', type: 'Entity' },
-      { name: 'component', type: 'String' },
+      { name: 'component', type: 'String', component: 'write' },
     ],
     'bool',
     ['ecs.write'],
@@ -176,7 +190,7 @@ export const ECS_CAPABILITIES: readonly CapabilityDefinition[] = [
     [
       { name: 'world', type: 'World' },
       { name: 'entity', type: 'Entity' },
-      { name: 'component', type: 'String' },
+      { name: 'component', type: 'String', component: 'read' },
       { name: 'field', type: 'String' },
     ],
     'f64',
@@ -190,7 +204,7 @@ export const ECS_CAPABILITIES: readonly CapabilityDefinition[] = [
     [
       { name: 'world', type: 'World' },
       { name: 'entity', type: 'Entity' },
-      { name: 'component', type: 'String' },
+      { name: 'component', type: 'String', component: 'write' },
       { name: 'field', type: 'String' },
       { name: 'value', type: 'f64' },
     ],
@@ -204,7 +218,7 @@ export const ECS_CAPABILITIES: readonly CapabilityDefinition[] = [
     'count',
     [
       { name: 'world', type: 'World' },
-      { name: 'component', type: 'String' },
+      { name: 'component', type: 'String', component: 'read' },
     ],
     'u32',
     ['ecs.read'],
@@ -216,7 +230,7 @@ export const ECS_CAPABILITIES: readonly CapabilityDefinition[] = [
     'at',
     [
       { name: 'world', type: 'World' },
-      { name: 'component', type: 'String' },
+      { name: 'component', type: 'String', component: 'read' },
       { name: 'index', type: 'u32' },
     ],
     'Entity',
@@ -243,7 +257,7 @@ export const ECS_CAPABILITIES: readonly CapabilityDefinition[] = [
     'findNearest',
     [
       { name: 'world', type: 'World' },
-      { name: 'component', type: 'String' },
+      { name: 'component', type: 'String', component: 'read' },
       { name: 'fieldX', type: 'String' },
       { name: 'fieldY', type: 'String' },
       { name: 'fieldZ', type: 'String' },
@@ -300,10 +314,10 @@ export const QUERY_CAPABILITIES: readonly CapabilityDefinition[] = [
     'query',
     [
       { name: 'world', type: 'World' },
-      { name: 'a', type: 'String' },
-      { name: 'b', type: 'String' },
-      { name: 'c', type: 'String' },
-      { name: 'd', type: 'String' },
+      { name: 'a', type: 'String', component: 'read' },
+      { name: 'b', type: 'String', component: 'read' },
+      { name: 'c', type: 'String', component: 'read' },
+      { name: 'd', type: 'String', component: 'read' },
     ],
     'Cursor',
     ['ecs.read'],
@@ -336,7 +350,7 @@ export const QUERY_CAPABILITIES: readonly CapabilityDefinition[] = [
     'view',
     [
       { name: 'world', type: 'World' },
-      { name: 'component', type: 'String' },
+      { name: 'component', type: 'String', component: 'read' },
       { name: 'forWriting', type: 'bool' },
     ],
     'View',

package/src/index.ts

@@ -32,6 +32,8 @@ export type { ComponentRegistry, RegisteredModule } from './entityHost.ts';
 export { assertHostShapes, registerEntityModule } from './entityHost.ts';
 
 export type { BindResult, HostServices } from './host.ts';
+/* What `HostServices.xr` takes, by name, so a host does not spell it `NonNullable<HostServices['xr']>`. */
+export type { XrRuntime } from './bindings/xr.ts';
 export {
   ENGINE_MODULES,
   bindModule,