Grabber

Picks up Draggable things with a button and carries them, for games played with a controller or keys: a cursor moved with the stick or the D-pad (give it a TopDownMovement or a GridMovement), or a character who carries things about. Press Action to pick up what’s under its hand (or else the nearest thing within Reach), and again to put it down where it’s held, onto a DropTarget as a mouse would.

It holds things by their middle at its hand: its own middle, moved by HoldOffset. A drop the mouse would send back (onto a full target or one for other kinds, or off targets for something that only goes on them) does nothing, so it keeps holding the thing. Dropped onto a full target that swaps, it picks up what was there. In a network game each player’s grabber answers to its own player.

Works with: Draggable (things to pick up); DropTarget (places to put them)

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.

• action: text = “Interact”. The input action that picks things up and puts them down, e.g. “Interact” (E, Enter or the gamepad’s Y) or “Jump” (Space or A). (Names an input action.) (Field: a name.)
• holdToCarry: true or false = false. True if it only carries things while Action is held, putting them down when it’s let go, as a mouse does. Otherwise one press picks up and the next puts down. (Field: on or off.)
• reach: a number = 1. How far from its hand a thing’s middle can be and still be picked up, in world units, if nothing is right under its hand. 0 only picks up what’s under it. (A distance: the Scene view draws it as a circle around the entity, with a handle to drag.) (Field: a number.)
• holdOffset: [x, y] = [0,0]. Where it holds things, from its middle, in world units: X is how far in front of it (on the side it faces: left or right, or up or down in a top-down game), Y how far up. (0, 1) is over a character’s head, (0.8, 0) in front of it, (0, 0) a cursor’s middle. (A point offset from the entity, in world units: with Distance Handles the Scene view puts a knob on it to drag.) (Field: a vector.)

Look and Messages

• highlight: a color, “#RRGGBB” or “#RRGGBBAA” = “#FFE082FF”. The color what it would pick up turns, so the player can see what a press takes. Transparent leaves things alone. (Field: a color.)
• refuseSound: text = null. A sound played when a press does nothing: nothing in reach, or nowhere to put what it holds. (A sound in Assets, e.g. “Sounds/hit.wav”.) (Field: a sound.)
• pickUpMessage: text = null. A message sent with Game.Send when it picks something up, with what it picked up as its data. (Names a message.) (Field: a name.)
• dropMessage: text = null. A message sent with Game.Send when it puts something down, with what it put down as its data. (Names a message.) (Field: a name.)

While the game runs

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

• holding: an entity: its name, id or path. What it’s carrying (a Draggable’s entity), or null.
• inReach: an entity: its name, id or path. What a press would pick up now (lit with Highlight), or null. Null while it’s carrying something.

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