Documentation
¶
Overview ¶
Package instancing implements ephemeral isolated session worlds — the "dungeon / raid / sandbox" model: spin up a world for a group, track objectives within it, fire bindings (open doors, gate triggers) as state advances, persist enough to resume after restart, and tear it all down when the session ends.
Game dungeons / raids are the canonical use; the same mechanism applies to CI pipeline runs, ephemeral training environments, and sandboxed execution contexts.
Per the architectural invariants, this package never imports kit/unreal/* or project services — entity ownership and spawn data are supplied by a caller-implemented Loader interface, keeping kit/game/* independent in the import graph.
Index ¶
- Variables
- type Binding
- type Definition
- type Instance
- func (i *Instance) ID() InstanceID
- func (i *Instance) Objective(obj ObjectiveID) ObjectiveState
- func (i *Instance) Objectives() map[ObjectiveID]ObjectiveState
- func (i *Instance) PlayerEnter(ctx context.Context, player string) error
- func (i *Instance) PlayerExit(ctx context.Context, player string) error
- func (i *Instance) Players() []string
- func (i *Instance) SetObjective(ctx context.Context, obj ObjectiveID, next ObjectiveState) error
- func (i *Instance) SpawnPlan() SpawnPlan
- type InstanceID
- type Loader
- type Manager
- type ObjectiveID
- type ObjectiveState
- type SpawnPlan
Constants ¶
This section is empty.
Variables ¶
var ( ErrUnknownInstance = errors.New("instancing: unknown instance") ErrInstanceExists = errors.New("instancing: instance already exists") ErrUnknownObjective = errors.New("instancing: unknown objective") ErrTerminalState = errors.New("instancing: objective is in a terminal state") )
Errors surfaced by the instancing package.
Functions ¶
This section is empty.
Types ¶
type Binding ¶
type Binding struct {
// Objective is the objective this binding watches.
Objective ObjectiveID
// Object is the world object the binding affects.
Object string
// OnState maps an objective state to an action token (caller-defined
// string, e.g. "open", "close", "spawn").
OnState map[ObjectiveState]string
}
Binding links a named object (door, gate, spawner) to an objective state. When the objective transitions to a state listed in OnState, the manager invokes Definition.OnBinding with the action token.
type Definition ¶
type Definition struct {
Name string
Objectives []ObjectiveID
Bindings []Binding
Loader Loader
OnCreate func(ctx context.Context, inst *Instance, plan SpawnPlan) error
OnPlayerEnter func(ctx context.Context, inst *Instance, player string) error
OnPlayerExit func(ctx context.Context, inst *Instance, player string) error
OnObjective func(ctx context.Context, inst *Instance, obj ObjectiveID, prev, next ObjectiveState)
OnBinding func(ctx context.Context, inst *Instance, b Binding, action string)
OnDestroy func(ctx context.Context, inst *Instance)
}
Definition is the shape of an instance type — what objectives exist, which bindings react to state changes, and the lifecycle hooks.
type Instance ¶
type Instance struct {
// contains filtered or unexported fields
}
Instance is a live session world.
func (*Instance) Objective ¶
func (i *Instance) Objective(obj ObjectiveID) ObjectiveState
Objective returns the current state of an objective. Returns ObjectiveNotStarted for unknown objectives — callers that need to distinguish "not started" from "doesn't exist" should consult the Definition.
func (*Instance) Objectives ¶
func (i *Instance) Objectives() map[ObjectiveID]ObjectiveState
Objectives returns a snapshot of all objective states.
func (*Instance) PlayerEnter ¶
PlayerEnter adds a player to the roster and fires OnPlayerEnter.
func (*Instance) PlayerExit ¶
PlayerExit removes a player from the roster and fires OnPlayerExit.
func (*Instance) SetObjective ¶
func (i *Instance) SetObjective(ctx context.Context, obj ObjectiveID, next ObjectiveState) error
SetObjective transitions an objective's state, fires the Definition's OnObjective hook, then runs any bindings that match (objective, newState). Returns ErrTerminalState if the objective is already completed/failed.
type Loader ¶
type Loader interface {
Load(ctx context.Context, def *Definition, inst InstanceID) (SpawnPlan, error)
}
Loader provides spawn data for a Definition. The implementation typically calls into a spawn-service or content pack. The kit never imports those; the Loader is the seam.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager creates, looks up, and destroys instances of a single Definition. Safe for concurrent use.
func NewManager ¶
func NewManager(def *Definition) *Manager
NewManager constructs a Manager for the given Definition.
func (*Manager) Create ¶
Create instantiates a new Instance. The Loader is consulted for spawn data, OnCreate fires, and the instance is registered for lookup via Get.
type ObjectiveState ¶
type ObjectiveState uint8
ObjectiveState enumerates the lifecycle of a single objective.
const ( // ObjectiveNotStarted — initial state. ObjectiveNotStarted ObjectiveState = iota // ObjectiveInProgress — actively being worked on. ObjectiveInProgress // ObjectiveCompleted — succeeded; terminal. ObjectiveCompleted // ObjectiveFailed — failed; terminal. ObjectiveFailed )
func (ObjectiveState) String ¶
func (s ObjectiveState) String() string
String returns the human-readable label.
Source Files