自定义 UI 接入

Guide

订阅战斗事件，通过 GCSApi 读取当前状态，再把出牌、回合、选择和奖励操作提交回运行时

上图展示了自定义 UI 与 GCS 之间唯一需要维持的双向关系，运行时用事件通知变化，UI 收到通知后重新读取当前状态，玩家操作再通过 GCSApi 提交回同一场战斗，界面本身不保存另一份权威战斗数据

代码片段只包含与 GCS 交互的组件部分，将它们放入项目的 presenter 或 MonoBehaviour，并按实际使用的类型添加 using System;、using System.Collections.Generic; 和 using TinyGiants.GCS.Runtime;

接入检查清单

放置并配置一个 GameCardManager
用 GCSApi.StartBattle 启动战斗
在 UI 生命周期方法中订阅运行时事件
每次事件触发后，从 GCSApi 刷新 UI
卡牌按钮使用 GCSApi.CanPlayCard 和 GCSApi.TryPlayCard
使用 TMP Description 时，通过 DescriptionTooltipTrigger 绑定卡牌规则文本
结束回合按钮使用 GCSApi.EndPlayerTurn
奖励界面使用 GCSApi.ApplyReward 或 GCSApi.SkipReward
释放每一个订阅
让 Demo 专用 View 组件保持可替换

订阅生命周期

每个 UI 对象用一个小的 disposable 列表管理订阅

private readonly List<IDisposable> _subscriptions = new();

void OnEnable()
{
    _subscriptions.Add(GCSApi.OnBattleStarted(RefreshAll));
    _subscriptions.Add(GCSApi.OnEnergyChanged(_ => RefreshEnergy()));
    _subscriptions.Add(GCSApi.OnCardDrawn(_ => RefreshHand()));
    _subscriptions.Add(GCSApi.OnCardDiscarded(_ => RefreshHand()));
    _subscriptions.Add(GCSApi.OnCardExhausted(_ => RefreshHand()));
    _subscriptions.Add(GCSApi.OnUnitHpChanged(_ => RefreshUnits()));
    _subscriptions.Add(GCSApi.OnStatusChanged(_ => RefreshStatuses()));
}

void OnDisable()
{
    foreach (var subscription in _subscriptions)
    {
        subscription.Dispose();
    }
    _subscriptions.Clear();
}

提示

GameObject 销毁时应释放它持有的订阅，否则陈旧监听器会在重新加载后叠加，造成 UI 重复刷新

战斗 HUD

高层 HUD 字段从状态刷新：

Widget	读取
Phase label	`GCSApi.Phase`
Turn label	`GCSApi.TurnNumber`
Energy	`GCSApi.PlayerEnergy`、`GCSApi.MaxEnergy`
End turn button	`GCSApi.Phase == BattlePhase.PlayerPhase`
Battle result overlay	`OnBattleEnded` 与 `BattleEndedEventArgs.Won`

阶段应以 GCSApi.Phase 和阶段事件为准，因为行为图可以结束回合、给予额外回合、打开选择，甚至在没有 UI 输入的情况下直接结束战斗

HUD 和游戏对不上时

打开 Game Card Monitor：

Tools > TinyGiants > GCS > Game Card Monitor

查看 Battle 标签页，如果 Monitor 中的战斗状态正确，而 HUD 显示错误，应检查 HUD 的事件订阅和刷新路径

运行中战斗里 Game Card Monitor 的 Battle 标签页，显示自定义 HUD 应当呈现的同一份阶段、回合、玩家和敌人状态

手牌 UI

手牌可以从 GCSApi.Hand() 完整重建，也可以按实例 ID 局部更新，该方法返回调用时刻的实时手牌堆，本回合新抽的卡也包含在内

void RefreshHand()
{
    foreach (var card in GCSApi.Hand())
    {
        var active = GCSApi.GetActiveCard(card);
        var cost = GCSApi.GetEffectiveEnergyCost(card);
        var playable = GCSApi.CanPlayCard(card);
        RenderCard(card, active, cost, playable);
    }
}

将 DescriptionTooltipTrigger 挂到显示 Description 的 GameObject 上，同一对象已有 TMP_Text 时无需设置 Description Label，文本在其他对象上时，将对应组件拖入该字段，若要按完整卡面定位 Tooltip，将卡面的 RectTransform 拖入 Tooltip Anchor

绑定卡牌视图时，调用 Bind 并传入当前 GameCard 和对应的 CardInstance，组件会解析 Description 中的 Token 与格式标签

提示

有效的 @Name 引用会隐藏 @ 前缀，并在悬停时显示对应 Tooltip

[SerializeField] private DescriptionTooltipTrigger descriptionTooltip;

void BindCard(CardInstance instance)
{
    var activeCard = GCSApi.GetActiveCard(instance);
    descriptionTooltip.Bind(activeCard, instance);
}

void ReleaseCard()
{
    descriptionTooltip.Clear();
}

卡牌视图返回对象池前，调用 Clear() 清除文本与引用数据，并关闭 Tooltip

提示

将 Description 引用的 GameStatus 加入 GameCardManager 已启用的 Status Database，组件只从这些数据库解析 Status 引用，Keyword 则通过 CardTagRegistry 解析

Canvas UI 需要在 Description 文本上启用 Raycast Target，在场景中添加 EventSystem，并在 Canvas 上添加 GraphicRaycaster，组件才能接收指针事件

世界空间卡牌可使用 Physics2DRaycaster 与 Collider2D 接收指针事件，使用自定义输入时，调用 UpdatePointer 传入指针屏幕坐标与事件相机

descriptionTooltip.UpdatePointer(pointerScreenPosition, eventCamera);

自定义输入未触发 OnPointerExit 时，在指针离开卡牌后调用 HideTooltip()

未设置 Tooltip Anchor 时，组件依次尝试自身的 RectTransform、Collider2D 和指针位置，使用第一个可用结果定位 Tooltip

奖励界面没有实时 CardInstance 时，只传入 GameCard 定义

descriptionTooltip.Bind(card);

该调用按基础卡牌定义渲染 Description，Tooltip 的锚点与输入方式仍使用组件当前配置

卡牌视图完成数据绑定后，再将卡牌点击事件接入现有的出牌检查流程

void OnCardClicked(CardInstance card)
{
    var active = GCSApi.GetActiveCard(card);
    if (GCSApi.RequiresTarget(active))
    {
        OpenTargetPicker(card);
        return;
    }

    GCSApi.TryPlayCard(card);
}

目标选择完成后：

void OnTargetSelected(CardInstance card, UnitState target)
{
    GCSApi.TryPlayCard(card, target);
}

单位面板

单位面板从运行时单位构建

面板值	读取
HP	`GCSApi.Hp(unit)`、`GCSApi.MaxHp(unit)`
护甲	`GCSApi.Armor(unit)`
存活/死亡	`GCSApi.IsAlive(unit)`
HP 百分比	`GCSApi.HpPercent(unit)`
状态	`GCSApi.StatusesOn(unit)`
敌人意图	`GCSApi.PendingIntents(enemy)`

单位面板可以由以下事件触发刷新：

OnUnitHpChanged
OnUnitDied
OnUnitRevived
OnPlayerUnitAdded
OnUnitRemoved
OnArmorGained
OnArmorLost
OnStatusChanged
OnStatusTicked
OnEnemyUnitIntentChanged
OnEnemyPhaseChanged

状态控件

状态 UI 应读取完整的当前状态映射，而不是只用事件 payload 里的值，用 StatusChangedEventArgs.UnitId 定位是哪个单位变了，然后重新读取它身上的全部状态

void RefreshStatusList(UnitState unit)
{
    foreach (var pair in GCSApi.StatusesOn(unit))
    {
        var status = pair.Key;
        var stacks = pair.Value;
        RenderStatus(status.Icon, status.DisplayName, stacks, status.ShowStackCount, status.IsDebuff);
    }
}

敌人意图

意图 UI 可以只显示当前顶部意图，也可以显示完整的待执行列表

void RenderIntent(UnitState enemy)
{
    var tag = GCSApi.CurrentIntentTag(enemy);
    var value = GCSApi.CurrentIntentValue(enemy);
    var pending = GCSApi.PendingIntents(enemy);
    RenderIntentIcons(tag, value, pending);
}

提示

请在 OnEnemyUnitIntentChanged 触发时刷新，敌人阶段变化后也要刷新

选择 UI

Choice 节点要求玩家选择卡牌、单位或状态时，GCS 触发 OnEffectChoiceOffered

Payload 字段	用途
`PromptText`	选择面板的标题文案
`Candidates`	要渲染的选项
`AllowSkip`	是否显示跳过按钮

选择面板需要实现 IChoicePresenter，打开选择时，运行时会传入提示文本、候选项、minPicks、maxPicks、onPicked 与 onSkipped，面板根据选择数量限制启用或禁用确认按钮，并通过对应回调返回原始候选对象，场景中没有 IChoicePresenter 或候选列表为空时，Choice 节点会按跳过处理，玩家选定后 GCS 会先保存选择结果，再通过 OnEffectChoiceSelected 提供全部已选索引与候选对象，显式或自动跳过都会触发 OnEffectChoiceSkipped

提示

GCSApi.IsWaitingForChoice 为 true 期间，应禁用普通卡牌按钮

奖励 UI

战斗胜利后，GCS 可能触发 OnBattleRewardOffered

private void ShowReward(BattleRewardOfferedEventArgs args)
{
    foreach (var card in args.CardCandidates)
    {
        RenderRewardCard(card);
    }
}

public void PickReward(GameCard card)
{
    GCSApi.ApplyReward(RewardChoice.Card, card);
}

public void SkipReward()
{
    GCSApi.SkipReward();
}

RewardChoice 还有 Energy 和 Cost 两个选项，选它们时卡牌参数传 null，应用或跳过都会结算奖励环节并触发 OnBattleEnded，用 GCSApi.IsWaitingForReward 判断奖励控件是否应该可见

飘字与表现层

自定义飘字订阅 FloatingTextSystem.Requested，处理函数会收到一个 FloatingTextRequest

void OnEnable()
{
    FloatingTextSystem.Requested += ShowFloatingText;
}

void OnDisable()
{
    FloatingTextSystem.Requested -= ShowFloatingText;
}

内置 UnitView 会按 UnitId 注册自身，使 FlowGraph 表现节点能够找到目标视图，自定义单位视觉则把自己的 View Model 绑定到事件 Payload 中的 Unit ID，Demo 的 HandController、CardView 和奖励 UI 类只服务于示例场景，正式项目应绑定稳定的运行时事件与 ID

刷新策略

策略	适用场景
完整重建	手牌、奖励选项、小型状态列表
按 ID 局部更新	单位面板、意图控件、飘字目标
防抖刷新	大型自定义战斗日志或分析面板
立即动画加刷新	伤害、治疗、护甲和卡牌移动

可见战斗 UI 通常可以直接从 GCSApi 完整刷新，只有性能分析确认这里形成实际瓶颈后，再改为局部更新或防抖

常见错误

错误	更好的做法
保留一份本地手牌副本并手动修改	在卡牌事件后从 `GCSApi.Hand()` 重建
只根据能量启用卡牌按钮	使用 `GCSApi.CanPlayCard(card)`
忘记取消订阅	保存并释放 `IDisposable` 句柄
把事件 Payload 当成完整状态	用 Payload 定位变化对象，再读取当前状态
正式 UI 依赖 Demo UI 类	依赖 `GCSApi`、事件和项目自己的 View 类
因为 VFX 或 SFX 资源缺失而阻塞玩法	让玩法正常结算，缺少资源时跳过对应表现

接入检查清单​

订阅生命周期​

战斗 HUD​

手牌 UI​

绑定卡牌 Description 与 Tooltip​

单位面板​

状态控件​

敌人意图​

选择 UI​

奖励 UI​

飘字与表现层​

刷新策略​

常见错误​