~ Directive

Automation and pre-processing tasks

Directives are tasks that can execute either during runtime or before a Script starts. They are intended for automation and do pre-processing tasks.

• A Directive statement starts with a ~ (Tilde), immediately followed by a space and the directive name.

---

Start

Defines a different starting point for this script.

By default, Quillscript scripts start at the beginning of the text file. With this directive, you can set a custom starting point.

Source

- Hank
  Jump this.

// This script actually starts here.
~ start

- Hank
  This is the first dialogue.

If you have the Keep Script History setting enabled in Quillscript Settings, you can add an index to multiple usages of the Start Directive. The Interpreter will start the script at index 1 the first time this script is played, at index 2 on the second play, and so on.

Source

~ start 1
- Matthew
  Hello, I'm Matthew.

~ start 2
- Matthew
  Can I help you?

---

Define

Replaces all occurrences of a pre-defined string during parsing time.

Source

~ define header Bob | ? {height} < 1.8

$ height = 1.5

- [header]
  Hello.
- [header]
  I'm short.

It is also possible to add parameters to the Define directive separated from the definition name with a : (colon). Any occurrence of those parameters will be replaced by their equivalent in the directive usage.

Source

~ define path:name "{&/Game/Assets/Characters/name.name}"

$ Sprite Alice
$ &Alice.Show [path:Alice_Idle]
// Replaced with {&/Game/Assets/Characters/Alice_Idle.Alice_Idle}

Or multiple parameters separated by ; (semi-colon)

Source

~ define path:folder;name "{&/Game/Assets/Characters/folder/name.name}"

$ Sprite Bob
$ &Bob.Show [path:Bob;Idle]
// Replaced with {&/Game/Assets/Characters/Bob/Idle.Idle}

---

Replace

Replaces all occurrences of a pre-defined parameter, before the script starts.

Source

~ replace name Bob
~ replace condition {height} < 1.5

$ height = 1.5

- [name] | ? [condition]
  Hello.

- [name] | ? [condition]
  I'm short.

---

Include

Inserts the data of a given Quillscript Script asset, at this point, either by id or by path.

To include a Script by id, use the script id starting with a @.

~ include @MyScriptId

To include a Script by path, use the script path, simple or complete.

~ include /Game/MyScript.MyScript
~ include /Script/Quillscript.QuillscriptAsset'/Game/MyScript.MyScript'

Source

~ include @MyScriptId

// Insert the content of "MyScript" again, at this position.
~ include @MyScriptId

Be aware not to cyclically include one script into another creating an infinite loop.

---

Import

Inserts the data of a given Quillscript Script asset, at the start of this script, only once, either by id or by path.

To import a Script by id, use the script id starting with a @.

~ import @MyScriptId

To include a Script by path, use the script path, simple or complete.

~ import /Game/MyScript.MyScript
~ import /Script/Quillscript.QuillscriptAsset'/Game/MyScript.MyScript'

Source

~ import @MyScriptId

// This one is ignored because this script was imported before.
~ import @MyScriptId

Be aware not to cyclically include one script into another creating an infinite loop.

---

Inject

Inserts the content of a given label from an external script, at this point, either by id or by path.

To inject a label content by id, use the script id starting with a @.

~ inject @MyScriptId MyLabelName

To include a label content by path, use the script path, simple or complete.

~ inject /Game/MyScript.MyScript MyLabelName
~ inject /Script/Quillscript.QuillscriptAsset'/Game/MyScript.MyScript' MyLabelName

Source

~ inject @MyScriptId MyLabelName

// Insert the content of "MyLabelName" again, at this position.
~ inject @MyScriptId MyLabelName

Be aware not to cyclically include one script or label into another creating an infinite loop.

---

Checkpoint

This directive halts the execution of the script until a specified condition is met. The Interpreter remains in a waiting state and does not proceed to the next line of code until the condition evaluates to true. The condition is an expression that can be evaluated.

~ checkpoint | ? {myVar} < 10 OR {flat} == on

It accepts a number parameter to set the delay in seconds between condition checks, this help to improve performance, it check every 0.1 seconds otherwise.

~ checkpoint 0.5 | ? {myVar} + 3 < 10 AND {flat} == on

It is also possible to concatenate Command statements to execute before each conditions check.

~ checkpoint 0.5 | &Obj.CheckMyCondition | ? {$ReturnValue} == on

---