NBA 篮球杀
一个篮球主题身份卡牌游戏原型。规则参考三国杀的身份局、回合制、手牌、距离、响应链、判定和濒死救援结构，但角色、牌名、技能、音效和场面反馈都改成篮球语境。
当前版本已经包含完整单机 AI 局、4-8 人身份配置、局域网房间、三套人物形象、三档 AI 难度、三档 AI 出牌节奏、五套球场背景、两套增强音效、聊天快捷语、球星专属金色发言、倒计时、手动弃牌、拖拽排序和移动端/iPad 适配。
非官方球迷作品，仅用于学习和原型演示。项目不隶属于 NBA、球队或球员本人。
快速开始
需要 Node.js。推荐直接用内置服务器启动，这样局域网房间和音频资源都能正常工作：
npm start
启动后终端会输出类似：
NBA Basketball Kill: http://127.0.0.1:4173/
LAN: http://192.168.x.x:4173/
本机打开 127.0.0.1 地址；同一 Wi-Fi 下的 iPad、手机或其他电脑打开 LAN 地址即可加入局域网房间。
基础检查：
npm run check
GitHub Pages
仓库包含 GitHub Actions 工作流，会在 main 分支推送后自动部署静态版：
https://11010tianyi.github.io/nba-basketball-kill/
Pages 静态版适合体验单机 AI 局、规则、角色、卡牌和界面适配。局域网房间依赖 server.mjs 的 WebSocket 服务，仍需在本机运行 npm start 后通过终端输出的 LAN 地址访问。
Android 安装包
项目用 Capacitor 把现有静态页面包进 Android WebView，没有额外的打包器。capacitor.config.json 的 webDir 是 www/：npm run mobile:web 会把 index.html、app.js、styles.css 和 assets/ 复制进去，并带上卡牌背景清单。页面里的相对路径保持不变，所以单机 AI、本地音效和卡牌图在安装包里都能离线打开，不依赖 GitHub Pages，也不需要 npm start。
- 应用名：
篮球杀
- 包名：
com.tianyi.nbabasketballkill
- 类型：debug APK，不是上架用的正式签名
安装包里的开局页只保留单机 AI。局域网房间仍然留在网页和 npm start 里；安装包没有内置房间服务器，如果还显示创建/加入房间，点下去只会失败。真人现场照片仍会向 Wikimedia 要图，离线时会回退到拟人卡，不影响开局。
可安装的 debug APK 会发到 GitHub Releases，文件名是 nba-basketball-kill-vX.Y.Z-debug.apk（第一次是 nba-basketball-kill-v1.0.0-debug.apk）：
https://github.com/11010tianyi/nba-basketball-kill/releases
Build Android debug APK workflow 在 main 上改到游戏或 Android 配置时自动构建，也可以手动 workflow_dispatch。它用 GITHUB_TOKEN 建一个新的 Release，这是长期下载地址。同一次构建还会上传名为 nba-basketball-kill-debug-apk 的 Actions artifact，那份文件大约 90 天后过期。只改文档不会触发这个 workflow，GitHub Pages 的部署也不受影响。
版本标签在 assembleDebug 之前根据已有 git tag 计算，并写入 APK 的 versionName / versionCode。workflow 不会把版本号提交回仓库：
- 还没有任何
vMAJOR.MINOR.PATCH tag 时，第一次发布是 v1.0.0。package.json 的版本号不参与计算。
- 之后每次成功构建都在最高的 semver tag 上把 patch 加一，例如
v1.0.3。versionName 是去掉 v 的标签，versionCode 是 major * 1000000 + minor * 1000 + patch。
- 发布时使用构建前算出的同一个 tag。如果这个 tag 或同名 Release 已经存在，任务失败，不会改发另一个版本号。
签名用仓库 secret ANDROID_DEBUG_KEYSTORE_BASE64。workflow 在 assembleDebug 之前把它解码到 runner 的 $HOME/.android/debug.keystore，Gradle 按 keytool 读到的密钥库类型显式使用这个文件和别名 androiddebugkey。AGP 默认会在自己的偏好目录里找 debug 密钥；只要 XDG_CONFIG_HOME 指向别的已存在目录，它就会另造一把钥匙，已安装的包就会报签名不一致。构建前会记下证书 SHA-256，并把密钥库改成不可写。构建后如果 APK 的 v2 证书 SHA-256 和这个指纹不同，或者密钥库在构建过程中被换掉，任务失败，不会发布。secret 缺失、为空、不是合法 base64，或不是 Android 默认 debug 密钥时，任务也会直接失败。仓库里不要提交 keystore 或密码。手机上如果还装着这次修复之前的安装包，需要先卸载一次；之后的版本可以覆盖安装。
本机打包
需要 JDK 21 和 Android SDK 36。本机如果还没有 ~/.android/debug.keystore，Gradle 会为这次本机构建生成一把，它只留在你的用户目录里，不要提交。CI 不会这样做。
npm install
npm run android:apk
APK 输出位置：
android/app/build/outputs/apk/debug/app-debug.apk
只同步 Web 资源、不打包时：
npm run android:sync
当前内容
- 球星角色：20 名，包括现役、历史级和中国球员
- 卡牌种类：18 种
- 牌堆总数：152 张
- 人数配置：4-8 人身份局
- 游戏模式：单机 AI 局、局域网房间
- 形象模式：拟人球星卡、经典简洁形象、真人现场照片
- AI 设置：新秀、轮换主力、名人堂三档难度；解说、快速、极速三档节奏
- 球场背景：NBA 木地板、复古主场、水泥外场、橡胶训练场、林式涂鸦街球
- 音效模式：球场现场 MP3、街机合成音效，覆盖穿鞋、冠军戒指、护臂、离场、聊天等事件
- 聊天系统：打字、表情快捷语、NBA 球迷文化快捷语、每名球星专属金色发言
- 卡牌视觉：不同功能牌有不同篮球图形背景；支持
assets/cards/*/ 自定义卡牌背景包
- 操作体验：响应链倒计时、弃牌倒计时、无牌可出快速结束、拖拽排序、一键排序、原因提示、新手规则帮助
- 适配：桌面、iPad 横竖屏、手机布局
截图
球星池
现役与近现代球星：
- 勒布朗、库里、约基奇、字母哥、东契奇、亚历山大、塔图姆、爱德华兹、文班亚马、布伦森
历史级与中国球员：
- 姚明、乔丹、科比、奥尼尔、艾弗森、邓肯、纳什、易建联、王治郅、郭艾伦
每名球员有体能、位置、标签和专属技能。技能已接入结算，例如库里的三分牵制、姚明的盖帽摸牌、科比的额外进攻、奥尼尔/字母哥的强攻双响应、邓肯的减伤、易建联的三分距离和罚球收益等。
身份与胜利
玩家身份：
- 核心：公开身份，核心离场通常会导致核心阵营失败
- 队友：隐藏身份，保护核心并协助清除威胁
- 挑战者：隐藏身份，目标是淘汰核心
- 独狼：隐藏身份，目标是成为最后存活者
人数配置会随 4-8 人自动调整挑战者、队友和独狼数量。每局开局会随机分配身份，玩家不一定总是核心；核心身份公开，其他身份只对自己可见。核心阵营清除全部挑战者和独狼后获胜；挑战者让核心离场后获胜；独狼需要在残局中单独取胜。
奖惩：
- 淘汰挑战者：击杀者摸 3 张
- 核心误伤队友：核心清空手牌和装备
回合流程
- 自动开球：哨声后中圈跳球，随机一名存活玩家获得球权并成为本局首攻
- 准备阶段：刷新本回合技能状态
- 摸牌阶段：摸 2 张
- 出牌阶段：使用进攻牌、战术牌、治疗牌、装备牌
- 响应链：进攻或部分战术牌会要求目标响应
- 弃牌阶段：手牌数超过当前体能时手动弃牌，战术板可让上限 +1
- 结束阶段：轮到下一名存活玩家
终场后会弹出比赛结果，可以返回首页、按当前设置重开，或随机人数和球星重新开局。
如果同一批人连续多轮都没有人离场（场上只剩两人时再过一轮，人更多时再过六轮），比赛进入绝杀时间：护臂和邓肯的减伤失效，暂停和冠军戒指也不能再阻止离场。这样残局不会被减伤和续命牌拖住。
距离系统
距离按场上存活玩家的座位最短距离计算。
- 突破：基础攻击距离 1
- 三分：基础攻击距离 3
- 球鞋：进攻距离 +1
- 护臂：被指定时防守距离 +1
- 挡拆：本回合下一次进攻距离视为无限
- 部分球星技能会调整距离，例如库里、易建联、郭艾伦、塔图姆
目标不在距离内时无法被选择，界面会提示距离原因；AI 出牌同样遵守距离。
响应链
进攻响应：
- 突破 / 三分指定目标后，目标可以打出防守或盖帽
- 字母哥、奥尼尔的近筐强攻需要 2 张响应
- 文班亚马每轮第一次受到进攻会自动防守
战术响应：
- 抢断、包夹、战术犯规等敌对战术牌可以被盖帽或教练挑战抵消
- 玩家受到指定时底部出现响应面板，按钮内显示倒计时
- AI 或无牌可响应的玩家会快速跳过，避免无效等待
AI 难度与节奏
AI 现在分为“节奏”和“难度”两套设置。
节奏：
- 解说节奏：默认模式，AI 每次出牌之间会停顿，并在战术日志里说明决策意图
- 快速节奏：接近原先版本，适合熟悉规则后快速推进
- 极速跳过：保留最早的高速版本，AI 几乎连续结算
难度：
- 新秀：偏随机，会做基础回血、装备和近距离进攻
- 轮换主力：按身份阵营选择目标，队友保护核心，挑战者压核心，独狼削弱强势角色
- 名人堂：更重视胜负目标、低体能集火、拆牌、包夹、战术犯规和队友支援
当前 AI 能读到规则层面的身份与角色定位，用于模拟三国杀式身份局的站队与背刺压力。它还不是完整推理 AI，下一步可以加入“AI 意图图标”和更细的身份怀疑值。
判定系统
部分牌会翻开牌堆顶一张作为判定牌。
已接入判定：
- 罚球：红色回复 1 点体能，黑色摸 1 张
- 易建联使用罚球判定为红色时额外摸 1 张
卡牌列表
基础 / 进攻：
- 突破：距离内目标需防守，否则失去 1 点体能
- 三分：远距离进攻，被防守后使用者摸 1 张
- 防守：响应突破或三分
- 暂停：回复 1 点体能。濒死时优先自己使用；同阵营才会自动用来救援，不会抢走对手的暂停
- 罚球：进行红黑判定
战术：
- 助攻：令一名角色摸 2 张
- 抢断：弃置目标 1 张手牌或装备
- 盖帽：响应进攻或战术
- 教练挑战：响应并抵消战术牌
- 快攻：连续冲击两个目标
- 包夹：目标弃 2 张，不足则失去体能
- 挡拆：下一次进攻距离无限
- 战术犯规：令目标本回合不能使用进攻牌
- 更衣室鼓舞：你和一名角色各摸 1 张
装备：
- 球鞋：进攻距离 +1
- 护臂：每轮第一次受伤 -1，并提供防守距离
- 战术板：手牌上限 +1
- 冠军戒指：濒死时自动回复 1 点并弃置
局域网房间
房间流程：
- 房主选择人数、球星和“局域网房间”，点击“创建房间”，把房间码发给其他玩家。
- 其他玩家输入房间码加入后，右下角按钮会变成“准备”；选好自己的球星后点击“准备”。
- 房主右下角始终是“开球”。所有已加入玩家准备后，房主点击“开球”进入同一局。
- 房主浏览器作为规则结算端，负责 AI、发牌、倒计时、响应链和状态同步。
- 其他玩家操作自己的手牌，动作会发送给房主结算并同步回全房间。
联机规则：
- 已开球的房间不允许新玩家中途加入。
- 同一浏览器重复加入同一房间不会重复占人数。
- 每个玩家本机视角都会把自己的角色放在球场下方。
- 局域网联机依赖房主页面保持在线，房主关闭页面会影响本局同步。
形象与音效
形象模式：
portrait：拟人卡通球星卡，默认模式classic：保留早期简洁球衣形象photo：真人现场照片模式，使用 Wikimedia Commons 的公开图片链接；加载失败会自动回退到拟人卡
指定形象：
http://127.0.0.1:4173/?avatar=portrait
http://127.0.0.1:4173/?avatar=classic
http://127.0.0.1:4173/?avatar=photo
音效：
- “球场现场”：本地 MP3 真实音频片段
- “街机合成”：Web Audio 合成音效
球场现场音效来自 UnstuntedSFX 免费 royalty-free 声音库，包括 Basketball Swish、Basketball Bounce、Whistle、Crowd Cheer 和 Crowd Applause。许可说明见 https://unstuntedsfx.net/license
新增音效事件：
- 穿鞋、护臂、战术板、冠军戒指装备
- 冠军戒指触发救命
- 离场 / 终场
- 教练挑战、罚球、聊天、球星专属发言
两套音效都覆盖这些事件：街机模式用 Web Audio 合成，现场模式用本地真实片段组合。
This is the beginning of the README. Read the rest at the original. Read the full README ↗
