Red Packet Rush 是一个固定四人参加的中文纸牌对战原型：玩家在大厅发现房间，在等待房间配置一副或两副牌，随后进行点数抢先、三牌出牌、暗抢、获牌弃牌和最终结算。Colyseus 服务端是唯一规则权威，Godot 客户端只呈现公开状态并提交意图。牌桌使用 CC0 传统扑克牌面，并在玩家席位区域依次公示出牌、抢牌所得和弃牌。
运行前请先读：本交付已验证 Windows x86_64 desktop 和 Android arm64 调试包。需要 Node.js 22+、Godot 4.7.1 stable（64 位、单精度）和仓库内锁定的 Colyseus Native SDK
godot-v0.17.11。项目使用 GDScript，不要求 Mono；不要用 Godot 双精度构建，也不要用未锁定的 SDKmain。
当前 QA 使用 Godot 4.7.1.stable.mono.official.a13da4feb console 可执行文件通过；Mono 只是已验证的引擎发行版，不是项目运行时依赖。
在仓库根目录打开 PowerShell：
cd C:\path\to\RedPacketRush
npm --prefix .\server ci
.\scripts\verify.ps1 -GodotPath "C:\path\to\Godot_v4.7.1-stable_win64_console.exe" -SkipInstallverify.ps1 会检查已跟踪文件没有依赖目录、编辑器缓存、日志或秘密文件，然后运行服务端测试、TypeScript 构建、Godot editor parse、全部 client/tests/run_*_tests.gd headless runner 和交付截图矩阵定义校验。省略 -SkipInstall 时，脚本会先执行 npm ci；只在已按锁文件安装依赖时使用 -SkipInstall。失败会立即停止并返回非零退出码。
启动服务端：
Push-Location .\server
npm start
Pop-Location默认地址是 http://127.0.0.1:2567，WebSocket 地址是 ws://127.0.0.1:2567。需要换端口时，在启动前设置 $env:PORT；客户端大厅的服务器地址输入框也要改成同一端口。
另开一个终端启动客户端：
$godot = "C:\path\to\Godot_v4.7.1-stable_win64_console.exe"
& $godot --path .\client也可以把 Godot 路径放在 GODOT_PATH（GODOT4 仍兼容）后只传开关：
$env:GODOT_PATH = "C:\path\to\Godot_v4.7.1-stable_win64_console.exe"
.\scripts\verify.ps1 -SkipInstall -LiveSmoke先在 Godot 4.7.1 的编辑器设置中配置 Android SDK、JDK 21 和调试 keystore，并安装与编辑器匹配的同版本官方导出模板；Mono 编辑器应使用 Godot_v4.7.1-stable_mono_export_templates.tpz。随后在仓库根目录运行：
$godot = "C:\path\to\Godot_v4.7.1-stable_win64_console.exe"
New-Item -ItemType Directory -Force .\build\android | Out-Null
$apk = Join-Path (Resolve-Path .\build\android).Path "RedPacketRush-debug.apk"
& $godot --headless --path .\client --export-debug Android $apk预设只导出 arm64-v8a，使用本机 Godot 调试签名，产物位于 build/android/RedPacketRush-debug.apk。真机访问电脑上的服务端时，大厅地址不能使用 127.0.0.1；请填写电脑的局域网地址，例如 ws://192.168.1.10:2567，并确保 Windows 防火墙允许该端口。
Windows 预设导出 x86_64 发布版，并将 PCK 嵌入可执行文件。在仓库根目录运行：
$godot = "C:\path\to\Godot_v4.7.1-stable_win64_console.exe"
New-Item -ItemType Directory -Force .\build\windows | Out-Null
$exe = Join-Path (Resolve-Path .\build\windows).Path "RedPacketRush.exe"
& $godot --headless --path .\client --export-release Windows $exe
Compress-Archive -Force .\build\windows\* .\build\RedPacketRush-windows-x86_64.zip分发时应使用 ZIP，确保 RedPacketRush.exe 与 Colyseus 原生 DLL 一起交付。
完整检查：
.\scripts\verify.ps1 -GodotPath "C:\path\to\Godot_v4.7.1-stable_win64_console.exe"Native SDK 四客户端 smoke：
.\scripts\verify.ps1 -GodotPath "C:\path\to\Godot_v4.7.1-stable_win64_console.exe" -LiveSmoke-LiveSmoke 调用 client/tests/run_live_lobby_smoke.ps1。该辅助脚本会自动分配空闲端口、启动临时 Colyseus 进程、验证大厅匹配/加入、四席准备、一个私有手牌、一个玩家意图和一个公开状态更新，最后清理进程；不需要另开服务端。若直接运行 .gd smoke runner，则必须先执行 npm --prefix .\server start 并传入 --endpoint=ws://127.0.0.1:2567。
可选的干净检出证明：
$env:GODOT_PATH = "C:\path\to\Godot_v4.7.1-stable_win64_console.exe"
.\scripts\verify.ps1 -CleanCheckout-CleanCheckout 要求当前工作树无改动，然后用 git clone --no-local 将当前 HEAD 克隆到系统临时目录。它在克隆中执行 npm ci、全部测试/构建、四客户端 smoke 和前后两次干净状态检查，完成后删除临时克隆。
服务端依赖只从 server/package-lock.json 安装：
npm --prefix .\server ci客户端已提交官方 Native SDK godot-v0.17.11 的 Windows x86_64 与 Android arm64 debug/release 二进制。来源、压缩包 SHA-256 和重装命令见 client/addons/colyseus/UPSTREAM.md。重装后应核对哈希 334ea298f80af77089549c06dda89dfcbd98a33d7177a4a8bee9b8e7dacd9b7c，再运行验证脚本。
服务器保持四个参与者、五张手牌、牌型计分和秘密抢牌的完整状态机。房主在等待房间选择 one 或 two 副牌，以及 15/30/60 秒行动期限；空席可由机器人填充。牌局开始后，房间从大厅移除。断线的人有 30 秒重连窗口，超时后由机器人接管。
| 阶段 | 客户端可见内容 |
|---|---|
| 大厅 | 连接状态、可加入房间和创建入口 |
| 等待房间 | 四个席位、准备状态、房主设置和机器人填充 |
| 牌局 | 点数抢先、当前行动者、牌堆/分数/事件、排序后的五张真实牌面、提示与出牌得分；出牌后公示三秒再开放抢牌 |
| 抢牌与弃牌 | 私有选择确认、四秒同步揭晓、席位前蓝框显示抢牌所得；获牌者可弃任意一张牌，全部弃完后公示两秒 |
| 最终结算 | 五张中自动选择的最高分三牌组合、排名、并列胜者和返回大厅入口 |
本项目不包含账号、持久化、密码房、好友/聊天、观战、晚加入、Android 正式签名、主机/Web 正式导出、可验证生产随机数或生产级反作弊。Playground 和 Monitor 只为本地开发开放；部署时应关闭它们、启用认证与 TLS，并重新评估 Native SDK beta 的平台兼容性。
服务端的详细命令、房间设置和目录边界见 server/README.md；扑克牌素材来源与 CC0 授权见 client/assets/cards/ATTRIBUTION.md；规则词汇和设计取舍见 CONTEXT.md、docs/adr/0001-use-colyseus-native-sdk-with-gdscript.md 和 docs/research/godot-colyseus-integration.md。