This project demonstrates Arcweave integration with Unity, allowing you to import Arcweave projects both during development and at runtime.

You can preview the example project directly in your browser https://arcweave.itch.io/arcweave-unity-example

• Import Arcweave projects from web (API key + project hash) or local JSON
• Preloaded project support included in builds
• Conditional dialogue branching driven by Arcweave variables
• Arcweave component-based dialogue start/end detection
• Variable-to-gameplay binding (health bars, object activation, UI colors)
• Scene control (lighting, particles) driven by Arcweave attributes
• Sword swing ability unlocked at a specific narrative beat
• Character portraits loaded from Arcweave components
• Runtime narrative update without rebuilding (local JSON or web API)

1. Clone this repository
2. Open the project in Unity Hub (Unity 6 or Unity 2022 LTS)
3. The Arcweave Unity plugin is already included -- no extra setup needed
4. Press Play to test the demo scene

To learn more about the plugin: https://github.com/Arcweave/arcweave-unity-plugin

1. Export your Arcweave project in Unity format
2. Place the JSON file in Assets/Arcweave/project.json
3. Place all related images and audio files in Assets/Resources
4. Alternatively, use the web importer at runtime (see below)

1. Select or create an ArcweaveProjectAsset in Assets/Arcweave/
   • To create a new one: right-click in Assets > Create > Arcweave > Project Asset
2. In the Inspector, choose your import method:
   • From JSON: assign the exported .json file
   • From Web: enter your API key and project hash
3. Click Generate Project
4. After import, the Inspector shows variables (useful for debugging). Click Open Project Viewer to browse boards, elements, and connections.

Remember to connect your Arcweave Project Asset to the ArcweaveImporter and ArcweavePlayer GameObjects.

1. Arcweave project: create boards (one per NPC), add variables, write conditional branches, attach components to elements, export
2. Unity - import: assign JSON to ArcweaveProjectAsset, click Generate Project
3. Unity - NPC: add DialogueTrigger with the board name matching the Arcweave board
4. Unity - GameManager: set Dialogue Start/End Component Name if using component-based detection
5. Unity - portraits: place images in Assets/Resources/ with filenames matching Arcweave
6. Unity - audio: place audio files in Assets/Resources/; add ArcweavePlayerAudio to NPCs that have audio in their board
7. Unity - variable binding: use ArcweaveObjectActivation for object activation and ArcweaveHealthUI for health/slider
8. Build: File > Build Settings > Build. The arcweave/ folder is created automatically

Images and audio files are searched in the same order:

1. Unity's Resources folder (baked into the build)
2. [Build Folder]/arcweave/resources/ (drop files here to update post-build without rebuilding)

1. Launch the application
2. Press Esc to open the menu
3. Enter your API key and project hash
4. Click Import Web

1. Place your JSON in [Build Folder]/arcweave/project.json
2. Place images and audio files in [Build Folder]/arcweave/resources/
3. Press Esc > click Import Local

• JSON not loading: verify the file is exported from Arcweave in Unity format
• Images missing: filenames must match those in the Arcweave project
• API key / hash invalid: check your Arcweave account settings and project URL
• NPC not talking: check that Specific Board Name matches the Arcweave board name exactly (case-sensitive)
• Dialogue stuck: the last element needs a dialogue_end tag or DialogueEnd component
• Object not activating: check that ArcweaveObjectActivation is on an always-active object (e.g. the NPC) and points to the hidden object; variable name must match exactly (e.g. sword_locked); object must start inactive; variable must be boolean, default true
• Sword swing not unlocking: Component Name in SwordSwingHandler must be Attack (exact match); the Attack component must be attached to the element in Arcweave; the Animator needs an Attack Trigger parameter
• Audio not playing: verify ArcweavePlayerAudio is on the NPC GameObject; check that audio assets are uploaded and assigned to elements in Arcweave; audio files must be in Assets/Resources/ (editor/build) or [Build]/arcweave/resources/ (post-build); supported formats: mp3, wav, ogg, aiff
• Audio not stopping (Stop mode): ArcweaveAudioManager must be present in the scene; add it to a persistent GameObject (e.g. GameManager)

Assets/Scripts/
├── Arcweave/       -- ArcweavePlayer, ArcweavePlayerUI, ArcweaveImageLoader,
|                      RuntimeArcweaveImporter, ArcweaveImporterUI,
|                      ArcweaveAudioManager, ArcweaveAudioLoader, ArcweavePlayerAudio
├── Handlers/       -- ArcweaveAttributeHandler, ArcweaveElementComponentHandler,
|                      ArcweaveSceneController,
|                      SwordSwingHandler, ArcweaveHealthUI, ArcweaveObjectActivation
├── Game/           -- GameManager, PlayerController, ThirdPersonCamera, DialogueTrigger
└── Editor/         -- ArcweaveBuildProcessor

Central controller for Arcweave narratives. Manages project state, navigation between elements, variable state, and save/load. Fires events that UI and other scripts subscribe to.

Key events:

• onProjectStart(Project) / onProjectFinish(Project) -- project lifecycle
• onProjectUpdated(Project) -- fires after project is initialized or reloaded
• onElementEnter(Element) -- new dialogue node reached
• onElementOptions(Options, Action<int>) -- player choices available
• onWaitInputNext(Action) -- single path forward, caller invokes to advance

arcweavePlayer.onElementEnter += (element) => {
    Debug.Log($"Entered: {element.Title}");
};

Subscribes to ArcweavePlayer events and renders dialogue text, images, choices, and variable debug list. Configure UI references in the Inspector.

Proximity-based NPC interaction (in Game/ folder). Measures distance to the player each frame; shows a prompt and starts dialogue on key press.

Connects an Arcweave health variable to a Unity Slider, text, and animator. Also reads a color attribute to style the slider fill.

Toggles a GameObject based on an Arcweave boolean variable. Uses inverted logic: true = object inactive, false = object activates.

Object Activation naming convention: name variables for the locked/closed state (e.g. sword_locked). Default true = hidden. When flipped to false, the object activates.

Reads the SceneSettings component on project load/import (in Handlers/ folder). Attributes: Time ("Day" / "Night") controls camera background; ParticleState ("rain" / "clear") toggles particle systems.

Optional singleton (DontDestroyOnLoad) that acts as a scene-wide event bus for audio stop signals. Required only when using the Stop playback mode on audio assets — it broadcasts a stop signal to all ArcweavePlayerAudio instances in the scene so a clip can be halted across multiple characters simultaneously.

Add it to any persistent GameObject (e.g. GameManager). If not present, Once and Loop modes work normally; only Stop mode has no effect.

Add to any NPC that has audio assets assigned to its Arcweave elements. Subscribes to ArcweavePlayer.onElementEnter and plays the audio assets attached to each element, but only while the DialogueTrigger reports an active dialogue — preventing stray audio if events fire outside a conversation.

Multiple audio assets can be assigned to a single element in Arcweave; each is played independently with its own settings. Audio assets are configured entirely in Arcweave (upload via the Assets tab, assign to elements). No audio clips are referenced directly in Unity.

For each asset, the script first calls TryGetAudioClip() (resolves from Unity Resources). If that returns null, it falls back to ArcweaveAudioLoader, which loads the file asynchronously from [Build]/arcweave/resources/ and caches it. This means audio files can be added or swapped post-build without rebuilding.

Playback modes (set in Arcweave):

Each audio asset also supports volume (0–1) and delay (seconds before playback starts), both set in Arcweave. Delayed clips use AudioSource.PlayDelayed(). Non-looping AudioSource components are destroyed when the element changes; looping sources persist until explicitly stopped via Stop mode.

Singleton that loads images by filename from Resources, then [Build]/arcweave/resources/, then custom paths. Caches loaded images for performance.

Singleton that loads audio files at runtime using the same pattern as ArcweaveImageLoader. Checks Unity's Resources folder first, then [Build]/arcweave/resources/. Loading from the build folder is async (UnityWebRequest); clips are cached by filename after the first load.

Used automatically by ArcweavePlayerAudio as a fallback when TryGetAudioClip() returns null — no manual setup needed. To support post-build audio updates, place audio files in [Build]/arcweave/resources/ alongside images.

Async import from web API or local JSON at runtime. Provides onImportSuccess / onImportFailure events. Saves credentials between sessions.

UI panel for runtime import. Accessible via Esc key. Supports both web and local JSON import.

Singleton state machine: Gameplay, Dialogue, Paused. Controls cursor lock, player/camera enable, and UI visibility.

Detection priority: component name first, attribute tag fallback. Existing boards using tags continue to work.

Camera-relative WASD movement. Drives Animator Speed float. Sword swing on left mouse button when canSwing is true (set by SwordSwingHandler).

Follows a target Transform with mouse-driven rotation. Disabled by GameManager during Dialogue and Paused states.

Editor-only post-build hook. Creates arcweave/ and arcweave/resources/ in the build output; copies project.json if present.

Two base classes for extending Arcweave-driven behavior. The designer configures data in Arcweave; the developer implements one method in Unity.

Reads a named attribute from a named component at project load. Override ApplyAttributeValue(string value).

public class MyHandler : ArcweaveAttributeHandler
{
    protected override void ApplyAttributeValue(string value)
    {
        // React to the attribute value
    }
}

Concrete example: ArcweaveHealthUI reads a slider color attribute from a component and applies it to the health bar slider fill.

Watches ArcweavePlayer.onElementEnter. Checks if the current element has a component matching componentName. Override OnComponentDetected and optionally OnComponentAbsent.

public class MyHandler : ArcweaveElementComponentHandler
{
    protected override void OnComponentDetected(Element element, Component component)
    {
        string value = GetAttributeValue(component, "MyAttribute");
        // React to the component
    }
}

Concrete example: SwordSwingHandler -- detects the Attack component, reads SwingSpeed attribute, calls PlayerController.EnableSwordSwing(speed). Once unlocked, the ability stays for the session.

Uses PlayerPrefs. Key prefix: arcweave_save. Saves current element ID and all variable values as JSON. Call ArcweavePlayer.Save() / Load().

• Unity 6 (6000.0.x) -- primary development version
• Unity 2022 LTS (2022.3.x) -- tested and working. Unity Hub automatically resolves package versions.
• Arcweave plugin: included in the project. Standalone plugin: https://github.com/Arcweave/arcweave-unity-plugin