Difference between revisions of "RegisterHookFunction"

Revision as of 21:27, 30 September 2014

registerHookFunction

Available since: v3.0

Registers a hook function for a specific operation.

Lua Syntax:

registerHookFunction(hook, hookFunction)

Arguments

hook

"string" - The operation for which the hook function should be called. Currently supported hooks: "setTextPosition" (the hook is called everytime the position of a displayed text is set), "getActionText" (the hook is called everytime to get the currently displayed action text), "getWalkAnimationIndex" (the hook is called everytime a character changes its direction during walking).

hookFunction

"string" - The name of the lua function which is called when the hook is executed.

"setTextPosition": The function should take exactly one argument which is the affected visionaire object. The function must return a boolean value: true if the operation was handled in the hook function, false if the operation was not handled and should be handled by the engine (as if there were no hook).

"getActionText": The function should take exactly one argument which is the current mouse position (a table containing x- and y-position). The function must return a string value which will be used as the current action text.

"getCharacterAnimationIndex": The function takes exactly 3 arguments: the character (visionaire object), animation type () and new direction (degrees). The function must return an integer value which specifies the walk animation to use for the new direction (0-based index).

If -1 is returned the index is handled by the engine (as if there were no hook).

Flags

Return Values

None.

Examples

Example 1: setTextPosition

function adaptedTextPosition(text)
  -- show texts of character Hero 10 pixel below character position
  local owner = text:getLink(VTextOwner)
  if owner:getId().tableId == eCharacters and owner:getName() == 'Hero' then
    local pos = owner:getPoint(VCharacterPosition)
    pos.y = pos.y + 10
    text:setValue(VTextPosition, pos)
    return true
  end
  return false
end

registerHookFunction("setTextPosition", "adaptedTextPosition")

Example 2: getActionText

function myActionText(mousePos)
  -- individual action text: object name (in current language) of object below cursor, if there is no object then '<empty>' is shown as action text
  local obj = game:getLink(VGameCurrentObject)
  if obj:getId().tableId == eObjects then
    return 'current object: ' .. obj:getTextStr(VObjectName)
  end
  return '<empty>'
end

registerHookFunction("getActionText", "myActionText")

@@ Line 9: / Line 9: @@
 ===Arguments===
 ====hook====
-:'''"string"''' - The operation for which the hook function should be called. Currently supported hooks: "setTextPosition" (the hook is called everytime the position of a displayed text is set), "getActionText" (the hook is called everytime to get the currently displayed action text).
+:'''"string"''' - The operation for which the hook function should be called. Currently supported hooks: "setTextPosition" (the hook is called everytime the position of a displayed text is set), "getActionText" (the hook is called everytime to get the currently displayed action text), "getWalkAnimationIndex" (the hook is called everytime a character changes its direction during walking).
 ====hookFunction====
-:'''"string"''' - The name of the lua function which is called when the hook is executed. "setTextPosition": The function should take exactly one argument which is the affected visionaire object. The function must return a boolean value: true if the operation was handled in the hook function, false if the operation was not handled and should be handled by the engine (as if there were no hook).
+:'''"string"''' - The name of the lua function which is called when the hook is executed.
+:"setTextPosition": The function should take exactly one argument which is the affected visionaire object. The function must return a boolean value: true if the operation was handled in the hook function, false if the operation was not handled and should be handled by the engine (as if there were no hook).
 :"getActionText": The function should take exactly one argument which is the current mouse position (a table containing x- and y-position). The function must return a string value which will be used as the current action text.
+:"getCharacterAnimationIndex": The function takes exactly 3 arguments: the character (visionaire object), animation type () and new direction (degrees). The function must return an integer value which specifies the walk animation to use for the new direction (0-based index).
+:If -1 is returned the index is handled by the engine (as if there were no hook).
 ===Flags===
 ===Return Values===
 None.
 ===Examples===
-None.
+Example 1: setTextPosition
-[[Category:Player Commands]]
+<syntaxhighlight>
+function adaptedTextPosition(text)
+  -- show texts of character Hero 10 pixel below character position
+  local owner = text:getLink(VTextOwner)
+  if owner:getId().tableId == eCharacters and owner:getName() == 'Hero' then
+    local pos = owner:getPoint(VCharacterPosition)
+    pos.y = pos.y + 10
+    text:setValue(VTextPosition, pos)
+    return true
+  end
+  return false
+end
+registerHookFunction("setTextPosition", "adaptedTextPosition")
+</syntaxhighlight>
+Example 2: getActionText
+<syntaxhighlight>
+function myActionText(mousePos)
+  -- individual action text: object name (in current language) of object below cursor, if there is no object then '<empty>' is shown as action text
+  local obj = game:getLink(VGameCurrentObject)
+  if obj:getId().tableId == eObjects then
+    return 'current object: ' .. obj:getTextStr(VObjectName)
+  end
+  return '<empty>'
+end
+registerHookFunction("getActionText", "myActionText")
+</syntaxhighlight>