Camera

Camera is a client-side, handle-based API for temporary camera ownership by Lua resources.

• Camera is visual-only and non-authoritative.
• Each acquired handle belongs to the calling resource.
• The newest active handle wins.

Scope

• client-only camera mode and transform control
• free camera movement for tooling/editor workflows
• safe coexistence with multiple resources

Function List

Function	Description	Scope
Camera.Acquire	Acquire a camera handle with mode/options.	C
Camera.Release	Release one camera handle.	C
Camera.GetState	Read effective camera state.	C
Camera.SetMode	Set camera mode for one owned handle (fixed / free).	C
Camera.GetMode	Read camera mode for one owned handle.	C
Camera.SetFreeOptions	Update free-camera movement/look options for one owned handle.	C
Camera.SetTransform	Set transform (position + rotation) for one owned handle.	C
Camera.GetTransform	Get current transform for one owned handle.	C
Camera.SetFov	Set FOV for one owned handle.	C
Camera.GetFov	Get FOV for one owned handle.	C
Camera.WorldToScreen	Project a world position to viewport coordinates for one active owned handle.	C
Camera.ScreenPointToRay	Build a world ray from a viewport screen position for one active owned handle.	C
Camera.RaycastElements	Raycast authored element bounds from a viewport screen position for one active owned handle.	C

Camera.Acquire

C Client Only

local handleId, err = Camera.Acquire({
  mode = "free",
  moveSpeed = 30.0,
  forwardMoveAction = "map_editor_freecam_forward:map-editor:v1",
  backwardMoveAction = "map_editor_freecam_backward:map-editor:v1",
  leftMoveAction = "map_editor_freecam_left:map-editor:v1",
  rightMoveAction = "map_editor_freecam_right:map-editor:v1",
  upMoveAction = "map_editor_freecam_up:map-editor:v1",
  downMoveAction = "map_editor_freecam_down:map-editor:v1",
  fastMultiplier = 3.0,
  fastMoveAction = "map_editor_freecam_fast:map-editor:v1",
  slowMoveAction = "map_editor_freecam_slow:map-editor:v1",
  slowMultiplier = 0.35,
  lookSensitivity = 0.2,
  fov = 75.0
})

Options:

• mode: "fixed" (default) or "free"
• position: { x, y, z } (optional)
• rotation: { x, y, z } in degrees (optional)
• fov: number (optional, clamped)
• moveSpeed: number (free mode)
• forwardMoveAction: string action name used for forward movement in free mode (default: move_forward)
• backwardMoveAction: string action name used for backward movement in free mode (default: move_backward)
• leftMoveAction: string action name used for left movement in free mode (default: move_left)
• rightMoveAction: string action name used for right movement in free mode (default: move_right)
• upMoveAction: string action name used for upward movement in free mode (default: jump)
• downMoveAction: string action name used for downward movement in free mode (default: crouch)
• fastMultiplier: number (free mode)
• fastMoveAction: string action name used as fast modifier in free mode (default: sprint)
• slowMoveAction: string action name used as slow modifier in free mode (default: none)
• slowMultiplier: number in [0.05, 1] applied while slowMoveAction is pressed (free mode)
• lookSensitivity: number (free mode)
• reason: string (optional diagnostics)

Returns:

• handleId (string | nil)
• err (nil | string)

Camera.Release

local err = Camera.Release(handleId)

Returns:

• err (nil | string)

Camera.GetState

local state, err = Camera.GetState()

Returned state fields:

• active (boolean)
• activeHandleCount (number)
• activeHandleId (string | nil)
• mode ("fixed" | "free")

Camera.SetMode / Camera.GetMode

local err = Camera.SetMode(handleId, "free")
local mode, getErr = Camera.GetMode(handleId)

Camera.SetFreeOptions

local err = Camera.SetFreeOptions(handleId, {
  moveSpeed = 30.0,
  forwardMoveAction = "map_editor_freecam_forward:map-editor:v1",
  backwardMoveAction = "map_editor_freecam_backward:map-editor:v1",
  leftMoveAction = "map_editor_freecam_left:map-editor:v1",
  rightMoveAction = "map_editor_freecam_right:map-editor:v1",
  upMoveAction = "map_editor_freecam_up:map-editor:v1",
  downMoveAction = "map_editor_freecam_down:map-editor:v1",
  fastMultiplier = 3.0,
  fastMoveAction = "map_editor_freecam_fast:map-editor:v1",
  slowMoveAction = "map_editor_freecam_slow:map-editor:v1",
  slowMultiplier = 0.35,
  lookSensitivity = 0.2
})

Updates free-camera tuning on an existing owned handle without reacquiring the camera.

Camera.SetTransform / Camera.GetTransform

local err = Camera.SetTransform(handleId, {
  position = { x = 0, y = 16, z = 0 },
  rotation = { x = -20, y = 180, z = 0 }
})

local transform, getErr = Camera.GetTransform(handleId)

GetTransform returns:

• position: { x, y, z }
• rotation: { x, y, z } in degrees

Camera.SetFov / Camera.GetFov

local err = Camera.SetFov(handleId, 70)
local fov, getErr = Camera.GetFov(handleId)

Camera.ScreenPointToRay

local ray, err = Camera.ScreenPointToRay(handleId, screenX, screenY)

Returns:

• ray.origin: { x, y, z }
• ray.direction: { x, y, z }

Notes:

• requires the handle to be currently active
• intended for editor/tool picking and local client-side queries

Camera.WorldToScreen

local point, err = Camera.WorldToScreen(handleId, {
  x = 10.0,
  y = 4.0,
  z = -22.0
})

Returns:

• point.x
• point.y
• point.visible

Notes:

• requires the handle to be currently active
• intended for editor/tool labels and other local client-side overlays

Camera.RaycastElements

local hit, err = Camera.RaycastElements(handleId, screenX, screenY, elements, {
  maxDistance = 5000.0,
  padding = 0.15,
  onlyVisible = true
})

Parameters:

• handleId (string)
• screenX (number)
• screenY (number)
• elements (table): authored element array with:
  • id
  • kind
  • objectType
  • effectiveVisible
  • worldX/worldY/worldZ or x/y/z
  • sx/sy/sz
• options (table, optional):
  • maxDistance (number)
  • padding (number)
  • onlyVisible (boolean)

Returns:

• hit (table | nil)
• err (nil | string)

hit fields:

• elementId
• distance
• ray.origin
• ray.direction

Notes:

• currently uses native bounds testing for authored editor elements
• intended for editor/tool workflows like map-editor hover/select
• this is not a deterministic world collision raycast

Free Mode Controls

Current built-in free mode input:

• move: forwardMoveAction, backwardMoveAction, leftMoveAction, rightMoveAction
• vertical: upMoveAction up, downMoveAction down
• fast move modifier: configurable via fastMoveAction (default sprint)
• slow move modifier: configurable via slowMoveAction + slowMultiplier
• look: mouse motion + right stick

Default vertical bindings are jump up and crouch down.

If a resource blocks game actions via Input.PushContext(...), it must allow these actions explicitly when free mode is intended.

Ownership Rules

• A resource can only mutate/release its own camera handles.
• Owned handles are auto-released on resource unload/disconnect.

Errors

Current error set includes:

• ERR_INVALID_HANDLE
• ERR_NOT_FOUND
• ERR_PERMISSION_DENIED
• ERR_INVALID_MODE
• ERR_INVALID_POSITION
• ERR_INVALID_ROTATION