From abca73c7c1395259d8542f9219f6e1eeabc10341 Mon Sep 17 00:00:00 2001
From: Victor Giers <mail@victorgiers.com>
Date: Tue, 14 Apr 2026 13:39:54 +0200
Subject: [PATCH] Add actor animation playback and path follow capabilities

---
 src/controls/control-surface.ts | 43 +++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/src/controls/control-surface.ts b/src/controls/control-surface.ts
index bbbda7dd..263fc2d9 100644
--- a/src/controls/control-surface.ts
+++ b/src/controls/control-surface.ts
@@ -11,6 +11,8 @@ export const CONTROL_INTERACTION_TARGET_KINDS = [
 ] as const;
 export const CONTROL_CAPABILITY_KINDS = [
   "actorPresence",
+  "actorAnimationPlayback",
+  "actorPathFollow",
   "animationPlayback",
   "modelVisibility",
   "soundPlayback",
@@ -31,6 +33,9 @@ export type ControlInteractionTargetKind =
   (typeof CONTROL_INTERACTION_TARGET_KINDS)[number];
 export type ControlCapabilityKind = (typeof CONTROL_CAPABILITY_KINDS)[number];
 
+export const ACTOR_PATH_PROGRESS_MODES = ["deriveFromTime"] as const;
+export type ActorPathProgressMode = (typeof ACTOR_PATH_PROGRESS_MODES)[number];
+
 export interface ActorControlTargetRef {
   kind: "actor";
   actorId: string;
@@ -91,6 +96,22 @@ export interface SetActorPresenceControlEffect {
   active: boolean;
 }
 
+export interface PlayActorAnimationControlEffect {
+  type: "playActorAnimation";
+  target: ActorControlTargetRef;
+  clipName: string;
+  loop?: boolean;
+}
+
+export interface FollowActorPathControlEffect {
+  type: "followActorPath";
+  target: ActorControlTargetRef;
+  pathId: string;
+  speed: number;
+  loop: boolean;
+  progressMode: ActorPathProgressMode;
+}
+
 export interface PlayModelAnimationControlEffect {
   type: "playModelAnimation";
   target: ModelInstanceControlTargetRef;
@@ -175,6 +196,8 @@ export interface SetSunLightColorControlEffect {
 
 export type ControlEffect =
   | SetActorPresenceControlEffect
+  | PlayActorAnimationControlEffect
+  | FollowActorPathControlEffect
   | PlayModelAnimationControlEffect
   | StopModelAnimationControlEffect
   | SetModelInstanceVisibleControlEffect
@@ -257,6 +280,24 @@ export interface RuntimeResolvedActorPresenceState {
   source: RuntimeResolvedControlSource;
 }
 
+export interface RuntimeResolvedActorAnimationPlaybackState {
+  type: "actorAnimationPlayback";
+  target: ActorControlTargetRef;
+  clipName: string | null;
+  loop: boolean | undefined;
+  source: RuntimeResolvedControlSource;
+}
+
+export interface RuntimeResolvedActorPathAssignmentState {
+  type: "actorPathAssignment";
+  target: ActorControlTargetRef;
+  pathId: string | null;
+  speed: number | null;
+  loop: boolean;
+  progressMode: ActorPathProgressMode | null;
+  source: RuntimeResolvedControlSource;
+}
+
 export interface RuntimeResolvedInteractionEnabledState {
   type: "interactionEnabled";
   target: InteractionControlTargetRef;
@@ -309,6 +350,8 @@ export interface RuntimeResolvedSunLightColorState {
 
 export type RuntimeResolvedDiscreteControlState =
   | RuntimeResolvedActorPresenceState
+  | RuntimeResolvedActorAnimationPlaybackState
+  | RuntimeResolvedActorPathAssignmentState
   | RuntimeResolvedLightEnabledState
   | RuntimeResolvedInteractionEnabledState
   | RuntimeResolvedModelInstanceVisibilityState