assertion

package

v0.4.27 Latest Latest Go to latest Published: Aug 12, 2026 License: LGPL-2.1 Imports: 8 Imported by: 0

Details

Package assertion 提供基于实体组件模型的断言与注入辅助。

Package assertion 通过反射从 ec.Entity 中提取组件，并按字段类型、组件名或原型名注入到结构体中。

它适合把多个组件组合成临时视图，或者在组件启动时把依赖字段补齐。字段可通过 `ec:"name,prototype"` tag 指定组件名或组件原型；如果目标原型已在服务的组件库中注册，但实体上尚未存在对应组件，Inject 还可以按原型动态创建组件。

未找到匹配组件时，对应字段保持零值，不视为错误。这类操作依赖反射并可能修改实体，应在实体所属 Runtime 的运行协程中执行；适合启动期、装配期或测试场景，不建议在高频热点路径中反复执行。

This section is empty.

This section is empty.

func As[T any](entity ec.Entity) (*T, bool)

As 创建 T 并从 entity 向其字段注入匹配组件。

T 必须是结构体。字段标签格式为 `ec:"组件名,完整组件原型名"`；指针字段未标注标签时会按字段类型推导名称和原型。未找到组件的字段保持零值，不影响 ok；只有注入参数或动态添加组件出错时 ok 才为 false。返回值反映调用时的组件快照，实体组件变化后应重新提取。

func Cast[T any](entity ec.Entity) *T

Cast 与 As 相同地创建并注入 T，但在 InjectRV 返回错误时 panic。未找到匹配组件的字段仍保持零值，不会单独触发 panic。

func Inject(entity ec.Entity, target any) error

Inject 使用反射向非 nil 结构体指针 target 注入 entity 的匹配组件。该操作可能按已声明原型创建并添加缺失组件。

func InjectRV(entity ec.Entity, target reflect.Value) error

InjectRV 向可寻址结构体或可解引用到结构体的 target 注入匹配组件。未找到匹配组件时保留字段原值；entity 为 nil、target 可解引用但为 nil、 target 类型不受支持或动态添加失败时返回错误。无效的 reflect.Value 会在读取类型时 panic。

This section is empty.