📼 Also in this series:

• 👖 Kinematic Walker
• 🏗️ TrenchFold
• 🎄 Illumination
• 🚧 Blockout Textures

This is a tweakable camera movement controller suitable for 3D games on the Defold. It can help you smoothly control your character’s camera or make cinematic motion paths using checkpoints.

Showing your player the level by flying around and finish the flight by smooth attachment to the character — sounds like a classic use case.

This extension is not about rendering so you can use any render script that you want.

🎮 Play HTML5 demo.

💬 Discuss on the forum.

• Camera rotation and zooming by mouse controls.
• External manual control by messages.
• Following an object with avoiding obstacles.
• Smart alignment to the ground slope.
• Smooth movement along checkpoints using a bezier path.
• Switching between multiple cameras.
• Request by adding an issue or contribute.

Add links to the zip-archive of the latest versions of defold-operator to your Defold project as dependencies.

If you plan to lock the cursor pointer, add a link to the latest version of defold-pointer-lock.

Add operator.collection to your scene and configure its script properties in the editor.

Character Following

1. Post the follow_point message to follow the game object.
2. Use mouse controls or post manual_control messages.

Cinematic Flight

1. Add checkpoint.go instances to your scene and configure their script properties in the editor.
2. Post the follow_sequence message with an array of checkpoints to follow the sequence.

Operator doesn't provide cursor locking functionality. To lock the cursor use the window.set_mouse_lock() method or look at the defold-pointer-lock extension.

To get more control and avoid camera rotation jumps, disable the internal control when the cursor is not locked and enable it when the cursor is locked.

If the operator is following a moving object with a physical body, you may notice a jittering effect.

The operator doesn't integrate into the hierarchy of the folowing object, so it requires to know the actual position of the object. For this purpose, make sure that the project settings correspond to the recommended settings for the game with 3D physics.

[physics]
type = 3D
use_fixed_timestep = 1
max_fixed_timesteps = 1

[display]
update_frequency = 60

[engine]
fixed_update_frequency = 60

Activates the operator during initialization.

Enables internal control with a mouse input during initialization.

Vertical field of view in degrees. The value passed to the camera component during initialization.

Near z position to render. The value passed to the camera component during initialization.

Far z position to render. The value passed to the camera component during initialization.

Enables horizontal camera rotation.

Enables vertical camera rotation.

Inverts horizontal camera rotation.

Inverts vertical camera rotation.

A vector representing lower bounds of the rotation and zoom distance limits.

• x - minimum vertical rotation in degrees.
• y - minimum horizontal rotation in degrees.
• z - minimum zoom distance in units.

A vector representing upper bounds of the rotation and zoom distance limits.

• x - maximum vertical rotation in degrees.
• y - maximum horizontal rotation in degrees.
• z - maximum zoom distance in units.

Input sensitivity for the camera rotation. The value is an angle in degrees to rotate by 1 input value.

• 0.0 - no reaction.
• 0.7 - degrees = 70% of input.

How much time in seconds needed to turn the current look to the desired look after input.

• 0 - look immediately and sharp.
• 0.1 - look smoothly.
• 1.2 - look like a sloth.

The first-person look usually uses sharper rotation than the third-person look.

An initial distance between the camera and the operator anchor point.

• 0 - use for the first-person look to rotate the camera inside the object.
• n - use for the third-person look to rotate the camera around the object.

The camera distance change in units per a zoom input value.

How much time in seconds needed to change the current zoom to the desired zoom after input.

• 0 - zoom immediately and sharp.
• 0.3 - zoom smoothly (recommended).
• 1.2 - zoom like a sloth.

Checks a path from the camera to the operator anchor for the collisions and moves it closer if necessary.

Minimum distance between the camera and the collision surface if collision_check is turned on.

How much align the camera to the ground normal.

• 0 - no alignment.
• 0.5 - half alignment (recommended).
• 1.0 - full alignment (not recommended).

How much time in seconds needed to change the current ground alignment to the desired ground alignment after the ground normal update.

• 0 - align immediately and sharp (not recommended).
• 0.5 - align smoothly.
• 2.3 - align like a sloth.

Don't use low values to avoid sharp shakes due to the ground geometry.

Follow the rotation while following the object. Useful when you want to control the object rather than the camera. For example, a car.

Activates the operator. Acquires input and camera focuses, posts use_camera_projection to the render. Automatically deactivates a previous operator.

msg.post(operator_url, hash 'activate')

Deactivates the operator. Releases input and camera focuses.

msg.post(operator_url, hash 'deactivate')

The operator can follow the object or follow checkpoints to make kind of cinematic camera movement.

Local space coordinates and rotations are respected so you can switch between two moving objects without problems.

There is two ways to create checkpoint:

• Place checkpoint.go instance to your scene and configure its script properties.
• Manually create table with parameters in the code.

A point table have additional parameters position and look, which are the equivalents of checkpoint.go position, rotation.

• object (optional, default is nil) - move the operator in the local object coordinates. Use this to attach it to something moving, like a character.
• position (optional, default is vmath.vector()) - the operator anchor position.
• look (optional, default is the previous point look) - the camera rotation.
• zoom (optional, default is the previous point zoom) - the camera zoom distance.
• speed (optional, default is the previous point speed) - the speed at which the operator should move at this point. Measured in units per second.
• inout (optional, default is false) - use in-out easing on speed changing along tha path to this point. The speed between points changes linearly so in-out is useful when moving from 0 to 0 speed.
• bezier (optional, default is true) - use bezier smoothness at this point.

local point = {
    -- global space
    object = nil

    -- global position
    position = vmath.vector3(14, 2, 7)

    -- look down to the left.
    look = vmath.vector3(-45, 90, 0)

    -- 3 units from the camera to the anchor
    zoom = 3

    -- 5 units/sec speed at this point
    speed = 5

    -- speed linear changing to this point
    inout = false

    -- use bezier smooth at this point
    bezier = true
}

Follow the sequence of points.

local sequence = {
    -- manually created point
    checkpoint_1,

    -- checkpoint instance url
    msg.url('/checkpoint_2'),

    -- follow the object
    object_point
}

msg.post(operator_url, hash 'follow_sequence', sequence)

Sender will become motion_observer during the motion to receivce motion messages.

This is equilent to the follow_sequence message with one point.

If you want just to attach the camera to the character — that's your case.

-- Create a point
local point = {
    object = character_url,
    position = vmath.vector3(0, 1.5, 0)
}

-- Follow the point
msg.post(operator_url, hash 'follow_point', point)

Stop following any sequence or object.

msg.post(operator_url, hash 'unfollow')

Update the ground normal to proper camera alignment. This is usually done with raycasting down from the followed object.

-- raycast from the object to the ground
local ground = physics.raycast(position, position + vmath.vector3(0, -1, 0), { hash 'default' })

-- nil will be interpreted as vmath.vector3(0, 1, 0).
local normal = ground and ground.normal or nil

msg.post(operator_url, hash 'ground_normal', { normal = normal })

Enables or disables internal control with a mouse input.

msg.post(operator_url, hash 'internal_control', { is_inabled = true })

Manually control the look and zoom by input values. This can be useful on devices without a mouse or if you prefer to control everything by yourself.

local input = {
    horizontal = dx,
    vertical = dy,
    zoom = dz
}

msg.post(operator_url, hash 'manual_control', input)

You can reference to default internal control values:

• Mouse moving actions send action.dx and action.dy values.
• Mouse wheel actions send dz as -1 or 1 values.

• operator - the url of the operator.

Sends to the followed object when the operator attached.

• operator - the url of the operator.

Sends to the followed object when the operator detached.

• object - the url of the object if exists.
• checkpoint- the url of the checkpoint if exists.

Sends to motion_observer when the operator has reached the checkpoint.

• object - the url of the object if exists.
• checkpoint- the url of the checkpoint if exists.

Sends to motion_observer when the current operator motion has finished.

Sends to motion_observer when the current operator motion has interrupted by any other commands.

The operator module gives you access to additional shared preferences. Add the following requirement to use it.

local operator = require 'operator.operator'

Returns the current active operator url.

local active_operator_url = operator.get_active_operator()

Enables camera and checkpoint meshes, active bezier drawing.

operator.set_debug(true)

Returns current debug mode state as bool.

local is_debug = operator.is_debug()

Collision groups that are tested by raycast from the operator anchor to the camera to avoid obstacles.

operator.camera_collisions_groups = { hash 'default' }

Count of bezier segments. Used by uniform position calculation. 16 is usually enough, but 32 is more beautiful.

operator.flight_bezier_samples_count = 32

Easing function to update the camera rotation between motion points.

-- set a ready to use easing function
operator.flight_look_easing = operator.EASING_INOUT_QUAD

-- or use your own
local easing_linear = function(x) return x end
operator.flight_look_easing = easing_linear

Included easing functions:

• operator.EASING_INOUT_SINE
• operator.EASING_INOUT_CUBIC
• operator.EASING_INOUT_QUINT
• operator.EASING_INOUT_CIRC
• operator.EASING_INOUT_QUAD
• operator.EASING_INOUT_EXPO

The bezier.lua module is used to move the camera, but you can also use it for your own purposes. It supports vector and integer points.

Add the following requirement to use it.

local bezier = require 'operator.bezier'

• points - an array of vector or integer points. 3 points for quadratic bezier or 4 points for cubic bezier.
• samples_count (optional, default is 32) - count of bezier segments for uniform position calculation.
• length_func (optional, default function supports vectors and integers) - length function to override.
• lerp_func (optional, default function supports vectors and integers) - lerp function to override.

Returns a bezier instance with pre-calculated data.

-- quadratic bezier with default count of samples
local points = { p1, p2, p3 }
local bezier_path = bezier.new(points)

-- cubic bezier with 16 samples
local points = { p1, p2, p3, p4 }
local bezier_path = bezier.new(points, 16)

• time - a float value from 0 to 1 representing progress.

Returns a classic position along the bezier.

• time - a float value from 0 to 1 representing progress.

Returns an uniform position along the bezier. The accuracy depends of samples_count.

• Pointer Lock by Artsiom Trubchyk (@aglitchman) used in the demo.