@dreadwood-types/types 0.1.0

package/dist/messages.d.ts

@@ -0,0 +1,723 @@
+import type { ChunkCoord, ChunkData, NpcKind, WorldEntity } from './constants.js';
+import type { CharacterAppearance } from './appearance.js';
+import type { ClientConfig, PartialClientConfig } from './clientConfig.js';
+import type { QuestId, QuestReward, QuestsSnapshot } from './quests.js';
+import type { EquipmentSlots } from './equipment.js';
+import type { WorldZoneId } from './zones.js';
+export type { WorldZoneId } from './zones.js';
+export type Vec2 = {
+    x: number;
+    y: number;
+};
+export type CharacterStats = {
+    health: number;
+    healthMax: number;
+    combat: number;
+    strength: number;
+    /** Melee power skill; paired with Mastery for attack effectiveness. */
+    archery: number;
+    /** Shared weapon-use skill. Shown to players as Mastery. */
+    precision: number;
+    fishing: number;
+    cooking: number;
+    foraging: number;
+    woodwork: number;
+    explorer: number;
+    combatXp: number;
+    strengthXp: number;
+    archeryXp: number;
+    precisionXp: number;
+    fishingXp: number;
+    cookingXp: number;
+    foragingXp: number;
+    woodworkXp: number;
+    explorerXp: number;
+};
+/** The currently selected combat training style. */
+export type CombatStance = 'strength' | 'archery' | 'mastery' | 'balanced';
+export declare function defaultCombatStance(): CombatStance;
+export declare function normalizeCombatStance(raw: unknown): CombatStance;
+export declare function defaultCharacterStats(): CharacterStats;
+export type PlayerPublic = {
+    id: string;
+    name: string;
+    color: string;
+    x: number;
+    y: number;
+    appearance: CharacterAppearance;
+    health: number;
+    healthMax: number;
+    level: number;
+    fishing?: boolean;
+    /**
+     * Which tackle the fishing pose should show. Pond fishing is a scoop net;
+     * lake fishing (perch/tench) is the small rod, which previously also drew a
+     * net — so casting for perch looked like scooping frogs.
+     */
+    fishingGear?: 'net' | 'rod';
+    /**
+     * World point this player should visually face, e.g. the water they are
+     * casting at. Same field pair NpcPublic already uses to aim Old Tom at the
+     * pond; without it an angler faces wherever they happened to stop walking.
+     */
+    faceX?: number;
+    faceY?: number;
+    woodwork?: boolean;
+    woodcutTarget?: string;
+    /** Repeating woodcraft at a work bench (knife-on-wood pose). */
+    carving?: boolean;
+    weapon?: string;
+    boots?: string;
+    gloves?: string;
+    helmet?: string;
+    top?: string;
+    bottom?: string;
+    offhand?: string;
+    path?: Vec2[];
+    /**
+     * Pet trailing this player, visible to everyone. Server-driven so other
+     * players see your beagle follow you; absent while dismissed to the bank.
+     */
+    companion?: CompanionPublic | null;
+};
+/** A player's pet, positioned by the server like a miniature NPC. */
+export type CompanionPublic = {
+    kind: 'beagle';
+    name: string;
+    x: number;
+    y: number;
+};
+export type NpcPublic = {
+    id: string;
+    kind: NpcKind;
+    name?: string;
+    x: number;
+    y: number;
+    level: number;
+    health: number;
+    healthMax: number;
+    /** Optional visual scale for special encounter variants. */
+    scale?: number;
+    inCombat: boolean;
+    path?: Vec2[];
+    speed?: number;
+    /** Optional world-space point this NPC should visually face (e.g. Old Tom facing pond water). */
+    faceX?: number;
+    faceY?: number;
+};
+export type CombatEndReason = 'victory' | 'defeat' | 'fled' | 'target_gone';
+export type CombatTargetKind = 'player' | 'npc';
+export type LootItem = {
+    kind: string;
+    qty: number;
+};
+export type InventorySlot = {
+    kind: string;
+    qty: number;
+    /** Craft quality for weapons (woodwork level when carved). */
+    precision?: number;
+};
+export type ItemAction = 'eat' | 'drop' | 'equip' | 'unequip';
+/**
+ * A shop listing a player can buy. Normally costed in gold via `price`, but a
+ * listing can instead be a barter (e.g. Wilson's rod-for-maggots trade) by
+ * setting `costKind`/`costQty` to an item cost — `price` is ignored then.
+ */
+export type ShopBuyEntry = {
+    kind: string;
+    price: number;
+    qty: number;
+    costKind?: string;
+    costQty?: number;
+};
+export type ShopSellEntry = {
+    kind: string;
+    price: number;
+};
+export type JoinRejectedReason = 'name_taken' | 'invalid_name';
+/**
+ * `reward` is for "you just gained something" moments — landing a fish, and
+ * anything else worth a beat of celebration. Distinct from `quiet` (which is a
+ * plain grey chat line and was where catches used to land, so they slid past
+ * unnoticed) and from the default gold notice, which is used for routine
+ * information.
+ */
+export type NoticeStyle = 'warning' | 'quiet' | 'combat' | 'reward' | 'area' | 'quest';
+export type LevelUpSkill = 'combat' | 'strength' | 'archery' | 'precision' | 'fishing' | 'cooking' | 'foraging' | 'woodwork' | 'explorer';
+export declare function skillDisplayName(skill: LevelUpSkill): string;
+export type TradeOfferSlot = {
+    kind: string;
+    qty: number;
+};
+export type TradeSessionSnapshot = {
+    partnerId: string;
+    partnerName: string;
+    you: TradeOfferSlot[];
+    them: TradeOfferSlot[];
+    youLocked: boolean;
+    themLocked: boolean;
+    youAccepted: boolean;
+    themAccepted: boolean;
+};
+export type DuelStakeSnapshot = {
+    partnerId: string;
+    partnerName: string;
+    you: TradeOfferSlot[];
+    them: TradeOfferSlot[];
+    youLocked: boolean;
+    themLocked: boolean;
+    phase: 'staking' | 'fighting';
+};
+/** Client SFX keys for trade/duel events (filenames under assets/audio/). */
+export type TradeDuelSfx = 'sending_trade_request' | 'trade_started' | 'item_put_up_for_trade' | 'trade_locked_in' | 'trade_completed' | 'duel_request_sent' | 'duel_accepted' | 'item_put_up_as_stake' | 'stake_screen_locked' | 'stake_starting' | 'stake_won' | 'stake_lost';
+/** Client SFX keys for the Rat Tunnel dungeon (filenames under assets/audio/). */
+export type DungeonSfx = 'enter_dungeon' | 'exit_dungeon' | 'gate_open' | 'gate_close' | 'door_open' | 'door_close' | 'rare_monster_alert_battle' | 'boss_victory' | 'area_effect_start' | 'area_effect_end';
+/** Client SFX keys for building and crafting (filenames under assets/audio/). */
+export type CraftSfx = 'workbench_build' | 'workbench_carve' | 'item_crafted' | 'torch_light';
+/** All server-broadcastable one-shot SFX keys. */
+export type ClientSfx = TradeDuelSfx | DungeonSfx | CraftSfx;
+export type ClientMessage = 
+/**
+ * `sessionToken` + `characterId` are used by account-backed entry points
+ * (including TikTok). The server verifies both before loading the character;
+ * name-only joins remain for legacy/browser guests.
+ */
+{
+    type: 'join';
+    name?: string;
+    appearance: CharacterAppearance;
+    sessionToken?: string;
+    characterId?: string;
+} | {
+    type: 'move';
+    x: number;
+    y: number;
+} | {
+    type: 'ping';
+    t: number;
+} | {
+    type: 'chunk_request';
+    chunks: ChunkCoord[];
+} | {
+    type: 'chat';
+    text: string;
+} | {
+    type: 'pm';
+    to: string;
+    text: string;
+} | {
+    type: 'friend_add';
+    name: string;
+} | {
+    type: 'friend_remove';
+    name: string;
+} | {
+    type: 'config';
+    config: PartialClientConfig;
+} | {
+    type: 'pickup';
+    entityId: string;
+} | {
+    type: 'attack';
+    targetId: string;
+} | {
+    type: 'set_combat_stance';
+    stance: CombatStance;
+}
+/**
+ * `slot` is the bag index the player actually clicked. Stacks are capped per
+ * slot, so the same kind can occupy several slots; without this the server
+ * always consumed the first matching stack, which is not the one that was
+ * clicked. Optional so older clients keep working (they get the old
+ * first-match behaviour).
+ */
+ | {
+    type: 'item_action';
+    item: string;
+    action: ItemAction;
+    qty?: number;
+    slot?: number;
+} | {
+    type: 'cook_start';
+    input: string;
+    qty: number;
+} | {
+    type: 'woodcraft_open';
+    entityId: string;
+} | {
+    type: 'woodcraft_make';
+    recipe: string;
+    qty: number;
+} | {
+    type: 'cook_cancel';
+} | {
+    type: 'shop_open';
+    npcId: string;
+} | {
+    type: 'shop_sell';
+    item: string;
+    qty: number;
+} | {
+    type: 'shop_buy';
+    item: string;
+    qty: number;
+} | {
+    type: 'bank_open';
+    entityId: string;
+} | {
+    type: 'bank_close';
+} | {
+    type: 'bank_deposit';
+    tab: number;
+    kind: string;
+    qty: number;
+} | {
+    type: 'bank_withdraw';
+    tab: number;
+    kind: string;
+    qty: number;
+} | {
+    type: 'quest_offer';
+    npcId: string;
+} | {
+    type: 'quest_accept';
+    quest: QuestId;
+} | {
+    type: 'quest_decline';
+    quest: QuestId;
+} | {
+    type: 'npc_action';
+    npcId: string;
+    action: string;
+} | {
+    type: 'use_item';
+    item: string;
+    npcId: string;
+} | {
+    type: 'use_item';
+    item: string;
+    entityId: string;
+} | {
+    type: 'milk_cow';
+    npcId: string;
+} | {
+    type: 'identify';
+    kind: string;
+} | {
+    type: 'fish_start';
+} | {
+    type: 'woodcut_start';
+    entityId: string;
+} | {
+    type: 'trade_request';
+    name: string;
+} | {
+    type: 'trade_respond';
+    accept: boolean;
+} | {
+    type: 'trade_offer';
+    item: string;
+    qty: number;
+} | {
+    type: 'trade_withdraw';
+    item: string;
+    qty: number;
+} | {
+    type: 'trade_lock';
+} | {
+    type: 'trade_accept';
+} | {
+    type: 'trade_cancel';
+} | {
+    type: 'duel_request';
+    name: string;
+} | {
+    type: 'duel_respond';
+    accept: boolean;
+} | {
+    type: 'duel_stake';
+    item: string;
+    qty: number;
+} | {
+    type: 'duel_withdraw';
+    item: string;
+    qty: number;
+} | {
+    type: 'duel_lock';
+} | {
+    type: 'duel_cancel';
+}
+/**
+ * Claims the rescued beagle, or renames one already claimed — the same
+ * message either way, since "name your beagle" and "rename your beagle" are
+ * the same operation to the server.
+ */
+ | {
+    type: 'upgrade_member';
+} | {
+    type: 'beagle_claim';
+    name: string;
+} | {
+    type: 'beagle_summon';
+} | {
+    type: 'beagle_dismiss';
+} | {
+    type: 'beagle_bark';
+}
+/** Feeds the pet one cooked item, the same way the quest beagle is fed. */
+ | {
+    type: 'beagle_feed';
+} | {
+    type: 'client_error';
+    report: ClientErrorReport;
+};
+/** Crash/error diagnostics pushed from client to server so they land in server logs
+ *  instead of only a phone's on-device console (which on TikTok can miss early boot
+ *  output — see crashDiagnostics.ts on the client). Best-effort, not persisted server-side. */
+export type ClientErrorReport = {
+    reason: string;
+    message?: string;
+    stack?: string;
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+    elapsedSec?: number;
+    breadcrumbs?: string[];
+    scene?: Record<string, unknown>;
+    webglEvents?: Array<{
+        t: number;
+        type: 'lost' | 'restored';
+        statusMessage?: string;
+    }>;
+    samples?: Array<Record<string, unknown>>;
+    recoveryRan?: boolean;
+    resumeAttempt?: number;
+};
+export type ServerMessage = {
+    type: 'welcome';
+    selfId: string;
+    originChunk: ChunkCoord;
+    chunks: ChunkData[];
+    players: PlayerPublic[];
+    npcs: NpcPublic[];
+    config: ClientConfig;
+    stats: CharacterStats;
+    friends: string[];
+    inventory: Array<InventorySlot | null>;
+    quests: QuestsSnapshot;
+    equipment: EquipmentSlots;
+    weaponPrecision?: number | null;
+    ammoQty?: number;
+    combatStance?: CombatStance;
+    fishingSpot: Vec2;
+    /** Fixed lake fishing spots (perch / tench). */
+    lakeFishingSpots?: Array<{
+        kind: 'perch' | 'tench';
+        x: number;
+        y: number;
+    }>;
+    /** Entity kinds this character has identified (server authority). */
+    identified: string[];
+    /** Membership unlocks the pet beagle (and whatever else members get). */
+    isMember?: boolean;
+    /** Null until the rescued beagle has been claimed and named. */
+    beagleName?: string | null;
+    /** True while the beagle is following; false while dismissed to the bank. */
+    beagleOut?: boolean;
+    /** Persistent fox-NPC kill count for Anne's Protect the Rabbits quest. */
+    anneFoxKills?: number;
+    /** Persistent Goblin Soldier kill count for the Battlefield Captain. */
+    captainGoblinKills?: number;
+} | {
+    type: 'join_rejected';
+    reason: JoinRejectedReason;
+    message: string;
+} | {
+    type: 'player_joined';
+    player: PlayerPublic;
+} | {
+    type: 'player_left';
+    id: string;
+} | {
+    type: 'players';
+    players: PlayerPublic[];
+} | {
+    type: 'npcs';
+    npcs: NpcPublic[];
+} | {
+    type: 'pong';
+    t: number;
+} | {
+    type: 'chunk_data';
+    chunks: ChunkData[];
+} | {
+    type: 'chunk_unload';
+    chunks: ChunkCoord[];
+} | {
+    type: 'ground_item_add';
+    cx: number;
+    cz: number;
+    entity: WorldEntity;
+} | {
+    type: 'ground_item_remove';
+    entityId: string;
+}
+/**
+ * One entity changed in place (a gate swinging, a prop restyled). Replaces
+ * just that model; resending the whole chunk makes the client tear down and
+ * respawn every prop around it, which reads as a visible flash.
+ */
+ | {
+    type: 'entity_update';
+    cx: number;
+    cz: number;
+    entity: WorldEntity;
+} | {
+    type: 'chat';
+    id: string;
+    name: string;
+    text: string;
+} | {
+    type: 'pm';
+    from: string;
+    to: string;
+    text: string;
+} | {
+    type: 'friends';
+    names: string[];
+}
+/** Quest hints can also appear above their NPC; popupText keeps the overhead copy brief. */
+ | {
+    type: 'notice';
+    text: string;
+    style?: NoticeStyle;
+    npcId?: string;
+    popupText?: string;
+}
+/** A temporary world effect. Kept generic so future hazards and blessings share the UI. */
+ | {
+    type: 'area_effect';
+    id: string;
+    active: boolean;
+    title: string;
+    detail: string;
+} | {
+    type: 'zone';
+    zone: WorldZoneId;
+} | {
+    type: 'loot';
+    items: LootItem[];
+} | {
+    type: 'item_gift';
+    kind: string;
+} | {
+    type: 'inventory';
+    slots: Array<InventorySlot | null>;
+} | {
+    type: 'player_say';
+    playerId: string;
+    name: string;
+    text: string;
+} | {
+    type: 'ate';
+    kind: string;
+} | {
+    type: 'cooked';
+    output: string;
+    done: number;
+    total: number;
+} | {
+    type: 'crafted';
+    output: string;
+    done: number;
+    total: number;
+} | {
+    type: 'dropped';
+} | {
+    type: 'burrow_disturbed';
+    x: number;
+    y: number;
+}
+/** Server confirmed a kind identification (used when forage level gates the reveal). */
+ | {
+    type: 'identified';
+    kind: string;
+} | {
+    type: 'shop_open';
+    npcId: string;
+    title: string;
+    buy: ShopBuyEntry[];
+    sell: ShopSellEntry[];
+} | {
+    type: 'shop_close';
+} | {
+    type: 'bank_state';
+    tabs: Array<Array<InventorySlot | null>>;
+} | {
+    type: 'bank_close';
+} | {
+    type: 'woodcraft_open';
+    /** Recipes with the player's current eligibility resolved server-side. */
+    recipes: Array<{
+        id: string;
+        output: string;
+        outputQty: number;
+        level: number;
+        xp: number;
+        materials: Array<{
+            kind: string;
+            qty: number;
+            have: number;
+        }>;
+        craftable: boolean;
+    }>;
+    hasKnife: boolean;
+} | {
+    type: 'woodcraft_close';
+} | {
+    type: 'quests';
+    quests: QuestsSnapshot;
+    anneFoxKills?: number;
+    captainGoblinKills?: number;
+} | {
+    type: 'quest_offer';
+    quest: QuestId;
+    npcId: string;
+    title: string;
+    description: string;
+    rewards: QuestReward[];
+} | {
+    type: 'equipment';
+    slots: EquipmentSlots;
+    weaponPrecision?: number | null;
+    ammoQty?: number;
+} | {
+    type: 'combat_stance';
+    stance: CombatStance;
+} | {
+    type: 'npc_celebrate';
+    npcId: string;
+} | {
+    type: 'npc_food_bubble';
+    npcId: string;
+} | {
+    type: 'npc_say';
+    npcId: string;
+    text: string;
+    style?: 'warning';
+} | {
+    type: 'fishing_spot';
+    x: number;
+    y: number;
+} | {
+    type: 'lake_fishing_spots';
+    spots: Array<{
+        kind: 'perch' | 'tench';
+        x: number;
+        y: number;
+    }>;
+} | {
+    type: 'fish_dip';
+} | {
+    type: 'tree_fell';
+    entityId: string;
+}
+/**
+ * Someone worked a dungeon gate. Broadcast to everyone, not just the player
+ * who did it: a gate you personally cannot open should still be seen and
+ * heard being used by someone who can, the same way the battlefield bridge
+ * is crossed in front of players who have not repaired it.
+ */
+ | {
+    type: 'gate_used';
+    entityId: string;
+} | {
+    type: 'stats';
+    stats: CharacterStats;
+} | {
+    type: 'discovery';
+    zone: string;
+    label: string;
+    xp: number;
+} | {
+    type: 'level_up';
+    playerId: string;
+    skill: LevelUpSkill;
+    level: number;
+} | {
+    type: 'npc_flyaway';
+    npcId: string;
+} | {
+    type: 'combat_start';
+    playerId: string;
+    targetId: string;
+    targetKind: CombatTargetKind;
+} | {
+    type: 'combat_hit';
+    attackerId: string;
+    targetId: string;
+    targetKind: CombatTargetKind;
+    damage: number;
+    health: number;
+    healthMax: number;
+    /** Ranged attack flavor — client renders a projectile instead of a melee punch. */
+    projectile?: 'blueberry' | 'arrow';
+} | {
+    type: 'combat_end';
+    playerId: string;
+    targetId: string;
+    targetKind: CombatTargetKind;
+    reason: CombatEndReason;
+} | {
+    type: 'respawn';
+    playerId: string;
+    x: number;
+    y: number;
+    reason: 'defeat';
+} | {
+    type: 'sfx';
+    sound: ClientSfx;
+} | {
+    type: 'trade_invite';
+    fromId: string;
+    fromName: string;
+} | {
+    type: 'trade_open';
+    session: TradeSessionSnapshot;
+} | {
+    type: 'trade_update';
+    session: TradeSessionSnapshot;
+} | {
+    type: 'trade_close';
+    reason: 'completed' | 'cancelled' | 'busy' | 'range' | 'left';
+} | {
+    type: 'duel_invite';
+    fromId: string;
+    fromName: string;
+} | {
+    type: 'duel_open';
+    session: DuelStakeSnapshot;
+} | {
+    type: 'duel_update';
+    session: DuelStakeSnapshot;
+} | {
+    type: 'duel_close';
+    reason: 'completed' | 'cancelled' | 'busy' | 'range' | 'left';
+    outcome?: 'won' | 'lost' | 'cancelled';
+} | {
+    type: 'membership';
+    isMember: boolean;
+}
+/** Pushed whenever the beagle is claimed, renamed, summoned or dismissed. */
+ | {
+    type: 'beagle_state';
+    name: string | null;
+    out: boolean;
+}
+/** Someone patted their beagle — shown over that owner's pet, not your own. */
+ | {
+    type: 'companion_speech';
+    ownerId: string;
+    text: string;
+};
+//# sourceMappingURL=messages.d.ts.map