gatos.vessel_control

tool Logical controls

Apply one logical vessel-level flight, focus, or rendering operation.

Use when: Changing a whole-vessel setpoint or mode without using a raw canonical action envelope.
Availability: Most operations require control_enabled and vessel authority; focus, scale, always_render, and debug take-control have specialized gates.

Input

Field	Type	Requirement	Description
`operation`	`string`	Required	Operation listed below or a dotted canonical action.
`vessel_id`	`string`	Required	Raw target vessel id.
`ordinal`	`integer`	Optional · -1	Normally unused; forwarded for canonical operations.
`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.

`ignite | shutdown | stage`

Canonical action: vessel.ignite | vessel.shutdown | vessel.stage

One-shot engine or staging triggers. Omitted payload fields keep their defaults and are ignored.

Arguments for this operation

{ operation, vessel_id }

Example

gatos.vessel_control({"operation":"stage","vessel_id":"Hunter"})

`engine_master | lights | rcs | always_render`

Canonical action: vessel.engine | vessel.lights | vessel.rcs | vessel.always_render

Set a vessel-wide flag. engine_master maps to vessel.engine.

Arguments for this operation

{ operation, vessel_id, value: 0 | 1 }

Example

gatos.vessel_control({"operation":"rcs","vessel_id":"Hunter","value":1})

`throttle`

Canonical action: vessel.throttle

Set manual throttle as a normalized fraction.

Arguments for this operation

{ operation: "throttle", vessel_id, value: number  // 0..1 }

Example

gatos.vessel_control({"operation":"throttle","vessel_id":"Hunter","value":0.72})

`translate | rotate`

Canonical action: vessel.translate | vessel.rotate

Latch body-axis bang-bang RCS commands. Write [0,0,0] to stop; rcs_mode must be Enabled.

Arguments for this operation

{ operation, vessel_id, values: [x, y, z]  // signs; magnitudes ignored }

Example

gatos.vessel_control({"operation":"translate","vessel_id":"Hunter","values":[1,0,-1]})

`rcs_mode`

Canonical action: vessel.rcs_mode

Set the flight computer's RCS master switch. This is distinct from the vessel rcs flag.

Arguments for this operation

{ operation: "rcs_mode", vessel_id, token: "Enabled" | "Disabled" }

Example

gatos.vessel_control({"operation":"rcs_mode","vessel_id":"Hunter","token":"Enabled"})

`attitude_mode`

Canonical action: vessel.attitude_mode

Choose manual control or a named flight-computer tracking mode. Matching is case-insensitive.

Arguments for this operation

{ operation: "attitude_mode", vessel_id, token: "manual" | "StabilityAssist" | "Prograde" | "Retrograde" | "Normal" | "AntiNormal" | "RadialIn" | "RadialOut" | "Target" | "AntiTarget" | "Maneuver" }

Example

gatos.vessel_control({"operation":"attitude_mode","vessel_id":"Hunter","token":"Prograde"})

`attitude_frame`

Canonical action: vessel.attitude_frame

Set the reference frame used by named attitude modes.

Arguments for this operation

{ operation: "attitude_frame", vessel_id, token: "Inertial" | "Orbital" | "Surface" | "Target" }

Example

gatos.vessel_control({"operation":"attitude_frame","vessel_id":"Hunter","token":"Orbital"})

`attitude_target`

Canonical action: vessel.attitude_target

Set a Body-to-CCI quaternion. The quaternion norm must be valid for the game actuator.

Arguments for this operation

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

Example

gatos.vessel_control({"operation":"attitude_target","vessel_id":"Hunter","values":[0,0,0,1]})

`burn`

Canonical action: vessel.burn

Set a flight-computer burn at absolute UT with a parent-body CCI delta-v in m/s.

Arguments for this operation

{ operation: "burn", vessel_id, values: [ut_seconds, dv_x, dv_y, dv_z] }

Example

gatos.vessel_control({"operation":"burn","vessel_id":"Hunter","values":[12840,0,12.5,0]})

`scale`

Canonical action: vessel.scale

Set session render scale. Value 1 restores ordinary scale.

Arguments for this operation

{ operation: "scale", vessel_id, value: number  // finite and > 0 }

Example

gatos.vessel_control({"operation":"scale","vessel_id":"Hunter","value":25})

`focus | take_control`

Canonical action: camera.focus | debug.control_vessel

Focus is view-only; take_control changes the player-controlled vessel and is a debug action.

Arguments for this operation

{ operation, vessel_id }

Example

gatos.vessel_control({"operation":"focus","vessel_id":"Hunter"})

Call example

gatos.vessel_control({"operation":"throttle","vessel_id":"Hunter","value":0.72})

Result

The compiled canonical action and command outcome with current freshness metadata.

Errors

EINVAL for an unknown operation or invalid shape/value; ENOENT for a missing vessel; EACCES for gate/authority denial.

Operational notes

Check controllable before normal flight control; KSA may ignore commands to an uncontrollable vessel.