CameraControls

namespace Griff.Scenes;

public sealed class CameraControls : Component

Pan and zoom with no code, for management, building and strategy games: put it on the camera, in place of a Follow. The PanUp, PanDown, PanLeft and PanRight actions (WASD, the arrow keys and the D-pad, rebound in Game > Controls or by the player) and a controller’s stick pan, a mouse button drags the world along, the wheel zooms toward the mouse between ZoomMin and ZoomMax, and the mouse at the screen’s edge can pan too. With StayInside the view never goes past the level’s edges, however big it grows. The wheel and drags are the HUD’s while the mouse is over it (anything pinned with a ScreenAnchor, an open panel, a button); set the camera’s HudSize to keep the HUD’s size as it zooms.

It runs on real time, so the view moves while the game is paused, but not under a menu that pauses it. For a “look at this” moment (a tour, a cutscene, a new building), FocusOn takes the camera over: it glides to a character and follows it at a closer Size, the player’s pan, drag and wheel waiting, until Release zooms back out and hands the camera back where it is. A Trigger or a Button can do both too.

This is a component: its saved properties are on its component page.

Properties

DragButton

public CameraDrag DragButton { get; set; }

The mouse button that drags the world along with the mouse, or None.

EdgeScroll

public bool EdgeScroll { get; set; }

Whether resting the mouse at the screen’s edge pans that way. Not while it’s on the HUD (a button row along the bottom, an open panel), so reaching for a button doesn’t pan the world away.

FocusSeconds

public float FocusSeconds { get; set; }

How many seconds (of real time) the camera takes to glide over to what it focuses on, zooming as it goes, and to zoom back once released. 0 jumps.

FocusSize

public float FocusSize { get; set; }

The camera’s Size while it’s focused on something (see FocusOn), smaller to look closer: what it zooms to when not told. 0 keeps the Size it has.

FocusTarget

public Entity? FocusTarget { get; }

The entity the camera is following while focused; null when it’s on a point, or not focused.

IsDragging

public bool IsDragging { get; }

True while a mouse button is dragging the view.

IsFocused

public bool IsFocused { get; }

True from FocusOn until the camera is the player’s again (after Release’s zoom back): the player’s pan, drag and wheel wait meanwhile.

IsGliding

public bool IsGliding { get; }

True while a GlideTo is under way: the player’s pan, drag or wheel cancels it.

PanSpeed

public float PanSpeed { get; set; }

How fast the keys and the screen’s edges pan, in screen heights a second: 1 crosses the screen’s height in a second, whatever the zoom.

PanWithKeys

public bool PanWithKeys { get; set; }

Whether the PanUp, PanDown, PanLeft and PanRight input actions (WASD, the arrow keys and the D-pad unless the game or the player rebinds them) and the left stick pan.

StayInside

public string? StayInside { get; set; }

The name of an entity whose area the view stays inside: a tilemap’s grid, a box collider, or a sprite, as it is each frame, so the view can reach more as the level grows.

ZoomMax

public float ZoomMax { get; set; }

The furthest the wheel zooms out: the camera’s largest Size.

ZoomMin

public float ZoomMin { get; set; }

The closest the wheel zooms in: the camera’s smallest Size.

ZoomStep

public float ZoomStep { get; set; }

How much each notch of the wheel zooms: 0.15 shows 15% less of the world (or more). 0 leaves the wheel alone.

Methods

FocusOn

public void FocusOn(string? name)

Takes the camera over to follow the entity with this name (the nearest, if there are several), zooming to FocusSize over FocusSeconds, until Release. Nothing happens if there’s none.

FocusOn

public void FocusOn(Entity target, float? size = default, float? seconds = default)

Takes the camera over to follow target: it glides there in seconds (or FocusSeconds), zooming to size (or FocusSize, and with neither keeping its Size), then keeps it in the middle of the view as it moves, inside StayInside. The player’s pan, drag and wheel wait until Release. Focusing on something else while focused glides on from there.

FocusOn

public void FocusOn(Vector2 point, float? size = default, float? seconds = default)

Takes the camera over to look at a point in the world, as FocusOn does a character.

GlideTo

public void GlideTo(string? name)

Glides the camera over to the entity with this name (the nearest, if there are several) over FocusSeconds at the Size it has, and leaves it the player’s there. Nothing happens if there’s none.

GlideTo

public void GlideTo(Entity target, float? size = default, float? seconds = default)

Glides the camera over to target in seconds (or FocusSeconds) and leaves it the player’s there: unlike FocusOn it keeps no hold on the camera, so there is no Release to time. It keeps the camera’s Size unless size is given (it zooms to that as it goes, and stays). The player’s pan keys, a drag or the wheel during the glide cancel it where the camera is.

GlideTo

public void GlideTo(Vector2 point, float? size = default, float? seconds = default)

Glides the camera over to a point in the world and leaves it the player’s, as GlideTo does.

Release

public void Release()

Hands the camera back to the player where it is: it zooms back to the Size it had before it was focused, over FocusSeconds, and then the player’s pan, drag and wheel work again.