Paths (Camera Paths)

Camera path system for cinematic playback. Creates, loads, saves, and plays spline-based camera paths with markers defining position, rotation, FOV, and timing.

Public Functions

Function	Signature	Description
`M.loadPath`	`(pathFileName) → path`	Loads a `.camPath.json` file; returns path object
`M.savePath`	`(cameraPath, filename)`	Saves a camera path to JSON
`M.getPaths`	`() → table`	Returns all loaded camera paths
`M.addPath`	`(path)`	Adds a path to the internal list (assigns unique ID)
`M.createPath`	`(name) → path`	Creates a new empty path
`M.deletePath`	`(path)`	Removes a path by name
`M.getUniquePathName`	`(name) → string`	Returns a unique name (appends counter if needed)
`M.getMarkerIds`	`(path, idx) → i1, i2, i3, i4`	Returns four marker indices for spline interpolation
`M.getEndIdx`	`(path) → number`	Returns the last valid interpolation index
`M.playPath`	`(path, offset, initData)`	Starts camera playback along the path
`M.stopCurrentPath`	`()`	Stops playback and switches to free camera
`M.getPath`	`(pathName) → path`	DEPRECATED - loads from SimPath scene objects
`M.onClientStartMission`	`()`	Auto-loads all `.camPath.json` files from the level's `camPaths/` folder
`M.onExtensionLoaded`	`()`	Lifecycle hook (no-op)
`M.onSerialize`	`() → table`	Saves paths for hot-reload
`M.onDeserialized`	`(data)`	Restores paths from serialized data

Marker Object

Field	Type	Description
`pos`	vec3	Camera position
`rot`	quat	Camera rotation
`time`	number	Time to next marker (seconds)
`fov`	number	Field of view at this marker
`trackPosition`	boolean	Track a position while moving
`positionSmooth`	number	Spline smoothing factor (default 0.5)
`bullettime`	number	Time scale multiplier (default 1.0)
`cut`	boolean	Hard cut (no interpolation)
`movingStart`	boolean	Whether movement begins at this marker
`movingEnd`	boolean	Whether movement ends at this marker

Usage Example

-- Load a camera path
local path = core_paths.loadPath("/levels/gridmap/camPaths/intro.camPath.json")

-- Play with 0 second offset
core_paths.playPath(path, 0)

-- Stop playback
core_paths.stopCurrentPath()

-- Create and save a new path
local newPath = core_paths.createPath("myPath")
table.insert(newPath.markers, {
  pos = vec3(10, 20, 5),
  rot = quat(0, 0, 0, 1),
  time = 3.0,
  fov = 60
})
core_paths.savePath(newPath, "/replays/myPath.camPath.json")

Path File Format (v6)

{
  "version": "6",
  "name": "intro",
  "looped": false,
  "manualFov": true,
  "markers": [
    {
      "pos": {"x": 10, "y": 20, "z": 5},
      "rot": {"x": 0, "y": 0, "z": 0, "w": 1},
      "time": 3.0,
      "fov": 60,
      "trackPosition": false
    }
  ]
}

Notes

Quaternion rotations are auto-fixed to avoid sign flips between consecutive markers.
Looped paths wrap marker indices using modular arithmetic.
Level camera paths are auto-loaded from <levelDir>/camPaths/*.camPath.json.
Playback uses the "path" camera mode via core_camera.setByName.

Public Functions

Function	Signature	Description
`M.loadPath`	`(pathFileName) → path`	Loads a `.camPath.json` file; returns path object
`M.savePath`	`(cameraPath, filename)`	Saves a camera path to JSON
`M.getPaths`	`() → table`	Returns all loaded camera paths
`M.addPath`	`(path)`	Adds a path to the internal list (assigns unique ID)
`M.createPath`	`(name) → path`	Creates a new empty path
`M.deletePath`	`(path)`	Removes a path by name
`M.getUniquePathName`	`(name) → string`	Returns a unique name (appends counter if needed)
`M.getMarkerIds`	`(path, idx) → i1, i2, i3, i4`	Returns four marker indices for spline interpolation
`M.getEndIdx`	`(path) → number`	Returns the last valid interpolation index
`M.playPath`	`(path, offset, initData)`	Starts camera playback along the path
`M.stopCurrentPath`	`()`	Stops playback and switches to free camera
`M.getPath`	`(pathName) → path`	DEPRECATED - loads from SimPath scene objects
`M.onClientStartMission`	`()`	Auto-loads all `.camPath.json` files from the level's `camPaths/` folder
`M.onExtensionLoaded`	`()`	Lifecycle hook (no-op)
`M.onSerialize`	`() → table`	Saves paths for hot-reload
`M.onDeserialized`	`(data)`	Restores paths from serialized data

Marker Object

Field	Type	Description
`pos`	vec3	Camera position
`rot`	quat	Camera rotation
`time`	number	Time to next marker (seconds)
`fov`	number	Field of view at this marker
`trackPosition`	boolean	Track a position while moving
`positionSmooth`	number	Spline smoothing factor (default 0.5)
`bullettime`	number	Time scale multiplier (default 1.0)
`cut`	boolean	Hard cut (no interpolation)
`movingStart`	boolean	Whether movement begins at this marker
`movingEnd`	boolean	Whether movement ends at this marker

Usage Example

-- Load a camera path
local path = core_paths.loadPath("/levels/gridmap/camPaths/intro.camPath.json")

-- Play with 0 second offset
core_paths.playPath(path, 0)

-- Stop playback
core_paths.stopCurrentPath()

-- Create and save a new path
local newPath = core_paths.createPath("myPath")
table.insert(newPath.markers, {
  pos = vec3(10, 20, 5),
  rot = quat(0, 0, 0, 1),
  time = 3.0,
  fov = 60
})
core_paths.savePath(newPath, "/replays/myPath.camPath.json")

Path File Format (v6)

{
  "version": "6",
  "name": "intro",
  "looped": false,
  "manualFov": true,
  "markers": [
    {
      "pos": {"x": 10, "y": 20, "z": 5},
      "rot": {"x": 0, "y": 0, "z": 0, "w": 1},
      "time": 3.0,
      "fov": 60,
      "trackPosition": false
    }
  ]
}

Notes

Quaternion rotations are auto-fixed to avoid sign flips between consecutive markers.
Looped paths wrap marker indices using modular arithmetic.
Level camera paths are auto-loaded from <levelDir>/camPaths/*.camPath.json.
Playback uses the "path" camera mode via core_camera.setByName.

Paths (Camera Paths)

Public Functions

Marker Object

Usage Example

Path File Format (v6)

Notes

See Also

On this page

Paths (Camera Paths)

Public Functions

Marker Object

Usage Example

Path File Format (v6)

Notes

See Also

On this page