基于 Kotlin + Jetpack Compose 的 UNO 卡牌游戏,支持单机 AI 对战和局域网多人联机
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
flykhan 702340fe6d
fix: 消除编译警告(冗余!!断言+未用变量+未用参数)
GameEngine.kt:
- 5处wildColor!!.displayName→wildColor.displayName(非空类型无需断言)
- restoreFromSave去掉未使用的players参数

LocalGameScreen.kt:
- 删除未使用的humanPlayer变量
2026-04-28 22:25:09 +08:00
app fix: 消除编译警告(冗余!!断言+未用变量+未用参数) 2026-04-28 22:25:09 +08:00
gradle/wrapper chore: 构建系统标准化,重生成gradle wrapper,签名从keystore.properties读取;新增gradlew.bat支持Windows开发 2026-04-27 11:41:27 +08:00
.gitignore feat: 重写局域网联机层,TCP长度前缀帧协议+主机权威架构,修复空闲断连/端口占用/并发崩溃 2026-04-27 17:06:10 +08:00
build.gradle.kts uno初版 2026-04-26 10:40:54 +08:00
gradle.properties uno初版 2026-04-26 10:40:54 +08:00
gradlew chore: 构建系统标准化,重生成gradle wrapper,签名从keystore.properties读取;新增gradlew.bat支持Windows开发 2026-04-27 11:41:27 +08:00
gradlew.bat chore: 构建系统标准化,重生成gradle wrapper,签名从keystore.properties读取;新增gradlew.bat支持Windows开发 2026-04-27 11:41:27 +08:00
README.md docs: 更新README核心模块说明对齐当前代码(网络层/TcpFramer/GameSaver/GameLogDialog/OnlineSetup) 2026-04-27 21:32:21 +08:00
settings.gradle.kts chore: 构建系统标准化,重生成gradle wrapper,签名从keystore.properties读取;新增gradlew.bat支持Windows开发 2026-04-27 11:41:27 +08:00

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 标志驱动文字/强调色自动适配