用途
该技能解决虚幻引擎项目中把玩法数值(物品属性、敌人配置、平衡数值、掉落表、曲线等)硬编码在代码里、导致迭代慢且风险高的问题。它指导开发者把这些数据迁移到美术与设计师可在编辑器中直接修改的资产和配置对象中,无需重新编译,并按数据形态选择合适的容器。
主要能力
- DataTables:适合定义大量同结构记录(物品、敌人、武器、技能、掉落)。需要定义继承
FTableRowBase的行结构体并标注USTRUCT(BlueprintType),在 Content Browser 创建 DataTable 资产或导入 CSV/JSON。运行时通过FindRow<T>、GetAllRows<T>、ForeachRow<T>访问;FDataTableRowHandle提供表名+行名的双字段引用,让设计师在 Details 面板选择具体行,避免字符串拼写错误。 - UCompositeDataTable:堆叠父表,行名重复时高索引父表优先,用于 DLC 或按平台的覆盖而不复制基础表。
- DataAssets:
UDataAsset用于单个富配置对象,UPrimaryDataAsset增加GetPrimaryAssetId(),支持 UAssetManager 发现、异步加载和按 bundle 流送;引用实例可用TObjectPtr(立即加载)或TSoftObjectPtr(懒加载)。 - 曲线:
UCurveFloat(独立资产,GetFloatValue)、UCurveTable(一个资产内多条命名曲线)、FRuntimeFloatCurve(内嵌于结构体/组件,可在 Details 面板直接编辑)用于伤害衰减、经验曲线、摄像机缓动等随连续输入变化的数值。 - 配置驱动属性(.ini):通过
UCLASS(Config=Game, DefaultConfig)与UPROPERTY(Config)读写Config/DefaultGame.ini,适合随项目发布的全局默认值。 - UDeveloperSettings:自动出现在 Project Settings 面板,适合跨系统调参入口和数据资产引用;需在模块
Build.cs的PublicDependencyModuleNames中加入DeveloperSettings。 - 数据校验:在 DataAsset 和行结构体中重写
IsDataValid(编辑器内)以在运行前暴露内容错误;可从 Content Browser 的 Asset Actions → Validate Assets 执行,或用UnrealEditor-Cmd.exe MyProject.uproject -run=DataValidation在 CI 中运行。
使用方式
按需求选择容器:同结构多行批量表格用 UDataTable;跨 DLC/变体分层覆盖用 UCompositeDataTable;单个富配置对象(可子类化)用 UDataAsset/UPrimaryDataAsset;依赖连续输入的数值用曲线;.ini 全局设置用 Config 属性;需要 Project Settings 面板入口与变更通知用 UDeveloperSettings。文档中给出了行结构体、DataTable 查询、DataAsset、曲线、配置类与 DeveloperSettings 的代码示例。
适用场景
物品/敌人/武器/技能/掉落等数据集、Boss 配置或游戏模式调参等单条配置、伤害衰减与等级经验等曲线、可覆盖的按模式/DLC/平台数据层,以及全局平衡参数。
限制与注意事项
- .ini 配置不适合内容规模数据(数百条记录),且不在资产浏览器中可见,设计体验较差。
- 行内或在资产中使用对重型资产的硬引用会导致表格加载时全部加载,纹理、网格、声音和类引用应改用
TSoftObjectPtr。 FindRow拼写错误会静默返回空(带日志警告),应优先使用FDataTableRowHandle选择器。- 行结构体忘记
USTRUCT(BlueprintType)会导致蓝图节点无法暴露该类型;向 CSV 增加字段需在末尾添加并保持列顺序与表头匹配后重新导入。 UDeveloperSettings不显示通常是因为模块未加入PublicDependencyModuleNames,或CategoryName不是已知分类(Game、Engine、Editor)。GetDefault<T>()只读且在任何地方安全,GetMutableDefault<T>()仅用于编辑器工具或启动初始化,绝不可用于游戏运行时。- 版本相关:
UCompositeDataTable自 UE4 起稳定,运行时修改父表的 API 可能造成卡顿;UDeveloperSettings自 UE5 起为独立模块;FRuntimeFloatCurve::GetRichCurveConst()为 UE5 新增的 const 访问器;FTableRowBase::IsDataValid签名与 UE5.1 引入的UObject::IsDataValid(FDataValidationContext&)一致。