You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The code executed by a hook is defined in functions within the Hook Blueprint.
103
-
The "Hook Implementation" option on hook nodes determines what function is invoked a hook node.
111
+
The "Hook Implementation" option on hook nodes determines what function is invoked by a hook node.
112
+
113
+
[id="HookImplementation_Parameters"]
114
+
=== Parameters
104
115
105
-
=== Hook Function Parameters
116
+
The parameters on the hook implementation function are populated by the hooking system
117
+
based on the target function's parameters, target class, and type of hook.
106
118
107
-
Hook functions parameters are populated by the hooking system based on
108
-
the target function's parameters, target class, and type of hook.
119
+
Parameters can be any variable that is available in the hooked function's context that the hook might want to read/write.
120
+
A wider type can be used unless the parameter is set to Pass-by-Reference (By Ref).
121
+
For example, a real value float could be converted to a double parameter,
122
+
or a real value of a specific object type could be converted to a general "Object" parameter.
109
123
110
-
The first parameter should be named `Target` and be of the type of Blueprint you are hooking.
111
-
Subsequent parameters can be any variable that is available in the hooked function's context that the hook might want to read/write.
112
-
If set to be By Ref, the type must exactly match, but otherwise a wider type can be used.
124
+
If a parameter is passed By Ref, the type must exactly match, and no automatic type conversion is ever performed.
125
+
By Ref parameters can be modified to change the mapped variable's value in the hooked function.
113
126
114
-
Parameters will be mapped using their name to:
127
+
Parameters are mapped to function variables by naming the parameter exactly the same thing as the variable.
115
128
116
-
* `Target` - special hooking argument that resolves to the object instance the hooked function was running on
117
-
* Global Variables - on the object instance
129
+
* Global Variables - on the object instance (the `Target`, see below)
118
130
* Local Variables - function inputs, function locals, and function temps (which you can check for in a BP code dump, either via the link:#ViewingBlueprintFunctionImplementations[`-DumpBlueprintPatchingResults` launch argument] which generates pseudocode, or in xref:Development/ExtractGameFiles.adoc#FModel[FModel] which generates a json very similar to the asset dump)
119
-
* `TargetReturnValue` - special hooking argument that resolves to the hooked function's ReturnValue
120
-
* `HookTarget` - special hooking argument for insertion hooks. Resolves to the expression the hook was pointing to, if it wasn't pointing to a statement
121
-
* `AssignmentTarget` - special hooking argument for insertion hooks on assignment statements. Resolves to the variable on the left side of an assignment statement.
122
-
* `OriginalValue` - special hooking argument that resolves to the original value when using redirect hooks (replacing an expression inside a statement, rather than an insert hook which goes before/replace/after a statement). Required when using a redirect hook.
131
+
132
+
In addition, the following special hooking arguments are available:
133
+
134
+
* `Target` - resolves to the object instance the hooked function was running on.
135
+
* `TargetReturnValue` - resolves to the hooked function's ReturnValue.
136
+
* `HookTarget` - only for insertion hooks. Resolves to the expression the hook was pointing to, if it wasn't pointing to a statement.
137
+
* `AssignmentTarget` - only for insertion hooks on assignment statements. Resolves to the variable on the left side of an assignment statement.
138
+
* `OriginalValue` - required for redirect hooks. Resolves to the original value (replacing an expression inside a statement, rather than an insert hook which goes before/replace/after a statement).
139
+
140
+
All parameters are optional, except `OriginalValue` for redirect hooks.
Insertion hooks can optionally return a boolean named `ReturnValue`
148
+
to control whether the hooked function should continue execution (`True`)
149
+
or jump to the return statement, effectively canceling the function and skipping any other hooks on the statement (`False`).
150
+
If this is not present, execution will continue by default.
151
+
152
+
Redirect hooks must return a value of the same type as the statement being replaced.
153
+
126
154
[id="Register"]
127
155
== Registering the Hook
128
156
@@ -146,13 +174,15 @@ You can modify the arguments the hooked function receives by using a Before Hook
146
174
Add the parameter you want to modify as a By-Ref parameter on your hook function.
147
175
The initial value can be accessed via the parameter and modified by a Set By Ref node.
148
176
149
-
// === Cancel Hooked Function Execution
177
+
=== Cancel Hooked Function Execution
178
+
179
+
Insertion hooks can conditionally cancel further execution of the function they are hooking.
180
+
Be careful exactly which statement you are hooking, as you don't want to accidentally run more of the target function's code than you intended.
150
181
151
-
// TODO, see https://discord.com/channels/555424930502541343/562722670974599227/1451402917624942612
182
+
To cancel execution, the hook implementation function should return a boolean `ReturnValue` of `False`.
152
183
153
-
// You can (conditionally) cancel the execution of a function using a Replace hook.
154
-
// By default, Replace hooks do not execute their original target, .
155
-
// When relevant, Replace hooks will still execute their original target if the Hook Implementation returns `True` for a boolean output parameter named `ReturnValue`.
184
+
If you intend to cancel execution just based off of input parameters,
185
+
use a Before hook on the Function Entry Statement expression.
0 commit comments