frame

type CobAnimSnap struct {
	Key    int   `json:"key"`
	Kind   int   `json:"kind"`
	Value  int64 `json:"value"`
	Target int64 `json:"target,omitempty"`
	Speed  int64 `json:"speed,omitempty"`
	Decel  int64 `json:"decel,omitempty"`
	Done   bool  `json:"done,omitempty"`
}

type CobCallFrame struct {
	ScriptIndex int     `json:"scriptIndex"`
	PC          int     `json:"pc"`
	Locals      []int32 `json:"locals,omitempty"`
}

type CobSnapshot struct {
	Static  []int32         `json:"static,omitempty"`
	Anims   []CobAnimSnap   `json:"anims,omitempty"`
	Hidden  []int           `json:"hidden,omitempty"` // piece indices that are HIDE'd
	Threads []CobThreadSnap `json:"threads,omitempty"`
	NextID  int32           `json:"nextId,omitempty"`
}

type CobThread struct {
	ID         int    // stable per-unit thread id, for list keys
	Script     string // entry-point name the thread is executing
	PC         int    // next instruction index within the current script
	Offset     int    // byte offset of that instruction, for the disassembly view
	SleepMs    int    // remaining sleep, 0 when running
	Waiting    bool   // blocked on a piece animation (turn/move) completing
	WaitTurn   bool   // when Waiting, true = turn animation, false = move
	SignalMask int    // signal bits this thread listens for
	// Locals and Stack are the thread's live local variables and operand stack,
	// surfaced to the debugger's variables tray. Debug-only, never hashed.
	Locals []int32
	Stack  []int32
	// BreakpointHit is true when the thread is parked on a breakpoint instruction
	// (the debugger autopauses on it). Cleared by a step / continue / pc edit.
	BreakpointHit bool
}

type CobThreadSnap struct {
	ID          int32          `json:"id"`
	ScriptIndex int            `json:"scriptIndex"`
	PC          int            `json:"pc"`
	Stack       []int32        `json:"stack,omitempty"`
	Locals      []int32        `json:"locals,omitempty"`
	SignalMask  int32          `json:"signalMask,omitempty"`
	SleepMs     int64          `json:"sleepMs,omitempty"`
	Waiting     bool           `json:"waiting,omitempty"`
	WaitRot     bool           `json:"waitRot,omitempty"`
	WaitKey     int            `json:"waitKey,omitempty"`
	CallStack   []CobCallFrame `json:"callStack,omitempty"`
	ReturnValue int32          `json:"returnValue,omitempty"`
}

type CobUnitState struct {
	Static  []int32
	Threads []CobThread
}

type Event struct {
	Kind     EventKind
	UnitID   uint32
	TargetID uint32
	Slot     int
	Anchor   fixed.Vec3
	// Target is the resolved aim point for a fire event — the unit's position
	// when locked on a unit, or the ground point for a force-fire. The renderer
	// needs it to launch a ballistic shot whose model the sim does not fly; for
	// a ground-aimed cannon ball there is no TargetID to look up, so without
	// this the client cannot derive a trajectory.
	Target fixed.Vec3
	// FromPiece is the COB piece index a fire event's shot exits from, as
	// reported by the unit's Query<slot> script. The sim is geometry-agnostic, so
	// it cannot resolve the muzzle's world position itself; it hands the renderer
	// the piece index (into the unit's piece-name table) and lets the client
	// compute the post-animation muzzle position. -1 means the unit has no Query
	// script, so the renderer falls back to the unit anchor. Running the query
	// also advances any per-barrel cycle the script keeps, so multi-barrel
	// weapons alternate their muzzle from shot to shot.
	FromPiece int32
	Weapon    string
	Sound     string
	SfxType   int
}

type EventKind uint8

type PieceState struct {
	Offset  fixed.Vec3 // local translation from MOVE
	Rot     [3]int32   // local rotation per axis (TA-angles) from TURN/SPIN
	Visible bool       // HIDE/SHOW state
}

type ProjectileState struct {
	ID      uint32
	Kind    string // 3DO model name the renderer draws the in-flight mesh from
	Pos     fixed.Vec3
	Heading int32
	Pitch   int32

	// Inspection fields — the studio's Projectiles panel plots a launch→aim
	// track and labels each shot by owner/weapon. They are render/debug-only
	// (never hashed), so surfacing them cannot perturb determinism.
	OwnerID  uint32
	TargetID uint32 // 0 when the shot is aimed at a fixed ground point
	Weapon   string
	Mode     string // flight behaviour: straight|dropped|vlaunch|guided|ballistic
	Vel      fixed.Vec3
	Origin   fixed.Vec3
	Target   fixed.Vec3
	Speed    fixed.Fixed
	AgeSec   fixed.Fixed
	LifeSec  fixed.Fixed
	// FromPiece is the emitter piece index the slot's Query script returned at
	// launch. The sim spawns from the unit origin (no geometry); the renderer
	// uses this to offset the in-flight mesh to the real muzzle.
	FromPiece int32
}

type QueuedOrder struct {
	Kind       uint8
	Target     fixed.Vec2 // move destination (move entries)
	TargetUnit uint32     // attack subject (attack entries)
	Name       string     // queued Build's unit type (build entries)
}

type ResourceState struct {
	Side        int
	MetalSpent  fixed.Fixed
	EnergySpent fixed.Fixed
	ManaSpent   fixed.Fixed
	MetalRate   fixed.Fixed
	EnergyRate  fixed.Fixed
	ManaRate    fixed.Fixed
	MetalStock  fixed.Fixed
	EnergyStock fixed.Fixed
	ManaStock   fixed.Fixed
	MetalCap    fixed.Fixed
	EnergyCap   fixed.Fixed
	ManaCap     fixed.Fixed
	MetalGen    fixed.Fixed
	EnergyGen   fixed.Fixed
	ManaGen     fixed.Fixed
	// Lifetime gross production, for the economy bar's totals line.
	MetalProduced  fixed.Fixed
	EnergyProduced fixed.Fixed
	ManaProduced   fixed.Fixed
}

type Snapshot struct {
	Tick   uint64
	Units  []UnitState
	Projos []ProjectileState
	Events []Event
	// Resources lists each active side's usage figures (only sides with any
	// spend or drain are included).
	Resources []ResourceState
}

type UnitState struct {
	ID           uint32
	Name         string
	Side         int
	Pos          fixed.Vec3
	Heading      int32
	Speed        fixed.Fixed // current locomotion speed (world units/sec)
	Health       fixed.Fixed // 0..100
	Dead         bool
	BuildPercent fixed.Fixed // 0..100
	IsMoving     bool
	Pieces       []PieceState
	// Current move destination + the shift-queued follow-ups, for the order
	// overlay (waypoint chain). Render-only; never hashed here.
	HasMove    bool
	MoveTarget fixed.Vec2
	Queue      []QueuedOrder
	// Production state, for the build-menu counters: the type currently
	// raising on this builder's pad (empty when idle) and the factory's
	// pending production run in click order.
	Building  string
	ProdQueue []string
	// Standing orders, for the Controls panel's Move/Fire orders rows
	// (values follow order.Move*/Fire*).
	MoveMode uint8
	FireMode uint8
	// SelfDestructMs is the remaining fuse time (0 = no fuse armed) for the
	// countdown overlay.
	SelfDestructMs int64
	// Transport links: the carrier this unit rides (0 = on the ground) and,
	// for a transport, the passengers aboard in load order.
	CarriedBy uint32
	Carrying  []uint32
}