From 2666fa1223635261fbeb45ada7c338d2508e3df4 Mon Sep 17 00:00:00 2001
From: Victor Giers <mail@victorgiers.com>
Date: Thu, 23 Apr 2026 08:49:59 +0200
Subject: [PATCH] auto-git:  [change] src/entities/entity-instances.ts

---
 src/entities/entity-instances.ts | 96 +++++++++++++++++++++++++++++++-
 1 file changed, 93 insertions(+), 3 deletions(-)

diff --git a/src/entities/entity-instances.ts b/src/entities/entity-instances.ts
index d51238a0..2f407185 100644
--- a/src/entities/entity-instances.ts
+++ b/src/entities/entity-instances.ts
@@ -1935,6 +1935,7 @@ type RailCameraRigEntityOverrides = Partial<
     | "enabled"
     | "rigType"
     | "pathId"
+    | "railPlacementMode"
     | "priority"
     | "defaultActive"
     | "target"
@@ -1947,9 +1948,37 @@ type RailCameraRigEntityOverrides = Partial<
   lookAround?: Partial<CameraRigLookAroundSettings>;
 };
 
+type MappedRailCameraRigEntityOverrides = Partial<
+  Pick<
+    MappedRailCameraRigEntity,
+    | "id"
+    | "name"
+    | "visible"
+    | "enabled"
+    | "rigType"
+    | "pathId"
+    | "railPlacementMode"
+    | "trackStartPoint"
+    | "trackEndPoint"
+    | "railStartProgress"
+    | "railEndProgress"
+    | "priority"
+    | "defaultActive"
+    | "target"
+    | "targetOffset"
+    | "transitionMode"
+    | "transitionDurationSeconds"
+  >
+> & {
+  rigType: "rail";
+  railPlacementMode: "mapTargetBetweenPoints";
+  lookAround?: Partial<CameraRigLookAroundSettings>;
+};
+
 export type CameraRigEntityOverrides =
   | FixedCameraRigEntityOverrides
-  | RailCameraRigEntityOverrides;
+  | RailCameraRigEntityOverrides
+  | MappedRailCameraRigEntityOverrides;
 
 export function createCameraRigEntity(
   overrides: FixedCameraRigEntityOverrides
@@ -1957,6 +1986,9 @@ export function createCameraRigEntity(
 export function createCameraRigEntity(
   overrides: RailCameraRigEntityOverrides
 ): RailCameraRigEntity;
+export function createCameraRigEntity(
+  overrides: MappedRailCameraRigEntityOverrides
+): MappedRailCameraRigEntity;
 export function createCameraRigEntity(
   overrides?: CameraRigEntityOverrides
 ): CameraRigEntity;
@@ -2011,12 +2043,70 @@ export function createCameraRigEntity(
   };
 
   if (rigType === "rail") {
-    const railOverrides = overrides as RailCameraRigEntityOverrides;
+    const railOverrides = overrides as
+      | RailCameraRigEntityOverrides
+      | MappedRailCameraRigEntityOverrides;
+    const railPlacementMode =
+      railOverrides.railPlacementMode ?? DEFAULT_CAMERA_RIG_RAIL_PLACEMENT_MODE;
+
+    if (!isCameraRigRailPlacementMode(railPlacementMode)) {
+      throw new Error(
+        "Rail Camera Rig placement mode must be nearestToTarget or mapTargetBetweenPoints."
+      );
+    }
+
+    if (railPlacementMode === "mapTargetBetweenPoints") {
+      const mappedRailOverrides =
+        railOverrides as MappedRailCameraRigEntityOverrides;
+      const trackStartPoint = cloneVec3(
+        mappedRailOverrides.trackStartPoint ??
+          DEFAULT_CAMERA_RIG_TRACK_START_POINT
+      );
+      const trackEndPoint = cloneVec3(
+        mappedRailOverrides.trackEndPoint ??
+          DEFAULT_CAMERA_RIG_TRACK_END_POINT
+      );
+      const railStartProgress =
+        mappedRailOverrides.railStartProgress ??
+        DEFAULT_CAMERA_RIG_RAIL_START_PROGRESS;
+      const railEndProgress =
+        mappedRailOverrides.railEndProgress ??
+        DEFAULT_CAMERA_RIG_RAIL_END_PROGRESS;
+
+      assertFiniteVec3(trackStartPoint, "Rail Camera Rig track start point");
+      assertFiniteVec3(trackEndPoint, "Rail Camera Rig track end point");
+      assertNonNegativeFiniteNumber(
+        railStartProgress,
+        "Rail Camera Rig start progress"
+      );
+      assertNonNegativeFiniteNumber(
+        railEndProgress,
+        "Rail Camera Rig end progress"
+      );
+
+      if (railStartProgress > 1 || railEndProgress > 1) {
+        throw new Error(
+          "Rail Camera Rig mapped progress values must remain between 0 and 1."
+        );
+      }
+
+      return {
+        ...base,
+        rigType: "rail",
+        pathId: normalizeCameraRigPathId(railOverrides.pathId),
+        railPlacementMode: "mapTargetBetweenPoints",
+        trackStartPoint,
+        trackEndPoint,
+        railStartProgress,
+        railEndProgress
+      };
+    }
 
     return {
       ...base,
       rigType: "rail",
-      pathId: normalizeCameraRigPathId(railOverrides.pathId)
+      pathId: normalizeCameraRigPathId(railOverrides.pathId),
+      railPlacementMode: "nearestToTarget"
     };
   }