Unity tutorial | Part 1: Install & set up

This tutorial walks you through installing the Arcweave Unity Plugin, exporting a narrative project from Arcweave, and importing it into Unity.

Video tutorial

You can watch the video version of this tutorial below.

Create a Unity project

If you already have a Unity project, skip to Download the plugin.

Open Unity Hub and click New project in the top right.

In the project creation window:

1. Select your Unity version from the dropdown at the top.
2. Choose either the Universal 2D or the Universal 3D template.
3. Give your project a name (e.g., Unity Arcweave Plugin).
4. Click Create project.

Download the plugin

The Arcweave Unity Plugin is available on both the Unity Asset Store and GitHub. The GitHub version is recommended as it is always up to date.

Navigate to the plugin repository: github.com/arcweave/arcweave-unity-plugin

Click the green Code button, then select Download ZIP.

Once the download is complete, extract the ZIP file. The extracted folder (arcweave-unity-plugin-main) contains:

• A readme file
• An Assets folder, containing:
  • Assets/Arcweave/Plugin: The core plugin (scripts, editor tools, runtime components). Required.
  • Assets/Arcweave/Demo: Demo scenes and sample implementations. Recommended for learning.

Install the plugin

The plugin's demo scripts require the Unity UI package (com.unity.ugui). If your project doesn't include it, install it from Window > Package Manager before you import the plugin; otherwise the demo scripts won't compile. New Unity 6000.5 projects don't include this package by default.

In Unity, make sure the Project window is visible and you are inside the Assets folder.

Arrange your windows so Unity and the file explorer are both visible side by side. Then drag the Arcweave folder from the extracted ZIP into Unity's Assets folder.

Unity will begin importing automatically. A progress bar appears in the bottom right while it compiles the scripts and sets up editor extensions. This takes about 30 seconds.

Once complete, verify the installation by expanding the Arcweave folder in the Project window — you should see Demo and Plugin subfolders.

To confirm everything is working, open the demo scene by navigating to the Demo folder and double-clicking the ArcweaveDemoScene scene file.

Export for Unity

The demo scene is empty until you provide narrative data from Arcweave. Log in to your Arcweave workspace at arcweave.com.

For this tutorial, open the Game Engine Example project. If it is not in your workspace, click + New project.

Then select the Game Engine Example template.

With the project open, click the Export icon (the download arrow) in the top menu bar.

In the Export project dialog, select the Engine tab, then choose Export for Unity.

The Include assets checkbox is enabled by default. Leave it checked — this adds the project's asset files to the ZIP alongside the narrative data.

Click the orange Export button. A ZIP file named after the project and the export time (for example, game-engine-example-2026-10-09-120000.unity.zip) downloads to your machine.

Examine the export

Extract the downloaded ZIP file. The folder contains:

• project.json (file): The core data file, which contains your entire narrative structure (elements, connections, variables, components, etc).
• assets (folder): Image, audio, and video files included in the project (if any), in the same folder structure as in the project's Assets tab.
• cover (folder): The project's cover image (if any). Not required for functionality.

Import into Unity

Add the files to your Unity project

To add the story data and assets into Unity:

1. Drag the project.json file into Unity's Assets/Arcweave folder.
2. In the Assets folder, create a new folder named Resources:
   1. Right-click Assets.
   2. Select Create → Folder.
   3. Name it Resources.
3. Drag the entire contents of the exported assets folder into Unity's Assets/Resources folder you just created.

Unity will automatically import all the files.

⚠️ The name must be exactly Resources. Unity uses this specific folder name to load assets dynamically at runtime. The plugin loads each file by its filename from the top level of a Resources folder, so if the exported assets folder contains subfolders, move their files directly into Resources.

Create ArcweaveProjectAsset

To load your Arcweave data, you first need to create an ArcweaveProjectAsset in Unity:

1. In the Project window, right-click inside the Assets/Arcweave/Demo folder.
2. Select Create → Arcweave → Project Asset.

A new asset appears and you can rename it to something descriptive, such as MyStory.

Select the asset. In the Inspector:

1. Set Import Source to From Json.
2. Drag project.json from the Project window into the Project JSON File field.
3. Click Import Project FromJson.

Unity will parse the JSON and populate the asset with the project name, global variables, and scoped board and component variables. You can inspect this data and modify variable values at runtime through the plugin API.

Explore with Project Viewer

In the Inspector of your ArcweaveProjectAsset, click Open Project Viewer.

A window opens directly inside Unity, showing the entire narrative structure of the Arcweave project that is loaded in the ArcweaveProjectAsset: its boards, elements, and their connections.

This lets you browse your narrative without leaving the editor.

Connect the asset to the ArcweavePlayer

The next step is to connect the ArcweaveProjectAsset with the ArcweavePlayer:

1. In the Hierarchy, select the ArcweavePlayer GameObject.
2. In its Inspector, locate the Aw field and drag your MyStory ArcweaveProjectAsset into it.

Press Play. The demo UI will display the Arcweave narrative project you imported.

Troubleshooting: UI buttons not responding

If the demo scene buttons are unresponsive, check the project's Active Input Handling (Edit > Project Settings > Player > Other Settings). If it is set to Input System Package (New), update the EventSystem's input module:

1. In the Hierarchy, select the EventSystem GameObject.
2. In the Inspector, find the Standalone Input Module component.
3. Click Replace with InputSystemUIInputModule.

The legacy Standalone Input Module can't read input when only the new Input System is active. Projects set to Input Manager (Old) or Both can keep it.

Import via REST API

Instead of a local JSON file, the plugin can fetch your project directly from Arcweave's servers. This is useful during production: when a narrative designer updates the project in Arcweave, you can pull the latest version into Unity without manually re-exporting.

The REST API is available to Team workspaces only. To use this method, you need an API Key with Read projects enabled and a Project Hash.

Get your API Key:

1. In Arcweave, open your workspace's API section.
2. Choose a key with Read projects enabled and copy it. See Workspace API to create or edit a key.

Get your Project Hash:

1. Open the project in Arcweave.
2. Click the Settings icon and go to Properties.
3. Copy the Project hash. See Copy the project hash.

Configure Unity:

1. Select your ArcweaveProjectAsset and change Import Source to From Web.
2. Paste your API Key into the User API Key field.
3. Paste the Project Hash into the Project Hash field.
4. Click Import Project FromWeb.

The Language ISO and Fallback Content fields are optional. Leave Language ISO empty to import the project's default language, or enter a language code to import that language of a localized project.

Unity will connect to Arcweave's servers and import the latest version of the project automatically.

Summary

You have now:

• Created a Unity project and installed the Arcweave Unity Plugin.
• Exported a narrative project from Arcweave.
• Imported it into Unity using the JSON method.
• Connected the project to the ArcweavePlayer and verified it in Play mode.