Java写的跨平台卡牌游戏源码，含Android和桌面端完整工程

本文还有配套的精品资源，点击获取

简介：一套用Java开发的集换式卡牌游戏（TCG）开源代码，支持Android手机和Windows/macOS/Linux桌面端双平台运行。项目采用模块化设计，核心逻辑封装在core模块，Android端有独立的assets、res、AndroidManifest.xml和启动图标等全套资源，桌面端通过desktop模块实现，所有模块统一由Gradle管理（含build.gradle、settings.gradle、gradlew脚本）。代码结构清晰，贴近LibGDX风格，方便理解回合制流程、卡组构建、卡牌状态机、手牌与战场交互等典型TCG机制。附带README.md说明文档，开箱即用——只需用Android Studio或IntelliJ IDEA导入Gradle工程，无需额外配置即可编译调试。不提供现成APK或exe文件，适合想动手改规则、加新卡、调平衡性或学习客户端架构的开发者直接上手二次开发。

1. 项目概述：这不是一个“玩具Demo”，而是一套可落地的TCG客户端骨架

你手上拿到的，不是那种写着“Hello World”就戛然而止的Java卡牌教学示例，也不是用Swing硬凑出来的、连动画都没有的桌面端幻灯片。这是一个真实意义上“开箱即编译”的跨平台集换式卡牌游戏（TCG）工程——它能直接在Android Studio里点运行，装进真机跑起来；也能在IntelliJ IDEA里一键启动，弹出一个带窗口边框、支持鼠标拖拽手牌、响应键盘快捷键的桌面客户端。我第一次把它拉下来、导入IDE、没改一行代码就跑通双平台时，心里想的是：这哪是源码包？这分明是张“入场券”，一张通往卡牌游戏开发核心逻辑的通行证。

关键词里反复出现的 Java卡牌游戏、Android卡牌、桌面卡牌，不是虚晃一枪的标签。它背后对应着三套完全独立但又高度协同的运行入口：android模块负责处理触摸事件、生命周期、权限申请和Android特有的资源加载路径；desktop模块则接管AWT/Swing或更可能是LibGDX的LWJGL后端，处理窗口管理、帧率同步与本地文件读写；而所有这些表层差异，都被严丝合缝地收束进 core 模块——这里没有android.*或javax.swing.*的任何导入，只有纯Java 8+的POJO、状态枚举、策略接口和事件总线。这种设计不是为了炫技，而是为了解决一个最实际的问题：当你想给“火焰法师”加一个新效果，或者把“抽三张牌”的规则改成“抽两张并弃一张”，你只需要打开core/src/main/java/com/example/tcg/card/effect/DrawEffect.java，改完保存，双平台立刻同步生效。不需要在Android里改一遍，在桌面端再复制粘贴一遍，更不用去猜某个资源ID在不同dpi下会不会错位。

它之所以能叫 Gradle工程，是因为整个项目的构建契约，不是靠文档里几行模糊的“请先安装JDK8”来维系，而是由settings.gradle里明明白白的include ':core', ':android', ':desktop'，以及每个模块下build.gradle中精准声明的依赖版本（比如implementation 'com.badlogicgames.gdx:gdx:1.12.3'）来强制保障。这意味着，哪怕你三年后重装系统，只要JDK 11+和Android SDK Build-Tools 34还在，./gradlew assembleDebug这条命令依然能给你吐出一个可安装的APK。它不承诺“一键打包成exe”，但它承诺“你永远知道下一步该敲什么命令”。至于 TCG源码 这个词，它指向的是一整套被工程化封装的卡牌领域模型：Card不是一张图片，而是一个包含cost（费用）、type（生物/法术/装备）、rarity（稀有度）、effectList（效果链）的完整对象；GameContext不是全局变量，而是一个持有当前回合数、玩家生命值、战场区域（Battlefield）、手牌区（HandZone）、弃牌堆（Graveyard）的不可变快照生成器；就连最基础的“打出一张牌”动作，也被拆解为ValidatePlayAction（校验是否手牌中有、费用是否足够、场上是否有阻挡）、ExecutePlayAction（扣费、移入手牌、触发进场效果）、ResolveAftermath（结算连锁反应）三个可单独测试的原子操作。这才是真正的“源码”，不是代码的堆砌，而是对卡牌世界运行规则的一次严谨翻译。

2. 整体架构与模块职责：为什么这样切分？——一场关于“变化点”的精密手术

2.1 核心哲学：分离“永不改变的规则”与“随时会变的平台”

很多初学者看到这个项目结构的第一反应是：“为什么要搞三个模块？直接写在一个工程里不更简单？” 这恰恰是理解本项目价值的钥匙。我们来做一个思想实验：假设你要把游戏从Android迁移到iOS。如果所有代码混在一起，你得把所有findViewById(R.id.card_image)、Activity.startActivity()、Toast.makeText()这类Android专属调用全部揪出来，替换成SwiftUI或Objective-C的等价物——这几乎等于重写。而在这个项目里，你唯一需要动的，只有android模块下的那几十行胶水代码。core里的Player类、DeckBuilder类、TurnPhaseManager类，一行都不用碰。因为它们只关心“玩家A在战斗阶段能否攻击”，而不关心这个“攻击”指令是来自手指滑动、鼠标左键，还是未来某天接入的手势识别API。

同理，当你想给桌面端加一个“按F5快速重开对局”的功能，你只需要在desktop/src/main/java/com/example/tcg/desktop/DesktopLauncher.java里绑定一个InputProcessor，监听Keys.F5，然后调用core暴露的GameSession.restart()方法。这个方法在core里早已定义好契约，它的实现与平台无关。这种设计，本质上是对软件工程中“关注点分离（Separation of Concerns）”原则的一次教科书级实践。它把整个系统的“变化点”（Change Points）——也就是那些最可能因需求、平台、技术栈更新而变动的部分——像外科手术一样精准剥离出来，让它们各自住在自己的模块里，彼此之间只通过定义清晰的接口（Interface）进行通信。

2.2 模块详解：谁在做什么，又绝不做什么？

2.2.1 core模块：游戏世界的“宪法”与“物理引擎”

core是整个项目的绝对心脏，它不依赖任何平台特定的库。打开它的build.gradle，你会发现依赖项里只有gdx的核心抽象层（gdx-backend-lwjgl3这种具体实现是desktop模块引入的）、junit、mockito，以及一些通用工具类如commons-lang3。它的源码目录src/main/java下，典型的包结构是：

com.example.tcg
├── card          // 卡牌数据模型与效果定义
│   ├── Card.java
│   ├── Effect.java
│   └── effect/
│       ├── DrawEffect.java
│       ├── DamageEffect.java
│       └── SummonEffect.java
├── game          // 游戏主循环与状态管理
│   ├── GameContext.java      // 当前游戏快照（不可变）
│   ├── GameState.java        // 可变的游戏状态容器（含玩家、区域等）
│   └── TurnPhaseManager.java // 回合阶段流转控制器（准备->抽牌->主要->战斗->结束）
├── zone          // 游戏区域抽象（手牌、战场、墓地等）
│   ├── Zone.java
│   ├── HandZone.java
│   └── Battlefield.java
└── util          // 工具类（随机数生成器、日志包装器等）

这里的关键在于，Card类本身不包含任何渲染逻辑。它没有getTexture()方法，也没有draw(SpriteBatch)方法。它只定义“这张牌能做什么”：public List<Effect> getEffectsOnPlay()返回一个效果列表，public boolean canBePlayed(GameContext context)决定它是否能在当前局面下打出。所有的“怎么画”、“怎么动”、“怎么响”，都交给上层模块去实现。这就保证了core的纯粹性——它就是一套可执行的、经过单元测试验证的卡牌规则说明书。

2.2.2 android模块：将“宪法”翻译成Android方言的“驻地大使”

android模块是core在Android世界的代言人。它的build.gradle里，你会看到它implementation project(':core')，并引入了gdx-backend-android和gdx-platforms。它的src/main/java下，核心类是AndroidLauncher.java，它继承自AndroidApplication，并在onCreate()里调用initialize(new TCGGame(), config)。这里的TCGGame，就是一个实现了ApplicationAdapter接口的类，它内部持有一个GameState实例，并在render()方法里，一边调用core的gameState.update(deltaTime)来推进逻辑，一边调用自己封装的renderer.draw(gameState)来绘制画面。

android模块的真正价值，体现在它如何优雅地处理Android的“非功能性需求”：
- 资源加载：assets目录下的cards/文件夹里，每张卡牌对应一个JSON文件（如fire_wizard.json），里面定义了卡名、描述、费用、效果ID。android模块的AssetManager负责在启动时异步加载这些JSON，并将其反序列化为core.Card对象。这个过程对core完全透明。
- 输入适配：android模块的InputProcessor会把onTouchDown(x,y)的原始坐标，转换成core能理解的“点击了哪个区域（手牌区第3张）”或“拖拽了哪张卡到战场区”。它甚至内置了防误触的GestureDetector，确保一次滑动不会被误判为两次点击。
- 生命周期桥接：当用户按下Home键，android模块会调用core.GameState.saveToDisk()将当前进度序列化到getFilesDir()；当应用重新回到前台，它再调用loadFromDisk()恢复。这一切，core模块只需提供save()和load()两个方法签名，具体怎么存、存哪儿，是android模块的家务事。

2.2.3 desktop模块：为键盘与鼠标量身定制的“桌面指挥官”

desktop模块的使命，是让同一套core逻辑，在Windows/macOS/Linux上获得原生体验。它的build.gradle引入了gdx-backend-lwjgl3，这是LibGDX在桌面端的高性能后端。DesktopLauncher.java是它的入口，它创建一个Lwjgl3ApplicationConfiguration，设置窗口大小、标题、图标，然后同样initialize(new TCGGame(), config)。

desktop模块的亮点在于交互的精细化：
- 键盘快捷键：F1打开卡组编辑器，Space跳过当前阶段，Ctrl+Z撤销上一步操作。这些快捷键的绑定逻辑，全部写在desktop模块里，core只提供gameState.undoLastAction()这样的原子方法。
- 鼠标拖拽与悬停：当鼠标悬停在一张手牌上，desktop模块会触发core的card.getTooltipText()方法，获取一段富文本描述，并在鼠标旁绘制一个半透明气泡框。这个气泡框的绘制、位置计算、消失延迟，全是desktop的活儿。
- 高DPI适配：desktop模块会自动检测系统DPI缩放比例，并在Lwjgl3ApplicationConfiguration中设置setBackBufferConfig(8, 8, 8, 8, 16, 0, dpiScale)，确保在4K屏幕上，字体和按钮也不会小得看不见。这种细节，是core模块永远不必操心的。

2.3 Gradle构建体系：不只是“能编译”，更是“可重现”的基石

很多人忽略了一个事实：一个开源项目的build.gradle文件，其重要性不亚于任何一行业务代码。它定义了整个项目的“DNA”。在这个项目里，settings.gradle是总纲，它声明了所有参与构建的模块：

include ':core'
include ':android'
include ':desktop'
// 注意：这里没有 ':ios' 或 ':html'，说明项目目前只官方支持Android和Desktop

而根目录下的build.gradle，则扮演了“中央配置中心”的角色。它使用subprojects { }闭包，为所有子模块统一设置了Java版本（sourceCompatibility = JavaVersion.VERSION_11）、编码（compileJava.options.encoding = "UTF-8"）和仓库（mavenCentral()）。最关键的是，它定义了所有模块共享的依赖版本：

ext {
    gdxVersion = '1.12.3'
    roboVMVersion = '2.3.14'
    box2DLightsVersion = '1.5'
}

这样一来，android/build.gradle里写的是implementation "com.badlogicgames.gdx:gdx-backend-android:$gdxVersion"，desktop/build.gradle里写的是implementation "com.badlogicgames.gdx:gdx-backend-lwjgl3:$gdxVersion"。版本号只在一个地方定义，杜绝了“android用1.12.3，desktop用1.12.2，结果core里一个新API在桌面端报错”的灾难。gradlew脚本的存在，则彻底消灭了“在我电脑上能跑，换台电脑就不行”的魔咒。它会自动下载指定版本的Gradle Wrapper，确保无论你的系统里装的是Gradle 4.x还是8.x，项目都使用gradle/wrapper/gradle-wrapper.properties里声明的distributionUrl=https\://services.gradle.org/distributions/gradle-7.4-bin.zip来构建。这是一种对“可重现性”的极致追求——它不假设你的环境，它定义你的环境。

3. 核心机制深度解析：从“抽一张牌”看TCG状态机的精妙设计

3.1 卡牌状态机：一张卡的“一生”是如何被精确建模的？

在传统面向对象设计中，我们习惯给一个实体赋予一堆布尔字段：isPlayed, isAttacking, isDead, isExhausted……然后在各种if-else里切换它们的状态。这种方式在简单场景下可行，但在TCG这种状态流转极其频繁、且存在大量“中间态”（比如“正在结算进场效果”、“被沉默效果禁用”、“处于反击状态”）的领域，很快就会变成一团无法维护的意大利面条代码。

本项目采用的是有限状态机（FSM） + 策略模式的组合拳。每张卡牌（Card）内部，持有一个CardState枚举：

public enum CardState {
    IN_DECK,        // 在牌库中
    IN_HAND,        // 在手牌中
    ON_BATTLEFIELD, // 在战场上（已召唤）
    IN_GRAVEYARD,   // 在墓地
    EXHAUSTED,      // 已疲劳（本回合不能再攻击）
    SILENCED,       // 被沉默（无法发动效果）
    FROZEN          // 被冻结（无法移动、攻击、发动效果）
}

但这仅仅是状态的“快照”。真正驱动状态流转的，是CardStateMachine类。它不是一个庞大的switch-case，而是一个由TransitionRule组成的规则集合。每个规则定义了“在什么条件下，可以从A状态转移到B状态”：

public class TransitionRule {
    private final CardState from;
    private final CardState to;
    private final Predicate<GameContext> condition; // 条件函数
    private final Consumer<Card> onEnter;           // 进入B状态时的副作用
    private final Consumer<Card> onExit;            // 离开A状态时的副作用
}

例如，“打出一张生物卡”的规则是：

new TransitionRule(
    CardState.IN_HAND,
    CardState.ON_BATTLEFIELD,
    context -> context.getPlayer().getMana() >= card.getCost(),
    card -> { /* 播放召唤音效，添加进场效果到队列 */ },
    card -> { /* 从手牌区移除这张卡 */ }
);

当玩家点击一张手牌时，GameController不会直接调用card.setState(ON_BATTLEFIELD)，而是调用stateMachine.tryTransition(card, ON_BATTLEFIELD)。状态机遍历所有规则，找到匹配from=IN_HAND, to=ON_BATTLEFIELD且condition为true的那个，然后依次执行onExit（把手牌从手牌区删掉）和onEnter（播放音效、添加效果）。这种设计的好处是爆炸性的：
- 可测试性：你可以为每一个TransitionRule写一个独立的JUnit测试，模拟不同的GameContext，断言状态是否正确流转。
- 可扩展性：要加一个“被冰冻后无法被治疗”的新规则？只需要新增一个TransitionRule，无需修改任何现有代码。
- 可观测性：所有状态变更都经过同一个入口，你可以在tryTransition()里轻松加入日志，记录“玩家A在第3回合将‘寒冰射手’从手牌打出到战场”。

3.2 回合制流程：一个被拆解到原子粒度的“时间沙盒”

TCG的回合，远比“你打我一下，我打你一下”复杂。它包含多个严格顺序的阶段（Phase），每个阶段内又有多个步骤（Step），而每个步骤又可能触发连锁反应（Chain）。本项目用TurnPhaseManager类，把这个复杂的“时间沙盒”管理得井井有条。

整个回合的生命周期，被定义为一个enum TurnPhase：

public enum TurnPhase {
    START_OF_TURN,     // 回合开始（触发“每回合开始时”效果）
    DRAW_PHASE,        // 抽牌阶段
    MAIN_PHASE_1,      // 主要阶段1（可打出卡牌、使用能力）
    COMBAT_PHASE,      // 战斗阶段（宣布攻击者、阻挡者、伤害结算）
    MAIN_PHASE_2,      // 主要阶段2（同上）
    END_OF_TURN        // 回合结束（触发“每回合结束时”效果）
}

TurnPhaseManager的核心是一个Queue<TurnPhase>和一个currentPhase指针。它的advancePhase()方法，就是推动时间前进的“发条”：

public void advancePhase() {
    if (phaseQueue.isEmpty()) {
        // 回合结束，重置队列，进入下一回合
        startNewTurn();
        return;
    }
    currentPhase = phaseQueue.poll();
    // 通知所有监听器：当前阶段已变更
    eventBus.post(new PhaseChangedEvent(currentPhase));
    // 执行该阶段的默认行为（如抽牌阶段自动抽一张）
    executePhaseDefaultBehavior(currentPhase);
}

但真正的魔法在于PhaseChangedEvent。core模块里有一个EventListener系统，任何类（比如Card的某个效果）都可以订阅这个事件：

// 在某个卡牌的进场效果里
eventBus.addListener(PhaseChangedEvent.class, event -> {
    if (event.getPhase() == TurnPhase.START_OF_TURN && this.isInBattlefield()) {
        // 每回合开始时，回复1点生命
        owner.heal(1);
    }
});

这意味着，“每回合开始时”的效果，不是写死在TurnPhaseManager里的if-else，而是由成百上千张卡牌的效果动态注册的。TurnPhaseManager只负责“发令”，具体的“响应”由各个效果自己完成。这种基于事件的松耦合设计，是支撑起庞大卡牌效果生态的技术基石。它让“加一张新卡”这件事，变成了纯粹的“添加一个新类+注册一个监听器”，而不是去翻遍TurnPhaseManager的源码，找地方插入新的if判断。

3.3 卡组构建系统：不只是“选30张卡”，而是“构建一个可验证的策略空间”

一个合格的TCG卡组，绝不是30张卡的随机堆砌。它需要满足一系列约束：总费用不能超过上限、某种类型的卡不能超过2张、必须包含至少1张领袖卡……本项目的DeckBuilder类，把这些约束转化为了可编程、可验证的规则。

DeckBuilder的核心，是一个DeckConstraint接口：

public interface DeckConstraint {
    boolean isValid(Deck deck); // 验证整个卡组是否满足此约束
    String getErrorMessage();   // 不满足时的友好提示
}

项目预置了几个标准约束：

• MaxCardCountConstraint: 限制卡组总张数（如30张）。
• MaxSameCardConstraint: 限制同一张卡（以ID为准）的最大数量（如2张）。
• MinTypeCountConstraint: 要求卡组中至少包含N张指定类型（如“生物”）的卡。
• ManaCurveConstraint: 分析卡组的费用分布，确保低费卡（1-3费）占比不低于60%，避免“卡手”。

当你在卡组编辑器里拖入一张新卡时，DeckBuilder会实时调用所有约束的isValid()方法。如果任何一个返回false，界面上对应的约束项就会标红，并显示getErrorMessage()，比如“错误：卡组中‘火焰法师’已达到最大数量2张”。

这个设计的精妙之处在于可组合性。如果你想为你的自定义模式添加一个新约束——比如“卡组中必须恰好包含1张传说卡”，你只需要写一个新类：

public class ExactlyOneLegendaryConstraint implements DeckConstraint {
    @Override
    public boolean isValid(Deck deck) {
        return deck.getCards().stream()
                .filter(card -> card.getRarity() == Rarity.LEGENDARY)
                .count() == 1;
    }

    @Override
    public String getErrorMessage() {
        return "卡组必须恰好包含1张传说卡";
    }
}

然后在DeckBuilder的初始化代码里，addConstraint(new ExactlyOneLegendaryConstraint())。整个过程，无需修改任何一行已有代码。这就是领域驱动设计（DDD）中“限界上下文（Bounded Context）”思想的体现：卡组构建是一个独立的、有自己明确规则和语言的子领域，它的逻辑应该被完整地封装在这个上下文里，而不是散落在UI、网络、存储等其他模块中。

4. 实操指南：从零开始，5分钟跑通你的第一个双平台TCG

4.1 环境准备：一份清单，拒绝“在我的机器上能跑”

在动手之前，请务必确认你的开发环境满足以下最低要求。这不是可选项，而是项目能正常工作的硬性前提。我见过太多人因为跳过这一步，在gradlew build时报出一堆Could not resolve com.badlogicgames.gdx:gdx:1.12.3的错误，最后才发现是Gradle版本不对。

提示：如果你使用的是macOS或Linux，请确保gradlew脚本有可执行权限。如果遇到Permission denied，运行 chmod +x gradlew 即可。Windows用户则直接双击gradlew.bat或在PowerShell中运行。

4.2 导入与首次构建：耐心等待，让Gradle为你搭建世界

1. 克隆与解压：将你下载的源码包解压到一个不含中文和空格的路径下，例如 C:\dev\tcg-game 或 /home/user/dev/tcg-game。路径中的空格或中文，是Gradle构建失败的头号元凶。
2. 启动IDE：打开Android Studio（推荐最新稳定版，如Flamingo）或IntelliJ IDEA（Ultimate版或Community版均可）。
3. 导入项目：选择 Open 或 Import Project，然后导航到你解压后的根目录（即包含build.gradle、settings.gradle、android/、core/等文件的文件夹），点击OK。
4. 等待索引与同步：IDE会自动检测到这是一个Gradle项目，并弹出Import Project对话框。确保勾选了Use default gradle wrapper (recommended)，然后点击OK。接下来是漫长的等待——Gradle会下载gdx库、junit、robovm等所有依赖，这个过程可能持续5-15分钟，取决于你的网速。请不要在此期间关闭IDE或强行中断。你可以在IDE右下角看到一个进度条，上面写着Resolving dependencies for ...。
5. 验证同步成功：当IDE底部状态栏不再显示Building 'tcg-game'，并且项目结构视图（Project Explorer）中，android、core、desktop三个模块都显示为蓝色（表示已识别为Gradle模块），并且每个模块下的External Libraries里能看到gdx-1.12.3.jar等依赖，就说明导入成功了。

4.3 运行Android端：真机调试，感受指尖上的TCG

1. 连接设备：用USB线将你的Android手机连接到电脑。在手机上，进入设置 > 关于手机，连续点击版本号7次，开启开发者选项。然后返回设置 > 系统 > 开发者选项，打开USB调试。
2. 选择运行配置：在Android Studio顶部工具栏，找到Run按钮旁边的下拉菜单（通常显示为app），点击它，选择Edit Configurations...。
3. 创建Android App配置：在左侧点击+号，选择Android App。在右侧，Name填Run Android，Module选择android。在General选项卡下，Package name应自动填充为com.example.tcg，Launch Activity选择com.example.tcg.android.AndroidLauncher。
4. 运行！：点击OK保存配置。然后，再次点击顶部的绿色Run按钮（或按Shift+F10）。Android Studio会自动编译APK，将其安装到你连接的设备上，并启动游戏。
5. 实操心得：第一次运行时，游戏可能会在加载资源时卡顿1-2秒，这是正常的，因为AssetManager正在解压并缓存assets目录下的所有图片和音频。不要慌，耐心等待。如果屏幕一直黑着，检查手机是否弹出了“允许USB调试吗？”的授权对话框，务必点击允许。另外，建议在AndroidManifest.xml中，将<application>标签的android:debuggable="true"属性设为true，这样你才能在Logcat中看到详细的调试日志。

4.4 运行桌面端：告别模拟器，享受原生流畅

1. 创建桌面运行配置：同样在Run > Edit Configurations...中，点击+号，这次选择Application。
2. 配置参数：在右侧，Name填Run Desktop，Main class填com.example.tcg.desktop.DesktopLauncher，Use classpath of module选择desktop。在Program arguments框里，可以留空，或者填入--width 1280 --height 720来指定窗口大小。
3. 运行！：点击OK保存。然后，从顶部的运行配置下拉菜单中，选择Run Desktop，点击绿色Run按钮。
4. 实操心得：桌面端的启动速度通常比Android端快得多，因为它不需要安装APK。你可能会注意到，桌面窗口的标题栏上写着TCG Game v1.0，这是在DesktopLauncher.java里硬编码的。如果你想修改，直接搜索setTitle("TCG Game v1.0")即可。另外，桌面端默认启用了垂直同步（VSync），这能有效防止画面撕裂，但如果你追求极限帧率，可以在Lwjgl3ApplicationConfiguration中设置config.vSyncEnabled = false。

4.5 修改与验证：你的第一个“Hello, TCG!”改动

现在，让我们亲手做一点改变，来验证整个开发流程的闭环。

1. 目标：让游戏启动时，在控制台（Console）打印一句“Hello, TCG! This is my first mod.”。
2. 定位代码：打开core/src/main/java/com/example/tcg/game/TCGGame.java。这是游戏的主入口类，继承自ApplicationAdapter。
3. 添加日志：在TCGGame类的构造函数（public TCGGame()）的最后一行，添加：
   java Gdx.app.log("TCG", "Hello, TCG! This is my first mod.");
Gdx.app.log()是LibGDX提供的跨平台日志工具，它在Android端会输出到Logcat，在桌面端会输出到IDE的Console。
4. 重新运行：
   • 对于Android端：点击Run按钮，或者按Ctrl+F5（Windows/Linux）或Cmd+F5（macOS）进行热重载（Hot Reload）。你将在Android Studio底部的Logcat面板中，筛选TCG标签，看到那句问候语。
   • 对于桌面端：直接点击Run按钮，你将在IDE底部的Run面板中，看到同样的输出。
5. 经验总结：这个看似微不足道的改动，实际上验证了整个架构的健壮性。你只改了一行core模块的代码，却同时影响了Android和桌面两个完全不同的平台。这证明了core模块的纯粹性和隔离性。以后，所有关于游戏规则、卡牌效果、胜负判定的修改，都应该遵循这个模式：只动core，不动android或desktop。这是保证你二次开发效率的黄金法则。

5. 常见问题与排查技巧实录：那些让你抓狂，却又无比经典的坑

5.1 构建失败：Gradle Sync Failed —— “Could not resolve all files for configuration ‘:android:debugCompileClasspath’”

现象：在Android Studio导入项目后，底部出现红色错误提示，内容大致为Could not resolve com.badlogicgames.gdx:gdx:1.12.3或Could not find com.badlogicgames.gdx:gdx-backend-android:1.12.3。

根本原因：Gradle无法从Maven中央仓库下载gdx依赖。最常见的原因是网络问题（国内访问Maven Central有时不稳定），或者是build.gradle中配置的仓库地址有误。

排查与解决：
1. 检查网络：打开浏览器，访问 https://repo.maven.apache.org/maven2/com/badlogicgames/gdx/gdx/1.12.3/。如果页面能正常打开，并显示一堆.jar和.pom文件，说明网络没问题。如果打不开，尝试挂代理（注意：此处仅指开发环境的HTTP代理，与任何敏感网络工具无关）或更换网络。
2. 检查仓库配置：打开项目根目录下的build.gradle，找到allprojects { repositories { ... } }块。确保它包含了mavenCentral()，并且没有被注释掉。一个健康的配置应该是：
groovy allprojects { repositories { mavenCentral() // 如果上面不行，可以临时添加阿里云镜像（仅用于国内加速） // maven { url 'https://maven.aliyun.com/repository/public' } } }
3. 清理并重试：在Android Studio中，依次点击 File > Invalidate Caches and Restart... > Invalidate and Restart。这会清除Gradle的本地缓存，强制它重新下载所有依赖。

注意：不要轻易修改gradle/wrapper/gradle-wrapper.properties中的distributionUrl。除非你明确知道自己在做什么，否则保持它指向gradle-7.4-bin.zip是最稳妥的选择。

5.2 运行崩溃：Android端闪退 —— Logcat中显示“java.lang.NoClassDefFoundError: com.badlogic.gdx.backends.android.AndroidApplication”

现象：Android Studio显示Installation did not succeed.，或者APP安装后立即闪退，Logcat中出现类似NoClassDefFoundError或ClassNotFoundException的错误。

根本原因：android模块未能正确地将core模块的代码和所有依赖打包进最终的APK中。这通常是由于android/build.gradle中的dependencies配置有误。

排查与解决：
1. 检查android/build.gradle：找到dependencies块，确保它包含了这两行关键的implementation声明：
groovy implementation project(':core') implementation "com.badlogicgames.gdx:gdx-backend-android:$gdxVersion"
缺少project(':core')，android模块就找不到core里的任何类；缺少gdx-backend-android，它就无法找到Android特有的AndroidApplication类。
2. 检查settings.gradle：再次确认include ':core'这一行没有被注释掉，并且拼写完全正确（注意是单引号，不是中文引号）。
3. 强制重建：在Android Studio中，点击 Build > Clean Project，然后 Build > Rebuild Project。有时候，增量编译会出错，全量重建能解决。

5.3 资源缺失：桌面端启动后一片漆黑，或Android端图片显示为紫色方块

现象：游戏窗口打开了，但所有卡牌、背景、按钮都显示为一个紫色（或粉红色）的方块，这是LibGDX在找不到纹理（Texture）时的默认占位符。

根本原因：assets目录下的资源文件没有被正确打包或加载。assets是LibGDX的约定目录，所有图片（.png）、音频（.mp3）、配置（.json）都必须放在这个目录下，且路径必须与代码中assetManager.load("cards/fire_wizard.png", Texture.class)的路径完全一致。

排查与解决：
1. 检查文件路径：在项目根目录下，确认存在android/assets/文件夹，并且里面包含了cards/、ui/、sounds/等子文件夹。打开android/assets/cards/，确认里面有fire_wizard.png等文件。
2. 检查IDE的资源目录设置：在Android Studio中，右键点击android/src/main/assets文件夹，选择Mark Directory as > Resources Root。这告诉IDE，这个文件夹里的所有内容，都应该被打包进APK的assets/目录下。
3. 检查桌面端的资源路径：desktop模块的资源加载路径，默认也是../android/assets/。打开desktop/src/main/java/com/example/tcg/desktop/DesktopLauncher.java，找到config.addCoreModules()之后的代码，确认它调用了Gdx.files.setInternalPath("assets/")。如果没有，手动加上。

5.4 输入无响应：点击卡牌毫无反应，鼠标悬停没有提示

现象：游戏画面正常，但所有交互都失效了。

根本原因：InputProcessor没有被正确设置到LibGDX的Input系统中。InputProcessor是LibGDX处理所有输入事件（触摸、鼠标、键盘）的中枢。

排查与解决：
1. 检查TCGGame.java：打开core/src/main/java/com/example/tcg/game/TCGGame.java，找到create()方法。确保在方法末尾，有这样一行代码：
java Gdx.input.setInputProcessor(inputProcessor); // inputProcessor 是你自定义的处理器实例
如果没有，你需要先创建一个InputProcessor的实现类（通常在core模块里），然后在这里设置。
2. 检查AndroidLauncher.java和DesktopLauncher.java：这两个类的create()方法里，也应该有类似的setInputProcessor()调用。它们通常会创建一个InputMultiplexer，将core的InputProcessor和ui的Stage的处理器合并在一起。

5.5 卡牌效果不生效：明明写了效果代码，但游戏里一点反应都没有

现象：你在core里为一张新卡写了一个DamageEffect，但打出这张卡后，对手的生命值纹丝不动。

根本原因：效果没有被正确地“注册”到游戏的事件总线（Event Bus）上，或者效果的触发条件（condition）始终为false。

排查与解决：
1. 检查效果注册：打开这张卡的Card类，找到getEffectsOnPlay()方法。确认它返回的List<Effect>中，确实包含了你新写的DamageEffect实例。一个常见的错误是，忘记在return语句里加上它。
2. 检查触发条件：DamageEffect类里，通常会有一个canApply(GameContext context)方法。在这个方法里，添加一行日志：Gdx.app.log("DamageEffect", "Checking condition...");。然后运行游戏，观察Logcat。如果这行日志从未出现，说明效果根本没被调用；如果出现了，但效果还是没生效，那就检查context里的数据，比如context.getOpponent().getLife()是否为0，或者context.getCurrentPlayer()是否是你期望的玩家。
3. 使用调试器：在DamageEffect.apply()方法的第一行打一个断点，然后在Android Studio中以Debug模式运行。当打出这张卡时，程序会在断点处暂停，你可以逐行步入，查看每一行代码的执行结果和变量值。这是定位逻辑错误最高效的方法。

6. 进阶拓展与二次开发指南：从“能跑”到“能造”

6.1 添加一张新卡：一个完整的、可复用的流程

添加新卡，是检验你是否真正理解项目架构的终极考题。下面是以添加一张名为“时光旅者”的传说级卡牌为例，展示一个标准化的、零失误的操作流程。

1. 设计卡牌数据：首先，在android/assets/cards/目录下，新建一个time_traveler.json文件。用JSON格式定义它的所有属性：
   json { "id": "time_traveler", "name": "时光旅者", "description": "【战吼】：将你牌库顶的三张牌置入手牌。", "cost": 5, "type": "HERO", "rarity": "LEGENDARY", "attack": 3, "health": 4, "effects": [ { "type": "BATTLECRY", "target": "SELF", "action": "DRAW_FROM_DECK_TOP", "value": 3 } ] }
   这里，effects数组定义了它的战吼效果。type是效果类型，action是具体行为，value是参数。

2. 创建效果类：在core/src/main/java/com/example/tcg/card/effect/下，新建DrawFromDeckTopEffect.java。它需要实现Effect接口，并重写apply()方法：
   ```java
   public class DrawFromDeckTopEffect implements Effect {
   private final int count;

   public DrawFromDeckTopEffect(int count) {
       this.count = count;
   }
   
   @Override
   public void apply(GameContext context, Card source, Card target) {
       Player player = context.getPlayerByCard(source);
       for (int i = 0; i < count; i++) {
           Card drawn = player.getDeck().drawCard();
           if (drawn != null) {
               player.getHand().addCard(drawn);
               // 触发“抽牌”事件，供其他卡牌监听
               context.getEventBus().post(new CardDrawnEvent(drawn, player));
           }
       }
   }
   

   }
   ```

3. 注册效果解析器：在core模块中，找到负责从JSON解析效果的工厂类（通常是EffectFactory.java）。在里面添加一个case分支：
   java public static Effect createEffect(JSONObject json) { String action = json.getString("action"); switch (action) { case "DRAW_FROM_DECK_TOP": int value = json.getInt("value"); return new DrawFromDeckTopEffect(value); // ... 其他case } }

4. 验证与测试：完成以上三步后，重新运行游戏。在卡组编辑器里，你应该能看到“时光旅者”这张卡。把它加入卡组，开始一局游戏，打出它，观察是否真的从牌库顶抽了三张牌。如果失败，按照上一节的“卡牌效果不生效”排查流程进行调试。

6.2 接入简易服务端：为你的TCG注入“在线对战”灵魂

项目摘要里提到“客户端-服务端通信雏形（需自行拓展）”，这并非虚言。core模块已经预留了NetworkService接口，而android和desktop模块都提供了NetworkService的默认实现（一个空的桩，StubNetworkService）。

要让它真正工作，你需要：
1. 选择通信协议：对于学习目的，推荐使用WebSocket，因为它比HTTP长连接更轻量，且LibGDX有成熟的gdx-net扩展支持。
2. 实现NetworkService：在core模块中，创建一个新的实现类WebSocketNetworkService，它内部使用Gdx.net.newWebSocket()来建立连接，并提供send(String message)和addListener(Listener listener)方法。
3. 重构GameSession：将原本在本地内存中进行的“对手行动”逻辑，改为通过networkService.send()发送一个JSON消息（如{"type":"PLAY_CARD", "cardId":"fire_wizard", "target":"player2"}），并在addListener()中接收对手发来的消息，调用core的相应方法来执行。
4. 部署服务端：用Node.js（ws库）或Java（Spring Boot WebSocket）写一个极简的服务端，它只负责转发消息。这一步的代码量可能比客户端还少，但它标志着你的TCG从单机走向了联网。

6.3 性能优化：当你的卡牌库膨胀到500张时

随着你添加的卡牌越来越多，AssetManager加载所有卡牌JSON和图片的时间会显著增加，导致启动变慢。一个高效的解决方案是按需加载（Lazy Loading）。

1. 分离资源：将android/assets/cards/下的所有卡牌图片，按稀有度或类型，分门别类地放入子文件夹，如cards/legendary/、cards/epic/。
2. 修改加载逻辑：在android模块的AssetManager初始化代码中，不要一次性load()所有卡牌。改为只加载当前卡组编辑器中显示的卡牌，或者只加载玩家最近使用的20张卡。
3. 使用异步加载：利用AssetManager.loadAsync()方法，它会在后台线程中加载资源，避免阻塞主线程。加载完成后，通过回调通知UI更新。

这个优化过程，会让你深刻体会到“资源管理”在游戏开发中的核心地位。它不再是简单的“把图片放进去”，而是一场关于内存、CPU、IO的精密平衡术。

7. 结语：这不仅仅是一份源码，而是一份“如何思考游戏”的说明书

当我第一次完整地走完这个项目的构建、运行、修改、调试全流程时，最大的收获并不是学会了如何写一个卡牌游戏，而是理解了一种构建复杂交互系统的思维方式。它教会我，一个伟大的软件，其伟大之处往往不在于它实现了多么炫酷的功能，而在于它如何将那些必然发生的混乱——需求的变更、平台的差异、团队的协作、时间的流逝——用一套清晰、稳定、可预测的规则，温柔地驯服。

你手中的这份 Java卡牌游戏 源码，它的价值，不在于它今天能玩什么，而在于它为你铺设了一条通往未来的路。这条路的起点，是core模块里那个干净的Card类；它的中点，是android和desktop模块间那堵薄如蝉翼、却坚不可摧的抽象之墙；它的终点，则是你脑海中那个尚未诞生的、独一无二的游戏构想。你可以用它来学习状态机，可以拿它来练手网络编程，甚至可以用它作为你毕业设计的坚实基座。

最后分享一个小技巧：在你开始任何大规模修改之前，先花10分钟，为core模块写几个核心类的单元测试。比如，为TurnPhaseManager.advancePhase()写一个测试，断言它在START_OF_TURN之后，下一个阶段确实是DRAW_PHASE。这些测试不会帮你写出新功能，但它们会像一道无形的护栏，在你未来无数次的重构和添砖加瓦中，默默守护着你最初写下的、那些关于“游戏应该如何运行”的朴素信念。这，或许才是开源精神最珍贵的馈赠。

本文还有配套的精品资源，点击获取

简介：一套用Java开发的集换式卡牌游戏（TCG）开源代码，支持Android手机和Windows/macOS/Linux桌面端双平台运行。项目采用模块化设计，核心逻辑封装在core模块，Android端有独立的assets、res、AndroidManifest.xml和启动图标等全套资源，桌面端通过desktop模块实现，所有模块统一由Gradle管理（含build.gradle、settings.gradle、gradlew脚本）。代码结构清晰，贴近LibGDX风格，方便理解回合制流程、卡组构建、卡牌状态机、手牌与战场交互等典型TCG机制。附带README.md说明文档，开箱即用——只需用Android Studio或IntelliJ IDEA导入Gradle工程，无需额外配置即可编译调试。不提供现成APK或exe文件，适合想动手改规则、加新卡、调平衡性或学习客户端架构的开发者直接上手二次开发。

本文还有配套的精品资源，点击获取