@jgengine/core 0.5.0 → 0.7.0

package/dist/game/race.js

@@ -0,0 +1,216 @@
+/**
+ * A race track is an ordered ring of checkpoint trigger volumes plus a lap count. The final checkpoint
+ * is the lap/finish line: a racer completes a lap by passing all checkpoints in order and hitting the
+ * last one.
+ */
+export function raceTrack(config) {
+    return { checkpoints: config.checkpoints, laps: Math.max(1, Math.floor(config.laps ?? 1)) };
+}
+function rankIds(standings) {
+    return standings.map((s) => s.racerId);
+}
+/** Race ends when `count` racers have crossed the finish; ranking is the current standings order. */
+export function firstPastPost(count = 1) {
+    return (standings) => {
+        const finished = standings.filter((s) => s.finished).length;
+        return finished >= count ? rankIds(standings) : null;
+    };
+}
+/** Round-cut (Fall Guys): the first `k` finishers qualify; race resolves the moment `k` cross. */
+export function topK(k) {
+    return firstPastPost(k);
+}
+/** Every non-eliminated racer must finish. */
+export function everyoneFinishes() {
+    return (standings) => {
+        const active = standings.filter((s) => !s.eliminated);
+        return active.length > 0 && active.every((s) => s.finished) ? rankIds(standings) : null;
+    };
+}
+/** Destruction-derby last-man-standing: ends when at most one racer is left un-eliminated. */
+export function lastStanding() {
+    return (standings) => {
+        const alive = standings.filter((s) => !s.eliminated);
+        return alive.length <= 1 && standings.length > 1 ? rankIds(standings) : null;
+    };
+}
+function insideAabb(point, cp) {
+    return (Math.abs(point[0] - cp.center[0]) <= cp.half[0] &&
+        Math.abs(point[1] - cp.center[1]) <= cp.half[1] &&
+        Math.abs(point[2] - cp.center[2]) <= cp.half[2]);
+}
+function distanceToNext(point, cp) {
+    const dx = point[0] - cp.center[0];
+    const dz = point[2] - cp.center[2];
+    return Math.sqrt(dx * dx + dz * dz);
+}
+/**
+ * Race state machine (issue #87). Drive it each tick with `update(now, positions)` — `now` is game time
+ * (`ctx.time`), `positions` maps each racer to a world point tested against the ordered checkpoint
+ * volumes. It emits `checkpoint.hit` / `lap.completed` / `position.changed` / `race.finished`, keeps
+ * cumulative split times for PB deltas, resolves a pluggable win condition (first-past-post, round-cut,
+ * derby last-standing), and `resetToCheckpoint` hands back a respawn pose at the racer's last checkpoint.
+ */
+export class RaceState {
+    track;
+    win;
+    racers = new Map();
+    order = [];
+    raceFinished = false;
+    finalRanking = [];
+    constructor(config) {
+        this.track = config.track;
+        this.win = config.win ?? firstPastPost(1);
+    }
+    addRacer(racerId, startTime = 0) {
+        if (this.racers.has(racerId))
+            return;
+        this.racers.set(racerId, {
+            racerId,
+            lap: 1,
+            nextCheckpoint: 0,
+            lastCheckpoint: -1,
+            progress: 0,
+            position: this.order.length + 1,
+            finished: false,
+            finishTime: null,
+            eliminated: false,
+            startTime,
+            splits: [],
+        });
+        this.order.push(racerId);
+    }
+    eliminate(racerId) {
+        const r = this.racers.get(racerId);
+        if (r !== undefined)
+            r.eliminated = true;
+    }
+    get finished() {
+        return this.raceFinished;
+    }
+    get ranking() {
+        return this.finalRanking;
+    }
+    progressOf(racerId) {
+        const r = this.racers.get(racerId);
+        return r === null || r === undefined ? null : this.snapshot(r);
+    }
+    snapshot(r) {
+        return {
+            racerId: r.racerId,
+            lap: r.lap,
+            nextCheckpoint: r.nextCheckpoint,
+            lastCheckpoint: r.lastCheckpoint,
+            progress: r.progress,
+            position: r.position,
+            finished: r.finished,
+            finishTime: r.finishTime,
+            eliminated: r.eliminated,
+            splits: [...r.splits],
+        };
+    }
+    standings() {
+        return this.order
+            .map((id) => this.racers.get(id))
+            .slice()
+            .sort((a, b) => this.compare(a, b, null))
+            .map((r) => this.snapshot(r));
+    }
+    resetToCheckpoint(racerId) {
+        const r = this.racers.get(racerId);
+        if (r === undefined)
+            return null;
+        const cps = this.track.checkpoints;
+        const idx = r.lastCheckpoint >= 0 ? r.lastCheckpoint : 0;
+        const cp = cps[idx];
+        if (cp === undefined)
+            return null;
+        const next = cps[(idx + 1) % cps.length];
+        const heading = Math.atan2(next.center[0] - cp.center[0], next.center[2] - cp.center[2]);
+        return { position: [cp.center[0], cp.center[1], cp.center[2]], heading };
+    }
+    compare(a, b, positions) {
+        if (a.finished !== b.finished)
+            return a.finished ? -1 : 1;
+        if (a.finished && b.finished)
+            return (a.finishTime ?? 0) - (b.finishTime ?? 0);
+        if (a.eliminated !== b.eliminated)
+            return a.eliminated ? 1 : -1;
+        if (a.progress !== b.progress)
+            return b.progress - a.progress;
+        if (positions !== null) {
+            const pa = positions.get(a.racerId);
+            const pb = positions.get(b.racerId);
+            const cps = this.track.checkpoints;
+            if (pa !== undefined && pb !== undefined && cps.length > 0) {
+                const da = distanceToNext(pa, cps[a.nextCheckpoint]);
+                const db = distanceToNext(pb, cps[b.nextCheckpoint]);
+                if (da !== db)
+                    return da - db;
+            }
+        }
+        return this.order.indexOf(a.racerId) - this.order.indexOf(b.racerId);
+    }
+    update(now, positions) {
+        const posMap = positions instanceof Map ? positions : new Map(Object.entries(positions));
+        const events = [];
+        const cps = this.track.checkpoints;
+        const count = cps.length;
+        if (count > 0) {
+            for (const id of this.order) {
+                const r = this.racers.get(id);
+                if (r.finished || r.eliminated)
+                    continue;
+                const pos = posMap.get(id);
+                if (pos === undefined)
+                    continue;
+                let guard = 0;
+                while (guard < count && insideAabb(pos, cps[r.nextCheckpoint])) {
+                    guard += 1;
+                    const hit = r.nextCheckpoint;
+                    r.lastCheckpoint = hit;
+                    r.progress += 1;
+                    r.splits.push(now - r.startTime);
+                    events.push({ type: "checkpoint.hit", racerId: id, checkpoint: hit, lap: r.lap, time: now });
+                    if (hit === count - 1) {
+                        events.push({ type: "lap.completed", racerId: id, lap: r.lap, time: now });
+                        if (r.lap >= this.track.laps) {
+                            r.finished = true;
+                            r.finishTime = now;
+                            break;
+                        }
+                        r.lap += 1;
+                        r.nextCheckpoint = 0;
+                    }
+                    else {
+                        r.nextCheckpoint = hit + 1;
+                    }
+                }
+            }
+        }
+        const sorted = this.order
+            .map((id) => this.racers.get(id))
+            .slice()
+            .sort((a, b) => this.compare(a, b, posMap));
+        for (let i = 0; i < sorted.length; i += 1) {
+            const r = sorted[i];
+            const newPos = i + 1;
+            if (r.position !== newPos) {
+                events.push({ type: "position.changed", racerId: r.racerId, position: newPos, previous: r.position });
+                r.position = newPos;
+            }
+        }
+        if (!this.raceFinished) {
+            const ranking = this.win(sorted.map((r) => this.snapshot(r)), this.track);
+            if (ranking !== null) {
+                this.raceFinished = true;
+                this.finalRanking = ranking;
+                events.push({ type: "race.finished", ranking, time: now });
+            }
+        }
+        return events;
+    }
+}
+export function createRaceState(config) {
+    return new RaceState(config);
+}

package/dist/game/runDraft.d.ts

@@ -0,0 +1,34 @@
+import type { StatModifier, StatModifierSet, Stats } from "../stats/statModifiers.js";
+export interface RunModifierOffer<TStat extends string = string, TData = unknown> {
+    id: string;
+    weight: number;
+    maxStacks?: number;
+    label?: string;
+    stats?: StatModifierSet<TStat>;
+    data?: TData;
+}
+export interface RunModifierPick {
+    id: string;
+    stacks: number;
+}
+export interface RunModifierStack<TStat extends string = string, TData = unknown> {
+    add(offerId: string): boolean;
+    count(offerId: string): number;
+    atMax(offerId: string): boolean;
+    picks(): RunModifierPick[];
+    offer(offerId: string): RunModifierOffer<TStat, TData> | null;
+    total(stat: TStat): StatModifier;
+    apply(stats: Stats<TStat>, sourceId?: string): void;
+    clear(): void;
+}
+export declare function createRunModifierStack<TStat extends string = string, TData = unknown>(offers: readonly RunModifierOffer<TStat, TData>[]): RunModifierStack<TStat, TData>;
+export interface RunDraftConfig<TStat extends string = string, TData = unknown> {
+    offers: readonly RunModifierOffer<TStat, TData>[];
+    rng?: () => number;
+}
+export interface RunDraft<TStat extends string = string, TData = unknown> {
+    present(count: number, rng?: () => number): RunModifierOffer<TStat, TData>[];
+    choose(offerId: string): boolean;
+    stack(): RunModifierStack<TStat, TData>;
+}
+export declare function createRunDraft<TStat extends string = string, TData = unknown>(config: RunDraftConfig<TStat, TData>): RunDraft<TStat, TData>;

package/dist/game/runDraft.js

@@ -0,0 +1,97 @@
+import { pickWeighted } from "../world/scatterItems.js";
+export function createRunModifierStack(offers) {
+    const byId = new Map();
+    for (const offer of offers) {
+        if (byId.has(offer.id))
+            throw new Error(`duplicate run modifier offer: ${offer.id}`);
+        byId.set(offer.id, offer);
+    }
+    const stacks = new Map();
+    function count(offerId) {
+        return stacks.get(offerId) ?? 0;
+    }
+    function atMax(offerId) {
+        const offer = byId.get(offerId);
+        if (offer === undefined)
+            return true;
+        return offer.maxStacks !== undefined && count(offerId) >= offer.maxStacks;
+    }
+    function total(stat) {
+        let add = 0;
+        let multiply = 1;
+        for (const [offerId, n] of stacks) {
+            const modifier = byId.get(offerId)?.stats?.[stat];
+            if (modifier === undefined)
+                continue;
+            if (modifier.add !== undefined)
+                add += modifier.add * n;
+            if (modifier.multiply !== undefined)
+                multiply *= Math.pow(modifier.multiply, n);
+        }
+        return { add, multiply };
+    }
+    function statKeys() {
+        const keys = new Set();
+        for (const offerId of stacks.keys()) {
+            const stat = byId.get(offerId)?.stats;
+            if (stat === undefined)
+                continue;
+            for (const key of Object.keys(stat))
+                keys.add(key);
+        }
+        return [...keys];
+    }
+    return {
+        add(offerId) {
+            if (!byId.has(offerId) || atMax(offerId))
+                return false;
+            stacks.set(offerId, count(offerId) + 1);
+            return true;
+        },
+        count,
+        atMax,
+        picks() {
+            return [...stacks.entries()].map(([id, s]) => ({ id, stacks: s }));
+        },
+        offer(offerId) {
+            return byId.get(offerId) ?? null;
+        },
+        total,
+        apply(stats, sourceId = "run-modifiers") {
+            const set = {};
+            for (const key of statKeys())
+                set[key] = total(key);
+            stats.addSource(sourceId, set);
+        },
+        clear() {
+            stacks.clear();
+        },
+    };
+}
+export function createRunDraft(config) {
+    const stack = createRunModifierStack(config.offers);
+    const defaultRng = config.rng ?? Math.random;
+    return {
+        present(count, rng = defaultRng) {
+            const pool = config.offers.filter((offer) => !stack.atMax(offer.id));
+            const remaining = pool.map((offer) => ({ value: offer, weight: offer.weight }));
+            const drawn = [];
+            while (drawn.length < count && remaining.length > 0) {
+                const picked = pickWeighted(remaining, rng());
+                if (picked === null)
+                    break;
+                drawn.push(picked);
+                const index = remaining.findIndex((entry) => entry.value.id === picked.id);
+                if (index >= 0)
+                    remaining.splice(index, 1);
+            }
+            return drawn;
+        },
+        choose(offerId) {
+            return stack.add(offerId);
+        },
+        stack() {
+            return stack;
+        },
+    };
+}

package/dist/game/social.d.ts

@@ -5,10 +5,24 @@ export interface PresenceInfo {
     zoneId?: string;
     instanceId?: string;
 }
+export interface EmoteEntityLookup {
+    get(id: string): {
+        position: readonly [number, number, number];
+        role: string;
+    } | null;
+}
+export interface EmoteSpatialLookup {
+    inRadius(center: readonly [number, number, number], radius: number, filter?: (id: string) => boolean): readonly string[];
+}
+export interface EmotesDeps {
+    entities: EmoteEntityLookup;
+    spatial: EmoteSpatialLookup;
+}
 export interface SocialDeps {
     events: GameEvents;
     presence?: (userId: string) => PresenceInfo;
     now?: () => number;
+    emotes?: EmotesDeps;
 }
 export interface FriendEntry {
     userId: string;
@@ -68,11 +82,24 @@ export interface Party {
     list(userId: string): PartyMemberEntry[];
     membersOf(userId: string): string[];
 }
+export declare const DEFAULT_EMOTE_RADIUS = 20;
+export interface EmoteBroadcastResult {
+    from: string;
+    emoteId: string;
+    at: readonly [number, number, number];
+    recipients: readonly string[];
+}
+export interface Emotes {
+    play(fromUserId: string, emoteId: string, radius?: number): EmoteBroadcastResult | {
+        reason: string;
+    };
+}
 export interface Social {
     friends: Friends;
     party: Party;
     presence: {
         get(userId: string): PresenceInfo;
     };
+    emotes: Emotes;
 }
 export declare function createSocial(deps: SocialDeps): Social;

package/dist/game/social.js

@@ -1,3 +1,4 @@
+export const DEFAULT_EMOTE_RADIUS = 20;
 const DEFAULT_INVITE_TTL_MS = 60_000;
 export function createSocial(deps) {
     const now = deps.now ?? Date.now;
@@ -215,6 +216,20 @@ export function createSocial(deps) {
             return partyOf(userId)?.members.slice() ?? [];
         },
     };
+    const emotes = {
+        play(fromUserId, emoteId, radius) {
+            const emoteDeps = deps.emotes;
+            if (emoteDeps === undefined)
+                return { reason: "emotes not configured" };
+            const origin = emoteDeps.entities.get(fromUserId);
+            if (origin === null)
+                return { reason: `entity "${fromUserId}" is not spawned` };
+            const recipients = emoteDeps.spatial.inRadius(origin.position, radius ?? DEFAULT_EMOTE_RADIUS, (id) => id !== fromUserId && emoteDeps.entities.get(id)?.role === "player");
+            const result = { from: fromUserId, emoteId, at: origin.position, recipients };
+            events.emit("emote.played", result);
+            return result;
+        },
+    };
     return {
         friends,
         party,
@@ -223,5 +238,6 @@ export function createSocial(deps) {
                 return deps.presence?.(userId) ?? { online: false };
             },
         },
+        emotes,
     };
 }

package/dist/game/worldItem.d.ts

@@ -0,0 +1,92 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+import { type LootFilterItem, type LootFilterRule } from "./lootFilter.js";
+import type { Drop } from "./lootTable.js";
+/** Scene-entity catalog name every dropped-item instance spawns under (see the three buckets: worldItem is an entity, never an inventory item or object). */
+export declare const WORLD_ITEM_ENTITY_NAME = "world_item";
+export declare const DEFAULT_RARITY = "common";
+export declare const DEFAULT_PICKUP_RADIUS = 2;
+export interface ScatterOptions {
+    radius: number;
+    minRadius?: number;
+    height?: number;
+}
+export declare const DEFAULT_SCATTER: ScatterOptions;
+/** Random offset within an annulus `[minRadius, radius]` around the origin — the on-death scatter impulse. */
+export declare function scatterOffset(rng: () => number, options?: ScatterOptions): EntityPosition;
+export declare function scatterPosition(origin: EntityPosition, rng: () => number, options?: ScatterOptions): EntityPosition;
+export interface WorldItemRecord {
+    instanceId: string;
+    itemId: string;
+    rarity: string;
+    baseType: string;
+    count: number;
+    affixTier?: number;
+    source?: string;
+    droppedAt: number;
+}
+export interface WorldItemSpawnInput {
+    itemId: string;
+    position: EntityPosition;
+    rarity?: string;
+    baseType?: string;
+    count?: number;
+    affixTier?: number;
+    source?: string;
+}
+export interface WorldItemStoreDeps {
+    spawnEntity(position: EntityPosition): string;
+    despawnEntity(instanceId: string): boolean;
+    resolvePosition(instanceId: string): EntityPosition | undefined;
+    now?(): number;
+}
+export interface WorldItemStore {
+    spawn(input: WorldItemSpawnInput): WorldItemRecord;
+    get(instanceId: string): WorldItemRecord | null;
+    list(): readonly WorldItemRecord[];
+    nearestInRadius(from: EntityPosition, radius: number, filter?: (record: WorldItemRecord) => boolean): string | null;
+    take(instanceId: string): WorldItemRecord | null;
+}
+/** Pure pickup-radius + nearest-item selection, usable without a live store (click-to-grab, proximity prompts). */
+export declare function selectNearestWorldItem(candidates: readonly {
+    instanceId: string;
+    position: EntityPosition;
+}[], from: EntityPosition, radius: number): string | null;
+export declare function createWorldItemStore(deps: WorldItemStoreDeps): WorldItemStore;
+export interface ResolveDeathDropsOptions {
+    mode: "grant" | "world";
+    origin: EntityPosition;
+    resolveRarity(itemId: string): string;
+    resolveBaseType?(itemId: string): string;
+    scatter?: ScatterOptions;
+    rng?(): number;
+    source?: string;
+}
+export interface ResolvedDeathDrops {
+    worldSpawns: WorldItemSpawnInput[];
+    grants: Drop[];
+}
+/**
+ * Splits rolled death drops between direct grants and scattered ground items.
+ * `mode: "grant"` is the legacy behavior (loot straight to inventory); `mode:
+ * "world"` routes item drops through a scatter impulse and leaves currency
+ * drops granting directly (coins fly to the killer, gear hits the ground).
+ */
+export declare function resolveDeathDrops(drops: readonly Drop[], options: ResolveDeathDropsOptions): ResolvedDeathDrops;
+export interface RarityStyle {
+    color?: string;
+    beam?: boolean;
+    label?: string;
+}
+export interface WorldItemPresentation {
+    hidden: boolean;
+    color?: string;
+    beam: boolean;
+    label?: string;
+}
+/**
+ * Composes the baseline rarity→beam/color/label render binding (#32, catalog
+ * data the game supplies) with the loot-filter rule overrides (#33). A
+ * matching rule wins field-by-field; unmatched fields fall back to the
+ * rarity's baseline style.
+ */
+export declare function resolveWorldItemPresentation(item: LootFilterItem, rarityStyle: Record<string, RarityStyle> | undefined, rules: readonly LootFilterRule[] | undefined): WorldItemPresentation;

package/dist/game/worldItem.js

@@ -0,0 +1,132 @@
+import { distanceBetween } from "../scene/spatial.js";
+import { evaluateLootFilter } from "./lootFilter.js";
+/** Scene-entity catalog name every dropped-item instance spawns under (see the three buckets: worldItem is an entity, never an inventory item or object). */
+export const WORLD_ITEM_ENTITY_NAME = "world_item";
+export const DEFAULT_RARITY = "common";
+export const DEFAULT_PICKUP_RADIUS = 2;
+export const DEFAULT_SCATTER = { radius: 1.5, minRadius: 0.4, height: 0 };
+/** Random offset within an annulus `[minRadius, radius]` around the origin — the on-death scatter impulse. */
+export function scatterOffset(rng, options = DEFAULT_SCATTER) {
+    const angle = rng() * Math.PI * 2;
+    const min = options.minRadius ?? 0;
+    const span = Math.max(options.radius - min, 0);
+    const distance = min + rng() * span;
+    return [Math.cos(angle) * distance, options.height ?? 0, Math.sin(angle) * distance];
+}
+export function scatterPosition(origin, rng, options = DEFAULT_SCATTER) {
+    const offset = scatterOffset(rng, options);
+    return [origin[0] + offset[0], origin[1] + offset[1], origin[2] + offset[2]];
+}
+/** Pure pickup-radius + nearest-item selection, usable without a live store (click-to-grab, proximity prompts). */
+export function selectNearestWorldItem(candidates, from, radius) {
+    let bestId = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const distance = distanceBetween(from, candidate.position);
+        if (distance <= radius && distance < bestDistance) {
+            bestDistance = distance;
+            bestId = candidate.instanceId;
+        }
+    }
+    return bestId;
+}
+export function createWorldItemStore(deps) {
+    const records = new Map();
+    const now = deps.now ?? Date.now;
+    return {
+        spawn(input) {
+            const instanceId = deps.spawnEntity(input.position);
+            const record = {
+                instanceId,
+                itemId: input.itemId,
+                rarity: input.rarity ?? DEFAULT_RARITY,
+                baseType: input.baseType ?? input.itemId,
+                count: input.count ?? 1,
+                droppedAt: now(),
+            };
+            if (input.affixTier !== undefined)
+                record.affixTier = input.affixTier;
+            if (input.source !== undefined)
+                record.source = input.source;
+            records.set(instanceId, record);
+            return record;
+        },
+        get(instanceId) {
+            return records.get(instanceId) ?? null;
+        },
+        list() {
+            return [...records.values()];
+        },
+        nearestInRadius(from, radius, filter) {
+            const candidates = [];
+            for (const record of records.values()) {
+                if (filter !== undefined && !filter(record))
+                    continue;
+                const position = deps.resolvePosition(record.instanceId);
+                if (position !== undefined)
+                    candidates.push({ instanceId: record.instanceId, position });
+            }
+            return selectNearestWorldItem(candidates, from, radius);
+        },
+        take(instanceId) {
+            const record = records.get(instanceId);
+            if (record === undefined)
+                return null;
+            records.delete(instanceId);
+            deps.despawnEntity(instanceId);
+            return record;
+        },
+    };
+}
+/**
+ * Splits rolled death drops between direct grants and scattered ground items.
+ * `mode: "grant"` is the legacy behavior (loot straight to inventory); `mode:
+ * "world"` routes item drops through a scatter impulse and leaves currency
+ * drops granting directly (coins fly to the killer, gear hits the ground).
+ */
+export function resolveDeathDrops(drops, options) {
+    if (options.mode !== "world")
+        return { worldSpawns: [], grants: [...drops] };
+    const rng = options.rng ?? Math.random;
+    const worldSpawns = [];
+    const grants = [];
+    for (const drop of drops) {
+        if (drop.item === undefined) {
+            grants.push(drop);
+            continue;
+        }
+        const spawn = {
+            itemId: drop.item,
+            count: drop.count,
+            rarity: options.resolveRarity(drop.item),
+            position: scatterPosition(options.origin, rng, options.scatter),
+        };
+        if (options.resolveBaseType !== undefined)
+            spawn.baseType = options.resolveBaseType(drop.item);
+        if (options.source !== undefined)
+            spawn.source = options.source;
+        worldSpawns.push(spawn);
+    }
+    return { worldSpawns, grants };
+}
+/**
+ * Composes the baseline rarity→beam/color/label render binding (#32, catalog
+ * data the game supplies) with the loot-filter rule overrides (#33). A
+ * matching rule wins field-by-field; unmatched fields fall back to the
+ * rarity's baseline style.
+ */
+export function resolveWorldItemPresentation(item, rarityStyle, rules) {
+    const base = rarityStyle?.[item.rarity];
+    const override = rules === undefined || rules.length === 0 ? {} : evaluateLootFilter(rules, item);
+    const presentation = {
+        hidden: override.hidden ?? false,
+        beam: override.beam ?? base?.beam ?? false,
+    };
+    const color = override.color ?? base?.color;
+    if (color !== undefined)
+        presentation.color = color;
+    const label = override.label ?? base?.label;
+    if (label !== undefined)
+        presentation.label = label;
+    return presentation;
+}