dsh-piggy 0.25.0

package/packages/pet-core/src/core/illness.js

@@ -0,0 +1,235 @@
+// @ts-check
+/**
+ * 生病与治病：按条件概率发病、病情推进与自愈、吃药（对症 / 吃错 / 百草丹）、看医生、死亡。
+ *
+ * 纯函数领域逻辑：时间由 nowMs 传入，随机数来自 core/random.js（见 docs/CONVENTIONS.md）。
+ * 数字见 data/illness.js（docs/tasks/numbers/B3-illness.md）。
+ * @module dsh-piggy/core/illness
+ */
+
+import {
+  CHAIN_INDEX,
+  DOCTOR_MARKUP,
+  GRAVE,
+  ILLNESS_CHAINS,
+  ILLNESS_ONSET,
+  MAX,
+  REVIVE_ITEM,
+  SELF_HEAL_CHANCE,
+  STAGE_HEALTH,
+  THRESHOLDS,
+  illnessAt,
+  nextIllness,
+} from '../data.js'
+import { announce, remember } from './effects.js'
+import { say } from './lines.js'
+import { chance, rollerFor } from './random.js'
+import { noteToday } from './diary.js'
+
+/**
+ * Let the pig go. Only accidents kill it (the end of an illness chain, or a
+ * wrong medicine at the last stage); there is no old age (B2).
+ * @param {string} why - shown in the announcement.
+ */
+export function die(state, nowMs, why) {
+  if (state.dead === true) return
+  state.dead = true
+  state.health = 0
+  state.illness = null
+  state.activity = null
+  state.diedAt = nowMs
+  state.stats.deaths = (state.stats.deaths ?? 0) + 1
+  remember(state, `${why} ${GRAVE.emoji}`, nowMs)
+  announce(state, 'death', `${state.name} ${why}…用${REVIVE_ITEM.label}可以救回来，也可以领养一只新的`, nowMs)
+  say(state, 'death', nowMs)
+}
+
+export function currentIllness(state) {
+  if (state.illness === null || state.illness === undefined) return null
+  return illnessAt(state.illness.chain, state.illness.stage)
+}
+
+// ---------------------------------------------------------------------------
+// Falling ill
+// ---------------------------------------------------------------------------
+
+/**
+ * What the pig is at risk of right now, per hour, and from which chain.
+ * Each condition adds its own chance and points at its own chain, so the
+ * illness tells the owner what went wrong: hungry → a cold, filthy → skin.
+ * @param {object} state
+ * @returns {Array<{chain: number, perHour: number}>}
+ */
+export function onsetRisks(state) {
+  /** @type {Array<{chain: number, perHour: number}>} */
+  const risks = [{ chain: -1, perHour: ILLNESS_ONSET.basePerHour }]
+  if (state.satiety < THRESHOLDS.hungry) risks.push({ chain: CHAIN_INDEX.cold, perHour: ILLNESS_ONSET.hungryPerHour })
+  if (state.cleanliness < THRESHOLDS.dirty) {
+    const chain = state.cleanliness < ILLNESS_ONSET.veryDirty ? CHAIN_INDEX.skin : CHAIN_INDEX.cough
+    risks.push({ chain, perHour: ILLNESS_ONSET.dirtyPerHour })
+  }
+  if (state.happiness < ILLNESS_ONSET.sadBelow) risks.push({ chain: CHAIN_INDEX.dizzy, perHour: ILLNESS_ONSET.sadPerHour })
+  if ((state.outingStreak ?? 0) >= ILLNESS_ONSET.overworkStreak) {
+    risks.push({ chain: CHAIN_INDEX.dizzy, perHour: ILLNESS_ONSET.overworkPerHour })
+  }
+  return risks
+}
+
+/**
+ * One stretch of time at home: maybe fall ill. The hourly chances are turned
+ * into a chance for this many minutes, so stepping in 5-minute slices gives
+ * the same odds as one long step would.
+ * @param {object} state
+ * @param {{minutes: number, atMs: number}} span
+ * @param {import('./random.js').Roll} next
+ */
+export function rollForIllness(state, span, next) {
+  if (state.illness !== null && state.illness !== undefined) return
+  const risks = onsetRisks(state)
+  const perHour = risks.reduce((sum, risk) => sum + risk.perHour, 0)
+  const hit = 1 - Math.pow(1 - Math.min(1, perHour), span.minutes / 60)
+  if (!chance(next, hit)) return
+  // Which condition did it: weighted by each one's share of the risk. The
+  // base chance (chain -1) picks any chain at random.
+  let pick = next() * perHour
+  let cause = risks[0]
+  for (const risk of risks) {
+    cause = risk
+    pick -= risk.perHour
+    if (pick < 0) break
+  }
+  const chain = cause.chain >= 0 ? cause.chain : Math.min(ILLNESS_CHAINS.length - 1, Math.floor(next() * ILLNESS_CHAINS.length))
+  catchIllness(state, chain, span.atMs)
+}
+
+/** Feeding a pig that is already stuffed can upset its stomach. */
+export function rollForOverfeeding(state, satietyBefore, nowMs) {
+  if (satietyBefore < ILLNESS_ONSET.overfullAt || state.illness !== null) return
+  if (chance(rollerFor(state), ILLNESS_ONSET.overfeedChance)) catchIllness(state, CHAIN_INDEX.stomach, nowMs)
+}
+
+/** Work, school and trips in a row wear the pig out; an hour at home resets it. */
+export function noteOuting(state) {
+  state.outingStreak = (state.outingStreak ?? 0) + 1
+  state.restMinutes = 0
+}
+
+export function restAtHome(state, minutes) {
+  state.restMinutes = (state.restMinutes ?? 0) + minutes
+  if (state.restMinutes >= ILLNESS_ONSET.restMinutes) state.outingStreak = 0
+}
+
+/**
+ * @param {object} state
+ * @param {number} chain - index into ILLNESS_CHAINS
+ * @param {number} nowMs
+ */
+export function catchIllness(state, chain, nowMs) {
+  state.illness = { chain, stage: 1, since: nowMs, progressMs: 0 }
+  state.health = STAGE_HEALTH[0]
+  state.stats.illnesses = (state.stats.illnesses ?? 0) + 1
+  const ill = illnessAt(chain, 1)
+  if (ill === null) return
+  remember(state, `得了${ill.name} 🤒`, nowMs)
+  announce(state, 'sick', `${state.name} 得了${ill.name}，需要${ill.cureEmoji}${ill.cure} 🤒`, nowMs)
+  noteToday(state, 'illness')
+  say(state, 'sick', nowMs)
+}
+
+// ---------------------------------------------------------------------------
+// Getting worse, getting better
+// ---------------------------------------------------------------------------
+
+/**
+ * A stage ran its course: it may shake itself off, otherwise it gets worse.
+ * @param {object} state
+ * @param {number} nowMs
+ * @param {import('./random.js').Roll} [next] - defaults to the pig's own seed.
+ */
+export function advanceIllness(state, nowMs, next = rollerFor(state)) {
+  const healChance = SELF_HEAL_CHANCE[state.illness.stage - 1] ?? 0
+  if (chance(next, healChance)) {
+    const name = ILLNESS_CHAINS[state.illness.chain].name
+    recover(state, nowMs)
+    remember(state, `自己好了，扛过去了 💚`, nowMs)
+    announce(state, 'cured', `${state.name} 的${name}自己好了 💚`, nowMs)
+    noteToday(state, 'cure')
+    return
+  }
+  worsen(state, nowMs, '没能撑过去')
+}
+
+/**
+ * One stage worse, now. The end of the chain is death.
+ * @param {string} why - the cause of death, if it comes to that.
+ */
+export function worsen(state, nowMs, why) {
+  const { chain, stage } = state.illness
+  const worse = nextIllness(chain, stage)
+  if (worse === null) {
+    die(state, nowMs, why)
+    return
+  }
+  state.illness = { chain, stage: stage + 1, since: nowMs, progressMs: 0 }
+  state.health = STAGE_HEALTH[stage]
+  remember(state, `病情加重：${worse.name}`, nowMs)
+  announce(state, 'worse', `${state.name} 的病情加重了：${worse.name}，需要${worse.cureEmoji}${worse.cure}`, nowMs)
+}
+
+/** Well again, all the way (#7): an illness leaves no permanent dent. */
+function recover(state, nowMs) {
+  state.illness = null
+  state.health = MAX.health
+  say(state, 'cured', nowMs)
+}
+
+// ---------------------------------------------------------------------------
+// Treatment
+// ---------------------------------------------------------------------------
+
+/**
+ * Give the pig a medicine it already has in the bag (the caller spends it).
+ * The right cure, or 百草丹, makes it well. The wrong one makes it worse at
+ * once, as in the original — which is why the panel always says what it needs.
+ * @returns {{ok: true, cured: true}|{ok: false, reason: 'not-sick'}|{ok: false, reason: 'wrong-medicine', needs: object|null}}
+ */
+export function medicate(state, item, nowMs) {
+  const ill = currentIllness(state)
+  if (ill === null) return { ok: false, reason: 'not-sick' }
+  if (item.cureAll === true || item.key === ill.cureKey) {
+    recover(state, nowMs)
+    state.stats.cures = (state.stats.cures ?? 0) + 1
+    remember(state, `吃了 ${item.emoji} ${item.label}，病好了`, nowMs)
+    announce(state, 'cured', `${state.name} 吃了 ${item.label}，痊愈了 💚`, nowMs)
+    noteToday(state, 'cure')
+    return { ok: true, cured: true }
+  }
+  remember(state, `吃错了药（${item.label}），病情加重`, nowMs)
+  say(state, 'wrongMedicine', nowMs)
+  noteToday(state, 'wrongMedicine')
+  worsen(state, nowMs, '吃错了药，没能撑过去')
+  return { ok: false, reason: 'wrong-medicine', needs: ill }
+}
+
+/** What seeing the doctor costs for the illness the pig has now. */
+export function doctorFee(state) {
+  const ill = currentIllness(state)
+  return ill === null ? null : Math.ceil(ill.curePrice * DOCTOR_MARKUP)
+}
+
+/** 看医生：pay the fee, skip the shopping, get well. */
+export function seeDoctor(state, nowMs) {
+  if (state === null) return { ok: false, reason: 'absent' }
+  if (state.dead === true) return { ok: false, reason: 'dead' }
+  const fee = doctorFee(state)
+  if (fee === null) return { ok: false, reason: 'not-sick' }
+  if (state.coins < fee) return { ok: false, reason: 'poor', need: fee, have: state.coins }
+  state.coins -= fee
+  recover(state, nowMs)
+  state.stats.cures = (state.stats.cures ?? 0) + 1
+  state.stats.doctorVisits = (state.stats.doctorVisits ?? 0) + 1
+  remember(state, `🏥 看了医生，花了 ${fee} 金币，病好了`, nowMs)
+  announce(state, 'cured', `${state.name} 看了医生，痊愈了 💚（${fee} 🪙）`, nowMs)
+  noteToday(state, 'cure')
+  return { ok: true, fee }
+}

package/packages/pet-core/src/core/interests.js

@@ -0,0 +1,55 @@
+// @ts-check
+/**
+ * 兴趣课。
+ *
+ * 纯函数领域逻辑：时间由 nowMs 传入，不读写文件、不碰 DOM（见 docs/CONVENTIONS.md）。
+ * @module dsh-piggy/core/interests
+ */
+
+import { INTERESTS, interestByKey } from '../data.js'
+import { begin } from './activity.js'
+import { TOO_WEAK_HEALTH } from './constants.js'
+import { remember } from './effects.js'
+
+/**
+/**
+ * 兴趣课的修读次数, per interest key.
+ *
+ * The point of 兴趣 is that it feeds an *existing* trait (智力/魅力/武力) — it
+ * is not a fourth axis, so there is nothing else to track.
+ */
+export function interestView(state) {
+  const out = {}
+  for (const entry of INTERESTS) out[entry.key] = state.interests?.[entry.key] ?? 0
+  return out
+}
+
+/**
+ * 兴趣课 — like 上课, but outside the school ladder and repeatable.
+ *
+ * It pays into the same three traits (智力/魅力/武力); there is no separate
+ * skill stat, because a skill stat would just be a second name for those three.
+ */
+export function startInterest(state, interestKey, nowMs) {
+  const interest = interestByKey(interestKey)
+  if (interest === null) return { ok: false, reason: 'unknown' }
+  if (state.hatched !== true) return { ok: false, reason: 'box' }
+  if (state.dead) return { ok: false, reason: 'dead' }
+  if (state.activity !== null) return { ok: false, reason: 'away' }
+  if (state.health <= TOO_WEAK_HEALTH) return { ok: false, reason: 'weak' }
+  if (state.coins < interest.cost) return { ok: false, reason: 'poor', price: interest.cost }
+  if (state.satiety < 15) return { ok: false, reason: 'hungry' }
+
+  state.coins -= interest.cost
+  const result = begin(state, {
+    kind: 'interest', key: interest.key,
+    label: `兴趣·${interest.label}`, emoji: interest.emoji,
+    minutes: interest.minutes, cost: interest.cost,
+  }, nowMs)
+  if (!result.ok) {
+    state.coins += interest.cost
+    return result
+  }
+  remember(state, `${interest.emoji} 去学${interest.label}（花了 ${interest.cost} 金币）`, nowMs)
+  return result
+}

package/packages/pet-core/src/core/inventory.js

@@ -0,0 +1,177 @@
+// @ts-check
+/**
+ * 背包、购买、装扮与道具使用。
+ *
+ * 纯函数领域逻辑：时间由 nowMs 传入，不读写文件、不碰 DOM（见 docs/CONVENTIONS.md）。
+ * @module dsh-piggy/core/inventory
+ */
+
+import { DEFAULT_TOY, REVIVE_ITEM, SHOP, dressSlotByKey, itemByKey } from '../data.js'
+import { levelProgress } from './clock.js'
+import { applyEffects, remember } from './effects.js'
+import { medicate } from './illness.js'
+import { decay } from './settlement.js'
+import { revive } from './state.js'
+
+/** Inventory counts, always including zeroes so the UI can render a grid. */
+export function inventoryView(state) {
+  const out = {}
+  for (const item of SHOP) {
+    // 家当 is not carried in counts — it is owned and worn.
+    if (item.kind === 'dress') continue
+    out[item.key] = state.inventory?.[item.key] ?? 0
+  }
+  // The free default toy is always in the bag and never runs out, so `玩耍` is
+  // never blocked by an empty one.
+  out[DEFAULT_TOY.key] = Infinity
+  return out
+}
+
+/**
+ * Owned / worn state for the 装扮 shelf, plus the level each one needs.
+ *
+ * The panel shows all twelve even when locked: an item you cannot see is an
+ * item you will never save up for.
+ */
+export function dressView(state) {
+  const owned = new Set(state.dress ?? [])
+  const worn = new Set(state.worn ?? [])
+  const have = levelProgress(state.xp).level
+  return SHOP.filter(item => item.kind === 'dress').map(item => ({
+    key: item.key, label: item.label, emoji: item.emoji, price: item.price,
+    level: item.level ?? 1,
+    // The anchor this piece goes on; one item per slot at a time.
+    slot: item.slot ?? null,
+    slotLabel: item.slot === undefined ? '' : (dressSlotByKey(item.slot)?.label ?? item.slot),
+    blurb: item.blurb ?? '',
+    owned: owned.has(item.key),
+    worn: worn.has(item.key),
+    unlocked: have >= (item.level ?? 1),
+  }))
+}
+
+export function buy(state, itemKey, nowMs) {
+  const item = itemByKey(itemKey)
+  if (item === null) return { ok: false, reason: 'unknown' }
+  if (state.dead && item.key !== REVIVE_ITEM.key) return { ok: false, reason: 'dead' }
+
+  // 家当 is a different transaction: own it once, then wear it. No counts.
+  if (item.kind === 'dress') {
+    if ((state.dress ?? []).includes(item.key)) return { ok: false, reason: 'owned', item }
+    const have = levelProgress(state.xp).level
+    const need = item.level ?? 1
+    if (have < need) return { ok: false, reason: 'low-level', need, have, item }
+    if (state.coins < item.price) return { ok: false, reason: 'poor', price: item.price }
+    state.coins -= item.price
+    state.dress = [...(state.dress ?? []), item.key]
+    state.stats.purchases += 1
+    remember(state, `买下了 ${item.emoji} ${item.label}（-${item.price} 金币）`, nowMs)
+    return { ok: true, item }
+  }
+
+  if (state.coins < item.price) return { ok: false, reason: 'poor', price: item.price }
+
+  state.coins -= item.price
+  state.inventory = { ...(state.inventory ?? {}) }
+  state.inventory[item.key] = (state.inventory[item.key] ?? 0) + 1
+  state.stats.purchases += 1
+  remember(state, `买了 ${item.emoji} ${item.label}（-${item.price} 金币）`, nowMs)
+  return { ok: true, item }
+}
+
+/** Shared checks for the two 装扮 actions. */
+export function wearableDress(state, itemKey) {
+  const item = itemByKey(itemKey)
+  if (item === null || item.kind !== 'dress') return { item: null, reason: 'unknown' }
+  if (!(state.dress ?? []).includes(item.key)) return { item: null, reason: 'not-owned' }
+  return { item, reason: null }
+}
+
+/**
+ * Put a 装扮 on. Only owned dress items; one item per slot, so a new hat
+ * automatically takes the old one off.
+ * @returns `{ ok: true, item, worn }` or `{ ok: false, reason }`.
+ */
+export function wearItem(state, itemKey, nowMs) {
+  const { item, reason } = wearableDress(state, itemKey)
+  if (item === null) return { ok: false, reason }
+  const worn = new Set(state.worn ?? [])
+  for (const key of [...worn]) {
+    const other = itemByKey(key)
+    if (other !== null && other.slot === item.slot) worn.delete(key)
+  }
+  worn.add(item.key)
+  state.worn = [...worn]
+  remember(state, `戴上了 ${item.emoji} ${item.label}`, nowMs)
+  return { ok: true, item, worn: state.worn.slice() }
+}
+
+/** Take a 装扮 off. */
+export function takeOff(state, itemKey, nowMs) {
+  const { item, reason } = wearableDress(state, itemKey)
+  if (item === null) return { ok: false, reason }
+  const worn = new Set(state.worn ?? [])
+  worn.delete(item.key)
+  state.worn = [...worn]
+  remember(state, `摘下了 ${item.emoji} ${item.label}`, nowMs)
+  return { ok: true, item, worn: state.worn.slice() }
+}
+
+/**
+ * Debug helper: hand the pig one of everything.
+ *
+ * 20 of each consumable, every 装扮 owned, and enough coins that price is never
+ * the reason a test in the panel fails.
+ */
+export function grantAll(state, nowMs) {
+  if (state === null || state === undefined) return { ok: false, reason: 'absent' }
+  const inventory = { ...(state.inventory ?? {}) }
+  for (const item of SHOP) {
+    if (item.kind === 'dress') continue
+    inventory[item.key] = Math.max(inventory[item.key] ?? 0, 20)
+  }
+  state.inventory = inventory
+  const dress = SHOP.filter(item => item.kind === 'dress').map(item => item.key)
+  state.dress = dress
+  state.coins = Math.max(state.coins ?? 0, 99999)
+  state.stats.purchases = (state.stats.purchases ?? 0) + dress.length
+  remember(state, '🔧 调试：一键拿齐了所有物品', nowMs)
+  return { ok: true, granted: { items: SHOP.length - dress.length, dress: dress.length, coins: state.coins } }
+}
+
+export const canAfford = (state, itemKey) => {
+  const item = itemByKey(itemKey)
+  return item !== null && state.coins >= item.price
+}
+
+export function useItem(state, itemKey, nowMs) {
+  const item = itemByKey(itemKey)
+  if (item === null) return { ok: false, reason: 'unknown' }
+  // 家当 is worn, not consumed — 穿上 is a different action.
+  if (item.kind === 'dress') return { ok: false, reason: 'not-consumable' }
+  const have = state.inventory?.[itemKey] ?? 0
+  if (have <= 0) return { ok: false, reason: 'empty' }
+  decay(state, nowMs)
+
+  if (item.key === REVIVE_ITEM.key) {
+    if (!state.dead) return { ok: false, reason: 'not-dead' }
+    state.inventory[itemKey] = have - 1
+    revive(state, nowMs)
+    return { ok: true, item }
+  }
+  if (state.dead) return { ok: false, reason: 'dead' }
+
+  if (item.kind === 'medicine') {
+    if (state.illness === null) return { ok: false, reason: 'not-sick' }
+    // Swallowed either way: the wrong medicine is spent too, and makes it worse.
+    state.inventory[itemKey] = have - 1
+    const result = medicate(state, item, nowMs)
+    return result.ok ? { ok: true, item } : result
+  }
+
+  if (state.activity !== null) return { ok: false, reason: 'away' }
+  state.inventory[itemKey] = have - 1
+  applyEffects(state, item, nowMs)
+  remember(state, `用了 ${item.emoji} ${item.label}`, nowMs)
+  return { ok: true, item }
+}

package/packages/pet-core/src/core/lines.js

@@ -0,0 +1,157 @@
+// @ts-check
+/**
+ * 台词：按场景挑一句、放进消息队列，处理主人的回复。
+ *
+ * 纯函数领域逻辑：时间由 nowMs 传入，不读写文件、不碰 DOM（见 docs/CONVENTIONS.md）。
+ * @module dsh-piggy/core/lines
+ */
+
+import { CATCHPHRASE_CHANCE, DEFAULT_OWNER_NAME, LINES, SERIOUS_SCENES, OWNER_NAME_MAX, OWNER_TOKEN, REPLY_HAPPINESS, THRESHOLDS, WELCOME_BACK_AFTER_MINUTES } from '../data.js'
+import { announce, clamp100 } from './effects.js'
+import { chance, rollerFor } from './random.js'
+
+/** The dialogue record every pig carries; older saves get it filled in. */
+export function emptyDialogue() {
+  return { ownerName: DEFAULT_OWNER_NAME, lastByScene: {}, open: null, quiet: false, greetedAt: 0 }
+}
+
+/**
+ * Pick a line for `scene`, never the same one twice in a row.
+ * @param {object} state - `dialogue.lastByScene` is updated in place.
+ * @param {string} scene
+ * @param {import('./random.js').Roll} [next]
+ * @returns {{scene: string, text: string, replies: Array<{label: string, happiness: number}>}|null}
+ */
+export function pickLine(state, scene, next = rollerFor(state)) {
+  const pool = LINES[scene]
+  if (pool === undefined || pool.length === 0) return null
+  const dialogue = ensureDialogue(state)
+  const last = dialogue.lastByScene[scene]
+  let index = Math.min(pool.length - 1, Math.floor(next() * pool.length))
+  if (pool.length > 1 && index === last) index = (index + 1) % pool.length
+  dialogue.lastByScene = { ...dialogue.lastByScene, [scene]: index }
+  const line = pool[index]
+  return {
+    scene,
+    text: withCatchphrase(state, scene, line.text.split(OWNER_TOKEN).join(dialogue.ownerName), next),
+    replies: (line.replies ?? []).map(reply => ({ label: reply.label, happiness: reply.happiness ?? REPLY_HAPPINESS })),
+  }
+}
+
+/**
+ * Now and then the pig ends a line with its catchphrase, the way the villagers
+ * do (B9): 「好舒服…」 → 「好舒服，呼噜…」. Never in serious moments, never on a
+ * stage direction like 「（眯起眼睛）」, and never twice.
+ */
+function withCatchphrase(state, scene, text, next) {
+  const phrase = typeof state.catchphrase === 'string' ? state.catchphrase.trim() : ''
+  if (phrase === '' || SERIOUS_SCENES.includes(scene) || text.startsWith('（') || text.includes(phrase)) return text
+  if (!chance(next, CATCHPHRASE_CHANCE)) return text
+  const match = /^(.*?)([。！？!?～~…]*)$/.exec(text)
+  const body = match === null ? text : match[1]
+  const tail = match === null ? '' : match[2]
+  return `${body}，${phrase}${tail}`
+}
+
+/**
+ * Have the pig say something: a `line` message the panel shows in its bubble,
+ * with reply buttons when the line has any. Only the newest line can be
+ * answered, so an old bubble cannot be replied to twice for extra mood.
+ * @returns {boolean} whether a line was queued.
+ */
+export function say(state, scene, nowMs, next) {
+  const line = pickLine(state, scene, next)
+  if (line === null) return false
+  const message = announce(state, 'line', line.text, nowMs, { scene, replies: line.replies.map(reply => reply.label) })
+  const dialogue = ensureDialogue(state)
+  dialogue.open = line.replies.length > 0 ? { id: message.id, replies: line.replies } : null
+  return true
+}
+
+/**
+ * The owner answers the pig's latest line.
+ * @param {object} state
+ * @param {number} lineId - the `id` of the `line` message being answered.
+ * @param {number} replyIndex
+ */
+export function replyToLine(state, lineId, replyIndex) {
+  if (state === null) return { ok: false, reason: 'absent' }
+  if (state.dead === true) return { ok: false, reason: 'dead' }
+  const dialogue = ensureDialogue(state)
+  const open = dialogue.open
+  if (open === null || open.id !== lineId) return { ok: false, reason: 'stale-line' }
+  const reply = open.replies[replyIndex]
+  if (reply === undefined) return { ok: false, reason: 'unknown' }
+  dialogue.open = null
+  state.happiness = clamp100(state.happiness + reply.happiness)
+  return { ok: true, reply: reply.label }
+}
+
+/**
+ * The pig speaks up on its own: `enter` when the owner opens DSH after being
+ * away a while, `idle` every so often (the panel decides when). An idle line
+ * says what the pig needs first — hungry, dirty, lonely — and only chats when
+ * it needs nothing. Never while away, ill, dead, a box, or on 免打扰.
+ * @param {object} state
+ * @param {'enter'|'idle'} reason
+ * @param {number} nowMs
+ */
+export function chat(state, reason, nowMs) {
+  if (state === null || state.hatched !== true || state.dead === true) return { ok: false, reason: 'silent' }
+  const dialogue = ensureDialogue(state)
+  if (dialogue.quiet) return { ok: false, reason: 'silent' }
+  if (state.activity !== null || state.illness !== null) return { ok: false, reason: 'silent' }
+  if (reason === 'enter') {
+    if (nowMs - dialogue.greetedAt < WELCOME_BACK_AFTER_MINUTES * 60_000) return { ok: false, reason: 'silent' }
+    dialogue.greetedAt = nowMs
+    say(state, 'enter', nowMs)
+    return { ok: true, scene: 'enter' }
+  }
+  const scene = state.satiety < THRESHOLDS.hungry ? 'hungry'
+    : state.cleanliness < THRESHOLDS.dirty ? 'dirty'
+      : state.happiness < THRESHOLDS.lonely ? 'lonely'
+        : 'idle'
+  say(state, scene, nowMs)
+  return { ok: true, scene }
+}
+
+/** 免打扰: no chatter and no routine toasts; illness and death still speak. */
+export function setQuiet(state, on) {
+  if (state === null) return { ok: false, reason: 'absent' }
+  ensureDialogue(state).quiet = on === true
+  return { ok: true, quiet: on === true }
+}
+
+/** What the pig calls its owner (the `[主人]` in its lines). */
+export function setOwnerName(state, rawName) {
+  if (state === null) return { ok: false, reason: 'absent' }
+  const name = typeof rawName === 'string' ? rawName.trim().slice(0, OWNER_NAME_MAX) : ''
+  if (name === '') return { ok: false, reason: 'empty' }
+  ensureDialogue(state).ownerName = name
+  return { ok: true, ownerName: name }
+}
+
+/** Make sure `state.dialogue` has every field, whatever the save held. */
+export function ensureDialogue(state) {
+  const raw = state.dialogue
+  const base = emptyDialogue()
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    state.dialogue = base
+    return base
+  }
+  const ownerName = typeof raw.ownerName === 'string' && raw.ownerName.trim() !== '' ? raw.ownerName.trim().slice(0, OWNER_NAME_MAX) : base.ownerName
+  const lastByScene = raw.lastByScene !== null && typeof raw.lastByScene === 'object' && !Array.isArray(raw.lastByScene) ? raw.lastByScene : {}
+  const open = sanitizeOpenLine(raw.open)
+  const quiet = raw.quiet === true
+  const greetedAt = Number.isFinite(raw.greetedAt) ? raw.greetedAt : 0
+  state.dialogue = { ownerName, lastByScene, open, quiet, greetedAt }
+  return state.dialogue
+}
+
+function sanitizeOpenLine(raw) {
+  if (raw === null || typeof raw !== 'object' || !Number.isInteger(raw.id) || !Array.isArray(raw.replies)) return null
+  const replies = raw.replies
+    .filter(reply => reply !== null && typeof reply === 'object' && typeof reply.label === 'string')
+    .map(reply => ({ label: reply.label, happiness: Number.isFinite(reply.happiness) ? reply.happiness : REPLY_HAPPINESS }))
+  return replies.length > 0 ? { id: raw.id, replies } : null
+}