Modding:Modder Guide/APIs/Input

Creating SMAPI mods

---

• Get started
• Game fundamentals
• Test & troubleshoot
• Release
• API reference

  Basic SMAPI APIs:

  • Mod structure
  • Manifest
  • Events
  • Configuration
  • Load & edit content
  • Data
  • Input
  • Logging
  • Reflection
  • Multiplayer
  • Translation
  • Update checks
  • Utilities

  Advanced SMAPI APIs:

  • Content packs
  • Mod console commands
  • Mod integrations
  • Harmony patching

• Specific guides

← Modding:Index

The following describes the upcoming SMAPI 2.6-beta.16, and may change before release.

The input API lets you check and suppress controller/keyboard/mouse state.

Data structures

SButton

SMAPI's SButton constants unify the Buttons, Keys, MouseState, and InputButton constants. SMAPI events use this to let you handle controller, keyboard, and mouse input without needing separate code for each. See Modding:Key bindings for a list of values.

SMAPI provides extensions to convert any of the other constants to SButton:

SButton key = Keys.A.ToSButton(); // SButton.A
SButton button = Buttons.A.ToSButton(); // SButton.ControllerA
SButton input = new InputButton(true).ToSButton(); // SButton.MouseLeft

You can also convert SButton to the other constants. This uses a TryGet approach since SButton is a superset of the others (e.g. you can't convert SButton.ControllerA to a keyboard value):

SButton value = SButton.A;
if (value.TryGetKeyboard(out Keys key))
   ...;
if (value.TryGetController(out Buttons button))
   ...;
if (value.TryGetStardewInput(out InputButton input))
   ...;

Two last extensions let you check how the button is mapped in the game:

SButton button = SButton.MouseLeft;
if (button.IsUseToolButton())
   // use tool
else if (button.IsActionButton())
   // perform action

You can use SButton values directly in your config model, and they'll be represented by their names:

internal class ModConfig { public SButton DoThingButton { get; set; } = SButton.LeftControl; }

→

{ "DoThingButton": "LeftControl" }

ICursorPosition

SMAPI's ICursorPosition provides the cursor position in three coordinate systems:

• ScreenPixels is the pixel position relative to the top-left corner of the visible screen, adjusted for game zoom.
• Tile is the tile position under the cursor.
• GrabTile is the tile position that the game considers under the cursor for the purposes of clicking actions. This automatically accounts for controller mode. This may be different than Tile if that's too far from the player.

This is returned by the this.Helper.Input.GetCursorPosition() method and in the event args for some input events.

APIs

Check button state

You can check if any controller/keyboard/mouse button is currently pressed by calling the IsDown(button) method. For example:

bool isShiftPressed = this.Helper.Input.IsDown(SButton.LeftShift) || this.Helper.Input.IsDown(SButton.RightShift);

Check cursor position

The GetCursorPosition() method provides the cursor position in three coordinate systems; see ICursorPosition.

For example:

// draw text at the cursor position
ICursorPosition cursorPos = this.Helper.Input.GetCursorPosition();
Game1.spriteBatch.DrawString(Game1.smallFont, "some text", cursorPos.ScreenPixels, Color.Black);

Suppress input

You can prevent the game from handling any controller/keyboard/mouse button press (including clicks) by suppressing it. This suppression will remain in effect until the player releases the button. This won't prevent other mods from handling it.

For example, this will prevent the game from seeing that the LeftShift button is pressed:

this.Helper.Input.Suppress(SButton.LeftShift);

That works for clicks too:

this.Helper.Input.Suppress(SButton.MouseLeft);

You can also check if a button is being suppressed:

if (this.Helper.Input.IsSuppressed(SButton.LeftShift))
   // left shift button is being suppressed

See also

• Input events
• Modding:Key bindings for a list of valid SButton values

← SMAPI reference