runtime

type AddInManager interface {
	extension.AddInManager

	IAddInManagerEventTab
	// contains filtered or unexported methods
}

type AddInStatus interface {
	extension.AddInStatus
	// contains filtered or unexported methods
}

type Callee interface {
	PushSubmit(fun generic.FuncVar1[Context, any, async.Result], args ...any) async.Future
	PushSubmitDelegate(fun generic.DelegateVar1[Context, any, async.Result], args ...any) async.Future
	PushSubmitVoid(fun generic.ActionVar1[Context, any], args ...any) async.Future
	PushSubmitDelegateVoid(fun generic.DelegateVoidVar1[Context, any], args ...any) async.Future
	PushPost(fun generic.ActionVar1[Context, any], args ...any) error
	PushPostDelegate(fun generic.DelegateVoidVar1[Context, any], args ...any) error
}

type Caller interface {
	Submit(fun generic.FuncVar1[Context, any, async.Result], args ...any) async.Future
	SubmitDelegate(fun generic.DelegateVar1[Context, any, async.Result], args ...any) async.Future
	SubmitVoid(fun generic.ActionVar1[Context, any], args ...any) async.Future
	SubmitDelegateVoid(fun generic.DelegateVoidVar1[Context, any], args ...any) async.Future
	Post(fun generic.ActionVar1[Context, any], args ...any) error
	PostDelegate(fun generic.DelegateVoidVar1[Context, any], args ...any) error
}

type ConcurrentContext interface {
	corectx.Context
	corectx.ConcurrentContextProvider
	Caller
	fmt.Stringer

	// Name 返回运行时名称。
	Name() string
	// Id 返回运行时的持久化 ID。
	Id() uid.Id
	// ExecutorID 返回进程内 Runtime 执行器 ID。
	ExecutorID() async.ExecutorID
	// BlockedFutureID 返回当前阻塞等待的 Future ID。
	BlockedFutureID() uint64
	// LastWaitRejectID 返回最近一次被 Runtime 等待规则拒绝的 Future ID。
	LastWaitRejectID() uint64
	// contains filtered or unexported methods
}

type ConcurrentContextProvider = corectx.ConcurrentContextProvider

type Context interface {
	ConcurrentContext
	corectx.CurrentContextProvider
	async.WaitGuard
	reinterpret.InstanceProvider
	extension.AddInProvider
	GCCollector

	// Name 返回运行时名称。
	Name() string
	// Id 返回运行时的持久化 ID。
	Id() uid.Id
	// Reflected 返回实际运行时上下文实例的反射值。
	Reflected() reflect.Value
	// Frame 返回帧统计接口；未启用帧循环时返回 nil。
	Frame() Frame
	// EntityManager 返回当前运行时的本地实体管理器。
	EntityManager() EntityManager
	// EntityTree 返回当前运行时的实体树。
	EntityTree() EntityTree
	// Managed 返回随运行时上下文统一解绑的事件句柄集合。
	Managed() *event.ManagedHandles

	IContextRunningEventTab
	// contains filtered or unexported methods
}

type ContextBehavior struct {
	corectx.ContextBehavior
	// contains filtered or unexported fields
}

type ContextOptions struct {
	InstanceFace   iface.Face[Context] // 自定义上下文实例及其接口缓存。
	Context        context.Context     // 父上下文；nil 时使用所属服务上下文。
	AutoRecover    bool                // 回调发生 panic 时是否自动恢复。
	ReportError    chan error          // 自动恢复后接收 panic 错误的通道。
	Name           string              // 运行时名称。
	PersistId      uid.Id              // 运行时持久化 ID；为 Nil 时自动生成。
	AddInManager   AddInManager        // 运行时插件管理器；nil 时创建默认管理器。
	RunningEventCB RunningEventCB      // 运行时运行事件回调。
}

type CurrentContextProvider = corectx.CurrentContextProvider

type EntityManager interface {
	corectx.CurrentContextProvider

	// AddEntity 接管 Born 状态的实体；运行时已启动时会同步推进其生命周期。
	AddEntity(entity ec.Entity) error
	// RemoveEntity 按 ID 请求销毁实体；实体不存在时不执行任何操作。
	RemoveEntity(id uid.Id)
	// GetEntity 按 ID 查询本地实体。
	GetEntity(id uid.Id) (ec.Entity, bool)
	// RangeEntities 按加入顺序遍历实体，回调返回 false 时停止。
	RangeEntities(fun generic.Func1[ec.Entity, bool])
	// EachEntities 按加入顺序遍历全部实体。
	EachEntities(fun generic.Action1[ec.Entity])
	// ReversedRangeEntities 按加入顺序逆向遍历实体，回调返回 false 时停止。
	ReversedRangeEntities(fun generic.Func1[ec.Entity, bool])
	// ReversedEachEntities 按加入顺序逆向遍历全部实体。
	ReversedEachEntities(fun generic.Action1[ec.Entity])
	// FilterEntities 按加入顺序返回符合条件的实体。
	FilterEntities(fun generic.Func1[ec.Entity, bool]) []ec.Entity
	// ListEntities 按加入顺序返回实体切片副本。
	ListEntities() []ec.Entity
	// CountEntities 返回当前实体数。
	CountEntities() int

	IEntityManagerEventTab
}

type EntityTree interface {
	corectx.CurrentContextProvider

	// MakeRoot 将自由实体作为根节点加入实体树。
	MakeRoot(entityId uid.Id) error
	// AddChild 将自由实体 childId 挂到 parentId 下。
	AddChild(parentId, childId uid.Id) error
	// RemoveNode 按后序递归移除整个子树的树关系；实体本身不会被销毁。
	RemoveNode(childId uid.Id) error
	// DetachNode 将节点从当前父实体移到虚拟森林节点下，使其成为根节点。
	DetachNode(childId uid.Id) error
	// MoveNode 将节点移动到新的父节点下。
	MoveNode(childId, parentId uid.Id) error
	// IsFree 报告实体是否尚未加入实体树。
	IsFree(entityId uid.Id) (bool, error)
	// IsRoot 报告实体是否直接挂在虚拟森林节点下。
	IsRoot(entityId uid.Id) (bool, error)
	// IsLeaf 报告实体是否没有子节点。
	IsLeaf(entityId uid.Id) (bool, error)
	// GetParent 返回父实体；根节点没有实体父节点，因此返回错误。
	GetParent(childId uid.Id) (ec.Entity, error)
	// RangeChildren 按加入顺序遍历直接子节点，回调返回 false 时停止。
	RangeChildren(parentId uid.Id, fun generic.Func1[ec.Entity, bool]) error
	// EachChildren 按加入顺序遍历全部直接子节点。
	EachChildren(parentId uid.Id, fun generic.Action1[ec.Entity]) error
	// ReversedRangeChildren 按加入顺序逆向遍历直接子节点，回调返回 false 时停止。
	ReversedRangeChildren(parentId uid.Id, fun generic.Func1[ec.Entity, bool]) error
	// ReversedEachChildren 按加入顺序逆向遍历全部直接子节点。
	ReversedEachChildren(parentId uid.Id, fun generic.Action1[ec.Entity]) error
	// FilterChildren 按加入顺序返回符合条件的直接子节点。
	FilterChildren(parentId uid.Id, fun generic.Func1[ec.Entity, bool]) ([]ec.Entity, error)
	// ListChildren 按加入顺序返回直接子节点切片。
	ListChildren(parentId uid.Id) ([]ec.Entity, error)
	// CountChildren 返回直接子节点数。
	CountChildren(parentId uid.Id) (int, error)

	IEntityTreeEventTab
}

type EventAddInStateChanged interface {
	OnAddInStateChanged(status AddInStatus, state extension.AddInState)
}

type EventAddInStateChangedHandler func(status AddInStatus, state extension.AddInState)

type EventContextRunningEvent interface {
	OnContextRunningEvent(ctx Context, runningEvent RunningEvent, args ...any)
}

type EventContextRunningEventHandler func(ctx Context, runningEvent RunningEvent, args ...any)

type EventEntityManagerAddEntity interface {
	OnEntityManagerAddEntity(entityManager EntityManager, entity ec.Entity)
}

type EventEntityManagerAddEntityHandler func(entityManager EntityManager, entity ec.Entity)

type EventEntityManagerEntityAddComponents interface {
	OnEntityManagerEntityAddComponents(entityManager EntityManager, entity ec.Entity, components []ec.Component)
}

type EventEntityManagerEntityAddComponentsHandler func(entityManager EntityManager, entity ec.Entity, components []ec.Component)

type EventEntityManagerEntityComponentEnableChanged interface {
	OnEntityManagerEntityComponentEnableChanged(entityManager EntityManager, entity ec.Entity, component ec.Component, enable bool)
}

type EventEntityManagerEntityComponentEnableChangedHandler func(entityManager EntityManager, entity ec.Entity, component ec.Component, enable bool)

type EventEntityManagerEntityFirstTouchComponent interface {
	OnEntityManagerEntityFirstTouchComponent(entityManager EntityManager, entity ec.Entity, component ec.Component)
}

type EventEntityManagerEntityFirstTouchComponentHandler func(entityManager EntityManager, entity ec.Entity, component ec.Component)

type EventEntityManagerEntityRemoveComponent interface {
	OnEntityManagerEntityRemoveComponent(entityManager EntityManager, entity ec.Entity, component ec.Component)
}

type EventEntityManagerEntityRemoveComponentHandler func(entityManager EntityManager, entity ec.Entity, component ec.Component)

type EventEntityManagerRemoveEntity interface {
	OnEntityManagerRemoveEntity(entityManager EntityManager, entity ec.Entity)
}

type EventEntityManagerRemoveEntityHandler func(entityManager EntityManager, entity ec.Entity)

type EventEntityTreeAddNode interface {
	OnEntityTreeAddNode(entityTree EntityTree, parentId, childId uid.Id)
}

type EventEntityTreeAddNodeHandler func(entityTree EntityTree, parentId, childId uid.Id)

type EventEntityTreeMoveNode interface {
	OnEntityTreeMoveNode(entityTree EntityTree, childId, fromParentId, toParentId uid.Id)
}

type EventEntityTreeMoveNodeHandler func(entityTree EntityTree, childId, fromParentId, toParentId uid.Id)

type EventEntityTreeRemoveNode interface {
	OnEntityTreeRemoveNode(entityTree EntityTree, parentId, childId uid.Id)
}

type EventEntityTreeRemoveNodeHandler func(entityTree EntityTree, parentId, childId uid.Id)

type EventInstallAddIn interface {
	OnInstallAddIn(status AddInStatus)
}

type EventInstallAddInHandler func(status AddInStatus)

type EventUninstallAddIn interface {
	OnUninstallAddIn(status AddInStatus)
}

type EventUninstallAddInHandler func(status AddInStatus)

type Frame interface {
	// TargetFPS 返回目标 FPS。
	TargetFPS() float64
	// CurFPS 返回最近一个统计周期内的实际 FPS。
	CurFPS() float64
	// TotalFrames 返回最大运行帧数；0 表示不限制。
	TotalFrames() int64
	// CurFrames 返回已经开始执行的帧数。
	CurFrames() int64
	// RunningBeginTime 返回帧循环的启动时间。
	RunningBeginTime() time.Time
	// RunningElapseTime 返回已累计的帧循环运行时长。
	RunningElapseTime() time.Duration
	// LoopBeginTime 返回当前帧循环的开始时间；循环包含异步调用处理。
	LoopBeginTime() time.Time
	// LastLoopElapseTime 返回上一帧完整循环的耗时，包含异步调用处理。
	LastLoopElapseTime() time.Duration
	// UpdateBeginTime 返回当前帧更新阶段的开始时间。
	UpdateBeginTime() time.Time
	// LastUpdateElapseTime 返回上一帧更新阶段的耗时。
	LastUpdateElapseTime() time.Duration
}

type GC interface {
	// GC 执行实际清理。
	GC()
	// NeedGC 报告对象当前是否需要清理。
	NeedGC() bool
}

type GCCollector interface {
	// CollectGC 在 gc 需要清理时将其加入当前运行时的待清理队列。
	CollectGC(gc GC)
}

type IAddInManagerEventTab interface {
	EventInstallAddIn() event.IEvent
	EventUninstallAddIn() event.IEvent
	EventAddInStateChanged() event.IEvent
}

type IContextRunningEventTab interface {
	EventContextRunningEvent() event.IEvent
}

type IEntityManagerEventTab interface {
	EventEntityManagerAddEntity() event.IEvent
	EventEntityManagerRemoveEntity() event.IEvent
	EventEntityManagerEntityAddComponents() event.IEvent
	EventEntityManagerEntityRemoveComponent() event.IEvent
	EventEntityManagerEntityComponentEnableChanged() event.IEvent
	EventEntityManagerEntityFirstTouchComponent() event.IEvent
}

type IEntityTreeEventTab interface {
	EventEntityTreeAddNode() event.IEvent
	EventEntityTreeRemoveNode() event.IEvent
	EventEntityTreeMoveNode() event.IEvent
}

type RunningEvent int32

type RunningEventCB = generic.ActionVar2[Context, RunningEvent, any] // 运行时运行事件回调。