Unity integration

Arcweave provides a free plugin for importing your Arcweave projects into Unity.

This plugin supports data that is either:

• Exported from Arcweave via Export for Unity (available to all workspace tiers) or
• Fetched via Arcweave's REST API (available to Team workspaces only).

Tutorials

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

Plugin repository

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

Example Project

Explore our Unity example project to see Arcweave's implementation with Unity in action.

The project uses Arcweave's project template called Game Engine Example.

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.

Install the plugin

Choose one of the following methods to install the Arcweave plugin for Unity:

The bundled demo requires Unity UI (com.unity.ugui version 2.0.0 or a compatible production release). If your project does not already include it, install it from Window > Package Manager before importing the plugin. New Unity 6000.5 projects do not include this package by default.

From GitHub

Downloading and manually installing the plugin from GitHub is the recommended solution. To do so:

1. Download this repository as a ZIP file from GitHub.
2. Extract the ZIP file.
3. Copy the /Assets/Arcweave folder into your Unity project's Assets folder.

From Unity Asset Store

You can also download and install the plugin from the Unity Asset Store:

1. Get the asset from the Unity Asset Store.
2. Open Unity and go to Window > Package Manager.
3. Select My Assets from the dropdown.
4. Find Arcweave for Unity and click Download, then Import.

Note: This repository is not structured as a UPM (Unity Package Manager) package and cannot be installed via Git URL.

Get Arcweave data

Via Export for Unity

In Arcweave:

1. Open your project.
2. Click the Export project icon in the top bar.
3. Go to the Engine tab.
4. Select Export for Unity.
5. Keep Include assets selected if your project uses images or audio. It is selected by default.
6. Click Export.

You will get a .zip file containing:

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

File placement:

• Place project.json anywhere in your Unity project's Assets folder.
• For this demo project, images must go in a Resources folder (create one if it doesn't exist) or they won't load at runtime.

Via REST API

Use of Arcweave REST API is available to Team workspaces only.

You will need:

• Your Team workspace API key with Read projects enabled (found in your workspace's API section).
• Your project hash (found in your project's Settings > Properties).

Create ArcweaveProjectAsset

To import your data into Unity:

1. Right-click in the Unity Project Window.
2. Navigate to Create > Arcweave > Project Asset.
3. Name the new .asset file as you prefer.
4. Select it to open the Inspector.

Import settings

Choose your import source:

• From Json: Set Import Source to From Json, then drag your project.json file into the Project JSON File field.
• From Web: Set Import Source to From Web, then enter your User API Key and Project Hash. To import a specific language, enter its code in Language ISO; select Fallback Content to fill missing translations from the language's Translates from chain.

Click the import button (Import Project FromJson or Import Project FromWeb) to begin the import.

After successful import, the Inspector displays:

• The project name
• The imported project data, including global variables and scoped variables nested under their boards or components
• An "Open Project Viewer" button for viewing the project flowchart

Demo scene

The plugin includes a Demo folder with a complete example scene.

Run the demo

1. Open ArcweaveDemoScene from the Demo folder.
2. Select the ArcweavePlayer GameObject in the hierarchy.
3. Assign your imported project asset to the Aw field.
4. Press Play.

Unity 6+ fix

If your project's Active Input Handling (Edit > Project Settings > Player > Other Settings) is set to Input System Package (New), the demo's legacy Standalone Input Module can't read input, and UI buttons won't respond to clicks. 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 the Replace with InputSystemUIInputModule button.

Projects set to Input Manager (Old) or Both can keep the Standalone Input Module.

Add image assets

If your Arcweave project uses images:

1. Create a Resources folder in your Unity project (if it doesn't exist).
2. Copy your image files into the Resources folder.
3. Ensure image filenames match those in Arcweave (without extension).
4. Set each image's Texture Type to Default in Import Settings.

The plugin loads images dynamically using Resources.Load().

Add audio assets

If your Arcweave project uses audio:

1. Create a Resources folder in your Unity project (if it doesn't exist).
2. Copy your audio files into the Resources folder.
3. Ensure audio filenames match the asset names in Arcweave.

Each element's audio is available through GetAudioAssets(). Call TryGetAudioClip() on an audio asset to load its clip with Resources.Load<AudioClip>(), using the filename without its extension.

Plugin reference guide

Project

The root container for an imported Arcweave project. Access via ArcweaveProjectAsset.Project.

Properties

Property	Type	Description
name	string	Project name
Boards	List<Board>	All boards in the project
components / Components	List<Component>	All components (characters/entities)
Variables	List<Variable>	All global variables
StartingElement	Element	Entry point for the narrative

Methods

Method	Description
void Initialize()	Must call before use. Resets all variables and visit counts.
Board BoardWithID(string id)	Get board by ID
Board BoardWithName(string name)	Get board by name
Element ElementWithId(string id)	Get element by ID
T GetNodeWithID<T>(string id)	Get any node by ID and type
Variable GetVariable(string name, string scope = null)	Get a global by name, or pass an owner custom ID for a scoped variable
IEnumerable<Variable> GetAllVariables()	Enumerate global, board, and component variables
bool SetVariable(string name, object value)	Set a global variable
bool SetVariable(string name, string scope, object value)	Set a board or component variable
bool SetVariableById(string id, object value)	Set any variable by its stable Arcweave ID
void ResetVariablesToDefaultValues()	Reset all global and scoped variables to defaults
string SaveVariables()	Serialize current global and scoped state to JSON
void LoadVariables(string json)	Restore global and scoped state from JSON
int Visits(string elementId)	Get visit count for an element
void ResetVisits()	Reset all visit counts to 0

Scoped variables

String Field, Boolean, Integer, and Float attributes become scoped 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:

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

Project.Variables contains globals. Each board or component exposes its own Variables collection, while GetAllVariables() enumerates every scope. Unqualified lookups remain global-only.

Variable globalHealth = project.GetVariable("health");
Variable boardHealth = project.GetVariable("health", "castle");
Variable componentHealth = project.GetVariable("health", "hero");

project.SetVariable("health", 100);
project.SetVariable("health", "castle", 10);
project.SetVariable("health", "hero", 20);

The attribute's Arcweave ID remains the stable variable ID used by runtime changes and saved state. A String Field attribute with null data imports as an empty string.

Board

Container for narrative nodes.

Properties

Property	Type	Description
Id	string	Unique identifier
CustomId	string	Arcweave custom ID used as a variable scope
Name	string	Board name
Nodes	List<INode>	All nodes (Elements, Branches, Jumpers)
Notes	List<Note>	Annotation notes
Attributes	List<Attribute>	Board attributes
Variables	List<Variable>	Variables scoped to this board

Methods

Method	Description
T NodeWithID<T>(string id)	Get node by ID and type
Element ElementWithID(string id)	Get element by ID

Element

A narrative node containing dialogue content.

Properties

Property	Type	Description
Id	string	Unique identifier
Title	string	Element title (may contain Arcscript)
RawContent	string	Original content with Arcscript markup
RuntimeContent	string	Evaluated content (call RunContentScript() first!)
Visits	int	Visit counter (get/set)
Components	List<Component>	Attached characters/entities
Attributes	List<Attribute>	Custom metadata
Outputs	List<Connection>	Outgoing connections
cover	Cover	Cover image reference
AudioAssets	AudioAsset[]	Audio assets attached to this element

Methods

Method	Description
void RunContentScript()	Evaluate Arcscript in content → updates RuntimeContent
Options GetOptions()	Get available paths (evaluates branch conditions)
bool HasContent()	Check if element has content
bool HasComponent(string name)	Check if element has component by name
bool TryGetComponent(string name, out Component c)	Try to get component by name
Texture2D GetCoverImage()	Load cover image from Resources
Texture2D GetFirstComponentCoverImage()	Load first component's cover image
Texture2D GetCoverOrFirstComponentImage()	Get cover or fallback to component image
AudioAsset[] GetAudioAssets()	Get the audio assets attached to this element

Code Example

// WRONG - RuntimeContent will be empty/outdated
string text = element.RuntimeContent;  // ❌ Don't do this!

// CORRECT - Always call RunContentScript() first
element.RunContentScript();            // ✅ Evaluates Arcscript
string text = element.RuntimeContent;  // ✅ Now it's updated

// Get available choices
Options options = element.GetOptions();
if (options.hasPaths) {
    foreach (Path path in options.Paths) {
        Debug.Log("Choice: " + path.text);
    }
}

Connection

Link between nodes with optional label.

Properties

Property	Type	Description
Id	string	Unique identifier
RawLabel	string	Original label with Arcscript
RuntimeLabel	string	Evaluated label (call RunLabelScript() first!)
Source	INode	Source node
Target	INode	Target node
isValid	bool	True if connection has valid ID

Methods

Method	Description
void RunLabelScript()	Evaluate Arcscript → updates RuntimeLabel

Branch

Conditional branching node with if/elseif/else logic.

Properties

Property	Type	Description
Id	string	Unique identifier
Conditions	List<Condition>	Ordered conditions (first true wins)
colorTheme	string	Visual theme color

Condition

Single condition in a branch.

Properties

Property	Type	Description
Id	string	Unique identifier
Script	string	Arcscript condition expression
Output	Connection	Output connection if true

Methods

Method	Description
bool Evaluate()	Evaluate condition (empty scripts return true)

Jumper

Navigation shortcut to another element.

Properties

Property	Type	Description
Id	string	Unique identifier
Target	Element	Target element to jump to

Component

Character or entity definition. Not a Unity MonoBehaviour.

Properties

Property	Type	Description
Id	string	Unique identifier
CustomId	string	Arcweave custom ID used as a variable scope
Name	string	Component name
Attributes	List<Attribute>	Custom attributes
Variables	List<Variable>	Variables scoped to this component
cover	Cover	Cover image reference

Methods

Method	Description
Texture2D GetCoverImage()	Load cover image from Resources

Attribute

Custom metadata on elements, components, or boards.

Properties

Property	Type	Description
Id	string	Stable Arcweave attribute ID
CustomId	string	Variable name for an eligible scoped attribute
Name	string	Attribute name
Type	DataType	Plain/rich string, component/asset list, bool, integer, float
data	object	Attribute data (lazy-evaluated for RichText)
containerType	ContainerType	Element, Component, or Board
containerId	string	ID of the container

Variable

Global, board-scoped, or component-scoped state variable. Supports: int, double, bool, string.

Properties

Property	Type	Description
Id	string	Stable Arcweave variable or attribute ID
Name	string	Variable name
Value	object	Current value
DefaultValue	object	Initial value
Parent	IHasVariables	Owning board/component; null for globals
Type	Type	System.Type of the value

Methods

Method	Description
void ResetToDefaultValue()	Reset to default value

Cover

Image or video reference.

Properties

Property	Type	Description
type	Cover.Type	Image, Youtube, or Undefined
filePath	string	Asset filename

Methods

Method	Description
Texture2D ResolveImage()	Load image from Resources folder

Options

Available paths from an element. Created by Element.GetOptions().

Properties

Property	Type	Description
Element	Element	Source element
Paths	List<Path>	Valid paths to next elements
hasPaths	bool	True if any paths exist
hasOptions	bool	True if multiple paths OR path has label

Path

Resolved path to a target element.

Properties

Property	Type	Description
label	string	Connection label (if any)
text	string	Label or target element's title
TargetElement	Element	Destination element

Methods

Method	Description
void ExecuteAppendedConnectionLabels()	Run Arcscript in all connection labels along path

ArcweavePlayer

Event-driven narrative player (demo helper class).

Inspector Fields

Field	Type	Description
aw	ArcweaveProjectAsset	The project to play
autoStart	bool	Auto-start on scene load

Events

Event	Signature	Description
onProjectStart	(Project)	Narrative started
onProjectFinish	(Project)	Narrative ended
onElementEnter	(Element)	Entered new element
onElementOptions	(Options, Action<int>)	Multiple choices available
onWaitInputNext	(Action)	Single path, waiting for continue

Methods

Method	Description
void PlayProject()	Start or restart the narrative
void Save()	Save current state to PlayerPrefs
void Load()	Load and restore saved state

Important Notes

1. The EventSystem's input module must match Active Input Handling: If the project uses Input System Package (New), as Unity 6 projects can, replace the EventSystem's Standalone Input Module with InputSystemUIInputModule. Otherwise, UI buttons won't respond to clicks. See Unity 6+ fix.

2. RuntimeContent requires RunContentScript(): The RuntimeContent property is not automatically evaluated. You must call RunContentScript() before reading it.

3. GetOptions() has side effects: This method internally saves and restores variable state while evaluating branch conditions.

4. Initialize() resets everything: Calling Project.Initialize() resets all global and scoped variables to defaults and all visit counts to 0.

5. Scoped variables require a scope: GetVariable("health") searches globals only. Pass the owning board or component custom ID to access a scoped variable.

6. Images and audio must be in a Resources folder: Cover images and audio clips are loaded via Resources.Load(). Place them in any Resources folder and ensure filenames match (without extension).

7. Components are not MonoBehaviours: Arcweave Components represent characters/entities in your narrative, not Unity components.

8. Visit tracking is manual: The Visits property must be incremented manually (or use ArcweavePlayer which does it automatically).

Troubleshooting

❌ UI buttons don't respond to clicks in Unity 6 or newer versions

✅ If Active Input Handling (Edit > Project Settings > Player > Other Settings) is set to Input System Package (New), the EventSystem needs the Input System's UI module. Perform the following steps:

1. Select EventSystem in the Hierarchy.
2. In the Inspector, locate Standalone Input Module.
3. Click Replace with InputSystemUIInputModule.

❌ Images not loading

GetCoverImage() returns null.

✅ Ensure images are in a folder named exactly Resources (case-sensitive).
✅ Verify the filename matches (without extension).
✅ Check the image's Texture Type is set to Default in Import Settings.

❌ RuntimeContent is empty or shows Arcscript markup

You are seeing {variable_name} or if/endif blocks in text.

✅ Always call RunContentScript before reading RuntimeContent

element.RunContentScript();

❌ Getting NullReferenceException when accessing variables

Variables are null or throw errors.

✅ Call Initialize once before using the project:

project.Initialize();

❌ Choices/paths not appearing

GetOptions() returns no paths or wrong paths.

✅ Check your branch conditions in Arcweave - they might all be evaluating to false.
✅ Verify variable values are correct: Debug.Log(project.GetVariable("varName").Value);
✅ Use the Project Viewer in Unity to visually inspect connections.

❌ Save/Load not working

Load() doesn't restore the correct state.

✅ Ensure you called Save() before Load().
✅ PlayerPrefs persists between sessions - use PlayerPrefs.DeleteAll() to clear if testing.
✅ Check the save keys exist: PlayerPrefs.HasKey("arcweave_save_currentElement").

❌ Import button is disabled

✅ From Json: Drag a TextAsset (.json file) into the Project JSON File field.
✅ From Web: Fill in both the User API Key and Project Hash fields.
✅ Ensure the JSON file is valid (open it in a text editor to verify it's not corrupted)

License

See the LICENSE file on GitHub for details.