Difference between revisions of "Modding:Modder Guide/APIs/Input"
Pathoschild (talk | contribs) (+ footer nav links) |
Pathoschild (talk | contribs) (+ SButton info from Modding:Modder Guide/APIs/Utilities (only author is Pathoschild)) |
||
Line 4: | Line 4: | ||
The input API lets you check and suppress controller/keyboard/mouse state. | The input API lets you check and suppress controller/keyboard/mouse state. | ||
− | == | + | ==Constants== |
− | === | + | ===SButton=== |
+ | SMAPI's <tt>SButton</tt> constants unify the [https://msdn.microsoft.com/en-us/library/microsoft.xna.framework.input.buttons.aspx <tt>Buttons</tt>], [https://msdn.microsoft.com/en-us/library/microsoft.xna.framework.input.keys.aspx <tt>Keys</tt>], [https://msdn.microsoft.com/en-us/library/microsoft.xna.framework.input.mousestate.aspx <tt>MouseState</tt>], and <tt>InputButton</tt> 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 <tt>SButton</tt>: | ||
+ | <source lang="c#"> | ||
+ | SButton key = Keys.A.ToSButton(); // SButton.A | ||
+ | SButton button = Buttons.A.ToSButton(); // SButton.ControllerA | ||
+ | SButton input = new InputButton(true).ToSButton(); // SButton.MouseLeft | ||
+ | </source> | ||
+ | |||
+ | You can also convert <tt>SButton</tt> to the other constants. This uses a <tt>TryGet</tt> approach since <tt>SButton</tt> is a superset of the others (e.g. you can't convert <tt>SButton.ControllerA</tt> to a keyboard value): | ||
+ | <source lang="c#"> | ||
+ | SButton value = SButton.A; | ||
+ | if (value.TryGetKeyboard(out Keys key)) | ||
+ | ...; | ||
+ | if (value.TryGetController(out Buttons button)) | ||
+ | ...; | ||
+ | if (value.TryGetStardewInput(out InputButton input)) | ||
+ | ...; | ||
+ | </source> | ||
+ | |||
+ | Two last extensions let you check how the button is mapped in the game: | ||
+ | <source lang="c#"> | ||
+ | SButton button = SButton.MouseLeft; | ||
+ | if (button.IsUseToolButton()) | ||
+ | // use tool | ||
+ | else if (button.IsActionButton()) | ||
+ | // perform action | ||
+ | </source> | ||
+ | |||
+ | You can use <tt>SButton</tt> values directly in your [[../Config|config model]], and they'll be represented by their names: | ||
+ | {| class="wikitable" | ||
+ | | <source lang="c#"> | ||
+ | internal class ModConfig | ||
+ | { | ||
+ | public SButton DoThingButton { get; set; } = SButton.LeftControl; | ||
+ | } | ||
+ | </source> | ||
+ | | → | ||
+ | | <source lang="json"> | ||
+ | { | ||
+ | "DoThingButton": "LeftControl" | ||
+ | } | ||
+ | </source> | ||
+ | |} | ||
+ | |||
+ | ==APIs== | ||
+ | ===Check button state=== | ||
You can check if any controller/keyboard/mouse button is currently pressed by calling the <tt>IsDown(button)</tt> method. For example: | You can check if any controller/keyboard/mouse button is currently pressed by calling the <tt>IsDown(button)</tt> method. For example: | ||
<source lang="c#"> | <source lang="c#"> | ||
Line 11: | Line 58: | ||
</source> | </source> | ||
− | === | + | ===Check cursor position=== |
The <tt>GetCursorPosition()</tt> method provides the cursor position in three coordinate systems: | The <tt>GetCursorPosition()</tt> method provides the cursor position in three coordinate systems: | ||
* <tt>ScreenPixels</tt> is the pixel position relative to the top-left corner of the visible screen, adjusted for game zoom. | * <tt>ScreenPixels</tt> is the pixel position relative to the top-left corner of the visible screen, adjusted for game zoom. | ||
Line 24: | Line 71: | ||
</source> | </source> | ||
− | == | + | ===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. | 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. | ||
Revision as of 20:57, 10 June 2018
- Get started
- Game fundamentals
- Test & troubleshoot
- Release
- API reference
- Basic SMAPI APIs:
- Advanced SMAPI APIs:
- Specific guides
The input API lets you check and suppress controller/keyboard/mouse state.
Constants
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"
}
|
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:
- 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.
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