diff --git a/docs/10.0/Functions-(Verb-Interaction).md b/docs/10.0/Functions-(Verb-Interaction).md index 58535477..da0e649c 100644 --- a/docs/10.0/Functions-(Verb-Interaction).md +++ b/docs/10.0/Functions-(Verb-Interaction).md @@ -4,26 +4,21 @@ ## …VerbConsume -`InputVerbConsume()` +`InputVerbConsume(verbIndex, [playerIndex=0])` <!-- tabs:start --> #### **Description** -**Returns:** , +**Returns:** N/A (`undefined`) |Name |Datatype|Purpose | |---------------|--------|----------------------------------------------------| +|`verbIndex` |integer |Verb to consume | +|`[playerIndex]`|integer |Player to target. If not specified, player 0 is used| -Returns - -#### **Example** +"Consumes" a verb, causing it to be immediately deactivated and return a value of zero until the verb is retriggered (e.g. by released a keyboard key and pressed it again). This helpful when navigating menus to prevent multiple inputs. -```gml -{ - -} -``` <!-- tabs:end --> @@ -36,105 +31,86 @@ Returns #### **Description** -**Returns:** , +**Returns:** N/A (`undefined`) |Name |Datatype|Purpose | |---------------|--------|----------------------------------------------------| +|`[playerIndex]`|integer |Player to target. If not specified, player 0 is used| -Returns +"Consumes" all verbs for a player, causing them to be immediately deactivated and return a value of zero until a verb is retriggered (e.g. by released a keyboard key and pressed it again). -#### **Example** - -```gml -{ - -} -``` <!-- tabs:end --> -## …VerbCount +## …VerbGetExportName -`InputVerbCount()` +`InputVerbGetExportName(verbIndex)` <!-- tabs:start --> #### **Description** -**Returns:** , - -|Name |Datatype|Purpose | -|---------------|--------|----------------------------------------------------| +**Returns:** String, the export name for a verb -Returns +|Name |Datatype|Purpose | +|-----------|--------|----------------------------------| +|`verbIndex`|integer |Verb whose name should be returned| -#### **Example** +Returns the export name for a verb, as defined by `InputDefineVerb()`. -```gml -{ - -} -``` <!-- tabs:end --> ## …VerbGetBindingName -`InputVerbGetBindingName()` +`InputVerbGetBindingName(verbIndex, [alternate=0], [playerIndex=0], [missingBindingName="???"])` <!-- tabs:start --> #### **Description** -**Returns:** , - -|Name |Datatype|Purpose | -|---------------|--------|----------------------------------------------------| +**Returns:** String, the name for a verb's binding using the player's current device -Returns +|Name |Datatype|Purpose | +|----------------------|--------|----------------------------------------------------------------------------------------| +|`verbIndex` |integer |Verb whose binding name should be returned | +|`[alternate]` |integer |Which alternate binding to target. If not specified, index 0 is used | +|`[playerIndex]` |integer |Player to target. If not specified, player 0 is used | +|`[missingBindingName]`|string |String to return if a binding name cannot be resolved. If not specified, `"???"` is used| -#### **Example** +Returns a name for a verb's binding using the player's current device. If a name for a binding cannot be found, this function will return `missingBindingName` (which is `"???"` by default). [You can find a full list of possible return values here](Binding-Names). + +!> This function is provided for basic binding naming and is suitable for debugging or alpha-quality games. Please use the "Binding Icons" plug-in for a higher quality system. -```gml -{ - -} -``` <!-- tabs:end --> -## …VerbGetExportName +## …VerbCount -`InputVerbGetExportName()` +`InputVerbCount()` <!-- tabs:start --> #### **Description** -**Returns:** , - -|Name |Datatype|Purpose | -|---------------|--------|----------------------------------------------------| +**Returns:** Integer, the number of defined verbs -Returns +|Name|Datatype|Purpose| +|----|--------|-------| +|None| | | -#### **Example** +Returns the number of verbs defined in `InputDefineVerb()`. -```gml -{ - -} -``` <!-- tabs:end --> ## …VerbStateArray -`InputVerbStateArray()` +`InputVerbStateArray([newArray=true], [playerIndex=0])` <!-- tabs:start --> @@ -142,42 +118,69 @@ Returns **Returns:** , -|Name |Datatype|Purpose | -|---------------|--------|----------------------------------------------------| +|Name |Datatype|Purpose | +|---------------|--------|------------------------------------------------------------------------------------------------------| +|`[newArray]` |boolean |Whether a new array should be returned (`true`) or whether a static array should be returned (`false`)| +|`[playerIndex]`|integer |Player to target. If not specified, player 0 is used | -Returns +Returns an array of verb states which are copies of the current verb state in the library. This is useful for interrogating verb history for e.g. a combo system. The verb states are structs that contain the following values: -#### **Example** +|Variable |Usage | +|-------------|-----------------------------------------------| +|`.prevHeld` |Whether the verb was held in the previous frame| +|`.held` |Whether the verb is held on this frame | +|`.valueRaw` |Raw analogue value | +|`.valueClamp`|Analogue value after remapping and clamping | +|`.duration` |Number of frames since the verb was pressed | -```gml -{ - -} -``` <!-- tabs:end --> -## …VerbStateByteLength +## …VerbStateWrite -`InputVerbStateByteLength()` +`InputVerbStateWrite(buffer, [playerIndex=0])` <!-- tabs:start --> #### **Description** -**Returns:** , +**Returns:** N/A (`undefined`) |Name |Datatype|Purpose | |---------------|--------|----------------------------------------------------| +|`buffer` |buffer |Buffer to write verb state into | +|`[playerIndex]`|integer |Player to target. If not specified, player 0 is used| + +Writes the current verb state into a buffer. Four values are written: -Returns +|Datatype |Value | +|-------------|-----------------------------------------------| +|`buffer_bool`|Whether the verb was held in the previous frame| +|`buffer_f32` |Raw analogue value | +|`buffer_f32` |Analogue value after remapping and clamping | +|`buffer_s32` |Number of frames since the verb was pressed | -#### **Example** +The verb state is preceded by the string "<-PWP" and ends with the string ">". Verb state can be restored by calling `InputPlugInVerbStateRead()` (but this read function must be called in a `INPUT_PLUG_IN_CALLBACK.UPDATE_PLAYER` callback). -```gml -{ - -} -``` <!-- tabs:end --> + + + +## …VerbStateByteLength + +`InputVerbStateByteLength(buffer, [playerIndex=0])` + +<!-- tabs:start --> + +#### **Description** + +**Returns:** Integer, the number of bytes that a verb state will occupy + +|Name|Datatype|Purpose| +|----|--------|-------| +|None| | | + +Returns the number of bytes that a verb state will occupy if `InputVerbStateWrite()` is called. + +<!-- tabs:end --> \ No newline at end of file