Building: Traps and Events
Event traps are used by the mud to respond to special events that can happen, such as opening a door, pressing
a button or many other more complicated things.
Note: Always check with one or more senior officers before adding new events.
e.g.
... lots of events
Note: Always check with one or more senior officers before adding new events.
How to add a new trap
Add a new line at the bottom of yourmusicmud/data/eventse.g.
... lots of events
before_myevent(pl, o1, o2, extra: string) -> 0 | 1 after_myevent(pl, o1, o2, extra: string) -> 0 | 1Types are not required on the 'standard' parameters: pl, o1, o2, o3 or txt. If you wish to use custom parameters these should have a type. The return type should be specified. Types are specified in a format a little bit like TypeScript, with core types
int,
string and mudobject, objset, as well as nil,
bool, and number literals.
Event can be 'const', which means their handlers are not allowed to mutate the MUD in any way,
and can only return a result. This is specified between the parameters and the return type,
for example
get_short(pl, o1) -> string
notes: Before you use your new event, you must make it available:
cd to yourmusicmud/musicmud/src/ and type make. This is before you try
and add a dispatch_lua_event() call in any source code, in case dependencies are not set up.
Use of 'dotrap' in source code
Find the part of source code you wish to trap/trigger an event for. Asuming its a before_ style event, insert a line like the following example just before the normal flow of events:
if (dispatch_lua_event(E_BEFOREMYEVENT, pl, o1 [,o2, o3, txt]))
return 0;
... the normal flow of events is here
For an after_ style event, then do the following:
... normal flor of events is finished
dispatch_lua_event(E_AFTERMYEVENT, pl, o1 [,o2, o3, txt])
notes: pl is the player causing the event (though it may be a mobile, or other object), o1 is 'this object' i.e. the actual object the trap is being triggered by. o2. o3 and txt are optional extras that you may need in order to pass extra information to your trap; o2 and o3 are normally object IDs and txt is a string.
You get the E_WHATEVER name by taking your event name, removing any underscores, and putting it all in capitals.
e.g.
for an event before_smashed, it would be E_BEFORESMASHED
Use of 'dotrap' in lua verbs
lua verbs are in yourmusicmud/data/verbs/ each one is a separate file named after the verb.
There is a lua funtion called, trap.exec that you can call.
Documentation
The first time the trap is used in any source file, add a comment line after it like the following:
if (dispatch_lua_event(E_BEFOREMYEVENT, , [,o2, o3, txt]))
/* ::: before_myevent o1==object that will be smashed, o2=whatever o2 is; return 1 to abort smashing */
return 0;
Then next time the web docuemntation is rebuilt, yours will be added.
If it is first (or only ever) used in a lua verb, its slightly different:
--lua
-- /* ::: before_myevent o1==object that will be smashed, o2=whatever o2 is; return 1 to abort smashing */
to update the webdocs
cd yourmusicmud/doc/src
./mkdocs.pl
If you have any problems, then search around the current source files for other occurances of ':::' and 'dotrap' and see if someone else has already done something similar to what you want.