Utilities

Placeholders

Placeholders allow unknown variables to be stored in YML files, to be filled in at runtime. This is typically used for player names within NPC text.

Drustcraft has the following placeholders builtin for use:

Placeholder

Description

$PLAYER.NAME$

Players name

If a placeholder is not supported within the context, it is replaced with empty characters.

Scripts can use the placeholder system on their own text by using the procedure:

<proc[drustcraftp.placeholder].context[<[my_text]>]>

If a script as additional one-off placeholders that need to be applied to a piece of text, then the script can pass a second definition to the drustcraftp.placeholder procedure which contains a map of placeholder-code:value.

For example, if I want to apply the built-in placeholder values to the text within the definition mytext and also replace the placeholder $CAT$ with Neko, I can use the procedure as:

- define 'mytext:Howdy $PLAYER.NAME$! Do you like my cat $CAT$?'
- define mymap:<map[CAT/Neko]>
- narrate <proc[drustcraftp.placeholder].context[<[mytext]>|<[mymap]>]>

Scripts can also register their own placeholders to be used by any script that supports the placeholder system by using the task:

- run drustcraft.placeholder.register def:<placeholder-code>|<callback>

An example of registering a simple placeholder of $SECRETCODE$ which when parsed, is replaced with the world cat:

myexample_world:
type: world
events:
- on drustcraft load:
- run drustcraft.placeholder.register def:SECRETCODE|myexample_task
myexample_task:
type: task
script:
- define placeholder_code:<[1]||<empty>>
- if <[placeholder_code]> == SECRETCODE:
- determine cat
- determine <empty>

Timers

Drustcraft supports callback timers that are used by various modules within the Drustcraft system.

To create a callback timer, run the task:

- run drustcraft.timer.add def:<seconds>|<callback>|<data>

The task does return a timer callback ID which can be used to remove the timer at a later date. This can be done by running the task:

- run drustcraft.timer.remove def:<id>

There is no guarantee that your timer will run at the exact time specified by the seconds value, but the Drustcraft engine will try it best to accomodate the request.

Once the callback is run, it is required from the timer queue.