初始化仓库：友乐/gameabc 房卡游戏平台脚手架（client + server + docs）

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-01 18:13:26 +08:00
commit 594820d393
655 changed files with 310861 additions and 0 deletions
@@ -0,0 +1,108 @@
+/**
+ * ============================================================================
+ * SoundResources.template.js - 音效资源常量定义规范
+ * ============================================================================
+ *
+ * 使用方式：
+ *   将此文件复制到游戏项目中，重命名为 SoundResources.js。
+ *   所有文件名必须与实际音效文件完全一致，不可自行编造。
+ *
+ * ============================================================================
+ * 文件命名规范
+ * ============================================================================
+ *
+ *   音效文件名 = 5位数字补零 + .mp3，例如：
+ *     ID=101 → '00101.mp3'
+ *     ID=151 → '00151.mp3'
+ *
+ * ============================================================================
+ * ID 分配规范
+ * ============================================================================
+ *
+ *   框架保留：00001–00100（平台系统音效，子游戏严禁占用）
+ *   子游戏范围：00101+（EFFECTS / VOICE / MUSIC 的具体分段按项目自行规划）
+ *
+ * ============================================================================
+ * 性别语音规则（AudioManager 依赖此规范）
+ * ============================================================================
+ *
+ *   男性语音 ID = 基础 ID（151+）
+ *   女性语音 ID = 男性语音 ID + FEMALE_VOICE_OFFSET（默认 100）
+ *   规律：男性 '00151.mp3' 对应 女性 '00251.mp3'
+ *
+ *   AudioManager.playActionVoiceBySeat(seat, action) 会根据该座位的
+ *   sex 字段（sex===2 为女性）自动选择正确的语音文件，
+ *   MALE 和 FEMALE 两组键名必须保持一一对应。
+ *
+ * ============================================================================
+ * 调用示例（供理解结构，不代表实际值）
+ * ============================================================================
+ *
+ *   AudioManager.playSound(SoundResources.EFFECTS.DISCARD);
+ *   // 游戏侧 GameAudio 封装 ID 映射，再调用框架层通用 API：
+ *   AudioManager.playVoiceBySeat(seat, ACTION_VOICE_BASE_ID['chi']);   // 自动按性别选语音
+ *   AudioManager.playVoiceBySeat(seat, CARD_VOICE_BASE_ID[cardValue]); // 自动按性别选报牌语音
+ *   AudioManager.playMusic();
+ *
+ * @see AudioManager.js  音频播放管理（gameabc-framework/system/）
+ * @see GameAudio.js     游戏专属 ID 映射（子游戏目录，如 game/managers/GameAudio.js）
+ */
+
+'use strict';
+
+var SoundResources = {
+
+    // ========================================================================
+    // EFFECTS - 通用音效
+    // ========================================================================
+    EFFECTS: {
+
+        // 操作动效音 ≠ 操作语音：
+        //   操作动效音 = 文字弹出时的短促音效（在 EFFECTS 中定义）
+        //   操作语音   = 玩家喊出操作词的人声（在 VOICE 中定义）
+
+        // DISCARD:     '<实际文件名>',
+        // DRAW:        '<实际文件名>',
+        // GAME_START:  '<实际文件名>',
+        // WIN:         '<实际文件名>',
+        // CHI_EFFECT:  '<实际文件名>',
+        // ...
+    },
+
+    // ========================================================================
+    // VOICE - 语音（按性别分组）
+    // 规则：女性语音文件 ID = 对应男性语音文件 ID + FEMALE_VOICE_OFFSET（默认100）
+    //       MALE 和 FEMALE 两组键名必须完全一一对应，AudioManager 依赖此结构
+    // ========================================================================
+    VOICE: {
+
+        MALE: {
+            // 操作语音键名（固定，AudioManager 按此查找）：
+            // CHI / PONG / KONG / HU / TING / PASS / ZIMO
+            // CHI:  '<实际文件名>',
+            // ...
+
+            // 报牌语音键名建议统一为 <SUIT>_<VALUE>
+            // 示例：WAN_1, WAN_2, ... TIAO_1, ... TONG_1, ... DONG, NAN, XI, BEI, ZHONG, FA, BAI
+            // WAN_1: '<实际文件名>',
+            // ...
+        },
+
+        FEMALE: {
+            // 键名与 MALE 完全相同，对应文件 ID + 100
+            // CHI:  '<实际文件名>',
+            // WAN_1: '<实际文件名>',
+            // ...
+        }
+    },
+
+    // ========================================================================
+    // MUSIC - 背景音乐
+    // 需同时在 game_config.soundList 中配置预加载
+    // ========================================================================
+    MUSIC: {
+        // GAME_BGM: '<实际文件名>',
+        // ROOM_BGM: '<实际文件名>',
+    }
+};
+