@jgengine/core 0.3.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

@@ -15,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;
@@ -41,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;
@@ -48,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;
@@ -57,10 +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;
     /** 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 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/runtime/gameContext.d.ts

@@ -63,6 +63,13 @@ export interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAsset
 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;
@@ -70,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;

package/dist/runtime/gameContext.js

@@ -280,11 +280,67 @@ 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,
@@ -300,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.3.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": {