Function Call

Quillscript can execute Blueprint/C++ functions using command lines.

Supposing you want to run a function with the following signature.

UFUNCTION()
void MyFunction(int32 Num, bool Flag);

Must be a UFunction

By default, you can pass only primary type parameters: Boolean (bool), Byte (uint8), Integer (int32), Integer64 (int64), Float (float/double), String (FString), Name (FName), Text (FText) and Enumerators (UEnum).

Although not a recommended practice, you can pass Null Pointers (nullptr), typing any string for that parameter. To pass a pointer to a valid reference, check Script References.

Built-in

If the above function belongs to the Interpreter, including custom interpreters, you call it by typing its name and passing the parameters separated by spaces.

$ MyFunction 10 true

Named Object

You can execute functions that belong to an instanced object by referencing its name or display name given in editor. For example, if an object is named 'MyActor', start the function with an & (ampersand) followed by the object name, and place a dot between the object name and the function name.

$ &MyActor.MyFunction 10 true

Additionally, if you do not want to use the display name given in editor, Quillscript also provides a Rename Object function to easily set a name for an object.

#include "Utils/Tools.h"
...

UTools::RenameObject(MyObject, "RefName");

Avoid using whitespaces and special characters in object names for safety.

Shortcuts

You can use these names to reference common Unreal Engine objects.

Script References

In addition, you can create a list of object references to use in scripts. To add an object to the list, use the method below:

#include "Utils/Quill.h"
...

UQuill::AddScriptReference(WorldContextObject, "MyRef", Reference);

And it becomes available in script, by name.

$ &MyRef.MyFunction 10 true

These objects can also be passed as parameter variables to other functions if they match parameter type. A null pointer is passed otherwise.

$ MyOtherFunction {&MyRef}

Although the interpreter tries to check if the parameter type and the referenced object type are different, you should avoid passing an object with a different type, this can result in a crash.

Object references are also be captured when they are sent as return value of a function. For example, the function with the following signature:

UFUNCTION()
AActor* ObjectOutputFunction(UObject*& MyOutputObject);

Must be a UFunction

An object reference for the output parameter is added and becomes immediately available in script.

$ &ReturnValue.MyFunction 10 true
$ &MyOutputObject.MyFunction 10 true

Script Reference By Path

It's very common to pass an Unreal Engine asset as a parameter to a function. To avoid the need to create a named script reference for every asset required, script references can use the Unreal Engine path pattern to pass asset references without the need to previously name it.

$ Background {&/Game/FolderName/AssetName.AssetName}

The same method can be applied to pass class references:

// Blueprint classes.
$ MyFunction {&/Game/FolderName/MyBlueprint.MyBlueprint_C}

// C++ classes.
$ MyFunction {&Engine.Actor}

Script assets will also reference these assets in the Reference Viewer.

Script Reference Search Paths

Also, often your assets are all in the same folder. For such cases, you can add that folder to a list of "Search Paths", either project-wide on plugin settings, or per script on the script asset itself. An asset in this specified folder does not need to be referenced by its entire path, but just by its name.

For example, suppose we have a folder named "Backgrounds" on the content browser. Inside this folder are 3 texture assets named "Classroom", "Street", and "Shop". You add this folder to your project search paths and reference these assets by name, without the need to create a script reference manually.

Search Path: /Game/Backgrounds/

 $ Background {&Classroom}
 $ Background {&Street}
 $ Background {&Shop}

Object, Actors, Widgets or Function Library of Class

You can execute functions in all objects of a given class. For example, if an object has the class "MyClass", start the function with an ^ (Circumflex) and the class name.

Start with the blueprint reference path, without the extension at the end:

$ ^Path/To/My/Blueprint/MyClass.MyFunction 10 true

Example

$ ^Game/MyBlueprint.MyFunction 10 true

Start with the module name and the class name.

$ ^MyModule.MyClass.MyFunction 10 true

Example

^Engine.Actor.MyFunction 10 true

Tagged Actors

You can execute functions that belong to instanced Actors using their tags. For example, if an Actor has the tag 'MyTag', start the function with a % (Percent Sign) and the tag name.

This method will execute the function in all actors with the specified tag.

$ %MyTag.MyFunction 10 true

Calling Nested Objects

You can also call functions from nested objects. For example:

$ MyParentObject.ChildObject1.ChildObject2.MyFunction 10 true

You cannot call functions from objects in arrays, sets, maps, and nested structs.

Return Values and Outer Parameters

Functions

You can capture the return values of a called function and store it in a Quillscript variable.

Suppose you want to capture the return value of the following function.

UFUNCTION()
bool MyFunction(int32& IntParam, FString& StringParam);

Must be a UFunction

When this function is called by one of the methods above, the return values are stored in Quillscript Outer Variables, a particular type of temporary variable that exists during that script execution.

These variables are named like the return value and outer parameters. The following variables are created in the example above: $ReturnValue, $IntParam, and $StringParam

Example

$ double = {$IntParam} * 2

- Alice | ? {$ReturnValue} == on
  {$StringParam}

Properties

You can capture the value of an UObject property.

Suppose you want to capture the return value of the following properties.

UPROPERTY()
int32 MyNumber;

UPROPERTY()
FString MyString;

Must be a UProperty

Call the variable by its path and use the property name as an outer variable.

$ MyParentObject.MyNumber

- Bob | ? {$MyNumber} > 5
  Hello!

And you can do the same for nested objects:

$ MyParentObject.ChildObject1.ChildObject2.MyString

- Alice
  {$MyString}

You cannot access properties from objects in arrays, sets, maps, and nested structs

Localizing Parameters' Text

Although being stored as an Unreal Engin's Text type, Quillscript's Text parameters are marked as cultural invariants by default. If the value of a parameter must be localized, set its value inside `` (backticks)

// void MyFunction(FString Param1, FString Param2)
$ MyFunction `This param value should be localized` 'This param should not'

Named Parameters

Is a versatile feature that allows users to call functions with parameters passed in any order. This is achieved by explicitly naming the parameters using the @ParamName:ParamValue syntax. This approach enhances code readability and flexibility, making it easier to understand and edit. At the same time, it also lets the writer pass only the desired parameters in the desired order and omits unnecessary ones.

Consider the following function:

UFUNCTION()
void MyFunction(int32 IntParam, FString StringParam, bool bBooleanParam);

Must be a UFunction

In a Quillscript file, you can call this function like this.

// Same order, but named for better readability.
$ MyFunction @IntParam:10 @StringParam:String @bBooleanParam:true

// Parameters are passed in the writer's desired order.
$ MyFunction @bBooleanParam:true @StringParam:String @IntParam:10

// The intended param is passed, and others are omitted (default value).
$ MyFunction @StringParam:String

PreviousQuillscript Variables NextBuilt-In Functions

Last updated 3 months ago