399 lines
34 KiB
Markdown
399 lines
34 KiB
Markdown
# 《冰冷的她醒来之前》数字版开发指导文档
|
||
|
||
## 1. 项目概述
|
||
|
||
### 技术选型
|
||
- **客户端**：C++20 + Qt6 (Widgets 模式，非 QML)
|
||
- **服务端**：Go 1.22+
|
||
- **通信层**：WebSocket + JSON（游戏逻辑与信令）；WebRTC（实时语音媒体传输）
|
||
- **语音架构**：客户端点对点（P2P）或选择性转发（SFU），服务端提供信令中继与房间管理
|
||
- **架构模式**：客户端-服务器架构，服务端持有绝对权威
|
||
|
||
### 核心设计原则
|
||
1. **服务端绝对权威**：所有游戏状态、逻辑判定、胜负计算、随机过程（洗牌）均由服务端完成。客户端仅负责渲染与输入采集。
|
||
2. **状态快照同步**：服务端以完整游戏状态快照的形式向客户端广播，客户端在收到快照后更新本地视图。禁止客户端本地预测游戏结果。
|
||
3. **信息隔离**：反面朝上的卡牌、其他玩家的手牌内容、尚未结算的质疑牌等敏感信息，在未被服务端授权前不得向客户端传输。客户端无法通过内存读取或抓包获知隐藏信息。
|
||
4. **数据可配置化**：卡牌的具体属性（名称、人力值、优先顺序、胜利条件、效果描述、张数配置）全部外置为配置文件，由用户自行填写，程序只读取配置运行。
|
||
|
||
---
|
||
|
||
## 2. 客户端架构说明
|
||
|
||
### 2.1 渲染框架
|
||
采用 Qt6 Widgets + QGraphicsScene 构建游戏主场景。场景按功能划分为若干逻辑层：
|
||
|
||
- **背景层**：桌面、环境装饰
|
||
- **公共区域层**：少女的尸体牌、调和区、信息提示牌
|
||
- **玩家区域层**：每个玩家对应一个独立面板，包含其已使用特技区、质疑区、手牌数量指示器
|
||
- **本地手牌层**：当前玩家自己的手牌，以可交互的卡牌视图呈现
|
||
- **动画层**：卡牌移动、翻转、传递的过渡动画覆盖在所有层之上
|
||
- **UI控件层**：行动菜单、弹窗、倒计时、日志面板
|
||
|
||
### 2.2 卡牌视图对象
|
||
每张卡牌对应一个独立的图形对象，具备以下状态：
|
||
- **正面/反面**：正面显示卡牌的立绘与文字，反面显示统一的卡背图案
|
||
- **选中/未选中**：高亮边框或抬升效果
|
||
- **可用/禁用**：根据当前回合阶段，不可操作的卡牌降低透明度或置灰
|
||
- **锁定**：暂时退出玩家的手牌进入锁定状态，不可被交互
|
||
|
||
卡牌对象的正面图像资源通过卡牌类型标识符从外部加载，程序不硬编码任何卡牌美术资源路径。
|
||
|
||
### 2.3 动画系统
|
||
关键动画效果包括：
|
||
- **放置动画**：卡牌从手牌区飞向目标区域（调和区、质疑区、已使用区）
|
||
- **翻转动画**：结算阶段时，反面朝上的卡牌逐渐翻转为正面，使用缩放模拟3D翻转
|
||
- **传递动画**：新闻部等效果导致手牌在玩家之间传递时，卡牌沿贝塞尔曲线路径飞行
|
||
- **高亮动画**：需要玩家做出选择时，可选目标脉冲闪烁
|
||
|
||
动画播放期间应阻塞玩家输入，防止在动画未完成时发送操作指令。
|
||
|
||
### 2.4 实时语音模块
|
||
客户端集成独立的语音通信子系统，与游戏逻辑模块解耦。
|
||
|
||
**音频采集与播放**
|
||
- 使用平台原生音频 API 或 Qt Multimedia 模块进行麦克风采集与扬声器播放
|
||
- 支持 16kHz/48kHz 采样率，单声道，Opus 编码
|
||
- 本地播放其他玩家的音频流，支持独立音量调节
|
||
|
||
**网络传输**
|
||
- 媒体流通过 WebRTC 传输，信令复用现有的 WebSocket 连接
|
||
- 支持两种拓扑模式：
|
||
- **P2P 网状网络**：3-4 人房间时，各客户端直接互连，服务端仅转发信令
|
||
- **SFU 选择性转发**：5-6 人房间或 P2P 连接失败时，由服务端语音中继模块转发混音后的音频流
|
||
|
||
**信令流程**
|
||
- 玩家加入房间后，通过 WebSocket 发送语音就绪通知
|
||
- 服务端广播房间内其他玩家的语音端点信息（WebRTC SDP offer/answer 与 ICE candidate 通过 WebSocket 隧道传输）
|
||
- 连接建立后，音频通道与游戏通道并行运行
|
||
|
||
**语音交互界面**
|
||
- 每位玩家头像旁显示语音状态指示器：
|
||
- 静音（麦克风关闭）
|
||
- 发言中（语音活动检测触发，显示声波动画）
|
||
- 连接异常
|
||
- 全局语音开关按钮：一键关闭/开启麦克风
|
||
- 独立音量滑块：可单独调节每位玩家的接收音量
|
||
- 可选的按键发言模式（按住空格键说话）
|
||
|
||
**语音与游戏联动**
|
||
- 玩家暂时退出或断开连接时，自动将其语音通道静音
|
||
- 结算阶段动画播放期间，语音保持畅通，不强制静音
|
||
|
||
---
|
||
|
||
## 3. 服务端架构说明
|
||
|
||
### 3.1 并发模型
|
||
服务端采用 Go 的 Goroutine + Channel 模型。每个游戏房间由一个独立的逻辑 Goroutine 管理，该 Goroutine 内部维护一个事件循环，按顺序处理玩家输入、效果结算、状态广播。同一房间内的所有操作串行执行，避免并发竞争。网络 I/O 与游戏逻辑解耦，WebSocket 连接层将玩家消息投递到对应房间的 Channel 中。
|
||
|
||
### 3.2 房间管理
|
||
服务端维护一个房间列表，每个房间包含：
|
||
- 房间唯一标识
|
||
- 玩家列表（含连接状态、语音就绪状态）
|
||
- 当前游戏状态机
|
||
- 历史日志（用于断线重连后同步）
|
||
|
||
房间支持的状态：等待中、设置中、进行中、结算中、已结束。
|
||
|
||
### 3.3 游戏状态机
|
||
游戏生命周期划分为以下主阶段，顺序不可逆：
|
||
|
||
1. **等待阶段**：玩家加入、准备、房主发起开始
|
||
2. **设置阶段**：根据人数计算调和目标值，从牌库中移除指定卡牌，构建本局牌库
|
||
3. **发牌阶段**：洗牌并均分到手牌，确定起始玩家
|
||
4. **进行阶段**：主循环，玩家依次行动
|
||
5. **结算阶段**：全员暂时退出后，依次执行调和判定、质疑判定、胜利判定
|
||
6. **结束阶段**：公布结果，房间回到等待状态或自动解散
|
||
|
||
进行阶段内部可细分为子状态：
|
||
- 等待选牌
|
||
- 等待选择行动方式（特技/调和/质疑）
|
||
- 等待选择目标（质疑对象或特技目标）
|
||
- 效果结算中
|
||
- 等待效果响应（如其他玩家选牌）
|
||
- 回合结束检查
|
||
|
||
### 3.4 效果系统架构
|
||
效果系统采用策略模式或接口驱动模式。每张卡牌的能力对应一个独立的效果处理器。效果处理器注册到全局效果表中，通过卡牌类型标识符查找触发。
|
||
|
||
效果处理器需声明以下能力：
|
||
- **触发时机**：打出时触发、回合开始时触发、回合结束时触发、结算阶段触发
|
||
- **是否需要响应**：是否需要向其他玩家发送选择请求并等待回复
|
||
- **响应类型**：选牌、选人、确认、二选一
|
||
- **是否可被取消**：在何种条件下效果失效（如目标不存在、玩家已退出）
|
||
|
||
效果结算采用链式或队列式处理：若一张卡牌的效果引发了另一张卡牌的条件（如外星人回应优等生），则效果管理器按顺序入队，依次处理。
|
||
|
||
### 3.5 实时语音中继模块
|
||
服务端运行一个与游戏逻辑并行的语音信令与媒体中继层。
|
||
|
||
**信令中继**
|
||
- 复用现有 WebSocket 连接，不额外开放端口
|
||
- 定义语音专属信令消息类型：SDP offer、SDP answer、ICE candidate、语音就绪、语音断开
|
||
- 收到某玩家的信令后，向目标玩家转发，服务端不解析 SDP 内容
|
||
|
||
**SFU 媒体中继（可选）**
|
||
- 当房间人数大于 4 人或 P2P 打洞失败时，启用 SFU 模式
|
||
- 服务端接收各客户端的音频流，进行混音或选择性转发
|
||
- 使用 Go 的 WebRTC 库（如 pion/webrtc）实现
|
||
- 混音策略：最多同时转发 3 路音频，避免带宽爆炸；优先转发最近发言者
|
||
|
||
**语音房间管理**
|
||
- 语音频道生命周期与游戏房间绑定：房间创建时初始化语音会话，房间销毁时关闭
|
||
- 玩家加入房间后，可选择是否加入语音（默认不自动开启麦克风）
|
||
- 玩家断线时，服务端通知其他客户端移除该玩家的音频轨道
|
||
|
||
---
|
||
|
||
## 4. 通信协议框架
|
||
|
||
### 4.1 传输层
|
||
基于 WebSocket 的全双工通信，消息载荷为 JSON。所有消息包含统一的元数据：消息类型、时间戳、序列号（用于丢包检测与断线重连）。
|
||
|
||
### 4.2 客户端向服务端发送的消息类型
|
||
- **加入/离开房间**
|
||
- **准备/取消准备**
|
||
- **开始游戏**（仅房主）
|
||
- **选择手牌**（从手牌中指定一张）
|
||
- **确认行动**（选择特技、调和或质疑，质疑需附带目标玩家标识）
|
||
- **效果响应**（在效果处理器要求下，选择特定卡牌或玩家，或确认/取消）
|
||
- **聊天消息**（可选）
|
||
- **语音信令**（WebRTC SDP/ICE，透传至目标玩家）
|
||
- **语音状态**（麦克风开启/关闭）
|
||
|
||
### 4.3 服务端向客户端广播的消息类型
|
||
- **房间状态同步**（玩家列表、准备状态、房主）
|
||
- **游戏开始通知**（附带初始配置）
|
||
- **完整状态快照**（游戏进行中的核心同步消息，包含所有公开信息与当前玩家自己的私有信息）
|
||
- **卡牌移动事件**（某张卡牌从某区域移动到某区域，是否反面朝上）
|
||
- **卡牌翻转事件**（结算时翻开调和区或质疑区）
|
||
- **效果触发通知**（告知所有玩家某效果正在结算，以及需要响应的玩家）
|
||
- **请求选择**（向特定玩家发送弹窗请求，要求其在限时内做出选择）
|
||
- **玩家暂时退出通知**
|
||
- **结算阶段通知**（进入调和判定、质疑判定、胜利判定）
|
||
- **游戏结束通知**（获胜者列表、结局类型）
|
||
- **错误通知**（非法操作、超时、网络异常）
|
||
- **语音信令转发**（将某玩家的 SDP/ICE 转发给目标玩家）
|
||
- **语音状态同步**（广播某玩家的麦克风开启/关闭状态）
|
||
|
||
### 4.4 状态快照的信息隔离策略
|
||
状态快照是服务端向客户端同步的核心机制，必须严格遵守信息隔离：
|
||
|
||
- **自己的手牌**：完整传输卡牌标识符、类型、人力值、优先顺序
|
||
- **他人的手牌**：仅传输数量，不传输任何卡牌内容
|
||
- **调和区**：游戏进行中仅传输卡牌标识符与放置顺序，不传输类型和人力值；结算阶段由服务端单独发送翻转事件
|
||
- **质疑区**：对质疑对象（被放置卡牌的玩家）是否可见由服务端决定；对非对象玩家，仅传输质疑区存在卡牌的数量或标识符，不传输内容
|
||
- **已使用区（特技区）**：正面朝上，完整传输所有信息
|
||
- **牌库**：不传输
|
||
|
||
### 4.5 语音信令消息格式
|
||
语音相关消息复用现有 WebSocket 通道，通过消息类型字段区分：
|
||
|
||
- **SDP Offer**：发起方发送，包含目标玩家 ID 与 SDP 字符串
|
||
- **SDP Answer**：响应方发送，包含目标玩家 ID 与 SDP 字符串
|
||
- **ICE Candidate**：双方交换网络候选路径，包含目标玩家 ID、候选类型、地址信息
|
||
- **Voice Ready**：客户端通知服务端本地语音引擎初始化完成
|
||
- **Voice Toggle**：客户端通知服务端麦克风开启或关闭，服务端广播给房间内其他玩家
|
||
|
||
---
|
||
|
||
## 5. 游戏逻辑核心流程
|
||
|
||
### 5.1 设置与发牌
|
||
根据玩家人数，从完整牌库中按配置移除指定类型和数量的卡牌，形成本局牌库。洗牌后按人数均分为手牌。持有特定起始标记卡牌的玩家成为起始玩家；若该卡牌已被移除，则随机指定。
|
||
|
||
### 5.2 回合流程
|
||
当前玩家从手牌中选择一张卡牌，并选择以下三种行动之一：
|
||
|
||
1. **特技**：将卡牌正面朝上放置于自己的已使用区，并触发该卡牌的效果。部分卡牌持有即生效，无需打出；打出后可能不产生额外效果。
|
||
2. **调和**：将卡牌反面朝上放置于调和区（尸体旁）。放置时记录先后顺序。
|
||
3. **质疑**：将卡牌反面朝上放置于另一名玩家的质疑区。不可质疑自己。
|
||
|
||
回合结束时，若玩家手牌仅剩最后一张，则该玩家暂时退出游戏。退出后不再参与回合轮转，其手牌被锁定（不再受到移动手牌类效果的影响），但仍可成为质疑目标。
|
||
|
||
### 5.3 效果失效与边界情况
|
||
效果系统需处理以下边界情况：
|
||
- 若效果的目标已不存在（如目标玩家已退出，或目标区域为空），则效果立即中止。
|
||
- 某些卡牌的效果需要持有者存活到特定时机才能生效；若持有者在效果生效前已退出，则效果自然失效。
|
||
- 暂时退出的玩家跳过需要其主动响应的效果（如新闻部传递手牌时跳过已退出者，将牌传给其左手边未退出的玩家）。
|
||
|
||
### 5.4 结算阶段
|
||
当所有玩家均暂时退出后，进入结算阶段，分为三个顺序执行的判定：
|
||
|
||
**调和判定**：翻开调和区所有卡牌，统计人力值总和。若总和达到或超过目标值，则调和成功；否则调和失败。
|
||
|
||
**质疑判定**：将每个玩家质疑区的卡牌全部改为正面朝上，分别计算各玩家质疑区的人力值合计。合计值最高的一名或多名玩家被视为犯罪嫌疑人而受到监禁。若所有玩家的合计值相同（包括全为零），则无人被监禁。人力值为负数的卡牌在质疑判定时视为零。
|
||
|
||
**胜利判定**：按照优先顺序由低到高（从第一优先到第五优先）依次检查每名玩家的最后一张手牌。若某优先顺序下有玩家满足其胜利条件，则这些玩家立即获胜，后续优先顺序不再检查。若同一优先顺序下有多名玩家满足条件，则他们共同获胜或共同失败。即使被监禁的玩家也可以参加胜利判定。
|
||
|
||
### 5.5 结局类型
|
||
- **正常胜利**：一至多名玩家满足胜利条件
|
||
- **全灭结局**：没有任何玩家满足胜利条件
|
||
- **混沌模式变体**：可在设置阶段开启。该模式下，玩家最后一张手牌也可以通过能力效果转移，但玩家仍然处于暂时退出状态。
|
||
|
||
---
|
||
|
||
## 6. 界面交互设计规范
|
||
|
||
### 6.1 主界面布局
|
||
界面采用横向宽屏布局，中央为公共区域，四周为玩家面板。
|
||
|
||
- **顶部**：房间信息、当前回合玩家指示、剩余时间倒计时、全局语音开关按钮
|
||
- **中央上方**：其他玩家的面板，以头像或名称标识，显示其手牌数量、已使用区、质疑区；头像旁显示语音状态指示灯
|
||
- **中央**：少女的尸体牌与调和区。调和区以横向排列的卡牌槽位展示，卡牌反面朝上时显示卡背，结算时依次翻开
|
||
- **底部**：当前玩家自己的手牌区，以扇形或横向排列展示，支持点击选中
|
||
- **底部操作栏**：选中卡牌后弹出行动按钮（特技、调和、质疑）。选择质疑后，其他玩家头像高亮，点击目标后确认
|
||
- **右下角**：游戏日志面板，滚动显示操作记录
|
||
- **左侧边栏（可选）**：房间内玩家列表与独立音量控制滑块
|
||
|
||
### 6.2 交互状态机
|
||
客户端界面需维护一个与服务器对应的本地交互状态：
|
||
- **空闲**：等待自己或他人的回合，禁止操作
|
||
- **选牌中**：自己的回合，可点击手牌，选中后弹出行动菜单
|
||
- **选目标中**：已选择质疑或需要指定目标的特技，等待点击目标玩家
|
||
- **等待响应**：自己的效果处理中，或等待其他玩家响应效果
|
||
- **选择响应中**：服务端要求自己选择卡牌或玩家作为效果响应
|
||
- **观看结算**：结算阶段，观看动画，禁止操作
|
||
|
||
### 6.3 信息提示与辅助
|
||
- 鼠标悬停在卡牌上时，显示该卡牌的详细说明（从配置读取）
|
||
- 调和区显示当前放置顺序编号
|
||
- 当效果需要玩家做出选择时，界面中央弹出模态对话框，附带倒计时条
|
||
- 超时未操作则自动执行默认行为或视为放弃（由服务端定义超时惩罚）
|
||
|
||
### 6.4 语音交互细节
|
||
- 发言者头像边框高亮或显示绿色脉冲环，直观指示当前谁在说话
|
||
- 玩家手动关闭麦克风时，头像旁显示静音图标
|
||
- 语音连接质量不佳时，显示弱网警告图标
|
||
- 提供全局静音按钮（仅关闭接收，不影响发送）用于专注思考
|
||
|
||
---
|
||
|
||
## 7. 关键机制实现要点
|
||
|
||
### 7.1 信息隔离的技术实现
|
||
信息隔离是防止作弊的核心。服务端在构建状态快照时，必须为每个玩家生成定制化的视图：
|
||
- 遍历所有卡牌，根据卡牌位置、朝向、以及当前接收快照的玩家身份，决定该卡牌在此快照中暴露哪些字段
|
||
- 卡牌内容字段（类型、人力值、优先顺序）仅在卡牌正面朝上且对该玩家可见时填充；否则留空或设为占位符
|
||
- 客户端渲染器根据卡牌内容是否存在，决定显示正面图像还是卡背图像
|
||
|
||
### 7.2 断线重连
|
||
玩家断线后，服务端保留其游戏状态一段时间。重连时，服务端向该玩家发送当前完整状态快照，客户端重建界面。若断线期间有需要该玩家响应的效果，应延长等待时间或为其选择默认选项。语音连接随游戏连接一并重建。
|
||
|
||
### 7.3 时序与并发
|
||
- 所有玩家操作必须带服务端时间戳排序
|
||
- 效果结算期间，房间应处于“结算中”状态，拒绝新的玩家操作（聊天与语音除外）
|
||
- 动画播放时间由客户端本地控制，但逻辑上服务端在发送事件后立即进入下一状态，不等待客户端动画完成。客户端通过队列缓冲事件，保证动画按顺序播放
|
||
|
||
### 7.4 配置热加载
|
||
卡牌库、设置规则、胜利条件等应存储于外部配置文件（如 JSON）。服务端启动时加载，游戏房间创建时复制一份配置快照，防止运行中修改配置影响已开局的房间。用户自行填写卡牌内容、人力值、优先顺序、张数、胜利条件、效果文本等字段，程序仅校验数据类型和逻辑一致性（如优先顺序范围、人力值范围）。
|
||
|
||
---
|
||
|
||
## 8. 开发阶段建议
|
||
|
||
### 第一阶段：网络与框架
|
||
实现 WebSocket 连接、房间管理、玩家加入离开、准备开始。客户端完成主界面布局与卡牌对象的基本显示。
|
||
|
||
### 第二阶段：核心循环
|
||
实现发牌、回合轮转、三种基础行动（特技/调和/质疑）、暂时退出机制。确保状态快照能正确同步，信息隔离生效。
|
||
|
||
### 第三阶段：效果系统
|
||
搭建效果处理器框架。逐个实现卡牌效果，重点处理需要多玩家响应的复杂效果（如手牌传递、交换、查看）。确保效果失效边界情况被覆盖。
|
||
|
||
### 第四阶段：语音集成
|
||
集成 WebRTC 或音频库，实现信令交换、P2P/SFU 媒体传输、语音状态指示器。先在等待房间中测试语音稳定性，再集成到游戏流程中。
|
||
|
||
### 第五阶段：结算与动画
|
||
实现三阶段结算流程。客户端配合完成卡牌翻转动画、结算结果展示。处理共同胜利、全灭结局等分支。
|
||
|
||
### 第六阶段： polish 与变体
|
||
添加混沌模式、音效、断线重连、观战模式、游戏日志导出。
|
||
|
||
---
|
||
|
||
## 9. 卡牌信息配置表
|
||
|
||
以下表格为游戏核心配置模板，请对照实体卡牌逐一填写。**程序启动时读取此表，运行时不再修改。**
|
||
|
||
### 9.1 基础卡牌属性表
|
||
|
||
| 序号 | 卡牌类型标识符（英文，程序内使用） | 中文名称 | 人力值 (MP) | 优先顺序 | 胜利条件简述 | 效果触发时机 | 效果描述（玩家可见文本） | 单卡张数 | 备注 |
|
||
| :--: | :--------------------------------- | :------- | :---------: | :------: | :--------------------- | :----------- | :----------------------------------------------------------- | :------: | :--- |
|
||
| 1 | honor_student | 优等生 | 2 | 4 | 调和成功即可获胜 | | 除你之外的所有玩家闭上眼睛，然后持犯人牌的玩家吐出舌头。等他们将舌头收回后所有玩家睁开眼睛。（一边发号施令一边进行游戏） | 3 | |
|
||
| 2 | health_committee_member | 保健委员 | 1 | 4 | 调和成功即可获胜 | | 你可以选择1张其他玩家已使用（正面朝上）的非保健委员的牌，将它加入自己的手牌中。 | 2 | |
|
||
| 3 | accomplice | 共犯 | 0 | 3 | 犯人获胜即可获胜 | | 将1张放在任意玩家面前质疑位置的牌转移到1名其他玩家面前。 | 1 | |
|
||
| 4 | library_committee_member | 图书委员 | 1 | 4 | 调和成功即可获胜 | | 你可以查看放在调和位置的所有卡牌。（※查看时注意不要改变卡牌的摆放顺序） | 3 | |
|
||
| 5 | alien | 外星人 | -1 | 1 | 被监禁即可获胜 | | 当你持有这张牌时，若有人使用了优等生的特技，你可以伸出舌头，装作是犯人来回应他。当你正面打出这张牌时，不会产生任何效果。 | 1 | |
|
||
| 6 | young_lady | 大小姐 | 1 | 4 | 调和成功即可获胜 | | 随机抽取1名其他玩家的1张手牌，然后选择1张自己的手牌保持反面朝上的状态返还给他。（你可以将抽到的那张返还给他） | 3 | |
|
||
| 7 | student_council_president | 学生会长 | 3 | 4 | 调和成功即可获胜 | | 持有者成为起始玩家（只需宣称持有即可）。正面打出时不会产生任何效果。 | 1 | |
|
||
| 8 | go_home_club | 归宅部 | 0 | 5 | 没有任何人获胜即可获胜 | | 你可以将1张自己的手牌和1张放在调和位置上的牌交换。 | 3 | |
|
||
| 9 | infected_person | 感染者 | 0 | 2 | 调和失败即可获胜 | | 在你的下一个回合开始时，若这张牌仍然正面朝上摆在你面前，则可以将调和位置的1张牌加入自己的手牌中。 | 1 | |
|
||
| 10 | newspaper_club | 新闻部 | 1 | 4 | 调和成功即可获胜 | | 每位玩家选择1张自己的手牌，将它保持反面朝上的状态传给自己左手边的玩家。 | 3 | |
|
||
| 11 | culprit | 犯人 | 0 | 3 | 不被监禁即可获胜 | | 这张牌无论是正面朝上还是反面朝上都无法被使用。（但可因其他卡牌的能力效果而进行移动） | 1 | |
|
||
| 12 | class_monitor | 班长 | 2 | 4 | 调和成功即可获胜 | | 选择1名玩家，双方各选择1张自己的手牌，然后保持反面朝上的状态转交给对方。(也可以选择一个人和自己换牌) | 2 | |
|
||
| 13 | discipline_committee_member | 风纪委员 | 1 | 4 | 调和成功即可获胜 | | 你可以查看一名玩家的所有手牌。 | 2 | |
|
||
| 14 | | | | | | | | | |
|
||
| 15 | | | | | | | | | |
|
||
|
||
> **字段说明**
|
||
>
|
||
> - **卡牌类型标识符**：程序代码中使用的枚举名或键名，建议英文驼峰命名，如 `StudentCouncilPresident`
|
||
> - **优先顺序**：胜利判定时的检查顺序，数字越小越早检查（1 最先，5 最后）
|
||
> - **效果触发时机**：可选值：`持有即生效` / `打出时触发` / `回合开始时触发` / `回合结束时触发` / `结算阶段触发`
|
||
> - **单卡张数**：该卡牌在完整牌库中的总张数
|
||
|
||
### 9.2 游戏设置规则表（按人数移除卡牌）
|
||
|
||
| 玩家人数 | 调和目标值 | 需移除的卡牌类型 | 本局总牌数 | 每人手牌数 |
|
||
| :------: | :--------: | :----------------------------------------------------------- | :--------: | :--------: |
|
||
| 3 | 9 | 图书委员×1、共犯×1、优等生×1、风纪委员×1、大小姐×1、新闻部×1、归宅部×1 | 18 | 6 |
|
||
| 4 | 8 | 图书委员×1 | 24 | 6 |
|
||
| 5 | 7 | 无（使用全部卡牌） | 25 | 5 |
|
||
| 6 | 6 | 图书委员×1 | 24 | 4 |
|
||
|
||
> **填写说明**
|
||
>
|
||
> - **调和目标值**：通常为 `12 - 玩家人数`，请确认实体规则
|
||
> - **需移除的卡牌类型标识符**：填写从完整牌库中移除的卡牌，多张请用逗号分隔
|
||
> - **每人手牌数**：总牌数 ÷ 人数，确认是否整除
|
||
|
||
### 9.3 特殊规则对照表
|
||
|
||
| 规则项 | 实体规则描述 | 程序实现要点 |
|
||
| :------------------------- | :----------------------------------------------------------- | :----------------------------------------------------------- |
|
||
| **起始玩家确定方式** | 持有"学生会长"的玩家成为起始玩家，只需宣称自己持有这张牌即可，并不需要第一张就打出 | 发牌完成后，服务端遍历所有玩家手牌，找到持有学生会长卡的玩家设为当前回合玩家。若该卡被移除（本局未加入牌库），则随机指定一名玩家为起始玩家。 |
|
||
| **犯人卡使用限制** | 这张牌无论是正面朝上还是反面朝上都无法被使用，但可因其他卡牌的能力效果而进行移动 | 行动验证阶段，若玩家选择犯人卡进行特技/调和/质疑，服务端直接拒绝并返回错误。犯人卡仅能通过班长交换、大小姐抽牌、新闻部传递、归宅部交换、共犯转移等被动方式移动。 |
|
||
| **感染者效果失效条件** | 若你在剩余手牌不到2张时使用这张牌，你无法活到下一个回合，效果自然失效 | 服务端允许玩家打出感染者，但在效果系统中标记：若打出后该玩家手牌数≤1（立即退出），则感染者效果标记为失效，下回合开始时不再触发选牌请求。 |
|
||
| **暂时退出后手牌锁定范围** | 手牌将被锁定，不再受到移动手牌的能力效果影响，但可以被质疑 | 退出玩家的手牌添加"locked"标记。效果系统处理移动手牌类效果（班长、大小姐、新闻部）时跳过这些卡牌。质疑操作不受影响，仍可正常被放置质疑牌。 |
|
||
| **质疑区MP合计为负时处理** | 质疑的合计值不会是负数。若合计值是-1，则将它当作0 | 结算阶段计算质疑区MP总和时，对每张卡牌取 `max(0, mp)`。外星人MP=-1，在质疑区贡献0点。 |
|
||
| **归宅部与犯人联动规则** | 归宅部可以将1张手牌和1张调和位置的牌交换。若犯人通过归宅部效果进入调和区，则可能出现"其实根本就没有犯人"的结局 | 允许交换。若犯人牌被换入调和区，调和判定阶段统计MP时犯人牌贡献0点（与实际MP一致）。归宅部持有者手牌中不再持有犯人。 |
|
||
| **混沌模式与基础模式差异** | 混沌模式中，玩家的最后一张手牌也可以用能力进行转移，但玩家仍然处于暂时退出的状态 | 开启混沌模式后，效果系统处理移动手牌效果时，不跳过仅剩1张手牌的玩家（允许其手牌被交换、传递、抽走）。但该玩家仍标记为已退出，不再参与回合轮转。 |
|
||
| **全灭结局触发条件** | 没有任何人能获得胜利而结束游戏的情况 | 胜利判定阶段按优先顺序1→5依次检查，若所有优先顺序下均无人满足胜利条件，则广播全灭结局。 |
|
||
|
||
### 9.4 卡牌效果详细规格表（供程序逻辑参考）
|
||
|
||
| 卡牌名称 | 是否需要选择目标 | 目标类型 | 是否影响他人手牌 | 是否影响调和区 | 是否影响质疑区 | 效果失效条件 | 响应超时处理 |
|
||
| :----------- | :----------------- | :----------------------------------------------------------- | :----------------------: | :----------------------: | :------------: | :----------------------------------------------------------- | :----------------------------------------------------------- |
|
||
| **学生会长** | 否 | 无 | 否 | 否 | 否 | 无（持有即生效，打出不产生效果） | 无 |
|
||
| **班长** | 是 | 先选择1名玩家，再双方各选1张自己的手牌 | 是 | 否 | 否 | 目标玩家已退出；目标玩家手牌为空 | 超时自动随机选择1张手牌完成交换 |
|
||
| **优等生** | 否（自动触发） | 无（向所有其他玩家发送闭眼指令，向持犯人牌玩家发送提示，向外星人持有者发送是否回应提示） | 否 | 否 | 否 | 其他玩家全部已退出；场上无犯人牌 | 犯人玩家超时未确认吐舌头视为不回应；外星人持有者超时未确认视为不装作犯人 |
|
||
| **风纪委员** | 是 | 选择1名玩家 | 否（仅查看，不移动） | 否 | 否 | 目标玩家已退出；目标玩家手牌为空 | 无（纯信息展示，无需超时处理） |
|
||
| **大小姐** | 是 | 系统随机选择1名其他玩家并随机抽其1张手牌，然后自己选择1张手牌返还 | 是 | 否 | 否 | 无其他玩家；被抽牌玩家手牌为空 | 超时自动将抽到的牌原路返还，或随机选择1张自己的手牌返还 |
|
||
| **新闻部** | 否（但需全员响应） | 每位未退出玩家选择自己的1张手牌 | 是 | 否 | 否 | 无 | 每位玩家超时自动随机选择1张手牌传递；已退出玩家自动跳过 |
|
||
| **归宅部** | 是 | 选择自己的1张手牌 + 选择调和区1张牌 | 否 | 是 | 否 | 调和区无卡牌；自己手牌为空 | 超时自动取消效果 |
|
||
| **图书委员** | 否 | 无 | 否 | 否（仅查看，不改变顺序） | 否 | 调和区无卡牌 | 无（纯信息展示） |
|
||
| **保健委员** | 是 | 选择其他玩家已使用区（SkillZone）中的1张非保健委员牌 | 是（从已使用区移入手牌） | 否 | 否 | 所有玩家已使用区为空；或仅有保健委员 | 超时自动随机选择1张符合条件的牌，若无则取消效果 |
|
||
| **外星人** | 否（被动触发） | 无 | 否 | 否 | 否 | 无人使用优等生特技；正面打出时无效果 | 收到优等生触发通知后，超时未响应视为不装作犯人 |
|
||
| **感染者** | 是（延迟触发） | 下回合开始时选择调和区1张牌 | 否 | 是 | 否 | 打出后手牌≤2（立即退出，无法活到下回合）；下回合开始时此牌不在已使用区；调和区无卡牌 | 超时自动随机选择1张调和区卡牌加入手牌，或放弃效果 |
|
||
| **犯人** | N/A | N/A | N/A | N/A | N/A | 无法主动使用 | N/A |
|
||
| **共犯** | 是 | 先选择任意质疑区1张牌，再选择1名其他玩家 | 否 | 否 | 是 | 全房间质疑区无卡牌 | 超时自动随机选择1张质疑区卡牌和1名随机其他玩家完成转移 |
|
||
|
||
> **字段说明**
|
||
> - **目标类型**：该效果是否需要玩家选择目标，以及目标的类型
|
||
> - **是否影响他人手牌**：效果是否会导致其他玩家的手牌数量或内容发生变化
|
||
> - **响应超时处理**：若需要其他玩家响应（如新闻部选牌），超时后如何处理（自动随机选择 / 跳过该玩家 / 效果取消）
|
||
|
||
---
|
||
|
||
> **文档说明**：本文档为框架性指导，所有涉及具体卡牌属性（人力值、优先顺序、效果描述、卡牌张数、移除规则）的字段均留空，由开发者根据实体卡牌自行填入配置文件。文档不涉及具体代码实现与项目目录结构。 |