GameUI.ConversationSystem

Conversation 仅客户端

命名空间 GameUI.ConversationSystem

public abstract class Conversation : IExecutableObject, IExecutionContext, IGameObject, IGameObject<GameDataConversation>, IEventSender

对话的运行时实例（仅客户端），管理对话行、选项和分支跳转。 由 GameDataConversation 配置驱动。

构造函数

Conversation 仅客户端

protected Conversation(IGameLink<GameDataConversation> link, IExecutionContext creationContext)

属性

Link 仅客户端

public IGameLink<GameDataConversation> Link { get; }

Cache 仅客户端

public GameDataConversation Cache { get; }

Parent 仅客户端

public IExecutableObject? Parent { get; }

Shared 仅客户端

public ConversationParamShared Shared { get; }

获取对话专用的共享参数（包含对话历史）

备注

提供对 ConversationParamShared 的类型安全访问。 所有对话节点共享同一个实例（根对话创建，子对话继承）。

Source 仅客户端

public ITarget Source { get; }

AggregatorWeakReference 仅客户端

public WeakReference<EventAggregator> AggregatorWeakReference { get; }

方法

StartAsync 仅客户端

public Task<CmdResult> StartAsync()

Execute 仅客户端

public abstract Task Execute()

Publish 仅客户端

public virtual void Publish<TEvent>(TEvent eventToPublish)

GetPublisher 仅客户端

public Action<TEvent>? GetPublisher<TEvent>()

ConversationChoiceGroup 仅客户端

命名空间 GameUI.ConversationSystem

public class ConversationChoiceGroup : Conversation, IGameObject<GameDataConversationChoiceGroup>, IGameObject

构造函数

ConversationChoiceGroup 仅客户端

protected internal ConversationChoiceGroup(IGameLink<GameDataConversationChoiceGroup> link, IExecutionContext creationContext)

属性

Link 仅客户端

public new IGameLink<GameDataConversationChoiceGroup> Link { get; }

Cache 仅客户端

public new GameDataConversationChoiceGroup Cache { get; }

方法

Execute 仅客户端

public override Task Execute()

ConversationChoiceHistoryEntry 仅客户端

命名空间 GameUI.ConversationSystem

public class ConversationChoiceHistoryEntry : ConversationHistoryEntry

选择历史记录

备注

记录对话中的选择事件，包括所有可用选项和玩家的选择。

构造函数

ConversationChoiceHistoryEntry 仅客户端

public ConversationChoiceHistoryEntry()

属性

PromptInfo 仅客户端

public ConversationChoicePromptInfo? PromptInfo { get; init; }

提示信息（如果有）

备注

选择组显示的提示内容（角色、文本等）。 可能为 null，表示没有提示，仅显示选项列表。

AllChoices 仅客户端

public required List<ConversationChoiceInfo> AllChoices { get; init; }

所有可用的选项

备注

包含所有显示给玩家的选项，包括禁用的选项。 可用于回顾玩家在该时刻的所有可能选择。

SelectedIndex 仅客户端

public required int SelectedIndex { get; init; }

玩家选择的选项索引（从0开始）

备注

指向 AllChoices 列表中的索引。 可用于回放玩家的选择路径。

SelectedChoiceText 仅客户端

public string SelectedChoiceText { get; }

玩家选择的选项文本（便捷访问）

ChoiceGroupReference 仅客户端

public WeakReference<ConversationChoiceGroup>? ChoiceGroupReference { get; init; }

选择组运行时对象的弱引用（可选）

备注

使用 WeakReference1` 以避免阻止垃圾回收。 仅用于实时访问，不应该用于持久化存储。

ConversationChoiceInfo 仅客户端

命名空间 GameUI.ConversationSystem

public class ConversationChoiceInfo

选择项信息

构造函数

ConversationChoiceInfo 仅客户端

public ConversationChoiceInfo()

属性

Text 仅客户端

public required string Text { get; set; }

选择项文本

IsEnabled 仅客户端

public bool IsEnabled { get; set; }

是否可用（不可用的选择项应该显示为灰色或者不显示）

ConversationChoicePromptInfo 仅客户端

命名空间 GameUI.ConversationSystem

public class ConversationChoicePromptInfo

选择组的提示信息

备注

用于在显示选项之前，给玩家提供上下文信息。 所有字段都是可选的，如果都为 null，则不显示提示内容。

构造函数

ConversationChoicePromptInfo 仅客户端

public ConversationChoicePromptInfo()

属性

PromptText 仅客户端

public string? PromptText { get; set; }

提示文本

CharacterName 仅客户端

public string? CharacterName { get; set; }

提示角色名称

Portrait 仅客户端

public Texture? Portrait { get; set; }

提示角色立绘

PortraitSide 仅客户端

public PortraitSide PortraitSide { get; set; }

立绘显示位置

DisplayMode 仅客户端

public ConversationDisplayMode DisplayMode { get; set; }

显示模式，控制提示内容在哪里显示

ConversationCustomAction 仅客户端

命名空间 GameUI.ConversationSystem

public class ConversationCustomAction : Conversation, IGameObject<GameDataConversationCustomAction>, IGameObject

构造函数

ConversationCustomAction 仅客户端

protected internal ConversationCustomAction(IGameLink<GameDataConversationCustomAction> link, IExecutionContext creationContext)

属性

Link 仅客户端

public new IGameLink<GameDataConversationCustomAction> Link { get; }

Cache 仅客户端

public new GameDataConversationCustomAction Cache { get; }

方法

Execute 仅客户端

public override Task Execute()

ConversationDurationEstimator 仅客户端

命名空间 GameUI.ConversationSystem

public static class ConversationDurationEstimator

对话持续时间估算器 根据文本内容（字符数、标点符号）估算合理的显示时间

方法

Estimate 仅客户端

public static TimeSpan Estimate(string text)

根据文本内容估算合理的持续时间

• text — 对话文本

返回： 估算的持续时间

EstimateWithStats 仅客户端

public static TimeSpan EstimateWithStats(string text, out int charCount, out int punctuationCount, out double totalPauseMs)

估算持续时间并输出详细统计信息（用于调试）

• text — 对话文本
• charCount — 输出：字符数
• punctuationCount — 输出：标点符号数
• totalPauseMs — 输出：总停顿时间

返回： 估算的持续时间

ConversationExtensions 仅客户端

命名空间 GameUI.ConversationSystem

public static class ConversationExtensions

方法

StartConversation 仅客户端

public static Task<CmdResult> StartConversation(this GameDataConversation data, IExecutionContext? context = null)

ConversationHistoryEntry 仅客户端

命名空间 GameUI.ConversationSystem

public abstract class ConversationHistoryEntry

对话历史记录条目基类

备注

使用多态设计，支持不同类型的历史记录（台词、选择等）。

构造函数

ConversationHistoryEntry 仅客户端

protected ConversationHistoryEntry()

属性

Timestamp 仅客户端

public DateTime Timestamp { get; init; }

记录的时间戳

ConversationHistoryExtensions 仅客户端

命名空间 GameUI.ConversationSystem

public static class ConversationHistoryExtensions

对话历史扩展方法

方法

GetLines 仅客户端

public static IEnumerable<ConversationLineHistoryEntry> GetLines(this List<ConversationHistoryEntry> history)

获取所有台词历史记录

• history — 历史记录列表

返回： 所有台词历史记录的枚举

GetChoices 仅客户端

public static IEnumerable<ConversationChoiceHistoryEntry> GetChoices(this List<ConversationHistoryEntry> history)

获取所有选择历史记录

• history — 历史记录列表

返回： 所有选择历史记录的枚举

GetLinesByCharacter 仅客户端

public static IEnumerable<ConversationLineHistoryEntry> GetLinesByCharacter(this List<ConversationHistoryEntry> history, string characterName)

获取特定角色的台词

• history — 历史记录列表
• characterName — 角色名称

返回： 该角色的所有台词历史记录

GetHistoryInTimeRange 仅客户端

public static IEnumerable<ConversationHistoryEntry> GetHistoryInTimeRange(this List<ConversationHistoryEntry> history, DateTime startTime, DateTime endTime)

获取指定时间范围内的历史记录

• history — 历史记录列表
• startTime — 起始时间
• endTime — 结束时间

返回： 时间范围内的历史记录

ConversationLine 仅客户端

命名空间 GameUI.ConversationSystem

public class ConversationLine : Conversation, IGameObject<GameDataConversationLine>, IGameObject

构造函数

ConversationLine 仅客户端

protected internal ConversationLine(IGameLink<GameDataConversationLine> link, IExecutionContext creationContext)

属性

Link 仅客户端

public new IGameLink<GameDataConversationLine> Link { get; }

Cache 仅客户端

public new GameDataConversationLine Cache { get; }

方法

Execute 仅客户端

public override Task Execute()

ConversationLineHistoryEntry 仅客户端

命名空间 GameUI.ConversationSystem

public class ConversationLineHistoryEntry : ConversationHistoryEntry

台词历史记录

备注

记录对话中显示的每一句台词的信息。

构造函数

ConversationLineHistoryEntry 仅客户端

public ConversationLineHistoryEntry()

属性

LineInfo 仅客户端

public required ConversationLineInfo LineInfo { get; init; }

台词显示信息

备注

包含了台词的所有显示数据（文本、角色、立绘等）。 可以安全地用于持久化存储和回放。

LineReference 仅客户端

public WeakReference<ConversationLine>? LineReference { get; init; }

台词运行时对象的弱引用（可选）

备注

使用 WeakReference1以避免阻止垃圾回收。 对话结束后，运行时对象可能被回收，此引用可能失效。 ⚠️ 注意： 此引用仅用于实时访问运行时数据， 不应该用于持久化存储。持久化应该只使用LineInfo`。

ConversationLineInfo 仅客户端

命名空间 GameUI.ConversationSystem

public class ConversationLineInfo

台词显示信息

构造函数

ConversationLineInfo 仅客户端

public ConversationLineInfo()

属性

Text 仅客户端

public required string Text { get; set; }

台词文本

CharacterName 仅客户端

public string? CharacterName { get; set; }

角色名称

Portrait 仅客户端

public Texture? Portrait { get; set; }

角色立绘

PortraitSide 仅客户端

public PortraitSide PortraitSide { get; set; }

立绘显示位置

Duration 仅客户端

public TimeSpan? Duration { get; set; }

显示持续时间（null表示一直显示直到确认）

WaitForConfirmation 仅客户端

public bool WaitForConfirmation { get; set; }

是否需要等待玩家确认

AllowSkip 仅客户端

public bool AllowSkip { get; set; }

是否允许跳过

DisplayMode 仅客户端

public ConversationDisplayMode DisplayMode { get; set; }

显示模式，控制对话内容在哪里显示

ConversationParamShared 仅客户端

命名空间 GameUI.ConversationSystem

public class ConversationParamShared : ExecutionParamShared

对话系统的共享参数，扩展了 ExecutionParamShared 以支持对话日志

备注

在整个对话树中共享，所有对话节点都能访问同一个历史记录列表。 根对话创建新实例，子对话继承父对话的实例。

构造函数

ConversationParamShared 仅客户端

public ConversationParamShared(IExecutionContext creationContext)

属性

ConversationHistory 仅客户端

public List<ConversationHistoryEntry> ConversationHistory { get; }

对话历史记录列表

备注

记录了整个对话流程中的所有台词和选择，按时间顺序排列。 UI层可以使用此列表实现对话历史回顾功能。

MaxHistoryEntries 仅客户端

public int MaxHistoryEntries { get; set; }

最大历史记录数量，超过后自动删除最旧的记录

备注

默认值为 100。设置为 0 表示不限制数量。

方法

AddHistory 仅客户端

public void AddHistory(ConversationHistoryEntry entry)

添加历史记录（自动管理容量）

• entry — 要添加的历史记录条目

ClearHistory 仅客户端

public void ClearHistory()

清除所有历史记录

ConversationSet 仅客户端

命名空间 GameUI.ConversationSystem

public class ConversationSet : Conversation, IGameObject<GameDataConversationSet>, IGameObject

构造函数

ConversationSet 仅客户端

protected internal ConversationSet(IGameLink<GameDataConversationSet> link, IExecutionContext creationContext)

属性

Link 仅客户端

public new IGameLink<GameDataConversationSet> Link { get; }

Cache 仅客户端

public new GameDataConversationSet Cache { get; }

方法

Execute 仅客户端

public override Task Execute()

ConversationUI 仅客户端

命名空间 GameUI.ConversationSystem

public static class ConversationUI

对话UI管理器，用于注册和获取当前的对话UI实现

属性

Current 仅客户端

public static IConversationUI? Current { get; }

当前的对话UI实现

方法

Register 仅客户端

public static void Register(IConversationUI ui)

注册对话UI实现

Unregister 仅客户端

public static void Unregister()

注销对话UI实现

ConversationWait 仅客户端

命名空间 GameUI.ConversationSystem

public class ConversationWait : Conversation, IGameObject<GameDataConversationWait>, IGameObject

构造函数

ConversationWait 仅客户端

protected internal ConversationWait(IGameLink<GameDataConversationWait> link, IExecutionContext creationContext)

属性

Link 仅客户端

public new IGameLink<GameDataConversationWait> Link { get; }

Cache 仅客户端

public new GameDataConversationWait Cache { get; }

方法

Execute 仅客户端

public override Task Execute()

IConversationUI 仅客户端

命名空间 GameUI.ConversationSystem

public interface IConversationUI

对话UI接口，用于在客户端显示对话内容

备注

游戏需要实现此接口来提供具体的UI表现。对话系统会通过此接口与UI层交互， 将对话内容显示给玩家。 实现要点： 所有异步方法都应该是可取消的（响应 CancellationToken） ShowLineAsync 在等待确认时应该阻塞，直到玩家点击继续或被取消 ShowChoicesAsync 应该等待玩家选择，并返回选择的索引 实现应该处理超时和取消的情况 注册方式： // 在游戏初始化时注册UI实现 ConversationUI.Register(new MyConversationUI());

方法

ShowLineAsync 仅客户端

Task ShowLineAsync(ConversationLineInfo lineInfo, ConversationLine? line, CancellationToken cancellationToken = default(CancellationToken))

显示一条台词，并等待显示完成或玩家确认

• lineInfo — 台词信息，包含文本、角色、显示时间等
• line — 台词运行时对象（可选），提供访问执行上下文和运行时数据的能力
• cancellationToken — 取消令牌，用于支持自动持续时间和超时

返回： 等待台词显示完成或玩家确认

备注

此方法的行为取决于 的WaitForConfirmation属性： 如果需要等待确认：方法应该阻塞直到玩家点击继续或被取消 如果不需要等待确认：方法应该在指定的持续时间后自动完成 当 被触发时，方法应该抛出OperationCanceledException。 参数提供了对话运行时对象，可用于： 访问执行上下文（IExecutionContext） 获取运行时计算的数据 访问角色绑定的实际游戏单位 ⚠️ 注意： UI层应该只读取数据，不应该修改对话状态或调用改变游戏状态的方法。

ShowChoicesAsync 仅客户端

Task<int> ShowChoicesAsync(List<ConversationChoiceInfo> choices, ConversationChoicePromptInfo? promptInfo, ConversationChoiceGroup? choiceGroup, CancellationToken cancellationToken = default(CancellationToken))

显示选择组，并等待玩家做出选择

• choices — 选择项列表，包含文本和是否可用等信息
• promptInfo — 提示信息（可选），用于在选项上方显示上下文
• choiceGroup — 选择组运行时对象（可选），提供访问执行上下文和运行时数据的能力
• cancellationToken — 取消令牌，用于支持超时机制

返回： 玩家选择的选项索引（从0开始）

备注

此方法应该： 如果 不为空且有内容，先显示提示信息（角色、文本等） 显示所有选择项，不可用的选项应显示为灰色或禁用 等待玩家点击某个选项 返回被选中选项的索引（从0开始） 如果设置了超时（通过 ），当超时时应该抛出OperationCanceledException， 对话系统会根据超时默认选项自动选择。 参数提供了选择组运行时对象，可用于： 访问执行上下文（IExecutionContext） 获取运行时计算的数据 访问选择项的详细配置数据 访问角色绑定的实际游戏单位 ⚠️ 注意： UI层应该只读取数据，不应该修改对话状态或调用改变游戏状态的方法。

Hide 仅客户端

void Hide()

隐藏对话UI

备注

在对话完成时调用，UI应该隐藏对话界面但保留当前显示的内容（可能用于淡出动画）。 调用此方法后可能会立即调用 Clear 来清除内容。

Clear 仅客户端

void Clear()

清除当前显示的内容

备注

清除所有对话相关的显示内容（文本、角色立绘、选项等），为下一次对话做准备。

GameDataCharacter 仅客户端

命名空间 GameUI.ConversationSystem.Data

public class GameDataCharacter : GameDataCategory<GameDataCharacter>, IGameDataCategory<GameDataCharacter>, IGameData<GameDataCharacter>, IGameData

对话角色数据，用于定义纯立绘角色或为实际单位提供额外的显示信息

构造函数

GameDataCharacter 仅客户端

public GameDataCharacter(GameLink<GameDataCharacter, GameDataCharacter> link)

GameDataCharacter 仅客户端

public GameDataCharacter(IGameLink<GameDataCharacter> link)

属性

DisplayName 仅客户端

public LocalizedString? DisplayName { get; set; }

角色显示名称

Portrait 仅客户端

public Texture? Portrait { get; set; }

角色立绘（头像或半身像）

NameColorOverride 仅客户端

public Color? NameColorOverride { get; set; }

角色名字颜色，用于在对话UI中区分不同角色 为空时使用默认颜色

Description 仅客户端

public LocalizedString? Description { get; set; }

角色描述（可选）

InGameUnit 仅客户端

public Unit? InGameUnit { get; set; }

游戏中的实际单位，如果对话设置为显示在单位上方，则需要在运行时动态设置此值

GameDataConversation 仅客户端

命名空间 GameUI.ConversationSystem.Data

public abstract class GameDataConversation : GameDataCategory<GameDataConversation>, IExecutableData, IGameData, IEventSender, IGameDataCategory<GameDataConversation>, IGameData<GameDataConversation>

对话数据基类，所有对话相关的数据类型（台词、选择、对话集合等）都继承自此类

备注

对话系统是一个客户端驱动的系统，用于创建和管理游戏中的对话内容。 支持以下功能： 单句台词显示（GameDataConversationLine） 玩家选择分支（GameDataConversationChoiceGroup） 对话集合和序列（GameDataConversationSet） 等待和延迟（GameDataConversationWait） 自定义动作（GameDataConversationCustomAction）

构造函数

GameDataConversation 仅客户端

public GameDataConversation(GameLink<GameDataConversation, GameDataConversation> link)

GameDataConversation 仅客户端

public GameDataConversation(IGameLink<GameDataConversation> link)

属性

Validators 仅客户端

public Validator? Validators { get; set; }

对话的验证器，只有满足验证器条件的对话内容才能显示

备注

验证器通常用于： 检查玩家是否满足显示条件（如任务进度、物品持有等） 控制选项的可用性（不满足条件的选项会显示为灰色或隐藏） 动态控制对话内容的显示

AggregatorWeakReference 仅客户端

public WeakReference<EventAggregator> AggregatorWeakReference { get; }

方法

Execute 仅客户端

public void Execute(IExecutableObject context)

Validate 仅客户端

public CmdResult Validate(IExecutableObject context)

CreateConversation 仅客户端

public Conversation? CreateConversation(IExecutionContext? context = null)

CreateConversationInternal 仅客户端

protected abstract Conversation? CreateConversationInternal(IExecutionContext context)

Publish 仅客户端

public void Publish<TEvent>(TEvent eventToPublish)

GetPublisher 仅客户端

public Action<TEvent>? GetPublisher<TEvent>()

GameDataConversationChoiceGroup 仅客户端

命名空间 GameUI.ConversationSystem.Data

public class GameDataConversationChoiceGroup : GameDataConversation, IGameData<GameDataConversationChoiceGroup>, IGameData

对话选择组数据，表示一组供玩家选择的选项

备注

用于创建分支对话，让玩家做出选择并导向不同的对话路径。 支持超时机制和默认选择，适用于限时决策场景（如战斗选择）。 示例： var choiceGroup = new GameDataConversationChoiceGroup { Choices = new List<IGameLink<GameDataConversationChoiceItem>?> { acceptChoice.ToLink(), declineChoice.ToLink() }, Timeout = TimeSpan.FromSeconds(30), DefaultChoiceOnTimeout = 1 // 超时默认选择"拒绝" };

构造函数

GameDataConversationChoiceGroup 仅客户端

public GameDataConversationChoiceGroup(GameLink<GameDataConversation, GameDataConversationChoiceGroup> link)

GameDataConversationChoiceGroup 仅客户端

public GameDataConversationChoiceGroup(IGameLink<GameDataConversationChoiceGroup> link)

属性

Choices 仅客户端

public List<IGameLink<GameDataConversationChoiceItem>?> Choices { get; set; }

选择项列表

备注

每个选择项可以有自己的验证器、服务器效果和后续对话。 不满足验证器条件的选项会显示为灰色或隐藏。

Timeout 仅客户端

public TimeSpan? Timeout { get; set; }

选择超时时间，为空时不限制

备注

超时使用游戏时间（受暂停和时间缩放影响），而非实际时间。 超时后会根据 DefaultChoiceOnTimeout 自动选择或中断对话。

DefaultChoiceOnTimeout 仅客户端

public int? DefaultChoiceOnTimeout { get; set; }

超时后的默认选择索引，为空时超时后不自动选择

备注

索引从0开始。如果设置的索引超出范围，会记录警告并中断对话。

PromptText 仅客户端

public LocalizedString? PromptText { get; set; }

选择组的提示文本（可选）

备注

显示在选项上方，用于给玩家提供上下文信息。 如果为空，则不显示额外文本，仅显示选项列表。 常用场景： 重复上一句对话，确保玩家能看到问题 提供简短的选择提示（如"你想购买什么？"） 显示当前状态或情境描述

PromptCharacter 仅客户端

public IGameLink<GameDataCharacter>? PromptCharacter { get; set; }

提示文本的说话角色（可选）

备注

为空时表示旁白或系统消息。 设置角色后，会显示角色的名称、立绘等信息。

PromptPortraitSide 仅客户端

public PortraitSide PromptPortraitSide { get; set; }

提示文本的立绘显示位置

备注

仅在 PromptCharacter 不为空时有效。

PromptVoice 仅客户端

public IGameLink<GameDataActorSound>? PromptVoice { get; set; }

提示语音，为空时不播放语音

备注

仅在 PromptText 不为空时有效。 可以为提示文本添加语音，增强表现力。

PromptTextParameters 仅客户端

public List<Func<IExecutionContext, object>>? PromptTextParameters { get; set; }

提示文本的参数，用于替换提示文本中的占位符

备注

仅在 PromptText 不为空时有效。 例如："你有 {0} 金币，想购买什么？" 可以动态替换玩家金币数量。

Camera 仅客户端

public IGameLink<GameDataCamera>? Camera { get; set; }

镜头设置，为空时不改变镜头

备注

显示选择组时切换到指定镜头。 选择完成后，镜头会在对话结束时重置。

CameraFollowCharacter 仅客户端

public bool CameraFollowCharacter { get; set; }

镜头是否跟随提示角色

备注

仅在 PromptCharacter 不为空且角色绑定了实际单位时有效。 镜头会跟随角色单位移动。

PromptSpeakerAnimation 仅客户端

public IGameLink<GameDataAnimation>? PromptSpeakerAnimation { get; set; }

提示角色说话时的动画，只有当角色绑定了实际单位时才有效

备注

仅在 PromptCharacter 不为空且角色绑定了实际单位时有效。 可以让角色在显示提示时播放特定动画（如思考、询问等）。

DisplayMode 仅客户端

public ConversationDisplayMode DisplayMode { get; set; }

选择组的显示模式

备注

控制选择组及其提示内容的显示位置。 目前支持的模式： UI：在对话UI中显示（默认） OnUnit：在单位上方显示（需要角色绑定了实际单位）

Link 仅客户端

public new IGameLink<GameDataConversationChoiceGroup> Link { get; }

方法

CreateConversationInternal 仅客户端

protected override Conversation? CreateConversationInternal(IExecutionContext context)

GameDataConversationChoiceItem 仅客户端

命名空间 GameUI.ConversationSystem.Data

public class GameDataConversationChoiceItem : GameDataCategory<GameDataConversationChoiceItem>, IEventSender, IGameDataCategory<GameDataConversationChoiceItem>, IGameData<GameDataConversationChoiceItem>, IGameData

对话选择项数据，表示选择组中的一个选项

备注

选择项是玩家可以选择的选项，可以包含验证器、后续对话、服务器端效果等。 支持两种方式在服务器端执行逻辑： ServerEffect：自动在服务器端执行效果，安全可靠（推荐） 监听 EventPlayerConversationChoiceSelected 事件：灵活的自定义逻辑 示例 - 使用 ServerEffect： var rewardEffect = new GameDataEffectSet { Effects = new List<IGameLink<GameDataEffect>?> { giveGoldEffect.ToLink(), giveExpEffect.ToLink() } }; var choice = new GameDataConversationChoiceItem { Text = new LocalizedString("领取奖励", "Claim Reward"), ServerEffect = rewardEffect.ToLink(), // 服务器端自动执行 Validators = ctx => HasCompletedQuest(ctx), NextConversation = thankYouDialog.ToLink() };

构造函数

GameDataConversationChoiceItem 仅客户端

public GameDataConversationChoiceItem(GameLink<GameDataConversationChoiceItem, GameDataConversationChoiceItem> link)

GameDataConversationChoiceItem 仅客户端

public GameDataConversationChoiceItem(IGameLink<GameDataConversationChoiceItem> link)

属性

Validators 仅客户端

public Validator? Validators { get; set; }

选项的验证器，只有满足验证器条件的选项才能被选择

备注

不满足条件的选项会显示为灰色（IsEnabled = false）或完全隐藏，具体表现由UI实现决定。 常用于检查玩家是否有足够的资源、是否完成了前置任务等。

Text 仅客户端

public LocalizedString? Text { get; set; }

选项的显示文本，支持多语言

NextConversation 仅客户端

public IGameLink<GameDataConversation>? NextConversation { get; set; }

选择此选项后要执行的后续对话

备注

可以链接到任何类型的对话节点（台词、选择组、对话集合等）。 为空时选择后直接结束对话。

ServerEffect 仅客户端

public IGameLink<GameDataEffect>? ServerEffect { get; set; }

当玩家选择此选项时，服务器会自动执行的效果

备注

工作原理： 效果在服务器端执行，客户端无法伪造，安全可靠 施法者和目标自动设置为本地玩家的主控单位 如果玩家没有主控单位，则不执行 设置此属性会自动通知服务器（无需手动设置 NotifyServer） 执行顺序： ServerEffect 优先于 EventPlayerConversationChoiceSelected 事件执行 适用场景： 给予玩家奖励（金币、经验、物品等） 改变玩家状态（属性、Buff、任务进度等） 触发游戏事件

NotifyServer 仅客户端

public bool NotifyServer { get; set; }

是否将选择事件通知给服务器，使服务器可以捕捉到 EventPlayerConversationChoiceSelected 事件

备注

如果设置了 ServerEffect，则必定会通知服务器（无论此属性的值如何）。 当需要在服务器端执行复杂的自定义逻辑时，设置此属性为 true 并在服务器端监听事件。

Icon 仅客户端

public Icon? Icon { get; set; }

选项的图标

备注

选项的图标，可以用于显示在对话UI中。 如果为空，则使用默认图标。

AggregatorWeakReference 仅客户端

public WeakReference<EventAggregator> AggregatorWeakReference { get; }

方法

Publish 仅客户端

public virtual void Publish<TEvent>(TEvent eventToPublish)

GetPublisher 仅客户端

public Action<TEvent>? GetPublisher<TEvent>()

GameDataConversationCustomAction 仅客户端

命名空间 GameUI.ConversationSystem.Data

public class GameDataConversationCustomAction : GameDataConversation, IGameData<GameDataConversationCustomAction>, IGameData

对话自定义动作节点，用于在对话中执行任意自定义逻辑

备注

自定义动作允许你在对话流程中插入任意代码逻辑，例如： 播放特效或音乐 触发游戏事件 修改游戏状态 执行复杂的条件判断 与其他系统交互 示例： var customAction = new GameDataConversationCustomAction { Func = async (ctx) => { // 播放特效 await PlayDramaticEffect(); // 检查条件 if (CheckCondition(ctx)) { return true; // 继续后续对话 } return false; // 中断对话 }, NextConversation = nextDialog.ToLink() };

构造函数

GameDataConversationCustomAction 仅客户端

public GameDataConversationCustomAction(GameLink<GameDataConversation, GameDataConversationCustomAction> link)

GameDataConversationCustomAction 仅客户端

public GameDataConversationCustomAction(IGameLink<GameDataConversationCustomAction> link)

属性

Func 仅客户端

public Func<IExecutionContext, ValueTask<bool>> Func { get; set; }

自定义动作函数，返回 true 表示继续后续对话，返回 false 表示中断对话

备注

函数参数为当前执行上下文（即当前对话自定义动作节点的实例 ConversationCustomAction）。 函数应该是异步的，以支持异步操作（如播放动画、等待事件等）。

NextConversation 仅客户端

public IGameLink<GameDataConversation>? NextConversation { get; set; }

后续对话，只有在自定义动作返回 true 后才会执行

备注

为空时，动作执行完成后对话结束。

Link 仅客户端

public new IGameLink<GameDataConversationCustomAction> Link { get; }

方法

CreateConversationInternal 仅客户端

protected override Conversation? CreateConversationInternal(IExecutionContext context)

GameDataConversationLine 仅客户端

命名空间 GameUI.ConversationSystem.Data

public class GameDataConversationLine : GameDataConversation, IGameData<GameDataConversationLine>, IGameData

对话台词数据，表示对话中的一句话

备注

对话台词是对话系统的基本单元，用于显示角色说话的内容。 可以包含角色信息、文本、语音、动画、镜头等元素。 示例： var line = new GameDataConversationLine { Character = npcCharacter.ToLink(), Text = new LocalizedString("你好，勇者！", "Hello, hero!"), WaitForConfirmation = true, AllowSkip = true }; await line.StartConversation();

构造函数

GameDataConversationLine 仅客户端

public GameDataConversationLine(GameLink<GameDataConversation, GameDataConversationLine> link)

GameDataConversationLine 仅客户端

public GameDataConversationLine(IGameLink<GameDataConversationLine> link)

属性

Character 仅客户端

public IGameLink<GameDataCharacter>? Character { get; set; }

说话的角色

备注

为空时表示旁白或系统消息。 角色数据包含名称、立绘、颜色等显示信息。

Text 仅客户端

public LocalizedString? Text { get; set; }

台词文本内容，支持多语言

备注

可以使用 TextParameters 来动态替换文本中的占位符。 例如："你好，{0}！你已经完成了 {1} 个任务。"

Voice 仅客户端

public IGameLink<GameDataActorSound>? Voice { get; set; }

语音，为空时不播放语音 TODO: 支持多语言语音 TODO: 支持获取语音时长，需要等引擎支持

TextParameters 仅客户端

public List<Func<IExecutionContext, object>>? TextParameters { get; set; }

台词的参数，用于替换台词中的占位符

Camera 仅客户端

public IGameLink<GameDataCamera>? Camera { get; set; }

镜头，为空时不改变镜头 整个对话结束后，镜头会重置

CameraFollowCharacter 仅客户端

public bool CameraFollowCharacter { get; set; }

镜头是否跟随角色，只有当角色绑定了实际单位时才有效

SpeakerAnimation 仅客户端

public IGameLink<GameDataAnimation>? SpeakerAnimation { get; set; }

角色说话时的动画，只有当角色绑定了实际单位时才有效

Duration 仅客户端

public TimeSpan? Duration { get; set; }

台词的显示时间，为空时使用音效时间、动画时间或由台词长度决定

WaitForConfirmation 仅客户端

public bool WaitForConfirmation { get; set; }

是否需要等待确认，如果需要等待确认，则需要等待用户确认后才能继续执行

AllowSkip 仅客户端

public bool AllowSkip { get; set; }

是否允许跳过，如果允许跳过，则可以通过点击屏幕等方式跳过当前台词，直接执行下一条台词。 跳过的方式由具体的UI系统决定

PortraitSide 仅客户端

public PortraitSide PortraitSide { get; set; }

立绘的显示位置，位于对话UI的左侧或右侧

DisplayMode 仅客户端

public ConversationDisplayMode DisplayMode { get; set; }

台词的显示模式

备注

如果父级为ConversationSet，且父级的LineDisplayMode不为空，则由父级决定，会忽略本设置。 目前支持的模式： UI：在对话UI中显示 OnUnit：在单位上方显示（需要角色绑定了实际单位）

Link 仅客户端

public new IGameLink<GameDataConversationLine> Link { get; }

方法

CreateConversationInternal 仅客户端

protected override Conversation? CreateConversationInternal(IExecutionContext context)

GameDataConversationSet 仅客户端

命名空间 GameUI.ConversationSystem.Data

public class GameDataConversationSet : GameDataConversation, IGameData<GameDataConversationSet>, IGameData

对话集合数据，用于组织多个对话节点

备注

对话集合可以包含多个对话节点（台词、选择、等待、自定义动作等），并控制它们的执行顺序。 支持两种执行模式： 顺序执行（Sequential）：按顺序依次播放所有对话节点 随机一条（RandomOne）：随机选择并播放一个对话节点 示例 - 顺序对话： var conversation = new GameDataConversationSet { Lines = new List<IGameLink<GameDataConversation>?> { line1.ToLink(), choiceGroup.ToLink(), line2.ToLink() }, ExecutionMode = ConversationExecutionMode.Sequential }; 示例 - 随机闲聊： var randomChatter = new GameDataConversationSet { Lines = new List<IGameLink<GameDataConversation>?> { greeting1.ToLink(), greeting2.ToLink(), greeting3.ToLink() }, ExecutionMode = ConversationExecutionMode.RandomOne };

构造函数

GameDataConversationSet 仅客户端

public GameDataConversationSet(GameLink<GameDataConversation, GameDataConversationSet> link)

GameDataConversationSet 仅客户端

public GameDataConversationSet(IGameLink<GameDataConversationSet> link)

属性

Lines 仅客户端

public List<IGameLink<GameDataConversation>?>? Lines { get; set; }

对话节点列表

备注

可以包含任何类型的对话节点：台词、选择组、对话集合（支持嵌套）、等待、自定义动作等。

LineDisplayMode 仅客户端

public ConversationDisplayMode? LineDisplayMode { get; set; }

台词的显示模式

备注

为空时由对话节点自己决定。 目前支持的模式： UI：在对话UI中显示 OnUnit：在单位上方显示（需要角色绑定了实际单位）

ExecutionMode 仅客户端

public ConversationExecutionMode? ExecutionMode { get; set; }

对话的执行模式

备注

Sequential：按顺序依次播放所有对话节点 RandomOne：随机选择并播放一个对话节点（适合NPC闲聊）

Link 仅客户端

public new IGameLink<GameDataConversationSet> Link { get; }

方法

CreateConversationInternal 仅客户端

protected override Conversation? CreateConversationInternal(IExecutionContext context)

GameDataConversationWait 仅客户端

命名空间 GameUI.ConversationSystem.Data

public class GameDataConversationWait : GameDataConversation, IGameData<GameDataConversationWait>, IGameData

对话等待节点，用于在对话中插入延迟

备注

通常用于过场动画或自动播放的对话序列中，在台词之间添加停顿。 等待时间使用游戏时间（受暂停和时间缩放影响）。 示例： var conversation = new GameDataConversationSet { Lines = new List<IGameLink<GameDataConversation>?> { line1.ToLink(), new GameDataConversationWait { Duration = TimeSpan.FromSeconds(1) }.ToLink(), line2.ToLink() }, ExecutionMode = ConversationExecutionMode.Sequential };

构造函数

GameDataConversationWait 仅客户端

public GameDataConversationWait(GameLink<GameDataConversation, GameDataConversationWait> link)

GameDataConversationWait 仅客户端

public GameDataConversationWait(IGameLink<GameDataConversationWait> link)

属性

Duration 仅客户端

public TimeSpan Duration { get; set; }

等待持续时间

备注

使用游戏时间，会受到游戏暂停和时间缩放的影响。

Link 仅客户端

public new IGameLink<GameDataConversationWait> Link { get; }

方法

CreateConversationInternal 仅客户端

protected override Conversation? CreateConversationInternal(IExecutionContext context)

ConversationDisplayMode 仅客户端

命名空间 GameUI.ConversationSystem.Data.Enum

public enum ConversationDisplayMode

对话显示模式，控制对话内容在哪里显示

枚举值

• UI — 在对话UI中显示（默认模式）
• OnUnit — 在单位上方显示

ConversationExecutionMode 仅客户端

命名空间 GameUI.ConversationSystem.Data.Enum

public enum ConversationExecutionMode

对话执行模式，控制对话集合中的对话节点如何执行

枚举值

• Sequential — 顺序执行模式（默认）
• RandomOne — 随机选择一条执行

PortraitSide 仅客户端

命名空间 GameUI.ConversationSystem.Data.Enum

public enum PortraitSide

立绘在对话界面中的显示位置

枚举值

• Left — 显示在左侧
• Right — 显示在右侧

EventConversationChoiceSelected 仅客户端

命名空间 GameUI.ConversationSystem.Event

public class EventConversationChoiceSelected : ITriggerEvent<EventConversationChoiceSelected>

对话选择事件（客户端），当玩家在对话中做出选择时触发

• conversation — 对话实例
• choiceIndex — 选择项的索引（从0开始）
• choiceLink — 被选中的选择项

备注

此事件只在客户端触发，用于追踪玩家的对话选择或执行客户端特定的逻辑。 常见用途： 播放选择确认音效 更新客户端UI状态 记录玩家选择用于客户端统计 触发客户端动画或特效 示例： Game.Instance.Subscribe<EventConversationChoiceSelected>(e => { Game.Logger.LogInfo("玩家选择: {0} (索引 {1})", e.ChoiceLink.FriendlyName, e.ChoiceIndex); // 播放确认音效 PlayConfirmSound(); });

构造函数

EventConversationChoiceSelected 仅客户端

public EventConversationChoiceSelected(Conversation conversation, int choiceIndex, IGameLink<GameDataConversationChoiceItem> choiceLink)

对话选择事件（客户端），当玩家在对话中做出选择时触发

• conversation — 对话实例
• choiceIndex — 选择项的索引（从0开始）
• choiceLink — 被选中的选择项

备注

此事件只在客户端触发，用于追踪玩家的对话选择或执行客户端特定的逻辑。 常见用途： 播放选择确认音效 更新客户端UI状态 记录玩家选择用于客户端统计 触发客户端动画或特效 示例： Game.Instance.Subscribe<EventConversationChoiceSelected>(e => { Game.Logger.LogInfo("玩家选择: {0} (索引 {1})", e.ChoiceLink.FriendlyName, e.ChoiceIndex); // 播放确认音效 PlayConfirmSound(); });

属性

Conversation 仅客户端

public Conversation Conversation { get; }

对话实例

ChoiceIndex 仅客户端

public int ChoiceIndex { get; }

选择项的索引（从0开始）

ChoiceLink 仅客户端

public IGameLink<GameDataConversationChoiceItem> ChoiceLink { get; }

被选中的选择项

EventConversationCompleted 仅客户端

命名空间 GameUI.ConversationSystem.Event

public class EventConversationCompleted : ITriggerEvent<EventConversationCompleted>

对话完成事件，在客户端对话正常完成时触发

• conversation — 完成的对话实例

备注

此事件在对话执行完毕（或被取消）时触发。 常见用途： 恢复游戏或重新启用玩家输入 隐藏对话UI界面 停止对话相关的背景音乐 记录对话完成状态 触发后续游戏逻辑（如给予奖励、开始任务等） 示例： Game.Instance.Subscribe<EventConversationCompleted>(e => { Game.Logger.LogInfo("对话完成: {0}", e.Conversation.Cache.Link.FriendlyName); // 恢复游戏 Game.Resume(); // 隐藏对话UI HideConversationUI(); });

构造函数

EventConversationCompleted 仅客户端

public EventConversationCompleted(Conversation conversation)

对话完成事件，在客户端对话正常完成时触发

• conversation — 完成的对话实例

备注

此事件在对话执行完毕（或被取消）时触发。 常见用途： 恢复游戏或重新启用玩家输入 隐藏对话UI界面 停止对话相关的背景音乐 记录对话完成状态 触发后续游戏逻辑（如给予奖励、开始任务等） 示例： Game.Instance.Subscribe<EventConversationCompleted>(e => { Game.Logger.LogInfo("对话完成: {0}", e.Conversation.Cache.Link.FriendlyName); // 恢复游戏 Game.Resume(); // 隐藏对话UI HideConversationUI(); });

属性

Conversation 仅客户端

public Conversation Conversation { get; }

完成的对话实例

EventConversationStarted 仅客户端

命名空间 GameUI.ConversationSystem.Event

public class EventConversationStarted : ITriggerEvent<EventConversationStarted>

对话开始事件，在客户端对话开始时触发

• conversation — 开始的对话实例

备注

此事件在对话实例创建并开始执行时触发。 常见用途： 暂停游戏或禁用玩家输入 播放对话相关的背景音乐或音效 显示对话UI界面 记录对话统计或日志 示例： Game.Instance.Subscribe<EventConversationStarted>(e => { Game.Logger.LogInfo("对话开始: {0}", e.Conversation.Cache.Link.FriendlyName); // 暂停游戏 Game.Pause(); // 显示对话UI ShowConversationUI(); });

构造函数

EventConversationStarted 仅客户端

public EventConversationStarted(Conversation conversation)

对话开始事件，在客户端对话开始时触发

• conversation — 开始的对话实例

备注

此事件在对话实例创建并开始执行时触发。 常见用途： 暂停游戏或禁用玩家输入 播放对话相关的背景音乐或音效 显示对话UI界面 记录对话统计或日志 示例： Game.Instance.Subscribe<EventConversationStarted>(e => { Game.Logger.LogInfo("对话开始: {0}", e.Conversation.Cache.Link.FriendlyName); // 暂停游戏 Game.Pause(); // 显示对话UI ShowConversationUI(); });

属性

Conversation 仅客户端

public Conversation Conversation { get; }

开始的对话实例

ProtoConversationChoiceItem 仅客户端

命名空间 GameUI.ConversationSystem.Proto

public readonly struct ProtoConversationChoiceItem : IProtocolClientTransient<ProtoConversationChoiceItem>, IBytesReplicableUnmanaged<ProtoConversationChoiceItem>, IBytesReplicable<ProtoConversationChoiceItem>, IProtocolClientTransient, IGameClass, IEquatable<ProtoConversationChoiceItem>

构造函数

ProtoConversationChoiceItem 仅客户端

public ProtoConversationChoiceItem(IGameLink<GameDataConversationChoiceItem> choiceItem)

属性

ProtoChoiceItem 仅客户端

public ProtoIGameLink<GameDataConversationChoiceItem> ProtoChoiceItem { get; }

ChoiceItem 仅客户端

public IGameLink<GameDataConversationChoiceItem>? ChoiceItem { get; }

方法

ToString 仅客户端

public override string ToString()

operator != 仅客户端

public static bool operator !=(ProtoConversationChoiceItem left, ProtoConversationChoiceItem right)

operator == 仅客户端

public static bool operator ==(ProtoConversationChoiceItem left, ProtoConversationChoiceItem right)

GetHashCode 仅客户端

public override int GetHashCode()

Equals 仅客户端

public override bool Equals(object obj)

Equals 仅客户端

public bool Equals(ProtoConversationChoiceItem other)