@jgengine/core 0.6.0 → 0.8.0

package/dist/game/race.d.ts

@@ -0,0 +1,100 @@
+export interface Checkpoint {
+    id: string;
+    center: readonly [number, number, number];
+    half: readonly [number, number, number];
+}
+export interface RaceTrackConfig {
+    checkpoints: readonly Checkpoint[];
+    laps?: number;
+}
+export interface RaceTrack {
+    readonly checkpoints: readonly Checkpoint[];
+    readonly laps: number;
+}
+/**
+ * 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 declare function raceTrack(config: RaceTrackConfig): RaceTrack;
+export interface RacerProgress {
+    racerId: string;
+    lap: number;
+    nextCheckpoint: number;
+    lastCheckpoint: number;
+    progress: number;
+    position: number;
+    finished: boolean;
+    finishTime: number | null;
+    eliminated: boolean;
+    splits: readonly number[];
+}
+export type RaceEvent = {
+    type: "checkpoint.hit";
+    racerId: string;
+    checkpoint: number;
+    lap: number;
+    time: number;
+} | {
+    type: "lap.completed";
+    racerId: string;
+    lap: number;
+    time: number;
+} | {
+    type: "position.changed";
+    racerId: string;
+    position: number;
+    previous: number;
+} | {
+    type: "race.finished";
+    ranking: readonly string[];
+    time: number;
+};
+export type RaceWinCondition = (standings: readonly RacerProgress[], track: RaceTrack) => readonly string[] | null;
+/** Race ends when `count` racers have crossed the finish; ranking is the current standings order. */
+export declare function firstPastPost(count?: number): RaceWinCondition;
+/** Round-cut (Fall Guys): the first `k` finishers qualify; race resolves the moment `k` cross. */
+export declare function topK(k: number): RaceWinCondition;
+/** Every non-eliminated racer must finish. */
+export declare function everyoneFinishes(): RaceWinCondition;
+/** Destruction-derby last-man-standing: ends when at most one racer is left un-eliminated. */
+export declare function lastStanding(): RaceWinCondition;
+export interface RaceStateConfig {
+    track: RaceTrack;
+    win?: RaceWinCondition;
+}
+/**
+ * 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.
+ * `removeRacer` drops a racer mid-race and `reset` returns the whole instance to its pre-race state for reuse.
+ */
+export declare class RaceState {
+    private readonly track;
+    private readonly win;
+    private readonly racers;
+    private readonly order;
+    private raceFinished;
+    private finalRanking;
+    constructor(config: RaceStateConfig);
+    addRacer(racerId: string, startTime?: number): void;
+    /** Removes a racer's progress/standing and renumbers the remaining field's positions; a no-op for an unknown id. */
+    removeRacer(racerId: string): void;
+    /** Clears all racer progress and finish state back to construction time; `track` and `win` are untouched, so the same instance can run another race. */
+    reset(): void;
+    eliminate(racerId: string): void;
+    get finished(): boolean;
+    get ranking(): readonly string[];
+    progressOf(racerId: string): RacerProgress | null;
+    private snapshot;
+    standings(): readonly RacerProgress[];
+    resetToCheckpoint(racerId: string): {
+        position: [number, number, number];
+        heading: number;
+    } | null;
+    private compare;
+    update(now: number, positions: Record<string, readonly [number, number, number]> | Map<string, readonly [number, number, number]>): readonly RaceEvent[];
+}
+export declare function createRaceState(config: RaceStateConfig): RaceState;

package/dist/game/race.js

@@ -0,0 +1,236 @@
+/**
+ * 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.
+ * `removeRacer` drops a racer mid-race and `reset` returns the whole instance to its pre-race state for reuse.
+ */
+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);
+    }
+    /** Removes a racer's progress/standing and renumbers the remaining field's positions; a no-op for an unknown id. */
+    removeRacer(racerId) {
+        if (!this.racers.delete(racerId))
+            return;
+        const idx = this.order.indexOf(racerId);
+        if (idx >= 0)
+            this.order.splice(idx, 1);
+        const remaining = this.order.map((id) => this.racers.get(id)).sort((a, b) => this.compare(a, b, null));
+        remaining.forEach((r, i) => {
+            r.position = i + 1;
+        });
+    }
+    /** Clears all racer progress and finish state back to construction time; `track` and `win` are untouched, so the same instance can run another race. */
+    reset() {
+        this.racers.clear();
+        this.order.length = 0;
+        this.raceFinished = false;
+        this.finalRanking = [];
+    }
+    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,25 @@ 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;
+    worldInviteTtlMs?: number;
 }
 export interface FriendEntry {
     userId: string;
@@ -18,6 +33,10 @@ export interface FriendsSnapshot {
     friends: string[];
     blocked: string[];
 }
+export interface FriendRequestEntry {
+    requestId: string;
+    fromUserId: string;
+}
 export interface Friends {
     canRequest(fromUserId: string, toUserId: string): {
         reason: string;
@@ -30,9 +49,11 @@ export interface Friends {
     accept(userId: string, requestId: string): {
         reason: string;
     } | null;
+    decline(userId: string, requestId: string): void;
     remove(userId: string, friendUserId: string): void;
     block(userId: string, targetUserId: string): void;
     list(userId: string): FriendEntry[];
+    requestsFor(userId: string): FriendRequestEntry[];
     snapshot(userId: string): FriendsSnapshot;
     hydrate(userId: string, data: FriendsSnapshot): void;
 }
@@ -45,6 +66,11 @@ export interface PartyConfig {
     maxMembers: number;
     inviteTtlMs?: number;
 }
+export interface PartyInviteEntry {
+    inviteId: string;
+    fromUserId: string;
+    createdAt: number;
+}
 export interface Party {
     register(config: PartyConfig): void;
     canInvite(fromUserId: string, toUserId: string): {
@@ -58,6 +84,7 @@ export interface Party {
     accept(userId: string, inviteId: string): {
         reason: string;
     } | null;
+    decline(userId: string, inviteId: string): void;
     kick(leaderUserId: string, memberUserId: string): {
         reason: string;
     } | null;
@@ -67,6 +94,46 @@ export interface Party {
     } | null;
     list(userId: string): PartyMemberEntry[];
     membersOf(userId: string): string[];
+    invitesFor(userId: string): PartyInviteEntry[];
+}
+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 WorldInviteTarget {
+    serverId: string;
+    joinCode?: string;
+}
+export interface WorldInvite extends WorldInviteTarget {
+    id: string;
+    fromUserId: string;
+    toUserId: string;
+    createdAt: number;
+}
+export interface WorldInvites {
+    canInvite(fromUserId: string, toUserId: string): {
+        reason: string;
+    } | null;
+    invite(fromUserId: string, toUserId: string, target: WorldInviteTarget): {
+        inviteId: string;
+    } | {
+        reason: string;
+    };
+    accept(userId: string, inviteId: string): {
+        target: WorldInviteTarget;
+    } | {
+        reason: string;
+    };
+    decline(userId: string, inviteId: string): void;
+    listFor(userId: string): WorldInvite[];
 }
 export interface Social {
     friends: Friends;
@@ -74,5 +141,7 @@ export interface Social {
     presence: {
         get(userId: string): PresenceInfo;
     };
+    emotes: Emotes;
+    worldInvites: WorldInvites;
 }
 export declare function createSocial(deps: SocialDeps): Social;