106,307
edits
Changes
Modding:Modder Guide/APIs/Input (view source)
Revision as of 18:48, 4 November 2021
, 18:48, 4 November 2021Text replacement - "tt>" to "samp>"
===Check button state===
===Check button state===
<dl>
<dl>
<dt><tt>IsDown</tt></dt>
<dt><samp>IsDown</samp></dt>
<dd>
<dd>
You can check if any [[#SButton|controller/keyboard/mouse button]] is currently pressed by calling the <tt>IsDown(button)</tt> method. For example:
You can check if any [[#SButton|controller/keyboard/mouse button]] is currently pressed by calling the <samp>IsDown(button)</samp> method. For example:
<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
bool isShiftPressed = this.Helper.Input.IsDown(SButton.LeftShift) || this.Helper.Input.IsDown(SButton.RightShift);
bool isShiftPressed = this.Helper.Input.IsDown(SButton.LeftShift) || this.Helper.Input.IsDown(SButton.RightShift);
</dd>
</dd>
<dt><tt>GetState</tt></dt>
<dt><samp>GetState</samp></dt>
<dd>
<dd>
For more finetuned control, you can check the [[#SButton|button]] state relative to the previous game tick:
For more finetuned control, you can check the [[#SButton|button]] state relative to the previous game tick:
| up
| up
| up
| up
| <tt>None</tt>
| <samp>None</samp>
|-
|-
| up
| up
| down
| down
| <tt>Pressed</tt>
| <samp>Pressed</samp>
|-
|-
| down
| down
| down
| down
| <tt>Held</tt>
| <samp>Held</samp>
|-
|-
| down
| down
| up
| up
| <tt>Released</tt>
| <samp>Released</samp>
|}
|}
</dd>
</dd>
===Check cursor position===
===Check cursor position===
The <tt>GetCursorPosition()</tt> method provides the [[#ICursorPosition|cursor position in three coordinate systems|ICursorPosition]].
The <samp>GetCursorPosition()</samp> method provides the [[#ICursorPosition|cursor position in three coordinate systems|ICursorPosition]].
For example:
For example:
|-
|-
| <code>Suppress</code>
| <code>Suppress</code>
| Suppress the specified [[#SButton|<tt>SButton</tt>]] value.
| Suppress the specified [[#SButton|<samp>SButton</samp>]] value.
|-
|-
| <code>SuppressActiveKeybinds</code>
| <code>SuppressActiveKeybinds</code>
| For the given [[#KeybindList|<tt>KeybindList</tt>]], suppress every button that's part of an activated keybind.
| For the given [[#KeybindList|<samp>KeybindList</samp>]], suppress every button that's part of an activated keybind.
|-
|-
| <code>IsSuppressed</code>
| <code>IsSuppressed</code>
| Get whether the specified [[#SButton|<tt>SButton</tt>]] value is currently suppressed.
| Get whether the specified [[#SButton|<samp>SButton</samp>]] value is currently suppressed.
|}
|}
Side-effects:
Side-effects:
<ul>
<ul>
<li>The [[Modding:Modder Guide/APIs/Events#Input.ButtonReleased|<tt>ButtonReleased</tt> event]] will be raised on the next tick for the suppressed input.</li>
<li>The [[Modding:Modder Guide/APIs/Events#Input.ButtonReleased|<samp>ButtonReleased</samp> event]] will be raised on the next tick for the suppressed input.</li>
<li>Methods like <tt>helper.Input.IsDown(button)</tt> and <tt>helper.Input.GetState(button)</tt> will show the button as released for the duration of the suppression, even if it's physically still pressed. You can use <tt>helper.Input.IsSuppressed(button)</tt> to check if that's the case (it will only be true until the button is physically released):
<li>Methods like <samp>helper.Input.IsDown(button)</samp> and <samp>helper.Input.GetState(button)</samp> will show the button as released for the duration of the suppression, even if it's physically still pressed. You can use <samp>helper.Input.IsSuppressed(button)</samp> to check if that's the case (it will only be true until the button is physically released):
<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
bool isPhysicallyDown = helper.Input.IsDown(button) || helper.Input.IsSuppressed(button);
bool isPhysicallyDown = helper.Input.IsDown(button) || helper.Input.IsSuppressed(button);
==Data structures==
==Data structures==
===SButton===
===SButton===
SMAPI's <tt>SButton</tt> is a constant which includes every [https://docs.microsoft.com/en-us/previous-versions/windows/xna/bb975202(v%3dxnagamestudio.40) controller], [https://docs.microsoft.com/en-us/previous-versions/windows/xna/bb197781(v%3dxnagamestudio.40) keyboard], and [https://docs.microsoft.com/en-us/previous-versions/windows/xna/bb198097(v%3dxnagamestudio.40) mouse] button. SMAPI events use this to let you handle button presses without needing separate code for each. See [[Modding:Player Guide/Key Bindings]] for a list of values.
SMAPI's <samp>SButton</samp> is a constant which includes every [https://docs.microsoft.com/en-us/previous-versions/windows/xna/bb975202(v%3dxnagamestudio.40) controller], [https://docs.microsoft.com/en-us/previous-versions/windows/xna/bb197781(v%3dxnagamestudio.40) keyboard], and [https://docs.microsoft.com/en-us/previous-versions/windows/xna/bb198097(v%3dxnagamestudio.40) mouse] button. SMAPI events use this to let you handle button presses without needing separate code for each. See [[Modding:Player Guide/Key Bindings]] for a list of values.
SMAPI provides extensions to convert any of the other constants to <tt>SButton</tt>:
SMAPI provides extensions to convert any of the other constants to <samp>SButton</samp>:
<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
SButton key = Keys.A.ToSButton(); // SButton.A
SButton key = Keys.A.ToSButton(); // SButton.A
</syntaxhighlight>
</syntaxhighlight>
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):
You can also convert <samp>SButton</samp> to the other constants. This uses a <samp>TryGet</samp> approach since <samp>SButton</samp> is a superset of the others (e.g. you can't convert <samp>SButton.ControllerA</samp> to a keyboard value):
<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
SButton value = SButton.A;
SButton value = SButton.A;
</syntaxhighlight>
</syntaxhighlight>
You can use <tt>SButton</tt> values directly in your [[../Config|config model]], but <tt>[[#KeybindList|KeybindList]]</tt> is recommended instead in most cases.
You can use <samp>SButton</samp> values directly in your [[../Config|config model]], but <samp>[[#KeybindList|KeybindList]]</samp> is recommended instead in most cases.
===KeybindList===
===KeybindList===
SMAPI's <tt>KeybindList</tt> utility lets you manage an arbitrary set of keybindings. A ''keybind list'' has any number of ''keybinds'', each of which has any number of [[#SButton|button codes]]. For example, the keybind list <code>"F2, LeftShift + S"</code> would be pressed if (a) <tt>F2</tt> is pressed, ''or'' (b) both <tt>LeftShift</tt> and <tt>S</tt> are pressed.
SMAPI's <samp>KeybindList</samp> utility lets you manage an arbitrary set of keybindings. A ''keybind list'' has any number of ''keybinds'', each of which has any number of [[#SButton|button codes]]. For example, the keybind list <code>"F2, LeftShift + S"</code> would be pressed if (a) <samp>F2</samp> is pressed, ''or'' (b) both <samp>LeftShift</samp> and <samp>S</samp> are pressed.
You can use a <tt>KeybindList</tt> directly in [[../Config|your <tt>config.json</tt> model]]:
You can use a <samp>KeybindList</samp> directly in [[../Config|your <samp>config.json</samp> model]]:
{| class="wikitable"
{| class="wikitable"
|}
|}
And you can then check whether it's pressed directly in your code. For example, in a [[../Events|<tt>ButtonsChanged</tt> event handler]]:
And you can then check whether it's pressed directly in your code. For example, in a [[../Events|<samp>ButtonsChanged</samp> event handler]]:
<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
</syntaxhighlight>
</syntaxhighlight>
The <tt>KeybindList</tt> provides a number of methods depending on your use case:
The <samp>KeybindList</samp> provides a number of methods depending on your use case:
{| class="wikitable"
{| class="wikitable"
|-
|-
| <code>GetState()</code>
| <code>GetState()</code>
| Get the overall [[#Check button state|keybind state relative to the previous tick]]. This state is transitive across keybinds; e.g. if the player releases one keybind and immediately presses another within the list, the overall state is <tt>Held</tt>.
| Get the overall [[#Check button state|keybind state relative to the previous tick]]. This state is transitive across keybinds; e.g. if the player releases one keybind and immediately presses another within the list, the overall state is <samp>Held</samp>.
|-
|-
| <code>IsDown()</code>
| <code>IsDown()</code>
|-
|-
| <code>JustPressed()</code>
| <code>JustPressed()</code>
| Get whether the player just activated the keybind during the current tick (i.e. <code>GetState()</code> returns <tt>Pressed</tt> instead of <tt>Held</tt>).
| Get whether the player just activated the keybind during the current tick (i.e. <code>GetState()</code> returns <samp>Pressed</samp> instead of <samp>Held</samp>).
|-
|-
| <code>GetKeybindCurrentlyDown()</code>
| <code>GetKeybindCurrentlyDown()</code>
| Get the individual <tt>Keybind</tt> in the list which is currently down, if any. If there are multiple keybinds down, the first one is returned.
| Get the individual <samp>Keybind</samp> in the list which is currently down, if any. If there are multiple keybinds down, the first one is returned.
|-
|-
| <code>ToString()</code>
| <code>ToString()</code>
Caveats:
Caveats:
* '''Don't use the <tt>ButtonPressed</tt> [[../Events|event]] to check keybinds''', since it's raised once for each button pressed. If the player presses two keys at once, your keybind would be activated twice. Use <tt>ButtonsChanged</tt> instead.
* '''Don't use the <samp>ButtonPressed</samp> [[../Events|event]] to check keybinds''', since it's raised once for each button pressed. If the player presses two keys at once, your keybind would be activated twice. Use <samp>ButtonsChanged</samp> instead.
===ICursorPosition===
===ICursorPosition===
SMAPI's <tt>ICursorPosition</tt> provides the cursor position in four coordinate systems:
SMAPI's <samp>ICursorPosition</samp> provides the cursor position in four coordinate systems:
* <tt>AbsolutePixels</tt> is the pixel position relative to the top-left corner of the in-game map, adjusted for [[Modding:Modder Guide/Game Fundamentals#Zoom level|zoom]] but not [[Modding:Modder Guide/Game Fundamentals#UI scaling|UI scaling]].
* <samp>AbsolutePixels</samp> is the pixel position relative to the top-left corner of the in-game map, adjusted for [[Modding:Modder Guide/Game Fundamentals#Zoom level|zoom]] but not [[Modding:Modder Guide/Game Fundamentals#UI scaling|UI scaling]].
* <tt>ScreenPixels</tt> is the pixel position relative to the top-left corner of the visible screen, adjusted for [[Modding:Modder Guide/Game Fundamentals#Zoom level|zoom]] but not [[Modding:Modder Guide/Game Fundamentals#UI scaling|UI scaling]].
* <samp>ScreenPixels</samp> is the pixel position relative to the top-left corner of the visible screen, adjusted for [[Modding:Modder Guide/Game Fundamentals#Zoom level|zoom]] but not [[Modding:Modder Guide/Game Fundamentals#UI scaling|UI scaling]].
* <tt>Tile</tt> is the [[Modding:Modder Guide/Game Fundamentals#Tiles|tile position]] under the cursor.
* <samp>Tile</samp> is the [[Modding:Modder Guide/Game Fundamentals#Tiles|tile position]] under the cursor.
* <tt>GrabTile</tt> 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 <tt>Tile</tt> if that's too far from the player.
* <samp>GrabTile</samp> 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 <samp>Tile</samp> if that's too far from the player.
This is returned by the <tt>this.Helper.Input.GetCursorPosition()</tt> method and in the event args for some input events.
This is returned by the <samp>this.Helper.Input.GetCursorPosition()</samp> method and in the event args for some input events.
'''The pixel positions are ''not'' adjusted for [[Modding:Modder Guide/Game Fundamentals#UI scaling|UI scaling]]''' (i.e. they're non-UI mode). Whether you need UI or non-UI positions depends how you're using them, so you can use <tt>cursorPos.GetScaledAbsolutePixels()</tt> or <tt>cursorPos.GetScaledScreenPixels()</tt> to adjust them automatically for the current mode or <tt>Utility.ModifyCoordinatesForUIScale</tt> to always get UI mode coordinates.
'''The pixel positions are ''not'' adjusted for [[Modding:Modder Guide/Game Fundamentals#UI scaling|UI scaling]]''' (i.e. they're non-UI mode). Whether you need UI or non-UI positions depends how you're using them, so you can use <samp>cursorPos.GetScaledAbsolutePixels()</samp> or <samp>cursorPos.GetScaledScreenPixels()</samp> to adjust them automatically for the current mode or <samp>Utility.ModifyCoordinatesForUIScale</samp> to always get UI mode coordinates.
==See also==
==See also==
* [[../Events#Input|Input events]]
* [[../Events#Input|Input events]]
* [[Modding:Player Guide/Key Bindings]] for a list of valid <tt>SButton</tt> values
* [[Modding:Player Guide/Key Bindings]] for a list of valid <samp>SButton</samp> values