# Unreal Engine integration

Source: https://docs.arcweave.com/integrations/unreal
Section: Integrations
Description: Install the Arcweave plugin for Unreal Engine, transfer your project data, and use its main classes, functions, and demo project

Arcweave provides a free plugin for importing your Arcweave projects into [Unreal Engine](https://www.unrealengine.com/) (version 5.0 and later).

The plugin can import data from Arcweave's [JSON](https://docs.arcweave.com/integrations/json) (available to all workspaces) or fetch them using Arcweave's [REST API](https://docs.arcweave.com/rest-api/overview) (Team workspaces only).

## Tutorials

Context: Arcweave docs > Integrations > Unreal Engine integration > Tutorials

For a step-by-step walkthrough and videos on this integration, see the [Unreal Engine integration tutorial](https://docs.arcweave.com/tutorials/unreal/overview).

## Plugin repository

Context: Arcweave docs > Integrations > Unreal Engine integration > Plugin repository

You can download the Arcweave plugin for Unreal Engine using [its GitHub link](https://github.com/arcweave/arcweave-unreal-plugin).

## Example Project

Context: Arcweave docs > Integrations > Unreal Engine integration > Example Project

![Screenshot from the example project in the Unreal Engine editor.](https://docs.arcweave.com/assets/unreal-example.CQYaul5w.jpg)

Explore our [Unreal example project](https://github.com/arcweave/arcweave-unreal-example) to see Arcweave's implementation with Unreal in action. The project uses Arcweave's [project template](https://docs.arcweave.com/workspaces/projects#project-templates) 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.](https://docs.arcweave.com/assets/project-templates-engines.CkDhZ3Sy.png)

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

Context: Arcweave docs > Integrations > Unreal Engine integration > Plugin installation

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

1. Download the plugin from its [GitHub repository](https://github.com/arcweave/arcweave-unreal-plugin).
1. Extract the contents of the downloaded `.zip` into the folder:
   `ProjectRootDirectory/Plugins`
   If this folder does not exist please create it.
1. Open your project.
1. If prompted to rebuild the Arcweave plugin, click **Yes**.

## Transferring your data

Context: Arcweave docs > Integrations > Unreal Engine integration > 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

Context: Arcweave docs > Integrations > Unreal Engine integration > Transferring your data > JSON import

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

#### a. Export from Arcweave

Context: Arcweave docs > Integrations > Unreal Engine integration > Transferring your data > JSON import > a. Export from Arcweave

In Arcweave:

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

#### b. Check the downloaded files & folders

Context: Arcweave docs > Integrations > Unreal Engine integration > Transferring your data > JSON import > 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

Context: Arcweave docs > Integrations > Unreal Engine integration > Transferring your data > JSON import > 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

Context: Arcweave docs > Integrations > Unreal Engine integration > Transferring your data > 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](https://docs.arcweave.com/rest-api/overview#api-tokens) with **Read projects** enabled and your project's [hash](https://docs.arcweave.com/project-tools/settings#project-hash).

#### a. Copy your workspace's API key

Context: Arcweave docs > Integrations > Unreal Engine integration > Transferring your data > REST API > 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

Context: Arcweave docs > Integrations > Unreal Engine integration > Transferring your data > REST API > 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

Context: Arcweave docs > Integrations > Unreal Engine integration > Transferring your data > REST API > 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

Context: Arcweave docs > Integrations > Unreal Engine integration > 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`:

Context: Arcweave docs > Integrations > Unreal Engine integration > Important Classes and Functions > 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

Context: Arcweave docs > Integrations > Unreal Engine integration > Important Classes and Functions > 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

Context: Arcweave docs > Integrations > Unreal Engine integration > Important Classes and Functions > 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

Context: Arcweave docs > Integrations > Unreal Engine integration > Important Classes and Functions > 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

Context: Arcweave docs > Integrations > Unreal Engine integration > Important Classes and Functions > 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](https://github.com/arcweave/arcweave-unreal-plugin/blob/main/docs/runtime-state.md) for an example.

## Using the Demo Project

Context: Arcweave docs > Integrations > Unreal Engine integration > Using the Demo Project

You can explore the plugin implementation and see examples of its usage in our [Arcweave demo project](https://github.com/Arcweave/arcweave-unreal-example).
This project includes a demo scene and samples of logic implementation using Arcweave's REST API, showcasing all the capabilities of the plugin.