@driftengine/entities 4.7.4 → 4.8.1

package/README.md

@@ -45,6 +45,15 @@ runSchedule(world, schedule, tick);
 **The declaration is enforced.** A system that writes something it did not declare is refused
 naming both — a schedule derived from a lie is worse than no schedule. `writes` implies `reads`.
 
+**A system that throws is skipped, and the others still run.** By default the failure is logged once
+per system per world. Pass a reporter as the fourth argument to take every failure, every tick, with
+the system's name, the tick and the error, and nothing is logged; throw from it to make a failure
+fatal while developing:
+
+```ts
+runSchedule(world, schedule, tick, ({ system, tick, error }) => overlay.add(system, tick, error));
+```
+
 Order is declaration order, adjusted only by `after`, which is topologically sorted with
 declaration order as the tie-break. A cycle in `after` is refused naming the systems.
 

package/dist/index.d.ts

@@ -25,7 +25,7 @@ export type { WorldSnapshot } from './world.ts';
 export { World, createWorldSnapshot } from './world.ts';
 export type { SystemDefinition, SystemView } from './system.ts';
 export { BoundSystem } from './system.ts';
-export type { Schedule } from './schedule.ts';
+export type { Schedule, SystemFailure, SystemFailureReporter } from './schedule.ts';
 export { buildSchedule, runSchedule } from './schedule.ts';
 export type { Prefab } from './prefab.ts';
 export { definePrefab, instantiate } from './prefab.ts';

package/dist/schedule.d.ts

@@ -37,8 +37,21 @@ export declare function buildSchedule(systems: readonly SystemDefinition[]): Sch
  * function no longer throws, which is what `AGENTS.md` requires of anything the frame loop calls.
  *
  * **What it gives up** is the stack reaching a debugger's uncaught-exception break, which is how
- * somebody working on a system would rather meet it. **What would change it** is a consumer wanting
- * failures fatal in development; the answer then is a reporter this takes as a parameter rather than
- * a rule chosen here for everybody.
+ * somebody working on a system would rather meet it. So `report` takes the decision back: given one,
+ * every failure goes to it, every tick it happens, with the system's name, the tick and the error as
+ * thrown, and nothing is logged. A game can count failures, show them in a debug overlay, send them
+ * to its own telemetry, or throw from it to make a failure fatal in development, which stops the
+ * schedule there. Without one, the failure is said once per system per world, as above.
  */
-export declare function runSchedule(world: World, schedule: Schedule, tick: number): void;
+export declare function runSchedule(world: World, schedule: Schedule, tick: number, report?: SystemFailureReporter): void;
+/** One system's failure in one step, as `runSchedule` hands it to a reporter. */
+export interface SystemFailure {
+    /** The failing system's name, as its definition gave it. */
+    readonly system: string;
+    /** The tick it failed on: the `tick` the schedule was run with. */
+    readonly tick: number;
+    /** What the system threw, unchanged. */
+    readonly error: unknown;
+}
+/** Called with every failure, every tick. Throwing from it stops the schedule at that system. */
+export type SystemFailureReporter = (failure: SystemFailure) => void;

package/dist/schedule.js

@@ -117,11 +117,13 @@ const reported = new WeakMap();
  * function no longer throws, which is what `AGENTS.md` requires of anything the frame loop calls.
  *
  * **What it gives up** is the stack reaching a debugger's uncaught-exception break, which is how
- * somebody working on a system would rather meet it. **What would change it** is a consumer wanting
- * failures fatal in development; the answer then is a reporter this takes as a parameter rather than
- * a rule chosen here for everybody.
+ * somebody working on a system would rather meet it. So `report` takes the decision back: given one,
+ * every failure goes to it, every tick it happens, with the system's name, the tick and the error as
+ * thrown, and nothing is logged. A game can count failures, show them in a debug overlay, send them
+ * to its own telemetry, or throw from it to make a failure fatal in development, which stops the
+ * schedule there. Without one, the failure is said once per system per world, as above.
  */
-export function runSchedule(world, schedule, tick) {
+export function runSchedule(world, schedule, tick, report) {
     let forWorld = bound.get(world);
     if (forWorld === undefined) {
         forWorld = new Map();
@@ -140,7 +142,10 @@ export function runSchedule(world, schedule, tick) {
             system.run();
         }
         catch (error) {
-            announce(world, definition, error);
+            if (report === undefined)
+                announce(world, definition, error);
+            else
+                report({ system: definition.name, tick, error });
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/entities",
-  "version": "4.7.4",
+  "version": "4.8.1",
   "description": "Entities with generational identity, component storage, systems and scenes",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,7 +27,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "driftscript": "1.14.0"
+    "driftscript": "1.16.0"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/index.ts

@@ -35,7 +35,7 @@ export { World, createWorldSnapshot } from './world.ts';
 export type { SystemDefinition, SystemView } from './system.ts';
 export { BoundSystem } from './system.ts';
 
-export type { Schedule } from './schedule.ts';
+export type { Schedule, SystemFailure, SystemFailureReporter } from './schedule.ts';
 export { buildSchedule, runSchedule } from './schedule.ts';
 
 export type { Prefab } from './prefab.ts';

package/src/schedule.ts

@@ -158,11 +158,18 @@ const reported = new WeakMap<World, Set<SystemDefinition>>();
  * function no longer throws, which is what `AGENTS.md` requires of anything the frame loop calls.
  *
  * **What it gives up** is the stack reaching a debugger's uncaught-exception break, which is how
- * somebody working on a system would rather meet it. **What would change it** is a consumer wanting
- * failures fatal in development; the answer then is a reporter this takes as a parameter rather than
- * a rule chosen here for everybody.
+ * somebody working on a system would rather meet it. So `report` takes the decision back: given one,
+ * every failure goes to it, every tick it happens, with the system's name, the tick and the error as
+ * thrown, and nothing is logged. A game can count failures, show them in a debug overlay, send them
+ * to its own telemetry, or throw from it to make a failure fatal in development, which stops the
+ * schedule there. Without one, the failure is said once per system per world, as above.
  */
-export function runSchedule(world: World, schedule: Schedule, tick: number): void {
+export function runSchedule(
+  world: World,
+  schedule: Schedule,
+  tick: number,
+  report?: SystemFailureReporter,
+): void {
   let forWorld = bound.get(world);
   if (forWorld === undefined) {
     forWorld = new Map();
@@ -181,11 +188,25 @@ export function runSchedule(world: World, schedule: Schedule, tick: number): voi
     try {
       system.run();
     } catch (error) {
-      announce(world, definition, error);
+      if (report === undefined) announce(world, definition, error);
+      else report({ system: definition.name, tick, error });
     }
   }
 }
 
+/** One system's failure in one step, as `runSchedule` hands it to a reporter. */
+export interface SystemFailure {
+  /** The failing system's name, as its definition gave it. */
+  readonly system: string;
+  /** The tick it failed on: the `tick` the schedule was run with. */
+  readonly tick: number;
+  /** What the system threw, unchanged. */
+  readonly error: unknown;
+}
+
+/** Called with every failure, every tick. Throwing from it stops the schedule at that system. */
+export type SystemFailureReporter = (failure: SystemFailure) => void;
+
 /** Say what failed, once per system per world. */
 function announce(world: World, definition: SystemDefinition, error: unknown): void {
   let seen = reported.get(world);