Quill

Quillscript Function Library

The Quillscript Function Library is a dedicated collection of utility functions designed to enhance the functionality and ease of use of the Quillscript Plugin in Unreal Engine.

This library offers a set of specialized tools and features for Quillscript Plugin users, enabling efficient coding, automation, and customization within your Quillscript-powered projects.

Script

Play Script

Initiate the execution of a Quillscript asset.

Parameters

WorldContextObject: ref
Script: ref[QuillscriptAsset]
(Omittable) StartingLabel: Name
(Omittable) Target: ref            // Object referenced by this Script as {&Target}

// Get a script reference.
$ ^Quillscript.Quill.GetScriptById MyScriptId

// Play script.
$ ^Quillscript.Quill.PlayScript {&ReturnValue}

// End current script. (Optional)
$ End

Notice that this process produces the same result as the $ Travel built-in function and is useful only if you need extra control of the code behavior or order.

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

UQuill::PlayScript(WorldContextObject, UQuill::GetScriptById("MyScriptId"));

Play Script Using Custom Settings

Play the given script using a custom set of settings passed as a parameter to this function. It allows you to fine-tune the behavior of the script execution according to your specific requirements.

Parameters

WorldContextObject: ref
Script: ref[QuillscriptAsset]
Settings: ScriptSettings
(Omittable) StartingLabel: Name
(Omittable) Target: ref            // Object referenced by this Script as {&Target}

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

// Configure custom settings.
FScriptSettings Settings;
Settings.EnableInputDuring = EPicker::No;
Settings.ShowMouseCursorAfter = EPicker::Yes;

// Play script using custom settings.
UQuill::PlayScriptUsingCustomSettings(
    WorldContextObject,
    UQuill::GetScriptById("MyScriptId"),
    Settings
);

Start Script

Same as Play Script but clears any previous script history to ensure a fresh start.

Parameters

WorldContextObject: ref
Script: ref[QuillscriptAsset]
(Omittable) StartingLabel: Name
(Omittable) Target: ref            // Object referenced by this Script as {&Target}

// Get a script reference.
$ ^Quillscript.Quill.GetScriptById MyScriptId

// Start script.
$ ^Quillscript.Quill.StartScript {&ReturnValue}

// End current script. (Optional)
$ End

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

UQuill::StartScript(WorldContextObject, UQuill::GetScriptById("MyScriptId"));

Start Script Using Custom Settings

Same as Play Script Using Custom Settings but clears any previous script history to ensure a fresh start.

Parameters

WorldContextObject: ref
Script: ref[QuillscriptAsset]
Settings: ScriptSettings
(Omittable) StartingLabel: Name
(Omittable) Target: ref            // Object referenced by this Script as {&Target}

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

// Configure custom settings.
FScriptSettings Settings;
Settings.EnableInputDuring = EPicker::No;
Settings.ShowMouseCursorAfter = EPicker::Yes;

// Start script using custom settings.
UQuill::StartScriptUsingCustomSettings(
    WorldContextObject,
    UQuill::GetScriptById("MyScriptId"),
    Settings
);

Resume Script

Continue the execution of a Quillscript from the last saved state entry in the script's history. It enables you to pick up the script where it left off, making it useful for scenarios where you need to maintain script continuity or when the game was saved during a script play and need to continue from that point.

Parameters

WorldContextObject: ref
Script: ref[QuillscriptAsset]

// Get a script reference.
$ ^Quillscript.Quill.GetScriptById MyScriptId

// Play script.
$ ^Quillscript.Quill.ResumeScript {&ReturnValue}

// End current script. (Optional)
$ End

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

UQuill::ResumeScript(WorldContextObject, UQuill::GetScriptById("MyScriptId"));

Parse Script

Takes a Quillscript language valid string as input and converts it into a Quillscript asset. This is particularly useful when you need to dynamically create or modify scripts at runtime, or when you allow modders or user to create their own scripts.

You can also specify a permission mode to control the script's behavior. See Permissions for more details.

Parameters

Text: string
(Omittable) Permission: PermissionMode        [ All, Safe, Sandbox ]

// Get a valid Quillscript language string.
$ :QuillscriptLanguageValidString := '$ x = 1'

// Create script object reference.
$ ^Quillscript.Quill.ParseScript {:QuillscriptLanguageValidString}

// Play created script.
$ ^Quillscript.Quill.PlayScript {&ReturnValue}

// End current script. (Optional)
$ End

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

const TObjectPtr<UQuillscriptAsset> Script{ UQuill::ParseScript(QuillscriptLanguageValidString, EPermissionMode::Sandbox) };
UQuill::PlayScript(WorldContextObject, Script);

Get Scripts

Retrieves a list of all available Quillscript script assets within your project. This can be useful when you need to access and manage multiple scripts programmatically.

$ ^Quillscript.Quill.GetScripts

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

TArray<UQuillscriptAsset*> Scripts{ UQuill::GetScripts() };

for (auto Script : Scripts)
{
    // Implementation.
}

Get Script by Path

Retrieve a specific Quillscript asset by providing its path within your project. This function simplifies script asset retrieval, making it easy to access the script you need for execution or manipulation.

Parameters

Path: string

// Get a script reference.
$ ^Quillscript.Quill.GetScriptByPath /Game/Path/To/MyScript.MyScript

// Play script.
$ ^Quillscript.Quill.PlayScript {&ReturnValue}

// End current script. (Optional)
$ End

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

const TObjectPtr<UQuillscriptAsset> Script{ UQuill::GetScriptByPath("/Game/Path/To/MyScript.MyScript") };
UQuill::PlayScript(WorldContextObject, Script);

Get Script by Id

Retrieve a Quillscript asset by its unique identifier (Id). Keep in mind that this function may have performance implications in projects with a large number of assets. Use it when you need to specifically locate a script by its Id.

Parameters

Id: name

// Get a script reference.
$ ^Quillscript.Quill.GetScriptById MyScriptId

// Play script.
$ ^Quillscript.Quill.PlayScript {&ReturnValue}

// End current script. (Optional)
$ End

#include "Utils/Quill.h"
...
const TObjectPtr<UQuillscriptAsset> Script{ UQuill::GetScriptById("MyScriptId") };
UQuill::PlayScript(WorldContextObject, Script);

Is Script Playing

Checks whether a specified Quillscript script is currently playing.

Parameters

WorldContextObject: ref
Script: ref[QuillscriptAsset]

$ ^Quillscript.Quill.GetScriptById MyScriptId
$ ^Quillscript.Quill.IsScriptPlaying {&ReturnValue}

if: {$ReturnValue} == on

    // Do something

endif

#include "Utils/Quill.h"
...
const TObjectPtr<UQuillscriptAsset> Script{ UQuill::GetScriptById("MyScriptId") };

if (UQuill::IsScriptPlaying(WorldContextObject, Script))
{
    // Implementation
}

Is Any Script Playing

Checks whether any Quillscript script is currently playing.

Parameters

WorldContextObject: ref

$ ^Quillscript.Quill.IsAnyScriptPlaying

if: {$ReturnValue} == on

    // Do something

endif

#include "Utils/Quill.h"
...
if (UQuill::IsAnyScriptPlaying(WorldContextObject))
{
    // Implementation
}

Make Permissions List

Generates a list of script permissions based on the specified permission mode. This function is helpful when you need to create a list of permissions for your scripts programmatically, allowing you to control the behavior of the scripts according to your permission requirements.

See Permissions for more details.

Parameters

PermissionMode: PermissionMode                [ All, Safe, Sandbox ]

// Get a script reference.
$ ^Quillscript.Quill.MakePermissionsList Sandbox

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

TArray<EPermission> Permissions{ UQuill::MakePermissionsList(EPermissionMode::Sandbox) };

Interpreter

Create Interpreter

Spawn an interpreter actor. It is recommended to use this method instead of manually spawning an interpreter actor.

Parameters

WorldContextObject: ref
(Omittable) InterpreterClass: SubclassOf[QuillscriptInterpreter]

$ ^Quillscript.Quill.CreateInterpreter

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

const TSubclassOf<AQuillscriptInterpreter> InterpreterClass{ LoadClass<AQuillscriptInterpreter>(nullptr, TEXT("/Game/Path/To/MyInterpreter.MyInterpreter_C")) };
const TObjectPtr<AQuillscriptInterpreter> Interpreter{ UQuill::CreateInterpreter(WorldContextObject, InterpreterClass) };

Get Interpreters

Retrieve all instantiated interpreter objects in the specified world context.

Parameters

WorldContextObject: ref

$ ^Quillscript.Quill.GetInterpreters

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

TArray<AQuillscriptInterpreter*> Interpreters{ UQuill::StartScript(WorldContextObject) };

for (auto Interpreter : Interpreters)
{
    // Implementation.
}

Variables

Quillscript Variable Exists

Check the existence of a Quillscript variable with a specified name. This function is particularly useful when you need to determine whether a specific variable is defined.

Parameters

WorldContextObject: ref
VariableName: name

// Store result in {$ReturnValue}.
$ ^Quillscript.Quill.QuillscriptVariableExists VariableName

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

if (UQuill::QuillscriptVariableExists(WorldContextObject, FName("VariableName")))
{
    // Implementation.
}

Get Quillscript Variable

Retrieves the value of a Quillscript variable with the specified name. If the variable does not exist, it returns "off" as a default value.

Parameters

WorldContextObject: ref
VariableName: name

// Store result in {$ReturnValue}.
$ ^Quillscript.Quill.GetQuillscriptVariable VariableName

Notice that this produces the same result as using the variable directly like $ x = {VariableName}

But this is useful to get a variable using a dynamic name.

$ ^Quillscript.Quill.GetQuillscriptVariable {dynamicName}

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

// Macro (Only inside an UObject method)
FString VariableValue{ VAR("VariableName") };

// Function call.
FString VariableValue{ UQuill::GetQuillscriptVariable(WorldContextObject, FName("VariableName")) };

Register Variable Modifier

When a Quillscript variable value is requested, the delegate event is played before retrieving the value, allowing the code to modify the variable value beforehand or to play some required code.

Parameters

VariableName: name
Delegate: event

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

FVariableGetDelegate OnVariableGet;
OnVariableGet.BindDynamic(MyObject, &UMyObject::MyFunction);

UQuill::RegisterVariableModifier(this, "HasCheckpointFinished", OnVariableGet);

void UMyObject::MyFunction(const FName& VariableName, const FString& VariableValue)
{
    // Implementation.
}

Unregister Variable Modifier

Unregister a variable modifier.

Parameters

VariableName: name

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

UQuill::UnregisterVariableModifier(this, "HasCheckpointFinished");

Save and Load

Save Game and Story to Slot

This function behaves the same as the native SaveGameToSlot, but additionally injects Quillscript data to the save game file.

Saves game data and Quillscript data to a specified save slot. The function returns true if the save operation is successful, and false otherwise.

Parameters

WorldContextObject: ref
SaveGameObject: ref[SaveGame]
SlotName: string
UserIndex: number

// Save game and Quillscript data to 'MySlot'.
$ ^Quillscript.Quill.SaveGameAndStoryToSlot {&SaveGame} "MySlot" 0

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

TObjectPtr<UMySaveGame> SaveGame{ Cast<UMySaveGame>(UGameplayStatics::CreateSaveGameObject(UMySaveGame::StaticClass())) };
UQuill::SaveGameAndStoryToSlot(WorldContextObjet, SaveGame, "MySlot", 0);

Load Game and Story from Slot

This function behaves the same as the native LoadGameFromSlot, but additionally extracts Quillscript data from the save game file and update Quillscript subsystem with the extracted data.

Returns a Save Game object containing the loaded data.

Parameters

WorldContextObject: ref
SlotName: string
UserIndex: number

// Load game and Quillscript data from 'MySlot'.
$ ^Quillscript.Quill.LoadGameAndStoryFromSlot "MySlot" 0

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

UQuill::LoadGameAndStoryFromSlot(WorldContextObjet, "MySlot", 0);

PreviousLibraries NextTools

Last updated 4 months ago