Script Messager
The script messager is a lightweight object designed to allow separate script systems to send and listen for string messages. It is very much like a cut-down event system, without the congestion of events that are naturally triggered by the game. Its main purpose is to underpin the mechanics of both the generated_battle system in battle and the narrative system in campaign.
Unlike the events system, the script messager supports the blocking of messages, so that one bit of script can prevent the transmission of a specific message by any other bit of script.
It is rare to need to get a handle to a script messager object directly, as the generated_battle system stores an internal reference to it and calls it automatically when necessary.
| Loaded in Campaign |
|
| Loaded in Battle |
|
| Loaded in Frontend |
|
-
script_messager:new() -
Gets or creates a
script_messagerobject.Returns:
defined in ../../warhammer/working_data/script/_lib/lib_script_messager.lua, line 54
Once an script_messager object has been created with script_messager:new, functions on it may be called in the form showed below.
Example - Specification:
<script_messager_object>:<function_name>(<args>)
Example - Creation and Usage:
local sm = script_messager:new() -- set up automatically by campaign or battle managers
sm:add_listener( -- calling a function on the object once created
"test_message",
function() out("* test_message received") end
)
-
script_messager:add_listener(message
string,callback to call
function,persistent
[boolean],condition
[function],listener name
[string]
) -
Adds a listener for a message. If the specified message is received, the specified callback is called. If the third parameter is set to
truethen the listener will continue after it calls the callback and will listen indefinitely.Parameters:
1
Message to listen for.
2
Target to call when the message is received and the optional condition passes.
3
optional, default value=false
Continue to listen after the target callback has been called.
4
optional, default value=nil
Condition function which must pass for the target callback to be called. The condition function is called when the message is received, and will be passed the message context as a single argument. It must return true, or a value that equates to true in a boolean comparison, for the condition to pass. If no condition function is supplied then the condition always passes.
5
optional, default value=nil
Name for this listener, by which it may be later cancelled.
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_script_messager.lua, line 122
-
script_messager:trigger_message(message namestring, [context datatable]) -
Triggers a string message. This prompts the messager system to notify any listeners for the subject message and call the callback that those listeners registered. An optional table of context data can be supplied to be passed through to the listening scripts.
Parameters:
1
message name
2
optional, default value=nil
context data
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_script_messager.lua, line 170
-
script_messager:remove_listener_by_message(stringmessage name) -
Removes any listener listening for a particular message.
Parameters:
1
stringmessage name
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_script_messager.lua, line 231
-
script_messager:remove_listener_by_name(stringmessage name) -
Removes any listener by name.
Parameters:
1
stringmessage name
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_script_messager.lua, line 244
-
script_messager:block_message(stringmessage name, [booleanshould block]) -
Blocks or unblocks a message from being transmitted in the future. If a message is blocked, no listeners will be notified when
script_messager:trigger_messageis called.Parameters:
1
stringmessage name
2
booleanoptional, default value=true
should block
Returns:
nil
defined in ../../warhammer/working_data/script/_lib/lib_script_messager.lua, line 263