import { CHUNK_SIZE } from "../../../shared/protocol/constants.js"; import { BlockType } from "../../../shared/definitions/tiles.js"; import { MobId, mobDefinition, mobSpriteName } from "../../../shared/definitions/mobs.js"; import { ItemId, itemDefinition } from "../../../shared/definitions/items.js"; import { isLetterWrittenBy } from "../../../shared/items/letters.js"; import { insertStack, insertStackGrowable, takeFromSlot, normalizeVault } from "../../../shared/items/inventory.js"; import { attachOrigins, normalizeOrigins } from "../../../shared/items/origin.js"; import { advanceCourierFlight } from "../../../shared/courier/flight.js"; import { buildDoorwayGraph, planPortalLegs, buildFallbackLegs, advanceAbstractTravel, poseOnCourierLeg, ensureCourierLegs } from "../../../shared/courier/doorwayGraph.js"; import { GAIT } from "../../../shared/protocol/constants.js"; import { OVERWORLD_ID, normalizeDimensionId } from "../../../shared/world/dimensions.js"; import { decodeChunkBlob } from "../world/chunkData.js"; import { findReservedChequeIndex } from "../items/bags.js"; import { BANK_LETTER_AUTHOR, bankRestNoticeLetterBody, isBankRestNoticeLetter, isCentralExchangeLetter, itemNameForNotice, mergeBankRestNoticeLines, sourceNameForVaultDeposit } from "../../../shared/courier/bankNotice.js"; import { makeSystemLetterStack } from "./systemLetter.js"; export class CourierService { constructor ({ stateDb, worldDb, simulation }) { this.stateDb = stateDb; this.worldDb = worldDb; this.simulation = simulation; this.bankTiles = []; this.bountyOfficeTiles = []; this.doorwayTiles = []; this.doorwayGraph = buildDoorwayGraph([]); this.refreshBankIndex(); this.refreshBountyOfficeIndex(); this.refreshDoorwayIndex(); } refreshBankIndex () { this.bankTiles = this.#listBlockTiles(BlockType.bank); } refreshBountyOfficeIndex () { this.bountyOfficeTiles = this.#listBlockTiles(BlockType.bountyOffice); } refreshDoorwayIndex () { this.doorwayTiles = this.#listDoorwayTiles(); this.doorwayGraph = buildDoorwayGraph(this.doorwayTiles); } #listBlockTiles (typeId) { const revisionId = this.worldDb.getActiveRevisionId(); const tiles = []; for (const coord of this.worldDb.listChunkCoords(revisionId)) { const dim = normalizeDimensionId(coord.dimension_id ?? OVERWORLD_ID); const row = this.worldDb.getChunkVersion(coord.chunk_x, coord.chunk_y, revisionId, dim); if (!row) { continue; } const data = decodeChunkBlob(row.data_blob, this.simulation.settings.defaultGroundTypeId, coord.chunk_x, coord.chunk_y); for (let localY = 0; localY < CHUNK_SIZE; localY++) { for (let localX = 0; localX < CHUNK_SIZE; localX++) { const block = data.blocks[localY * CHUNK_SIZE + localX]; if (block?.typeId !== typeId) { continue; } tiles.push({ tileX: coord.chunk_x * CHUNK_SIZE + localX, tileY: coord.chunk_y * CHUNK_SIZE + localY, dimensionId: dim }); } } } return tiles; } #listDoorwayTiles () { const revisionId = this.worldDb.getActiveRevisionId(); const tiles = []; for (const coord of this.worldDb.listChunkCoords(revisionId)) { const dim = normalizeDimensionId(coord.dimension_id ?? OVERWORLD_ID); const row = this.worldDb.getChunkVersion(coord.chunk_x, coord.chunk_y, revisionId, dim); if (!row) { continue; } const data = decodeChunkBlob(row.data_blob, this.simulation.settings.defaultGroundTypeId, coord.chunk_x, coord.chunk_y); for (let localY = 0; localY < CHUNK_SIZE; localY++) { for (let localX = 0; localX < CHUNK_SIZE; localX++) { const block = data.blocks[localY * CHUNK_SIZE + localX]; if (block?.typeId !== BlockType.doorway) { continue; } const config = block.config && typeof block.config === "object" ? block.config : null; tiles.push({ tileX: coord.chunk_x * CHUNK_SIZE + localX, tileY: coord.chunk_y * CHUNK_SIZE + localY, dimensionId: dim, targetDimensionId: config?.targetDimensionId, targetTileX: config?.tileX, targetTileY: config?.tileY }); } } } return tiles; } nearestBank (tileX, tileY, dimensionId = null) { return this.#nearestTile(this.bankTiles, tileX, tileY, dimensionId); } nearestBountyOffice (tileX, tileY, dimensionId = null) { return this.#nearestTile(this.bountyOfficeTiles, tileX, tileY, dimensionId); } isAdjacentToBountyOffice (tileX, tileY, dimensionId = null) { const dim = dimensionId != null ? normalizeDimensionId(dimensionId) : null; return this.bountyOfficeTiles.some((office) => { if (dim != null && normalizeDimensionId(office.dimensionId ?? OVERWORLD_ID) !== dim) { return false; } return Math.max(Math.abs(office.tileX - tileX), Math.abs(office.tileY - tileY)) <= 1; }); } /** * Prefer same-dimension tiles when dimensionId is set; otherwise / as fallback, nearest overall. */ #nearestTile (tiles, tileX, tileY, dimensionId = null) { if (!tiles.length) { return null; } const dim = dimensionId != null ? normalizeDimensionId(dimensionId) : null; let bestSame = null; let bestSameDist = Infinity; let bestAny = null; let bestAnyDist = Infinity; for (const tile of tiles) { const dist = Math.hypot(tile.tileX - tileX, tile.tileY - tileY); if (dist < bestAnyDist) { bestAnyDist = dist; bestAny = tile; } if (dim != null && normalizeDimensionId(tile.dimensionId ?? OVERWORLD_ID) === dim && dist < bestSameDist) { bestSameDist = dist; bestSame = tile; } } return bestSame ?? bestAny; } /** * Player dispatch: cargo is money or one inventory stack. * destination: { kind: "bank" } | { kind: "player", firstName, lastName } */ dispatchFromPlayer ({ characterId, originTileX, originTileY, originDimensionId = OVERWORLD_ID, destination, cargo }) { const onlineId = this.simulation.characterEntities.get(characterId); const bag = onlineId ? this.simulation.bagOf(onlineId) : this.stateDb.getBag(characterId); if (!bag) { const error = new Error("No bag."); error.userFacing = true; throw error; } let takenCargo; if (cargo?.kind === "item") { const slot = bag.inventory?.[cargo.slotIndex | 0]; if (slot?.itemId === ItemId.blankCheque) { const error = new Error("Blank cheques cannot be sent by pigeon."); error.userFacing = true; throw error; } if (slot?.itemId === ItemId.letter && !isLetterWrittenBy(slot, characterId)) { const error = new Error("You can only send letters you wrote."); error.userFacing = true; throw error; } const taken = takeFromSlot(bag.inventory, cargo.slotIndex | 0, cargo.quantity ?? null); if (!taken.ok || !taken.taken) { const error = new Error("That item is not available."); error.userFacing = true; throw error; } bag.inventory = taken.slots; const stack = taken.taken; if (stack.itemId === ItemId.letter && stack.instance) { stack.instance = { ...stack.instance, opened: false }; } takenCargo = { kind: "item", stack }; } else { const error = new Error("Pigeon cargo must be money or one item stack."); error.userFacing = true; throw error; } const originDim = normalizeDimensionId(originDimensionId); const dest = this.#resolveDestination(destination, originTileX, originTileY, originDim); this.#persistBag(characterId, bag); const transit = this.#insertRoutedTransit({ senderCharacterId: characterId, destinationKind: dest.kind, destinationCharacterId: dest.characterId ?? null, vaultCharacterId: dest.vaultCharacterId ?? null, cargo: takenCargo, originTileX, originTileY, originDimensionId: originDim, destTileX: dest.tileX, destTileY: dest.tileY, destDimensionId: dest.dimensionId }); return { transit, bag }; } /** * Shared entry for system letters (gift / CE / bounty / church / cowardice / …). * Online (not combat-logout): pigeon flies immediately. * Offline / combat-logout: held until the character enters the world. */ enqueueSystemLetter ({ characterId, originTileX, originTileY, originDimensionId = OVERWORLD_ID, authorDisplayName, authorOrganization = null, body, centralExchange = false, bankRestNotice = false }) { const stack = makeSystemLetterStack({ authorDisplayName, authorOrganization, body, centralExchange, bankRestNotice }); return this.dispatchSystemLetter({ characterId, originTileX, originTileY, originDimensionId, stack }); } /** * System letters (gift / CE / bounty): pigeon to the player (inventory; bank if full). * While offline, hold with player destination so login flies from the bank to the character * — never deposit the letter straight into the vault. * Prefer enqueueSystemLetter when building a new system letter from author/body fields. */ dispatchSystemLetter ({ characterId, originTileX, originTileY, originDimensionId = OVERWORLD_ID, stack }) { const recipientId = characterId | 0; const cargo = { kind: "item", stack }; const row = this.stateDb.getCharacter(recipientId); return this.dispatchHeldCargo({ senderCharacterId: recipientId, originTileX, originTileY, originDimensionId, destination: { kind: "player", firstName: row?.first_name ?? "Unknown", lastName: row?.last_name ?? "" }, cargo, vaultCharacterId: recipientId }); } /** * Market / system dispatch already holding cargo (no bag take). * When the recipient is offline, holds delivery until login (CE letters, etc.). * Player-bound holds keep destinationKind "player" even though resolve would route to bank * while offline — on login the pigeon then delivers to the character, not the vault. */ dispatchHeldCargo ({ senderCharacterId, originTileX, originTileY, originDimensionId = OVERWORLD_ID, destination, cargo, vaultCharacterId = null }) { const originDim = normalizeDimensionId(originDimensionId); const recipientId = vaultCharacterId ?? senderCharacterId; if (!this.simulation.isCharacterOnline(recipientId)) { const dest = this.#resolveDestination(destination, originTileX, originTileY, originDim); const intendedKind = destination?.kind === "player" ? "player" : dest.kind; this.stateDb.insertHeldCourierDelivery({ characterId: recipientId, senderCharacterId, originTileX, originTileY, originDimensionId: originDim, destinationKind: intendedKind, destinationCharacterId: dest.characterId ?? recipientId, vaultCharacterId: vaultCharacterId ?? dest.vaultCharacterId ?? recipientId, cargo }); return null; } const dest = this.#resolveDestination(destination, originTileX, originTileY, originDim); return this.#insertRoutedTransit({ senderCharacterId, destinationKind: dest.kind, destinationCharacterId: dest.characterId ?? null, vaultCharacterId: vaultCharacterId ?? dest.vaultCharacterId ?? null, cargo, originTileX, originTileY, originDimensionId: originDim, destTileX: dest.tileX, destTileY: dest.tileY, destDimensionId: dest.dimensionId }); } /** Flush offline-held deliveries and send a bank resting notice when the player enters the world. */ onCharacterEnteredWorld (characterId, tileX, tileY, dimensionId = OVERWORLD_ID) { const enterDim = normalizeDimensionId(dimensionId); for (const held of this.stateDb.listHeldCourierDeliveries(characterId)) { this.stateDb.deleteHeldCourierDelivery(held.holdId); const row = this.stateDb.getCharacter(held.destinationCharacterId ?? characterId); this.dispatchHeldCargo({ senderCharacterId: held.senderCharacterId, originTileX: held.originTileX, originTileY: held.originTileY, originDimensionId: held.originDimensionId ?? OVERWORLD_ID, destination: held.destinationKind === "bank" ? { kind: "bank" } : { kind: "player", firstName: row?.first_name ?? "Unknown", lastName: row?.last_name ?? "" }, cargo: held.cargo, vaultCharacterId: held.vaultCharacterId ?? characterId }); } const noticeTransit = this.#dispatchBankRestNotice(characterId, tileX, tileY, enterDim); void noticeTransit; } step (now, dt) { const events = []; const settings = this.simulation.settings; for (const transit of this.stateDb.listActiveCourierTransits()) { ensureCourierLegs(transit); this.#retargetPlayerDest(transit); ensureCourierLegs(transit); const advancedEvents = this.#advanceTransit(transit, now, dt, settings); events.push(...advancedEvents); } return events; } #insertRoutedTransit ({ senderCharacterId, destinationKind, destinationCharacterId, vaultCharacterId, cargo, originTileX, originTileY, originDimensionId, destTileX, destTileY, destDimensionId }) { const originDim = normalizeDimensionId(originDimensionId); const destDim = normalizeDimensionId(destDimensionId ?? OVERWORLD_ID); const originX = originTileX + 0.5; const originY = originTileY + 0.5; const destX = destTileX + 0.5; const destY = destTileY + 0.5; const legs = this.#planLegs({ fromX: originX, fromY: originY, fromDimensionId: originDim, toX: destX, toY: destY, toDimensionId: destDim }); return this.stateDb.insertCourierTransit({ senderCharacterId, destinationKind, destinationCharacterId, vaultCharacterId, cargo, originX, originY, destX, destY, originDimensionId: originDim, destDimensionId: destDim, legs, legIndex: 0, traveled: 0, status: "in_transit", entityId: null }); } #planLegs ({ fromX, fromY, fromDimensionId, toX, toY, toDimensionId }) { const planned = planPortalLegs({ fromX, fromY, fromDimensionId, toX, toY, toDimensionId, graph: this.doorwayGraph }); if (planned.mode !== "fallback") { return planned.legs; } return buildFallbackLegs({ fromX, fromY, fromDimensionId, toX, toY, toDimensionId, isSimulating: (tileX, tileY, dimensionId) => this.simulation.chunkIsSimulating(tileX, tileY, dimensionId), settings: this.simulation.settings }).legs; } #repathTransit (transit, fromX, fromY, fromDimensionId, toX, toY, toDimensionId) { if (transit.entityId) { this.simulation.despawnEntity(transit.entityId); transit.entityId = null; } transit.originX = fromX; transit.originY = fromY; transit.originDimensionId = normalizeDimensionId(fromDimensionId); transit.destX = toX; transit.destY = toY; transit.destDimensionId = normalizeDimensionId(toDimensionId); transit.legs = this.#planLegs({ fromX, fromY, fromDimensionId: transit.originDimensionId, toX, toY, toDimensionId: transit.destDimensionId }); transit.legIndex = 0; transit.traveled = 0; } #currentPose (transit) { ensureCourierLegs(transit); const leg = transit.legs[transit.legIndex | 0]; const pose = poseOnCourierLeg(leg, transit.traveled); if (pose) { return pose; } if (leg?.kind === "abstract") { return { x: leg.fromX, y: leg.fromY, dimensionId: normalizeDimensionId(leg.fromDimensionId ?? transit.originDimensionId ?? OVERWORLD_ID) }; } return { x: transit.originX, y: transit.originY, dimensionId: normalizeDimensionId(transit.originDimensionId ?? OVERWORLD_ID) }; } #advanceTransit (transit, now, dt, settings) { const events = []; ensureCourierLegs(transit); let remainingDt = Math.max(0, dt); let guard = 0; while (remainingDt > 0 && guard++ < 16) { const leg = transit.legs[transit.legIndex | 0]; if (!leg) { events.push(...this.#deliver(transit, now)); return events; } if (leg.kind === "portal") { transit.traveled = 0; transit.legIndex = (transit.legIndex | 0) + 1; if (transit.entityId) { this.simulation.despawnEntity(transit.entityId); events.push({ type: "entity-despawn", entityId: transit.entityId, tileX: Math.floor(leg.fromX), tileY: Math.floor(leg.fromY), dimensionId: normalizeDimensionId(leg.fromDimensionId ?? OVERWORLD_ID) }); transit.entityId = null; } if ((transit.legIndex | 0) >= transit.legs.length) { events.push(...this.#deliver(transit, now)); return events; } continue; } if (leg.kind === "abstract") { if (transit.entityId) { const pose = this.#currentPose(transit); this.simulation.despawnEntity(transit.entityId); events.push({ type: "entity-despawn", entityId: transit.entityId, tileX: Math.floor(pose.x), tileY: Math.floor(pose.y), dimensionId: pose.dimensionId }); transit.entityId = null; } const advanced = advanceAbstractTravel({ traveled: transit.traveled, distance: leg.distance ?? 0, dt: remainingDt, settings }); transit.traveled = advanced.traveled; transit.updatedAt = now; if (!advanced.arrived) { this.stateDb.updateCourierTransit(transit); return events; } remainingDt = 0; transit.traveled = 0; transit.legIndex = (transit.legIndex | 0) + 1; if ((transit.legIndex | 0) >= transit.legs.length) { events.push(...this.#deliver(transit, now)); return events; } continue; } // fly leg const advanced = advanceCourierFlight({ originX: leg.fromX, originY: leg.fromY, destX: leg.toX, destY: leg.toY, traveled: transit.traveled, dt: remainingDt, settings }); transit.traveled = advanced.traveled; transit.updatedAt = now; if (!advanced.arrived) { events.push(...this.#syncVisiblePigeon(transit, advanced, now, leg)); this.stateDb.updateCourierTransit(transit); return events; } remainingDt = 0; transit.traveled = 0; transit.legIndex = (transit.legIndex | 0) + 1; if ((transit.legIndex | 0) >= transit.legs.length) { events.push(...this.#deliver(transit, now)); return events; } // Despawn at portal approach so next portal/fly starts clean. if (transit.entityId) { this.simulation.despawnEntity(transit.entityId); events.push({ type: "entity-despawn", entityId: transit.entityId, tileX: Math.floor(advanced.x), tileY: Math.floor(advanced.y), dimensionId: normalizeDimensionId(leg.fromDimensionId ?? OVERWORLD_ID) }); transit.entityId = null; } } this.stateDb.updateCourierTransit(transit); return events; } #retargetPlayerDest (transit) { if (transit.destinationKind !== "player" || !transit.destinationCharacterId) { return; } const onlineId = this.simulation.characterEntities.get(transit.destinationCharacterId); if (onlineId) { const pos = this.simulation.positionOf(onlineId); if (!pos) { return; } const destDim = normalizeDimensionId(pos.dimensionId ?? OVERWORLD_ID); const destX = pos.tileX + 0.5; const destY = pos.tileY + 0.5; const prevDim = normalizeDimensionId(transit.destDimensionId ?? OVERWORLD_ID); if (destDim !== prevDim) { const pose = this.#currentPose(transit); this.#repathTransit( transit, pose.x, pose.y, pose.dimensionId, destX, destY, destDim ); return; } transit.destX = destX; transit.destY = destY; transit.destDimensionId = destDim; const lastIdx = transit.legs.length - 1; const last = transit.legs[lastIdx]; if (last?.kind === "fly" && normalizeDimensionId(last.toDimensionId ?? destDim) === destDim) { const oldToX = last.toX; const oldToY = last.toY; last.toX = destX; last.toY = destY; if ((transit.legIndex | 0) === lastIdx) { const oldTotal = Math.hypot(oldToX - last.fromX, oldToY - last.fromY); const newTotal = Math.hypot(destX - last.fromX, destY - last.fromY); if (oldTotal > 1e-6) { transit.traveled = Math.min(newTotal, (transit.traveled || 0) * (newTotal / oldTotal)); } } } return; } this.#routeTransitToBank(transit, transit.destinationCharacterId); } #routeTransitToBank (transit, vaultCharacterId) { const pose = this.#currentPose(transit); const bank = this.nearestBank(Math.floor(pose.x), Math.floor(pose.y), pose.dimensionId) ?? this.nearestBank(Math.floor(transit.destX), Math.floor(transit.destY), transit.destDimensionId) ?? this.nearestBank(Math.floor(transit.originX), Math.floor(transit.originY), transit.originDimensionId); if (!bank) { return; } transit.destinationKind = "bank"; transit.vaultCharacterId = vaultCharacterId ?? transit.vaultCharacterId ?? transit.destinationCharacterId ?? transit.senderCharacterId; this.#repathTransit( transit, pose.x, pose.y, pose.dimensionId, bank.tileX + 0.5, bank.tileY + 0.5, bank.dimensionId ?? OVERWORLD_ID ); } #resolveDestination (destination, originTileX, originTileY, originDimensionId = OVERWORLD_ID) { const originDim = normalizeDimensionId(originDimensionId); if (destination?.kind === "player") { const character = this.stateDb.getCharacterByName(destination.firstName, destination.lastName); if (!character) { const error = new Error("No character with that name."); error.userFacing = true; throw error; } const onlineId = this.simulation.characterEntities.get(character.character_id); if (!onlineId) { const charDim = normalizeDimensionId(character.dimension_id ?? OVERWORLD_ID); const bank = this.nearestBank(originTileX, originTileY, originDim) ?? this.nearestBank(character.tile_x, character.tile_y, charDim); if (!bank) { const error = new Error("No bank exists in the world yet."); error.userFacing = true; throw error; } return { kind: "bank", characterId: character.character_id, vaultCharacterId: character.character_id, tileX: bank.tileX, tileY: bank.tileY, dimensionId: normalizeDimensionId(bank.dimensionId ?? OVERWORLD_ID) }; } const pos = this.simulation.positionOf(onlineId); return { kind: "player", characterId: character.character_id, tileX: pos.tileX, tileY: pos.tileY, dimensionId: normalizeDimensionId(pos.dimensionId ?? OVERWORLD_ID) }; } if (destination?.kind === "bank") { const bank = this.nearestBank(originTileX, originTileY, originDim); if (!bank) { const error = new Error("No bank exists in the world yet."); error.userFacing = true; throw error; } return { kind: "bank", tileX: bank.tileX, tileY: bank.tileY, dimensionId: normalizeDimensionId(bank.dimensionId ?? OVERWORLD_ID) }; } const error = new Error("Pigeon destination must be bank or player."); error.userFacing = true; throw error; } #syncVisiblePigeon (transit, advanced, now, leg) { const events = []; const tileX = Math.floor(advanced.x); const tileY = Math.floor(advanced.y); const dimensionId = normalizeDimensionId( leg?.fromDimensionId ?? transit.originDimensionId ?? OVERWORLD_ID ); if (!this.simulation.chunkIsSimulating(tileX, tileY, dimensionId)) { if (transit.entityId) { this.simulation.despawnEntity(transit.entityId); events.push({ type: "entity-despawn", entityId: transit.entityId, tileX, tileY, dimensionId }); transit.entityId = null; } return events; } if (!transit.entityId || !this.simulation.entityRecord(transit.entityId)) { transit.entityId = null; const def = mobDefinition(MobId.pigeon); const entityId = this.simulation.spawnEntity({ position: { tileX, tileY, dimensionId }, movement: { gait: GAIT.walk, walkCarry: 0 }, path: { tiles: [] }, flight: { x: advanced.x, y: advanced.y, targetX: leg?.toX ?? transit.destX, targetY: leg?.toY ?? transit.destY, speed: advanced.speed, nextPickAt: now + 60_000, lastAt: now, courierId: transit.courierId }, appearance: { sex: def.sex, firstName: def.displayName, lastName: "", sprite: mobSpriteName(MobId.pigeon) }, creature: { mobTypeId: MobId.pigeon }, health: { current: 1, max: 1 } }, { requireResident: true }); if (entityId != null) { transit.entityId = entityId; } return events; } const moved = this.simulation.updateCourierFlight(transit.entityId, { x: advanced.x, y: advanced.y, targetX: leg?.toX ?? transit.destX, targetY: leg?.toY ?? transit.destY, speed: advanced.speed, lastAt: now, courierId: transit.courierId }, now); if (moved?.despawned) { transit.entityId = null; events.push({ type: "entity-despawn", entityId: moved.entityId, tileX, tileY, dimensionId }); } else if (moved?.event) { events.push(moved.event); } return events; } #deliver (transit, now) { const events = []; const destDim = normalizeDimensionId(transit.destDimensionId ?? OVERWORLD_ID); if (transit.entityId) { this.simulation.despawnEntity(transit.entityId); events.push({ type: "entity-despawn", entityId: transit.entityId, tileX: Math.floor(transit.destX), tileY: Math.floor(transit.destY), dimensionId: destDim }); transit.entityId = null; } if (transit.destinationKind === "bank") { const vaultCharacterId = transit.vaultCharacterId ?? transit.destinationCharacterId ?? transit.senderCharacterId; const toast = this.#creditVault(vaultCharacterId, transit.cargo, { senderCharacterId: transit.senderCharacterId }); if (toast) { events.push(toast); } } else if (transit.destinationKind === "player") { const delivered = this.#tryDeliverToPlayer(transit.destinationCharacterId, transit.cargo); if (!delivered) { const bank = this.nearestBank(Math.floor(transit.destX), Math.floor(transit.destY), destDim) ?? this.nearestBank(Math.floor(transit.originX), Math.floor(transit.originY), transit.originDimensionId); if (bank) { const pose = { x: transit.destX, y: transit.destY, dimensionId: destDim }; transit.destinationKind = "bank"; transit.vaultCharacterId = transit.destinationCharacterId; this.#repathTransit( transit, pose.x, pose.y, pose.dimensionId, bank.tileX + 0.5, bank.tileY + 0.5, bank.dimensionId ?? OVERWORLD_ID ); transit.updatedAt = now; this.stateDb.updateCourierTransit(transit); events.push({ type: "pigeon-reroute-bank", courierId: transit.courierId, characterId: transit.destinationCharacterId }); return events; } const toast = this.#creditVault(transit.destinationCharacterId, transit.cargo, { senderCharacterId: transit.senderCharacterId }); if (toast) { events.push(toast); } } else { events.push({ type: "item-bubble", entityId: delivered.entityId, itemId: delivered.itemId, quantity: delivered.quantity }); } } transit.status = "delivered"; transit.traveled = Math.hypot(transit.destX - transit.originX, transit.destY - transit.originY); transit.updatedAt = now; this.stateDb.updateCourierTransit(transit); events.push({ type: "pigeon-delivered", courierId: transit.courierId, senderCharacterId: transit.senderCharacterId, destinationKind: transit.destinationKind, destinationCharacterId: transit.destinationCharacterId, cargo: transit.cargo }); return events; } #normalizeCargo (cargo) { if (cargo?.kind === "money") { return { kind: "item", stack: attachOrigins({ itemId: ItemId.coins, quantity: Math.max(0, cargo.amount | 0) }) }; } return cargo; } #tryDeliverToPlayer (characterId, cargo) { cargo = this.#normalizeCargo(cargo); const onlineId = this.simulation.characterEntities.get(characterId); if (!onlineId) { return null; } if (cargo.kind === "item") { const bag = this.simulation.bagOf(onlineId); if (!bag) { return null; } const def = itemDefinition(cargo.stack.itemId); const result = insertStack(bag.inventory, cargo.stack, def); if (!result.ok || result.remainder) { return null; } bag.inventory = result.slots; this.#persistBag(characterId, bag); return { entityId: onlineId, itemId: cargo.stack.itemId, quantity: Math.max(1, cargo.stack.quantity | 0 || 1) }; } return null; } #creditVault (characterId, cargo, { senderCharacterId = null, recordRestNotice = true } = {}) { cargo = this.#normalizeCargo(cargo); const onlineId = this.simulation.characterEntities.get(characterId); const bag = onlineId ? this.simulation.bagOf(onlineId) : this.stateDb.getBag(characterId); if (!bag) { return null; } if (cargo.kind !== "item") { return null; } const stack = cargo.stack; const isCeLetter = stack?.itemId === ItemId.letter && isCentralExchangeLetter(stack.instance); const isRestNoticeLetter = stack?.itemId === ItemId.letter && isBankRestNoticeLetter(stack.instance); if (stack?.itemId === ItemId.filledCheque && stack.instance?.kind === "filled-cheque") { this.#redeemChequeIntoVault(characterId, bag, stack); this.#maybeRecordRestNotice({ characterId, stack, senderCharacterId, recordRestNotice: recordRestNotice && !onlineId && !isCeLetter && !isRestNoticeLetter }); return null; } const def = itemDefinition(stack.itemId); const vault = normalizeVault( bag.vaultReserved != null ? { slots: bag.vault, reserved: bag.vaultReserved } : bag.vault ); const result = insertStackGrowable(vault.slots, stack, def); bag.vault = result.slots; bag.vaultReserved = vault.reserved; this.#persistBag(characterId, bag); this.#maybeRecordRestNotice({ characterId, stack, senderCharacterId, recordRestNotice: recordRestNotice && !onlineId && !isCeLetter && !isRestNoticeLetter }); if (onlineId && isRestNoticeLetter) { return { type: "toast", characterId, message: "A letter arrived for you at the bank." }; } return null; } #maybeRecordRestNotice ({ characterId, stack, senderCharacterId, recordRestNotice }) { if (!recordRestNotice || !stack) { return; } const sender = senderCharacterId ? this.stateDb.getCharacter(senderCharacterId) : null; const senderDisplayName = sender ? `${sender.first_name} ${sender.last_name}`.trim() : null; this.stateDb.appendBankRestNotice(characterId, { itemId: stack.itemId, itemName: itemNameForNotice(stack), quantity: stack.quantity | 0 || 1, sourceName: sourceNameForVaultDeposit(stack, senderCharacterId, senderDisplayName) }); } /** Pigeon/bank delivery of a filled cheque deposits the reserved goods, not the paper. */ #redeemChequeIntoVault (characterId, bag, chequeStack) { const instance = chequeStack.instance; const issuerId = instance.issuerCharacterId; const goodsDef = itemDefinition(instance.itemId); if (!goodsDef) { return; } let reservedStack = null; if (Number(issuerId) === Number(characterId)) { const reserved = [...(bag.vaultReserved ?? [])]; const index = findReservedChequeIndex(reserved, instance); if (index < 0) { // Paper arrived but reservation is gone — keep the cheque so it isn't silently lost. const def = itemDefinition(ItemId.filledCheque); const vault = normalizeVault({ slots: bag.vault, reserved: bag.vaultReserved }); const result = insertStackGrowable(vault.slots, chequeStack, def); bag.vault = result.slots; bag.vaultReserved = vault.reserved; this.#persistBag(characterId, bag); return; } reservedStack = reserved[index]; reserved.splice(index, 1); bag.vaultReserved = reserved; } else { const release = this.simulation.releaseChequeReservation(issuerId, instance.chequeId, instance); if (!release?.ok) { const def = itemDefinition(ItemId.filledCheque); const vault = normalizeVault({ slots: bag.vault, reserved: bag.vaultReserved }); const result = insertStackGrowable(vault.slots, chequeStack, def); bag.vault = result.slots; bag.vaultReserved = vault.reserved; this.#persistBag(characterId, bag); return; } reservedStack = release.stack; } const vault = normalizeVault({ slots: bag.vault, reserved: bag.vaultReserved }); const goodsStack = attachOrigins({ itemId: reservedStack.itemId, quantity: reservedStack.quantity, origins: normalizeOrigins(reservedStack), instance: reservedStack.instance ?? null }); const inserted = insertStackGrowable(vault.slots, goodsStack, goodsDef); bag.vault = inserted.slots; bag.vaultReserved = vault.reserved; this.#persistBag(characterId, bag); this.#maybeRecordRestNotice({ characterId, stack: goodsStack, senderCharacterId: null, recordRestNotice: !this.simulation.characterEntities.get(characterId) }); } #persistBag (characterId, bag) { this.stateDb.saveBag(characterId, bag); const onlineId = this.simulation.characterEntities.get(characterId); if (onlineId) { this.simulation.applyBag(onlineId, bag); this.simulation.pushInventory(characterId, bag); } } #characterDisplayName (characterId) { const row = this.stateDb.getCharacter(characterId); return { firstName: row?.first_name ?? "Unknown", lastName: row?.last_name ?? "", full: row ? `${row.first_name} ${row.last_name}`.trim() : "Adventurer" }; } #dispatchBankRestNotice (characterId, tileX, tileY, dimensionId = OVERWORLD_ID) { const entries = this.stateDb.listBankRestNotices(characterId); if (!entries.length) { return null; } const dim = normalizeDimensionId(dimensionId); const bank = this.nearestBank(tileX, tileY, dim); if (!bank) { return null; } const lines = mergeBankRestNoticeLines(entries.map((entry) => ({ quantity: entry.quantity, itemName: entry.itemName, sourceName: entry.sourceName }))); const { full: playerName } = this.#characterDisplayName(characterId); const body = bankRestNoticeLetterBody({ playerName, lines }); const stack = makeSystemLetterStack({ authorDisplayName: BANK_LETTER_AUTHOR, body, bankRestNotice: true }); this.stateDb.clearBankRestNotices(characterId); return this.dispatchSystemLetter({ characterId, originTileX: bank.tileX, originTileY: bank.tileY, originDimensionId: bank.dimensionId ?? OVERWORLD_ID, stack }); } }