Arcweave Documentation

Appearance

Unreal Engine integration ​

Arcweave provides a free plugin for importing your Arcweave projects into Unreal Engine (version 5.0 and later).

The plugin can import data from Arcweave's JSON (available to all workspaces) or fetch them using Arcweave's REST API (Team workspaces only).

Tutorials ​

For a step-by-step walkthrough and videos on this integration, see the Unreal Engine integration tutorial.

Plugin repository ​

You can download the Arcweave plugin for Unreal Engine using its GitHub link.

Example Project ​

Screenshot from the example project in the Unreal Engine editor.

Explore our Unreal example project to see Arcweave's implementation with Unreal in action. The project uses Arcweave's project template called Game Engine Example.

The Projects section of an Arcweave workspace, showing the "Create new project" modal open, where the "Game Engine Example" template has been highlighted with an orange rectangle.

To recreate the Game Engine Example template:

  1. Go to the workspace's Projects section.
  2. Click the + New project button.
  3. Select a template from the menu.

Plugin installation ​

Complete the following steps, to install the Arcweave plugin for Unreal Engine:

  1. Download the plugin from its GitHub repository.
  2. Extract the contents of the downloaded .zip into the folder:
    ProjectRootDirectory/Plugins
    If this folder does not exist please create it.
  3. Open your project.
  4. If prompted to rebuild the Arcweave plugin, click Yes.

Transferring your data ​

There are 2 ways you can transfer your project's data and access them with the Arcweave Plugin for Unreal Engine:

JSON import ​

This method is available to all workspaces. For this method, complete the following steps:

a. Export from Arcweave ​

In Arcweave:

  1. Go to Export project > Engine
  2. Select Export for Unreal.
  3. Check or uncheck the Include assets checkbox, depending on whether you want to download the project's audio and image assets.
  4. Press the Export button.
  5. Save the downloaded .zip file to your drive.

b. Check the downloaded files & folders ​

The downloaded .zip file should contain the following files & folders:

  • project.json: contains all the data of your Arcweave project.
  • (Optional) cover/: the project cover image, if the project has one.
  • (Optional) assets/: the project's asset files, in the same folder structure as the project's asset library.

The files & folders marked as "optional" are included if you have checked the Include assets checkbox.

c. Import to Unreal Engine ​

To import your Arcweave data into your Unreal project, place those files & folders in this directory:

Content/ArcweaveExport

If this directory does not exist, create it. The plugin loads the first .json file it finds in this directory or its subfolders, so keep only one project JSON file there.

Then, enable local JSON import:

  1. In Unreal Engine, open Project Settings and go to Plugins > Arcweave.
  2. Select the checkbox that enables receiving data from local JSON (EnableReceiveMethodFromLocalJSON).
  3. Restart Unreal Engine for the setting to take effect.

When this setting is enabled, the plugin loads the local JSON file instead of fetching data from the REST API.

REST API ​

You can fetch your Arcweave project's data from within Unreal Engine, via Arcweave's REST API. This feature is available to Team workspaces only.

To do this, you will need your workspace's API key with Read projects enabled and your project's hash.

a. Copy your workspace's API key ​

To locate your API key, follow these steps:

  • Go to the API section of your workspace (Team workspaces only).
  • In the list of API keys, locate the one you want to use.
  • In the Key column, click the clipboard icon to copy the key to your clipboard.

You will paste the API key into your Project Settings, in Unreal Engine (see further below).

b. Copy your project's hash ​

To locate your project's hash, follow these steps:

  • Open your project.
  • In the top menu, click the cog icon to open Project settings.
  • Select Properties.
  • In the Project hash row, click the clipboard icon to copy the hash to your clipboard.

You will paste the project hash into your Project Settings, in Unreal Engine (see below).

c. Paste API key and hash to Project Settings ​

In Unreal Engine, follow these steps to link your Arcweave project:

  • Navigate to Project Settings.
  • Go to Plugins > Arcweave.
  • Make sure the local JSON setting (EnableReceiveMethodFromLocalJSON) is disabled.
  • Paste your API key into API Token and your project hash into Hash.

Important Classes and Functions ​

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: ​

  1. Fetch Data from Arcweave API or local JSON (FetchData)

    • This function fetches data from the Arcweave API using the provided API token and project hash. If the local JSON setting is enabled, it loads the JSON file from Content/ArcweaveExport instead.

  2. Load Arcweave API Token from Settings (LoadArcweaveSettings)

    • This function returns the plugin settings, including the Arcweave API token and project hash.

  3. Save Arcweave API Token to Settings (SaveArcweaveSettings)

    • This function saves the provided API token and project hash to the plugin settings.

  4. Get Arcweave Project Data (GetArcweaveProjectData)

    • This function retrieves the Arcweave project data.

  5. Run Transpiler for the Element and Increase Visits Counter (TranspileObject)

    • 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 (TranspileCondition)

    • This function runs the transpiler for a specific condition. It requires the condition ID and the ID of the element the flow is coming from (OriginElementId).

  7. Set Variable (SetVariable)

    • This function changes a variable's current runtime value from anywhere in your project, outside the dialogue logic. Provide the variable ID and the new value as a string in the same format as the original value. It does not change the value in your Arcweave project.

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

Scoped variables ​

String Field, Boolean, Integer, and Float attributes become 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's Arcweave ID remains the stable ID used by Set Variable and variable-change events.

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

Unqualified names resolve global variables only. All global, board, and component variables are available in FArcweaveProjectData.CurrentVars.

Each FArcweaveVariable stores its mutable Value separately from the project-authored DefaultValue. As a result, reset and resetAll restore the authored defaults even after earlier interpreter calls have changed the variables.

Import results ​

Bind OnArcweaveResponseReceived to use a successfully loaded project. For API imports, also bind OnArcweaveFetchCompleted(bSuccess, Message) to show the result in your own UI. A failed import keeps the previously loaded project.

API requests time out after 20 seconds. Starting a new import or calling CancelFetch() cancels a pending API request.

Starting element ​

After a successful import, FArcweaveProjectData.StartingElementId contains the project's starting element ID. It is empty when the project has no starting element. Importing does not run the starting element: pass the ID to TranspileObject when your game is ready to start the story.

Runtime save and load ​

CaptureState and RestoreState save and restore the current values of global, board, and component variables and the project's visit counts, using FArcweaveRuntimeState. Store this struct in your game's USaveGame. The plugin does not write save files or track your game's current position in the story.

Restore a snapshot only after importing the same project content; a snapshot taken from different content is rejected. See the plugin's runtime save/load guide for an example.

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 REST API, showcasing all the capabilities of the plugin.