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, editor's name or display name. 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, 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.

Although using the ~~object's editor's name~~ does work on the Play-in-Editor, and development and debug builds, it won't work on distribution builds (shipping). Therefore, using the object's editor's name should be avoided and used only for quick testing and prototyping. Use the object name or display name instead.

Shortcuts

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

&GameInstance

Game Instance Object

&PlayerController

Player Controller Actor

&GameMode

Game Mode Object

&Pawn

Player Pawn Actor

&Character

Player Character Actor

&GameState

Game State Object

&PlayerState

Player State Object

&PlayerCameraManager

Player Camera Manager Actor

&Interpreter or &this

This script interpreter Actor

&Target

Script target object (Passed in the Play Script node)

&Script

Script object

&DialogBox

Dialog Box Widget

&SelectionBox

Selection Box Widget

&BackgroundBox

Background Box Widget

&Level

Current Level Script Actor

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

$ &MyParentObject.MyFunction

$ 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

It's also possible to retrieve an element from some container types using the :: separator.

From Arrays or Sets using the element index number:

$ MyParentObject.MyArray

- Bob
  {$MyArray::0}

Currently, only the following types are supported: Boolean (bool), Byte (uint8), Integer (int32), Integer64 (int64), Float (float/double), String (FString) and Name (FName).

From Maps using the element key:

$ MyParentObject.MyMap

- Bob
  {$MyMap::key}

Localizing Parameters' Text

Although being stored as an Unreal Engine's Text type, Quillscript's Text are culture-invariant by default. If the value of a parameter must be localized, set its value inside `` (backticks) and it will be changed to culture-correct.

// 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 18 days ago