GFramework/docs/api-reference/core-api.md

GFramework.Core API 参考

GFramework.Core 模块的完整 API 参考文档，包含所有核心类、接口和方法的详细说明。

📋 目录

• Architecture 核心架构
• Models 数据模型
• Systems 业务系统
• Commands 命令模式
• Queries 查询模式
• Events 事件系统
• Properties 属性绑定
• IoC 容器
• Utilities 工具类
• Extensions 扩展方法
• Rules 规则接口

Architecture 核心架构

IArchitecture

架构接口，定义了框架的核心功能契约。

方法签名

// 组件注册
void RegisterSystem<TSystem>(TSystem system) where TSystem : ISystem;
void RegisterModel<TModel>(TModel model) where TModel : IModel;
void RegisterUtility<TUtility>(TUtility utility) where TUtility : IUtility;

// 组件获取
T GetModel<T>() where T : class, IModel;
T GetSystem<T>() where T : class, ISystem;
T GetUtility<T>() where T : class, IUtility;

// 命令处理
void SendCommand(ICommand command);
TResult SendCommand<TResult>(ICommand<TResult> command);

// 查询处理
TResult SendQuery<TResult>(IQuery<TResult> query);

// 事件管理
void SendEvent<T>(T e) where T : new();
void SendEvent<T>(T e);
IUnRegister RegisterEvent<T>(Action<T> onEvent) where T : new();
void UnRegisterEvent<T>(Action<T> onEvent) where T : new();

使用示例

// 注册组件
architecture.RegisterModel(new PlayerModel());
architecture.RegisterSystem(new CombatSystem());
architecture.RegisterUtility(new StorageUtility());

// 获取组件
var playerModel = architecture.GetModel<PlayerModel>();
var combatSystem = architecture.GetSystem<CombatSystem>();
var storageUtility = architecture.GetUtility<StorageUtility>();

// 发送命令
architecture.SendCommand(new AttackCommand { TargetId = "enemy1" });

// 发送查询
var canAttack = architecture.SendQuery(new CanAttackQuery { PlayerId = "player1" });

// 发送事件
architecture.SendEvent(new PlayerDiedEvent { PlayerId = "player1" });

// 注册事件监听
var unregister = architecture.RegisterEvent<PlayerDiedEvent>(OnPlayerDied);

Architecture

抽象架构基类，实现了 IArchitecture 接口。

构造函数

public abstract class Architecture(
    IArchitectureConfiguration? configuration = null,
    IEnvironment? environment = null,
    IArchitectureServices? services = null,
    IArchitectureContext? context = null
)

主要属性

public IArchitectureContext Context { get; }
public ArchitecturePhase Phase { get; }
public bool IsInitialized { get; }
public bool IsDestroyed { get; }

主要方法

// 初始化
public void Initialize()
public async Task InitializeAsync()

// 销毁
public void Destroy()

// 模块安装
public void InstallModule(IArchitectureModule module)
public void InstallModule<T>() where T : IArchitectureModule, new();

架构阶段

public enum ArchitecturePhase
{
    None = 0,
    BeforeUtilityInit = 1,
    AfterUtilityInit = 2,
    BeforeModelInit = 3,
    AfterModelInit = 4,
    BeforeSystemInit = 5,
    AfterSystemInit = 6,
    Ready = 7,
    FailedInitialization = 8,
    Destroying = 9,
    Destroyed = 10
}

使用示例

public class GameArchitecture : Architecture
{
    protected override void Init()
    {
        RegisterModel(new PlayerModel());
        RegisterSystem(new CombatSystem());
        RegisterUtility(new StorageUtility());
    }
    
    protected override void InstallModules()
    {
        InstallModule(new AudioModule());
        InstallModule(new SaveModule());
    }
    
    protected override void OnPhase(ArchitecturePhase phase, IArchitecture architecture)
    {
        switch (phase)
        {
            case ArchitecturePhase.Ready:
                GD.Print("Architecture is ready");
                break;
            case ArchitecturePhase.Destroying:
                GD.Print("Architecture is destroying");
                break;
        }
    }
}

IArchitectureModule

架构模块接口。

方法签名

void Install(IArchitecture architecture);

使用示例

public class AudioModule : IArchitectureModule
{
    public void Install(IArchitecture architecture)
    {
        architecture.RegisterSystem(new AudioSystem());
        architecture.RegisterUtility(new AudioUtility());
    }
}

Models 数据模型

IModel

模型接口，定义了模型的基本行为。

继承的接口

IContextAware
ILogAware
IAsyncInitializable
IArchitecturePhaseAware

方法签名

void Init();
void OnArchitecturePhase(ArchitecturePhase phase);

AbstractModel

抽象模型基类，实现了 IModel 接口。

使用示例

public class PlayerModel : AbstractModel
{
    public BindableProperty<int> Health { get; } = new(100);
    public BindableProperty<int> MaxHealth { get; } = new(100);
    public BindableProperty<Vector2> Position { get; } = new(Vector2.Zero);
    public BindableProperty<PlayerState> State { get; } = new(PlayerState.Idle);
    
    protected override void OnInit()
    {
        Health.Register(OnHealthChanged);
        State.Register(OnStateChanged);
    }
    
    protected override void OnArchitecturePhase(ArchitecturePhase phase)
    {
        if (phase == ArchitecturePhase.Ready)
        {
            // 架构准备就绪
            SendEvent(new PlayerModelReadyEvent());
        }
    }
    
    private void OnHealthChanged(int newHealth)
    {
        if (newHealth <= 0)
        {
            State.Value = PlayerState.Dead;
            SendEvent(new PlayerDiedEvent());
        }
    }
    
    private void OnStateChanged(PlayerState newState)
    {
        SendEvent(new PlayerStateChangedEvent { NewState = newState });
    }
}

public enum PlayerState
{
    Idle,
    Moving,
    Attacking,
    Dead
}

Systems 业务系统

ISystem

系统接口，定义了系统的基本行为。

继承的接口

IContextAware
ILogAware
IAsyncInitializable
IArchitecturePhaseAware

方法签名

void Init();
void OnArchitecturePhase(ArchitecturePhase phase);

AbstractSystem

抽象系统基类，实现了 ISystem 接口。

使用示例

public class CombatSystem : AbstractSystem
{
    private PlayerModel _playerModel;
    private EnemyModel _enemyModel;
    
    protected override void OnInit()
    {
        _playerModel = GetModel<PlayerModel>();
        _enemyModel = GetModel<EnemyModel>();
        
        // 注册事件监听
        this.RegisterEvent<AttackInputEvent>(OnAttackInput);
        this.RegisterEvent<EnemyDeathEvent>(OnEnemyDeath);
    }
    
    protected override void OnArchitecturePhase(ArchitecturePhase phase)
    {
        if (phase == ArchitecturePhase.Ready)
        {
            // 系统准备就绪
            Logger.Info("CombatSystem is ready");
        }
    }
    
    private void OnAttackInput(AttackInputEvent e)
    {
        if (_playerModel.State.Value == PlayerState.Attacking)
            return;
            
        var enemy = FindEnemyInRange();
        if (enemy != null)
        {
            PerformAttack(_playerModel, enemy);
        }
    }
    
    private void OnEnemyDeath(EnemyDeathEvent e)
    {
        Logger.Info($"Enemy {e.EnemyId} died");
        
        // 更新玩家分数
        _playerModel.Score.Value += 100;
        
        // 发送事件通知其他系统
        SendEvent(new EnemyDefeatedEvent { EnemyId = e.EnemyId });
    }
    
    private Enemy FindEnemyInRange()
    {
        // 查找范围内的敌人逻辑
        return null;
    }
    
    private void PerformAttack(PlayerModel player, Enemy enemy)
    {
        var damage = CalculateDamage(player, enemy);
        enemy.Health.Value -= damage;
        
        SendEvent(new DamageDealtEvent
        {
            AttackerId = player.Id,
            TargetId = enemy.Id,
            Damage = damage
        });
    }
    
    private int CalculateDamage(PlayerModel player, Enemy enemy)
    {
        // 伤害计算逻辑
        return player.AttackPower.Value;
    }
}

Commands 命令模式

ICommand

命令接口，定义了命令的基本行为。

方法签名

void Execute();

ICommand

带返回值的命令接口。

方法签名

TResult Execute();

AbstractCommand

抽象命令基类，实现了 ICommand 接口。

可用的方法

// 获取模型
T GetModel<T>() where T : class, IModel;

// 获取系统
T GetSystem<T>() where T : class, ISystem;

// 获取工具
T GetUtility<T>() where T : class, IUtility;

// 发送事件
void SendEvent<T>(T e) where T : new();
void SendEvent<T>(T e);

// 发送命令
void SendCommand(ICommand command);
TResult SendCommand<TResult>(ICommand<TResult> command);

// 发送查询
TResult SendQuery<TResult>(IQuery<TResult> query);

使用示例

public class AttackCommand : AbstractCommand
{
    public string AttackerId { get; set; }
    public string TargetId { get; set; }
    public int Damage { get; set; }
    
    protected override void OnExecute()
    {
        var attacker = GetModel<PlayerModel>(AttackerId);
        var target = GetModel<EnemyModel>(TargetId);
        
        if (!CanAttack(attacker, target))
            return;
            
        PerformAttack(attacker, target, Damage);
        
        SendEvent(new AttackCompletedEvent
        {
            AttackerId = AttackerId,
            TargetId = TargetId,
            Damage = Damage
        });
    }
    
    private bool CanAttack(PlayerModel attacker, EnemyModel target)
    {
        return attacker.State.Value == PlayerState.Idle &&
               target.Health.Value > 0 &&
               Vector2.Distance(attacker.Position.Value, target.Position.Value) <= attacker.AttackRange.Value;
    }
    
    private void PerformAttack(PlayerModel attacker, EnemyModel target, int damage)
    {
        target.Health.Value -= damage;
        
        SendEvent(new DamageDealtEvent
        {
            AttackerId = attacker.Id,
            TargetId = target.Id,
            Damage = damage
        });
    }
}

public class GetPlayerScoreQuery : AbstractQuery<int>
{
    public string PlayerId { get; set; }
    
    protected override int OnDo()
    {
        var playerModel = GetModel<PlayerModel>(PlayerId);
        return playerModel.Score.Value;
    }
}

// 使用示例
var attackCommand = new AttackCommand
{
    AttackerId = "player1",
    TargetId = "enemy1",
    Damage = 50
};

Context.SendCommand(attackCommand);

var scoreQuery = new GetPlayerScoreQuery { PlayerId = "player1" };
var score = Context.SendQuery(scoreQuery);

Queries 查询模式

IQuery

查询接口，定义了查询的基本行为。

方法签名

TResult OnDo();

AbstractQuery

抽象查询基类，实现了 IQuery 接口。

可用的方法

与 AbstractCommand 相同，提供：

• GetModel<T>()
• GetSystem<T>()
• GetUtility<T>()
• SendEvent<T>()
• SendCommand()
• SendQuery()

使用示例

public class CanAttackQuery : AbstractQuery<bool>
{
    public string PlayerId { get; set; }
    public string TargetId { get; set; }
    
    protected override bool OnDo()
    {
        var player = GetModel<PlayerModel>(PlayerId);
        var target = GetModel<EnemyModel>(TargetId);
        
        if (player.State.Value != PlayerState.Idle)
            return false;
            
        if (player.Health.Value <= 0)
            return false;
            
        if (target.Health.Value <= 0)
            return false;
            
        var distance = Vector2.Distance(
            player.Position.Value, 
            target.Position.Value
        );
        
        return distance <= player.AttackRange.Value;
    }
}

public class GetInventoryItemsQuery : AbstractQuery<List<InventoryItem>>
{
    public string PlayerId { get; set; }
    public string ItemType { get; set; }
    
    protected override List<InventoryItem> OnDo()
    {
        var inventorySystem = GetSystem<InventorySystem>();
        return inventorySystem.GetPlayerItems(PlayerId, ItemType);
    }
}

public class GetGameStatisticsQuery : AbstractQuery<GameStatistics>
{
    protected override GameStatistics OnDo()
    {
        var playerModel = GetModel<PlayerModel>();
        var gameModel = GetModel<GameModel>();
        
        return new GameStatistics
        {
            PlayerLevel = playerModel.Level.Value,
            PlayerScore = playerModel.Score.Value,
            PlayerHealth = playerModel.Health.Value,
            PlayTime = gameModel.PlayTime.Value,
            EnemiesDefeated = gameModel.EnemiesDefeated.Value
        };
    }
}

// 使用示例
var canAttackQuery = new CanAttackQuery { PlayerId = "player1", TargetId = "enemy1" };
var canAttack = Context.SendQuery(canAttackQuery);

var inventoryQuery = new GetInventoryItemsQuery 
{ 
    PlayerId = "player1", 
    ItemType = "weapon" 
};
var weapons = Context.SendQuery(inventoryQuery);

var statsQuery = new GetGameStatisticsQuery();
var stats = Context.SendQuery(statsQuery);

Events 事件系统

IEvent

事件标记接口，用于标识事件类型。

public interface IEvent
{
    // 事件类型标识
}

IUnRegister

注销接口，用于取消事件注册。

方法签名

void UnRegister();

IUnRegisterList

注销列表接口，用于批量管理注销对象。

属性

IList<IUnRegister> UnregisterList { get; }

方法签名

void Add(IUnRegister unRegister);
void UnRegisterAll();

EasyEvent

无参事件类。

构造函数

public EasyEvent()

方法

IUnRegister Register(Action onEvent);
void Trigger();

使用示例

// 创建事件
var buttonClicked = new EasyEvent();

// 注册监听
var unregister = buttonClicked.Register(() => {
    GD.Print("Button clicked!");
});

// 触发事件
buttonClicked.Trigger();

// 注销监听
unregister.UnRegister();

Event

单参数泛型事件类。

构造函数

public Event<T>()

方法

IUnRegister Register(Action<T> onEvent);
void Trigger(T data);

使用示例

// 创建事件
var scoreChanged = new Event<int>();

// 注册监听
var unregister = scoreChanged.Register(score => {
    GD.Print($"Score changed to: {score}");
});

// 触发事件
scoreChanged.Trigger(100);

// 注销监听
unregister.UnRegister();

EventBus

事件总线类，提供基于类型的事件发送和注册。

方法

IUnRegister Register<T>(Action<T> onEvent) where T : new();
void Send<T>(T e) where T : new();
void Send<T>() where T : new();

使用示例

// 创建事件总线
var eventBus = new EventBus();

// 注册事件
eventBus.Register<PlayerDiedEvent>(e => {
    GD.Print($"Player died at position: {e.Position}");
});

// 发送事件
eventBus.Send(new PlayerDiedEvent 
{ 
    Position = new Vector3(10, 0, 5) 
});

Properties 属性绑定

BindableProperty

可绑定属性类，支持属性变化监听。

构造函数

public BindableProperty(T initialValue = default)

属性

public T Value { get; set; }
public T PreviousValue { get; }

方法

IUnRegister Register(Action<T> onValueChanged);
IUnRegister RegisterWithInitValue(Action<T> onValueChanged);
void SetValueWithoutNotify(T value);

使用示例

public class PlayerModel : AbstractModel
{
    public BindableProperty<int> Health { get; } = new(100);
    public BindableProperty<Vector2> Position { get; } = new(Vector2.Zero);
    
    protected override void OnInit()
    {
        // 注册健康值变化监听
        Health.Register(OnHealthChanged);
        
        // 注册位置变化监听（包含初始值）
        Position.RegisterWithInitValue(OnPositionChanged);
    }
    
    private void OnHealthChanged(int newHealth)
    {
        if (newHealth <= 0)
        {
            SendEvent(new PlayerDiedEvent());
        }
    }
    
    private void OnPositionChanged(Vector2 newPosition)
    {
        // 处理位置变化
        UpdatePlayerPosition(newPosition);
    }
}

// 外部使用
var playerModel = new PlayerModel();

// 监听属性变化
var healthUnregister = playerModel.Health.Register(health => {
    GD.Print($"Player health: {health}");
});

// 设置属性值
playerModel.Health.Value = 80;  // 会触发监听器
playerModel.Health.SetValueWithoutNotify(90);  // 不会触发监听器

// 注销监听
healthUnregister.UnRegister();

IoC 容器

IBelongToArchitecture

属于架构的接口标记。

IContextAware

上下文感知接口。

属性

IContextAware.Context Context { get; }
void SetContext(IContextAware.Context context);

ILogAware

日志感知接口。

属性

ILogger Logger { get; }

ContextAwareBase

上下文感知基类，实现了 IContextAware 接口。

属性

public IContextAware.Context Context { get; }

使用示例

public class MyService : ContextAwareBase
{
    public void DoWork()
    {
        var playerModel = Context.GetModel<PlayerModel>();
        Logger.Info("Doing work with player model");
    }
}

Utilities 工具类

IUtility

工具接口，标记工具类。

方法签名

void Init();

AbstractUtility

抽象工具基类。

可用的方法

与 AbstractCommand 相同，提供：

• GetModel<T>()
• GetSystem<T>()
• GetUtility<T>()
• SendEvent<T>()
• SendCommand()
• SendQuery()

使用示例

public class MathUtility : AbstractUtility
{
    public float Distance(Vector2 a, Vector2 b)
    {
        return Vector2.Distance(a, b);
    }
    
    public float Lerp(float a, float b, float t)
    {
        return a + (b - a) * t;
    }
    
    public Vector2 Normalize(Vector2 vector)
    {
        if (vector == Vector2.Zero)
            return Vector2.Zero;
            
        return vector.Normalized();
    }
}

public class StorageUtility : AbstractUtility
{
    private readonly IStorage _storage;
    
    public StorageUtility(IStorage storage)
    {
        _storage = storage;
    }
    
    protected override void OnInit()
    {
        Logger.Info("Storage utility initialized");
    }
    
    public async Task SaveAsync<T>(string key, T data)
    {
        await _storage.WriteAsync(key, data);
        Logger.Info($"Saved data to key: {key}");
    }
    
    public async Task<T> LoadAsync<T>(string key, T defaultValue = default)
    {
        var data = await _storage.ReadAsync<T>(key, defaultValue);
        Logger.Info($"Loaded data from key: {key}");
        return data;
    }
}

Extensions 扩展方法

组件获取扩展

// 为 IArchitectureContext 提供扩展方法
public static class ArchitectureContextExtensions
{
    public static T GetModel<T>(this IContextAware.Context context) where T : class, IModel;
    public static T GetSystem<T>(this IContextAware.Context context) where T : class, ISystem;
    public static T GetUtility<T>(this IContextAware.Context context) where T : class, IUtility;
}

事件扩展

// 为事件注册提供扩展方法
public static class EventExtensions
{
    public static IUnRegister UnRegisterWhenNodeExitTree<T>(
        this IUnRegister unRegister, 
        Node node) where T : new();
        
    public static IUnRegister AddToUnregisterList(
        this IUnRegister unRegister,
        IUnRegisterList unregisterList);
}

使用示例

// 使用扩展方法
var playerModel = Context.GetModel<PlayerModel>();
var combatSystem = Context.GetSystem<CombatSystem>();
var storageUtility = Context.GetUtility<StorageUtility>();

// 使用事件扩展
var unregister = this.RegisterEvent<PlayerDiedEvent>(OnPlayerDied)
    .UnRegisterWhenNodeExitTree(this);

var unregisterList = new UnRegisterList();
this.RegisterEvent<GameEvent>(OnGameEvent)
    .AddToUnregisterList(unregisterList);

Rules 规则接口

IRule

规则接口标记。

ICanGetModel

可获取模型的规则接口。

T GetModel<T>() where T : class, IModel;

ICanGetSystem

可获取系统的规则接口。

T GetSystem<T>() where T : class, ISystem;

ICanGetUtility

可获取工具的规则接口。

T GetUtility<T>() where T : class, IUtility;

ICanSendCommand

可发送命令的规则接口。

void SendCommand(ICommand command);
TResult SendCommand<TResult>(ICommand<TResult> command);

ICanSendQuery

可发送查询的规则接口。

TResult SendQuery<TResult>(IQuery<TResult> query);

ICanRegisterEvent

可注册事件的规则接口。

IUnRegister RegisterEvent<T>(Action<T> onEvent) where T : new();

IController

控制器接口，组合了多个规则接口。

public interface IController : 
    ICanGetModel, 
    ICanGetSystem, 
    ICanGetUtility,
    ICanSendCommand,
    ICanSendQuery,
    ICanRegisterEvent
{
}

错误处理

GFrameworkException

框架基础异常类。

public class GFrameworkException : Exception
{
    public GFrameworkException(string message) : base(message) { }
    public GFrameworkException(string message, Exception innerException) : base(message, innerException) { }
}

ArchitectureException

架构相关异常。

public class ArchitectureException : GFrameworkException
{
    public ArchitectureException(string message) : base(message) { }
}

ComponentException

组件相关异常。

public class ComponentException : GFrameworkException
{
    public ComponentException(string message) : base(message) { }
}

---

文档版本: 1.0.0
更新日期: 2026-01-12