@driftengine/tools 4.1.0 → 4.1.1

package/README.md

@@ -4,7 +4,7 @@ The editor's panels, as something a shipped game can carry: an inspector, a cons
 a network panel, with the command stack that makes their edits undoable, and the overlay that puts
 them on screen on a key.
 
-**5,105 bytes gzipped**, measured by `scripts/size-gate.test.mjs` against
+**5,391 bytes gzipped**, measured by `scripts/size-gate.test.mjs` against
 `scripts/fixtures/size/tools-only.ts`. Optional — nothing in `@driftengine/core` imports it, so a
 game that never asks for these pays nothing.
 
@@ -77,6 +77,28 @@ if (overlay.route(keyEvent(event.key, event.shiftKey, event.ctrlKey))) event.pre
 While it is closed `frame` returns before it builds anything and `route` refuses every event but the
 one that opens it, so a game that never presses the key pays for a boolean.
 
+## Two adapters, because every consumer was about to write the same ones
+
+A panel needs its world in the shape the panel reads. Two of those shapes are the same in every
+game that has the thing behind them, so they are here rather than in each of them.
+
+`entitiesInspectable(world, types)` turns an entity world into an `InspectableWorld`: the inspector
+addresses a component by name because that is what a row carries, and a world addresses it by the
+type object because that is what indexes its stores. A name with no type behind it does nothing
+rather than guessing, so a row built from a stale schema cannot write a field into a component the
+world does not have and report success.
+
+`createSessionRecorder` plus `observeSession` and `sessionReadout` turn a lockstep session into a
+`NetworkReadout`. The watching is the part worth having written once: `session.desync` is **latched
+rather than an event**, so it keeps answering with the same disagreement every frame until the next
+one arrives, and a recorder that appended what it read would turn one divergence into sixty a
+second. `snapshotBytes` is the caller's, because `RewindLoop` is generic over the state it
+snapshots and cannot know the size of one.
+
+**Both are typed structurally**, the way `@driftengine/drft` takes DTEX types that
+`@driftengine/texture` satisfies, so this package depends on nothing new and anything shaped right
+can be read — including a consumer whose state is not an entity world at all.
+
 ## Building it in or leaving it out
 
 Import it and it is in the bundle; do not and it is not. There is no flag, because a flag would be a

package/dist/index.d.ts

@@ -25,12 +25,14 @@ export type { Selection } from './selection.ts';
 export { addToSelection, clearSelection, createSelection, isSelected, primarySelection, selectOnly, selectRange, selectedEntities, toggleSelection, } from './selection.ts';
 export { divergenceIsUnaccounted, divergentComponents } from './divergence.ts';
 export type { InspectableWorld, InspectorRow, InspectorView, InspectorWorld, RowKind, } from './inspector.ts';
-export { MIXED, addComponentCommand, createInspectorView, fieldEditable, inspectorPanel, inspectorRows, removeComponentCommand, rowText, setFieldCommand, } from './inspector.ts';
+export type { EntityWorldLike, InspectableComponentType } from './inspector.ts';
+export { MIXED, addComponentCommand, createInspectorView, entitiesInspectable, fieldEditable, inspectorPanel, inspectorRows, removeComponentCommand, rowText, setFieldCommand, } from './inspector.ts';
 export type { ConsoleView, ConsoleWorld, LogEntry, LogFilter, LogRing, Severity, SourceCursor, } from './console.ts';
 export { DISPLAY_LIMIT, appendLog, consolePanel, createConsoleView, createLogFilter, createLogRing, displayText, filteredEntries, jumpToSourceCommand, logEntries, } from './console.ts';
 export type { FrameHistory, ProfilerRow, ProfilerView, ProfilerWorld } from './profiler.ts';
 export { createFrameHistory, createGpuPassTimings, createProfilerView, formatMs, historyValues, occupancy, profilerPanel, profilerRows, pushFrame, recordGpuSample, } from './profiler.ts';
 export type { NetworkReadout, NetworkView, NetworkWorld, RollbackHistory } from './network.ts';
-export { componentDivergence, createNetworkView, createRollbackHistory, networkPanel, pushRollback, rollbackValues, } from './network.ts';
+export type { SessionLike, SessionRecorder } from './network.ts';
+export { componentDivergence, createNetworkView, createRollbackHistory, createSessionRecorder, networkPanel, observeSession, pushRollback, rollbackValues, sessionReadout, } from './network.ts';
 export type { OverlayPainter, OverlaySite, PanelBinding, ToolsOverlay, ToolsOverlayOptions, } from './overlay.ts';
 export { bindPanel, createToolsOverlay, paintOverlay } from './overlay.ts';

package/dist/index.js

@@ -3,8 +3,8 @@ export { createUndoStack } from './command.js';
 export { PANEL_PREFIX, createPanelRoot, emptyPanel, keyEvent, panelIdOf, pointerEvent, treeShape, wheelEvent, } from './panel.js';
 export { addToSelection, clearSelection, createSelection, isSelected, primarySelection, selectOnly, selectRange, selectedEntities, toggleSelection, } from './selection.js';
 export { divergenceIsUnaccounted, divergentComponents } from './divergence.js';
-export { MIXED, addComponentCommand, createInspectorView, fieldEditable, inspectorPanel, inspectorRows, removeComponentCommand, rowText, setFieldCommand, } from './inspector.js';
+export { MIXED, addComponentCommand, createInspectorView, entitiesInspectable, fieldEditable, inspectorPanel, inspectorRows, removeComponentCommand, rowText, setFieldCommand, } from './inspector.js';
 export { DISPLAY_LIMIT, appendLog, consolePanel, createConsoleView, createLogFilter, createLogRing, displayText, filteredEntries, jumpToSourceCommand, logEntries, } from './console.js';
 export { createFrameHistory, createGpuPassTimings, createProfilerView, formatMs, historyValues, occupancy, profilerPanel, profilerRows, pushFrame, recordGpuSample, } from './profiler.js';
-export { componentDivergence, createNetworkView, createRollbackHistory, networkPanel, pushRollback, rollbackValues, } from './network.js';
+export { componentDivergence, createNetworkView, createRollbackHistory, createSessionRecorder, networkPanel, observeSession, pushRollback, rollbackValues, sessionReadout, } from './network.js';
 export { bindPanel, createToolsOverlay, paintOverlay } from './overlay.js';

package/dist/inspector.d.ts

@@ -84,3 +84,45 @@ export declare function createInspectorView(options: {
 /** What a row shows to the right of its label. `—` is the mark for a disagreement. */
 export declare function rowText(row: InspectorRow): string;
 export declare const inspectorPanel: Panel<InspectorWorld, InspectorView>;
+/**
+ * The shape of a component type, as this package needs it.
+ *
+ * **Structural rather than imported.** `@driftengine/entities`' `ComponentType` satisfies it, and
+ * so does anything else a consumer describes its state with — which is the arrangement
+ * `@driftengine/drft` already has with `@driftengine/texture`'s DTEX types across a boundary the
+ * one package must not depend across. This package gains no dependency for the adapter below, so
+ * the release's place count does not move.
+ */
+export interface InspectableComponentType {
+    readonly name: string;
+    readonly schema: {
+        readonly fields: readonly {
+            readonly name: string;
+            readonly type: string;
+        }[];
+    };
+}
+/** The five methods the adapter forwards to. `World` has all of them. */
+export interface EntityWorldLike<T> {
+    has(entity: number, type: T): boolean;
+    add(entity: number, type: T): void;
+    remove(entity: number, type: T): boolean;
+    read(entity: number, type: T, field: string): unknown;
+    write(entity: number, type: T, field: string, value: unknown): void;
+}
+/**
+ * An entity world, as something the inspector can read and edit.
+ *
+ * **Written once here because every consumer with a world was about to write it.** The inspector
+ * addresses a component by name, since a name is what a row carries; a world addresses it by the
+ * type object, since that is what indexes its stores. Bridging the two is seven forwarding methods
+ * and a lookup, identical wherever it is written.
+ *
+ * **A name with no type behind it does nothing rather than guessing.** A row built against a stale
+ * schema would otherwise write a field into a component the world does not have and report
+ * success, which is a silent loss of the edit a person just made and watched apply.
+ *
+ * `componentsOf` answers in the order the types were given, so a panel's rows do not reorder
+ * between frames.
+ */
+export declare function entitiesInspectable<T extends InspectableComponentType>(world: EntityWorldLike<T>, types: readonly T[]): InspectableWorld;

package/dist/inspector.js

@@ -263,3 +263,58 @@ export const inspectorPanel = {
         return null;
     },
 };
+/**
+ * An entity world, as something the inspector can read and edit.
+ *
+ * **Written once here because every consumer with a world was about to write it.** The inspector
+ * addresses a component by name, since a name is what a row carries; a world addresses it by the
+ * type object, since that is what indexes its stores. Bridging the two is seven forwarding methods
+ * and a lookup, identical wherever it is written.
+ *
+ * **A name with no type behind it does nothing rather than guessing.** A row built against a stale
+ * schema would otherwise write a field into a component the world does not have and report
+ * success, which is a silent loss of the edit a person just made and watched apply.
+ *
+ * `componentsOf` answers in the order the types were given, so a panel's rows do not reorder
+ * between frames.
+ */
+export function entitiesInspectable(world, types) {
+    const byName = new Map();
+    for (const type of types)
+        byName.set(type.name, type);
+    return {
+        componentsOf(entity) {
+            const out = [];
+            for (const type of types)
+                if (world.has(entity, type))
+                    out.push(type.name);
+            return out;
+        },
+        schemaOf(component) {
+            return byName.get(component)?.schema.fields ?? [];
+        },
+        read(entity, component, field) {
+            const type = byName.get(component);
+            return type === undefined ? undefined : world.read(entity, type, field);
+        },
+        write(entity, component, field, value) {
+            const type = byName.get(component);
+            if (type !== undefined)
+                world.write(entity, type, field, value);
+        },
+        hasComponent(entity, component) {
+            const type = byName.get(component);
+            return type !== undefined && world.has(entity, type);
+        },
+        addComponent(entity, component) {
+            const type = byName.get(component);
+            if (type !== undefined)
+                world.add(entity, type);
+        },
+        removeComponent(entity, component) {
+            const type = byName.get(component);
+            if (type !== undefined)
+                world.remove(entity, type);
+        },
+    };
+}

package/dist/network.d.ts

@@ -56,3 +56,45 @@ export declare function createNetworkView(options: {
     historyLength?: number;
 }): NetworkView;
 export declare const networkPanel: Panel<NetworkWorld, NetworkView>;
+/**
+ * A session, as this package needs it.
+ *
+ * Structural rather than imported, so nothing here loads `@driftengine/network` at run time and a
+ * consumer whose session is its own shape can still be read.
+ */
+export interface SessionLike {
+    readonly participants: number;
+    readonly inputDelay: number;
+    /** The disagreement the session is currently holding, or null. Latched, not an event. */
+    readonly desync: Desync | null;
+    readonly loop: {
+        readonly depth: number;
+    };
+}
+/** What a recorder keeps: the disagreements it has seen, oldest first. */
+export interface SessionRecorder {
+    readonly desyncs: Desync[];
+    readonly limit: number;
+}
+export declare function createSessionRecorder(limit?: number): SessionRecorder;
+/**
+ * Watch a session for one frame.
+ *
+ * **`desync` is latched rather than an event**, which is the whole reason this is not one line at
+ * the call site. A session keeps answering with the same disagreement on every frame until the
+ * next one arrives, so appending what it reads turns one divergence into sixty a second and buries
+ * the tick somebody is looking for under copies of itself. A disagreement is new when its tick and
+ * peer differ from the last one kept.
+ *
+ * Bounded, because a session that desyncs every tick would otherwise grow an array forever behind
+ * a panel nobody has open.
+ */
+export declare function observeSession(recorder: SessionRecorder, session: SessionLike): void;
+/**
+ * The session and what has been seen of it, as the panel's readout.
+ *
+ * **`snapshotBytes` is the caller's, because the engine cannot know it.** `RewindLoop` is generic
+ * over the state it snapshots, so its depth is knowable here and the size of one is not. A caller
+ * passing zero is saying it has not measured, which the panel renders as such.
+ */
+export declare function sessionReadout(session: SessionLike, recorder: SessionRecorder, snapshotBytes: number, componentHashes?: NetworkReadout['componentHashes']): NetworkReadout;

package/dist/network.js

@@ -118,3 +118,46 @@ export const networkPanel = {
         return null;
     },
 };
+export function createSessionRecorder(limit = 32) {
+    return { desyncs: [], limit: Math.max(1, limit) };
+}
+/**
+ * Watch a session for one frame.
+ *
+ * **`desync` is latched rather than an event**, which is the whole reason this is not one line at
+ * the call site. A session keeps answering with the same disagreement on every frame until the
+ * next one arrives, so appending what it reads turns one divergence into sixty a second and buries
+ * the tick somebody is looking for under copies of itself. A disagreement is new when its tick and
+ * peer differ from the last one kept.
+ *
+ * Bounded, because a session that desyncs every tick would otherwise grow an array forever behind
+ * a panel nobody has open.
+ */
+export function observeSession(recorder, session) {
+    const seen = session.desync;
+    if (seen === null)
+        return;
+    const last = recorder.desyncs[recorder.desyncs.length - 1];
+    if (last !== undefined && last.tick === seen.tick && last.peer === seen.peer)
+        return;
+    recorder.desyncs.push(seen);
+    if (recorder.desyncs.length > recorder.limit)
+        recorder.desyncs.shift();
+}
+/**
+ * The session and what has been seen of it, as the panel's readout.
+ *
+ * **`snapshotBytes` is the caller's, because the engine cannot know it.** `RewindLoop` is generic
+ * over the state it snapshots, so its depth is knowable here and the size of one is not. A caller
+ * passing zero is saying it has not measured, which the panel renders as such.
+ */
+export function sessionReadout(session, recorder, snapshotBytes, componentHashes = null) {
+    return {
+        inputDelay: session.inputDelay,
+        participants: session.participants,
+        snapshotBytes,
+        snapshotCount: session.loop.depth,
+        desyncs: recorder.desyncs,
+        componentHashes,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/tools",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "The editor panels a shipped game can carry, and the command stack that makes their edits undoable",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,11 +27,11 @@
   ],
   "sideEffects": false,
   "peerDependencies": {
-    "@driftengine/core": "4.1.0",
-    "@driftengine/editor": "4.1.0",
-    "@driftengine/network": "4.1.0",
-    "@driftengine/texture": "4.1.0",
-    "@driftengine/ui2d": "4.1.0"
+    "@driftengine/core": "4.1.1",
+    "@driftengine/editor": "4.1.1",
+    "@driftengine/network": "4.1.1",
+    "@driftengine/texture": "4.1.1",
+    "@driftengine/ui2d": "4.1.1"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/index.ts

@@ -58,10 +58,12 @@ export type {
   InspectorWorld,
   RowKind,
 } from './inspector.ts';
+export type { EntityWorldLike, InspectableComponentType } from './inspector.ts';
 export {
   MIXED,
   addComponentCommand,
   createInspectorView,
+  entitiesInspectable,
   fieldEditable,
   inspectorPanel,
   inspectorRows,
@@ -107,13 +109,17 @@ export {
 } from './profiler.ts';
 
 export type { NetworkReadout, NetworkView, NetworkWorld, RollbackHistory } from './network.ts';
+export type { SessionLike, SessionRecorder } from './network.ts';
 export {
   componentDivergence,
   createNetworkView,
   createRollbackHistory,
+  createSessionRecorder,
   networkPanel,
+  observeSession,
   pushRollback,
   rollbackValues,
+  sessionReadout,
 } from './network.ts';
 
 /*

package/src/inspector.ts

@@ -348,3 +348,80 @@ export const inspectorPanel: Panel<InspectorWorld, InspectorView> = {
     return null;
   },
 };
+
+/**
+ * The shape of a component type, as this package needs it.
+ *
+ * **Structural rather than imported.** `@driftengine/entities`' `ComponentType` satisfies it, and
+ * so does anything else a consumer describes its state with — which is the arrangement
+ * `@driftengine/drft` already has with `@driftengine/texture`'s DTEX types across a boundary the
+ * one package must not depend across. This package gains no dependency for the adapter below, so
+ * the release's place count does not move.
+ */
+export interface InspectableComponentType {
+  readonly name: string;
+  readonly schema: { readonly fields: readonly { readonly name: string; readonly type: string }[] };
+}
+
+/** The five methods the adapter forwards to. `World` has all of them. */
+export interface EntityWorldLike<T> {
+  has(entity: number, type: T): boolean;
+  add(entity: number, type: T): void;
+  remove(entity: number, type: T): boolean;
+  read(entity: number, type: T, field: string): unknown;
+  write(entity: number, type: T, field: string, value: unknown): void;
+}
+
+/**
+ * An entity world, as something the inspector can read and edit.
+ *
+ * **Written once here because every consumer with a world was about to write it.** The inspector
+ * addresses a component by name, since a name is what a row carries; a world addresses it by the
+ * type object, since that is what indexes its stores. Bridging the two is seven forwarding methods
+ * and a lookup, identical wherever it is written.
+ *
+ * **A name with no type behind it does nothing rather than guessing.** A row built against a stale
+ * schema would otherwise write a field into a component the world does not have and report
+ * success, which is a silent loss of the edit a person just made and watched apply.
+ *
+ * `componentsOf` answers in the order the types were given, so a panel's rows do not reorder
+ * between frames.
+ */
+export function entitiesInspectable<T extends InspectableComponentType>(
+  world: EntityWorldLike<T>,
+  types: readonly T[],
+): InspectableWorld {
+  const byName = new Map<string, T>();
+  for (const type of types) byName.set(type.name, type);
+
+  return {
+    componentsOf(entity: number): readonly string[] {
+      const out: string[] = [];
+      for (const type of types) if (world.has(entity, type)) out.push(type.name);
+      return out;
+    },
+    schemaOf(component: string): readonly { readonly name: string; readonly type: string }[] {
+      return byName.get(component)?.schema.fields ?? [];
+    },
+    read(entity: number, component: string, field: string): unknown {
+      const type = byName.get(component);
+      return type === undefined ? undefined : world.read(entity, type, field);
+    },
+    write(entity: number, component: string, field: string, value: unknown): void {
+      const type = byName.get(component);
+      if (type !== undefined) world.write(entity, type, field, value);
+    },
+    hasComponent(entity: number, component: string): boolean {
+      const type = byName.get(component);
+      return type !== undefined && world.has(entity, type);
+    },
+    addComponent(entity: number, component: string): void {
+      const type = byName.get(component);
+      if (type !== undefined) world.add(entity, type);
+    },
+    removeComponent(entity: number, component: string): void {
+      const type = byName.get(component);
+      if (type !== undefined) world.remove(entity, type);
+    },
+  };
+}

package/src/network.ts

@@ -183,3 +183,71 @@ export const networkPanel: Panel<NetworkWorld, NetworkView> = {
     return null;
   },
 };
+
+/**
+ * A session, as this package needs it.
+ *
+ * Structural rather than imported, so nothing here loads `@driftengine/network` at run time and a
+ * consumer whose session is its own shape can still be read.
+ */
+export interface SessionLike {
+  readonly participants: number;
+  readonly inputDelay: number;
+  /** The disagreement the session is currently holding, or null. Latched, not an event. */
+  readonly desync: Desync | null;
+  readonly loop: { readonly depth: number };
+}
+
+/** What a recorder keeps: the disagreements it has seen, oldest first. */
+export interface SessionRecorder {
+  readonly desyncs: Desync[];
+  readonly limit: number;
+}
+
+export function createSessionRecorder(limit = 32): SessionRecorder {
+  return { desyncs: [], limit: Math.max(1, limit) };
+}
+
+/**
+ * Watch a session for one frame.
+ *
+ * **`desync` is latched rather than an event**, which is the whole reason this is not one line at
+ * the call site. A session keeps answering with the same disagreement on every frame until the
+ * next one arrives, so appending what it reads turns one divergence into sixty a second and buries
+ * the tick somebody is looking for under copies of itself. A disagreement is new when its tick and
+ * peer differ from the last one kept.
+ *
+ * Bounded, because a session that desyncs every tick would otherwise grow an array forever behind
+ * a panel nobody has open.
+ */
+export function observeSession(recorder: SessionRecorder, session: SessionLike): void {
+  const seen = session.desync;
+  if (seen === null) return;
+  const last = recorder.desyncs[recorder.desyncs.length - 1];
+  if (last !== undefined && last.tick === seen.tick && last.peer === seen.peer) return;
+  recorder.desyncs.push(seen);
+  if (recorder.desyncs.length > recorder.limit) recorder.desyncs.shift();
+}
+
+/**
+ * The session and what has been seen of it, as the panel's readout.
+ *
+ * **`snapshotBytes` is the caller's, because the engine cannot know it.** `RewindLoop` is generic
+ * over the state it snapshots, so its depth is knowable here and the size of one is not. A caller
+ * passing zero is saying it has not measured, which the panel renders as such.
+ */
+export function sessionReadout(
+  session: SessionLike,
+  recorder: SessionRecorder,
+  snapshotBytes: number,
+  componentHashes: NetworkReadout['componentHashes'] = null,
+): NetworkReadout {
+  return {
+    inputDelay: session.inputDelay,
+    participants: session.participants,
+    snapshotBytes,
+    snapshotCount: session.loop.depth,
+    desyncs: recorder.desyncs,
+    componentHashes,
+  };
+}