Skip to content

About

Official Arcweave plugin for Unreal Engine. Bring branching dialogue and story logic into your game.

Topics

Resources

Contributing

Stars

8 stars

Watchers

3 watching

Forks

Latest commit

 

History

127 Commits

Folders and files

Repository files navigation

Arcweave Plugin for Unreal Engine

Version Unreal Engine Language License GitHub Issues Discord YouTube

IMAGE ALT TEXT HERE

This is the official README file for the Arcweave plugin repository, which facilitates the import of Arcweave projects into Unreal Engine (version 5.0 and later). The plugin can import data from an exported Arcweave JSON file (available to all Arcweave users) or it can directly utilize Arcweave's web API to fetch data, a feature available to Arcweave Team account owners. You can watch a full video tutorial series on how to install and use the plugin.

Table of Contents

Plugin Installation

To install the Arcweave Plugin for Unreal Engine, follow these steps:

  1. Download the plugin from this repository.
  2. Copy the plugin (the downloaded .zip file) into the ProjectRootDirectory/Plugins folder. If this folder does not exist please create it.
  3. Open your project.
  4. If prompted to rebuild the Arcweave plugin, click Yes.

Data Collection Methods

There are two primary methods for collecting Arcweave project data:

JSON Import:

For this method, you'll need to do the following:

  • Export your Arcweave project for Unreal Engine and unzip it.

  • Move the exported JSON file along with all required assets in the Content->ArcweaveExport directory. If this directory does not exist create it.

  • ⚠️ Make sure you set the tick to the field "Enable receive method from local JSON" inside Unreal under ProjectSettings at the tab "Arcweave Settings"

    Arcweave Settings - Enable receive method from local JSON

Web API:

This involves fetching data directly from the Arcweave Web API within Unreal Engine. You will need:

  • Your Arcweave API key and your project's hash (Refer to the Arcweave Documentation for more info on how to find these).
  • Navigate to Project Settings -> Plugins -> Arcweave. Here, you can input your APIToken and the project hash obtained in the previous step.

Important Classes and Functions

Runtime import results

Bind OnArcweaveResponseReceived to apply a successfully loaded project. Bind OnArcweaveFetchCompleted(bool bSuccess, const FString& Message) to show the API result in your own UI, including Shipping builds. Failures cover request startup, transport/timeouts, HTTP errors and invalid JSON exports. A failed import keeps the previous project; error messages do not include the response body or token.

API requests have a 20-second timeout. Starting a new API import, loading local JSON or calling CancelFetch() cancels the previous request. Cancelled requests do not emit a completion event and late responses are ignored. LoadJsonFile() returns false for invalid JSON as well as file errors.

Run Arcweave.Project.ImportFailures in Unreal Automation to verify malformed exports, failed requests, retries and cancellation.

   classDiagram
   class UArcweaveSubsystem{}

   class UArcscriptTranspilerWrapper{}
   class FarcweaveModule {}
   class FArcweaveProjectData {}
   UArcweaveSubsystem --|> UEngineSubsystem
   UArcweaveSubsystem *--> FArcweaveProjectData: provides
   UArcweaveSubsystem ..> UArcscriptTranspilerWrapper
   UArcscriptTranspilerWrapper ..> FArcweaveProjectData
   UArcweaveSubsystem ..> FarcweaveModule
   FarcweaveModule *--> UArcscriptTranspilerWrapper
Loading

The primary class that contains all the blueprint-exposed functions and data is UArcweaveSubsystem. This class is located in the file path Plugins\arcweave\Source\arcweave\Public\ArcweaveSubsystem.h. It provides a range of functions that can be utilized in both Blueprints and C++ to interact with, modify, and retrieve data.

List of Important Functions in UArcweaveSubsystem:

   classDiagram
   class UArcweaveSubsystem{
      +HandleApiCall
      +HandleSettings
      +HandleArcweaveProjectData
      +ParseDataFromJson
      +TranspileData
   }

   UArcweaveSubsystem --|> UEngineSubsystem
Loading
  1. Fetch Data from Arcweave API or local JSON

    • This function allows you to fetch data from the Arcweave API by providing the API token and project hash.
  2. Load Arcweave API Token from Settings

    • This function retrieves the Arcweave API token from the settings.
  3. Save Arcweave API Token to Settings

    • This function saves the Arcweave API token to the settings, using the provided API token and project hash.
  4. Get Arcweave Project Data

    • This function retrieves the Arcweave project data.
  5. Run Transpiler for the Element and Increase Visits Counter

    • This function runs the transpiler for a specific element and increases the visits counter for that element. It requires the object ID as an input.
  6. Run Transpiler for the Condition

    • This function runs the transpiler for a specific condition. It requires the condition ID as an input.
  7. Set Variable

    • This function lets you modify the current variable value outside the dialogue logic. From anywhere in the project. You only need to provide the variable ID.

These functions provide a comprehensive set of tools for interacting with the Arcweave API and managing project data within your Unreal Engine project.

Starting element

After a successful local or API import, FArcweaveProjectData.StartingElementId contains the exported startingElement ID. Read it from GetArcweaveProjectData() or the project data supplied by OnArcweaveResponseReceived. The value is empty when the export omits the field or sets it to null or an empty string. Each successful import replaces the previous value; a rejected import preserves the loaded project.

Importing does not execute the starting element. When the game is ready to run it, pass the ID to TranspileObject:

#include "ArcweaveSubsystem.h"
#include "Engine/Engine.h"

// Run after a successful import.
UArcweaveSubsystem* Arcweave = GEngine->GetEngineSubsystem<UArcweaveSubsystem>();
const FString StartingElementId = Arcweave->GetArcweaveProjectData().StartingElementId;
if (!StartingElementId.IsEmpty())
{
    bool bSuccess = false;
    FArcweaveElementData Element = Arcweave->TranspileObject(StartingElementId, bSuccess);
    // Use Element when bSuccess is true.
}

In Blueprints, break the ArcweaveProjectData struct, read Starting Element Id, and connect it to the transpiler node's Object Id input when nonempty. This is the project-wide starting element; it does not identify a separate entry for every board.

Run Arcweave.Project.StartingElement in Unreal Automation to verify imports, reimports, and explicit execution using the imported ID.

Scoped variables

Boolean, integer, float, and plain-string attributes can be used as Arcscript variables when both the attribute and its owning board or component have custom IDs. The attribute custom ID is the variable name, the owner custom ID is its scope, and the attribute ID remains the stable ID used by SetVariable and variable-change events.

health = 100
castle.health = 10
hero.health = 20

All global, board, and component variables are available in FArcweaveProjectData.CurrentVars. Each FArcweaveVariable stores its mutable Value separately from its project-authored DefaultValue, so reset and resetAll continue to restore project defaults after earlier interpreter calls.

All parsed attributes remain available through the owning board, component, or element's Attributes collection. Only eligible board and component attributes are added to CurrentVars and passed to Arcscript; element attributes, unsupported attribute types, and attributes without the required custom IDs are not exposed as Arcscript variables.

For local JSON imports, re-export the project from the current Arcweave version so legacy board variables are migrated to attributes. Web API imports already use the current schema.

Runtime save/load

CaptureState and RestoreState save and restore current global, board, and component variable values and project visit counts through FArcweaveRuntimeState. Store this reflected struct in your game's USaveGame; the plugin does not write save files or manage the game's narrative cursor or world state.

Import the same project content before restoring. Restore validates the entire snapshot before applying it, preserves authored defaults and metadata, and emits only OnArcweaveStateRestored, without replaying variable-change or Arcscript events. Changed project content requires a game-specific migration; it is not accepted automatically.

See the C++ runtime save/load guide for a USaveGame example, import coordination, safe resume behavior, and the Arcweave.Project.RuntimeState automation test.

Arcweave Transpiler script wrapper ArcscriptTranspilerWrapper:

   classDiagram
   class ArcweaveSubsystem{}
   class ArcscriptTranspilerWrapper{
      +RunScript()
      +HandleArcweaveDll()
   }
   ArcweaveSubsystem ..> ArcscriptTranspilerWrapper: run the code throught
Loading

Run scripts fetched from JSON or through the Web API using Arcweave DLLs from the plugin.

Plugin module ArcweaveModule:

   classDiagram
   class ArcweaveModule{
      + HandlePluginModule()
      + ProvidesHookToReachTranspiler()
   }
   ArcweaveModule ..> ArcscriptTranspilerWrapper: gets
Loading

This class provides the possibility to access the Arcweave wrapper to call the DLL functions that interpret the code inside the Arcweave app.

         FarcweaveModule* arcweaveModule = FModuleManager::GetModulePtr<FarcweaveModule>("Arcweave");
         UArcscriptTranspilerWrapper* ArcscriptWrapper = arcweaveModule->getArcscriptWrapper();

Data structs:

Wrapper structs containing a series of Blueprint-type structs needed to use the transpiler, and convert the data from and to JSON.

View Complete relationship between data structs UML Diagram

Project struct :ArcweaveProjectData

This is the struct containing the board(ref to the image below) objects, the cover, all the components, and connection present in the project

classDiagram
direction TB

note for FArcweaveProjectData "Main Data Container"
    class FArcweaveProjectData {
	    +FString Name
	    +  Boards
	    +  CurrentVars
	    +  Cover
	    +  ComponentsMap
	    +  Conditions
	    +  Connections
    }

    class FArcweaveBoardData {
	    +FString Id
	    +FString Name
	    + Elements
	    + Connections
	    + Branches
	    + Jumpers
    }

    class FArcweaveVariable {
	    +FString Id
	    +FString Name
	    +FString Type
	    +FString Value
    }

   
	<<USTRUCT>> FArcweaveProjectData
	<<USTRUCT>> FArcweaveBoardData
	<<USTRUCT>> FArcweaveVariable


    FArcweaveProjectData --> FArcweaveBoardData : contains
    FArcweaveProjectData --> FArcweaveVariable : has

Loading

Board struct :ArcweaveBoardData

ArcweaveBoard image in web app

The board is the second most important container and represent what we see in the app in the red rectangle looking at the figure

classDiagram
direction TB
    class FArcweaveBoardData {
	    +FString BoardId
	    +FString CustomId
	    +FString Name
	    +TArray~FArcweaveElementData~ Elements
	    +TArray~FArcweaveConnectionsData~ Connections
	    +TArray~FArcweaveBranchData~ Branches
	    +TArray~FArcweaveJumpersData~ Jumpers
    }

    class FArcweaveElementData {
	    +FString Id
	    +FString Title
	    +FString Content
	    +TArray~FArcweaveConnectionsData~ Outputs
	    +TArray~FString~ ComponentIds
	    +TArray~FArcweaveAttributeData~ Attributes
    }

    class FArcweaveConnectionsData {
	    +FString Id
	    +FString Label
	    +FString Sourceid
	    +FString Targetid
    }

    class FArcweaveBranchData {
	    +FString Id
	    +FArcweaveConditionData IfCondition
	    +FArcweaveConditionData ElseCondition
	    +TArray~FArcweaveConditionData~ ElseIfConditions
    }

	<<USTRUCT>> FArcweaveBoardData
	<<USTRUCT>> FArcweaveElementData
	<<USTRUCT>> FArcweaveConnectionsData
	<<USTRUCT>> FArcweaveBranchData

    FArcweaveBoardData --> FArcweaveElementData : has
    FArcweaveBoardData --> FArcweaveConnectionsData : connects via
    FArcweaveBoardData --> FArcweaveBranchData : manages
Loading

Attribute struct: ArcweaveAttributeData

ArcweaveAttributeData image in web app

Attributes are metadata containers that can be attached to Elements, Components, or defined globally in your Arcweave project. They enable flexible data organization and provide a mechanism to store custom properties with type-safe values.

classDiagram
direction TB
    class FArcweaveAttributeData {
        +FString Id
        +FString cId
        +FString Name
        +EArcweaveAttributeDataType cType
        +FArcweaveAttributeValueData Value
    }

    class FArcweaveAttributeValueData {
        +FString Data
        +TArray~FString~ ComponentIds
        +EArcweaveAttributeValueDataType Type
        +bool Plain
    }

    class EArcweaveAttributeDataType {
        <<enumeration>>
        Undefined
        Elements
        Global
        Components
        Boards
    }

    class EArcweaveAttributeValueDataType {
        <<enumeration>>
        Undefined
        String (Plain Text)
        String (Rich Text)
        Component List
        Asset List
        Boolean
        Integer
        Float
    }

    <<USTRUCT>> FArcweaveAttributeData
    <<USTRUCT>> FArcweaveAttributeValueData

    FArcweaveAttributeData --> FArcweaveAttributeValueData : contains
    FArcweaveAttributeData --> EArcweaveAttributeDataType : defines scope via
    FArcweaveAttributeValueData --> EArcweaveAttributeValueDataType : typed by
Loading

Key Properties:

  • Id: Unique identifier for the attribute
  • cId: Container ID - identifies the element, component, or project it belongs to
  • Name: Human-readable name of the attribute
  • cType: Defines the scope of the attribute (Elements, Global, Components, or Boards)
  • Value: Contains the actual data and type information

Attribute Value Properties:

  • Data: The actual value stored as a string
  • ComponentIds: Array of component IDs if the attribute references components
  • Type: The data type of the attribute value (String, Rich Text, Component List, Asset List, Boolean, Integer, or Float)
  • Plain: Boolean flag indicating if the string is plain text or rich text

Usage Example:

Details

Components in AttributeData can be accessed using the IDs stored inside the "ComponentIds" array in AttributeValueData through the blueprint callable method TryGetArcweaveComponentById:

// Get the Arcweave subsystem
UArcweaveSubsystem* ArcweaveSubsystem = GEngine->GetEngineSubsystem<UArcweaveSubsystem>();
if (!ArcweaveSubsystem)
    return;

// Access attributes from an element
for (const FArcweaveAttributeData& Attribute : ElementData.Attributes)
{
    FString AttributeName = Attribute.Name;
    FString AttributeValue = Attribute.Value.Data;
    EArcweaveAttributeValueDataType ValueType = Attribute.Value.Type;

    // Handle different attribute types
    switch (ValueType)
    {
        case EArcweaveAttributeValueDataType::String:
        {
            // Handle plain text
            break;
        }
        case EArcweaveAttributeValueDataType::StringRichText:
        {
            // Handle rich text
            break;
        }
        case EArcweaveAttributeValueDataType::ComponentList:
        {
            // Handle component list - iterate through all component IDs referenced by this attribute
            for (const FString& ComponentId : Attribute.Value.ComponentIds)
            {
                FArcweaveComponentData ReferencedComponent;
                if (ArcweaveSubsystem->TryGetArcweaveComponentById(ReferencedComponent, ComponentId))
                {
                    // You can now work with the component data
                    // For example, access its attributes
                    for (const FArcweaveAttributeData& ComponentAttribute : ReferencedComponent.Attributes)
                    {
                        UE_LOG(LogTemp, Warning, TEXT("  Component Attribute: %s = %s"), 
                            *ComponentAttribute.Name, *ComponentAttribute.Value.Data);
                    }
                }
            }
            break;
        }
        case EArcweaveAttributeValueDataType::AssetList:
        {
            // Handle asset references
            break;
        }
        default:
        {
            break;
        }
    }
}

Breaking changes / upgrading

Attribute and component handling changed in this release. Existing C++ code that uses the old members will not compile, and Blueprints that use the old pins will show broken nodes until they are updated. These changes are part of version 3.0.0 (the previous release was 2.2.0).

Before Now
FArcweaveElementData::Components (TArray<FArcweaveComponentData>, copies) FArcweaveElementData::ComponentIds (TArray<FString>)
FArcweaveProjectData::Components (TArray<FArcweaveComponentData>) FArcweaveProjectData::ComponentsMap (TMap<FString, FArcweaveComponentData>, keyed by component id)
FArcweaveAttributeData::cType (FString) EArcweaveAttributeDataType (Elements, Global, Components, Boards, Undefined)
FArcweaveAttributeValueData::Type (FString) EArcweaveAttributeValueDataType (String, StringRichText, ComponentList, AssetList, Boolean, Integer, Float, Undefined)

Upgrading

  1. Replace reads of Element.Components with a loop over Element.ComponentIds, resolving each id with UArcweaveSubsystem::TryGetArcweaveComponentById. Check the returned boolean, and guard against elements whose ComponentIds array is empty before reading index 0.
  2. Replace reads of ProjectData.Components with ProjectData.ComponentsMap (use Find(Id) or iterate the map).
  3. Replace string comparisons such as Attribute.cType == TEXT("components") or Attribute.Value.Type == TEXT("string") with the enum values. Rich text is now reported as StringRichText (a "string" value with plain: false); plain text stays String.
  4. In Blueprints, refresh or re-create the nodes that used Components, cType or Value.Type, and switch on the new enums.

Using the Demo Project

You can explore the plugin implementation and see examples of its usage in our Arcweave demo project. This project includes a demo scene and samples of logic implementation using Arcweave's Web API, showcasing all the capabilities of the plugin.

Support

If you need support for an issue, you can open it using the CONTRIBUTING.md guide on GitHub or you can reach out on the 🔗 Discord server. .

License

The plugin is available under the MIT license. The bundled Arcscript and ANTLR runtimes retain their BSD 3-Clause licenses; their notices are included in packaged games.

About

Official Arcweave plugin for Unreal Engine. Bring branching dialogue and story logic into your game.

Topics

Resources

Contributing

Stars

8 stars

Watchers

3 watching

Forks

Releases

Packages

Contributors

Languages