Global Command: registerHookFunction - Revision history

EK at 09:26, 11 August 2023

2023-08-11T09:26:44Z

EK at 08:20, 22 May 2023

2023-05-22T08:20:49Z

EK: Created page with "Register a hook function for a specific operation. == Syntax == registerHookFunction(operation, hookFunction) == Parameters..."

2023-05-18T12:00:42Z

Created page with "Register a hook function for a specific operation. == Syntax == <syntaxhighlight lang="lua"> registerHookFunction(operation, hookFunction) </syntaxhighlight> == Parameters..."

New page

Register a hook function for a specific operation.

== Syntax ==
<syntaxhighlight lang="lua">
registerHookFunction(operation, hookFunction)
</syntaxhighlight>

== Parameters ==

{| class="ts"
|-
! style="width:15%" | Parameter
! style="width:15%" | Type
! style="width:15%" | Supported values
! colspan="2" | Description
|-
| rowspan="6" | operation
| rowspan="6" | string
| "getActionText"
| Hook into the action text display. Lets you change/set the action text.
| rowspan="6" style="width:15%" | The operation for which the hook function should be called.
|-
| "getCharacterAnimationIndex"
| Hook into the change of the character animation. Lets you change/set the character animation index.
|-
| "renderObject"
|
|-
| "setTextPosition"
| Hook into the text display. Lets you change/set the text position.
|-
| "textRender"
| Hook into the text display. Lets you write your own rendering routine.
|-
| "textText"
| Hook into the text display. Lets you change/set the current text.
|-
| hookFunction
| string
|
| colspan="2" | The name of the function which is called when the hook is executed. See the table below for the arguments the function takes.
|}

=== Hook function ===

Depending on the operation, the hook function takes and returns different arguments/values.

{| class="ts"
|-
! style="width:15%" | operation
! style="width:15%" | Arguments
! Description
! style="width:15%" | Return value
|-
| rowspan="2" | "getActionText"
| mousePos (t_point)
| The current mouse position (an associative array containing the elements '''x (int)''' and '''y (int)''').
| rowspan="2" | The new action text (str).
|-
| actionText (str)
| The default action text generated by the engine.
|-
| rowspan="3" | "getCharacterAnimationIndex"
| character (TVisObj)
| The current character object.
| rowspan="3" style="width:15%" | Index (0-based) of the character animation to use for the new direction (int).

If -1 is returned, the index is handled by the engine, ignoring the hook.
|-
| animState (int)
| The current animation state. Supported values:
* eNoAnim (0)
* eWalkAnim (1)
* eTalkAnim (2)
* eStandingAnim (3)
* eCharacterAnim (4)
* eRandomAnim (5)
|-
| newDirection (int)
| The direction of the upcoming character animation.
|-
| "renderObject"
|
|
|
|-
| "setTextPosition"
| text (TVisObj)
| The affected text object.
| True if the operation was handled in the hook function, false if the operation should be handled by the engine, ignoring the hook (bool).
|-
| "textRender"
| text (TVisObj)
| The affected text object.
| True if the rendering was handled in the hook function, false if the engine should render the text, ignoring the hook (bool).
|-
| "textText"
| text (TVisObj)
| The affected text object.
| The text to display (str).
|}

== Return values ==

none

== Examples ==

'''Example 1:''' Generate an individual action text.
<syntaxhighlight lang="lua">
function myActionText(mousePos, actionText)
local obj = game.CurrentObject

if obj:getId().tableId == eObjects then
return 'This is a ' .. obj:getTextStr(VObjectName)
else
return ""
end
end

registerHookFunction("getActionText", "myActionText")
</syntaxhighlight>

'''Example 2:''' Place character texts in the top left corner of the screen (assuming text alignment is set to "Left" in the game properties).
<syntaxhighlight lang="lua">
function myTextPosition(text)
local owner = text.Owner

if owner:getId().tableId == eCharacters then
text.Position = {x = game.ScrollPosition.x + 30, y = game.ScrollPosition.y + 30}

return true
else
return false
end
end

registerHookFunction("setTextPosition", "myTextPosition")
</syntaxhighlight>
{{toc}}

@@ Line 109: / Line 109: @@
    local obj = game.CurrentObject
-   if obj:getId().tableId == eObjects then
+   if obj.tableId == eObjects then
      return 'This is a ' .. obj:getTextStr(VObjectName)
    else
@@ Line 125: / Line 125: @@
    local owner = text.Owner
-   if owner:getId().tableId == eCharacters then
+   if owner.tableId == eCharacters then
      text.Position = {x = game.ScrollPosition.x + 30, y = game.ScrollPosition.y + 30}

@@ Line 17: / Line 17: @@
 ! colspan="2" | Description
 |-
-| rowspan="6" | operation
+| rowspan="5" | operation
-| rowspan="6" | string
+| rowspan="5" | string
 | "getActionText"
 | Hook into the action text display. Lets you change/set the action text.
-| rowspan="6" style="width:15%" | The operation for which the hook function should be called.
+| rowspan="5" style="width:15%" | The operation for which the hook function should be called.
 |-
 | "getCharacterAnimationIndex"
 | Hook into the change of the character animation. Lets you change/set the character animation index.
 |-
 | "setTextPosition"
@@ Line 82: / Line 79: @@
 | newDirection (int)
 | The direction of the upcoming character animation.
 |-
 | "setTextPosition"