camera

Converts 2D screen coordinates (x,y) to the 3D world-space point on the camera's near plane for that pixel. If a camera isn't specified, the last enabled camera is used.

// Place objects at the touch point.
export default defineScript({
  on_input(self, action_id, action) {
    if (action_id === hash("touch")) {
      if (action.pressed) {
        const world_position = camera.screen_xy_to_world(action.screen_x, action.screen_y);
        go.set_position(world_position, "/go1");
      }
    }
  },
});

Parameters

• x: number — X coordinate on screen.
• y: number — Y coordinate on screen.
• camera?: Url | number | nil — optional camera id

Returns

• world_pos: Vector3 — the world coordinate on the camera near plane

Converts a screen-space 2D point with view depth to a 3D world point. z is the view depth in world units measured from the camera plane along the camera forward axis. If a camera isn't specified, the last enabled camera is used.

// Place objects at the touch point with a random Z position, keeping them
// within the visible view zone.
export default defineScript({
  on_input(self, action_id, action) {
    if (action_id === hash("touch")) {
      if (action.pressed) {
        const perspective_camera = msg.url("#perspective_camera");
        const random_z = math.random(
          camera.get_near_z(perspective_camera) + 0.01,
          camera.get_far_z(perspective_camera) - 0.01,
        );
        const world_position = camera.screen_to_world(
          vmath.vector3(action.screen_x, action.screen_y, random_z),
          perspective_camera,
        );
        go.set_position(world_position, "/go1");
      }
    }
  },
});

Parameters

• pos: Vector3 — Screen-space position (x, y) with z as view depth in world units
• camera?: Url | number | nil — optional camera id

Returns

• world_pos: Vector3 — the world coordinate

Converts a 3D world position to screen-space coordinates with view depth. Returns a vector3 where x and y are in screen pixels and z is the view depth in world units measured from the camera plane along the camera forward axis. The returned z can be used with camera.screen_to_world to reconstruct the world position on the same pixel ray. If a camera isn't specified, the last enabled camera is used.

// Convert a game object position into a screen position.
go.update_world_transform("/go1");
const world_pos = go.get_world_position("/go1");
const screen_pos = camera.world_to_screen(world_pos);

Parameters

• world_pos: Vector3 — World-space position
• camera?: Url | number | nil — optional camera id

Returns

• screen_pos: Vector3 — Screen position (x,y in pixels, z is view depth)

This function returns a table with all the camera URLs that have been registered in the render context.

for (const camera_id of camera.get_cameras()) {
  render.set_camera(camera_id);
  render.draw(predicate);
  render.set_camera();
}

Returns

• cameras: Record<string | number, unknown> — a table with all camera URLs

get enabled

Parameters

• camera: Url | number | nil — camera id

Returns

• flag: boolean — true if the camera is enabled

get projection matrix

Parameters

• camera: Url | number | nil — camera id

Returns

• projection: Matrix4 — the projection matrix.

get view matrix

Parameters

• camera: Url | number | nil — camera id

Returns

• view: Matrix4 — the view matrix.

Gets the effective aspect ratio of the camera. If auto aspect ratio is enabled, returns the aspect ratio calculated from the current render target dimensions. Otherwise returns the manually set aspect ratio.

Parameters

• camera: Url | number | nil — camera id

Returns

• aspect_ratio: number — the effective aspect ratio.

get far z

Parameters

• camera: Url | number | nil — camera id

Returns

• far_z: number — the far z.

get field of view

Parameters

• camera: Url | number | nil — camera id

Returns

• fov: number — the field of view.

get near z

Parameters

• camera: Url | number | nil — camera id

Returns

• near_z: number — the near z.

get orthographic zoom

Parameters

• camera: Url | number | nil — camera id

Returns

• orthographic_zoom: number — the zoom level when the camera uses orthographic projection.

Sets the manual aspect ratio for the camera. This value is only used when auto aspect ratio is disabled. To disable auto aspect ratio and use this manual value, call camera.set_auto_aspect_ratio(camera, false).

Parameters

• camera: Url | number | nil — camera id
• aspect_ratio: number — the manual aspect ratio value.

set far z

Parameters

• camera: Url | number | nil — camera id
• far_z: number — the far z.

set field of view

Parameters

• camera: Url | number | nil — camera id
• fov: number — the field of view.

set near z

Parameters

• camera: Url | number | nil — camera id
• near_z: number — the near z.

set orthographic zoom

Parameters

• camera: Url | number | nil — camera id
• orthographic_zoom: number — the zoom level when the camera uses orthographic projection.

get orthographic zoom mode

Parameters

• camera: Url | number | nil — camera id

Returns

• mode: number — one of camera.ORTHO_MODE_FIXED, camera.ORTHO_MODE_AUTO_FIT or camera.ORTHO_MODE_AUTO_COVER

set orthographic zoom mode

Parameters

• camera: Url | number | nil — camera id
• mode: number — camera.ORTHO_MODE_FIXED, camera.ORTHO_MODE_AUTO_FIT or camera.ORTHO_MODE_AUTO_COVER

Returns whether auto aspect ratio is enabled. When enabled, the camera automatically calculates aspect ratio from render target dimensions. When disabled, uses the manually set aspect ratio value.

Parameters

• camera: Url | number | nil — camera id

Returns

• auto_aspect_ratio: boolean — true if auto aspect ratio is enabled

Enables or disables automatic aspect ratio calculation. When enabled (true), the camera automatically calculates aspect ratio from render target dimensions. When disabled (false), uses the manually set aspect ratio value.

Parameters

• camera: Url | number | nil — camera id
• auto_aspect_ratio: boolean — true to enable auto aspect ratio

Uses the manually set orthographic zoom value (camera.set_orthographic_zoom).

Computes zoom so the original display area (game.project width/height) fits inside the window while preserving aspect ratio. Equivalent to using min(window_width/width, window_height/height).

Computes zoom so the original display area covers the entire window while preserving aspect ratio. Equivalent to using max(window_width/width, window_height/height).