@jgengine/core 0.1.1 → 0.3.0

package/dist/combat/effects.d.ts

@@ -1,5 +1,5 @@
 import type { EntityPosition } from "../scene/entityStore.js";
-import { type PoolStatMap } from "../scene/entityStats.js";
+import { type StatValueMap } from "../scene/entityStats.js";
 export interface ReceiveRule {
     order: string[];
     modifiers?: Record<string, number>;
@@ -47,7 +47,7 @@ export interface CombatSpatialDeps {
 }
 export interface EffectSystemDeps {
     resolveReceive(instanceId: string): ReceiveMap | null | undefined;
-    resolveStats(instanceId: string): PoolStatMap | undefined;
+    resolveStats(instanceId: string): StatValueMap | undefined;
     getStat(itemId: string, stat: string): number | null;
     spatial: CombatSpatialDeps;
     drainStatByEffect?: Record<string, string>;

package/dist/game/playableGame.d.ts

@@ -1,3 +1,4 @@
+import type { PositionedPrompt } from "../interaction/proximityPrompt.js";
 import type { GameContext, GameContextContent } from "../runtime/gameContext.js";
 import type { GameDefinition, GameLoop } from "./defineGame.js";
 export interface CameraFollowState {
@@ -58,6 +59,8 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown> {
     entitySprites?: Record<string, EntitySpriteConfig>;
     /** Optional scroll-selected hotbar index for primary ability (mouse0). */
     hotbarSelection?: () => number;
+    /** Positioned proximity prompts for the interact key + HUD; single source shared with useActivePrompt. */
+    prompts?: (ctx: GameContext) => readonly PositionedPrompt[];
     /** Third-person orbit camera tuning for the dev game player shell. */
     camera?: GameCameraConfig;
 }

package/dist/input/actionBindings.d.ts

@@ -30,6 +30,22 @@ export type ActionCodes<TCode extends string = string> = readonly TCode[] | {
 };
 export type ActionCodesMap<TAction extends string = string, TCode extends string = string> = Record<TAction, ActionCodes<TCode>>;
 export declare function toActionStateBindingMap<TAction extends string, TCode extends string>(map: ActionCodesMap<TAction, TCode>): ActionStateBindingMap<TAction, TCode>;
+export declare function hotbarSlotBindings(count: number, options?: {
+    action?: (slot: number) => string;
+}): ActionCodesMap;
+/** 0-based slot index for a hotbar-slot action name (`slot1`, `hotbarSlot1`), or null. */
+export declare function hotbarSlotActionIndex(action: string): number | null;
+export declare function isHotbarSlotAction(action: string): boolean;
+/**
+ * Convention mapping a bound input action to the command it fires: the action's
+ * own name when a command by that name exists, otherwise a `ui.<action>`
+ * fallback. Reserved actions (consumed natively by the shell) and hotbar slots
+ * yield null so the shell can handle them itself.
+ */
+export declare function resolveActionCommand(action: string, has: (command: string) => boolean, reserved: ReadonlySet<string>): string | null;
+export declare function bindingLabel(code: string): string;
+/** Short display label for an action's first bound code, or null when unbound. */
+export declare function actionLabel(map: ActionCodesMap, action: string): string | null;
 export interface ActionStateTracker<TAction extends string> {
     handleDown(code: string): TAction | null;
     handleUp(code: string): TAction | null;

package/dist/input/actionBindings.js

@@ -44,6 +44,101 @@ export function toActionStateBindingMap(map) {
     }
     return result;
 }
+const HOTBAR_DIGIT_CODES = [
+    "Digit1",
+    "Digit2",
+    "Digit3",
+    "Digit4",
+    "Digit5",
+    "Digit6",
+    "Digit7",
+    "Digit8",
+    "Digit9",
+    "Digit0",
+];
+export function hotbarSlotBindings(count, options) {
+    if (!Number.isInteger(count) || count < 1 || count > HOTBAR_DIGIT_CODES.length) {
+        throw new Error(`hotbarSlotBindings: count must be an integer in [1, ${HOTBAR_DIGIT_CODES.length}]`);
+    }
+    const action = options?.action ?? ((slot) => `hotbarSlot${slot}`);
+    const map = {};
+    for (let slot = 1; slot <= count; slot += 1) {
+        map[action(slot)] = [HOTBAR_DIGIT_CODES[slot - 1]];
+    }
+    return map;
+}
+const HOTBAR_SLOT_ACTION = /^(?:hotbar)?slot(\d+)$/i;
+/** 0-based slot index for a hotbar-slot action name (`slot1`, `hotbarSlot1`), or null. */
+export function hotbarSlotActionIndex(action) {
+    const match = HOTBAR_SLOT_ACTION.exec(action);
+    return match === null ? null : Number(match[1]) - 1;
+}
+export function isHotbarSlotAction(action) {
+    return HOTBAR_SLOT_ACTION.test(action);
+}
+/**
+ * Convention mapping a bound input action to the command it fires: the action's
+ * own name when a command by that name exists, otherwise a `ui.<action>`
+ * fallback. Reserved actions (consumed natively by the shell) and hotbar slots
+ * yield null so the shell can handle them itself.
+ */
+export function resolveActionCommand(action, has, reserved) {
+    if (reserved.has(action) || isHotbarSlotAction(action))
+        return null;
+    if (has(action))
+        return action;
+    const uiCommand = `ui.${action}`;
+    return has(uiCommand) ? uiCommand : null;
+}
+const CODE_LABELS = {
+    mouse0: "LMB",
+    mouse1: "MMB",
+    mouse2: "RMB",
+    Space: "Space",
+    space: "Space",
+    Escape: "Esc",
+    Tab: "Tab",
+    Enter: "Enter",
+    Backspace: "Bksp",
+    Shift: "Shift",
+    ShiftLeft: "Shift",
+    ShiftRight: "Shift",
+    Control: "Ctrl",
+    ControlLeft: "Ctrl",
+    ControlRight: "Ctrl",
+    AltLeft: "Alt",
+    AltRight: "Alt",
+    ArrowUp: "↑",
+    ArrowDown: "↓",
+    ArrowLeft: "←",
+    ArrowRight: "→",
+};
+export function bindingLabel(code) {
+    const direct = CODE_LABELS[code];
+    if (direct !== undefined)
+        return direct;
+    if (code.startsWith("Key") && code.length === 4)
+        return code.slice(3);
+    if (code.startsWith("Digit") && code.length === 6)
+        return code.slice(5);
+    return code.length === 1 ? code.toUpperCase() : code;
+}
+/** Short display label for an action's first bound code, or null when unbound. */
+export function actionLabel(map, action) {
+    const codes = map[action];
+    if (codes === undefined)
+        return null;
+    let list;
+    if (Array.isArray(codes)) {
+        list = codes;
+    }
+    else {
+        const modes = codes;
+        list = modes.hold ?? modes.toggle ?? [];
+    }
+    const first = list[0];
+    return first === undefined ? null : bindingLabel(first);
+}
 function resolveActionBindingModes(config) {
     if (Array.isArray(config))
         return { hold: config, toggle: [] };

package/dist/runtime/gameContext.d.ts

@@ -12,12 +12,13 @@ import { type QuestJournal } from "../game/quest.js";
 import { type Social } from "../game/social.js";
 import { type TradeField, type TradeSystem } from "../game/trade.js";
 import { type Unlocks } from "../game/unlocks.js";
-import { type InventorySet } from "../inventory/inventoryModel.js";
+import { type InventoryLayout, type InventorySet } from "../inventory/inventoryModel.js";
+import type { ProximityPrompt } from "../interaction/proximityPrompt.js";
 import { type ItemUseHandler, type ItemUseInput, type ItemUseRejection, type ItemUseResult } from "../item/use.js";
 import { type WeaponStats } from "../item/weapon.js";
 import { type PoseAllowedStates, type PoseState } from "../movement/poseState.js";
 import type { ModelAssetRef } from "../scene/assetCatalog.js";
-import { type EntityStatsApi, type PoolStatCatalog } from "../scene/entityStats.js";
+import { type EntityStatsApi, type StatCatalog } from "../scene/entityStats.js";
 import type { EntityPose, SceneEntity, SpawnOptions } from "../scene/entityStore.js";
 import { type ObjectStore } from "../scene/objectStore.js";
 import { type SpatialApi } from "../scene/spatial.js";
@@ -28,18 +29,27 @@ export interface GameContextItemEntry {
     weapon?: Record<string, unknown>;
     trade?: TradeField;
 }
+export type CatalogEntityRole = "player" | "enemy" | "hostile" | "npc" | "vehicle";
 export interface GameContextEntityEntry {
-    stats?: PoolStatCatalog;
+    stats?: StatCatalog;
     receive?: ReceiveMap;
     onDeath?: OnDeathSpec;
     movement?: PoseAllowedStates & {
         walkSpeed?: number;
     };
-    role?: string;
+    role?: CatalogEntityRole;
+}
+export interface GameContextObjectEntry {
+    proximityPrompt?: ProximityPrompt;
+    breakable?: false | {
+        baseBreakTime: number;
+    };
+    slotInventory?: InventoryLayout;
 }
 export interface GameContextContent {
     itemById?(itemId: string): GameContextItemEntry | null | undefined;
     entityById?(catalogId: string): GameContextEntityEntry | null | undefined;
+    objectById?(catalogId: string): GameContextObjectEntry | null | undefined;
 }
 export interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> {
     definition: GameDefinition<TAssetRef, TMultiplayer>;
@@ -50,6 +60,9 @@ export interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAsset
     };
     now?: () => number;
 }
+export interface SceneObjectContext extends ObjectStore {
+    catalog(instanceId: string): GameContextObjectEntry | null;
+}
 export interface SceneEntityContext {
     spawn(name: string, options?: SpawnOptions): string;
     despawn(instanceId: string): boolean;
@@ -102,7 +115,7 @@ export interface GameContextItemUse {
 }
 export interface GameContext {
     scene: {
-        object: ObjectStore;
+        object: SceneObjectContext;
         entity: SceneEntityContext;
     };
     game: {

package/dist/runtime/gameContext.js

@@ -16,7 +16,7 @@ import { createInventorySet, putItem, } from "../inventory/inventoryModel.js";
 import { createItemUse, } from "../item/use.js";
 import { createWeaponStats } from "../item/weapon.js";
 import { createPoseState } from "../movement/poseState.js";
-import { createEntityStatsApi, seedPoolStats, setPoolStat, } from "../scene/entityStats.js";
+import { createEntityStatsApi, seedStatValues, setStatValue, } from "../scene/entityStats.js";
 import { createObjectStore } from "../scene/objectStore.js";
 import { createSpatialApi } from "../scene/spatial.js";
 import { createTargeting } from "../scene/targeting.js";
@@ -44,6 +44,10 @@ export function createGameContext(options) {
         const entity = entities.get(instanceId);
         return entity === null ? undefined : content.entityById?.(entity.name);
     }
+    function catalogObject(instanceId) {
+        const object = objects.get(instanceId);
+        return object === null ? undefined : content.objectById?.(object.catalogId);
+    }
     const spatial = createSpatialApi({
         resolvePosition: (instanceId) => entities.get(instanceId)?.position,
         candidates: () => entities.list().map((entity) => entity.id),
@@ -166,7 +170,7 @@ export function createGameContext(options) {
     });
     function seedUserPool(userId, statId, pool) {
         const map = ensureInstanceStats(userId);
-        const next = setPoolStat(map, statId, pool);
+        const next = setStatValue(map, statId, pool);
         map[statId] = next[statId];
     }
     const rawQuest = createQuestJournal({
@@ -226,7 +230,7 @@ export function createGameContext(options) {
             : { ...spawnOptions, movement: { ...spawnOptions?.movement, walkSpeed } };
         const instanceId = entities.spawn(name, options);
         death.revive(instanceId);
-        statsByInstance.set(instanceId, entry?.stats === undefined ? {} : seedPoolStats(entry.stats));
+        statsByInstance.set(instanceId, entry?.stats === undefined ? {} : seedStatValues(entry.stats));
         return instanceId;
     }
     function despawnEntity(instanceId) {
@@ -282,9 +286,13 @@ export function createGameContext(options) {
         getStat: weapon.getStat,
         now,
     }), ["fireProjectile", "settleProjectile"], signal.notify);
+    const sceneObjects = {
+        ...objects,
+        catalog: (instanceId) => catalogObject(instanceId) ?? null,
+    };
     const ctx = {
         scene: {
-            object: objects,
+            object: sceneObjects,
             entity: {
                 spawn: spawnEntity,
                 despawn: despawnEntity,

package/dist/scene/entityStats.d.ts

@@ -1,38 +1,38 @@
-export interface PoolStat {
+export interface StatValue {
     current: number;
     max: number;
     min: number;
 }
-export interface PoolStatPatch {
+export interface StatValuePatch {
     current?: number;
     max?: number;
     min?: number;
 }
-export type PoolStatMap = Record<string, PoolStat>;
-export type PoolStatCatalog = Record<string, {
+export type StatValueMap = Record<string, StatValue>;
+export type StatCatalog = Record<string, {
     max: number;
     min?: number;
     current?: number;
 }>;
 export type PoolDeltaResult = {
     status: "ok";
-    map: PoolStatMap;
-    stat: PoolStat;
+    map: StatValueMap;
+    stat: StatValue;
     hitMin: boolean;
     hitMax: boolean;
 } | {
     status: "rejected";
     reason: string;
 };
-export declare function getPoolStat(map: PoolStatMap, statId: string): PoolStat | null;
-export declare function setPoolStat(map: PoolStatMap, statId: string, patch: PoolStatPatch): PoolStatMap;
-export declare function applyPoolDelta(map: PoolStatMap, statId: string, amount: number): PoolDeltaResult;
-export declare function seedPoolStats(catalogStats: PoolStatCatalog): PoolStatMap;
+export declare function getStatValue(map: StatValueMap, statId: string): StatValue | null;
+export declare function setStatValue(map: StatValueMap, statId: string, patch: StatValuePatch): StatValueMap;
+export declare function applyPoolDelta(map: StatValueMap, statId: string, amount: number): PoolDeltaResult;
+export declare function seedStatValues(catalogStats: StatCatalog): StatValueMap;
 export interface EntityStatsApi {
-    get(instanceId: string, statId: string): PoolStat | null;
-    set(instanceId: string, statId: string, patch: PoolStatPatch): boolean;
+    get(instanceId: string, statId: string): StatValue | null;
+    set(instanceId: string, statId: string, patch: StatValuePatch): boolean;
     delta(instanceId: string, statId: string, amount: number): null | {
         reason: string;
     };
 }
-export declare function createEntityStatsApi(resolve: (instanceId: string) => PoolStatMap | undefined): EntityStatsApi;
+export declare function createEntityStatsApi(resolve: (instanceId: string) => StatValueMap | undefined): EntityStatsApi;

package/dist/scene/entityStats.js

@@ -1,10 +1,10 @@
 function clamp(value, min, max) {
     return Math.min(max, Math.max(min, value));
 }
-export function getPoolStat(map, statId) {
+export function getStatValue(map, statId) {
     return map[statId] ?? null;
 }
-export function setPoolStat(map, statId, patch) {
+export function setStatValue(map, statId, patch) {
     const existing = map[statId];
     const max = patch.max ?? existing?.max ?? 0;
     const min = patch.min ?? existing?.min ?? 0;
@@ -26,7 +26,7 @@ export function applyPoolDelta(map, statId, amount) {
         hitMax: current === existing.max,
     };
 }
-export function seedPoolStats(catalogStats) {
+export function seedStatValues(catalogStats) {
     const map = {};
     for (const [statId, declaration] of Object.entries(catalogStats)) {
         const min = declaration.min ?? 0;
@@ -41,13 +41,13 @@ export function createEntityStatsApi(resolve) {
             const map = resolve(instanceId);
             if (map === undefined)
                 return null;
-            return getPoolStat(map, statId);
+            return getStatValue(map, statId);
         },
         set(instanceId, statId, patch) {
             const map = resolve(instanceId);
             if (map === undefined)
                 return false;
-            const next = setPoolStat(map, statId, patch);
+            const next = setStatValue(map, statId, patch);
             map[statId] = next[statId];
             return true;
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Genre-agnostic TypeScript game engine SDK: game runtime, state store, entity scene, combat, movement, inventory, economy, quests, multiplayer primitives.",
   "license": "AGPL-3.0-only",
   "type": "module",