@jgengine/core 0.7.0 → 0.8.0

package/dist/game/chat.js

@@ -0,0 +1,165 @@
+export const DEFAULT_CHAT_RATE_LIMIT = { count: 10, perMs: 10_000 };
+export const DEFAULT_CHAT_HISTORY_LIMIT = 100;
+export const DEFAULT_CHAT_BODY_LENGTH = 500;
+export const DEFAULT_PROXIMITY_CHAT_RADIUS = 20;
+export const WHISPER_CHANNEL_PREFIX = "whisper:";
+export function whisperChannelId(a, b) {
+    const [first, second] = a < b ? [a, b] : [b, a];
+    return `${WHISPER_CHANNEL_PREFIX}${first}:${second}`;
+}
+export function createChatRateLimiter(limit) {
+    const windows = new Map();
+    return {
+        allow(key, atMs) {
+            const cutoff = atMs - limit.perMs;
+            const stamps = (windows.get(key) ?? []).filter((stamp) => stamp > cutoff);
+            if (stamps.length >= limit.count) {
+                windows.set(key, stamps);
+                return false;
+            }
+            stamps.push(atMs);
+            windows.set(key, stamps);
+            return true;
+        },
+    };
+}
+const BUILTIN_CHANNELS = [
+    { id: "global", kind: "global" },
+    { id: "party", kind: "party" },
+    { id: "proximity", kind: "proximity", radius: DEFAULT_PROXIMITY_CHAT_RADIUS },
+];
+export function createChat(deps) {
+    const now = deps.now ?? Date.now;
+    const events = deps.events;
+    const maxBodyLength = deps.maxBodyLength ?? DEFAULT_CHAT_BODY_LENGTH;
+    const defaultRateLimit = deps.defaultRateLimit ?? DEFAULT_CHAT_RATE_LIMIT;
+    const blockedBy = deps.blockedBy ?? (() => []);
+    const channelDefs = new Map();
+    for (const def of BUILTIN_CHANNELS)
+        channelDefs.set(def.id, { ...def });
+    const messagesByChannel = new Map();
+    const limiters = new Map();
+    let counter = 0;
+    function limiterFor(channelId, rateLimit) {
+        let limiter = limiters.get(channelId);
+        if (limiter === undefined) {
+            limiter = createChatRateLimiter(rateLimit);
+            limiters.set(channelId, limiter);
+        }
+        return limiter;
+    }
+    function hasBlocked(userId, targetUserId) {
+        return blockedBy(userId).includes(targetUserId);
+    }
+    function resolveRecipients(fromUserId, channelId, def) {
+        if (channelId.startsWith(WHISPER_CHANNEL_PREFIX)) {
+            const pair = channelId.slice(WHISPER_CHANNEL_PREFIX.length).split(":");
+            const toUserId = pair.find((userId) => userId !== fromUserId);
+            if (pair.length !== 2 || toUserId === undefined || !pair.includes(fromUserId)) {
+                return { reason: "not a participant of this whisper" };
+            }
+            if (hasBlocked(toUserId, fromUserId) || hasBlocked(fromUserId, toUserId)) {
+                return { reason: "blocked" };
+            }
+            return { recipients: [toUserId] };
+        }
+        if (def === null)
+            return { reason: `unknown channel "${channelId}"` };
+        if (def.kind === "global")
+            return { recipients: "all" };
+        if (def.kind === "party") {
+            const members = deps.party?.membersOf(fromUserId) ?? [];
+            if (!members.includes(fromUserId))
+                return { reason: "not in a party" };
+            return {
+                recipients: members.filter((userId) => userId !== fromUserId && !hasBlocked(userId, fromUserId)),
+            };
+        }
+        const proximity = deps.proximity;
+        if (proximity === undefined)
+            return { reason: "proximity chat not configured" };
+        const origin = proximity.entities.get(fromUserId);
+        if (origin === null)
+            return { reason: `entity "${fromUserId}" is not spawned` };
+        const nearby = proximity.spatial.inRadius(origin.position, def.radius ?? DEFAULT_PROXIMITY_CHAT_RADIUS, (id) => id !== fromUserId && proximity.entities.get(id)?.role === "player");
+        return { recipients: nearby.filter((userId) => !hasBlocked(userId, fromUserId)) };
+    }
+    function append(channelId, message, historyLimit) {
+        const ring = messagesByChannel.get(channelId) ?? [];
+        ring.push(message);
+        if (ring.length > historyLimit)
+            ring.splice(0, ring.length - historyLimit);
+        messagesByChannel.set(channelId, ring);
+    }
+    function sendResolved(fromUserId, channelId, body, def) {
+        const trimmed = body.trim();
+        if (trimmed.length === 0)
+            return { reason: "empty message" };
+        if (trimmed.length > maxBodyLength)
+            return { reason: "message too long" };
+        const resolved = resolveRecipients(fromUserId, channelId, def);
+        if ("reason" in resolved)
+            return resolved;
+        const at = now();
+        const rateLimit = def?.rateLimit ?? defaultRateLimit;
+        if (!limiterFor(channelId, rateLimit).allow(`${fromUserId}|${channelId}`, at)) {
+            return { reason: "rate limited" };
+        }
+        counter += 1;
+        const message = {
+            id: `msg_${counter}`,
+            channelId,
+            fromUserId,
+            body: trimmed,
+            at,
+        };
+        append(channelId, message, def?.historyLimit ?? DEFAULT_CHAT_HISTORY_LIMIT);
+        const event = { ...message };
+        if (resolved.recipients !== "all")
+            event.recipients = resolved.recipients;
+        events.emit("chat.message", event);
+        return { message, recipients: resolved.recipients };
+    }
+    return {
+        register(def) {
+            channelDefs.set(def.id, { ...def });
+            limiters.delete(def.id);
+        },
+        channels() {
+            return Array.from(channelDefs.values(), (def) => ({ ...def }));
+        },
+        send(fromUserId, channelId, body) {
+            const def = channelDefs.get(channelId) ?? null;
+            return sendResolved(fromUserId, channelId, body, def);
+        },
+        whisper(fromUserId, toUserId, body) {
+            if (fromUserId === toUserId)
+                return { reason: "cannot whisper yourself" };
+            const channelId = whisperChannelId(fromUserId, toUserId);
+            return sendResolved(fromUserId, channelId, body, channelDefs.get(channelId) ?? null);
+        },
+        history(channelId, options) {
+            const ring = messagesByChannel.get(channelId) ?? [];
+            const viewerUserId = options?.viewerUserId;
+            const visible = viewerUserId === undefined
+                ? ring
+                : ring.filter((message) => !hasBlocked(viewerUserId, message.fromUserId));
+            const limit = options?.limit;
+            return limit === undefined ? visible.slice() : visible.slice(-limit);
+        },
+        snapshot() {
+            const messages = {};
+            for (const [channelId, ring] of messagesByChannel) {
+                messages[channelId] = ring.map((message) => ({ ...message }));
+            }
+            return { messages, counter };
+        },
+        hydrate(data) {
+            messagesByChannel.clear();
+            for (const [channelId, ring] of Object.entries(data.messages)) {
+                messagesByChannel.set(channelId, ring.map((message) => ({ ...message })));
+            }
+            counter = data.counter;
+        },
+    };
+}

package/dist/game/defineGame.d.ts

@@ -1,13 +1,15 @@
 import type { ActionCodesMap } from "../input/actionBindings.js";
+import type { GameFeedOptions } from "./feed.js";
 import type { ItemTraits } from "../inventory/inventoryModel.js";
 import type { StorageTier } from "../inventory/storageTier.js";
 import type { SaveConfig } from "../runtime/save.js";
-import type { AssetCatalog, ModelAssetRef } from "../scene/assetCatalog.js";
+import { type AssetCatalog, type ModelAssetRef } from "../scene/assetCatalog.js";
 import { type EntityStore } from "../scene/entityStore.js";
 import type { TimeConfig } from "../time/simClock.js";
 import type { WorldFeature } from "../world/features.js";
 export interface PhysicsConfig {
     gravity?: number;
+    jumpVelocity?: number;
 }
 export interface InventoryDeclaration {
     slots: number;
@@ -35,6 +37,8 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     physics?: PhysicsConfig;
     /** Simulation clock: real→game time scale, selectable speeds, calendar. Exposed as `ctx.time`; the shell feeds its scaled dt to `loop.onTick`. */
     time?: TimeConfig;
+    /** Per-action ring-buffer capacity for `ctx.game.feed`. Default 20. */
+    feed?: GameFeedOptions;
     inventories?: Record<string, InventoryDeclaration>;
     input?: ActionCodesMap;
     server?: GameServerConfig;
@@ -42,5 +46,7 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     ui?: unknown;
     loop?: GameLoop<any>;
 }
-export type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene">;
+export type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets"> & {
+    assets?: AssetCatalog<TAssetRef>;
+};
 export declare function defineGame<TAssetRef extends ModelAssetRef, TMultiplayer>(config: GameDefinitionConfig<TAssetRef, TMultiplayer>): GameDefinition<TAssetRef, TMultiplayer>;

package/dist/game/defineGame.js

@@ -1,7 +1,8 @@
+import { createAssetCatalog } from "../scene/assetCatalog.js";
 import { createEntityStore } from "../scene/entityStore.js";
 export function defineGame(config) {
     if (config.name.trim().length === 0) {
         throw new Error("defineGame: name must be non-empty");
     }
-    return { ...config, scene: createEntityStore() };
+    return { ...config, scene: createEntityStore(), assets: config.assets ?? createAssetCatalog() };
 }

package/dist/game/events.d.ts

@@ -63,6 +63,28 @@ export interface SocialPartyLeftEvent {
     userId: string;
     partyId: string;
 }
+export interface SocialWorldInvitedEvent {
+    inviteId: string;
+    fromUserId: string;
+    toUserId: string;
+    serverId: string;
+    joinCode?: string;
+}
+export interface SocialWorldAcceptedEvent {
+    inviteId: string;
+    userId: string;
+    fromUserId: string;
+    serverId: string;
+    joinCode?: string;
+}
+export interface ChatMessageEvent {
+    id: string;
+    channelId: string;
+    fromUserId: string;
+    body: string;
+    at: number;
+    recipients?: readonly string[];
+}
 export interface StatLevelUpEvent {
     userId: string;
     stat: string;
@@ -147,6 +169,9 @@ export interface GameEventMap {
     "social.friend.added": SocialFriendAddedEvent;
     "social.party.joined": SocialPartyJoinedEvent;
     "social.party.left": SocialPartyLeftEvent;
+    "social.world.invited": SocialWorldInvitedEvent;
+    "social.world.accepted": SocialWorldAcceptedEvent;
+    "chat.message": ChatMessageEvent;
     "stat.levelUp": StatLevelUpEvent;
     "projectile.settled": ProjectileSettledEvent;
     "worldItem.dropped": WorldItemDroppedEvent;

package/dist/game/levelSequence.d.ts

@@ -0,0 +1,44 @@
+export interface LevelDescriptor<TLevelConfig> {
+    id: string;
+    config: TLevelConfig;
+}
+export interface LevelSequenceConfig<TLevelConfig> {
+    levels: readonly LevelDescriptor<TLevelConfig>[];
+    /** Extra attempts granted after the first per level. Defaults to 0 (a single attempt, no retries). */
+    retriesPerLevel?: number;
+}
+export type LevelSequenceStatus = "idle" | "playing" | "cleared" | "failed" | "complete";
+export interface CurrentLevel<TLevelConfig> {
+    id: string;
+    index: number;
+    config: TLevelConfig;
+    attempt: number;
+}
+export interface LevelSequenceProgress {
+    index: number;
+    total: number;
+    cleared: readonly string[];
+}
+export interface LevelSequence<TLevelConfig> {
+    current(): CurrentLevel<TLevelConfig> | null;
+    status(): LevelSequenceStatus;
+    /** Enters level 0. A no-op on an empty level list, which leaves `status()` at "idle" forever. */
+    start(): void;
+    /** Marks the current level cleared; call `advance()` to move to the next one. */
+    clear(): void;
+    /** Consumes an attempt on the current level. Returns "retry" while attempts remain, else "failed". */
+    fail(): "retry" | "failed";
+    /** Restarts the current level after a "retry"-eligible failure. Returns false if there was nothing to retry. */
+    retry(): boolean;
+    /** Moves past a cleared level, or to "complete" if it was the last one. Returns false unless status is "cleared". */
+    advance(): boolean;
+    reset(): void;
+    progress(): LevelSequenceProgress;
+}
+/**
+ * A pure, deterministic level campaign: an ordered list of levels, each with its own opaque config, played
+ * through a `start` → (`clear` → `advance`)* → `complete` happy path, with `fail`/`retry` handling per-level
+ * attempts. Mirrors the reducer style of `game/race.ts` and `ai/spawnDirector.ts` — no I/O, no timers, just
+ * state transitions driven by the caller.
+ */
+export declare function createLevelSequence<TLevelConfig>(config: LevelSequenceConfig<TLevelConfig>): LevelSequence<TLevelConfig>;

package/dist/game/levelSequence.js

@@ -0,0 +1,78 @@
+/**
+ * A pure, deterministic level campaign: an ordered list of levels, each with its own opaque config, played
+ * through a `start` → (`clear` → `advance`)* → `complete` happy path, with `fail`/`retry` handling per-level
+ * attempts. Mirrors the reducer style of `game/race.ts` and `ai/spawnDirector.ts` — no I/O, no timers, just
+ * state transitions driven by the caller.
+ */
+export function createLevelSequence(config) {
+    const levels = config.levels;
+    const maxAttempts = 1 + Math.max(0, Math.floor(config.retriesPerLevel ?? 0));
+    let index = 0;
+    let attempt = 1;
+    let status = "idle";
+    const clearedIds = [];
+    function current() {
+        if (status === "idle" || status === "complete")
+            return null;
+        const level = levels[index];
+        if (level === undefined)
+            return null;
+        return { id: level.id, index, config: level.config, attempt };
+    }
+    return {
+        current,
+        status: () => status,
+        start() {
+            if (levels.length === 0)
+                return;
+            index = 0;
+            attempt = 1;
+            clearedIds.length = 0;
+            status = "playing";
+        },
+        clear() {
+            if (status !== "playing" || current() === null)
+                return;
+            clearedIds.push(levels[index].id);
+            status = "cleared";
+        },
+        fail() {
+            if (status !== "playing" || current() === null)
+                return "failed";
+            status = "failed";
+            return attempt < maxAttempts ? "retry" : "failed";
+        },
+        retry() {
+            if (status !== "failed" || attempt >= maxAttempts)
+                return false;
+            attempt += 1;
+            status = "playing";
+            return true;
+        },
+        advance() {
+            if (status !== "cleared")
+                return false;
+            if (index >= levels.length - 1) {
+                status = "complete";
+                return true;
+            }
+            index += 1;
+            attempt = 1;
+            status = "playing";
+            return true;
+        },
+        reset() {
+            index = 0;
+            attempt = 1;
+            clearedIds.length = 0;
+            status = "idle";
+        },
+        progress() {
+            return {
+                index: status === "complete" ? levels.length : index,
+                total: levels.length,
+                cleared: [...clearedIds],
+            };
+        },
+    };
+}