### Install Defold Orthographic Library

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Add the library as a Defold dependency in your game.project file.

```ini
[project]
dependencies#0 = https://github.com/britzl/defold-orthographic/archive/master.zip
```

--------------------------------

### Multi-Camera Render Script Integration

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Example usage pattern for the bundled orthographic.render_script, demonstrating how to handle multiple cameras, set viewports, and draw GUI elements in screen space.

```lua
-- orthographic/render/orthographic.render_script (abridged usage pattern)
local camera = require "orthographic.camera"

function update(self)
    render.clear({[render.BUFFER_COLOR_BIT] = self.clear_color,
                  [render.BUFFER_DEPTH_BIT] = 1,
                  [render.BUFFER_STENCIL_BIT] = 0})

    local cameras = camera.get_cameras()
    for _, camera_id in ipairs(cameras) do
        local viewport = camera.get_viewport(camera_id)
        render.set_viewport(viewport.x, viewport.y, viewport.z, viewport.w)
        render.set_view(camera.get_view(camera_id))
        local proj = camera.get_projection(camera_id)
        render.set_projection(proj)
        local frustum = proj * camera.get_view(camera_id)
        render.draw(self.tile_pred,     { frustum = frustum })
        render.draw(self.particle_pred, { frustum = frustum })
    end

    -- Draw GUI in screen space (full window, identity view, orthographic projection)
    local ww, wh = render.get_window_width(), render.get_window_height()
    render.set_viewport(0, 0, ww, wh)
    render.set_view(vmath.matrix4())
    render.set_projection(vmath.matrix4_orthographic(0, ww, 0, wh, -1, 1))
    render.draw(self.gui_pred)
end
```

--------------------------------

### Get Display Size

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Retrieves the display size as configured in game.project.

```lua
local width, height = camera.get_display_size()
```

--------------------------------

### Get Camera Zoom with go.get

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Use go.get to retrieve the camera's current zoom level. Specify the URL to the camera script.

```lua
local zoom = go.get("mycamera#camerascript", "zoom")

```

--------------------------------

### Get Window and Display Sizes

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Obtain the current physical window pixel size and the logical display size defined in game.project. Useful for calculating DPI scale factors.

```lua
local camera = require "orthographic.camera"

local win_w, win_h = camera.get_window_size()
local dis_w, dis_h = camera.get_display_size()

print(("window: %dx%d"):format(win_w, win_h))   -- e.g. window: 2560x1440 (HiDPI)
print(("display: %dx%d"):format(dis_w, dis_h))  -- e.g. display: 1280x720

-- Compute DPI scale factor
local scale = win_w / dis_w
print("dpi scale:", scale)  -- e.g. 2.0 on Retina displays
```

--------------------------------

### Get List of Cameras

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Retrieve a list of all active cameras, sorted by their 'order' property.

```lua
local cameras = camera.get_cameras()

```

--------------------------------

### Get Current Window Size

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Retrieves the current dimensions of the game window. Defaults are set in game.project.

```lua
local width, height = camera.get_window_size()
```

--------------------------------

### Get Camera Size

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Retrieve the current size of the camera's view in pixels.

```lua
local size = camera.get_size(self.camera_id)

```

--------------------------------

### Get Camera Zoom with camera.get_zoom

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Retrieve the camera's current zoom level using the camera.get_zoom function.

```lua
local zoom = camera.get_zoom(self.camera_id)

```

--------------------------------

### Get All Active Cameras

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Retrieves an ordered list of enabled camera IDs. This is essential for render scripts to iterate through all active cameras each frame.

```lua
local camera = require "orthographic.camera"

-- In a custom render script
local cameras = camera.get_cameras()
print("active cameras:", #cameras)
-- { hash("/camera1"), hash("/camera2"), ... }
```

--------------------------------

### Get visible world bounds

Source: https://context7.com/britzl/defold-orthographic/llms.txt

The `screen_to_world_bounds` function returns the four world-space corners of the screen as a `vector4` (left, top, right, bottom). This is useful for culling objects outside the visible area or for coordinate overlays.

```lua
local camera = require "orthographic.camera"

local CAMERA_ID = hash("/camera")

function update(self, dt)
    local bounds = camera.screen_to_world_bounds(CAMERA_ID)
    -- bounds.x = left world edge visible on screen
    -- bounds.y = top world edge
    -- bounds.z = right world edge
    -- bounds.w = bottom world edge

    -- Display corners in GUI
    gui.set_text(gui.get_node("bottom_left"),  ("%d,%d"):format(bounds.x, bounds.w))
    gui.set_text(gui.get_node("bottom_right"), ("%d,%d"):format(bounds.z, bounds.w))
    gui.set_text(gui.get_node("top_left"),     ("%d,%d"):format(bounds.x, bounds.y))
    gui.set_text(gui.get_node("top_right"),    ("%d,%d"):format(bounds.z, bounds.y))
end
```

--------------------------------

### camera.deadzone

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Defines a rectangular region around the camera's current position inside which the camera does not move. The camera only starts following when the target reaches the edge of the deadzone. Pass no size arguments (or all nils) to remove the deadzone.

```APIDOC
## camera.deadzone(camera_id, left, top, right, bottom)

### Description
Defines a rectangular region around the camera's current position inside which the camera does not move. The camera only starts following when the target reaches the edge of the deadzone. Pass no size arguments (or all nils) to remove the deadzone.

### Parameters
#### Path Parameters
- **camera_id** (hash) - Required - The ID of the camera component.
- **left** (number) - Optional - The width of the deadzone on the left side.
- **top** (number) - Optional - The height of the deadzone on the top side.
- **right** (number) - Optional - The width of the deadzone on the right side.
- **bottom** (number) - Optional - The height of the deadzone on the bottom side.

### Request Example
```lua
local camera = require "orthographic.camera"
local CAMERA_ID = hash("/camera")

-- Set a 200x160 deadzone
camera.deadzone(CAMERA_ID, 100, 80, 100, 80)

-- Remove the deadzone
camera.deadzone(CAMERA_ID)
```

### Message Equivalent
```
msg.post("/camera", "deadzone", { left = 100, right = 100, bottom = 80, top = 80 })
msg.post("/camera", "deadzone", {})
```
```

--------------------------------

### Control Camera Zoom Level

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Reads or sets the camera zoom level. A zoom of 2 makes objects appear twice as large, while 0.5 zooms out to half size. Zoom can be animated using `go.animate` for smooth transitions. Includes examples for direct API calls, input handling, and message equivalents.

```lua
local camera = require "orthographic.camera"

local CAMERA_ID = hash("/camera")

-- Read current zoom
local zoom = camera.get_zoom(CAMERA_ID)
print("current zoom:", zoom)  -- e.g. 1.0

-- Set zoom directly
camera.set_zoom(CAMERA_ID, 2.0)

-- Zoom in/out incrementally (e.g., from mouse wheel input)
local function on_input(self, action_id, action)
    if action_id == hash("zoom_in") then
        local z = camera.get_zoom(CAMERA_ID)
        camera.set_zoom(CAMERA_ID, math.min(4, z + 0.05))
    elseif action_id == hash("zoom_out") then
        local z = camera.get_zoom(CAMERA_ID)
        camera.set_zoom(CAMERA_ID, math.max(0.2, z - 0.05))
    end
end

-- Animate zoom via go.animate (target the script component URL)
go.animate("mycamera#camerascript", "zoom", go.PLAYBACK_ONCE_FORWARD, 2.5, go.EASING_OUTQUAD, 1.0)

-- Message equivalent
msg.post("/camera", "zoom_to", { zoom = 2.5 })
```

--------------------------------

### Enable Camera by Message

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Enable a camera by sending it an 'enable' message.

```lua
msg.post(self.camera_id, "enable")

```

--------------------------------

### Follow Target with Camera

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Make the camera follow a specified game object. Configure follow_horizontal, follow_vertical, follow_immediately, follow_lerp, and follow_offset.

```lua
camera.follow(self.camera_id, self.follow_target, self.follow_horizontal, self.follow_vertical, self.follow_immediately, self.follow_lerp, self.follow_offset)

```

--------------------------------

### camera.follow

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Configures the camera to follow one or more game objects, optionally with offset and interpolation.

```APIDOC
## camera.follow(camera_id, targets, [options])

### Description
Follow one or more game objects. When following multiple objects the camera will follow the center point between the objects.

### Parameters
#### Path Parameters
* `camera_id` (hash|url|nil) - nil for the first camera
* `targets` (hash|url|table) - Game object(s) to follow
* `options` (table) - Optional. Options (see below)

Acceptable values for the `options` table:

* `lerp` (number) - Lerp from current position to target position with `lerp` as t.
* `offset` (vector3) - Camera offset from target position.
* `horizontal` (boolean) - True if following the target along the horizontal axis.
* `vertical` (boolean) - True if following the target along the vertical axis.
* `immediate` (boolean) - True if the camera should be immediately positioned on the target even when lerping.
```

--------------------------------

### Add Defold Library Dependency

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Add this project as a Defold library dependency in your game.project file.

```plaintext
https://github.com/britzl/defold-orthographic/archive/master.zip
```

--------------------------------

### Camera Follow API - Smooth Lerp and Offset

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Configure smooth following with lerp and apply an offset to the follow target. Set horizontal and vertical axes independently.

```lua
local camera = require "orthographic.camera"

local CAMERA_ID = hash("/camera")
local PLAYER_ID = hash("/player")

-- Follow with smooth lerp, horizontal axis only
camera.follow(CAMERA_ID, PLAYER_ID, {
    lerp       = 0.1,
    horizontal = true,
    vertical   = false,
    offset     = vmath.vector3(0, 100, 0),  -- look 100px ahead vertically
})
```

--------------------------------

### Set Render Script in game.project

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Configure your game.project file to use the bundled orthographic render script.

```ini
[bootstrap]
render = /orthographic/render/orthographic.renderc
```

--------------------------------

### Camera Follow Message Equivalent

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Control camera following using Defold's message passing system. This is an alternative to the Lua API.

```lua
msg.post("/camera", "follow", {
    target     = PLAYER_ID,
    lerp       = 0.7,
    horizontal = true,
    vertical   = true,
    immediate  = false,
})
```

--------------------------------

### Set Camera Zoom with go.set

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Use go.set to directly set the camera's zoom level. Specify the URL to the camera script.

```lua
go.set("mycamera#camerascript", "zoom", 2.0)

```

--------------------------------

### Enable/Disable Camera with go.set

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Toggle the camera's enabled state using go.set. Set the 'enable' property to true or false.

```lua
go.set(camera_id, "enable", true)

```

--------------------------------

### camera.follow

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Configures the camera to follow a target. This is a message-based command.

```APIDOC
## camera.follow (message)

### Description
Message equivalent to `camera.follow()`. Accepted message keys: `target`, `lerp`, `horizontal`, `vertical`, `immediate`, `offset`.

### Message Example
```
msg.post("camera", "follow", { target = hash("player"), lerp = 0.7, horizontal = true, vertical = false, immediate = true })
```
```

--------------------------------

### camera.get_window_size() / camera.get_display_size()

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Obtains the dimensions of the game window and the logical display size defined in the game project settings.

```APIDOC
## camera.get_window_size() / camera.get_display_size()

### Description
`get_window_size()` returns the current physical window pixel dimensions, which are updated each frame. `get_display_size()` returns the logical display size as defined in `game.project`.

### Returns
- `number` - The width of the window/display.
- `number` - The height of the window/display.
```

--------------------------------

### Set Camera Bounds

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Configure the camera's bounding box by setting the bounds_left, bounds_right, bounds_top, and bounds_bottom properties.

```lua
camera.bounds(self.camera_id, bounds_left, bounds_right, bounds_top, bounds_bottom)

```

--------------------------------

### Camera Follow API - Single Target

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Use the Lua API to make the camera track a single game object. Options like 'immediate' control smoothing.

```lua
local camera = require "orthographic.camera"

local CAMERA_ID = hash("/camera")
local PLAYER_ID = hash("/player")

-- Follow a single target immediately, no smoothing
camera.follow(CAMERA_ID, PLAYER_ID, { immediate = true })
```

--------------------------------

### Camera Follow API - Multiple Targets

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Make the camera follow multiple targets by providing a table of their IDs. The camera will center on their average position.

```lua
local camera = require "orthographic.camera"

local CAMERA_ID = hash("/camera")
local PLAYER_ID = hash("/player")
local ENEMY_ID  = hash("/enemy")

-- Follow multiple targets (camera centers between them)
camera.follow(CAMERA_ID, { PLAYER_ID, ENEMY_ID })
```

--------------------------------

### Access camera view, projection, and viewport matrices

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Retrieve the current view matrix, projection matrix, and viewport rectangle using `get_view`, `get_projection`, and `get_viewport`. These values are crucial for custom render scripts or manual frustum culling.

```lua
local camera = require "orthographic.camera"

local CAMERA_ID = hash("/camera")

-- Read matrices (e.g., for a custom render script or manual frustum culling)
local view       = camera.get_view(CAMERA_ID)
local projection = camera.get_projection(CAMERA_ID)
local viewport   = camera.get_viewport(CAMERA_ID)
-- viewport is a vector4: x=left, y=bottom, z=width, w=height

-- Manual frustum culling in a custom render script
local cameras = camera.get_cameras()
for _, cam_id in ipairs(cameras) do
    local vp   = camera.get_viewport(cam_id)
    local v    = camera.get_view(cam_id)
    local p    = camera.get_projection(cam_id)
    render.set_viewport(vp.x, vp.y, vp.z, vp.w)
    render.set_view(v)
    render.set_projection(p)
    local frustum = p * v
    render.draw(tile_pred, { frustum = frustum })
end
```

--------------------------------

### Set Camera Viewport

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Configure the camera's viewport using the viewport_left, viewport_right, viewport_top, and viewport_bottom properties.

```lua
camera.viewport(self.camera_id, viewport_left, viewport_right, viewport_top, viewport_bottom)

```

--------------------------------

### Send Follow Message

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Configures the camera to follow a specific target. Allows control over lerp speed, axis constraints, and immediate updates.

```lua
msg.post("camera", "follow", { target = hash("player"), lerp = 0.7, horizontal = true, vertical = false, immediate = true })
```

--------------------------------

### Send Enable Camera Message

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Activates the camera component. When enabled, the camera updates its view and projection, sending them to the render script.

```lua
msg.post("camera", "enable")
```

--------------------------------

### Camera Script Properties

Source: https://context7.com/britzl/defold-orthographic/llms.txt

These properties are configurable in the Defold editor for the camera.script component.

```lua
-- camera.script exposes these go.property values:
go.property("near_z", -1)           -- near clipping plane
go.property("far_z", 1)             -- far clipping plane
go.property("zoom", 1)              -- zoom level (1 = no zoom)
go.property("automatic_zoom", false)-- auto-fit zoom to display size
go.property("enabled", true)        -- camera active by default
go.property("order", 1)             -- render order across multiple cameras

go.property("follow", false)
go.property("follow_horizontal", true)
go.property("follow_vertical", true)
go.property("follow_immediately", false)
go.property("follow_target", hash(""))
go.property("follow_lerp", 0.5)
go.property("follow_offset", vmath.vector3(0, 0, 0))

go.property("bounds_left", 0)
go.property("bounds_bottom", 0)
go.property("bounds_right", 0)
go.property("bounds_top", 0)

go.property("deadzone_left", 0)
go.property("deadzone_bottom", 0)
go.property("deadzone_right", 0)
go.property("deadzone_top", 0)

go.property("viewport_left", 0)    -- 0 means "use full window"
go.property("viewport_bottom", 0)
go.property("viewport_right", 0)
go.property("viewport_top", 0)
```

--------------------------------

### camera.enable

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Enables the camera, causing it to update its view and projection. This is a message-based command.

```APIDOC
## camera.enable (message)

### Description
Enable the camera. While the camera is enabled it will update it's view and projection and send these to the render script.

### Message Example
```
msg.post("camera", "enable")
```
```

--------------------------------

### camera.get_display_size

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Retrieves the display size as configured in the game.project file.

```APIDOC
## camera.get_display_size()

### Description
Get the display size, as specified in game.project.

### Return
#### Success Response
- **width** (number) - Display width.
- **height** (number) - Display height.
```

--------------------------------

### Set Camera Zoom with go.animate

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Use go.animate to smoothly change the camera's zoom level. Ensure you specify the URL to the camera script, not the game object.

```lua
go.animate("mycamera#camerascript", "zoom", 10, 2.0, go.EASING_LINEAR)

```

--------------------------------

### camera.follow_offset

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Sets an offset for the camera's follow behavior. This is a message-based command.

```APIDOC
## camera.follow_offset (message)

### Description
Message equivalent to `camera.follow_offset()`. Accepted message keys: `offset`.

### Message Example
```
msg.post("camera", "follow_offset", { offset = vmath.vector3(150, 250, 0) })
```
```

--------------------------------

### Drag-to-Scroll Interaction Pattern

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Implements a drag-to-pan interaction with zoom-corrected delta calculation using screen-to-world conversion, zoom level, and direct position setting.

```lua
local camera = require "orthographic.camera"

local CAMERA_ID = hash("/camera")

function init(self)
    msg.post(".", "acquire_input_focus")
end

function on_input(self, action_id, action)
    if action_id == hash("touch") then
        if action.pressed then
            self.pressed_pos = vmath.vector3(action.x, action.y, 0)
            self.camera_start = go.get_position(CAMERA_ID)
        elseif action.released then
            self.pressed_pos = nil
        end
    elseif action_id == nil and self.pressed_pos then
        -- Pan: subtract drag delta scaled by zoom
        local zoom     = camera.get_zoom(CAMERA_ID)
        local curr_pos = vmath.vector3(action.x, action.y, 0)
        local diff     = (curr_pos - self.pressed_pos) / zoom
        go.set_position(self.camera_start - diff, CAMERA_ID)
    elseif action_id == hash("zoom_in") then
        camera.set_zoom(CAMERA_ID, math.min(4, camera.get_zoom(CAMERA_ID) + 0.05))
    elseif action_id == hash("zoom_out") then
        camera.set_zoom(CAMERA_ID, math.max(0.2, camera.get_zoom(CAMERA_ID) - 0.05))
    end
end
```

--------------------------------

### Convert World to Screen Coordinates

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Convert world coordinates to screen coordinates using the camera API.

```lua
local screen_pos = camera.world_to_screen(self.camera_id, world_pos)

```

--------------------------------

### camera.bounds

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Sets the camera's movement boundaries. This is a message-based command.

```APIDOC
## camera.bounds (message)

### Description
Message equivalent to `camera.bounds()`. Accepted message keys: `left`, `right`, `bottom` and `top`.

### Message Example
```
msg.post("camera", "bounds", { left = 10, right = 200, bottom = 10, top = 100 })
```
```

--------------------------------

### camera.get_window_size

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Retrieves the current dimensions of the game window.

```APIDOC
## camera.get_window_size()

### Description
Get the current window size. The default values will be the ones specified in game.project.

### Return
#### Success Response
- **width** (number) - Current window width.
- **height** (number) - Current window height.
```

--------------------------------

### Send Bounds Message

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Sets the world boundaries for the camera. The camera will not move outside these defined limits.

```lua
msg.post("camera", "bounds", { left = 10, right = 200, bottom = 10, top = 100 })
```

--------------------------------

### Send Use Projection Message

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Sets the projection mode for the camera. Accepts a hash representing the desired projection type.

```lua
msg.post("camera", "use_projection", { projection = hash("FIXED_AUTO") })
```

--------------------------------

### camera.follow

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Makes the camera track one or more game objects. The camera centers on the average of their world positions when multiple targets are supplied. The `lerp` option smooths movement using frame-rate-independent damping.

```APIDOC
## camera.follow(camera_id, targets, options)

### Description
Makes the camera track one or more game objects. When multiple targets are supplied the camera centers on the average of their world positions. The `lerp` option smooths movement using frame-rate-independent damping.

### Parameters
#### Path Parameters
- **camera_id** (hash) - Required - The ID of the camera game object to control.
- **targets** (hash or table of hash) - Required - The ID(s) of the game object(s) to follow.

#### Query Parameters
- **options** (table) - Optional - Configuration options for following.
  - **immediate** (boolean) - If true, follow without smoothing.
  - **lerp** (number) - Damping factor for smooth following (0.0 to 1.0).
  - **horizontal** (boolean) - Whether to follow along the horizontal axis.
  - **vertical** (boolean) - Whether to follow along the vertical axis.
  - **offset** (vector3) - An offset to apply to the follow target position.

### Request Example
```lua
local camera = require "orthographic.camera"

local CAMERA_ID = hash("/camera")
local PLAYER_ID = hash("/player")
local ENEMY_ID  = hash("/enemy")

-- Follow a single target immediately, no smoothing
camera.follow(CAMERA_ID, PLAYER_ID, { immediate = true })

-- Follow with smooth lerp, horizontal axis only
camera.follow(CAMERA_ID, PLAYER_ID, {
    lerp       = 0.1,
    horizontal = true,
    vertical   = false,
    offset     = vmath.vector3(0, 100, 0),  -- look 100px ahead vertically
})

-- Follow multiple targets (camera centers between them)
camera.follow(CAMERA_ID, { PLAYER_ID, ENEMY_ID })
```

### Message Equivalent
```lua
msg.post("/camera", "follow", {
    target     = PLAYER_ID,
    lerp       = 0.7,
    horizontal = true,
    vertical   = true,
    immediate  = false,
})
```
```

--------------------------------

### Send Deadzone Message

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Sets the deadzone margins for the camera. Input within the deadzone will not cause camera movement.

```lua
msg.post("camera", "deadzone", { left = 10, right = 200, bottom = 10, top = 100 })
```

--------------------------------

### camera.shake

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Initiates a camera shake effect. This is a message-based command.

```APIDOC
## camera.shake (message)

### Description
Message equivalent to `camera.shake()`. Accepted message keys: `intensity`, `duration` and `direction`.

### Message Example
```
msg.post("camera", "shake", { intensity = 0.05, duration = 2.5, direction = "both" })
```
```

--------------------------------

### Set Camera Zoom with camera.set_zoom

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Set the camera's zoom level directly using the camera.set_zoom function.

```lua
camera.set_zoom(self.camera_id, zoom)

```

--------------------------------

### camera.use_projection

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Sets the projection mode for the camera. This is a message-based command.

```APIDOC
## camera.use_projection (message)

### Description
Set which projection to use.

### Message Example
```
msg.post("camera", "use_projection", { projection = hash("FIXED_AUTO") })
```
```

--------------------------------

### Convert Screen to World Coordinates

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Convert screen coordinates (e.g., from input events) to world coordinates using the camera API.

```lua
local world_pos = camera.screen_to_world(self.camera_id, screen_pos)

```

--------------------------------

### Enable, Disable, or Toggle Camera

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Control camera visibility and rendering at runtime using messages or by directly setting the 'enabled' property on the script component.

```lua
-- Enable the camera via message
msg.post("/camera", "enable")

-- Disable
msg.post("/camera", "disable")

-- Toggle via go.set on the script component
go.set("/camera#camerascript", "enabled", false)
```

--------------------------------

### camera.shake

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Applies a randomized positional shake to the camera for a specified duration. Intensity is a fraction of display dimensions, and an optional callback can be provided to fire when the shake finishes.

```APIDOC
## camera.shake(camera_id, intensity, duration, direction, cb)

### Description
Applies a randomized positional shake to the camera for a specified duration. Intensity is a fraction of display dimensions (e.g., 0.05 = 5% of screen width/height). An optional callback fires when the shake finishes.

### Parameters
#### Path Parameters
- **camera_id** (hash) - Required - The ID of the camera component.
- **intensity** (number) - Required - The intensity of the shake, as a fraction of screen dimensions.
- **duration** (number) - Required - The duration of the shake in seconds.
- **direction** (hash) - Optional - The direction of the shake (e.g., `camera.SHAKE_BOTH`, `camera.SHAKE_HORIZONTAL`, `camera.SHAKE_VERTICAL`). Defaults to both axes.
- **cb** (function) - Optional - A callback function to execute when the shake completes.

### Request Example
```lua
local camera = require "orthographic.camera"
local CAMERA_ID = hash("/camera")

-- Shake in both axes, medium intensity, 0.5s
camera.shake(CAMERA_ID, 0.05, 0.5, camera.SHAKE_BOTH, function()
    print("shake finished")
end)

-- Horizontal-only shake
camera.shake(CAMERA_ID, 0.03, 0.3, camera.SHAKE_HORIZONTAL)

-- Vertical-only shake
camera.shake(CAMERA_ID, 0.03, 0.3, camera.SHAKE_VERTICAL)
```

### Message Equivalent
```
msg.post("/camera", "shake", { intensity = 0.05, duration = 2.5, direction = hash("both") })
```
```

--------------------------------

### camera.get_view / camera.get_projection / camera.get_viewport

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Access the camera's current view matrix, projection matrix, and viewport rectangle.

```APIDOC
## camera.get_view(camera_id) / camera.get_projection(camera_id) / camera.get_viewport(camera_id) — Matrix and viewport access

Retrieves the current view matrix, projection matrix, and viewport rectangle for a given camera. These are the values passed to the render script each frame.

### Parameters
- **camera_id** (hash) - The ID of the camera component.

### Returns
- **camera.get_view**: (matrix4) - The current view matrix.
- **camera.get_projection**: (matrix4) - The current projection matrix.
- **camera.get_viewport**: (vector4) - The viewport rectangle (x=left, y=bottom, z=width, w=height).

### Example
```lua
local camera = require "orthographic.camera"

local CAMERA_ID = hash("/camera")

-- Read matrices (e.g., for a custom render script or manual frustum culling)
local view       = camera.get_view(CAMERA_ID)
local projection = camera.get_projection(CAMERA_ID)
local viewport   = camera.get_viewport(CAMERA_ID)
-- viewport is a vector4: x=left, y=bottom, z=width, w=height

-- Manual frustum culling in a custom render script
local cameras = camera.get_cameras()
for _, cam_id in ipairs(cameras) do
    local vp   = camera.get_viewport(cam_id)
    local v    = camera.get_view(cam_id)
    local p    = camera.get_projection(cam_id)
    render.set_viewport(vp.x, vp.y, vp.z, vp.w)
    render.set_view(v)
    render.set_projection(p)
    local frustum = p * v
    render.draw(tile_pred, { frustum = frustum })
end
```
```

--------------------------------

### Set Camera Deadzone

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Define the camera's deadzone by setting the deadzone_left, deadzone_right, deadzone_top, and deadzone_bottom properties.

```lua
camera.deadzone(self.camera_id, deadzone_left, deadzone_right, deadzone_top, deadzone_bottom)

```

--------------------------------

### Translate Screen Boundaries to World Coordinates

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Converts the screen boundaries (left, top, right, bottom) to world coordinates. Useful for determining the world space represented by the visible screen area.

```lua
local bounds = camera.screen_to_world_bounds(camera_id)
```

--------------------------------

### camera.screen_to_world

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Translates screen coordinates to world coordinates using the camera's view and projection.

```APIDOC
## camera.screen_to_world(camera_id, screen)

### Description
Translate screen coordinates to world coordinates, based on the view and projection of the camera.

### Parameters
#### Path Parameters
- **camera_id** (hash|url|nil) - Optional - nil for the first camera
- **screen** (vector3) - Required - Screen coordinates to convert

### Return
#### Success Response
- **world_coords** (vector3) - World coordinates
```

--------------------------------

### Send Follow Offset Message

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Adjusts the follow offset of the camera. Use this to fine-tune the camera's position relative to its target.

```lua
msg.post("camera", "follow_offset", { offset = vmath.vector3(150, 250, 0) })
```

--------------------------------

### camera.screen_to_world_bounds

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Translates screen boundaries (corners) to world coordinates using the camera's view and projection.

```APIDOC
## camera.screen_to_world_bounds(camera_id)

### Description
Translate screen boundaries (corners) to world coordinates, based on the view and projection of the camera.

### Parameters
#### Path Parameters
- **camera_id** (hash|url|nil) - Optional - nil for the first camera

### Return
#### Success Response
- **bounds** (vector4) - Screen bounds (x = left, y = top, z = right, w = bottom)
```

--------------------------------

### camera.world_to_screen

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Translates world coordinates to screen coordinates using the camera's view and projection. Useful for culling or positioning GUI elements.

```APIDOC
## camera.world_to_screen(camera_id, world, [adjust_mode])

### Description
Translate world coordinates to screen coordinates, based on the view and projection of the camera. This is useful when manually culling game objects and you need to determine if a world coordinate will be visible or not. It can also be used to position gui nodes on top of game objects.

### Parameters
#### Path Parameters
- **camera_id** (hash|url|nil) - Optional - nil for the first camera
- **world** (vector3) - Required - World coordinates to convert
- **adjust_mode** (any) - Optional - Adjust mode for conversion

### Return
#### Success Response
- **screen_coords** (vector3) - Screen coordinates
```

--------------------------------

### Convert screen coordinates to world coordinates

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Use `screen_to_world` to convert screen-space positions from input events (like touches) into world coordinates. This is essential for interacting with game objects based on user taps.

```lua
local camera = require "orthographic.camera"

local CAMERA_ID = hash("/camera")

function on_input(self, action_id, action)
    if action_id == hash("touch") and action.pressed then
        local screen_pos = vmath.vector3(action.screen_x, action.screen_y, 0)
        local world_pos  = camera.screen_to_world(CAMERA_ID, screen_pos)
        print(("touched world position: %.1f, %.1f"):format(world_pos.x, world_pos.y))
        -- Spawn an object at the tapped world position
        factory.create("#spawner", world_pos)
    end
end
```

--------------------------------

### camera.follow_offset

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Modifies the camera's follow offset from the target game object.

```APIDOC
## camera.follow_offset(camera_id, offset)

### Description
Change the camera follow offset.

### Parameters
#### Path Parameters
* `camera_id` (hash|url|nil) - nil for the first camera
* `offset` (vector3) - Camera offset from target position.
```

--------------------------------

### camera.follow_offset

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Changes the world-space offset applied to the follow target position without re-issuing a full `follow` call.

```APIDOC
## camera.follow_offset(camera_id, offset)

### Description
Changes the world-space offset applied to the follow target position without re-issuing a full `follow` call.

### Parameters
#### Path Parameters
- **camera_id** (hash) - Required - The ID of the camera game object to control.
- **offset** (vector3) - Required - The world-space offset to apply.

### Request Example
```lua
local camera = require "orthographic.camera"

-- Shift the camera 150px right and 250px up from the target
camera.follow_offset(hash("/camera"), vmath.vector3(150, 250, 0))
```

### Message Equivalent
```lua
msg.post("/camera", "follow_offset", { offset = vmath.vector3(150, 250, 0) })
```
```

--------------------------------

### Enable / Disable camera messages

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Allows cameras to be toggled at runtime. Disabled cameras are excluded from `get_cameras()` and will not be rendered.

```APIDOC
## Enable / Disable camera messages

### Description
Cameras can be enabled or disabled at runtime using messages. Disabled cameras are automatically excluded from the list returned by `camera.get_cameras()` and will not be rendered.

### Messages
- **enable**: Send this message to enable a camera.
- **disable**: Send this message to disable a camera.

### Example Usage
```lua
-- Enable the camera via message
msg.post("/camera", "enable")

-- Disable
msg.post("/camera", "disable")
```

### Alternative Method
Cameras can also be toggled via `go.set` on the script component:
```lua
go.set("/camera#camerascript", "enabled", false)
```
```

--------------------------------

### Send Shake Message

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Initiates a camera shake effect. Accepts intensity, duration, and direction as parameters.

```lua
msg.post("camera", "shake", { intensity = 0.05, duration = 2.5, direction = "both" })
```

--------------------------------

### Disable Camera by Message

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Disable a camera by sending it a 'disable' message.

```lua
msg.post(self.camera_id, "disable")

```

--------------------------------

### Convert world coordinates to screen coordinates

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Use `world_to_screen` to convert world-space positions to screen-space coordinates. This is useful for positioning UI elements like health bars above game objects or for manual culling.

```lua
local camera = require "orthographic.camera"

local CAMERA_ID = hash("/camera")

-- Position a GUI health bar above a world-space character
function update(self, dt)
    local world_pos    = go.get_world_position(hash("/player"))
    local screen_pos   = camera.world_to_screen(CAMERA_ID, world_pos)
    -- Offset the label 40px above the sprite
    screen_pos.y = screen_pos.y + 40
    gui.set_screen_position(gui.get_node("healthbar"), screen_pos)
end

-- With GUI adjust_mode for correct scaling behaviour
local node      = gui.get_node("label")
local world_pos = vmath.vector3(160, 160, 0)
local screen_pos = camera.world_to_screen(CAMERA_ID, world_pos, gui.get_adjust_mode(node))
gui.set_screen_position(node, screen_pos)
```

--------------------------------

### camera.deadzone

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Defines the deadzone area for camera movement. This is a message-based command.

```APIDOC
## camera.deadzone (message)

### Description
Message equivalent to `camera.deadzone()`. Accepted message keys: `left`, `right`, `bottom` and `top`.

### Message Example
```
msg.post("camera", "deadzone", { left = 10, right = 200, bottom = 10, top = 100 })
```
```

--------------------------------

### Translate Screen to World Coordinates

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Converts screen coordinates to world coordinates using the camera's view and projection. Use when you need to map a point on the screen to its corresponding position in the game world.

```lua
local world_coords = camera.screen_to_world(camera_id, screen)
```

--------------------------------

### camera.shake

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Applies a shaking effect to the camera with customizable intensity, duration, and direction.

```APIDOC
## camera.shake(camera_id, [intensity], [duration], [direction], [cb])

### Description
Shake the camera.

### Parameters
#### Path Parameters
* `camera_id` (hash|url) - The ID of the camera to shake.
* `intensity` (number) - Optional. Intensity of the shake, in percent of screen. Defaults to 0.05.
* `duration` (number) - Optional. Duration of the shake, in seconds. Defaults to 0.5.
* `direction` (hash) - Optional. Direction of the shake. Possible values: `both`, `horizontal`, `vertical`. Defaults to `both`.
* `cb` (function) - Optional. Function to call when the shake has finished.

```

--------------------------------

### camera.zoom_to

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Adjusts the camera's zoom level to a specific value. This is a message-based command.

```APIDOC
## camera.zoom_to (message)

### Description
Message equivalent to `camera.zoom_to()`. Accepted message keys: `zoom`.

### Message Example
```
msg.post("camera", "zoom_to", { zoom = 2.5 })
```
```

--------------------------------

### Enable and check auto zoom for orthographic camera

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Use `set_automatic_zoom` to enable or disable auto zoom, which adjusts the camera to fit the display area to the screen. `get_automatic_zoom` checks the current state. Auto zoom can also be controlled via messages.

```lua
local camera = require "orthographic.camera"

local CAMERA_ID = hash("/camera")

-- Enable auto zoom
camera.set_automatic_zoom(CAMERA_ID, true)

-- Check if enabled
local is_auto = camera.get_automatic_zoom(CAMERA_ID)
print("auto zoom:", is_auto)  -- true

-- Disable
camera.set_automatic_zoom(CAMERA_ID, false)

-- Toggle on button press
camera.set_automatic_zoom(CAMERA_ID, not camera.get_automatic_zoom(CAMERA_ID))

-- Message equivalent
msg.post("/camera", "set_automatic_zoom", { enabled = true })
```

--------------------------------

### camera.bounds

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Clamps the camera viewport to a specified world rectangle, preventing it from scrolling outside these boundaries. If the bounded area is smaller than the viewport, the camera is centered on the bounded area. Pass no arguments to remove bounds.

```APIDOC
## camera.bounds(camera_id, left, top, right, bottom)

### Description
Clamps the camera viewport to a specified world rectangle, preventing it from scrolling outside these boundaries. If the bounded area is smaller than the viewport, the camera is centered on the bounded area. Pass no arguments to remove bounds.

### Parameters
#### Path Parameters
- **camera_id** (hash) - Required - The ID of the camera component.
- **left** (number) - Optional - The left boundary of the world rectangle.
- **top** (number) - Optional - The top boundary of the world rectangle.
- **right** (number) - Optional - The right boundary of the world rectangle.
- **bottom** (number) - Optional - The bottom boundary of the world rectangle.

### Request Example
```lua
local camera = require "orthographic.camera"
local CAMERA_ID = hash("/camera")

-- Clamp to a 1728x1280 world map
camera.bounds(CAMERA_ID, 0, 1280, 1728, 0)

-- Remove bounds
camera.bounds(CAMERA_ID)
```

### Message Equivalent
```
msg.post("/camera", "bounds", { left = 0, right = 1728, bottom = 0, top = 1280 })
msg.post("/camera", "bounds", {})
```
```

--------------------------------

### camera.set_zoom

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Sets the camera zoom level directly. A zoom of 2 makes objects appear twice as large; 0.5 zooms out to half size. Zoom can also be driven through `go.animate` for smooth transitions.

```APIDOC
## camera.set_zoom(camera_id, zoom)

### Description
Sets the camera zoom level directly. A zoom of 2 makes objects appear twice as large; 0.5 zooms out to half size. Zoom can also be driven through `go.animate` for smooth transitions.

### Parameters
#### Path Parameters
- **camera_id** (hash) - Required - The ID of the camera component.
- **zoom** (number) - Required - The desired zoom level.

### Request Example
```lua
local camera = require "orthographic.camera"
local CAMERA_ID = hash("/camera")

-- Set zoom directly
camera.set_zoom(CAMERA_ID, 2.0)

-- Zoom in/out incrementally
local function on_input(self, action_id, action)
    if action_id == hash("zoom_in") then
        local z = camera.get_zoom(CAMERA_ID)
        camera.set_zoom(CAMERA_ID, math.min(4, z + 0.05))
    elseif action_id == hash("zoom_out") then
        local z = camera.get_zoom(CAMERA_ID)
        camera.set_zoom(CAMERA_ID, math.max(0.2, z - 0.05))
    end
end

-- Animate zoom via go.animate
go.animate("mycamera#camerascript", "zoom", go.PLAYBACK_ONCE_FORWARD, 2.5, go.EASING_OUTQUAD, 1.0)
```

### Message Equivalent
```
msg.post("/camera", "zoom_to", { zoom = 2.5 })
```
```

--------------------------------

### Apply Screen Shake Effect

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Applies a randomized positional shake to the camera for a specified duration. Intensity is a fraction of display dimensions. An optional callback fires when the shake finishes. Supports horizontal, vertical, or both axes. Can be stopped early via API or message.

```lua
local camera = require "orthographic.camera"

local CAMERA_ID = hash("/camera")

-- Shake in both axes, medium intensity, 0.5s
camera.shake(CAMERA_ID, 0.05, 0.5, camera.SHAKE_BOTH, function()
    print("shake finished")
end)

-- Horizontal-only shake (e.g., horizontal hit reaction)
camera.shake(CAMERA_ID, 0.03, 0.3, camera.SHAKE_HORIZONTAL)

-- Vertical-only shake
camera.shake(CAMERA_ID, 0.03, 0.3, camera.SHAKE_VERTICAL)

-- Stop early
camera.stop_shaking(CAMERA_ID)

-- Message equivalents (shake_complete message is sent back to sender on finish)
msg.post("/camera", "shake", { intensity = 0.05, duration = 2.5, direction = hash("both") })
msg.post("/camera", "stop_shaking")
```

--------------------------------

### Apply Camera Recoil Effect

Source: https://context7.com/britzl/defold-orthographic/llms.txt

Applies an instantaneous positional offset to the camera that decays linearly back to zero over a given duration. Useful for feedback like gun-fire or impacts. Message equivalent is also shown.

```lua
local camera = require "orthographic.camera"

local CAMERA_ID = hash("/camera")

-- Kick the camera 100px up-right, returning over 0.75s
camera.recoil(CAMERA_ID, vmath.vector3(100, 100, 0), 0.75)

-- Message equivalent
msg.post("/camera", "recoil", { offset = vmath.vector3(100, 100, 0), duration = 0.75 })
```

--------------------------------

### camera.disable

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Disables the camera. This is a message-based command.

```APIDOC
## camera.disable (message)

### Description
Disable the camera.

### Message Example
```
msg.post("camera", "disable")
```
```

--------------------------------

### camera.get_view

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Retrieves the current view matrix of a specified camera.

```APIDOC
## camera.get_view(camera_id)

### Description
Get the current view of the camera.

### Parameters
#### Path Parameters
* `camera_id` (hash|url|nil) - nil for the first camera

### Return
* `view` (matrix) - The current view
```

--------------------------------

### camera.recoil

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Applies a recoil effect to the camera. This is a message-based command.

```APIDOC
## camera.recoil (message)

### Description
Message equivalent to `camera.recoil()`. Accepted message keys: `offset` and `duration`.

### Message Example
```
msg.post("camera", "recoil", { offset = vmath.vector3(100, 100, 0), duration = 0.75 })
```
```

--------------------------------

### Translate World to Screen Coordinates

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Converts world coordinates to screen coordinates. This is useful for manual culling of game objects or positioning GUI nodes relative to game objects.

```lua
local screen_coords = camera.world_to_screen(camera_id, world, adjust_mode)
```

--------------------------------

### camera.stop_shaking

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Stops any ongoing camera shake effect. This is a message-based command.

```APIDOC
## camera.stop_shaking (message)

### Description
Message equivalent to `camera.stop_shaking()`.

### Message Example
```
msg.post("camera", "stop_shaking")
```
```

--------------------------------

### Send Stop Shaking Message

Source: https://github.com/britzl/defold-orthographic/blob/master/README.md

Immediately stops any ongoing camera shake effect.

```lua
msg.post("camera", "stop_shaking")
```