@rpgm-tools/neo-angband-core 0.10.0

package/src/sound/engine.ts

@@ -0,0 +1,375 @@
+/**
+ * Core sound engine, ported from reference/src/sound-core.c (Angband 4.2.6).
+ *
+ * This is the front-end-agnostic half of the sound subsystem: it owns the
+ * message->sound map (message_sounds[]), the deduplicated sound pool
+ * (sounds[] / next_sound_id), load-status tracking, and the random sample
+ * selection in play_sound. A platform supplies the SoundHooks that actually
+ * load and play audio; the core has no DOM or audio-API dependency.
+ *
+ * Faithful details preserved from the C:
+ *  - djb2_hash + name compare dedup so a sample used by many messages gets
+ *    one shared sound id (message_sound_define, L179).
+ *  - The MAX_SOUNDS_PER_MESSAGE - 1 cap (the C uses `< (MAX - 1)`, so a
+ *    message keeps at most 15 samples, not 16 - replicated exactly).
+ *  - Selection via randint0(num_sounds) over the message's sample ids
+ *    (play_sound, L320), through an injected RNG seam for determinism.
+ *  - Lazy load: an UNKNOWN sound is loaded just before its first play;
+ *    preload loads it as soon as it is assigned to a message.
+ */
+
+import type { GameEvents, MessageEventData } from "../events.js";
+import { MESSAGE_ENTRIES, MSG } from "../generated/message.js";
+import { SoundStatus, MAX_SOUNDS_PER_MESSAGE } from "./types.js";
+import type { SoundData, SoundHooks } from "./types.js";
+
+/** djb2_hash (z-util.c): hash * 33 + c, seeded at 5381, in uint32. */
+export function djb2Hash(str: string): number {
+  let hash = 5381 >>> 0;
+  for (let i = 0; i < str.length; i++) {
+    // ((hash << 5) + hash) + c, kept in uint32 with Math.imul(hash, 33).
+    hash = (Math.imul(hash, 33) + str.charCodeAt(i)) >>> 0;
+  }
+  return hash;
+}
+
+/** contains_only_spaces (z-util.c:801-806): the rest is spaces and tabs only. */
+function containsOnlySpaces(s: string): boolean {
+  return /^[ \t]*$/.test(s);
+}
+
+/**
+ * strtoul(s, &pe, 10), enough of it for message_lookup_by_name: returns the
+ * parsed value and the unconsumed tail, or null when nothing was consumed
+ * (the `pe == name` case). C skips leading whitespace and accepts a sign, and
+ * `unsigned long` is 32-bit on the reference toolchain, so a negative literal
+ * wraps to a huge value and an overflow saturates at ULONG_MAX -- both of which
+ * land above MSG_MAX and are rejected by the caller, which is exactly what
+ * upstream's own test asserts for "-3" (tests/message/message.c:533-534).
+ */
+function strtoul10(s: string): { value: number; tail: string } | null {
+  const m = /^[ \t\n\v\f\r]*([+-]?)([0-9]+)/.exec(s);
+  if (!m) return null;
+  const digits = m[2]!;
+  const raw = Number(digits);
+  const value =
+    raw > 0xffffffff
+      ? 0xffffffff
+      : m[1] === "-"
+        ? (0x100000000 - (raw % 0x100000000)) % 0x100000000
+        : raw;
+  return { value, tail: s.slice(m[0].length) };
+}
+
+/**
+ * message_lookup_by_name (message.c:295-317): MSG_ index for a name, or -1.
+ *
+ * Two paths, and the numeric one comes FIRST. A name that parses as a decimal
+ * number is that message index outright, provided the remainder is blank and
+ * the value is below MSG_MAX; only if nothing numeric was consumed does the
+ * name table get searched, and that search is case-INSENSITIVE (my_stricmp at
+ * :312). Both were missing here (findings UT-001 and UT-006): the numeric path
+ * entirely, and the name comparison was `===`, so "generic" returned -1 where
+ * upstream returns MSG_GENERIC. The C reaches this from every `msgt:` directive
+ * in gamedata (init.c, mon-init.c, obj-init.c, player-timed.c), so the
+ * case-folding is load-bearing once a data reader is wired to it.
+ */
+export function messageLookupByName(name: string): number {
+  const parsed = strtoul10(name);
+  if (parsed) {
+    return containsOnlySpaces(parsed.tail) && parsed.value < MSG.MAX ? parsed.value : -1;
+  }
+  const lower = name.toLowerCase();
+  for (let i = 0; i < MESSAGE_ENTRIES.length; i++) {
+    if (MESSAGE_ENTRIES[i]!.name.toLowerCase() === lower) return i;
+  }
+  return -1;
+}
+
+/**
+ * message_sound_name (message.c:349-361): the sound.prf name for a MSG_, or
+ * null outside [MSG_GENERIC, MSG_MAX). Note MSG_GENERIC and MSG_BIRTH map to
+ * the EMPTY STRING, not null — list-message.h gives only MSG_MAX a NULL — so a
+ * caller must distinguish "no name" from "out of range".
+ */
+export function messageSoundName(message: number): string | null {
+  if (message < MSG.GENERIC || message >= MSG.MAX) return null;
+  return MESSAGE_ENTRIES[message]!.sound;
+}
+
+/**
+ * message_lookup_by_sound_name (message.c:325-341): the MSG_ whose sound.prf
+ * name matches, or MSG_GENERIC when nothing does.
+ *
+ * Three warts kept deliberately. The compare is my_stricmp, so it is
+ * case-INSENSITIVE. MSG_MAX is excluded from the scan (its name is NULL). And
+ * the not-found answer is MSG_GENERIC, i.e. 0 — NOT -1 as in
+ * message_lookup_by_name — so a caller cannot tell a miss from a real hit on
+ * MSG_GENERIC. The mapping is also not one-to-one: several messages share the
+ * empty sound name, and the first of those (MSG_GENERIC) always wins.
+ */
+export function messageLookupBySoundName(name: string): number {
+  const lower = name.toLowerCase();
+  /* Exclude MSG_MAX since it has NULL for the sound's name. */
+  for (let i = 0; i < MESSAGE_ENTRIES.length - 1; i++) {
+    if ((MESSAGE_ENTRIES[i]!.sound ?? "").toLowerCase() === lower) return i;
+  }
+  return MSG.GENERIC;
+}
+
+/** struct msg_snd_data (sound-core.c): a message's mapped sample ids. */
+interface MsgSndData {
+  numSounds: number;
+  soundIds: number[];
+}
+
+/** The RNG seam: randint0(n) yields 0..n-1. Inject the game's RNG. */
+export type Randint0 = (n: number) => number;
+
+export interface SoundEngineOptions {
+  /** Platform hooks; omit for a fully silent (no-op) engine. */
+  hooks?: SoundHooks;
+  /** randint0 seam (defaults to a non-deterministic Math.random helper). */
+  randint0?: Randint0;
+  /** If true, load each sound as soon as it is assigned to a message. */
+  preload?: boolean;
+}
+
+function defaultRandint0(n: number): number {
+  return Math.floor(Math.random() * n);
+}
+
+/**
+ * The sound engine: mirrors the file-scope state of sound-core.c
+ * (message_sounds[], sounds[], next_sound_id, preload_sounds, hooks) as an
+ * instantiable object.
+ */
+export class SoundEngine {
+  /** message_sounds[MSG_MAX]: sample ids mapped to each message type. */
+  private messageSounds: MsgSndData[] = MESSAGE_ENTRIES.map(() => ({
+    numSounds: 0,
+    soundIds: [],
+  }));
+
+  /** sounds[]: the deduplicated sample pool (index == sound id). */
+  private sounds: SoundData[] = [];
+
+  /** next_sound_id: number of pool entries assigned so far. */
+  private nextSoundId = 0;
+
+  private hooks: SoundHooks;
+  private randint0: Randint0;
+  private preloadSounds: boolean;
+
+  /** The bound "sound" handler, kept so it can be removed on close. */
+  private soundHandler: ((type: "sound", data: MessageEventData) => void) | null =
+    null;
+
+  constructor(opts: SoundEngineOptions = {}) {
+    this.hooks = opts.hooks ?? {};
+    this.randint0 = opts.randint0 ?? defaultRandint0;
+    this.preloadSounds = opts.preload ?? false;
+  }
+
+  /**
+   * set_preloaded_sounds: switch immediate-vs-lazy loading. Returns the
+   * previous setting, exactly like the C.
+   */
+  setPreloadedSounds(newSetting: boolean): boolean {
+    const old = this.preloadSounds;
+    this.preloadSounds = newSetting;
+    return old;
+  }
+
+  /** Install platform hooks after construction (mirrors init_sound wiring). */
+  setHooks(hooks: SoundHooks): void {
+    this.hooks = hooks;
+  }
+
+  /**
+   * load_sound (sound-core.c, L127): try each platform-supported file type
+   * until the platform reports it can play the sound. The C builds a path
+   * under ANGBAND_DIR_SOUNDS and checks file_exists before each attempt; the
+   * platform-agnostic core delegates path resolution and existence to the
+   * loadSound hook, which sets data.status (LOADED on success).
+   */
+  private loadSound(data: SoundData): void {
+    if (!this.hooks.loadSound || !this.hooks.supportedFiles) return;
+    const supported = this.hooks.supportedFiles();
+    let loaded = false;
+    for (const sf of supported) {
+      if (loaded) break;
+      loaded = this.hooks.loadSound(data.name, sf.type, data);
+    }
+    // On total failure the C logs and leaves status ERROR/UNKNOWN as the
+    // hook set it; nothing else to do here.
+  }
+
+  /**
+   * message_sound_define (sound-core.c, L179): assign a space-separated list
+   * of sample names to a message type. New names join the shared pool (with
+   * djb2 dedup); each name is appended to the message's id list up to the
+   * MAX_SOUNDS_PER_MESSAGE - 1 cap.
+   */
+  messageSoundDefine(messageId: number, soundsStr: string): void {
+    const msg = this.messageSounds[messageId];
+    if (!msg) return;
+
+    // Delete any existing mapping of message id to sound ids.
+    msg.numSounds = 0;
+    msg.soundIds = [];
+
+    // sounds_str is a space separated list of sound names. The C tokenizer
+    // splits on single spaces; replicate by splitting on " " and dropping
+    // the empty tokens that runs of spaces would produce (strchr-based walk).
+    const tokens = soundsStr.split(" ").filter((t) => t.length > 0);
+
+    for (const token of tokens) {
+      const hash = djb2Hash(token);
+
+      // Have we already processed this sound name?
+      let found = false;
+      let soundId = 0;
+      for (let i = 0; i < this.nextSoundId && !found; i++) {
+        if (this.sounds[i]!.hash === hash && this.sounds[i]!.name === token) {
+          found = true;
+          soundId = i;
+        }
+      }
+
+      if (!found) {
+        soundId = this.nextSoundId;
+        // Add the new sound to the pool (grow_sound_list is implicit here).
+        const entry: SoundData = {
+          name: token,
+          hash,
+          status: SoundStatus.UNKNOWN,
+          platData: null,
+        };
+        this.sounds[soundId] = entry;
+        if (this.preloadSounds) this.loadSound(entry);
+        this.nextSoundId++;
+      }
+
+      // Add this sound (by id) to the message->sounds map. The C caps at
+      // MAX_SOUNDS_PER_MESSAGE - 1 (an off-by-one that keeps at most 15).
+      if (msg.numSounds < MAX_SOUNDS_PER_MESSAGE - 1) {
+        msg.soundIds[msg.numSounds] = soundId;
+        msg.numSounds++;
+      }
+    }
+  }
+
+  /**
+   * play_sound (sound-core.c, L309): pick one of the message's samples at
+   * random, lazily load it if still UNKNOWN, and play it only if LOADED.
+   * A no-op when the message has no sounds or no play hook is installed.
+   */
+  playSound(messageType: number): void {
+    if (!this.hooks.playSound) return;
+
+    const msg = this.messageSounds[messageType];
+    if (!msg || msg.numSounds === 0) return; // No sounds for this message.
+
+    const s = this.randint0(msg.numSounds);
+    const soundId = msg.soundIds[s]!;
+    const sound = this.sounds[soundId];
+    if (!sound) return;
+
+    // Ensure the sound is loaded before we play it.
+    if (sound.status === SoundStatus.UNKNOWN) this.loadSound(sound);
+
+    // Only bother playing it if the platform can.
+    if (sound.status === SoundStatus.LOADED) this.hooks.playSound(sound);
+  }
+
+  /**
+   * Load the message->sound map from parsed sound.prf entries. Faithful to
+   * register_sound_pref_parser + parse_prefs_sound: each entry's type name
+   * is resolved via message_lookup_by_name, then message_sound_define is
+   * applied. Entries with an unknown message name are skipped (upstream
+   * returns PARSE_ERROR_INVALID_MESSAGE for that line).
+   */
+  loadPrefs(entries: readonly { type: string; sounds: string }[]): void {
+    for (const e of entries) {
+      const idx = messageLookupByName(e.type);
+      if (idx < 0) continue;
+      this.messageSoundDefine(idx, e.sounds);
+    }
+  }
+
+  /**
+   * init_sound (sound-core.c, L356): open the platform audio and subscribe
+   * to the EVENT_SOUND stream. Returns true on success. The core-agnostic
+   * form takes the game event bus to subscribe on.
+   */
+  init(events: GameEvents): boolean {
+    if (this.hooks.openAudio && !this.hooks.openAudio()) return false;
+    this.soundHandler = (_type, data): void => this.playSound(data.type);
+    events.on("sound", this.soundHandler);
+    // Mark as inited even with no open hook, matching a module that just
+    // installs a play hook; is_sound_inited keys off the pool below.
+    return true;
+  }
+
+  /**
+   * close_sound (sound-core.c, L392): unload every pooled sound, free the
+   * pool, and close platform audio. Detaches the event handler too.
+   */
+  close(events?: GameEvents): void {
+    if (events && this.soundHandler) {
+      events.off("sound", this.soundHandler);
+    }
+    this.soundHandler = null;
+
+    if (this.nextSoundId !== 0 && this.hooks.unloadSound) {
+      for (let i = 0; i < this.nextSoundId; i++) {
+        this.hooks.unloadSound(this.sounds[i]!);
+      }
+    }
+    this.sounds = [];
+    this.nextSoundId = 0;
+    for (const m of this.messageSounds) {
+      m.numSounds = 0;
+      m.soundIds = [];
+    }
+    if (this.hooks.closeAudio) this.hooks.closeAudio();
+  }
+
+  /** is_sound_inited (sound-core.c, L423): a pool means it was opened. */
+  isSoundInited(): boolean {
+    return this.nextSoundId !== 0;
+  }
+
+  // ---- Introspection helpers (not upstream; for wiring and tests) ----
+
+  /** Number of pooled samples (== next_sound_id). */
+  soundCount(): number {
+    return this.nextSoundId;
+  }
+
+  /** Number of samples mapped to a message type. */
+  messageSoundCount(messageType: number): number {
+    return this.messageSounds[messageType]?.numSounds ?? 0;
+  }
+
+  /** The sample base-names mapped to a message type, in order. */
+  messageSampleNames(messageType: number): string[] {
+    const msg = this.messageSounds[messageType];
+    if (!msg) return [];
+    return msg.soundIds
+      .slice(0, msg.numSounds)
+      .map((id) => this.sounds[id]!.name);
+  }
+
+  /** The pooled SoundData for a sample name, or undefined. */
+  findSound(name: string): SoundData | undefined {
+    const hash = djb2Hash(name);
+    for (let i = 0; i < this.nextSoundId; i++) {
+      if (this.sounds[i]!.hash === hash && this.sounds[i]!.name === name) {
+        return this.sounds[i];
+      }
+    }
+    return undefined;
+  }
+}

package/src/sound/index.ts

@@ -0,0 +1,13 @@
+/**
+ * The sound subsystem: a platform-agnostic engine (engine.ts) plus the
+ * message->sound name mapping data (sound-prefs-data.ts), ported from
+ * reference/src/sound-core.c, sound.h, and reference/lib/customize/sound.prf.
+ *
+ * A front end supplies SoundHooks (load/play audio) and an RNG seam; the
+ * core selects samples faithfully to play_sound. No audio assets are
+ * bundled - the web front end loads a user-supplied pack.
+ */
+
+export * from "./types.js";
+export * from "./engine.js";
+export * from "./sound-prefs-data.js";

package/src/sound/sound-prefs-data.ts

@@ -0,0 +1,173 @@
+// Generated from reference/lib/customize/sound.prf by
+// scripts/gen-sound-prefs.mjs. Do not edit.
+//
+// The message->sound NAME MAPPING (functional data) from the Dubtrain
+// Angband sound config. Each entry is one `sound:<MSG_NAME>:<samples>`
+// directive: 'type' is the MSG_ name (message_lookup_by_name), 'sounds' is
+// the raw space-separated list of sample base-names (no path, no extension).
+//
+// NO AUDIO ASSETS are bundled: the Dubtrain .mp3 pack is Creative-Commons
+// NON-COMMERCIAL. This repo has commercial intent, so only the name mapping
+// is ported. A web front end loads user-supplied audio from a configurable
+// base URL (see packages/web/src/sound.ts).
+
+/** One parsed `sound:` directive from sound.prf. */
+export interface SoundPrefEntry {
+  /** MSG_ name (feeds message_lookup_by_name). */
+  readonly type: string;
+  /** Space-separated sample base-names, exactly as in the prf. */
+  readonly sounds: string;
+}
+
+/** Every `sound:` directive from sound.prf, in file order. */
+export const SOUND_PREF_ENTRIES: readonly SoundPrefEntry[] = [
+  { type: "AMBIENT_DAY", sounds: "amb_thunder_rain" },
+  { type: "AMBIENT_NITE", sounds: "amb_guitar_chord amb_thunder_roll" },
+  { type: "AMBIENT_DNG1", sounds: "amb_door_iron amb_bell_metal1" },
+  { type: "AMBIENT_DNG2", sounds: "amb_bell_tibet1 amb_bell_metal2 amb_gong_strike" },
+  { type: "AMBIENT_DNG3", sounds: "amb_bell_tibet2 amb_dungeon_echo amb_pulse_low" },
+  { type: "AMBIENT_DNG4", sounds: "amb_bell_tibet3 amb_dungeon_echowet amb_gong_undertone" },
+  { type: "AMBIENT_DNG5", sounds: "amb_door_doom amb_gong_chinese amb_gong_low" },
+  { type: "STORE1", sounds: "sto_man_hey" },
+  { type: "STORE2", sounds: "id_bad_dang" },
+  { type: "STORE3", sounds: "sto_man_haha" },
+  { type: "STORE4", sounds: "sto_man_whoohaha" },
+  { type: "STORE5", sounds: "sto_coins_countertop sto_bell_register1 sto_bell_register2" },
+  { type: "STORE_ENTER", sounds: "sto_bell_desk sto_bell_ding sto_bell_dingaling sto_bell_jingles sto_bell_ringing sto_bell_shop" },
+  { type: "STORE_HOME", sounds: "plm_door_entrance" },
+  { type: "STORE_LEAVE", sounds: "plm_door_bolt" },
+  { type: "HIT", sounds: "plc_hit_hay plc_hit_body" },
+  { type: "HIT_GOOD", sounds: "plc_hit_anvil" },
+  { type: "HIT_GREAT", sounds: "plc_hit_groan" },
+  { type: "HIT_SUPERB", sounds: "plc_hit_grunt" },
+  { type: "HIT_HI_GREAT", sounds: "plc_hit_grunt2" },
+  { type: "HIT_HI_SUPERB", sounds: "plc_hit_anvil2" },
+  { type: "MISS", sounds: "plc_miss_arrow2" },
+  { type: "SHOOT", sounds: "plc_miss_arrow" },
+  { type: "SHOOT_HIT", sounds: "plc_hit_arrow" },
+  { type: "HITPOINT_WARN", sounds: "plc_bell_warn" },
+  { type: "DEATH", sounds: "plc_die_laugh" },
+  { type: "BLIND", sounds: "pls_tone_conk" },
+  { type: "CONFUSED", sounds: "pls_man_ugh" },
+  { type: "POISONED", sounds: "pls_tone_guiro" },
+  { type: "AFRAID", sounds: "pls_man_yell" },
+  { type: "PARALYZED", sounds: "pls_man_gulp_new" },
+  { type: "DRUGGED", sounds: "pls_breathe_in" },
+  { type: "SLOW", sounds: "pls_man_sigh" },
+  { type: "STUN", sounds: "pls_bell_mute" },
+  { type: "CUT", sounds: "pls_man_argoh" },
+  { type: "DRAIN_STAT", sounds: "pls_tone_headstock" },
+  { type: "RECOVER", sounds: "pls_bell_chime_new" },
+  { type: "SPEED", sounds: "pls_bell_sustain" },
+  { type: "SHIELD", sounds: "pls_bell_bowl" },
+  { type: "BLESSED", sounds: "sum_ainu_song" },
+  { type: "HERO", sounds: "pls_tone_goblet" },
+  { type: "BOLD", sounds: "pls_bell_hibell_soft" },
+  { type: "BERSERK", sounds: "pls_man_scream2" },
+  { type: "PROT_EVIL", sounds: "pls_bell_glass" },
+  { type: "INVULN", sounds: "pls_tone_blurk" },
+  { type: "SEE_INVIS", sounds: "pls_tone_clave6" },
+  { type: "INFRARED", sounds: "pls_tone_clavelo8" },
+  { type: "RES_ACID", sounds: "pls_man_sniff" },
+  { type: "RES_ELEC", sounds: "pls_tone_elec" },
+  { type: "RES_FIRE", sounds: "pls_tone_scrape" },
+  { type: "RES_COLD", sounds: "pls_tone_stick" },
+  { type: "RES_POIS", sounds: "pls_man_spit" },
+  { type: "HUNGRY", sounds: "pls_man_sob" },
+  { type: "MONEY1", sounds: "plm_coins_light plm_coins_shake" },
+  { type: "MONEY2", sounds: "plm_chain_light plm_coins_pour" },
+  { type: "MONEY3", sounds: "plm_coins_dump" },
+  { type: "DROP", sounds: "plm_drop_boot" },
+  { type: "LEVEL", sounds: "plm_levelup" },
+  { type: "STUDY", sounds: "plm_book_pageturn" },
+  { type: "TELEPORT", sounds: "plm_chimes_jangle" },
+  { type: "QUAFF", sounds: "plm_bottle_clinks plm_cork_pop plm_cork_squeak" },
+  { type: "ZAP_ROD", sounds: "plm_zap_rod" },
+  { type: "TPOTHER", sounds: "plm_chimes_jangle" },
+  { type: "HITWALL", sounds: "plm_wood_thud" },
+  { type: "EAT", sounds: "plm_eat_bite" },
+  { type: "DIG", sounds: "plm_metal_clank" },
+  { type: "OPENDOOR", sounds: "plm_door_bolt plm_door_creak plm_door_dungeon plm_door_entrance plm_door_open plm_door_opening plm_door_rusty plm_door_squeaky" },
+  { type: "SHUTDOOR", sounds: "plm_bang_dumpster plm_cabinet_shut plm_close_hatch plm_door_creakshut plm_door_latch plm_door_shut plm_door_slam" },
+  { type: "TPLEVEL", sounds: "sum_bell_crystal" },
+  { type: "BELL", sounds: "plm_jar_ding" },
+  { type: "NOTHING_TO_OPEN", sounds: "plm_click_switch2 plm_door_knob" },
+  { type: "LOCKPICK_FAIL", sounds: "plm_click_dry plm_click_switch plm_click_wood plm_door_echolock plm_door_wooden" },
+  { type: "LOCKPICK", sounds: "plm_break_wood plm_cabinet_open plm_chest_unlatch plm_lock_case plm_lock_distant plm_open_case" },
+  { type: "DISARM", sounds: "plm_bang_ceramic plm_chest_latch plm_click_switch3" },
+  { type: "STAIRS_UP", sounds: "plm_floor_creak2" },
+  { type: "STAIRS_DOWN", sounds: "plm_floor_creak" },
+  { type: "ACT_ARTIFACT", sounds: "plm_aim_wand" },
+  { type: "USE_STAFF", sounds: "plm_use_staff" },
+  { type: "DESTROY", sounds: "plm_bang_metal plm_break_canister plm_break_glass plm_break_glass2 plm_break_plates plm_break_shatter plm_break_smash plm_glass_breaking plm_glass_break plm_glass_smashing" },
+  { type: "WIELD", sounds: "plm_metal_sharpen" },
+  { type: "QUIVER", sounds: "plc_miss_swish" },
+  { type: "CURSED", sounds: "pls_man_oooh" },
+  { type: "NOTICE", sounds: "id_bad_hmm" },
+  { type: "RUNE", sounds: "id_good_hmm" },
+  { type: "SPELL", sounds: "plm_spell1 plm_spell2 plm_spell3" },
+  { type: "PRAYER", sounds: "sum_ainu_song" },
+  { type: "FLEE", sounds: "mco_creature_yelp" },
+  { type: "KILL", sounds: "mco_howl_croak mco_howl_deep mco_howl_distressed mco_howl_high mco_howl_long" },
+  { type: "KILL_UNIQUE", sounds: "sum_ghost_wail" },
+  { type: "KILL_KING", sounds: "amb_guitar_chord" },
+  { type: "MON_HIT", sounds: "mco_hit_whip" },
+  { type: "MON_TOUCH", sounds: "mco_click_vibra" },
+  { type: "MON_PUNCH", sounds: "mco_squish_snap" },
+  { type: "MON_KICK", sounds: "mco_rubber_thud" },
+  { type: "MON_CLAW", sounds: "mco_ceramic_trill mco_scurry_dry" },
+  { type: "MON_BITE", sounds: "mco_snarl_short mco_bite_soft mco_bite_munch mco_bite_long mco_bite_short mco_bite_gnash mco_bite_chomp mco_bite_regular mco_bite_small mco_bite_dainty mco_bite_hard mco_bite_chew" },
+  { type: "MON_STING", sounds: "mco_castanet_trill mco_tube_hit" },
+  { type: "MON_BUTT", sounds: "mco_cuica_rubbing mco_thud_crash" },
+  { type: "MON_CRUSH", sounds: "mco_dino_low mco_squish_hit" },
+  { type: "MON_ENGULF", sounds: "mco_dino_talk mco_dino_yawn" },
+  { type: "MON_CRAWL", sounds: "mco_card_shuffle mco_shake_roll" },
+  { type: "MON_DROOL", sounds: "mco_creature_choking mco_liquid_squirt" },
+  { type: "MON_SPIT", sounds: "mco_attack_spray" },
+  { type: "MON_GAZE", sounds: "mco_thoing_backwards" },
+  { type: "MON_WAIL", sounds: "mco_dino_low" },
+  { type: "MON_SPORE", sounds: "mco_dub_wobble mco_spray_long" },
+  { type: "MON_BEG", sounds: "mco_man_mumble" },
+  { type: "MON_INSULT", sounds: "mco_strange_thwoink" },
+  { type: "MON_MOAN", sounds: "mco_strange_music" },
+  { type: "SHRIEK", sounds: "mco_mouse_squeaks" },
+  { type: "CREATE_TRAP", sounds: "mco_thoing_deep" },
+  { type: "CAST_FEAR", sounds: "mco_creature_groan mco_dino_slur" },
+  { type: "MULTIPLY", sounds: "mco_frog_trill" },
+  { type: "SUM_MONSTER", sounds: "sum_chime_jangle" },
+  { type: "SUM_AINU", sounds: "sum_ainu_song" },
+  { type: "SUM_UNDEAD", sounds: "sum_ghost_oooo" },
+  { type: "SUM_ANIMAL", sounds: "sum_lion_growl" },
+  { type: "SUM_SPIDER", sounds: "sum_piano_scrape" },
+  { type: "SUM_HOUND", sounds: "sum_lion_growl" },
+  { type: "SUM_HYDRA", sounds: "sum_piano_scrape" },
+  { type: "SUM_DEMON", sounds: "sum_ghost_wail sum_laugh_evil2" },
+  { type: "SUM_DRAGON", sounds: "sum_piano_scrape" },
+  { type: "SUM_HI_UNDEAD", sounds: "sum_ghost_moan" },
+  { type: "SUM_HI_DRAGON", sounds: "sum_gong_temple" },
+  { type: "SUM_HI_DEMON", sounds: "sum_ghost_moan" },
+  { type: "SUM_WRAITH", sounds: "sum_bell_hand" },
+  { type: "SUM_UNIQUE", sounds: "sum_bell_tone" },
+  { type: "BR_FROST", sounds: "mco_attack_breath" },
+  { type: "BR_ELEC", sounds: "mco_attack_breath" },
+  { type: "BR_ACID", sounds: "mco_attack_breath" },
+  { type: "BR_GAS", sounds: "mco_attack_breath" },
+  { type: "BR_FIRE", sounds: "mco_attack_breath" },
+  { type: "BR_DISEN", sounds: "mco_attack_breath" },
+  { type: "BR_CHAOS", sounds: "mco_attack_breath" },
+  { type: "BR_SHARDS", sounds: "mco_attack_breath" },
+  { type: "BR_SOUND", sounds: "mco_attack_breath" },
+  { type: "BR_LIGHT", sounds: "mco_attack_breath" },
+  { type: "BR_DARK", sounds: "mco_attack_breath" },
+  { type: "BR_NETHER", sounds: "mco_attack_breath" },
+  { type: "BR_NEXUS", sounds: "mco_attack_breath" },
+  { type: "BR_TIME", sounds: "mco_attack_breath" },
+  { type: "BR_INERTIA", sounds: "mco_attack_breath" },
+  { type: "BR_GRAVITY", sounds: "mco_attack_breath" },
+  { type: "BR_PLASMA", sounds: "mco_attack_breath" },
+  { type: "BR_FORCE", sounds: "mco_attack_breath" },
+  { type: "BR_ELEMENTS", sounds: "mco_attack_breath" },
+  { type: "IDENT_BAD", sounds: "id_bad_aww id_bad_dang id_bad_hmm id_bad_hmph id_bad_ohh" },
+  { type: "IDENT_EGO", sounds: "id_ego_whoa id_ego_woohoo id_ego_yeah id_ego_yeah2 id_ego_yes" },
+  { type: "IDENT_ART", sounds: "id_good_hey id_good_hey2 id_good_hmm id_good_huh id_good_ooh id_good_ooo id_good_wow" },
+];

package/src/sound/types.ts

@@ -0,0 +1,68 @@
+/**
+ * Sound subsystem types, ported from reference/src/sound.h (Angband 4.2.6).
+ *
+ * These are the platform-agnostic data structures and the platform hook
+ * seam. The core engine (engine.ts) owns the message->sound map, the sound
+ * pool, load-status tracking, and random selection; a front end supplies
+ * the hooks that actually load and play audio. Nothing here touches the DOM
+ * or any browser audio API.
+ */
+
+/** MAX_SOUNDS_PER_MESSAGE (sound-core.c): cap on samples mapped per message. */
+export const MAX_SOUNDS_PER_MESSAGE = 16;
+
+/**
+ * enum sound_status (sound.h). UNKNOWN: nothing done yet. ERROR: the file
+ * exists but the platform could not make it playable. LOADED: playable.
+ * The core checks for LOADED before asking the platform to play.
+ */
+export enum SoundStatus {
+  UNKNOWN = 0,
+  ERROR = 1,
+  LOADED = 2,
+}
+
+/**
+ * struct sound_data (sound.h): one sound sample.
+ *  name:      base name (no path, no extension)
+ *  hash:      djb2 hash of name, to speed up dedup searches
+ *  status:    SoundStatus (see above)
+ *  platData:  platform-specific handle (the C void *plat_data); the core
+ *             never inspects it, it only hands it back to the hooks.
+ */
+export interface SoundData {
+  name: string;
+  hash: number;
+  status: SoundStatus;
+  platData: unknown;
+}
+
+/**
+ * struct sound_file_type (sound.h): a file extension the platform can load
+ * and the platform-defined numeric type it maps to. `type` 0 terminates the
+ * upstream array; here the list is simply finite.
+ */
+export interface SoundFileType {
+  readonly extension: string;
+  readonly type: number;
+}
+
+/**
+ * struct sound_hooks (sound.h): the platform sound module. A front end
+ * implements these; the core calls them. Every hook is optional so the core
+ * degrades gracefully (silent) when a platform provides none.
+ *
+ * loadSound mirrors load_sound_hook: given a resolved filename and file
+ * type it should set data.platData / data.status and return true on
+ * success. supportedFiles mirrors supported_files_hook: the extensions to
+ * try, in order. playSound mirrors play_sound_hook. unloadSound and the
+ * open/close audio hooks round out the C struct.
+ */
+export interface SoundHooks {
+  openAudio?: () => boolean;
+  closeAudio?: () => void;
+  loadSound?: (filename: string, fileType: number, data: SoundData) => boolean;
+  unloadSound?: (data: SoundData) => boolean;
+  playSound?: (data: SoundData) => boolean;
+  supportedFiles?: () => readonly SoundFileType[];
+}