@sharpee/world-model 0.9.66-beta → 0.9.69-beta

package/entities/entity-store.d.ts

@@ -0,0 +1,66 @@
+import { IFEntity } from './if-entity';
+/**
+ * Entity store that works with IFEntity instances.
+ * Provides trait-aware entity management.
+ */
+export declare class EntityStore {
+    private ifEntities;
+    constructor();
+    /**
+     * Add an IF entity to the store
+     */
+    add(entity: IFEntity): void;
+    /**
+     * Get an IF entity by ID
+     */
+    get(id: string): IFEntity | undefined;
+    /**
+     * Check if an entity exists
+     */
+    has(id: string): boolean;
+    /**
+     * Remove an entity from the store
+     */
+    remove(id: string): boolean;
+    /**
+     * Get all entities
+     */
+    getAll(): IFEntity[];
+    /**
+     * Get entities by type
+     */
+    getByType(type: string): IFEntity[];
+    /**
+     * Find entities with a specific trait
+     */
+    findWithTrait(traitType: string): IFEntity[];
+    /**
+     * Find entities with all specified traits
+     */
+    findWithAllTraits(...traitTypes: string[]): IFEntity[];
+    /**
+     * Find entities with any of the specified traits
+     */
+    findWithAnyTraits(...traitTypes: string[]): IFEntity[];
+    /**
+     * Clear all entities from the store
+     */
+    clear(): void;
+    /**
+     * Get the number of entities in the store
+     */
+    get size(): number;
+    /**
+     * Iterate over all entities
+     */
+    [Symbol.iterator](): Iterator<IFEntity>;
+    /**
+     * Serialize all entities to JSON
+     */
+    toJSON(): any[];
+    /**
+     * Load entities from JSON data
+     */
+    static fromJSON(json: any[]): EntityStore;
+}
+//# sourceMappingURL=entity-store.d.ts.map

package/entities/entity-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-store.d.ts","sourceRoot":"","sources":["../../../../../../mnt/c/repotemp/sharpee/packages/world-model/src/entities/entity-store.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,UAAU,CAAwB;;IAM1C;;OAEG;IACH,GAAG,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI;IAI3B;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAIrC;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAQ3B;;OAEG;IACH,MAAM,IAAI,QAAQ,EAAE;IAIpB;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE;IAInC;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,EAAE;IAI5C;;OAEG;IACH,iBAAiB,CAAC,GAAG,UAAU,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE;IAItD;;OAEG;IACH,iBAAiB,CAAC,GAAG,UAAU,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE;IAItD;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC;IAIvC;;OAEG;IACH,MAAM,IAAI,GAAG,EAAE;IAIf;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,WAAW;CAY1C"}

package/entities/entity-store.js

@@ -0,0 +1,116 @@
+"use strict";
+// packages/world-model/src/entities/entity-store.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityStore = void 0;
+const if_entity_1 = require("./if-entity");
+/**
+ * Entity store that works with IFEntity instances.
+ * Provides trait-aware entity management.
+ */
+class EntityStore {
+    ifEntities;
+    constructor() {
+        this.ifEntities = new Map();
+    }
+    /**
+     * Add an IF entity to the store
+     */
+    add(entity) {
+        this.ifEntities.set(entity.id, entity);
+    }
+    /**
+     * Get an IF entity by ID
+     */
+    get(id) {
+        return this.ifEntities.get(id);
+    }
+    /**
+     * Check if an entity exists
+     */
+    has(id) {
+        return this.ifEntities.has(id);
+    }
+    /**
+     * Remove an entity from the store
+     */
+    remove(id) {
+        const entity = this.ifEntities.get(id);
+        if (entity) {
+            entity.clearTraits(); // Cleanup traits before removal
+        }
+        return this.ifEntities.delete(id);
+    }
+    /**
+     * Get all entities
+     */
+    getAll() {
+        return Array.from(this.ifEntities.values());
+    }
+    /**
+     * Get entities by type
+     */
+    getByType(type) {
+        return this.getAll().filter(entity => entity.type === type);
+    }
+    /**
+     * Find entities with a specific trait
+     */
+    findWithTrait(traitType) {
+        return this.getAll().filter(entity => entity.has(traitType));
+    }
+    /**
+     * Find entities with all specified traits
+     */
+    findWithAllTraits(...traitTypes) {
+        return this.getAll().filter(entity => entity.hasAll(...traitTypes));
+    }
+    /**
+     * Find entities with any of the specified traits
+     */
+    findWithAnyTraits(...traitTypes) {
+        return this.getAll().filter(entity => entity.hasAny(...traitTypes));
+    }
+    /**
+     * Clear all entities from the store
+     */
+    clear() {
+        // Cleanup all entities
+        for (const entity of this.ifEntities.values()) {
+            entity.clearTraits();
+        }
+        this.ifEntities.clear();
+    }
+    /**
+     * Get the number of entities in the store
+     */
+    get size() {
+        return this.ifEntities.size;
+    }
+    /**
+     * Iterate over all entities
+     */
+    [Symbol.iterator]() {
+        return this.ifEntities.values();
+    }
+    /**
+     * Serialize all entities to JSON
+     */
+    toJSON() {
+        return this.getAll().map(entity => entity.toJSON());
+    }
+    /**
+     * Load entities from JSON data
+     */
+    static fromJSON(json) {
+        const store = new EntityStore();
+        if (Array.isArray(json)) {
+            for (const entityData of json) {
+                const entity = if_entity_1.IFEntity.fromJSON(entityData);
+                store.add(entity);
+            }
+        }
+        return store;
+    }
+}
+exports.EntityStore = EntityStore;
+//# sourceMappingURL=entity-store.js.map

package/entities/entity-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-store.js","sourceRoot":"","sources":["../../../../../../../../../mnt/c/repotemp/sharpee/packages/world-model/src/entities/entity-store.ts"],"names":[],"mappings":"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"}

package/entities/entity-types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Standard Interactive Fiction entity types
+ *
+ * These represent the fundamental object types in IF games.
+ * The values match the type strings used throughout the system.
+ */
+export declare const EntityType: {
+    /** A location in the game world */
+    readonly ROOM: "room";
+    /** A doorway or portal between rooms */
+    readonly DOOR: "door";
+    /** A generic takeable object */
+    readonly ITEM: "item";
+    /** A character (NPC or player) */
+    readonly ACTOR: "actor";
+    /** An object that can contain other objects */
+    readonly CONTAINER: "container";
+    /** An object that can support other objects on top */
+    readonly SUPPORTER: "supporter";
+    /** Fixed decorative objects that can't be taken */
+    readonly SCENERY: "scenery";
+    /** A directional exit (rarely used as entity) */
+    readonly EXIT: "exit";
+    /** Generic object type (default) */
+    readonly OBJECT: "object";
+};
+/**
+ * Type representing valid entity types
+ */
+export type EntityType = typeof EntityType[keyof typeof EntityType];
+/**
+ * Type guard to check if a string is a valid IF entity type
+ */
+export declare function isEntityType(type: string): type is EntityType;
+/**
+ * Get the ID prefix for an entity type
+ * Used for generating consistent entity IDs
+ */
+export declare function getEntityTypePrefix(type: EntityType): string;
+//# sourceMappingURL=entity-types.d.ts.map

package/entities/entity-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-types.d.ts","sourceRoot":"","sources":["../../../../../../mnt/c/repotemp/sharpee/packages/world-model/src/entities/entity-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,UAAU;IACrB,mCAAmC;;IAGnC,wCAAwC;;IAGxC,gCAAgC;;IAGhC,kCAAkC;;IAGlC,+CAA+C;;IAG/C,sDAAsD;;IAGtD,mDAAmD;;IAGnD,iDAAiD;;IAGjD,oCAAoC;;CAE5B,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAEpE;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,UAAU,CAE7D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAc5D"}

package/entities/entity-types.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityType = void 0;
+exports.isEntityType = isEntityType;
+exports.getEntityTypePrefix = getEntityTypePrefix;
+/**
+ * Standard Interactive Fiction entity types
+ *
+ * These represent the fundamental object types in IF games.
+ * The values match the type strings used throughout the system.
+ */
+exports.EntityType = {
+    /** A location in the game world */
+    ROOM: 'room',
+    /** A doorway or portal between rooms */
+    DOOR: 'door',
+    /** A generic takeable object */
+    ITEM: 'item',
+    /** A character (NPC or player) */
+    ACTOR: 'actor',
+    /** An object that can contain other objects */
+    CONTAINER: 'container',
+    /** An object that can support other objects on top */
+    SUPPORTER: 'supporter',
+    /** Fixed decorative objects that can't be taken */
+    SCENERY: 'scenery',
+    /** A directional exit (rarely used as entity) */
+    EXIT: 'exit',
+    /** Generic object type (default) */
+    OBJECT: 'object'
+};
+/**
+ * Type guard to check if a string is a valid IF entity type
+ */
+function isEntityType(type) {
+    return Object.values(exports.EntityType).includes(type);
+}
+/**
+ * Get the ID prefix for an entity type
+ * Used for generating consistent entity IDs
+ */
+function getEntityTypePrefix(type) {
+    const prefixMap = {
+        [exports.EntityType.ROOM]: 'r',
+        [exports.EntityType.DOOR]: 'd',
+        [exports.EntityType.ITEM]: 'i',
+        [exports.EntityType.ACTOR]: 'a',
+        [exports.EntityType.CONTAINER]: 'c',
+        [exports.EntityType.SUPPORTER]: 's',
+        [exports.EntityType.SCENERY]: 'y',
+        [exports.EntityType.EXIT]: 'e',
+        [exports.EntityType.OBJECT]: 'o'
+    };
+    return prefixMap[type] || 'o';
+}
+//# sourceMappingURL=entity-types.js.map

package/entities/entity-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-types.js","sourceRoot":"","sources":["../../../../../../../../../mnt/c/repotemp/sharpee/packages/world-model/src/entities/entity-types.ts"],"names":[],"mappings":";;;AA2CA,oCAEC;AAMD,kDAcC;AAjED;;;;;GAKG;AACU,QAAA,UAAU,GAAG;IACxB,mCAAmC;IACnC,IAAI,EAAE,MAAM;IAEZ,wCAAwC;IACxC,IAAI,EAAE,MAAM;IAEZ,gCAAgC;IAChC,IAAI,EAAE,MAAM;IAEZ,kCAAkC;IAClC,KAAK,EAAE,OAAO;IAEd,+CAA+C;IAC/C,SAAS,EAAE,WAAW;IAEtB,sDAAsD;IACtD,SAAS,EAAE,WAAW;IAEtB,mDAAmD;IACnD,OAAO,EAAE,SAAS;IAElB,iDAAiD;IACjD,IAAI,EAAE,MAAM;IAEZ,oCAAoC;IACpC,MAAM,EAAE,QAAQ;CACR,CAAC;AAOX;;GAEG;AACH,SAAgB,YAAY,CAAC,IAAY;IACvC,OAAO,MAAM,CAAC,MAAM,CAAC,kBAAU,CAAC,CAAC,QAAQ,CAAC,IAAkB,CAAC,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,IAAgB;IAClD,MAAM,SAAS,GAA+B;QAC5C,CAAC,kBAAU,CAAC,IAAI,CAAC,EAAE,GAAG;QACtB,CAAC,kBAAU,CAAC,IAAI,CAAC,EAAE,GAAG;QACtB,CAAC,kBAAU,CAAC,IAAI,CAAC,EAAE,GAAG;QACtB,CAAC,kBAAU,CAAC,KAAK,CAAC,EAAE,GAAG;QACvB,CAAC,kBAAU,CAAC,SAAS,CAAC,EAAE,GAAG;QAC3B,CAAC,kBAAU,CAAC,SAAS,CAAC,EAAE,GAAG;QAC3B,CAAC,kBAAU,CAAC,OAAO,CAAC,EAAE,GAAG;QACzB,CAAC,kBAAU,CAAC,IAAI,CAAC,EAAE,GAAG;QACtB,CAAC,kBAAU,CAAC,MAAM,CAAC,EAAE,GAAG;KACzB,CAAC;IAEF,OAAO,SAAS,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC;AAChC,CAAC"}

package/entities/if-entity.d.ts

@@ -0,0 +1,314 @@
+import { IEntity, EntityId, IEntityCreationParams } from "../src/index";
+import { ITrait, ITraitConstructor } from '../traits/trait';
+import { TraitType } from '../traits/trait-types';
+import { IEventHandlers } from '../events/types';
+import { Annotation, AnnotationCondition } from '../annotations/types';
+/**
+ * Interactive Fiction Entity with trait-based composition.
+ * Implements the core Entity interface and adds trait management capabilities.
+ */
+export declare class IFEntity implements IEntity {
+    readonly id: EntityId;
+    readonly type: string;
+    attributes: Record<string, unknown>;
+    relationships: Record<string, EntityId[]>;
+    traits: Map<TraitType, ITrait>;
+    /**
+     * Author-controlled disambiguation priorities per action
+     * Higher priority = more likely to be selected when ambiguous
+     * Key is action ID (e.g., 'if.action.eating')
+     * Value is priority (default 100, higher = preferred)
+     */
+    private scopePriorities;
+    /**
+     * Author-controlled minimum scope levels
+     * Allows entities to be "in scope" regardless of spatial location.
+     * Key is room ID (or '*' for all rooms)
+     * Value is minimum scope level (0=UNAWARE, 1=AWARE, 2=VISIBLE, 3=REACHABLE, 4=CARRIED)
+     *
+     * Example uses:
+     * - sky.setMinimumScope(2) - always visible everywhere
+     * - mountain.setMinimumScope(2, ['overlook']) - visible from specific room
+     * - butterfly.setMinimumScope(3, ['garden']) - reachable in garden
+     */
+    private minimumScopes;
+    /**
+     * Presentation metadata annotations (ADR-124).
+     * Keyed by kind (e.g., 'illustration', 'portrait', 'voice').
+     * Multiple annotations per kind are supported.
+     */
+    private annotations;
+    /**
+     * Event handlers for this entity
+     * Key is the event type (e.g., 'if.event.pushed')
+     * Value is the handler function
+     */
+    on?: IEventHandlers;
+    constructor(id: string, type: string, params?: Partial<IEntityCreationParams>);
+    /**
+     * Check if entity has a specific trait
+     */
+    has(type: TraitType | string): boolean;
+    /**
+     * Get a typed trait from the entity
+     */
+    get<T extends ITrait>(type: TraitType | string | ITraitConstructor<T>): T | undefined;
+    /**
+     * Alias for get() method - for backwards compatibility
+     */
+    getTrait<T extends ITrait>(type: TraitType | string | ITraitConstructor<T>): T | undefined;
+    /**
+     * Add a trait to the entity
+     */
+    add(trait: ITrait): this;
+    /**
+     * Remove a trait from the entity
+     */
+    remove(type: TraitType | string): boolean;
+    /**
+     * Check if entity has all specified traits
+     */
+    hasAll(...types: (TraitType | string)[]): boolean;
+    /**
+     * Check if entity has any of the specified traits
+     */
+    hasAny(...types: (TraitType | string)[]): boolean;
+    /**
+     * Get all traits on this entity
+     */
+    getTraits(): ITrait[];
+    /**
+     * Get all trait types on this entity
+     */
+    getTraitTypes(): (TraitType | string)[];
+    /**
+     * Clear all traits from the entity
+     */
+    clearTraits(): void;
+    /**
+     * Get or set author-controlled disambiguation priority for an action.
+     *
+     * When multiple entities match a command, higher priority entities are
+     * preferred for automatic disambiguation.
+     *
+     * @param actionId - The action ID (e.g., 'if.action.eating')
+     * @param priority - Optional priority to set (100 = default, higher = preferred)
+     * @returns The current priority for this action (default 100)
+     *
+     * @example
+     * // Make real apple preferred for eating over wax apple
+     * realApple.scope('if.action.eating', 150);
+     * waxApple.scope('if.action.eating', 50);
+     *
+     * @example
+     * // Get current priority
+     * const priority = apple.scope('if.action.eating');  // Returns 150
+     */
+    scope(actionId: string, priority?: number): number;
+    /**
+     * Clear disambiguation priority for an action (resets to default)
+     */
+    clearScope(actionId: string): void;
+    /**
+     * Clear all disambiguation priorities
+     */
+    clearAllScopes(): void;
+    /**
+     * Get all scope priorities for serialization
+     */
+    getScopePriorities(): Record<string, number>;
+    /**
+     * Set minimum scope level for this entity.
+     *
+     * Makes an entity "in scope" regardless of its spatial location.
+     * The scope resolver will return the maximum of the physical scope
+     * and the minimum scope (additive only - can raise scope, not lower it).
+     *
+     * Scope levels (numeric values match ScopeLevel enum in stdlib):
+     * - 0: UNAWARE - not in scope
+     * - 1: AWARE - can hear/smell but not see
+     * - 2: VISIBLE - can see but not reach
+     * - 3: REACHABLE - can physically interact
+     * - 4: CARRIED - in inventory (rarely used for minimum)
+     *
+     * @param level The minimum scope level (0-4)
+     * @param rooms Optional array of room IDs where this applies. If omitted, applies everywhere.
+     *
+     * @example
+     * // Sky is always visible everywhere
+     * sky.setMinimumScope(2);
+     *
+     * // Mountain visible only from overlook and trail
+     * mountain.setMinimumScope(2, ['overlook', 'mountain_trail']);
+     *
+     * // Butterfly reachable (but may escape) in garden areas
+     * butterfly.setMinimumScope(3, ['garden', 'meadow', 'pond']);
+     *
+     * // Ticking clock audible from adjacent rooms
+     * clock.setMinimumScope(1, ['hallway', 'study']);
+     */
+    setMinimumScope(level: number, rooms?: string[]): this;
+    /**
+     * Get the minimum scope level for this entity in a specific room.
+     *
+     * @param roomId The room to check (or null to get global minimum)
+     * @returns The minimum scope level, or 0 (UNAWARE) if not set
+     */
+    getMinimumScope(roomId: string | null): number;
+    /**
+     * Clear minimum scope for specific rooms or all rooms.
+     *
+     * @param rooms Optional array of room IDs to clear. If omitted, clears all.
+     */
+    clearMinimumScope(rooms?: string[]): void;
+    /**
+     * Get all minimum scopes for serialization
+     */
+    getMinimumScopes(): Record<string, number>;
+    /**
+     * Add a presentation annotation to this entity.
+     *
+     * @param kind - Annotation kind (e.g., 'illustration', 'portrait')
+     * @param data - Kind-specific payload. Must include an `id` field.
+     * @param condition - Optional condition for when this annotation is active
+     *
+     * @example
+     * entity.annotate('illustration', {
+     *   id: 'dam-exterior',
+     *   src: 'dam-dry.jpg',
+     *   alt: 'The massive concrete face of Flood Control Dam #3',
+     *   trigger: 'on-enter',
+     *   position: 'right',
+     * });
+     */
+    annotate(kind: string, data: Record<string, unknown> & {
+        id: string;
+    }, condition?: AnnotationCondition): this;
+    /**
+     * Get all annotations of a given kind (unfiltered).
+     */
+    getAnnotations(kind: string): Annotation[];
+    /**
+     * Get annotations whose conditions are currently met.
+     * Requires a world model reference to resolve trait state on self/player/location.
+     *
+     * @param kind - Annotation kind to query
+     * @param world - World model for condition evaluation (must have getEntity, getPlayer, getLocation)
+     */
+    getActiveAnnotations(kind: string, world: {
+        getEntity(id: string): IFEntity | undefined;
+        getPlayer(): IFEntity | undefined;
+        getLocation(entityId: string): string | undefined;
+    }): Annotation[];
+    /**
+     * Remove a specific annotation by kind and id.
+     * @returns true if the annotation was found and removed
+     */
+    removeAnnotation(kind: string, id: string): boolean;
+    /**
+     * Check if entity has any annotations of a given kind.
+     */
+    hasAnnotations(kind: string): boolean;
+    /**
+     * Evaluate an annotation condition against current world state.
+     */
+    private evaluateCondition;
+    /**
+     * Clone this entity with all its traits
+     */
+    clone(newId: string): IFEntity;
+    /**
+     * Serialize entity and traits to JSON
+     */
+    toJSON(): any;
+    /**
+     * Create entity from JSON data
+     */
+    static fromJSON(json: any): IFEntity;
+    /**
+     * Check if this is a room
+     */
+    get isRoom(): boolean;
+    /**
+     * Check if this can contain other entities
+     */
+    get canContain(): boolean;
+    /**
+     * Check if this is takeable (default behavior unless has scenery trait)
+     */
+    get isTakeable(): boolean;
+    /**
+     * Check if this is fixed in place (has scenery trait)
+     */
+    get isScenery(): boolean;
+    /**
+     * Check if this can be opened
+     */
+    get isOpenable(): boolean;
+    /**
+     * Check if this is currently open
+     */
+    get isOpen(): boolean;
+    /**
+     * Check if this can be locked
+     */
+    get isLockable(): boolean;
+    /**
+     * Check if this is currently locked
+     */
+    get isLocked(): boolean;
+    /**
+     * Check if this is a container
+     */
+    get isContainer(): boolean;
+    /**
+     * Check if this is a supporter
+     */
+    get isSupporter(): boolean;
+    /**
+     * Check if this is a door
+     */
+    get isDoor(): boolean;
+    /**
+     * Check if this is an actor
+     */
+    get isActor(): boolean;
+    /**
+     * Check if this is the player
+     */
+    get isPlayer(): boolean;
+    /**
+     * Check if this provides light
+     */
+    get providesLight(): boolean;
+    /**
+     * Check if this is switchable
+     */
+    get isSwitchable(): boolean;
+    /**
+     * Check if this can be entered by actors
+     * Vehicles are inherently enterable (boats, baskets, etc.)
+     */
+    get enterable(): boolean;
+    /**
+     * Check if this is switched on
+     */
+    get isOn(): boolean;
+    /**
+     * Get the name of this entity
+     */
+    get name(): string;
+    /**
+     * Get the description of this entity
+     */
+    get description(): string | undefined;
+    /**
+     * Get the weight of this entity
+     */
+    get weight(): number;
+    /**
+     * Alias for has() method - for backwards compatibility
+     */
+    hasTrait(type: TraitType | string): boolean;
+}
+//# sourceMappingURL=if-entity.d.ts.map

package/entities/if-entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"if-entity.d.ts","sourceRoot":"","sources":["../../../../../../mnt/c/repotemp/sharpee/packages/world-model/src/entities/if-entity.ts"],"names":[],"mappings":"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"}