camera
Messages to control camera components and camera focus.
Functions
camera.get_aspect_ratio(camera?: Url | number | string | Hash): numbercamera.get_auto_aspect_ratio(camera?: Url | number | string | Hash): booleancamera.get_cameras(): Url[]camera.get_enabled(camera?: Url | number | string | Hash): booleancamera.get_far_z(camera?: Url | number | string | Hash): numbercamera.get_fov(camera?: Url | number | string | Hash): numbercamera.get_near_z(camera?: Url | number | string | Hash): numbercamera.get_orthographic_auto_zoom(camera?: Url | number | string | Hash): numberNcamera.get_orthographic_mode(camera?: Url | number | string | Hash):camera.OrthoModecamera.get_orthographic_zoom(camera?: Url | number | string | Hash): numbercamera.get_projection(camera?: Url | number | string | Hash): Matrix4camera.get_view(camera?: Url | number | string | Hash): Matrix4camera.screen_to_world(pos: Vector3, camera?: Url | number | string | Hash): Vector3camera.screen_xy_to_world(x: number, y: number, camera?: Url | number | string | Hash): Vector3camera.set_aspect_ratio(camera: Url | number | string | Hash | undefined, aspect_ratio: number): voidcamera.set_auto_aspect_ratio(camera: Url | number | string | Hash | undefined, auto_aspect_ratio: boolean): voidcamera.set_far_z(camera: Url | number | string | Hash | undefined, far_z: number): voidcamera.set_fov(camera: Url | number | string | Hash | undefined, fov: number): voidcamera.set_near_z(camera: Url | number | string | Hash | undefined, near_z: number): voidcamera.set_orthographic_mode(camera: Url | number | string | Hash | undefined, mode:camera.OrthoMode): voidcamera.set_orthographic_zoom(camera: Url | number | string | Hash | undefined, orthographic_zoom: number): voidcamera.world_to_screen(world_pos: Vector3, camera?: Url | number | string | Hash): Vector3
camera.get_aspect_ratio(camera?: Url | number | string | Hash): number
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 | string | Hash— camera id
Returns
aspect_ratio:number— the effective aspect ratio.
camera.get_auto_aspect_ratio(camera?: Url | number | string | Hash): boolean
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 | string | Hash— camera id
Returns
auto_aspect_ratio:boolean— true if auto aspect ratio is enabled
camera.get_cameras(): Url[]
This function returns a table with all the camera URLs that have been registered in the render context.
const predicate = render.predicate([hash("my_tag")]);
for (const camera_id of camera.get_cameras()) {
render.set_camera(camera_id);
render.draw(predicate);
render.set_camera();
}for k,v in pairs(camera.get_cameras()) do
render.set_camera(v)
render.draw(...)
render.set_camera()
endReturns
cameras:Url[]— a table with all camera URLs
camera.get_enabled(camera?: Url | number | string | Hash): boolean
get enabled
Parameters
camera?:Url | number | string | Hash— camera id
Returns
flag:boolean— true if the camera is enabled
camera.get_far_z(camera?: Url | number | string | Hash): number
get far z
Parameters
camera?:Url | number | string | Hash— camera id
Returns
far_z:number— the far z.
camera.get_fov(camera?: Url | number | string | Hash): number
get field of view
Parameters
camera?:Url | number | string | Hash— camera id
Returns
fov:number— the field of view.
camera.get_near_z(camera?: Url | number | string | Hash): number
get near z
Parameters
camera?:Url | number | string | Hash— camera id
Returns
near_z:number— the near z.
camera.get_orthographic_auto_zoom(camera?: Url | number | string | Hash): numberN
- Since Defold 1.13.0
Gets the orthographic zoom calculated from the current window and project dimensions in auto-fit and auto-cover modes. Returns 1.0 in fixed mode.
Parameters
camera?:Url | number | string | Hash— camera id
Returns
orthographic_auto_zoom:number— the calculated orthographic auto zoom.
camera.get_orthographic_mode(camera?: Url | number | string | Hash): camera.OrthoMode
get orthographic zoom mode
Parameters
camera?:Url | number | string | Hash— camera id
Returns
camera.get_orthographic_zoom(camera?: Url | number | string | Hash): number
Gets the positive user-controlled orthographic zoom multiplier. In auto-fit and auto-cover modes, this value is multiplied with camera.get_orthographic_auto_zoom(camera).
Parameters
camera?:Url | number | string | Hash— camera id
Returns
orthographic_zoom:number— the positive zoom multiplier when the camera uses orthographic projection.
camera.get_projection(camera?: Url | number | string | Hash): Matrix4
get projection matrix
Parameters
camera?:Url | number | string | Hash— camera id
Returns
projection:Matrix4— the projection matrix.
camera.get_view(camera?: Url | number | string | Hash): Matrix4
get view matrix
Parameters
camera?:Url | number | string | Hash— camera id
Returns
view:Matrix4— the view matrix.
camera.screen_to_world(pos: Vector3, camera?: Url | number | string | Hash): Vector3
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 && action.screen_x !== undefined && action.screen_y !== undefined) {
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");
}
}
},
}); function on_input(self, action_id, action)
if action_id == hash("touch") then
if action.pressed then
local percpective_camera = msg.url("#perspective_camera")
local random_z = math.random(camera.get_near_z(percpective_camera) + 0.01, camera.get_far_z(percpective_camera) - 0.01)
local world_position = camera.screen_to_world(vmath.vector3(action.screen_x, action.screen_y, random_z), percpective_camera)
go.set_position(world_position, "/go1")
end
end
endParameters
pos:Vector3— Screen-space position (x, y) with z as view depth in world unitscamera?:Url | number | string | Hash— optional camera id
Returns
world_pos:Vector3— the world coordinate
camera.screen_xy_to_world(x: number, y: number, camera?: Url | number | string | Hash): Vector3
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 && action.screen_x !== undefined && action.screen_y !== undefined) {
const world_position = camera.screen_xy_to_world(action.screen_x, action.screen_y);
go.set_position(world_position, "/go1");
}
}
},
}); function on_input(self, action_id, action)
if action_id == hash("touch") then
if action.pressed then
local world_position = camera.screen_xy_to_world(action.screen_x, action.screen_y)
go.set_position(world_position, "/go1")
end
end
endParameters
x:number— X coordinate on screen.y:number— Y coordinate on screen.camera?:Url | number | string | Hash— optional camera id
Returns
world_pos:Vector3— the world coordinate on the camera near plane
camera.set_aspect_ratio(camera: Url | number | string | Hash | undefined, aspect_ratio: number): void
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 | string | Hash | undefined— camera idaspect_ratio:number— the manual aspect ratio value.
camera.set_auto_aspect_ratio(camera: Url | number | string | Hash | undefined, auto_aspect_ratio: boolean): void
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 | string | Hash | undefined— camera idauto_aspect_ratio:boolean— true to enable auto aspect ratio
camera.set_far_z(camera: Url | number | string | Hash | undefined, far_z: number): void
set far z
Parameters
camera:Url | number | string | Hash | undefined— camera idfar_z:number— the far z.
camera.set_fov(camera: Url | number | string | Hash | undefined, fov: number): void
set field of view
Parameters
camera:Url | number | string | Hash | undefined— camera idfov:number— the field of view.
camera.set_near_z(camera: Url | number | string | Hash | undefined, near_z: number): void
set near z
Parameters
camera:Url | number | string | Hash | undefined— camera idnear_z:number— the near z.
camera.set_orthographic_mode(camera: Url | number | string | Hash | undefined, mode: camera.OrthoMode): void
set orthographic zoom mode
Parameters
camera:Url | number | string | Hash | undefined— camera idmode:camera.OrthoMode— camera.ORTHO_MODE_FIXED, camera.ORTHO_MODE_AUTO_FIT or camera.ORTHO_MODE_AUTO_COVER
camera.set_orthographic_zoom(camera: Url | number | string | Hash | undefined, orthographic_zoom: number): void
Sets the positive user-controlled orthographic zoom multiplier. In auto-fit and auto-cover modes, this value is multiplied with camera.get_orthographic_auto_zoom(camera).
Parameters
camera:Url | number | string | Hash | undefined— camera idorthographic_zoom:number— the positive zoom multiplier when the camera uses orthographic projection.
camera.world_to_screen(world_pos: Vector3, camera?: Url | number | string | Hash): Vector3
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); go.update_world_transform("/go1")
local world_pos = go.get_world_position("/go1")
local screen_pos = camera.world_to_screen(world_pos)Parameters
world_pos:Vector3— World-space positioncamera?:Url | number | string | Hash— optional camera id
Returns
screen_pos:Vector3— Screen position (x,y in pixels, z is view depth)
Constants
camera.ORTHO_MODE_AUTO_COVER: number & { readonly __brand: "camera.ORTHO_MODE_AUTO_COVER" }
auto-cover orthographic zoom mode 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). The result is multiplied by the user-controlled orthographic zoom.
camera.ORTHO_MODE_AUTO_FIT: number & { readonly __brand: "camera.ORTHO_MODE_AUTO_FIT" }
auto-fit orthographic zoom mode 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). The result is multiplied by the user-controlled orthographic zoom.
camera.ORTHO_MODE_FIXED: number & { readonly __brand: "camera.ORTHO_MODE_FIXED" }
fixed orthographic zoom mode Uses the manually set orthographic zoom value (camera.set_orthographic_zoom).
Properties
aspect_ratio: numberN
- Since Defold 1.13.0
The ratio between the frustum width and height. Used when calculating the projection of a perspective camera. The type of the property is number.
far_z: numberN
- Since Defold 1.13.0
Camera frustum far plane. The type of the property is float.
fov: numberN
- Since Defold 1.13.0
Vertical field of view of the camera. The type of the property is float.
near_z: numberN
- Since Defold 1.13.0
Camera frustum near plane. The type of the property is float.
orthographic_auto_zoom: numberN
- Since Defold 1.13.0
READ ONLY The zoom calculated from the current window and project dimensions in auto fit and auto cover modes. The value is 1.0 in fixed mode. The type of the property is float.
orthographic_zoom: numberN
- Since Defold 1.13.0
Positive zoom multiplier when using an orthographic projection. In auto fit and auto cover modes, this value is multiplied with the calculated orthographic_auto_zoom value. The type of the property is float.
projection: Matrix4N
- Since Defold 1.13.0
READ ONLY The calculated projection matrix of the camera. The type of the property is matrix4.
view: Matrix4N
- Since Defold 1.13.0
READ ONLY The calculated view matrix of the camera. The type of the property is matrix4.