@skewedaspect/sage-core 0.10.0-beta.2 → 0.10.0-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher Case
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/behavior.d.ts

@@ -1,13 +1,16 @@
-import { EventSubscription, GameEvent } from "./events.d.ts";
-import { GameEntity } from "./gameEntity.d.ts";
-export declare abstract class Behavior<State extends object, Requires extends object = object> {
+import { Computation } from "./computedState.js";
+import { EventSubscription, GameEvent } from "./events.js";
+import { GameEntity } from "./gameEntity.js";
+export declare abstract class Behavior<State extends object, Requires extends object = object, Entity extends GameEntity = GameEntity> {
     readonly state: State;
     readonly ops: Requires;
-    readonly entity: GameEntity;
+    readonly entity: Entity;
     abstract readonly defaults: State;
+    onStateReady?(): void;
     onCreate?(): void;
     onUpdate?(dt: number): void;
     onEvent?(event: GameEvent): boolean | undefined;
+    protected computed<Field extends keyof State & string>(field: Field, computation: Computation<State[Field]>): void;
 }
 export interface BehaviorClass {
     new (): Behavior<object, object>;

package/dist/computedState.d.ts

@@ -0,0 +1,11 @@
+/** What a computed field is read and written through (design/entities.md#computed-state). */
+export interface Computation<Value> {
+    get: () => Value;
+    set: (value: Value) => void;
+}
+export declare function defineComputed<Value>(state: object, field: string, computation: Computation<Value>): void;
+/**
+ * Take every computation off a state bag, newest first, so a computation over a computation leaves the one beneath
+ * it answering and the field ends as the plain value the last one answered with.
+ */
+export declare function removeComputed(state: object): void;

package/dist/eventBus.d.ts

@@ -1,7 +1,15 @@
-import { EventSubscription, GameEvent, Subscriber, Unsubscribe } from "./events.d.ts";
+import { EventSubscription, EventsMatching, GameEvent, RawGameEvent, Subscriber, Unsubscribe } from "./events.js";
+export type EventCallback<Subscription extends EventSubscription = EventSubscription> = (event: EventsMatching<Subscription>) => void;
 export declare class EventBus {
     #private;
     register(subscriber: Subscriber, subscriptions: readonly EventSubscription[]): Unsubscribe;
+    on<Subscription extends EventSubscription>(subscription: Subscription, callback: EventCallback<Subscription>): Unsubscribe;
+    /**
+     * The ID the n-th subscriber `on` makes registers under (design/events.md#registration).
+     */
+    protected mintSubscriberID(ordinal: number): string;
     emit(event: GameEvent): void;
     drain(): void;
+    protected takeQueuedEvents(): GameEvent[];
+    protected static reclaimQueuedEvents(bus: EventBus, events: readonly RawGameEvent[]): GameEvent[];
 }

package/dist/events.d.ts

@@ -1,4 +1,4 @@
-import { EventMap } from "./index.d.ts";
+import { EventMap } from "./index.js";
 export type { EventMap };
 export type GameEvent = {
     [Type in keyof EventMap & string]: {
@@ -10,6 +10,11 @@ export type GameEvent = {
 }[keyof EventMap & string];
 type EventPrefix<Type extends string> = Type extends `${infer Prefix}:${infer Rest}` ? Prefix | `${Prefix}:${EventPrefix<Rest>}` : never;
 export type EventSubscription = (keyof EventMap & string) | `${EventPrefix<keyof EventMap & string>}:*`;
+export type EventsMatching<Subscription extends EventSubscription> = Subscription extends `${infer Prefix}:*` ? Extract<GameEvent, {
+    type: `${Prefix}:${string}`;
+}> : Extract<GameEvent, {
+    type: Subscription;
+}>;
 export type Unsubscribe = () => void;
 export interface Subscriber {
     readonly id: string;

package/dist/gameEntity.d.ts

@@ -1,6 +1,7 @@
-import { EventMap, EventSubscription, GameEvent, Subscriber } from "./events.d.ts";
-import { Behavior, BehaviorClass } from "./behavior.d.ts";
-import { GameSimulationContext } from "./simulationContext.d.ts";
+import { Computation } from "./computedState.js";
+import { EventMap, GameEvent, Subscriber } from "./events.js";
+import { Behavior, BehaviorClass } from "./behavior.js";
+import { GameSimulationContext } from "./simulationContext.js";
 export type StateValue = null | boolean | number | string | StateValue[] | {
     [key: string]: StateValue;
 };
@@ -27,6 +28,9 @@ export type StateFor<Behaviors extends readonly BehaviorClass[]> = GameEntitySta
 export type OpsFor<Behaviors extends readonly BehaviorClass[]> = UnionToIntersection<OpsFrom<Behaviors[number]>> & object;
 export type OpsOf<Class extends BehaviorClass> = OpsFrom<Class>;
 export type StateSliceOf<Class extends BehaviorClass> = StateOf<Class>;
+type EntityOf<Class> = Class extends new () => {
+    entity: infer Entity;
+} ? Entity : GameEntity;
 interface Unsatisfied<Missing> {
     'ERROR: a behavior requires operations the entity does not provide': Missing;
 }
@@ -36,6 +40,12 @@ interface DuplicateOperation<Name> {
 interface IncompatibleState<Name> {
     'ERROR: two behaviors declare one state field with incompatible types': Name;
 }
+interface WrongEntity<Class> {
+    'ERROR: a behavior attaches to an entity of another class': Class;
+}
+type ValidateEntity<Behaviors extends readonly BehaviorClass[], Entity> = {
+    [Index in keyof Behaviors]: Entity extends EntityOf<Behaviors[Index]> ? Behaviors[Index] : WrongEntity<Behaviors[Index]>;
+};
 type ValidateRequires<Behaviors extends readonly BehaviorClass[]> = {
     [Index in keyof Behaviors]: OpsFor<Behaviors> extends RequiresOf<Behaviors[Index]> ? Behaviors[Index] : Unsatisfied<Exclude<keyof RequiresOf<Behaviors[Index]>, keyof OpsFor<Behaviors>>>;
 };
@@ -44,13 +54,17 @@ type IncompatibleKeys<First, Second> = {
     [Key in keyof First & keyof Second]: [First[Key]] extends [Second[Key]] ? [Second[Key]] extends [First[Key]] ? never : Key : Key;
 }[keyof First & keyof Second];
 type IncompatibleStateKeys<Behaviors extends readonly unknown[], SeenState extends object = object> = Behaviors extends readonly [infer Head, ...infer Tail] ? IncompatibleKeys<SeenState, StateOf<Head>> | IncompatibleStateKeys<Tail, SeenState & StateOf<Head>> : never;
-export type ValidTuple<Behaviors extends readonly BehaviorClass[]> = [DuplicateNames<Behaviors>] extends [never] ? [IncompatibleStateKeys<Behaviors>] extends [never] ? Behaviors extends ValidateRequires<Behaviors> ? Behaviors : ValidateRequires<Behaviors> : readonly IncompatibleState<IncompatibleStateKeys<Behaviors>>[] : readonly DuplicateOperation<DuplicateNames<Behaviors>>[];
+export type ValidTuple<Behaviors extends readonly BehaviorClass[], Entity = GameEntity> = [DuplicateNames<Behaviors>] extends [never] ? [IncompatibleStateKeys<Behaviors>] extends [never] ? Behaviors extends ValidateRequires<Behaviors> ? Behaviors extends ValidateEntity<Behaviors, Entity> ? Behaviors : ValidateEntity<Behaviors, Entity> : ValidateRequires<Behaviors> : readonly IncompatibleState<IncompatibleStateKeys<Behaviors>>[] : readonly DuplicateOperation<DuplicateNames<Behaviors>>[];
 export interface GameEntityType {
     readonly behaviors: readonly BehaviorClass[];
     readonly prototype: GameEntity;
 }
+export interface GameEntityClass<Context extends GameSimulationContext = GameSimulationContext> extends GameEntityType {
+    readonly create: (id: string, context: Context, state?: object, name?: string) => GameEntity;
+    readonly restore: (id: string, context: Context, state: GameEntityState, name?: string) => GameEntity;
+}
 export type ComposedOf<Type extends GameEntityType> = Type['prototype'] & {
-    readonly state: StateFor<Type['behaviors']>;
+    readonly state: DeepReadonly<StateFor<Type['behaviors']>>;
     readonly ops: OpsFor<Type['behaviors']>;
 };
 export type NarrowedTo<Class extends BehaviorClass> = GameEntity & {
@@ -65,13 +79,12 @@ export declare abstract class GameEntity implements Subscriber {
     protected readonly context: GameSimulationContext;
     readonly state: object;
     readonly ops: object;
-    readonly eventSubscriptions: readonly EventSubscription[];
     static readonly behaviors: readonly BehaviorClass[];
     static create<Type extends GameEntityType>(this: Type & {
-        behaviors: ValidTuple<Type['behaviors']>;
+        behaviors: ValidTuple<Type['behaviors'], Type['prototype']>;
     }, id: string, context: GameSimulationContext, state?: Partial<StateFor<Type['behaviors']>>, name?: string): ComposedOf<Type>;
     static restore<Type extends GameEntityType>(this: Type & {
-        behaviors: ValidTuple<Type['behaviors']>;
+        behaviors: ValidTuple<Type['behaviors'], Type['prototype']>;
     }, id: string, context: GameSimulationContext, state: StateFor<Type['behaviors']>, name?: string): ComposedOf<Type>;
     protected constructor(id: string, context: GameSimulationContext, providedState: object, runCreateHooks: boolean, name?: string);
     hasBehavior<Class extends BehaviorClass>(behaviorClass: Class): this is NarrowedTo<Class>;
@@ -80,6 +93,9 @@ export declare abstract class GameEntity implements Subscriber {
     update(dt: number): void;
     receive(event: GameEvent): boolean;
     destroy(): void;
+    protected declareComputedState(suppliedState: object): void;
+    protected computed<OwnState extends object, Field extends keyof OwnState & string>(field: Field, computation: Computation<OwnState[Field]>): void;
+    protected removeComputedState(): void;
     protected attachedBehaviors(): readonly BehaviorInstance[];
 }
 export {};

package/dist/index.d.ts

@@ -1,17 +1,19 @@
 export interface EventMap {
 }
-export type { Action, AnalogAction, DigitalAction } from "./action.d.ts";
-export { Behavior } from "./behavior.d.ts";
-export type { BehaviorClass } from "./behavior.d.ts";
-export { NamedBehavior } from "./namedBehavior.d.ts";
-export type { NamedState } from "./namedBehavior.d.ts";
-export { defineStates, StateMachineBehavior } from "./stateMachineBehavior.d.ts";
-export type { StateDefinition } from "./stateMachineBehavior.d.ts";
-export { dilationLimit, drainPassLimit, operationCallDepthLimit } from "./constants.d.ts";
-export type { EventSubscription, GameEvent, Subscriber, Unsubscribe } from "./events.d.ts";
-export { EventBus } from "./eventBus.d.ts";
-export { GameEntity } from "./gameEntity.d.ts";
-export type { ComposedOf, DeepReadonly, GameEntityState, GameEntityType, NarrowedTo, OpsFor, OpsOf, StateBag, StateFor, StateSliceOf, StateValue, ValidTuple, } from "./gameEntity.d.ts";
-export { GameSimulationManager } from "./simulation.d.ts";
-export type { GameEntitySnapshot, IDAllocator, GameSimulationOptions, GameSimulationSnapshot, } from "./simulation.d.ts";
-export type { GameSimulationContext } from "./simulationContext.d.ts";
+export type { Action, AnalogAction, DigitalAction } from "./action.js";
+export { Behavior } from "./behavior.js";
+export type { BehaviorClass } from "./behavior.js";
+export type { Computation } from "./computedState.js";
+export { NamedBehavior } from "./namedBehavior.js";
+export type { NamedState } from "./namedBehavior.js";
+export { defineStates, StateMachineBehavior } from "./stateMachineBehavior.js";
+export type { StateDefinition } from "./stateMachineBehavior.js";
+export { dilationLimit, drainPassLimit, operationCallDepthLimit } from "./constants.js";
+export type { EventSubscription, EventsMatching, GameEvent, Subscriber, Unsubscribe } from "./events.js";
+export { EventBus } from "./eventBus.js";
+export type { EventCallback } from "./eventBus.js";
+export { GameEntity } from "./gameEntity.js";
+export type { ComposedOf, DeepReadonly, GameEntityClass, GameEntityState, GameEntityType, NarrowedTo, OpsFor, OpsOf, StateBag, StateFor, StateSliceOf, StateValue, ValidTuple, } from "./gameEntity.js";
+export { GameSimulationManager } from "./simulation.js";
+export type { GameEntityRegistry, GameEntitySnapshot, IDAllocator, GameSimulationOptions, GameSimulationSnapshot, ValidEntityRegistry, } from "./simulation.js";
+export type { GameSimulationContext } from "./simulationContext.js";

package/dist/namedBehavior.d.ts

@@ -1,4 +1,4 @@
-import { Behavior } from "./behavior.d.ts";
+import { Behavior } from "./behavior.js";
 export interface NamedState {
     displayName: string;
 }