Button

Makes the entity clickable: it lightens under the mouse, darkens while held, and clicks when the mouse is released over it. Behaviors on the entity get OnClick. Menus need no code at all: set Action to load a scene, restart or quit. Put a Sprite on the entity for a background and a Text for its label. HoverGrow, PressShrink and PopTime make it pop: grow under the mouse and shrink as it’s pressed, easing into each (only as it’s drawn: its clickable area stays its size).

Works with: Sprite (a background); Text (a label)

Needed by: Choice, Toggle

Changes how its entity is drawn (a tint, a shake or drawing it on top).

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.

• size: [x, y] = [3,1]. The clickable area, centered on the entity, in world units before the transform’s scale. Rotation is ignored. (A rectangle’s size, around the entity, in its own units before its scale: with Resize handles the Scene view puts handles on its edges and corners to drag.) (Field: a vector.)
• action: one of None, LoadScene, RestartScene, Quit, OpenPanel, ClosePanel, Rebind, ResetControls, HostGame, JoinGame, LeaveGame, EndTurn, Do, SaveGame, LoadGame, DeleteSave, QuickSave, QuickLoad, NewGame, Continue = “None”. What clicking it does with no code: load a scene, restart, quit, open or close a panel, rebind a key and so on. (Field: one of its values.)
• scene: text = null. For ButtonAction.LoadScene and New Game: the scene’s name, e.g. “Level1”. For Host Game and Leave Game, the scene to go to afterwards (empty stays). (Only used when action is LoadScene, NewGame, HostGame or LeaveGame.) (Names a scene.) (Field: a name.)
• savedScene: text = null. For ButtonAction.LoadScene: a name in Game.SaveData holding a scene to go to instead of Scene, e.g. “Room” (where an adventure’s walker keeps the room it’s in): a Play button that carries on where the player left off, and goes to Scene while nothing’s saved there. (Only used when action is LoadScene.) (Names a name in the save data.) (Field: a name.)
• fade: a number = 0. For loading and restarting: seconds to fade the screen out (and back in) around the switch. 0 cuts straight there. (Only used when action is LoadScene, NewGame, RestartScene, HostGame, LeaveGame, LoadGame, QuickLoad or Continue.) (Field: a number.)
• panel: text = null. For ButtonAction.OpenPanel: the name of the panel’s entity, e.g. “Options”. (Only used when action is OpenPanel.) (Names an entity.) (Field: an entity’s name.)
• do: text = null. For ButtonAction.Do: what to do, e.g. “Attack”, “Cast Spell” or “Open”: an action of the Targets’ components (or this entity’s). “Battler.Attack” names one component’s. (Only used when action is Do.) (Names an action of the entities targets names, or this entity without any: one component_describe lists under Actions, e.g. “Damage”, or “Health.Damage” for one component’s.) (Field: an action’s name.)
• targets: text = null. For ButtonAction.Do: the entities to do it on, by name, separated by commas. Empty does it on this entity. (Only used when action is Do.) (Names entities: their names, separated by commas.) (Field: an entity’s name.)
• with: text = null. For ButtonAction.Do: what to do it with, for an action that takes a value (Damage 2). Empty uses the action’s own default. (Only used when action is Do.) (The value the action do names is done with, as the action takes it: a number (“2”), true or false, or a name (a flag for Set Flag, a scene for Load Scene). Empty uses the action’s own default. The Inspector gives a box, a tick or a list as the action wants.) (Field: its own editor: Action Value.)
• slot: text = null. For Save Game, Load Game and Delete Save: the slot’s name, e.g. “1”. Empty uses the slot of the SaveSlot it’s on or inside. (Only used when action is SaveGame, LoadGame or DeleteSave.) (Names a save slot: this entity’s own, which other fields can name.) (Field: a name.)
• inputAction: text = null. For ButtonAction.Rebind: the input action it changes, e.g. “Jump”. (Only used when action is Rebind.) (Names an input action.) (Field: a name.)
• bindingSlot: a whole number = 0. For ButtonAction.Rebind: which of the action’s bindings on the device pressed it replaces, from 0: 0 its first key or mouse button (or gamepad button), 1 its second, so a controls screen can have a primary and a secondary key. One past the last adds one. Label it “{PanUp:1}” to show that slot’s binding. (Only used when action is Rebind.) (Field: a number.)

Control

• interactable: true or false = true. Whether it can be clicked. A button that can’t is drawn faded, ignores the mouse and its shortcut, and is skipped by the arrow keys. Scripts can set it, e.g. a Buy button while the player can’t afford it. (Field: on or off.)
• needsSaved: text = null. A name in Game.SaveData that has to be saved for the button to work, e.g. “level” for a Continue button that does nothing until there’s a game to continue. Empty always works. (Names a name in the save data.) (Field: a name.)
• shortcut: one of None, A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z, D0, D1, D2, D3, D4, D5, D6, D7, D8, D9, Space, Enter, Escape, Tab, Backspace, Left, Right, Up, Down, LeftShift, RightShift, LeftControl, RightControl, LeftAlt, RightAlt, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, Delete, Insert, Home, End, PageUp, PageDown, CapsLock, NumPad0, NumPad1, NumPad2, NumPad3, NumPad4, NumPad5, NumPad6, NumPad7, NumPad8, NumPad9, NumPadPlus, NumPadMinus, NumPadMultiply, NumPadDivide, NumPadDecimal, Minus, Equals, Comma, Period, Slash, Backslash, Semicolon, Quote, LeftBracket, RightBracket, Grave = “None”. A key that clicks the button too, e.g. Enter for a Play button. None for mouse only. (Field: one of its values.)
• shortcutAction: text = null. An input action that clicks the button too, e.g. “OpenMap” bound to M in Game > Controls: like Shortcut, but its keys are the action’s, so the Controls window and the player’s Rebind change them. Empty for none. (Names an input action.) (Field: a name.)
• navigable: true or false = true. Whether the arrow keys, D-pad and stick can move to this button (see IsFocused). Turn it off for a button on a HUD during play, so moving the player doesn’t pick it. (Field: on or off.)
• overPanels: true or false = false. Whether it still takes clicks and its shortcuts while a Panel it isn’t on is open, even one that pauses the game: a menu bar’s Game button or a pause button that opens the game menu over a letter or a shop, on top of it (closing that menu leaves the letter open). The arrow keys stay on the panel. Off, it waits until panels close. (Field: on or off.)

Feel

• sound: text = null. Plays when it’s clicked, e.g. “Sounds/select.wav”. (A sound in Assets, e.g. “Sounds/hit.wav”.) (Field: a sound.)
• highlight: a number = 0.2. How much lighter the button’s sprite and text get under the mouse, from 0 (not at all) to 1 (white). (Field: a number.)
• hoverGrow: a number = 0. How much bigger it’s drawn under the mouse or picked with keys, with what’s inside it: 0.08 is 8% bigger. 0 keeps its size. (Field: a number.)
• pressShrink: a number = 0. How much smaller than its size it’s drawn while it’s held down: 0.06 is 6% smaller. 0 keeps its size. (Field: a number.)
• popTime: a number = 0. Seconds it takes to grow, shrink and shade into being under the mouse, held down or left, eased, rather than changing at once: 0.1 for a soft pop. 0 changes at once. (Field: a number.)

While the game runs

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

• isHovered: true or false. True while the mouse is over the button.
• isFocused: true or false. True while the keyboard or a gamepad has picked this button: the arrow keys, D-pad or stick move between buttons, and Enter, Space or the A button click the picked one. It’s lit up like the mouse is over it.
• isPressed: true or false. True while the button is held down after being pressed on.
• isUsable: true or false. True while it can be clicked: it’s Interactable, and what it NeedsSaved is saved.
• isMissingSave: true or false. True while the game has nothing saved under NeedsSaved, or, for Load Game, Delete Save and Quick Load, no game saved in the slot (and for saving and loading, during a network game). Kept up to date by the game.
• isListening: true or false. True while a ButtonAction.Rebind button waits for the player to press something.

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