@jgengine/core 0.1.0

package/dist/game/playableGame.d.ts

@@ -0,0 +1,55 @@
+import type { GameContext, GameContextContent } from "../runtime/gameContext.js";
+import type { GameDefinition, GameLoop } from "./defineGame.js";
+export interface CameraFollowState {
+    entityId: string;
+    target: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    camera: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    distance: number;
+}
+export interface GameCameraConfig {
+    minDistance?: number;
+    maxDistance?: number;
+    targetHeight?: number;
+    /** Extra offset on top of entity position for the orbit target. */
+    targetOffset?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    initialDistance?: number;
+    initialHeight?: number;
+    /** Lock orbit radius while the follow target moves (default true in shell). */
+    followLock?: boolean;
+    /** When false, orbit target stays fixed (cinematic / debug). Default true. */
+    followEnabled?: boolean;
+    /** Instance id to follow; defaults to local player in the dev shell. */
+    followEntityId?: string;
+    /** Fired each frame after cameraFollow lock is applied. */
+    onCameraFollow?: (state: CameraFollowState) => void;
+    rotateSpeed?: number;
+    zoomSpeed?: number;
+    dampingFactor?: number;
+    targetSmoothing?: number;
+    dragTargetSmoothing?: number;
+    distanceSmoothing?: number;
+}
+export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown> {
+    game: GameDefinition;
+    content: GameContextContent;
+    loop: Required<GameLoop<GameContext>>;
+    GameUI: TUi;
+    /** Optional canvas-layer VFX component (e.g. traveling projectiles). */
+    WorldOverlay?: TWorldOverlay;
+    /** Optional scroll-selected hotbar index for primary ability (mouse0). */
+    hotbarSelection?: () => number;
+    /** Third-person orbit camera tuning for the dev game player shell. */
+    camera?: GameCameraConfig;
+}

package/dist/game/playableGame.js

@@ -0,0 +1 @@
+export {};

package/dist/game/quest.d.ts

@@ -0,0 +1,93 @@
+import type { GameEvents } from "./events.js";
+export interface QuestObjective {
+    id: string;
+    kind: "kill" | "collect" | string;
+    target?: string;
+    item?: string;
+    count: number;
+    partyShare?: {
+        radius: number;
+        credit: "all" | "tagger";
+    };
+}
+export interface QuestRewards {
+    xp?: {
+        amount: number;
+    };
+    economy?: Record<string, number>;
+    items?: {
+        item: string;
+        count: number;
+        inventory: string;
+    }[];
+    unlocks?: string[];
+    quests?: string[];
+}
+export interface QuestDef {
+    id: string;
+    title: string;
+    description?: string;
+    giver?: string;
+    turnIn?: string;
+    requires?: string[];
+    objectives: QuestObjective[];
+    rewards?: QuestRewards;
+}
+export type QuestStatus = "active" | "completed";
+export interface QuestObjectiveProgress {
+    id: string;
+    kind: string;
+    count: number;
+    progress: number;
+    complete: boolean;
+}
+export interface QuestInstance {
+    questId: string;
+    status: QuestStatus;
+    objectives: QuestObjectiveProgress[];
+}
+export type QuestSnapshotEntry = {
+    questId: string;
+    status: QuestStatus;
+    progress: Record<string, number>;
+};
+export interface QuestJournalDeps {
+    events: GameEvents;
+    rewards: {
+        grantXp(userId: string, amount: number): void;
+        grantEconomy(userId: string, currencyId: string, amount: number): void;
+        grantItem(userId: string, inventoryId: string, itemId: string, count: number): {
+            reason: string;
+        } | null;
+        grantUnlock(userId: string, unlockId: string): void;
+    };
+    hasUnlock?(userId: string, id: string): boolean;
+    partyMembersNear?(userId: string, radius: number): string[];
+}
+export interface QuestJournal {
+    register(catalog: QuestDef[] | Record<string, QuestDef>): void;
+    has(questId: string): boolean;
+    canAccept(userId: string, questId: string): {
+        reason: string;
+    } | null;
+    accept(userId: string, questId: string): {
+        reason: string;
+    } | null;
+    abandon(userId: string, questId: string): void;
+    progress(userId: string, questId: string, objectiveId: string, delta: number): void;
+    canTurnIn(userId: string, questId: string): {
+        reason: string;
+    } | null;
+    turnIn(userId: string, questId: string): {
+        reason: string;
+    } | null;
+    grant(userId: string, questId: string, options?: {
+        completed?: boolean;
+    }): void;
+    revoke(userId: string, questId: string): void;
+    list(userId: string): QuestInstance[];
+    bind(action: "entity.died" | "inventory.added"): () => void;
+    snapshot(userId: string): QuestSnapshotEntry[];
+    hydrate(userId: string, data: QuestSnapshotEntry[]): void;
+}
+export declare function createQuestJournal(deps: QuestJournalDeps): QuestJournal;

package/dist/game/quest.js

@@ -0,0 +1,228 @@
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+export function createQuestJournal(deps) {
+    const catalog = new Map();
+    const users = new Map();
+    function requireUserQuests(userId) {
+        let quests = users.get(userId);
+        if (!quests) {
+            quests = new Map();
+            users.set(userId, quests);
+        }
+        return quests;
+    }
+    function requirementMet(userId, requirementId) {
+        if (users.get(userId)?.get(requirementId)?.status === "completed")
+            return true;
+        return deps.hasUnlock?.(userId, requirementId) ?? false;
+    }
+    function canAccept(userId, questId) {
+        const def = catalog.get(questId);
+        if (def === undefined)
+            return { reason: `unknown quest "${questId}"` };
+        const state = users.get(userId)?.get(questId);
+        if (state?.status === "active")
+            return { reason: `quest "${questId}" already active` };
+        if (state?.status === "completed")
+            return { reason: `quest "${questId}" already completed` };
+        for (const requirementId of def.requires ?? []) {
+            if (!requirementMet(userId, requirementId)) {
+                return { reason: `quest "${questId}" requires "${requirementId}"` };
+            }
+        }
+        return null;
+    }
+    function accept(userId, questId) {
+        const denied = canAccept(userId, questId);
+        if (denied !== null)
+            return denied;
+        requireUserQuests(userId).set(questId, { status: "active", progress: new Map() });
+        deps.events.emit("quest.accepted", { userId, questId });
+        return null;
+    }
+    function progress(userId, questId, objectiveId, delta) {
+        const def = catalog.get(questId);
+        const state = users.get(userId)?.get(questId);
+        if (def === undefined || state === undefined || state.status !== "active")
+            return;
+        const objective = def.objectives.find((candidate) => candidate.id === objectiveId);
+        if (objective === undefined)
+            return;
+        const previous = state.progress.get(objectiveId) ?? 0;
+        const next = clamp(previous + delta, 0, objective.count);
+        if (next === previous)
+            return;
+        state.progress.set(objectiveId, next);
+        deps.events.emit("quest.updated", { userId, questId, objectiveId, progress: next });
+    }
+    function canTurnIn(userId, questId) {
+        const def = catalog.get(questId);
+        if (def === undefined)
+            return { reason: `unknown quest "${questId}"` };
+        const state = users.get(userId)?.get(questId);
+        if (state === undefined || state.status !== "active") {
+            return { reason: `quest "${questId}" is not active` };
+        }
+        for (const objective of def.objectives) {
+            if ((state.progress.get(objective.id) ?? 0) < objective.count) {
+                return { reason: `objective "${objective.id}" incomplete` };
+            }
+        }
+        return null;
+    }
+    function applyRewards(userId, rewards) {
+        if (rewards.xp)
+            deps.rewards.grantXp(userId, rewards.xp.amount);
+        for (const [currencyId, amount] of Object.entries(rewards.economy ?? {})) {
+            deps.rewards.grantEconomy(userId, currencyId, amount);
+        }
+        for (const entry of rewards.items ?? []) {
+            deps.rewards.grantItem(userId, entry.inventory, entry.item, entry.count);
+        }
+        for (const unlockId of rewards.unlocks ?? []) {
+            deps.rewards.grantUnlock(userId, unlockId);
+        }
+    }
+    function turnIn(userId, questId) {
+        const denied = canTurnIn(userId, questId);
+        if (denied !== null)
+            return denied;
+        const def = catalog.get(questId);
+        const state = users.get(userId).get(questId);
+        state.status = "completed";
+        if (def.rewards)
+            applyRewards(userId, def.rewards);
+        deps.events.emit("quest.completed", { userId, questId });
+        for (const nextQuestId of def.rewards?.quests ?? []) {
+            if (canAccept(userId, nextQuestId) === null)
+                accept(userId, nextQuestId);
+        }
+        return null;
+    }
+    function creditKill(killerUserId, catalogId) {
+        for (const def of catalog.values()) {
+            for (const objective of def.objectives) {
+                if (objective.kind !== "kill" || objective.target !== catalogId)
+                    continue;
+                const recipients = new Set([killerUserId]);
+                if (objective.partyShare?.credit === "all" && deps.partyMembersNear) {
+                    for (const member of deps.partyMembersNear(killerUserId, objective.partyShare.radius)) {
+                        recipients.add(member);
+                    }
+                }
+                for (const userId of recipients)
+                    progress(userId, def.id, objective.id, 1);
+            }
+        }
+    }
+    function creditCollect(userId, itemId, count) {
+        for (const def of catalog.values()) {
+            for (const objective of def.objectives) {
+                if (objective.kind !== "collect" || objective.item !== itemId)
+                    continue;
+                progress(userId, def.id, objective.id, count);
+            }
+        }
+    }
+    return {
+        register(defs) {
+            const entries = Array.isArray(defs) ? defs : Object.values(defs);
+            for (const def of entries)
+                catalog.set(def.id, def);
+        },
+        has(questId) {
+            return catalog.has(questId);
+        },
+        canAccept,
+        accept,
+        abandon(userId, questId) {
+            const quests = users.get(userId);
+            if (quests?.get(questId)?.status === "active")
+                quests.delete(questId);
+        },
+        progress,
+        canTurnIn,
+        turnIn,
+        grant(userId, questId, options) {
+            const def = catalog.get(questId);
+            if (def === undefined)
+                return;
+            const completed = options?.completed ?? false;
+            const progressMap = new Map();
+            if (completed) {
+                for (const objective of def.objectives)
+                    progressMap.set(objective.id, objective.count);
+            }
+            requireUserQuests(userId).set(questId, {
+                status: completed ? "completed" : "active",
+                progress: progressMap,
+            });
+            if (completed)
+                deps.events.emit("quest.completed", { userId, questId });
+            else
+                deps.events.emit("quest.accepted", { userId, questId });
+        },
+        revoke(userId, questId) {
+            users.get(userId)?.delete(questId);
+        },
+        list(userId) {
+            const quests = users.get(userId);
+            if (!quests)
+                return [];
+            const instances = [];
+            for (const [questId, state] of quests) {
+                const def = catalog.get(questId);
+                if (def === undefined)
+                    continue;
+                instances.push({
+                    questId,
+                    status: state.status,
+                    objectives: def.objectives.map((objective) => {
+                        const current = state.progress.get(objective.id) ?? 0;
+                        return {
+                            id: objective.id,
+                            kind: objective.kind,
+                            count: objective.count,
+                            progress: current,
+                            complete: current >= objective.count,
+                        };
+                    }),
+                });
+            }
+            return instances;
+        },
+        bind(action) {
+            if (action === "entity.died") {
+                return deps.events.on("entity.died", (event) => {
+                    if (event.reason.kind !== "player_kill")
+                        return;
+                    creditKill(event.reason.killerUserId, event.catalogId);
+                });
+            }
+            return deps.events.on("inventory.added", (event) => {
+                creditCollect(event.userId, event.item, event.count);
+            });
+        },
+        snapshot(userId) {
+            const quests = users.get(userId);
+            if (!quests)
+                return [];
+            return Array.from(quests, ([questId, state]) => ({
+                questId,
+                status: state.status,
+                progress: Object.fromEntries(state.progress),
+            }));
+        },
+        hydrate(userId, data) {
+            const quests = new Map();
+            for (const entry of data) {
+                quests.set(entry.questId, {
+                    status: entry.status,
+                    progress: new Map(Object.entries(entry.progress)),
+                });
+            }
+            users.set(userId, quests);
+        },
+    };
+}

package/dist/game/social.d.ts

@@ -0,0 +1,78 @@
+import type { GameEvents } from "./events.js";
+export interface PresenceInfo {
+    online: boolean;
+    serverId?: string;
+    zoneId?: string;
+    instanceId?: string;
+}
+export interface SocialDeps {
+    events: GameEvents;
+    presence?: (userId: string) => PresenceInfo;
+    now?: () => number;
+}
+export interface FriendEntry {
+    userId: string;
+    online: boolean;
+}
+export interface FriendsSnapshot {
+    friends: string[];
+    blocked: string[];
+}
+export interface Friends {
+    canRequest(fromUserId: string, toUserId: string): {
+        reason: string;
+    } | null;
+    request(fromUserId: string, toUserId: string): {
+        requestId: string;
+    } | {
+        reason: string;
+    };
+    accept(userId: string, requestId: string): {
+        reason: string;
+    } | null;
+    remove(userId: string, friendUserId: string): void;
+    block(userId: string, targetUserId: string): void;
+    list(userId: string): FriendEntry[];
+    snapshot(userId: string): FriendsSnapshot;
+    hydrate(userId: string, data: FriendsSnapshot): void;
+}
+export type PartyRole = "leader" | "member";
+export interface PartyMemberEntry {
+    userId: string;
+    role: PartyRole;
+}
+export interface PartyConfig {
+    maxMembers: number;
+    inviteTtlMs?: number;
+}
+export interface Party {
+    register(config: PartyConfig): void;
+    canInvite(fromUserId: string, toUserId: string): {
+        reason: string;
+    } | null;
+    invite(fromUserId: string, toUserId: string): {
+        inviteId: string;
+    } | {
+        reason: string;
+    };
+    accept(userId: string, inviteId: string): {
+        reason: string;
+    } | null;
+    kick(leaderUserId: string, memberUserId: string): {
+        reason: string;
+    } | null;
+    leave(userId: string): void;
+    promote(leaderUserId: string, memberUserId: string): {
+        reason: string;
+    } | null;
+    list(userId: string): PartyMemberEntry[];
+    membersOf(userId: string): string[];
+}
+export interface Social {
+    friends: Friends;
+    party: Party;
+    presence: {
+        get(userId: string): PresenceInfo;
+    };
+}
+export declare function createSocial(deps: SocialDeps): Social;

package/dist/game/social.js

@@ -0,0 +1,227 @@
+const DEFAULT_INVITE_TTL_MS = 60_000;
+export function createSocial(deps) {
+    const now = deps.now ?? Date.now;
+    const events = deps.events;
+    const friendships = new Map();
+    const blocked = new Map();
+    const friendRequests = new Map();
+    let requestCounter = 0;
+    function requireSet(map, userId) {
+        let set = map.get(userId);
+        if (!set) {
+            set = new Set();
+            map.set(userId, set);
+        }
+        return set;
+    }
+    function pendingBetween(a, b) {
+        for (const request of friendRequests.values()) {
+            if ((request.from === a && request.to === b) || (request.from === b && request.to === a))
+                return true;
+        }
+        return false;
+    }
+    function canRequest(fromUserId, toUserId) {
+        if (fromUserId === toUserId)
+            return { reason: "cannot friend yourself" };
+        if (friendships.get(fromUserId)?.has(toUserId))
+            return { reason: "already friends" };
+        if (pendingBetween(fromUserId, toUserId))
+            return { reason: "request already pending" };
+        if (blocked.get(toUserId)?.has(fromUserId) || blocked.get(fromUserId)?.has(toUserId)) {
+            return { reason: "blocked" };
+        }
+        return null;
+    }
+    const friends = {
+        canRequest,
+        request(fromUserId, toUserId) {
+            const denied = canRequest(fromUserId, toUserId);
+            if (denied !== null)
+                return denied;
+            requestCounter += 1;
+            const requestId = `freq_${requestCounter}`;
+            friendRequests.set(requestId, { from: fromUserId, to: toUserId });
+            return { requestId };
+        },
+        accept(userId, requestId) {
+            const request = friendRequests.get(requestId);
+            if (request === undefined)
+                return { reason: `unknown request "${requestId}"` };
+            if (request.to !== userId)
+                return { reason: "request is not addressed to this user" };
+            friendRequests.delete(requestId);
+            requireSet(friendships, request.from).add(request.to);
+            requireSet(friendships, request.to).add(request.from);
+            events.emit("social.friend.added", { userId: request.to, friendUserId: request.from });
+            events.emit("social.friend.added", { userId: request.from, friendUserId: request.to });
+            return null;
+        },
+        remove(userId, friendUserId) {
+            friendships.get(userId)?.delete(friendUserId);
+            friendships.get(friendUserId)?.delete(userId);
+        },
+        block(userId, targetUserId) {
+            requireSet(blocked, userId).add(targetUserId);
+            friends.remove(userId, targetUserId);
+            for (const [requestId, request] of friendRequests) {
+                const between = (request.from === userId && request.to === targetUserId) ||
+                    (request.from === targetUserId && request.to === userId);
+                if (between)
+                    friendRequests.delete(requestId);
+            }
+        },
+        list(userId) {
+            return Array.from(friendships.get(userId) ?? [], (friendUserId) => ({
+                userId: friendUserId,
+                online: deps.presence?.(friendUserId).online ?? false,
+            }));
+        },
+        snapshot(userId) {
+            return {
+                friends: Array.from(friendships.get(userId) ?? []),
+                blocked: Array.from(blocked.get(userId) ?? []),
+            };
+        },
+        hydrate(userId, data) {
+            friendships.set(userId, new Set(data.friends));
+            blocked.set(userId, new Set(data.blocked));
+        },
+    };
+    let partyConfig = null;
+    const parties = new Map();
+    const memberToParty = new Map();
+    const partyInvites = new Map();
+    let partyCounter = 0;
+    let inviteCounter = 0;
+    function partyOf(userId) {
+        const partyId = memberToParty.get(userId);
+        if (partyId === undefined)
+            return null;
+        return parties.get(partyId) ?? null;
+    }
+    function canInvite(fromUserId, toUserId) {
+        if (partyConfig === null)
+            return { reason: "party not configured" };
+        if (fromUserId === toUserId)
+            return { reason: "cannot invite yourself" };
+        if (memberToParty.has(toUserId))
+            return { reason: "already in a party" };
+        const party = partyOf(fromUserId);
+        if (party !== null && party.members.length >= partyConfig.maxMembers) {
+            return { reason: "party full" };
+        }
+        return null;
+    }
+    function addMember(party, userId) {
+        party.members.push(userId);
+        memberToParty.set(userId, party.id);
+        events.emit("social.party.joined", { userId, partyId: party.id });
+    }
+    function removeMember(party, userId) {
+        party.members = party.members.filter((member) => member !== userId);
+        memberToParty.delete(userId);
+        events.emit("social.party.left", { userId, partyId: party.id });
+        if (party.members.length === 0) {
+            parties.delete(party.id);
+            return;
+        }
+        if (party.leader === userId)
+            party.leader = party.members[0];
+    }
+    const party = {
+        register(config) {
+            partyConfig = config;
+        },
+        canInvite,
+        invite(fromUserId, toUserId) {
+            const denied = canInvite(fromUserId, toUserId);
+            if (denied !== null)
+                return denied;
+            inviteCounter += 1;
+            const inviteId = `pinv_${inviteCounter}`;
+            partyInvites.set(inviteId, { from: fromUserId, to: toUserId, createdAt: now() });
+            return { inviteId };
+        },
+        accept(userId, inviteId) {
+            if (partyConfig === null)
+                return { reason: "party not configured" };
+            const invite = partyInvites.get(inviteId);
+            if (invite === undefined)
+                return { reason: `unknown invite "${inviteId}"` };
+            if (invite.to !== userId)
+                return { reason: "invite is not addressed to this user" };
+            const ttlMs = partyConfig.inviteTtlMs ?? DEFAULT_INVITE_TTL_MS;
+            if (now() - invite.createdAt > ttlMs) {
+                partyInvites.delete(inviteId);
+                return { reason: "invite expired" };
+            }
+            if (memberToParty.has(userId))
+                return { reason: "already in a party" };
+            const existing = partyOf(invite.from);
+            if (existing !== null && existing.members.length >= partyConfig.maxMembers) {
+                return { reason: "party full" };
+            }
+            partyInvites.delete(inviteId);
+            if (existing !== null) {
+                addMember(existing, userId);
+                return null;
+            }
+            partyCounter += 1;
+            const created = { id: `party_${partyCounter}`, leader: invite.from, members: [] };
+            parties.set(created.id, created);
+            addMember(created, invite.from);
+            addMember(created, userId);
+            return null;
+        },
+        kick(leaderUserId, memberUserId) {
+            const leaderParty = partyOf(leaderUserId);
+            if (leaderParty === null || leaderParty.leader !== leaderUserId) {
+                return { reason: "not the party leader" };
+            }
+            if (!leaderParty.members.includes(memberUserId) || memberUserId === leaderUserId) {
+                return { reason: "not a member of this party" };
+            }
+            removeMember(leaderParty, memberUserId);
+            return null;
+        },
+        leave(userId) {
+            const current = partyOf(userId);
+            if (current === null)
+                return;
+            removeMember(current, userId);
+        },
+        promote(leaderUserId, memberUserId) {
+            const leaderParty = partyOf(leaderUserId);
+            if (leaderParty === null || leaderParty.leader !== leaderUserId) {
+                return { reason: "not the party leader" };
+            }
+            if (!leaderParty.members.includes(memberUserId)) {
+                return { reason: "not a member of this party" };
+            }
+            leaderParty.leader = memberUserId;
+            return null;
+        },
+        list(userId) {
+            const current = partyOf(userId);
+            if (current === null)
+                return [];
+            return current.members.map((member) => ({
+                userId: member,
+                role: member === current.leader ? "leader" : "member",
+            }));
+        },
+        membersOf(userId) {
+            return partyOf(userId)?.members.slice() ?? [];
+        },
+    };
+    return {
+        friends,
+        party,
+        presence: {
+            get(userId) {
+                return deps.presence?.(userId) ?? { online: false };
+            },
+        },
+    };
+}