Operator battle voices: the official combat lines play by voice slot during battles, one at a time (#73)

Deploy, skill and result lines come from the operators' official voice slots; a newer line takes the channel over (stale callbacks of the replaced line no longer release it), and the result line is spoken by an operator of the player's own battle. Contributed by @Convey123.

tools/assets/plan.mjs

@@ -20,10 +20,16 @@
 
 import { RAW, joinUrl, safeName, urlBase, urlDir } from './sources.mjs';
 import { kindOf } from './formats.mjs';
-import { pickUnitSfx, UI_SFX, BATTLE_SFX, resolveSpec } from './audio.mjs';
+import { pickUnitSfx, UI_SFX, BATTLE_SFX, resolveSpec, indexVoice, VOICE_DIRS, VOICE_BATTLE_SLOTS } from './audio.mjs';
 import { literal } from './manifest.mjs';
 import { EMOTE_CATALOG } from '../../shared/constants.js';
 
+/**
+ * The voice slots are read from the zh_CN charword table, whose voiceIds are always `CN_*`: the other dubs
+ * (`--voice-lang=jp|en|kr`) share the very same slot numbering and file names, only the dump folder differs.
+ */
+const VOICE_ID_LANG = 'CN';
+
 /**
  * Enemies whose Spine no community dump carries: the web model is another enemy's (research 07 §5.6). Their official
  * models come from the local client only (tools/local-extract ENEMY_SPINES): `localEnemySpines` adds them as the
@@ -127,6 +133,14 @@ function leaf(...alts) {
   return list.length ? { alts: list } : null;
 }
 
+/** One operator voice line: charword voiceAsset ('char_263_skadi/CN_023') → `audio/voice/<lang>/<charId>/cn_023.mp3`. */
+function voiceAlt(asset, lang) {
+  const [charId, voiceId] = String(asset).split('/');
+  if (!charId || !voiceId || !/^[a-z0-9_]+$/i.test(charId) || !/^[a-z]{2}_\d+$/i.test(voiceId)) return null;
+  const file = `${charId}/${voiceId.toLowerCase()}.mp3`;
+  return alt(`audio/voice/${lang}/${file}`, joinUrl(RAW.aa2voice, `${VOICE_DIRS[lang]}/${file}`));
+}
+
 /** Sound path under sound_beta_2 → alternative under public/assets/audio/<sub>. */
 function soundAlt(path, sub = 'sfx') {
   const rel = `audio/${sub}/` + path.split('/').map(safeName).join('/');
@@ -251,6 +265,11 @@ export function collectEnemyIds({ assets07, enemies05, maps05, ops03 }) {
  * @param {any} p.maps05 docs/research/05-maps.json
  * @param {ReturnType<import('./audio.mjs').indexAudio>} p.audio indexed audio_data.json
  * @param {any} p.modelsData Ark-Models models_data.json
+ * @param {any} [p.charword] parsed excel/charword_table.json — the operators' official voice slots (voice)
+ * @param {string} [p.voiceLang] voice dump to plan: cn (default) | jp | en | kr
+ * @param {Iterable<string>|null} [p.voiceSlots] which voice slots to plan: VOICE_BATTLE_SLOTS (default) plans only the
+ *   lines a battle can play, null plans every slot of audio.mjs VOICE_SLOTS (`--voice-all`). The prep-only slots
+ *   (干员报到 / 编入队伍 / 任命队长) are never requested by the client and cost 360 files / 19.3 MB of downloads.
  * @param {string[]} [p.extraEnemyIds] more enemy ids that can spawn (e.g. keys of data/enemies.json)
  * @param {string[]} [p.extraTokenIds] more token ids (e.g. token_* keys of data/tokens.json)
  * @param {Record<string,string>} [p.extraHandbook] enemyId → handbook/model id (e.g. from data/bosses.json)
@@ -259,7 +278,9 @@ export function collectEnemyIds({ assets07, enemies05, maps05, ops03 }) {
  *   gets `spineLocal` = { group: 'spine/enemy/<id>', ...meta } beside its web `spine`
  * @returns {{ template: any, models: Map<string, any>, notes: string[] }}
  */
-export function buildPlan({ assets07, ops03, enemies05, maps05, audio, modelsData, extraEnemyIds = [], extraTokenIds = [], extraHandbook = {}, localEnemySpines = {} }) {
+export function buildPlan({ assets07, ops03, enemies05, maps05, audio, modelsData, charword = null, voiceLang = 'cn',
+  voiceSlots = VOICE_BATTLE_SLOTS,
+  extraEnemyIds = [], extraTokenIds = [], extraHandbook = {}, localEnemySpines = {} }) {
   const notes = [];
   /** @type {Map<string, any>} */
   const models = new Map();
@@ -533,9 +554,38 @@ export function buildPlan({ assets07, ops03, enemies05, maps05, audio, modelsDat
   const sfxBattle = {};
   for (const [name, spec] of Object.entries(BATTLE_SFX)) { const l = soundLeaf(resolveSpec(spec, audio.bank)); if (l) sfxBattle[name] = l; else notes.push(`battle SFX ${name}: no sound`); }
 
+  // --- 干员战斗语音 (excel/charword_table.json → audio.voice) ---------------------------------------------
+  // The official lines of every operator the mode can field, for the slots a battle can actually play: 行动出发 start /
+  // 行动开始 faceEnemy / 选中干员 select / 部署 place / 作战中1-4 skillN / 结算 result* (charword `placeType`,
+  // audio.mjs VOICE_BATTLE_SLOTS). A slot with several lines stays an array — the client draws one at random
+  // (public/js/audio.js voice). Operators without official battle voice keep no entry at all: the 17 预备干员
+  // (char_60x_c*, char_617_sharp2) and the mode's own 盟约·辅助干员 (char_616_pithst).
+  // The three prep-only slots (干员报到 gacha / 编入队伍 squad / 任命队长 squadFirst) are NOT planned by default: the
+  // client never requests them, and downloading them adds 360 files / 19.3 MB to every `npm run assets` — pass --voice-all for
+  // the complete official set (`voiceSlots: null`, reviewer note on the voice PR).
+  const voice = {};
+  for (const [charId, slots] of indexVoice(charword, VOICE_ID_LANG, voiceSlots)) {
+    if (!chars[charId]) continue;            // only the operators this game can field (the 138-pool charIds)
+    const v = {};
+    for (const [slot, assets] of Object.entries(slots)) {
+      // one leaf per line (部署1 / 部署2 …): an array stays an array so the client can draw one — chaining them as
+      // alternatives of a single leaf would keep only the first line that landed on disk.
+      const lines = assets.map((a) => leaf(voiceAlt(a, voiceLang))).filter(Boolean);
+      if (!lines.length) continue;
+      v[slot] = lines.length === 1 ? lines[0] : lines;
+    }
+    if (Object.keys(v).length) voice[charId] = v;
+  }
+  if (!Object.keys(voice).length) notes.push('battle voice: charword_table.json has no slots (index missing?)');
+
   const template = {
     chars, enemies, tokens, bonds, items, bands, skills, skillsById, ui, prof,
-    audio: { bgm, bossBgm: Object.fromEntries(Object.entries(bossBgm).sort(([a], [b]) => a.localeCompare(b, 'en', { numeric: true }))), sfx: { ui: sfxUi, battle: sfxBattle, units: unitsSfx } },
+    audio: {
+      bgm,
+      bossBgm: Object.fromEntries(Object.entries(bossBgm).sort(([a], [b]) => a.localeCompare(b, 'en', { numeric: true }))),
+      voice,
+      sfx: { ui: sfxUi, battle: sfxBattle, units: unitsSfx },
+    },
   };
   return { template, models, notes };
 }