@jgengine/core 0.2.0 → 0.4.0

package/dist/combat/projectiles.d.ts

@@ -13,12 +13,20 @@ export interface RaycastHit {
     at: EntityPosition;
 }
 export type Raycast = (from: string, aim: Aim, range: number) => RaycastHit[];
+export interface ProjectileSettleReport {
+    from: string;
+    origin: EntityPosition;
+    at: EntityPosition;
+    effect: string;
+    hit: boolean;
+}
 export interface ProjectileSystemDeps {
     effects: EffectSystem;
     spatial: CombatSpatialDeps;
     getStat(itemId: string, stat: string): number | null;
     raycast?: Raycast;
     now?: () => number;
+    onSettle?(report: ProjectileSettleReport): void;
 }
 export interface ProjectilePrediction {
     hits: {

package/dist/combat/projectiles.js

@@ -132,8 +132,11 @@ export function createProjectileSystem(deps) {
                 return { status: "rejected", shotId, reason: "already-settled" };
             shot.settled = true;
             const { input } = shot;
+            const origin = shotOrigin(input.from, input.aim) ?? [0, 0, 0];
             if (isBallistic(input.via)) {
-                return { status: "settled", shotId, at: ballisticSettlePoint(input), hits: [] };
+                const at = ballisticSettlePoint(input);
+                deps.onSettle?.({ from: input.from, origin, at, effect: input.effect, hit: false });
+                return { status: "settled", shotId, at, hits: [] };
             }
             const { visible } = predictHits(input);
             const receivable = visible.filter((hit) => deps.effects.canReceive(hit.instanceId, input.effect) === null);
@@ -150,7 +153,9 @@ export function createProjectileSystem(deps) {
                     }));
                 }
             }
-            return { status: "settled", shotId, at: settledAt(input, receivable), hits };
+            const at = settledAt(input, receivable);
+            deps.onSettle?.({ from: input.from, origin, at, effect: input.effect, hit: receivable.length > 0 });
+            return { status: "settled", shotId, at, hits };
         },
     };
 }

package/dist/game/events.d.ts

@@ -66,8 +66,23 @@ export interface StatLevelUpEvent {
     stat: string;
     level: number;
 }
+export interface EntityFloatTextEvent {
+    instanceId?: string;
+    position: [number, number, number];
+    text: string;
+    kind: string;
+    amount?: number;
+}
+export interface ProjectileSettledEvent {
+    from: string;
+    origin: [number, number, number];
+    at: [number, number, number];
+    effect: string;
+    hit: boolean;
+}
 export interface GameEventMap {
     "entity.died": EntityDiedEvent;
+    "entity.floatText": EntityFloatTextEvent;
     "loot.granted": LootGrantedEvent;
     "inventory.added": InventoryAddedEvent;
     "quest.accepted": QuestAcceptedEvent;
@@ -77,6 +92,7 @@ export interface GameEventMap {
     "social.party.joined": SocialPartyJoinedEvent;
     "social.party.left": SocialPartyLeftEvent;
     "stat.levelUp": StatLevelUpEvent;
+    "projectile.settled": ProjectileSettledEvent;
 }
 export type GameEventHandler<TPayload> = (payload: TPayload) => void;
 export interface GameEvents<TMap extends GameEventMap = GameEventMap> {

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 {
@@ -14,7 +15,23 @@ export interface CameraFollowState {
     };
     distance: number;
 }
+export interface FirstPersonCameraConfig {
+    /** Camera height above the followed entity's origin. Default 1.6. */
+    eyeHeight?: number;
+    /** Mouse-look radians per pixel of pointer movement. Default 0.0025. */
+    sensitivity?: number;
+    /** Clamp on look pitch in radians (± from horizon). Default 1.45. */
+    maxPitch?: number;
+    /** Show the centered crosshair overlay. Default true. */
+    reticle?: boolean;
+    /** Render a simple first-person weapon in view. Default true. */
+    viewmodel?: boolean;
+}
 export interface GameCameraConfig {
+    /** "third" mounts the orbit camera (default); "first" mounts pointer-lock mouse-look. */
+    perspective?: "third" | "first";
+    /** First-person tuning; only read when perspective is "first". */
+    firstPerson?: FirstPersonCameraConfig;
     minDistance?: number;
     maxDistance?: number;
     targetHeight?: number;
@@ -40,6 +57,9 @@ export interface GameCameraConfig {
     targetSmoothing?: number;
     dragTargetSmoothing?: number;
     distanceSmoothing?: number;
+    /** Vertical look clamp (three.js polar angle, radians): 0 = top-down over the head, PI/2 = level, >PI/2 = look up from below. Widen for top-down or vertical aim; unset keeps the standard chase feel. */
+    minPolarAngle?: number;
+    maxPolarAngle?: number;
 }
 export interface EntitySpriteConfig {
     url: string;
@@ -47,6 +67,11 @@ export interface EntitySpriteConfig {
     height: number;
     y: number;
 }
+export interface ModelConfig {
+    url: string;
+    scale?: number;
+    y?: number;
+}
 export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown> {
     game: GameDefinition;
     content: GameContextContent;
@@ -56,8 +81,18 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown> {
     WorldOverlay?: TWorldOverlay;
     /** Billboard sprites keyed by entity kind name; unmatched entities get primitive markers. */
     entitySprites?: Record<string, EntitySpriteConfig>;
+    /** GLB models keyed by entity kind name; a string resolves as an asset-catalog key via game.assets, a ModelConfig renders directly. Takes priority over sprites, then primitives. */
+    entityModels?: Record<string, string | ModelConfig>;
+    /** GLB models keyed by object catalog id; a string resolves via game.assets, a ModelConfig renders directly. Replaces the colored box when present. */
+    objectModels?: Record<string, string | ModelConfig>;
     /** Optional scroll-selected hotbar index for primary ability (mouse0). */
     hotbarSelection?: () => number;
-    /** Third-person orbit camera tuning for the dev game player shell. */
+    /** Positioned proximity prompts for the interact key + HUD; single source shared with useActivePrompt. */
+    prompts?: (ctx: GameContext) => readonly PositionedPrompt[];
+    /** Camera tuning (perspective, orbit, first-person) for the dev game player shell. */
     camera?: GameCameraConfig;
+    /** Opt in to world-space health bars floating over non-local entities that carry the stat. */
+    worldHealthBars?: boolean | {
+        statId?: string;
+    };
 }

package/dist/input/actionBindings.d.ts

@@ -33,6 +33,16 @@ export declare function toActionStateBindingMap<TAction extends string, TCode ex
 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;

package/dist/input/actionBindings.js

@@ -67,6 +67,29 @@ export function hotbarSlotBindings(count, options) {
     }
     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",

package/dist/runtime/gameContext.d.ts

@@ -12,7 +12,8 @@ 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";
@@ -28,6 +29,7 @@ export interface GameContextItemEntry {
     weapon?: Record<string, unknown>;
     trade?: TradeField;
 }
+export type CatalogEntityRole = "player" | "enemy" | "hostile" | "npc" | "vehicle";
 export interface GameContextEntityEntry {
     stats?: StatCatalog;
     receive?: ReceiveMap;
@@ -35,11 +37,19 @@ export interface GameContextEntityEntry {
     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,16 @@ export interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAsset
     };
     now?: () => number;
 }
+export interface SceneObjectContext extends ObjectStore {
+    catalog(instanceId: string): GameContextObjectEntry | null;
+}
+export interface FloatTextInput {
+    instanceId?: string;
+    position?: [number, number, number];
+    text?: string;
+    kind?: string;
+    amount?: number;
+}
 export interface SceneEntityContext {
     spawn(name: string, options?: SpawnOptions): string;
     despawn(instanceId: string): boolean;
@@ -57,6 +77,7 @@ export interface SceneEntityContext {
     get(instanceId: string): SceneEntity | null;
     list(): readonly SceneEntity[];
     stats: EntityStatsApi;
+    floatText(input: FloatTextInput): void;
     setTarget(fromId: string, toId: string | null): void;
     getTarget(fromId: string): string | null;
     cycleTarget(fromId: string, options?: CycleTargetOptions): string | null;
@@ -102,7 +123,7 @@ export interface GameContextItemUse {
 }
 export interface GameContext {
     scene: {
-        object: ObjectStore;
+        object: SceneObjectContext;
         entity: SceneEntityContext;
     };
     game: {

package/dist/runtime/gameContext.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),
@@ -276,15 +280,75 @@ export function createGameContext(options) {
             }
         },
     }), ["applyEffect"], signal.notify);
+    function emitFloatText(input) {
+        const position = input.position ??
+            (input.instanceId === undefined ? undefined : entities.get(input.instanceId)?.position);
+        if (position === undefined)
+            return;
+        const text = input.text ?? (input.amount === undefined ? "" : String(Math.round(input.amount)));
+        const event = {
+            position: [position[0], position[1], position[2]],
+            text,
+            kind: input.kind ?? "info",
+        };
+        if (input.instanceId !== undefined)
+            event.instanceId = input.instanceId;
+        if (input.amount !== undefined)
+            event.amount = input.amount;
+        events.emit("entity.floatText", event);
+    }
+    function applyEffectAndFloat(input) {
+        const positionsBefore = new Map();
+        for (const entity of entities.list())
+            positionsBefore.set(entity.id, entity.position);
+        const results = effects.applyEffect(input);
+        for (const result of results) {
+            let total = 0;
+            for (const delta of result.applied)
+                total += delta.delta;
+            if (total === 0)
+                continue;
+            const position = entities.get(result.instanceId)?.position ?? positionsBefore.get(result.instanceId);
+            if (position === undefined)
+                continue;
+            const magnitude = Math.abs(total);
+            emitFloatText({
+                instanceId: result.instanceId,
+                position: [position[0], position[1], position[2]],
+                text: String(Math.round(magnitude)),
+                kind: total < 0 ? "damage" : "heal",
+                amount: magnitude,
+            });
+        }
+        return results;
+    }
+    const floatingEffects = {
+        canReceive: effects.canReceive,
+        preview: effects.preview,
+        applyEffect: applyEffectAndFloat,
+    };
     const projectiles = notifyAfter(createProjectileSystem({
-        effects,
+        effects: floatingEffects,
         spatial: combatSpatial,
         getStat: weapon.getStat,
         now,
+        onSettle(report) {
+            events.emit("projectile.settled", {
+                from: report.from,
+                origin: [report.origin[0], report.origin[1], report.origin[2]],
+                at: [report.at[0], report.at[1], report.at[2]],
+                effect: report.effect,
+                hit: report.hit,
+            });
+        },
     }), ["fireProjectile", "settleProjectile"], signal.notify);
+    const sceneObjects = {
+        ...objects,
+        catalog: (instanceId) => catalogObject(instanceId) ?? null,
+    };
     const ctx = {
         scene: {
-            object: objects,
+            object: sceneObjects,
             entity: {
                 spawn: spawnEntity,
                 despawn: despawnEntity,
@@ -292,12 +356,13 @@ export function createGameContext(options) {
                 get: entities.get,
                 list: entities.list,
                 stats: entityStats,
+                floatText: emitFloatText,
                 setTarget: targeting.setTarget,
                 getTarget: targeting.getTarget,
                 cycleTarget: targeting.cycleTarget,
                 canReceive: effects.canReceive,
                 preview: effects.preview,
-                effect: effects.applyEffect,
+                effect: applyEffectAndFloat,
                 willHitProjectile: projectiles.willHitProjectile,
                 fireProjectile: projectiles.fireProjectile,
                 settleProjectile: projectiles.settleProjectile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -22,8 +22,8 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && bun ../../scripts/fix-extensions.ts dist",
-    "check-types": "tsc --noEmit -p tsconfig.json",
+    "build": "tsgo -p tsconfig.build.json && bun ../../scripts/fix-extensions.ts dist",
+    "check-types": "tsgo --noEmit -p tsconfig.json",
     "test": "bun test src"
   },
   "publishConfig": {