Arcweave Plugin for Unreal Engine

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
• Packaging
• Data Collection Methods
  • JSON Import
  • Web API
• Important Classes and Functions
  • UArcweaveSubsystem Functions
  • Starting element
  • Scoped variables
  • Runtime save/load
  • ArcscriptTranspilerWrapper
  • ArcweaveModule
  • ArcweaveTypes
• Using the Demo Project
• Support
• License

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 thick to the field "Enable receive method from local JSON" inside Unreal under ProjectSettings at the tab "Arcweave Settings"

  

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 ArcweaveSubsystem{}

   class ArcscriptTranspilerWrapper{}
   class Arcweave {}
   class ArcweaveTypes {}
   ArcweaveSubsystem --|> UEngineSubsystem
   ArcweaveSubsystem "1"--"1..*" ArcweaveTypes
   ArcweaveSubsystem ..> ArcscriptTranspilerWrapper
   ArcscriptTranspilerWrapper ..> ArcweaveTypes
   ArcweaveSubsystem ..> Arcweave
   Arcweave *--> ArcscriptTranspilerWrapper

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 ArcweaveSubsystem{
      +HandleApiCall
      +HandleSettings
      +HandleArcweaveProjectData
      +ParseDataFromJson
      +TranspileData
   }

   ArcweaveSubsystem --|> 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 wrapper ArcweaveTypes:

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

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.