Skip to main content

15 - Multiple Cameras

From edition=15 onwards, the Camera function now takes a new Id parameter which by default is implicitly assigned by the compiler. This means that calling Camera now creates a new camera by default, instead of replacing the existing camera. This change was made to support multiple cameras in Easel, which is useful for minimaps, overlay screens, heads-up displays, parallax, scene transitions and other effects.

To support this change, the SolidBackground, Vignette and PointerAimingLine functions also now take an Id parameter, as it is possible you may need multiple instances of these components to appear in multiple cameras.

Upgrade instructions​

First, set edition=15 (or higher) in your easel.toml file:

[engine]
edition = 15

Updating Camera usages​

Look at all usages of Camera in your project (using the Find-and-Replace feature of your code editor) and find the instances where you call Camera multiple times on the same entity. Note that this is not common in most projects - many projects just call Camera once and never again.

Give these instances an explicit Id to preserve the old behavior of replacing the single camera. If you don't do this, in edition=15 onwards, each Camera call will create a new camera instead of modifying the existing one. This may cause some unexpected behavior in your project.

Example​

Let's say your code looks like this:

Camera(radius=28, freeRadius=8, priority=10, transitionSpeed=0.02)

on ResetCamera {
    Camera(radius=28, freeRadius=0, priority=10, transitionSpeed=1)
}

All of these Camera calls would previously have been modifying the same camera. We can preserve this behavior by giving them all the same explicit Id. For example, if we call the camera mainCamera, we would update the code to look like this:

Camera<mainCamera>(radius=28, freeRadius=8, priority=10, transitionSpeed=0.02)

on ResetCamera {
    Camera<mainCamera>(radius=28, freeRadius=0, priority=10, transitionSpeed=1)
}

Updating SolidBackground, Vignette and PointerAimingLine usages​

If you are using SolidBackground, Vignette or PointerAimingLine in your project, you can update these in the same way. Look for all usages of these functions in your project, and if you are calling them multiple times on the same entity, give them an explicit Id to preserve the old behavior of replacing the single instance. Note that this is also not common and so chances are does not affect your project. Most projects call these functions once per entity and then never again.

Opt-out​

If you would like to temporarily opt-out your entire project from this change, you can set singleCamera=true in legacy.toml, like this:

[legacy]
singleCamera = true