@jgengine/core 0.6.0 → 0.8.0

package/dist/multiplayer/matchmaking.d.ts

@@ -0,0 +1,33 @@
+export type SessionVisibility = "public" | "private";
+export type SessionStatus = "open" | "running" | "closed";
+export interface SessionListing {
+    serverId: string;
+    gameId: string;
+    status: SessionStatus;
+    visibility: SessionVisibility;
+    memberCount: number;
+    slotsPerServer: number;
+    label?: string;
+    mode?: string;
+    joinCode?: string;
+    tags?: readonly string[];
+    updatedAt: number;
+}
+export interface MatchFilter {
+    mode?: string;
+    tags?: readonly string[];
+    query?: string;
+    notFull?: boolean;
+    status?: readonly SessionStatus[];
+    includePrivate?: boolean;
+}
+export interface BrowseOptions {
+    limit?: number;
+}
+export declare function normalizeJoinCode(code: string): string;
+export declare function generateJoinCode(random: () => number, length?: number): string;
+export declare function hasSpace(listing: SessionListing): boolean;
+export declare function matchesFilter(listing: SessionListing, filter: MatchFilter): boolean;
+export declare function browseSessions(listings: readonly SessionListing[], filter?: MatchFilter, options?: BrowseOptions): SessionListing[];
+export declare function findByJoinCode(listings: readonly SessionListing[], code: string): SessionListing | null;
+export declare function quickMatch(listings: readonly SessionListing[], filter?: MatchFilter): SessionListing | null;

package/dist/multiplayer/matchmaking.js

@@ -0,0 +1,60 @@
+export function normalizeJoinCode(code) {
+    return code.toUpperCase().replace(/[^A-Z0-9]/g, "");
+}
+const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+export function generateJoinCode(random, length = 6) {
+    let code = "";
+    for (let i = 0; i < length; i += 1) {
+        const index = Math.min(CODE_ALPHABET.length - 1, Math.floor(random() * CODE_ALPHABET.length));
+        code += CODE_ALPHABET[index];
+    }
+    return code;
+}
+export function hasSpace(listing) {
+    return listing.memberCount < listing.slotsPerServer;
+}
+export function matchesFilter(listing, filter) {
+    if (listing.visibility === "private" && filter.includePrivate !== true)
+        return false;
+    const statuses = filter.status ?? ["open", "running"];
+    if (!statuses.includes(listing.status))
+        return false;
+    if (filter.mode !== undefined && listing.mode !== filter.mode)
+        return false;
+    if (filter.notFull === true && !hasSpace(listing))
+        return false;
+    if (filter.tags !== undefined && filter.tags.length > 0) {
+        const owned = new Set(listing.tags ?? []);
+        if (!filter.tags.every((tag) => owned.has(tag)))
+            return false;
+    }
+    if (filter.query !== undefined && filter.query.length > 0) {
+        const haystack = (listing.label ?? "").toLowerCase();
+        if (!haystack.includes(filter.query.toLowerCase()))
+            return false;
+    }
+    return true;
+}
+export function browseSessions(listings, filter = {}, options = {}) {
+    const matched = listings
+        .filter((listing) => matchesFilter(listing, filter))
+        .sort((a, b) => b.memberCount - a.memberCount || b.updatedAt - a.updatedAt);
+    return options.limit !== undefined ? matched.slice(0, options.limit) : matched;
+}
+export function findByJoinCode(listings, code) {
+    const normalized = normalizeJoinCode(code);
+    if (normalized.length === 0)
+        return null;
+    for (const listing of listings) {
+        if (listing.joinCode !== undefined && normalizeJoinCode(listing.joinCode) === normalized) {
+            return listing;
+        }
+    }
+    return null;
+}
+export function quickMatch(listings, filter = {}) {
+    const candidates = listings
+        .filter((listing) => matchesFilter(listing, { ...filter, notFull: true }))
+        .sort((a, b) => b.memberCount - a.memberCount || a.updatedAt - b.updatedAt);
+    return candidates[0] ?? null;
+}

package/dist/multiplayer/poseSyncGate.d.ts

@@ -4,6 +4,7 @@ export interface PlayerPose {
     z: number;
     rotationY: number;
     rotationPitch: number;
+    appearance?: Record<string, string>;
 }
 export interface PoseSyncTuning {
     minIntervalMs: number;

package/dist/multiplayer/poseSyncGate.js

@@ -1,9 +1,21 @@
+function appearanceChanged(a, b) {
+    if (a === b)
+        return false;
+    if (a === undefined || b === undefined)
+        return true;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return true;
+    return aKeys.some((key) => a[key] !== b[key]);
+}
 function poseChanged(a, b, tuning) {
     return (Math.abs(a.x - b.x) > tuning.positionEpsilon
         || Math.abs(a.y - b.y) > tuning.verticalEpsilon
         || Math.abs(a.z - b.z) > tuning.positionEpsilon
         || Math.abs(a.rotationY - b.rotationY) > tuning.rotationEpsilon
-        || Math.abs(a.rotationPitch - b.rotationPitch) > tuning.rotationEpsilon);
+        || Math.abs(a.rotationPitch - b.rotationPitch) > tuning.rotationEpsilon
+        || appearanceChanged(a.appearance, b.appearance));
 }
 export function createPoseSyncGate(tuning) {
     let lastSentPose = null;

package/dist/multiplayer/presenceModel.d.ts

@@ -7,6 +7,7 @@ export interface PresencePoseState {
     rotationY: number;
     rotationPitch?: number;
     lastSeenAtMs?: number;
+    appearance?: Record<string, string>;
 }
 export interface IncomingPose {
     position: {
@@ -16,6 +17,7 @@ export interface IncomingPose {
     };
     rotationY?: number;
     rotationPitch?: number;
+    appearance?: Record<string, string>;
 }
 export interface PoseSyncRules {
     /** Speed cap (units/sec) for client-authoritative movement. */
@@ -36,6 +38,7 @@ export interface PoseSyncDecision {
     };
     rotationY: number;
     rotationPitch: number;
+    appearance?: Record<string, string>;
     /** True when the pose differs and a pose write is needed. */
     changed: boolean;
     /** True when only the keep-alive stamp should be written. */

package/dist/multiplayer/presenceModel.js

@@ -1,3 +1,14 @@
+function appearanceEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((key) => a[key] === b[key]);
+}
 export function decidePoseSync(current, incoming, rules, nowMs) {
     const elapsedSec = Math.max(rules.minElapsedSec, Math.min(rules.maxElapsedSec, (nowMs - (current.lastSeenAtMs ?? nowMs)) / 1000));
     const maxDist = rules.maxSpeed * elapsedSec;
@@ -17,14 +28,17 @@ export function decidePoseSync(current, incoming, rules, nowMs) {
         : Math.max(0, Math.min(rules.maxVerticalOffset, incoming.position.y));
     const nextRotationY = incoming.rotationY ?? current.rotationY;
     const nextRotationPitch = incoming.rotationPitch ?? current.rotationPitch ?? 0;
+    const nextAppearance = incoming.appearance ?? current.appearance;
+    const appearanceChanged = incoming.appearance !== undefined && !appearanceEqual(incoming.appearance, current.appearance);
     const moved = targetX !== current.position.x || targetZ !== current.position.z;
     const jumped = nextY !== current.position.y;
     const rotated = nextRotationY !== current.rotationY || nextRotationPitch !== (current.rotationPitch ?? 0);
-    const changed = moved || jumped || rotated;
+    const changed = moved || jumped || rotated || appearanceChanged;
     return {
         position: { x: targetX, y: nextY, z: targetZ },
         rotationY: nextRotationY,
         rotationPitch: nextRotationPitch,
+        appearance: nextAppearance,
         changed,
         refreshKeepAlive: !changed && shouldRefreshKeepAlive(current.lastSeenAtMs, nowMs, rules),
     };

package/dist/multiplayer/simultaneousCommit.d.ts

@@ -0,0 +1,34 @@
+export type CommitPhase = "collecting" | "revealed";
+export interface SealedCommit<TAction> {
+    playerId: string;
+    action: TAction;
+    sealedAt: number;
+}
+export interface CommitRoundConfig {
+    participants: readonly string[];
+    allowReseal?: boolean;
+}
+export type SealResult = {
+    ok: true;
+    allSealed: boolean;
+} | {
+    ok: false;
+    reason: "unknown_participant" | "already_sealed" | "already_revealed";
+};
+export declare class CommitRound<TAction> {
+    private readonly order;
+    private readonly participants;
+    private readonly allowReseal;
+    private readonly sealed;
+    private revealedFlag;
+    constructor(config: CommitRoundConfig);
+    seal(playerId: string, action: TAction, at: number): SealResult;
+    hasSealed(playerId: string): boolean;
+    sealedCount(): number;
+    pending(): string[];
+    allSealed(): boolean;
+    get phase(): CommitPhase;
+    reveal(): readonly SealedCommit<TAction>[] | null;
+}
+export declare function createCommitRound<TAction>(config: CommitRoundConfig): CommitRound<TAction>;
+export declare function resolveCommits<TAction, TResult>(reveals: readonly SealedCommit<TAction>[], resolver: (ordered: readonly SealedCommit<TAction>[]) => TResult): TResult;

package/dist/multiplayer/simultaneousCommit.js

@@ -0,0 +1,53 @@
+export class CommitRound {
+    order;
+    participants;
+    allowReseal;
+    sealed = new Map();
+    revealedFlag = false;
+    constructor(config) {
+        if (config.participants.length === 0) {
+            throw new RangeError("a commit round needs at least one participant");
+        }
+        this.order = [...config.participants];
+        this.participants = new Set(config.participants);
+        this.allowReseal = config.allowReseal ?? false;
+    }
+    seal(playerId, action, at) {
+        if (this.revealedFlag)
+            return { ok: false, reason: "already_revealed" };
+        if (!this.participants.has(playerId))
+            return { ok: false, reason: "unknown_participant" };
+        if (this.sealed.has(playerId) && !this.allowReseal) {
+            return { ok: false, reason: "already_sealed" };
+        }
+        this.sealed.set(playerId, { playerId, action, sealedAt: at });
+        return { ok: true, allSealed: this.allSealed() };
+    }
+    hasSealed(playerId) {
+        return this.sealed.has(playerId);
+    }
+    sealedCount() {
+        return this.sealed.size;
+    }
+    pending() {
+        return this.order.filter((id) => !this.sealed.has(id));
+    }
+    allSealed() {
+        return this.sealed.size === this.participants.size;
+    }
+    get phase() {
+        return this.revealedFlag ? "revealed" : "collecting";
+    }
+    reveal() {
+        if (!this.allSealed())
+            return null;
+        this.revealedFlag = true;
+        return this.order.map((id) => this.sealed.get(id));
+    }
+}
+export function createCommitRound(config) {
+    return new CommitRound(config);
+}
+export function resolveCommits(reveals, resolver) {
+    return resolver(reveals);
+}

package/dist/multiplayer/voiceContract.d.ts

@@ -0,0 +1,44 @@
+export interface VoiceParticipant {
+    userId: string;
+    streamId?: string;
+}
+export interface VoiceRoute {
+    fromUserId: string;
+    channelId: string;
+    gain: number;
+}
+/**
+ * Signaling seam for voice: who is in a channel and which media stream
+ * descriptor they published. The media plane (WebRTC, SFU, or anything else
+ * that moves audio bytes) stays behind this seam, host-supplied — the engine
+ * never touches it. subscribers delivers the channel roster on every change,
+ * starting with the current roster.
+ */
+export interface VoiceTransport {
+    join(channelId: string, streamId?: string): Promise<void>;
+    leave(channelId: string): Promise<void>;
+    publish(channelId: string, streamId: string): Promise<void>;
+    subscribers(channelId: string, onChange: (participants: readonly VoiceParticipant[]) => void): () => void;
+}
+export declare function createLocalVoiceTransport(options?: {
+    userId?: string;
+}): {
+    transport: VoiceTransport;
+    participants(channelId: string): readonly VoiceParticipant[];
+};
+export type PushToTalkMode = "hold" | "toggle" | "openMic";
+export type PushToTalkStatus = "idle" | "keyed" | "open";
+export interface PushToTalk {
+    mode(): PushToTalkMode;
+    setMode(mode: PushToTalkMode): void;
+    keyDown(): void;
+    keyUp(): void;
+    muted(): boolean;
+    setMuted(muted: boolean): void;
+    status(): PushToTalkStatus;
+    transmitting(): boolean;
+}
+export declare function createPushToTalk(config?: {
+    mode?: PushToTalkMode;
+    onChange?: (transmitting: boolean) => void;
+}): PushToTalk;

package/dist/multiplayer/voiceContract.js

@@ -0,0 +1,108 @@
+export function createLocalVoiceTransport(options) {
+    const userId = options?.userId ?? "local";
+    const rosters = new Map();
+    const listeners = new Map();
+    function roster(channelId) {
+        let entries = rosters.get(channelId);
+        if (entries === undefined) {
+            entries = new Map();
+            rosters.set(channelId, entries);
+        }
+        return entries;
+    }
+    function snapshot(channelId) {
+        return [...roster(channelId).values()].map((participant) => ({ ...participant }));
+    }
+    function notify(channelId) {
+        const current = snapshot(channelId);
+        for (const listener of listeners.get(channelId) ?? [])
+            listener(current);
+    }
+    const transport = {
+        join(channelId, streamId) {
+            const participant = { userId };
+            if (streamId !== undefined)
+                participant.streamId = streamId;
+            roster(channelId).set(userId, participant);
+            notify(channelId);
+            return Promise.resolve();
+        },
+        leave(channelId) {
+            if (roster(channelId).delete(userId))
+                notify(channelId);
+            return Promise.resolve();
+        },
+        publish(channelId, streamId) {
+            const participant = roster(channelId).get(userId);
+            if (participant !== undefined) {
+                participant.streamId = streamId;
+                notify(channelId);
+            }
+            return Promise.resolve();
+        },
+        subscribers(channelId, onChange) {
+            let set = listeners.get(channelId);
+            if (set === undefined) {
+                set = new Set();
+                listeners.set(channelId, set);
+            }
+            set.add(onChange);
+            onChange(snapshot(channelId));
+            return () => {
+                set.delete(onChange);
+                if (set.size === 0)
+                    listeners.delete(channelId);
+            };
+        },
+    };
+    return { transport, participants: snapshot };
+}
+export function createPushToTalk(config) {
+    let mode = config?.mode ?? "hold";
+    let keyed = false;
+    let muted = false;
+    let lastTransmitting = false;
+    function transmitting() {
+        if (muted)
+            return false;
+        return mode === "openMic" ? true : keyed;
+    }
+    function emit() {
+        const current = transmitting();
+        if (current === lastTransmitting)
+            return;
+        lastTransmitting = current;
+        config?.onChange?.(current);
+    }
+    return {
+        mode: () => mode,
+        setMode(next) {
+            mode = next;
+            keyed = false;
+            emit();
+        },
+        keyDown() {
+            if (mode === "hold")
+                keyed = true;
+            else if (mode === "toggle")
+                keyed = !keyed;
+            emit();
+        },
+        keyUp() {
+            if (mode === "hold")
+                keyed = false;
+            emit();
+        },
+        muted: () => muted,
+        setMuted(next) {
+            muted = next;
+            emit();
+        },
+        status() {
+            if (mode === "openMic")
+                return "open";
+            return keyed ? "keyed" : "idle";
+        },
+        transmitting,
+    };
+}

package/dist/nav/navConstrain.d.ts

@@ -0,0 +1,14 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+import type { NavGrid, NavPoint } from "./navGrid.js";
+export interface NavConstrainProposed {
+    position: EntityPosition;
+    rotationY: number;
+    grounded: boolean;
+}
+export interface NavConstrainEntity {
+    position: EntityPosition;
+}
+export interface NavConstrainOptions {
+    y?: (point: NavPoint) => number;
+}
+export declare function constrainToNavGrid(grid: NavGrid, options?: NavConstrainOptions): (proposed: NavConstrainProposed, entity: NavConstrainEntity) => NavConstrainProposed | null;

package/dist/nav/navConstrain.js

@@ -0,0 +1,26 @@
+function withYRemap(proposed, options) {
+    if (options?.y === undefined)
+        return proposed;
+    const y = options.y([proposed.position[0], proposed.position[2]]);
+    return { ...proposed, position: [proposed.position[0], y, proposed.position[2]] };
+}
+function walkable(grid, point) {
+    const cell = grid.cellAt(point);
+    return grid.isWalkable(cell.col, cell.row);
+}
+export function constrainToNavGrid(grid, options) {
+    return (proposed, entity) => {
+        const target = [proposed.position[0], proposed.position[2]];
+        if (walkable(grid, target))
+            return withYRemap(proposed, options);
+        const slideX = [entity.position[0], proposed.position[2]];
+        if (walkable(grid, slideX)) {
+            return withYRemap({ ...proposed, position: [entity.position[0], proposed.position[1], proposed.position[2]] }, options);
+        }
+        const slideZ = [proposed.position[0], entity.position[2]];
+        if (walkable(grid, slideZ)) {
+            return withYRemap({ ...proposed, position: [proposed.position[0], proposed.position[1], entity.position[2]] }, options);
+        }
+        return null;
+    };
+}

package/dist/nav/navFromEnvironment.d.ts

@@ -0,0 +1,11 @@
+import type { EnvironmentWorldFeature } from "../world/features.js";
+import type { Aabb } from "../world/geometry.js";
+export interface NavObstacleGrid {
+    blockAabb(aabb: Aabb): void;
+}
+/**
+ * Expands every structure descriptor on an environment world feature into its
+ * generated buildings and blocks their footprints on `grid`. Returns the
+ * number of buildings blocked.
+ */
+export declare function populateNavGridFromEnvironment(grid: NavObstacleGrid, world: EnvironmentWorldFeature): number;

package/dist/nav/navFromEnvironment.js

@@ -0,0 +1,16 @@
+import { resolveStructureBuildings } from "../world/environmentSummary.js";
+/**
+ * Expands every structure descriptor on an environment world feature into its
+ * generated buildings and blocks their footprints on `grid`. Returns the
+ * number of buildings blocked.
+ */
+export function populateNavGridFromEnvironment(grid, world) {
+    let blocked = 0;
+    for (const descriptor of world.structures ?? []) {
+        for (const building of resolveStructureBuildings(descriptor)) {
+            grid.blockAabb(building.bounds);
+            blocked += 1;
+        }
+    }
+    return blocked;
+}

package/dist/nav/navGrid.d.ts

@@ -0,0 +1,56 @@
+import type { Aabb } from "../world/geometry.js";
+export type NavPoint = readonly [number, number];
+export interface NavGridConfig {
+    bounds: Aabb;
+    cellSize: number;
+    /** Allow 8-neighbour movement (no corner cutting). Default true. */
+    diagonal?: boolean;
+}
+export interface NavCell {
+    col: number;
+    row: number;
+}
+export interface FindPathOptions {
+    /** String-pull the raw grid path into straight runs where line-of-sight is clear. Default true. */
+    smooth?: boolean;
+    /** Diameter of the mover in world units — blocks cells within this margin of an obstacle. Default 0. */
+    clearance?: number;
+    /** Multiplier (>=1) applied to the base cost of stepping from one cell center to a neighbour's. Use to penalize slopes, terrain, etc. */
+    stepCost?: (from: NavPoint, to: NavPoint) => number;
+}
+export interface NavGrid {
+    readonly cols: number;
+    readonly rows: number;
+    readonly cellSize: number;
+    readonly bounds: Aabb;
+    readonly diagonal: boolean;
+    isWalkable(col: number, row: number): boolean;
+    setWalkable(col: number, row: number, walkable: boolean): void;
+    blockAabb(aabb: Aabb): void;
+    clearAabb(aabb: Aabb): void;
+    reset(walkable: boolean): void;
+    inBounds(col: number, row: number): boolean;
+    cellAt(point: NavPoint): NavCell;
+    center(col: number, row: number): NavPoint;
+    /** Nearest walkable cell to a point (spiral search); null if the whole grid is blocked. */
+    nearestWalkable(point: NavPoint): NavCell | null;
+    /** Unobstructed straight line between two world points (supercover cell walk). */
+    lineOfSight(from: NavPoint, to: NavPoint): boolean;
+}
+export declare function createNavGrid(config: NavGridConfig): NavGrid;
+/**
+ * A* over the walkable grid. Returns a polyline of world-space `[x, z]` waypoints
+ * from `from` to `to`, or `null` when no route exists. Blocked start/goal snap to
+ * the nearest walkable cell so a click on an obstacle still routes to its edge.
+ */
+export declare function findPath(grid: NavGrid, from: NavPoint, to: NavPoint, options?: FindPathOptions): NavPoint[] | null;
+/**
+ * `FindPathOptions.stepCost` factory that penalizes steep terrain: cost is
+ * `1 + weight * |Δheight| / horizontalDistance`, so with the default weight a
+ * 45° slope roughly doubles the step cost.
+ */
+export declare function slopeStepCost(field: {
+    sampleHeight(x: number, z: number): number;
+}, weight?: number): (from: NavPoint, to: NavPoint) => number;
+/** Remove waypoints the mover can skip because it has clear line-of-sight past them. */
+export declare function smoothPath(grid: NavGrid, points: readonly NavPoint[]): NavPoint[];