game_object

type GameObject interface {
	common.Delegate[GameObject]

	// ID returns the object's unique identifier.
	//
	// Returns:
	//   - uint64: the object ID
	ID() uint64

	// Enabled returns whether this object is enabled for rendering.
	//
	// Returns:
	//   - bool: true if enabled
	Enabled() bool

	// Ephemeral returns whether this object is ephemeral.
	// Ephemeral objects are not persisted in the scene's registry when added.
	//
	// Returns:
	//   - bool: true if ephemeral
	Ephemeral() bool

	// Model returns the Model associated with this object, or nil if not set.
	//
	// Returns:
	//   - model.Model: the associated model or nil
	Model() model.Model

	// Animator returns the Animator associated with this object.
	//
	// Returns:
	//   - animator.Animator: the associated Animator, or nil
	Animator() animator.Animator

	// AnimatorInstanceID returns the instance index within the Animator.
	//
	// Returns:
	//   - int: the instance index, or -1 if unset
	AnimatorInstanceID() int

	// Position derives the instance's current position from the Animator.
	// Returns zeros if no Animator is set.
	//
	// Returns:
	//   - x, y, z: position components
	Position() (x, y, z float32)

	// Rotation derives the instance's current rotation from the Animator.
	// Returns zeros if no Animator is set or on skeletal backends.
	//
	// Returns:
	//   - rx, ry, rz: rotation angles
	Rotation() (rx, ry, rz float32)

	// RotationSpeed derives the instance's current rotation speed from the Animator.
	// Returns zeros if no Animator is set or on skeletal backends.
	//
	// Returns:
	//   - rx, ry, rz: rotation speed values
	RotationSpeed() (rx, ry, rz float32)

	// Scale derives the instance's current scale from the Animator.
	// Returns zeros if no Animator is set.
	//
	// Returns:
	//   - sx, sy, sz: scale components
	Scale() (sx, sy, sz float32)

	// TransformData reads all transform data from the Animator in a single pair of calls.
	// Returns zeros if no Animator is set.
	//
	// Returns:
	//   - pos: position as [3]float32 (x, y, z)
	//   - scale: scale as [3]float32 (x, y, z)
	//   - rot: rotation as [3]float32 (rx, ry, rz)
	//   - rotSpeed: rotation speed as [3]float32 (rx, ry, rz)
	TransformData() (pos, scale, rot, rotSpeed [3]float32)

	// SetID sets the object's unique identifier.
	//
	// Parameters:
	//   - id: the ID to assign
	SetID(id uint64)

	// SetEnabled sets whether the object is enabled for rendering.
	//
	// Parameters:
	//   - enabled: true to enable
	SetEnabled(enabled bool)

	// SetModel assigns a Model to this object.
	//
	// Parameters:
	//   - m: the Model to associate
	SetModel(m model.Model)

	// SetAnimator sets the Animator associated with this object.
	//
	// Parameters:
	//   - anim: the Animator to associate
	SetAnimator(anim animator.Animator)

	// SetAnimatorInstanceID sets the instance index within the Animator.
	//
	// Parameters:
	//   - instanceID: the instance index
	SetAnimatorInstanceID(instanceID int)

	// SetPosition updates the instance's position via the Animator, preserving current scale.
	//
	// Parameters:
	//   - x, y, z: new position components
	SetPosition(x, y, z float32)

	// SetRotation updates the instance's rotation via the Animator, preserving current rotation speed.
	//
	// Parameters:
	//   - rx, ry, rz: new rotation angles
	SetRotation(rx, ry, rz float32)

	// SetRotationSpeed updates the instance's rotation speed via the Animator, preserving current rotation.
	//
	// Parameters:
	//   - rx, ry, rz: new rotation speed values
	SetRotationSpeed(rx, ry, rz float32)

	// SetScale updates the instance's scale via the Animator, preserving current position.
	//
	// Parameters:
	//   - sx, sy, sz: new scale factors
	SetScale(sx, sy, sz float32)

	// Light returns the Light attached to this object, or nil if none is set.
	//
	// Returns:
	//   - light.Light: the attached light or nil
	Light() light.Light

	// SetLight attaches a Light to this object. When the object is added to a
	// scene, the scene will automatically sync the light's position from the
	// object's transform each frame. Pass nil to detach.
	//
	// Parameters:
	//   - l: the Light to attach, or nil to detach
	SetLight(l light.Light)

	// RigidBody returns the physics.RigidBody associated with this object, or nil if none is set.
	//
	// Returns:
	//   - physics.RigidBody: the associated rigid body or nil
	RigidBody() physics.RigidBody

	// SetRigidBody sets the RigidBody instance for this GameObject.
	//
	// Parameters:
	//   - rb: the RigidBody to associate with this GameObject
	SetRigidBody(rb physics.RigidBody)
}

type GameObjectBuilderOption func(*gameObject)