gatos.camera_control

tool Camera and media

Own and direct gatOS's programmable camera.

Use when: Framing a shot, following an entity, changing projection, or controlling camera playback.
Availability: camera_enabled; playback also requires schedule_enabled. IVA and Map ownership contexts remain unsupported.

Input

Field	Type	Requirement	Description
`operation`	`string`	Required	Logical operation listed below. A dotted canonical action is also accepted.
`value`	`number`	Optional · 0	Operation-specific scalar.
`values`	`number[] \| null`	Optional · null	Operation-specific numeric vector.
`token`	`string \| null`	Optional · null	Operation-specific named value.
`aux`	`string \| null`	Optional · null	Operation-specific secondary value.

Operation call shapes

Choose an operation below. Its required payload and a complete call stay together—there is no second table to cross-reference.

`ownership | take`

Canonical action: camera.enabled

Take ownership with 1 or perform the configured eased hand-back with 0.

Arguments for this operation

{ operation, value: 0 | 1 }

Example

gatos.camera_control({"operation":"ownership","value":1})

`release | reset | stop`

Canonical action: camera.release | camera.pose_reset | camera.stop

One-shot hard release, pose-override reset, or camera-player stop.

Arguments for this operation

{ operation }

Example

gatos.camera_control({"operation":"release"})

`mode`

Canonical action: camera.mode

Change the game's camera mode while gatOS does not own the camera.

Arguments for this operation

{ operation: "mode", token: "orbit" | "free" | "map" | "iva" | "fixed" }

Example

gatos.camera_control({"operation":"mode","token":"fixed"})

`follow | anchor | aim_target`

Canonical action: camera.follow | camera.anchor | camera.aim_target

Set a target reference. follow does not accept part targets; anchor does.

Arguments for this operation

{ operation, token: "vessel:<id>" | "body:<id>" | "part:<vessel>/<instance_id>" | "none" }

Example

gatos.camera_control({"operation":"anchor","token":"vessel:Hunter"})

`tidal | ortho`

Canonical action: camera.tidal | camera.ortho

Set a boolean game-camera or projection channel.

Arguments for this operation

{ operation, value: 0 | 1 }

Example

gatos.camera_control({"operation":"ortho","value":1})

`map_scope | orbit_radius | orbit_azimuth | orbit_elevation | roll | fov | ortho_height | smoothing`

Canonical action: camera.*

Set one scalar. Units/ranges: map_scope and radii/heights are metres; azimuth/elevation/roll/fov are degrees; smoothing is 0..10 seconds.

Arguments for this operation

{ operation, value: number }

Example

gatos.camera_control({"operation":"smoothing","value":0.35})

`position | aim_offset`

Canonical action: camera.position | camera.aim_offset

Set a three-vector. position may carry a placement-frame token; aim_offset uses the current aim frame.

Arguments for this operation

{ operation, values: [x, y, z], token?: frame }

Example

gatos.camera_control({"operation":"position","values":[-40,0,-6],"token":"bodyfixed"})

`frame | aim_frame`

Canonical action: camera.frame | camera.aim_frame

Select the placement or aim-offset reference frame.

Arguments for this operation

{ operation, token: "ecl" | "cce" | "bodyfixed" | "enu" | "lvlh" | "chase" }

Example

gatos.camera_control({"operation":"frame","token":"bodyfixed"})

`geodetic`

Canonical action: camera.geo

Place over terrain on an explicit body or the current body anchor.

Arguments for this operation

{ operation: "geodetic", values: [lat_deg, lon_deg, altitude_m], token?: "body:<id>" }

Example

gatos.camera_control({"operation":"geodetic","values":[12.5,-42,800],"token":"body:Kerbin"})

`rotation`

Canonical action: camera.rotation

Set an explicit camera quaternion; valid norm is 0.5..2.

Arguments for this operation

{ operation: "rotation", values: [x, y, z, w] }

Example

gatos.camera_control({"operation":"rotation","values":[0,0,0,1]})

`aim`

Canonical action: camera.aim

Set the complete aim constraint. Frame ordinals 0..5 are ecl/cce/bodyfixed/enu/lvlh/chase; up ordinals 0..3 are world/target/velocity/free.

Arguments for this operation

{ operation: "aim", token: target_ref, values: [off_x, off_y, off_z, frame_ordinal, up_ordinal, roll_deg, roll_present] }

Example

gatos.camera_control({"operation":"aim","token":"vessel:Hunter","values":[0,0,-1.2,2,0,0,0]})

`aim_up`

Canonical action: camera.aim_up

Choose the camera aim up-reference.

Arguments for this operation

{ operation: "aim_up", token: "world" | "target" | "velocity" | "free" }

Example

gatos.camera_control({"operation":"aim_up","token":"world"})

`play`

Canonical action: camera.play

Start a stored track. Track time is seconds and schedule_enabled is also required.

Arguments for this operation

{ operation: "play", token: track_name, aux?: group, values?: [at_s, rate, loop, at_present, rate_present, loop_present] }

Example

gatos.camera_control({"operation":"play","token":"launch","values":[0,1,0,0,0,0]})

`set`

Canonical action: camera.set

Patch the active camera player with flat numeric key/value pairs.

Arguments for this operation

{ operation: "set", values: [key, value, ...]  // 0=t_s, 1=rate, 2=loop, 3=paused }

Example

gatos.camera_control({"operation":"set","values":[3,1]})

Call example

gatos.camera_control({"operation":"aim_target","token":"Hunter"})

Result

Camera command result correlated to current snapshot state.

Errors

EOPNOTSUPP when camera/schedule support is disabled; EBUSY when ownership context cannot be taken; EINVAL for invalid frame or values.

Operational notes

KSA vectors use the documented CCI/body frames.
Orthographic height cannot be restored after giving ownership back.