88 lines
2.4 KiB
Markdown
88 lines
2.4 KiB
Markdown
# How to use hooks
|
|
|
|
Hooks are basically functions that get called when events happen in-game, like chat messages. They can be triggered either by Lua itself or the game code.
|
|
|
|
## Adding hooks
|
|
|
|
Hooks can be added like this:
|
|
|
|
```
|
|
Hook.Add("chatMessage", "test", function(message, client)
|
|
print(client.Name .. " has sent " .. message)
|
|
end)
|
|
```
|
|
|
|
The event name (first argument), is case-insensitive, so you can call it chatMessage, cHaTmEsSaGe, chatmessage, etc.
|
|
|
|
## Calling hooks
|
|
|
|
You can also call hooks with the following code:
|
|
|
|
```
|
|
Hook.Call("myCustomEvent", {"some", "arguments", 123})
|
|
```
|
|
|
|
## XML Status Effect Hooks
|
|
|
|
With Lua, a new XML tags is added, it can be used to call hooks inside status effects:
|
|
|
|
```
|
|
<StatusEffect type="OnUse">
|
|
<Hook name="doSomething" custom="thing" />
|
|
</StatusEffect>
|
|
```
|
|
|
|
```
|
|
Hook.Add("doSomething", function(effect, deltaTime, item, targets, worldPosition, element)
|
|
print(effect, ' ', item)
|
|
|
|
-- You can also access the XML custom parameters
|
|
print(element.GetAttributeString("custom", "default value"))
|
|
end)
|
|
```
|
|
|
|
## Patching
|
|
|
|
Patching allows you to hook into existing methods in the game code.
|
|
Be aware that it can be a little unstable depending on the method that you are patching.
|
|
|
|
If your lua function returns **any** value (including `nil`), it will replace
|
|
the return value of the original method.
|
|
|
|
### Postfix
|
|
|
|
Postfixes are functions that get called after the original method executes.
|
|
|
|
```
|
|
Hook.Patch("Barotrauma.CharacterInfo", "IncreaseSkillLevel", function(instance, ptable)
|
|
print(string.format("%s gained % xp", instance.Character.Name, ptable["increase"]))
|
|
end, Hook.HookMethodType.After)
|
|
```
|
|
|
|
### Prefix
|
|
|
|
Prefixes are functions that get called before the original method executes.
|
|
For more advanced use cases, they can also be used to modify the incoming
|
|
parameters or prevent the original method from executing.
|
|
|
|
```
|
|
Hook.Patch(
|
|
"Barotrauma.Character",
|
|
"CanInteractWith",
|
|
{
|
|
"Barotrauma.Item",
|
|
-- ref/out parameters are supported
|
|
"out System.Single",
|
|
"System.Boolean"
|
|
},
|
|
function(instance, ptable)
|
|
-- This prevents the original method from executing, so we're
|
|
-- effectively replacing the method entirely.
|
|
ptable.PreventExecution = true
|
|
-- Modify the `out System.Single` parameter
|
|
ptable["distanceToItem"] = Single(50)
|
|
-- This changes the return value to "null"
|
|
return nil
|
|
end, Hook.HookMethodType.Before)
|
|
```
|