UnoGame
基于 Kotlin + Jetpack Compose 的 UNO 卡牌游戏,支持单机 AI 对战和局域网多人联机。
功能特性
- 4 种游戏模式:标准 UNO、UNO Flip(双面牌映射)、No Mercy(无情模式)、7-0
- 本地 AI 对战:3 档 AI 难度(简单/普通/困难),支持 2~8 人对局,可存档 / 继续游戏
- 局域网联机:TCP 长度前缀帧协议 + 主机权威架构,断线玩家 AI 接管
- 联机房间配置:可选模式、总人数 2~8、AI 难度、手牌上限、机器人名字
- 联机排行榜:独立于本地积分榜,对局结束自动记录
- 7 套卡面主题 + 7 套桌面背景,支持浅色/深色自适应
- 出牌记录浮窗:卡牌颜色高亮、角色名主题色,暗色桌面自动适配
- 罚牌叠加:+2/+4/+5/+6/+10 同色或万能牌连锁累积
- 全员一循环后强制出牌:解决手牌上限过少等死局问题
- 积分排行榜:按模式筛选,支持 JSON 导入/导出/剪贴板
开发环境
| 工具 |
版本要求 |
| Java JDK |
17+ |
| Android SDK |
API 34+(compileSdk = 34,minSdk = 24) |
Android SDK 随 Android Studio 安装即可。local.properties 由 IDE 打开项目时自动生成,无需手动创建。
| Gradle | 8.5(wrapper 已包含在仓库中,无需手动安装) |
| Kotlin | 1.9.x(Compose 编译器扩展 1.5.5) |
Linux
# 安装 JDK 17(Fedora)
sudo dnf install java-17-openjdk-devel
# 安装 JDK 17(Ubuntu/Debian)
sudo apt install openjdk-17-jdk
# 构建
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk # 根据实际路径调整
./gradlew assembleDebug
macOS
# 安装 JDK 17
brew install openjdk@17
# 构建
export JAVA_HOME="$(brew --prefix openjdk@17)"
./gradlew assembleDebug
Windows
:: 安装 JDK 17(从 https://adoptium.net 下载安装)
:: 安装 Android Studio(含 SDK)
:: 构建
set JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-17.0.0.0-hotspot\
gradlew.bat assembleDebug
提示:项目已包含 gradlew(Linux/macOS)和 gradlew.bat(Windows),无需全局安装 Gradle。首次构建会自动下载 Gradle 8.5 及所有依赖。
构建命令
# Debug APK(开发/测试用)
./gradlew assembleDebug # Linux/macOS
gradlew.bat assembleDebug # Windows
# Release APK(发布用,需要签名配置)
./gradlew assembleRelease
# 清理构建缓存
./gradlew clean
# 安装到已连接的设备
adb install app/build/outputs/apk/debug/app-debug.apk
APK 输出路径:app/build/outputs/apk/
Release 签名
在项目根目录创建 keystore.properties(已在 .gitignore 中排除):
storeFile=app/uno-release.keystore
storePassword=<密码>
keyAlias=<别名>
keyPassword=<密码>
如果该文件不存在,release 构建会回退使用默认 debug keystore(仅供测试)。
密钥库备份位于 keystorebak/ 目录(同样在 .gitignore 中,不会提交到 Git)。
项目结构
UnoGame/
├── app/
│ ├── build.gradle.kts # 应用构建配置(签名、依赖、ProGuard)
│ ├── src/main/
│ │ ├── AndroidManifest.xml
│ │ └── java/com/unogame/
│ │ ├── MainActivity.kt # 入口 Activity + 顶层导航 + 网络生命周期
│ │ ├── model/ # 数据模型
│ │ ├── game/ # 游戏引擎 & AI
│ │ ├── network/ # 局域网联机
│ │ └── ui/ # Compose UI
│ └── uno-release.keystore # 发布签名密钥库(已在 .gitignore)
├── gradle/wrapper/ # Gradle Wrapper(已提交)
├── gradlew / gradlew.bat # Wrapper 启动脚本
├── keystorebak/ # 密钥库备份(已在 .gitignore)
└── keystore.properties # 签名配置(已在 .gitignore)
核心模块
model/ — 数据模型
| 文件 |
职责 |
Card.kt |
卡牌定义:CardColor(红/蓝/绿/黄 + Flip 暗面)、CardType(数字/跳过/反转/+2/万能/+4/Flip/+5/+6/+10 等 15 种类型)、匹配与计分逻辑 |
GameState.kt |
对局状态快照:玩家列表、当前回合、方向、弃牌堆、摸牌堆、万能色、Flip 状态、回合数、日志消息 |
Player.kt |
玩家数据:ID、名称、手牌、房主标志、连接状态、UNO 叫牌状态、剩余牌数 |
game/ — 游戏引擎 & AI
| 文件 |
职责 |
GameEngine.kt |
核心引擎。构建 4 种模式的牌堆(标准 108 张、Flip 双面、No Mercy 含超级罚牌、7-0),实现 playCard()(含叠加罚牌、翻转、7-0 传递/交换机制、胜利判定)、drawCard()(罚牌累积 + 手牌上限)、finishSwap()、skipAfterDraw()、challengeUno()、Fisher-Yates 洗牌、restoreFromSave() 存档恢复 |
GameRules.kt |
规则定义:GameMode 枚举(NORMAL / FLIP / NO_MERCY / SEVEN_ZERO)、初始手牌数、叠加开关、手牌上限。每种模式记住各自的 AI 难度和总玩家数 |
SimpleAI.kt |
AI 机器人:AIDifficulty(Easy/Normal/Hard 带持久化记忆)。Easy 有 30% 随机抽牌行为;Normal/Hard 按惩罚牌优先级选最优出牌;30% 概率挑战未喊 UNO 的玩家 |
GameSaver.kt |
存档系统:SaveData 模型 + Gson 序列化到 SharedPreferences。保存/加载/删除存档,支持牌堆、手牌、日志、计时等全状态恢复 |
network/ — 局域网联机
| 文件 |
职责 |
TcpFramer.kt |
TCP 帧协议:4 字节大端长度前缀 + JSON 消息体,彻底解决粘包/半包 |
Messages.kt |
协议定义:消息类型常量、GameMessage/NetworkEvent/PlayerAction、ProtocolHelper 模型转换 |
GameNetwork.kt |
抽象接口:GameNetwork + LanGameNetwork,预留远程联机扩展点 |
LanHost.kt |
TCP 服务端:主机权威运行 GameEngine,公有/私有状态分离防作弊,断线玩家 AI 机器人接管,房主退出广播游戏结束 |
LanClient.kt |
TCP 客户端:soTimeout=0 + tcpNoDelay + keepAlive 防止空闲断连,事件流驱动 UI 更新 |
LanDiscovery.kt |
UDP 广播房间发现(辅助,手动 IP 输入为主方案) |
LanNetwork.kt |
统一入口:整合 Host + Client + Discovery,房主 127.0.0.1 回环连接走相同消息流 |
ui/ — Compose 界面
ui/screens/ — 页面
| 文件 |
职责 |
MainMenuScreen.kt |
主菜单:本地模式 / 在线模式 / 积分榜 / 规则说明 / 设置 |
ModeSelectScreen.kt |
模式选择:展示 4 张模式卡牌(含说明和图标) |
LocalSetupScreen.kt |
本机配置:玩家名(含预设下拉)、人/机器人数量(2~8)、AI 难度、手牌上限滑动条、参与者预览 |
LocalGameScreen.kt |
单机对局:管理 GameEngine,处理出牌/摸牌/万能色/UNO叫牌/挑战/7-0交换,AI 自动出牌(1.2 秒间隔),"摸后即出"弹窗,对局日志弹窗(彩色高亮),退出确认,胜局自动存积分,存档/读档 |
LobbyMenuScreen.kt |
联机入口:创建房间 / 加入房间 / 联机排行 |
LobbyScreen.kt |
房间大厅:房主视角(显示本机 IP + 玩家列表 + 开始游戏按钮)、加入者视角(发现列表 + 刷新 + 手动输入 IP 连接) |
OnlineSetupScreen.kt |
联机房间设置:游戏模式选择、总玩家数 2~8、AI 难度三色、手牌上限滑动条、机器人名字下拉选择(参与者预览) |
GameScreen.kt |
通用对局界面(单机 & 联机共用):消息栏 / 方向指示 / Flip 状态 / 摸牌堆计数 / 对手头像行 / 弃牌堆 + 摸牌堆 / 罚牌警示 / 手牌区(水平滚动 + 高度可调) / 万能色选择 / UNO 按钮 / 挑战按钮 / 保存按钮 |
GameOverScreen.kt |
结算页:胜者名、奖杯图标、得分、难度/时长/人数/回合数据,联机模式显示"返回主菜单",本地模式"再来一局" |
ScoreboardScreen.kt |
积分榜:按模式筛选排行、金/银/铜高亮、点击查看详情(对手名 + 各自得分 + 出牌记录回放)、导出/导入 JSON / 剪贴板粘贴导入 |
RulesHelpScreen.kt |
规则说明:4 种模式详规 + 通用规则(叫 UNO、计分、AI 难度),可折叠卡片 |
SettingsScreen.kt |
设置:昵称、卡面主题(7 种实时预览)、桌面背景(7 种)、屏幕方向、手牌偏移高度、关于弹窗 |
ui/components/ — 可复用组件
| 文件 |
职责 |
CardView.kt |
卡牌渲染:7 套主题样式、Flip 双面自动切换、选中浮起、长按详情弹窗(跟随手牌偏移)、牌背图 |
PlayerHand.kt |
手牌区:水平滚动、Flip 面正确匹配可出牌判定、可出绿色/不可出红色染色 |
PlayerAvatar.kt |
玩家头像卡:机器人专属图标+颜色 / 人类金色图标、bot_前缀/AI后缀识别、UNO 提示、方向箭头、金框高亮 |
ColorPickerDialog.kt |
万能色选择:4 个颜色圆(普通模式红蓝绿黄 / Flip 暗面粉紫青橙)+ 中文颜色名 |
BotAvatarIcons.kt |
19 个预设机器人名 → Material 图标 + 专属色映射,AI 接管后缀 (AI) 自动剥离匹配 |
GameLogDialog.kt |
共享出牌记录弹窗(本地 & 联机共用):米白/暗色桌面自适应、卡牌色底高亮、角色名主题色、滚动箭头 |
ui/theme/ — 主题系统
| 文件 |
职责 |
Theme.kt |
Compose 主题入口:LocalCardTheme、LocalTableBg、LocalCardScale、LocalTextOnTable 等 CompositionLocal;卡片缩放/手牌偏移持久化 |
Color.kt |
颜色常量:4 种标准 UNO 色 + 4 种 Flip 暗面色 + 主题色(暗底/卡面/金色强调);getCardColor() / getCardBgColor() 工具函数 |
CardTheme.kt |
7 种卡面主题枚举,支持持久化 |
TableBg.kt |
7 种桌面背景枚举,含 isDark 标志驱动文字/强调色自动适配 |