星火 2.0 开发文档

主题

UI 属性系统（UIProperty System） ​

允许客户端设置玩家级别的 UI 状态属性（面板折叠、快捷键配置等），通过 TypedMessage 同步到服务端持久化。

定义位置：TriggerEncapsulation.UIProperty

工作流程 ​

  1. 客户端调用 player.SetUIPropertyAsync(property, value)
  2. 发送 UIPropertySetRequest 到服务端
  3. 服务端 UIPropertyMessageHandler 处理请求
  4. 服务端存储值并发布 EventPlayerUIPropertyChange

初始化 ​

服务端需调用一次初始化：

csharp
#if SERVER
private static void OnGameTriggerInitialization()
{
    UIPropertyMessageHandler.Initialize();
}
#endif

预定义属性 ​

PropertyPlayerUI 可扩展枚举：

值说明
UIPanelCollapsedUI 面板折叠状态
ChatChannelPreference聊天频道偏好
KeyBindingSettings快捷键配置
UILayoutConfig界面布局配置

可通过 [EnumExtension(Extends = typeof(EPropertyPlayerUI))] 扩展。

客户端 API ​

PlayerUIPropertyExtensions 扩展方法：

csharp
// 设置单个属性
async Task<bool> SetUIPropertyAsync<TValue>(this Player player, PropertyPlayerUI property, TValue value);

// 批量设置
async Task<bool> SetUIPropertiesAsync(this Player player, Dictionary<PropertyPlayerUI, object> properties);

// JSON 序列化设置
async Task<bool> SetUIPropertyJsonAsync(this Player player, PropertyPlayerUI property, object value);

读取 API（双端） ​

csharp
// Player 原生方法
TValue? GetUIProperty<TValue>(PropertyPlayerUI property);

// 扩展方法（带默认值）
TValue GetUIPropertyAs<TValue>(this Player player, PropertyPlayerUI property, TValue defaultValue = default!);

// JSON 反序列化读取
TValue GetUIPropertyFromJson<TValue>(this Player player, PropertyPlayerUI property, TValue defaultValue = default!);

事件 ​

csharp
// 服务端 — 属性变化事件
public class EventPlayerUIPropertyChange : ITriggerEvent<EventPlayerUIPropertyChange>
{
    Player Player { get; }
    PropertyPlayerUI Property { get; }
}

订阅示例：

csharp
#if SERVER
var trigger = new Trigger<EventPlayerUIPropertyChange>(OnUIPropertyChanged);
trigger.Register(Game.Instance);

private static void OnUIPropertyChanged(EventPlayerUIPropertyChange e)
{
    Game.Logger.LogInformation("玩家 {PlayerId} 的 {Property} 已变更",
        e.Player.Id, e.Property);
}
#endif

用法示例 ​

csharp
#if CLIENT
// 保存面板折叠状态
await Player.LocalPlayer.SetUIPropertyAsync(PropertyPlayerUI.UIPanelCollapsed, true);

// 读取
bool collapsed = Player.LocalPlayer.GetUIPropertyAs<bool>(PropertyPlayerUI.UIPanelCollapsed);
#endif

相关文档 ​