Player input
Scripts can read the local player's controls, for example to drive a vehicle or fire a toy. Input works the same on desktop, in VR, with a gamepad and with the on-screen controls on phones. (In VRChat terms: Udon input events.)
Reading input every frame
StageTimeInput holds the current state. Read it in Update or FixedUpdate:
Vector2 move = StageTimeInput.move; // x = right, y = forward, each -1 to 1
Vector2 look = StageTimeInput.look; // x = right, y = up
bool jumping = StageTimeInput.GetButton(STInputButton.Jump);
float throttle = StageTimeInput.GetButtonValue(STInputButton.Use); // 0 to 1
GetButtonValue says how far a button is pressed, from 0 to 1. Triggers (Use, SecondaryUse) and the VR grip (Grab)
are analog on VR controllers and gamepads, so a half-pulled trigger gives about 0.5: use it for a throttle or a
spray strength. Keys, mouse buttons and the other buttons give 0 or 1. The events and GetButton turn on past
about half way.
Input events
Every script in the world gets these events when the input changes, on the local player's device only:
| Event | When |
|---|---|
OnInputJump(bool value, STInputArgs args) | Jump pressed (true) or released (false) |
OnInputUse(bool value, STInputArgs args) | Use pressed or released |
OnInputGrab(bool value, STInputArgs args) | Grab pressed or released |
OnInputDrop(bool value, STInputArgs args) | Drop pressed or released (in VR: a grip let go, see below) |
OnInputSecondaryUse(bool value, STInputArgs args) | SecondaryUse pressed or released |
OnInputMoveHorizontal(float value, STInputArgs args) | Move left/right changed (-1 to 1) |
OnInputMoveVertical(float value, STInputArgs args) | Move back/forward changed |
OnInputLookHorizontal(float value, STInputArgs args) | Look left/right changed |
OnInputLookVertical(float value, STInputArgs args) | Look down/up changed |
public override void OnInputJump(bool value, STInputArgs args)
{
if (value) Debug.Log("Jump pressed with the " + args.handType + " hand");
}
STInputArgs has eventType (Button or Axis), boolValue, floatValue and handType (Left or Right;
keyboard input counts as Left and mouse input as Right).
Controls
| Input | Desktop | VR | Gamepad / phone |
|---|---|---|---|
| Move | W A S D | left stick | left stick |
| Look | arrow keys | right stick | right stick |
| Jump | Space | A (right controller) | Y / North, the on-screen jump button |
| Use | left mouse button | right trigger | right trigger |
| SecondaryUse | F | left trigger | left trigger |
| Grab | left mouse button | grip | left shoulder |
| Drop | right mouse button | letting go of a grip | B / East |
In VR, Drop happens when a grip is let go and that hand is holding nothing: OnInputDrop gets true and then
false straight away, from that hand. With the player's sticky grab setting on, the first release keeps the
object in hand, so Drop comes with the second release, when the object is actually let go. Because of this, GetButton(STInputButton.Drop) is never seen held in VR. React to the event. Letting go of a held
ST Pickup drops it as well, whatever the script does.
Input pauses while the StageTime menu, the on-screen keyboard or a text field is open; anything held is released
first (false and 0 events), so a script never sees a button stuck down.
Players still walk and turn with the same controls, so input on its own is best for actions. To take over a player's movement, seat them in an ST Seat with Take Controls: the Drivable car example does this.