CameraControls

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 Camera.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.

Requires: Camera

In a network game, each machine keeps its own entity with this on it: it isn’t sent.

Properties

Each is listed as its key in the scene file and the MCP tools, then its kind of value, its default and what it does.

• panSpeed: a number = 1. 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. (Field: a number.)
• panWithKeys: true or false = true. 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. (Field: on or off.)
• dragButton: one of None, Left, Middle, Right, MiddleOrRight = “MiddleOrRight”. The mouse button that drags the world along with the mouse, or None. (Field: one of its values.)
• edgeScroll: true or false = false. 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. (Field: on or off.)
• zoomMin: a number = 3. The closest the wheel zooms in: the camera’s smallest Size. (Field: a number.)
• zoomMax: a number = 16. The furthest the wheel zooms out: the camera’s largest Size. (Field: a number.)
• zoomStep: a number = 0.15. How much each notch of the wheel zooms: 0.15 shows 15% less of the world (or more). 0 leaves the wheel alone. (Field: a number.)
• stayInside: text = null. 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. (Names an entity.) (Field: an entity’s name.)
• focusSize: a number = 0. 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. (Field: a number.)
• focusSeconds: a number = 0.75. 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. (Field: a number.)

Actions

What anything can make it do with no code: a Trigger’s do when its message arrives, a Contraptions Wire’s input as its signal comes on, a script’s Game.Do(entity, “Name”).

• FocusOn (done with a name, its name: a trigger’s with). 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.
• GlideTo (done with a name, its name: a trigger’s with). 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.
• 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.

While the game runs

Not saved with the scene; scripts read them, and entity_get shows them as live while the game plays.

• isDragging: true or false. True while a mouse button is dragging the view.
• isFocused: true or false. 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: true or false. True while a GlideTo is under way: the player’s pan, drag or wheel cancels it.
• focusTarget: an entity: its name, id or path. The entity the camera is following while focused; null when it’s on a point, or not focused.

Scripts use it as CameraControls: its methods, events and values that aren’t saved with the scene.