@jgengine/core 0.1.0 → 0.2.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

@@ -41,6 +41,12 @@ export interface GameCameraConfig {
     dragTargetSmoothing?: number;
     distanceSmoothing?: number;
 }
+export interface EntitySpriteConfig {
+    url: string;
+    width: number;
+    height: number;
+    y: number;
+}
 export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown> {
     game: GameDefinition;
     content: GameContextContent;
@@ -48,6 +54,8 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown> {
     GameUI: TUi;
     /** Optional canvas-layer VFX component (e.g. traveling projectiles). */
     WorldOverlay?: TWorldOverlay;
+    /** Billboard sprites keyed by entity kind name; unmatched entities get primitive markers. */
+    entitySprites?: Record<string, EntitySpriteConfig>;
     /** Optional scroll-selected hotbar index for primary ability (mouse0). */
     hotbarSelection?: () => number;
     /** Third-person orbit camera tuning for the dev game player shell. */

package/dist/input/actionBindings.d.ts

@@ -30,6 +30,12 @@ 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;
+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,78 @@ 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 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

@@ -17,7 +17,7 @@ import { type ItemUseHandler, type ItemUseInput, type ItemUseRejection, type Ite
 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";
@@ -29,7 +29,7 @@ export interface GameContextItemEntry {
     trade?: TradeField;
 }
 export interface GameContextEntityEntry {
-    stats?: PoolStatCatalog;
+    stats?: StatCatalog;
     receive?: ReceiveMap;
     onDeath?: OnDeathSpec;
     movement?: PoseAllowedStates & {

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";
@@ -166,7 +166,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 +226,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) {

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.0",
+  "version": "0.2.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",