Camera class Null safety

A camera translates your game coordinate system; this is useful when your world is not 1:1 with your screen size.

A camera always has a current position, however you cannot set it directly. You must use some methods to ensure that the camera moves smoothly as the game runs. Smoothly here means that sudden snaps should be avoided, as they feel jarring to the player.

There are three major factors that determine the camera position:

• Follow If you want, you can call followComponent at the beginning of your stage/world/level, and provided a PositionComponent. The camera will follow this component making sure its position is fixed on the screen. You can set the relative position of the screen you want the follow object to stay in (normally the center), and you can even change that and get a smooth transition.

• Move You can alternatively move the camera to a specific world coordinate. This will set the top left of the camera and will ignore any existing follow rules and move the camera smoothly until it reaches the desired destination.

• Shake Regardless of the the previous rules, you can additionally add a shake effect for a brief period of time on top of the current coordinate. The shake adds a random immediate delta to each tick to simulate the shake effect.

Note: in the context of the FlameGame, the camera effectively translates the position where components are rendered with relation to the Viewport. Components marked as positionType = PositionType.viewport; are always rendered in screen coordinates, bypassing the camera altogether.

Note: beware of using very large numbers with the camera (like coordinates spanning the dozens of millions). Due to the required matrix operations performed by the Camera, using such large numbers can cause performance issues. Consider breaking down huge maps into manageable chunks.

Inheritance

• Object
• Projector
• Camera

Constructors

Camera()

Properties

canvasSize → Vector2

read-only

combinedProjector → Projector

read-only

defaultShakeDuration ↔ double

read / write

defaultShakeIntensity ↔ double

read / write

follow ↔ Vector2?

If set, the camera will "follow" this vector, making sure that this vector is always rendered in a fixed position in the screen, by immediately moving the camera to "focus" on the where the vector is.

read / write

gameSize → Vector2

read-only

hashCode → int

The hash code for this object.

read-only, inherited

position → Vector2

This is the current position of the camera, ie the world coordinate that is rendered on the top left of the screen (origin of the screen space).

read-only

relativeOffset → Vector2

Where in the screen the follow object should be.

read-only

runtimeType → Type

A representation of the runtime type of the object.

read-only, inherited

shaking → bool

Whether the camera is currently shaking or not.

read-only

speed ↔ double

read / write

viewport ↔ Viewport

read / write

worldBounds ↔ Rect?

If set, this determines boundaries for the camera movement.

read / write

zoom ↔ double

If set, the camera will zoom by this ratio. This can be greater than 1 (zoom in) or smaller (zoom out), but should always be greater than zero.

read / write

Methods

absoluteTarget() → Vector2

This is the (current) absolute target of the camera, i.e., the coordinate that should with relativeOffset taken into consideration but regardless of world boundaries or shake.

apply(Canvas canvas) → void

Use this method to transform the canvas using the current rules provided by this camera object.

followComponent(PositionComponent component, {Anchor relativeOffset = Anchor.center, Rect? worldBounds}) → void

Immediately snaps the camera to start following the component.

followVector2(Vector2 vector2, {Anchor relativeOffset = Anchor.center, Rect? worldBounds}) → void

Immediately snaps the camera to start following vector2.

handleResize(Vector2 canvasSize) → void

moveTo(Vector2 position) → void

Applies an ad-hoc movement to the camera towards the target, bypassing follow. Once it arrives the camera will not move until resetMovement is called.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a non-existent method or property is accessed.

inherited

onPositionUpdate(Vector2 position) → void

If you need updated on when the position of the camera is updated you can override this.

projectVector(Vector2 worldCoordinates) → Vector2

Converts a vector in the world space to the screen space.

override

resetMovement() → void

Smoothly resets any moveTo targets.

scaleVector(Vector2 worldCoordinates) → Vector2

Converts a vector representing a delta in the world space to the screen space.

override

screenToWorld(Vector2 screenCoordinates) → Vector2

Takes coordinates in the screen space and returns their counter-part in the world space.

setRelativeOffset(Anchor newRelativeOffset) → void

This will trigger a smooth transition to a new relative offset.

shake({double? duration, double? intensity}) → void

Applies a shaking effect to the camera for duration seconds and with intensity expressed in pixels.

snap() → void

Use this to immediately "snap" the camera to where it should be right now. This bypasses any currently smooth transitions and might be janky, but can be used to setup after a new world transition for example.

snapTo(Vector2 position) → void

Instantly moves the camera to the target, bypassing follow. This will replace any previous targets.

toString() → String

A string representation of this object.

inherited

translateBy(Vector2 displacement) → void

Moves the camera by a given displacement (delta). This is the same as moveTo but instead of providing an absolute end position, you can provide a desired translation vector.

unprojectVector(Vector2 screenCoordinates) → Vector2

Converts a vector in the screen space to the world space.

override

unscaleVector(Vector2 screenCoordinates) → Vector2

Converts a vector representing a delta in the screen space to the world space.

override

update(double dt) → void

This smoothly updates the camera for an amount of time dt.

worldToScreen(Vector2 worldCoordinates) → Vector2

Takes coordinates in the world space and returns their counter-part in the screen space.

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Constants

defaultSpeed → const double

50.0