` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. # Welcome Source: https://docs.arcweave.com/ Section: Introduction Description: Welcome to the Arcweave documentation, with guides, tutorials, integrations, and API references for designing interactive stories and games [Arcweave](https://arcweave.com) is a browser-based tool for writing and designing interactive stories and games, such as branching narratives, dialogue trees, and quests. You map out your story as a visual flowchart of scenes and choices, add game logic with variables and conditions, and play-test it instantly in [Play Mode](https://docs.arcweave.com/introduction/quick-tour/play-mode). When it's ready, you can share it as a playable prototype or export it to game engines like Unity, Godot, and Unreal. You can start for free: a new [Arcweave account](https://docs.arcweave.com/introduction/quick-tour/create-account) comes with a free workspace and a sample project to explore. ![Screenshot of Arcweave's user interface, showing an open project, its left sidebar and top menus, and an open board with elements and connections forming a short scene.](https://docs.arcweave.com/assets/intro-ui.Dmn3yplH.png) ## About this guide Context: Arcweave docs > Introduction > Welcome > About this guide This guide is designed to provide you the following: - **Quick Arcweave overview** New to Arcweave or not sure if it's right for you? Start with this **Introduction** section. Click **Next Page** below, use the left sidebar to explore, or jump ahead to the [Quick Tour](https://docs.arcweave.com/introduction/quick-tour/overview). - **Diverse tutorials collection** The [Tutorials](https://docs.arcweave.com/tutorials/overview) section offers a range of hands-on examples to read and watch, that will help you deepen your skills and tackle real-world interactive storytelling challenges. - **Solid reference guide** A complete reference covering all of Arcweave's features. Use the search field (Ctrl/Cmd+K), look up a term in the [Glossary](https://docs.arcweave.com/introduction/glossary), or browse the following sections on the sidebar: - [Project Items](https://docs.arcweave.com/project-items/overview) and [Project Tools](https://docs.arcweave.com/project-tools/overview) cover everything related to your projects. - [Integrations](https://docs.arcweave.com/integrations/overview) shows how to use Arcweave with other platforms and game engines. - [REST API](https://docs.arcweave.com/rest-api/overview) covers authentication, read and write access, and the endpoint reference for custom integrations. - [Workspaces](https://docs.arcweave.com/workspaces/overview) covers workspaces, their members and roles, plans, and billing. - [Account](https://docs.arcweave.com/account/overview) covers creating your Arcweave account and managing its settings. ## Users community Context: Arcweave docs > Introduction > Welcome > Users community If you have questions, join the [Arcweave community on Discord](https://discord.com/invite/atVXxAK), where you can get answers, share your work, and connect with other creators. # What is Arcweave? Source: https://docs.arcweave.com/introduction/what-is-arcweave Section: Introduction Description: What Arcweave is, its design philosophy, why teams use it, and how it works for interactive stories and games Arcweave is a collaborative narrative engine for designing and prototyping immersive interactive experiences. It enables writers and designers to create complex projects intuitively, collaborate synchronously, and maintain a healthy and liberating distance from the development side. Arcweave is a cloud-based app. You only need a browser and an internet connection to create and manage your projects. ## Arcweave's philosophy Context: Arcweave docs > Introduction > What is Arcweave? > Arcweave's philosophy Arcweave separates **design** from **development**. - [Writers & Designers](https://docs.arcweave.com/introduction/whom-is-it-for/writers-designers) should be free to focus on story, without worrying about code. - [Developers](https://docs.arcweave.com/introduction/whom-is-it-for/developers) should get clean, structured data ready for integration. - [Team Leaders](https://docs.arcweave.com/introduction/whom-is-it-for/team-leaders) should have a clear overview, leave comments, and delegate. Arcweave enables parallel workflows with live collaboration, reusable components (story objects such as characters and items), and export formats ready for engines like Unity, Godot, or Unreal. ## Why use Arcweave? Context: Arcweave docs > Introduction > What is Arcweave? > Why use Arcweave? Tools like spreadsheets or flowchart apps can help get ideas and dialogue lines down, but they quickly become cluttered, error-prone, and hard to manage as complexity grows. Arcweave is purpose-built for interactive narrative design. It allows you to: - Map out complex story structures visually and intuitively. - Keep your story segments (be they chapters, scenes, or dialogue trees) organized in small, easy-to-read boards. - Assign attributes to characters, items, and locations. - Link logic and conditions directly into your story flow. - Preview and test your project in Arcweave's integrated Play Mode or your game engine's build. - Export structured data to your development environment. > ✅ No more struggling to trace story flow in a tangle of cells or... spaghetti megagraphs. ## How Arcweave works Context: Arcweave docs > Introduction > What is Arcweave? > How Arcweave works Arcweave runs entirely in your browser, offering a cross-platform, consistent environment for you to design, collaborate, and manage your **projects** efficiently in your teams' **workspaces**. ### Projects Context: Arcweave docs > Introduction > What is Arcweave? > How Arcweave works > Projects A [project](https://docs.arcweave.com/workspaces/projects) is where you design your interactive experiences. Each story or game you create lives in its own project. ![The Arcweave window showing an open project.](https://docs.arcweave.com/assets/project-general.Cw-i8z_y.png) Within a project, you can do the following: - Design your [story flow](https://docs.arcweave.com/introduction/quick-tour/flowchart), plot, and dialogue trees. - Store your [story objects](https://docs.arcweave.com/introduction/quick-tour/flowchart#attached-components). - [Play-test and debug](https://docs.arcweave.com/introduction/quick-tour/play-mode) your creation—immediately. - [Collaborate](https://docs.arcweave.com/introduction/quick-tour/collaboration) with teammates in real time. - Export your project for [integration](https://docs.arcweave.com/integrations/overview) with your platform or game engine. > ℹ️ New to terms like boards, elements, and branches? See [Core concepts](https://docs.arcweave.com/introduction/core-concepts) for a short map of how they fit together. ### Workspaces Context: Arcweave docs > Introduction > What is Arcweave? > How Arcweave works > Workspaces A [workspace](https://docs.arcweave.com/workspaces/overview) is your team's collaborative environment. Each workspace can contain multiple projects and its own set of collaborators. ![The Arcweave window showing the Roles section of a workspace.](https://docs.arcweave.com/assets/workspace-roles.C7SNZ55t.png) In a workspace, you can do the following: - Manage your team's projects. - Invite collaborators as workspace members. - Manage the members' permission roles. - Create custom roles (Team workspaces only). - Manage your workspace's settings and billing preferences. > ℹ️ Need help or want to connect? Join our [Discord community](https://discord.gg/atVXxAK)—we'd love to hear from you! # Core concepts Source: https://docs.arcweave.com/introduction/core-concepts Section: Introduction Description: A beginner's map of Arcweave's building blocks—boards, elements, connections, branches, jumpers, components, attributes, variables, and Arcscript—and how they fit together Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. Arcweave uses a small set of building blocks to describe an interactive story. This page explains each one in plain terms and shows how they fit together, so the rest of the documentation makes sense. Each term links to its full reference page. ## The big picture Context: Arcweave docs > Introduction > Core concepts > The big picture Your work in Arcweave is organized like this: - A **[workspace](https://docs.arcweave.com/workspaces/overview)** is your team's space. It holds your projects and the people who work on them. - A **[project](https://docs.arcweave.com/workspaces/projects)** is one story or game. Inside a project you'll find: - **[Boards](https://docs.arcweave.com/project-items/boards)**: the canvases where you draw your story as a flowchart: boxes for the story's moments, joined by arrows that show what can happen next. A board holds: - **[Elements](https://docs.arcweave.com/project-items/elements)**: the story's moments, such as a scene, a location, or a line of dialogue. - **[Connections](https://docs.arcweave.com/project-items/connections)**: the arrows between items. Their **[labels](https://docs.arcweave.com/project-items/labels)** become the choices the player clicks. - **[Branches](https://docs.arcweave.com/project-items/branches)**: decision points that pick a path based on conditions. - **[Jumpers](https://docs.arcweave.com/project-items/jumpers)**: shortcuts that continue the story at an element somewhere else. - **[Notes](https://docs.arcweave.com/project-items/notes)**: annotations for you and your team. They aren't part of the story. - **[Components](https://docs.arcweave.com/project-items/components)**: your story objects, such as characters, locations, and items. Each one stores its details in **[attributes](https://docs.arcweave.com/project-items/attributes)**. - **[Variables](https://docs.arcweave.com/project-items/variables/overview)**: the story's memory, such as whether the player has found a key. - **[Assets](https://docs.arcweave.com/project-items/assets/overview)**: images, audio, and video files. Boards hold the **story flow**: what happens and in which order. Components, variables, and assets belong to the whole project, so you can use them on any board. ## Story flow Context: Arcweave docs > Introduction > Core concepts > Story flow You build the flow on a board by placing items and linking them with connections. - **Elements** carry the story. An element has a title and content: the text the player reads. You can also attach images, audio, video, or components to it. - **Connections** link one item to the next and set the order of events. An element's outgoing connections lead to the player's options, and a connection's label is the option's text. - **Branches** let the story react. A branch checks conditions written as `if`, `elseif`, and `else`, and sends the flow down the first path whose condition is true. - **Jumpers** keep large stories tidy. Instead of drawing a long arrow across a board—or to another board—you connect to a jumper, and the story continues at its target element. Split a large story into several boards, for example one per chapter, scene, or conversation, and use jumpers to move between them. ## Story objects Context: Arcweave docs > Introduction > Core concepts > Story objects **Components** describe the things your story is about. A component for a character might hold their name, a portrait, and attributes such as their age or backstory. **Attributes** are labeled values, such as text, numbers, true/false values, or lists of other components or assets. Components, elements, and boards can all have attributes. Game engines can read them when you [export](https://docs.arcweave.com/integrations/overview) your project. ## Story logic Context: Arcweave docs > Introduction > Core concepts > Story logic **Variables** let the story remember what happened. For example, a `has_key` variable can start as `false` and become `true` when the player finds the key. Variables can belong to the whole project ([global](https://docs.arcweave.com/project-items/variables/global)), to a [board](https://docs.arcweave.com/project-items/variables/board), or to a [component](https://docs.arcweave.com/project-items/variables/component). **[Arcscript](https://docs.arcweave.com/project-items/arcscript)** is Arcweave's simple scripting language. You use it to change and read variables: - In an element's content or a connection's label, a line of Arcscript can change a variable when the player reaches it: ```arcscript has_key = true ``` - In a branch, an Arcscript condition reads variables to choose a path, for example `has_key`, which is true once the player has the key. ## How a story plays Context: Arcweave docs > Introduction > Core concepts > How a story plays [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview) lets you play your project as a choice-based game. It follows your flowchart like this: 1. The story begins at the **starting element** you choose. 1. Play Mode shows the current element's content, cover, and attached components. 1. Play Mode follows the element's outgoing connections to work out the player's **options**: - A connection's label becomes the option's text. - When a path goes through a **branch**, only the path of the first true condition counts, so branches decide which options the player sees. - A path that ends at a **jumper** continues at the jumper's target element, even on another board. 1. When the player picks an option, the element at the end of that path becomes the current one. 1. Along the way, Arcscript in elements and labels updates variables, so later branches can react to the player's choices. For example, the player reaches a locked door. Earlier, an element where they searched the room set `has_key = true`. Now a branch after the door checks `has_key`: if it's true, the player sees the option "Unlock the door"; otherwise, they see "Walk away." ## Where to go next Context: Arcweave docs > Introduction > Core concepts > Where to go next - See these concepts in a real project in the quick tour's [Flowchart analysis](https://docs.arcweave.com/introduction/quick-tour/flowchart), which uses the sample project _The Castle._ - Build your first project step by step in the [Basic Arcweave tutorial](https://docs.arcweave.com/tutorials/basic/overview). - Look up any Arcweave term in the [Glossary](https://docs.arcweave.com/introduction/glossary). - For a detailed table of every item, where it lives, and what it connects to, see [Project items](https://docs.arcweave.com/project-items/overview#how-project-items-relate). # Whom is Arcweave for? Source: https://docs.arcweave.com/introduction/whom-is-it-for/overview Section: Introduction Description: An overview of Arcweave's application to various workflows Arcweave is a collaborative narrative design tool used by a wide range of creative professionals who design nonlinear content and interactive experiences. Professionals using Arcweave include: - Game designers and developers - Interactive fiction writers - Instructional and learning experience designers - Serious games developers - Narrative and quest designers - Escape room and puzzle creators - TTRPG writers & referees - UX and interaction designers - Creative and marketing writers Whether you're working solo or as part of a team, Arcweave helps you structure your ideas clearly, collaborate efficiently, and export your story data to your desired platform or game engine. To see what changes in your day-to-day work, read the page for your role: - [Writers & Designers](https://docs.arcweave.com/introduction/whom-is-it-for/writers-designers): you write the story, dialogue, and game logic. - [Developers](https://docs.arcweave.com/introduction/whom-is-it-for/developers): you bring the story into a game engine or another platform. - [Team Leaders](https://docs.arcweave.com/introduction/whom-is-it-for/team-leaders): you manage the people, projects, and plan. > ✅ Already working in another tool? Arcweave supports a range of workflows, and it's easy to incorporate it into your process. [Contact us](https://arcweave.com/contact) to discuss a tailored migration solution for your team. # Arcweave for Writers & Designers Source: https://docs.arcweave.com/introduction/whom-is-it-for/writers-designers Section: Introduction > Whom is it for? Description: How Arcweave applies to the workflow of writers & designers Arcweave is built with writers and narrative designers as its core users. It's purpose-built to support the creation of interactive experiences—whether that's branching dialogue, RPGs and adventure games, nonlinear quests, or immersive story-driven worlds. This guide introduces the main benefits and tools available to writers, game designers, and interactive storytellers working in Arcweave. ## What changes for you Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Writers & Designers > What changes for you If you write branching stories in documents, spreadsheets, or general-purpose flowchart apps, here's what changes when you move to Arcweave: | Without Arcweave | With Arcweave | | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Dialogue trees live in spreadsheet rows, and following one branch is hard. | You draw each scene as a flowchart on a [board](https://docs.arcweave.com/project-items/boards) and see every choice and where it leads. | | You wait for a build to find out whether a branch works. | You play your story in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview) right away, or [start from any element](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#quickstart-play-mode-from-here). | | You track what the player has done ("Has the player found the key?") in notes. | [Variables](https://docs.arcweave.com/project-items/variables/overview) remember it, branches react to it, and the [Debugger](https://docs.arcweave.com/project-tools/play-mode/debugger) shows the values as you play. | | Character sheets and lore sit in separate documents. | [Components](https://docs.arcweave.com/project-items/components) hold each character, item, or location, and you attach them to the story where they appear. | | You send a document around and merge everyone's edits. | Your team edits the same project at the same time and leaves [comments](https://docs.arcweave.com/project-items/comments) on the boards. | ## Story-focused Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Writers & Designers > Story-focused Arcweave lets you map, organize, and test your narrative without diving into code or spreadsheets. You can: - **Design your content visually** with flowcharts and see how your narrative flows at a glance. - **Organize into multiple boards** to break your narrative into scenes, chapters, or content types for clarity. - **Write dialogue and descriptions** in flexible elements. - **Write without breaking focus** using keyboard shortcuts and real-time navigation. - **Catch errors immediately** by editing while playtesting without leaving the preview. - **Build logic with branches, variables, and Arcscript.** It's simple, no programming background needed. - **Bring in existing stories** by [importing projects](https://docs.arcweave.com/workspaces/projects#import-projects) or through the [REST API](https://docs.arcweave.com/rest-api/overview) (Team workspaces), without starting from scratch. > ✅ Everything stays visual and intuitive, so your focus remains on storytelling, pacing, and player experience. ## Reusable story objects Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Writers & Designers > Reusable story objects Arcweave lets you define structured, reusable objects—such as characters, items, locations, spells, or any other narrative elements your story requires. These are stored as **components**, one of Arcweave's most versatile tools. ![An Arcweave project showing the component of a character called "grain merchant." The component includes attributes like "name," "personality," "reputation," et al.](https://docs.arcweave.com/assets/component-character-info.-r7AtDcB.png) Use **component attributes** to organize and document key information: character backstories, lore, relationships, inventory, stats—anything relevant to your story or game systems. ![Another component example from a card game, of which the attributes include a component list called "cards" and various asset lists.](https://docs.arcweave.com/assets/component-integration-attributes.BWiFN7E2.png) Component attributes also play a central role in integration with game engines—if your team uses one in its workflow. You can use them to add any metadata or technical values the engine needs to read directly from the narrative design. The image above shows an example component from the card game created by the Arcweave team for [Arcjam 2024: The Card Game Challenge](https://itch.io/jam/arcjam-2024-card-game-challenge). ![A short segment of an Arcweave flowchart showing 4 elements having one attached component each. The components signify the speaker of each line.](https://docs.arcweave.com/assets/component-attachments.B9IlVJXQ.png) Attach components to elements in your story flow for visual reference or to trigger in-game events. In the dialogue extract above, components are used to indicate the speaker of each line. ## Test and debug as you write Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Writers & Designers > Test and debug as you write ![Arcweave's Play Mode screen, with the Debugger sidebar open on the right showing the values of 3 variables.](https://docs.arcweave.com/assets/play-debug-demo.BbidGTts.png) Arcweave includes a built-in **Play Mode** for previewing your story. With it you can do the following: - Immediately playtest any segment of your project. - Track variable changes and story logic using the **Debugger**. - Run a prototype of your story with zero setup. - Customize the look and feel with the built-in **Style Editor**. - Share your prototype via a public or private link. ![Arcweave's Play Mode screen, with the Style Editor sidebar open on the right, showing a block of CSS code affecting the playthrough's appearance on the left: the option buttons are semi-transparent and the cover image is full screen.](https://docs.arcweave.com/assets/play-style-editor.cx55xf1r.png) > ✅ Play Mode helps you iterate quickly and catch logic errors early—before your story reaches development. ## Real-time collaboration Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Writers & Designers > Real-time collaboration Whether you're working solo or with a writing team, Arcweave keeps everyone in sync: - **Collaborate live** on the same project and see updates happen in real time. - Manage access by inviting collaborators as **editors** or **commenters**. - Leave **comments** on your boards and get notified of replies. ## From design to implementation Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Writers & Designers > From design to implementation Arcweave separates **creative design** from **technical development**. While you focus on the narrative, developers can transfer your story data via **JSON export** or use Arcweave's **[REST API](https://docs.arcweave.com/rest-api/overview)** for read and write access to project data in a Team workspace. This division of labor helps teams work in parallel and stay productive without bottlenecks. > ✅ Arcweave is ideal for visual novels, RPGs, narrative-driven games, educational tools, and more—anything where interactive storytelling is central. # Arcweave for Developers Source: https://docs.arcweave.com/introduction/whom-is-it-for/developers Section: Introduction > Whom is it for? Description: How Arcweave applies to the workflow of developers Arcweave may be designed with writers and designers in mind, but its structured outputs and integration tools ensure a smooth handoff to developers. Whether you're building a commercial game, an educational simulation, or a training environment, Arcweave helps your team separate creative development from technical implementation—while still giving you everything you need to turn branching stories into working systems. ## What changes for you Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Developers > What changes for you If you currently turn writers' scripts or spreadsheets into game data by hand, here's what changes when the narrative team works in Arcweave: | Without Arcweave | With Arcweave | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | You copy dialogue from documents into code, and again after every rewrite. | You [export](https://docs.arcweave.com/project-tools/export) structured data, or load it with the [Unity, Unreal, or Godot plugins](https://docs.arcweave.com/integrations/overview), and re-export when the story changes. | | You write a new parser for each writer's format. | Every project uses the same documented [JSON structure](https://docs.arcweave.com/integrations/json), so you write your import tools once. | | Writers ask you for a build to test a branch. | Writers test their own logic in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview) before it reaches you. | | Story conditions live in code that writers can't read. | Conditions are written in [Arcscript](https://docs.arcweave.com/project-items/arcscript) in the project, where writers and developers both see them. | | Moving content in and out of your pipeline is a manual step. | In Team workspaces, the [REST API](https://docs.arcweave.com/rest-api/overview) reads and writes project data from your own tools. | ## Export-ready structure Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Developers > Export-ready structure Arcweave projects can be exported in [structured JSON](https://docs.arcweave.com/integrations/json), providing you with: - Full story flow data: elements, connections, branches, jumpers - Variables and logic conditions - Component data (characters, items, etc.) and their attributes - References to attached assets (e.g. images, audio files) - Metadata for custom use in your runtime system You can treat Arcweave as a source of narrative truth and parse its output into Unity, Unreal, Godot—or any custom engine or scripting system you use. > ✅ Arcweave's JSON structure is stable and documented. You can write import tools once and reuse them across multiple projects. ## Smarter workflows Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Developers > Smarter workflows Arcweave offers more than just raw JSON exports. It provides complete [integration solutions and plugins](https://docs.arcweave.com/integrations/overview) for popular game engines, reducing the time spent on boilerplate integration work and enabling faster iterations between teams. You minimize manual content updates in code, even as the narrative evolves. This reduces developer overhead while keeping the game logic tightly synced with the writing. ## Localization Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Developers > Localization In Team workspaces, Arcweave includes [localization tools](https://docs.arcweave.com/project-tools/localization) for multi-language projects. Teams can add languages, translate elements, connection labels, and component names, track translation status, import localized spreadsheets, and choose which language data to include in JSON, spreadsheet, image, PDF, and engine exports. ## Story versioning Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Developers > Story versioning In Team workspaces, the [History](https://docs.arcweave.com/project-tools/history) panel lets teams inspect previous project states and restore work when needed, reducing the need to build in-house recovery tooling around every content iteration. ## API access Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Developers > API access For custom integrations, Arcweave provides a **[REST API](https://docs.arcweave.com/rest-api/overview)** with **read and write access** to projects in Team workspaces. You can: - Fetch the latest state of a project at runtime. - Build tools that read project data and send content updates back to Arcweave. - Import projects and create or update content such as boards, elements, branches, variables, components, attributes, and assets. - Automate workflows like previewing or regression testing against narrative logic. This is ideal for live environments, interactive installations, or collaborative pipelines where the narrative is still evolving while the platform is already in use. ## Clean collaboration Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Developers > Clean collaboration Arcweave allows your writing and design team to work independently from the implementation team, reducing bottlenecks and freeing up developers from creative iteration cycles. As a developer, you can: - Access the project directly, to inspect logic and structure. - Leave comments on boards, to flag technical concerns or integration questions. - Help define naming conventions or metadata structures in components for cleaner parsing. You don't need to learn Arcweave's design interface, but you'll appreciate how structured and readable the narrative system is. ## Migrating to Arcweave Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Developers > Migrating to Arcweave Already working in another tool? Arcweave supports a range of workflows, and it's easy to incorporate it into your process. We can help you: - Import data and convert story structures - Integrate Arcweave into your development pipeline - Maintain consistency with your current tools > ✅ Every project is different. [Contact us](https://arcweave.com/contact) to discuss a tailored migration solution for your team. # Arcweave for Team Leaders Source: https://docs.arcweave.com/introduction/whom-is-it-for/team-leaders Section: Introduction > Whom is it for? Description: How Arcweave applies to the workflow of team leaders If you're leading a narrative design team, game studio, or any collaborative creative effort, Arcweave provides the structure and tools to manage your team efficiently, while keeping the creative workflow seamless. This guide introduces the capabilities you have as a **workspace owner** and team leader in Arcweave. ## What changes for you Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Team Leaders > What changes for you If your team's story is spread across documents, spreadsheets, chat threads, and a game build, here's what changes when it lives in Arcweave: | Without Arcweave | With Arcweave | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | The story is split across several tools, and nobody is sure which copy is current. | Writing, logic, and assets live in one shared [project](https://docs.arcweave.com/workspaces/projects) that everyone edits in real time. | | Feedback arrives in chat or email, away from the content it refers to. | Reviewers leave [comments](https://docs.arcweave.com/project-items/comments) on the boards and mention teammates, who get notified. | | Giving someone access means sharing files and hoping they don't break them. | You invite people with a [role](https://docs.arcweave.com/workspaces/roles), such as editor or commenter, and add outside collaborators as guests on specific projects. | | Writers wait on developers to test the story, and developers wait on writers. | Writers playtest in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview) while developers work from the exported data, so both sides move in parallel. | | A bad edit means digging through backups. | In Team workspaces, [History](https://docs.arcweave.com/project-tools/history) lets you view and restore earlier versions of a project. | ## Management Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Team Leaders > Management Arcweave's [workspaces](https://docs.arcweave.com/workspaces/overview) are the foundation of collaboration and team management. ![The People section of an Arcweave workspace, showing the Invitations tab, where two invitations are pending.](https://docs.arcweave.com/assets/people-invitations.C6Og3ZAS.png) As a workspace owner, you have full control over your team's environment and permissions. You can: - Invite team members to the workspace. - Assign, change, or revoke member roles and permissions. - Maintain a clear overview of your team's projects—you can create, view, comment on, edit, and delete any of them. - Manage workspace settings and billing. > ✅ Owners have full administrative rights, including role assignments and all project management tasks. ## Efficiency Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Team Leaders > Efficiency Arcweave helps reduce overhead by consolidating writing, logic design, collaboration, and asset management into a **single unified tool**. This eliminates the need for multiple apps or custom integrations, cutting down on both licensing costs and coordination time. ## Autonomy Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Team Leaders > Autonomy Each department—writing, design, development—can work **comfortably and independently** within Arcweave. Writers don't need to wait on developers for logic testing, and developers don't have to manually track narrative updates. This separation of concerns speeds up production, minimizes miscommunication, and helps everyone stay aligned without interrupting each other's flow. ## Choosing the right plan Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Team Leaders > Choosing the right plan Workspaces come in various plans (see Arcweave's [Pricing](https://arcweave.com/pricing) page), and you can configure the number of seats to match your team's size and requirements. For detailed guidance on subscription management and different upgrade scenarios, see [Manage your subscriptions](https://docs.arcweave.com/introduction/quick-tour/manage-subscriptions). Select the plan that provides the right balance of features, assets storage, and tools for collaboration & integration. Each plan is designed to grow with your team, ensuring you only pay for what you need while maintaining the flexibility to expand as your projects evolve. ## Pipeline automation Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Team Leaders > Pipeline automation If your studio has an established production pipeline, Arcweave can become part of it. The **Team** plan includes access to the [REST API](https://docs.arcweave.com/rest-api/overview), which lets your scripts and tools read and write project data programmatically. With the REST API, you can: - **Import** content into Arcweave from your own tools and sources, instead of entering it by hand. - **Export** project data on demand and feed it into your build process, game engine, or other tools. - **Keep working in Arcweave** while your pipeline stays in sync, so writers and designers don't have to wait for manual import and export steps. Automation reduces repetitive work and the errors that come with it, and it keeps your team focused on the narrative instead of on moving files around. > ℹ️ REST API access is available only in **Team** workspaces. See [workspace billing plans](https://docs.arcweave.com/workspaces/billing-plans). ## Customized solutions Context: Arcweave docs > Introduction > Whom is it for? > Arcweave for Team Leaders > Customized solutions If you have questions or want to explore how Arcweave can fit your team's unique workflow, [contact us](https://arcweave.com/contact). We'll be happy to help you tailor Arcweave to your team's needs. # Quick tour of Arcweave Source: https://docs.arcweave.com/introduction/quick-tour/overview Section: Introduction Description: Start the Arcweave quick tour by creating an account, exploring The Castle sample project, and meeting the main tools Welcome! This quick tour is designed to give you a fast and hands-on introduction to Arcweave, so you can immediately see how it can power your interactive projects. ![Arcweave's project screen open at the Interactive Fiction Example project.](https://docs.arcweave.com/assets/project-general.Cw-i8z_y.png) In just a few minutes, you'll learn how to create your account, explore a sample project (_The Castle_—pictured above), and get a first look at the tools that will help you build your own interactive experiences. All you need is a browser and an internet connection. ## What the tour covers Context: Arcweave docs > Introduction > Quick tour of Arcweave > What the tour covers The tour has short stops, in the order you'll likely need them: 1. [Create your free account](https://docs.arcweave.com/introduction/quick-tour/create-account): Sign up with your email or Google account. 1. [Arcweave interface](https://docs.arcweave.com/introduction/quick-tour/ui): Find your way around the Projects section, the board area, the left sidebar, and the top and bottom menus. 1. [Flowchart analysis](https://docs.arcweave.com/introduction/quick-tour/flowchart): See how _The Castle_ is built from elements, connections, jumpers, and branches, with attached assets and components. 1. [Play Mode](https://docs.arcweave.com/introduction/quick-tour/play-mode): Play the story as a player would. 1. [AI tools](https://docs.arcweave.com/introduction/quick-tour/ai): Meet the Design Assistant, Element Generator, Element Enhancer, and Image Generator. 1. [Collaboration](https://docs.arcweave.com/introduction/quick-tour/collaboration): Work with teammates and guests in real time, and use notes and comments. 1. [Share & export](https://docs.arcweave.com/introduction/quick-tour/share-export): Share your project to collaborate or to let others play it, and export it to other formats and game engines. 1. [Your workspace](https://docs.arcweave.com/introduction/quick-tour/workspace): Invite people to your workspace and change its settings. 1. [Manage subscriptions](https://docs.arcweave.com/introduction/quick-tour/manage-subscriptions): Upgrade a workspace and add users to it. > ✅ Short on time? Stops 2–4 show how a story is built and played. Stops 6–9 matter once you work with a team or need a paid plan. If terms like _element_ or _branch_ are new to you, read [Core concepts](https://docs.arcweave.com/introduction/core-concepts) first, or keep it open as you go. > ✅ Start by reading how to [create your Arcweave account](https://docs.arcweave.com/introduction/quick-tour/create-account), on the next page. If you already have an Arcweave account, jump to exploring the [Arcweave interface](https://docs.arcweave.com/introduction/quick-tour/ui). # Create your free account Source: https://docs.arcweave.com/introduction/quick-tour/create-account Section: Introduction > Quick tour Description: Sign up for a free Arcweave account with email or Google and verify your email address > ✅ Creating an Arcweave account is free—now and forever. No strings attached. To create an Arcweave account: 1. Visit the [Arcweave sign-up page](https://arcweave.com/register). 1. Enter your first name, last name, email, and a secure password, then click **Create account**. 1. Check your inbox for our verification email. 1. Click the link in the email to verify your account. Arcweave signs you in and opens your workspace. You can also select **Continue with Google** on the sign-up page to create your account with Google. Google sign-up does not require the email verification step. > ℹ️ Didn't receive the email? Check your spam folder. Still no luck? Reach out to us on Arcweave's [Discord](https://discord.gg/atVXxAK). # Arcweave interface Source: https://docs.arcweave.com/introduction/quick-tour/ui Section: Introduction > Quick tour Description: Quick tour of the Arcweave interface, including the Projects section, board area, left sidebar, top menu, and bottom menu Arcweave's interface is clean and intuitive. This section provides a quick tour of the main areas you'll interact with while working on your projects. ## Projects section Context: Arcweave docs > Introduction > Quick tour > Arcweave interface > Projects section ![The Projects section of the Arcweave workspace environment, showing the thumbnail of the default, sample project.](https://docs.arcweave.com/assets/projects-page-free.D570iK2y.png) After logging in, you'll land on the **Projects** section of your first (free) **workspace**. You'll see a sample project titled _The Castle._ This is Arcweave's _Interactive Fiction Example,_ one of its built-in project templates. Click on the project thumbnail to open it. > ✅ Arcweave provides a handful of project templates you can study and expand. Just click **+ New Project** to explore them! > ℹ️ Revisit previous sections on [projects](https://docs.arcweave.com/introduction/what-is-arcweave#projects) and [workspaces](https://docs.arcweave.com/introduction/what-is-arcweave#workspaces) if you need a reminder of what they are and what they enable you to do. ## Inside the project Context: Arcweave docs > Introduction > Quick tour > Arcweave interface > Inside the project ![The Arcweave project environment.](https://docs.arcweave.com/assets/castle-intro.bAzTbsFV.png) Once inside _The Castle,_ you can see the main parts of Arcweave's interface: ## Current board area Context: Arcweave docs > Introduction > Quick tour > Arcweave interface > Current board area ![The Arcweave project environment with an orange rectangle highlighting the current board area.](https://docs.arcweave.com/assets/castle-open-board.CBDsR0ZS.png) The largest area of the window is taken up by the **current board**, where a portion of its **flowchart** is visible. To explore more of the flowchart do one of the following: - **Zoom in and out**: - On touch devices: Pinch in and out. - On desktop: Use your mouse scroll wheel, or pinch on your trackpad. - **Pan**: - On touch devices: Drag empty board space with one finger. - On desktop: Hold SPACE and drag with your mouse, drag with your mouse's middle button, or scroll with two fingers on your trackpad. - Click the **Fit to screen** icon (bottom right): This automatically scales the board to fit your window. > ℹ️ How Arcweave interprets scrolling depends on the [Input device](https://docs.arcweave.com/project-tools/settings#input-device) setting in **Project Settings**. ## Left sidebar Context: Arcweave docs > Introduction > Quick tour > Arcweave interface > Left sidebar ![The Arcweave project environment with an orange rectangle highlighting the left sidebar.](https://docs.arcweave.com/assets/castle-sidebar.DNtBNczK.png) The sidebar on the left side of your window provides access to important items of your project: - **Components** (top half, tab): Define reusable story objects like characters, items, or locations. - **Assets** (top half, tab): Upload and manage image, audio, and video files. - **Boards** (bottom half): Organize your narrative into separate canvases for different scenes or sections. This is where you'll find the current board as well, titled _Main Board._ - **Global variables** (bottom): Set variables to use across your project and drive logic and conditions. Feel free to explore each sidebar section to get a sense of how you can manage your project and its content. ## Top menu Context: Arcweave docs > Introduction > Quick tour > Arcweave interface > Top menu ![The Arcweave project environment with an orange rectangle highlighting the top menu.](https://docs.arcweave.com/assets/castle-top-menu.DQtyWvSz.png) The top menu provides access to key [project tools](https://docs.arcweave.com/project-tools/overview). On the left, you'll find [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview), [Project Settings](https://docs.arcweave.com/project-tools/settings), [Export](https://docs.arcweave.com/project-tools/export), and [Share](https://docs.arcweave.com/project-tools/share). On the right, you can see active collaborators and access the [Design Assistant](https://docs.arcweave.com/project-tools/ai-features/design-assistant), [History](https://docs.arcweave.com/project-tools/history), [Localization](https://docs.arcweave.com/project-tools/localization), [Comments](https://docs.arcweave.com/project-items/comments), and [Search](https://docs.arcweave.com/project-tools/search), depending on your plan and permissions. On narrow screens, these actions are grouped into dropdown menus on the left and right. Play Mode and your profile remain directly accessible in the top bar. ## Bottom menu Context: Arcweave docs > Introduction > Quick tour > Arcweave interface > Bottom menu ![The Arcweave project environment with an orange rectangle highlighting the bottom menu.](https://docs.arcweave.com/assets/castle-bottom-menu.Cjn8g9lw.png) The bottom menu contains tools for creating [project items](https://docs.arcweave.com/project-items/overview) (on the left) and adjusting your board view with zooming and panning (on the right). On narrow screens, use the **+** button to expand the creation tools and the bottom-right chevron to expand the zoom and help tools. # Flowchart analysis Source: https://docs.arcweave.com/introduction/quick-tour/flowchart Section: Introduction > Quick tour Description: How Arcweave flowcharts work, with elements & attachments, connections, jumpers, and branches The heart of any Arcweave project is its **flowchart**, a visual representation of your story, with its branching flow, player choices, and logic. [Play Mode](https://docs.arcweave.com/introduction/quick-tour/play-mode) follows the structure of your flowchart and lets you prototype your project as a choice-based game. This section walks you through the key building blocks of the flowchart using _The Castle,_ the built-in example project in Arcweave. ## Elements & connections Context: Arcweave docs > Introduction > Quick tour > Flowchart analysis > Elements & connections ![Screenshot of Arcweave's UI demonstrating the example project's flowchart composed of story elements connected with connections. The elements are highlighted in orange rectangles.](https://docs.arcweave.com/assets/castle-elements.BNOtGi5V.png) In the screenshot above, notice how the example's main flowchart consists mostly of [elements](https://docs.arcweave.com/project-items/elements) linked together with arrow [connections](https://docs.arcweave.com/project-items/connections). You design your story so it progresses from element to element, as the player clicks on **options**. > ✅ You can use **keyboard shortcuts** to [navigate your project](https://docs.arcweave.com/project-tools/interface/keyboard-shortcuts#navigation-view) and [create connected elements](https://docs.arcweave.com/project-tools/interface/keyboard-shortcuts#element-creation-connection). ![Screenshot of Arcweave's UI focusing on two connections with labels, which have been highlighted in orange rectangles.](https://docs.arcweave.com/assets/castle-connection-labels.CE8hBUfX.png) Connections can have [labels](https://docs.arcweave.com/project-items/labels), as shown in the screenshot above. It is not mandatory, but it is the best way to write clear text for the player's options. Both elements and connection labels can include [Arcscript](https://docs.arcweave.com/project-items/arcscript), Arcweave's simple scripting language for story logic. Don't be surprised if you come across snippets of code, like the examples shown in the image below. ![Screenshot of Arcweave's UI demonstrating segments containing Arcscript code embedded in elements and connections.](https://docs.arcweave.com/assets/arcscript-segments.C7DrAHW_.png) ## Attached assets Context: Arcweave docs > Introduction > Quick tour > Flowchart analysis > Attached assets [Assets](https://docs.arcweave.com/project-items/assets/overview) allow you to prototype the interactive experience with rich audiovisual feedback. By attaching **images**, **audio**, and **video assets** to your flowchart's elements, they appear in [Play Mode](https://docs.arcweave.com/introduction/quick-tour/play-mode), when each element loads. ### Images Context: Arcweave docs > Introduction > Quick tour > Flowchart analysis > Attached assets > Images In _The Castle,_ many elements have an attached [image asset](https://docs.arcweave.com/project-items/assets/images) that serves as a [cover](https://docs.arcweave.com/project-items/elements#element-covers): a visual that spans the full width of the element, helping set the tone or context, as shown in the screenshot below. ![Screenshot of Arcweave's UI demonstrating an element with an image asset attached as its cover.](https://docs.arcweave.com/assets/castle-element-cover.BkZZOA6K.png) ### Audio Context: Arcweave docs > Introduction > Quick tour > Flowchart analysis > Attached assets > Audio Some elements can also include one or more [audio assets](https://docs.arcweave.com/project-items/assets/audio). These may be music clips, ambience tracks, or sound effects that play or stop when the flow reaches the element. ![Screenshot of Arcweave's UI demonstrating two elements with attached audio assets. The attached audio assets appear as a list at the bottom of each element.](https://docs.arcweave.com/assets/castle-element-audio.BKkOTOdh.png) ### Video Context: Arcweave docs > Introduction > Quick tour > Flowchart analysis > Attached assets > Video Finally, instead of an image, you can attach a [video asset](https://docs.arcweave.com/project-items/assets/video) to an element. The video occupies the same area an image would and, by default, begins playing when the element loads in Play Mode. You can change this in the video's [playback settings](https://docs.arcweave.com/project-items/assets/video#playback-behavior). ![Settings panel for a video asset attached to an Arcweave element. The video shows two oxen and is attributed to Matthias Groeneveld from Pixabay.](https://docs.arcweave.com/assets/assets-video-settings.D8zqS1lH.png) ## Attached components Context: Arcweave docs > Introduction > Quick tour > Flowchart analysis > Attached components Elements can also take [components](https://docs.arcweave.com/project-items/components) as attachments. Components are great for keeping information about your story objects organized. ![Screenshot of Arcweave's UI demonstrating a component attached to an element.](https://docs.arcweave.com/assets/castle-attached-component.BvVG52VX.png) In the screenshot above, the attached component represents one of the story's characters. Click the component to open it. ![Screenshot of Arcweave's UI demonstrating an opened component showing detailed information about a story character.](https://docs.arcweave.com/assets/castle-component.kRnEn2wd.png) When opening a component for editing, you can also add and edit its [attributes](https://docs.arcweave.com/project-items/attributes). > ✅ Components can be very useful when [integrating](https://docs.arcweave.com/integrations/overview) Arcweave with game engines. ## Jumpers Context: Arcweave docs > Introduction > Quick tour > Flowchart analysis > Jumpers [Jumpers](https://docs.arcweave.com/project-items/jumpers) let you connect elements that are either on different boards or too far apart on the same board. Use them to keep your flowchart tidy and easy to follow. ![Screenshot of Arcweave's UI demonstrating a jumper in the board, highlighting it in an orange rectangle. Two orange arrows indicate the destination board and the jumper's target element, in the UI's left sidebar.](https://docs.arcweave.com/assets/intro-jumpers.CLNFicYh.png) In the screenshot above, the jumper sends the flow to an element that is in the board Crusader Dialogue, as shown on the [sidebar](https://docs.arcweave.com/introduction/quick-tour/ui#left-sidebar). ## Branches Context: Arcweave docs > Introduction > Quick tour > Flowchart analysis > Branches [Branches](https://docs.arcweave.com/project-items/branches) add logic to your flow. They route the story based on conditions using `if`, `elseif`, and `else`. This makes your narrative responsive to player actions or [variables](https://docs.arcweave.com/project-items/variables/overview): values the story remembers, such as whether the player has found a key. ![Screenshot of Arcweave's UI demonstrating a branch using if and else blocks. The branch comes after the element where the Crusader character tells the player "Only he who knows my name shall pass." The branch checks the condition "if the player has examined the painting."](https://docs.arcweave.com/assets/intro-branches.DnN04Vef.png) The screenshot above shows a branch in the example project, which includes an `if` and an `else` condition. # Play Mode Source: https://docs.arcweave.com/introduction/quick-tour/play-mode Section: Introduction > Quick tour Description: Quick tour of Play Mode, where you play through your story as a player would and use its top menu Arcweave includes a built-in **Play Mode** to simulate your interactive experience directly. ![An orange arrow pointing at the Play Mode button of an Arcweave project's top menu.](https://docs.arcweave.com/assets/play-button.Cx3qNU9M.png) While still in _The Castle,_ click the ▶️ **Play Mode** button in the top menu (left side, right after the project and current board name) to enter Play Mode. ![A split screen view of an Arcweave project and its Play Mode. The focus in both sides is the starting element, and it is clear that the connection's label (saying "Enter the castle") in the board corresponds to the Play Mode button with the same text.](https://docs.arcweave.com/assets/play-split.CKbt7P3b.png) Play Mode opens in a separate browser tab and **updates automatically** with any edits you make. If your screen size permits it, you can place the two browser tabs side by side for more control. ## Play Context: Arcweave docs > Introduction > Quick tour > Play Mode > Play You can now play through the example story. ![A split-screen view of an Arcweave project and its Play Mode, with both sides focusing on the starting element. Orange rectangles and arrows highlight how the element's cover becomes the featured image in Play Mode, and how the connection's label appears as an option button.](https://docs.arcweave.com/assets/play-split-arrows.Bffgc1CY.png) As the story flow moves from element to element, you'll notice the following: - The current element's **cover** appears as a prominent image above the **text content**. - The **connection labels** render as **option buttons** below the text. - The **audio attachments** play when their element loads. Click the option buttons to progress the story. ## Top menu Context: Arcweave docs > Introduction > Quick tour > Play Mode > Top menu Play Mode holds more features, but it's too early to go through them all. If you're feeling curious, explore its **top menu**, which includes the following. On desktop, the menu hides a few seconds after your cursor leaves it; hover near the top of the window to show it again. - **Restart**: Resets everything and restarts the story. - **Enter full screen**: Shows Play Mode in full screen. - **Share**: Lets you [share](https://docs.arcweave.com/project-tools/share) your project and control its public access. - **Audio**: Controls the [playback volume](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#control-audio-volume) of your project's audio. - **Localization**: Lets you [choose the story's language](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#choose-language) (Team workspaces only). - **Edit content**: Lets you [edit element and option text, as well as reorder option buttons](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#edit-content-in-play-mode) while playtesting. Changes are saved automatically. - **Style Editor**: Lets you [style](https://docs.arcweave.com/project-tools/play-mode/style-editor) Play Mode's appearance through direct CSS editing. - **Debug**: Opens the [Debugger](https://docs.arcweave.com/project-tools/play-mode/debugger), where you can inspect the current board, current element, and variable changes. **Edit content**, **Style Editor**, and **Debug** are available only to owners and editors. # Arcweave's AI tools Source: https://docs.arcweave.com/introduction/quick-tour/ai Section: Introduction > Quick tour Description: Quick tour of Arcweave's AI tools, including the Design Assistant, Element Generator, Element Enhancer, and Image Generator Arcweave includes a suite of AI-powered tools designed to assist your creative process. - [Design Assistant](https://docs.arcweave.com/project-tools/ai-features/design-assistant): Answers questions about your project and Arcweave, offers suggestions, and makes the changes you ask for, such as creating elements, connecting them, or reorganizing boards. - [Element Generator](https://docs.arcweave.com/project-tools/ai-features/element-generator): Generates the next element from any existing one, offering ideas and plot suggestions to inspire your story. - [Element Enhancer](https://docs.arcweave.com/project-tools/ai-features/element-enhancer): Rewrites or improves an element based on your prompt, allowing you to edit content, adjust mood or style, and fix grammar errors. - [Image Generator](https://docs.arcweave.com/project-tools/ai-features/image-generator): Creates images from your prompts to enrich your prototypes with custom visuals. ![Screenshot of the Arcweave interface with the Design Assistant open, showing example questions like "Who is the story's antagonist?" and "How can the player discover the name?" with AI-generated replies.](https://docs.arcweave.com/assets/ai-design-assistant.Q5di2PoU.png) The above image shows an example of using the Design Assistant. To use AI tools, you need permission to edit the project, and each action consumes [AI credits](https://docs.arcweave.com/project-tools/ai-features/overview#monthly-ai-credits) from your workspace's monthly allowance. > ℹ️ You can [enable or disable all AI tools](https://docs.arcweave.com/project-tools/ai-features/overview#toggle-ai-features) in your workspace settings. Read the [AI tools overview](https://docs.arcweave.com/project-tools/ai-features/overview) for more information. # Collaboration Source: https://docs.arcweave.com/introduction/quick-tour/collaboration Section: Introduction > Quick tour Description: Quick tour of collaboration in Arcweave, with workspace members and guests, real-time co-editing, notes, and comments Arcweave is built for teams, keeping every member aligned throughout the creative process. Its collaboration features operate at two levels: - **Workspaces**: Manage members, guests, access levels, and permissions. - **Projects**: Co-create in real time, leave notes on boards, and exchange comments with your team. ## Workspaces Context: Arcweave docs > Introduction > Quick tour > Collaboration > Workspaces Arcweave's workspace tools let you control who has access to your projects and what they can do. It distinguishes between workspace **members** and **guests**, each with different access levels and permissions. ![The People section of Arcweave's workspace environment, showing the Members tab, with 3 users as members.](https://docs.arcweave.com/assets/people-members.CMM_gLcx.png) ### Members Context: Arcweave docs > Introduction > Quick tour > Collaboration > Workspaces > Members Members are users with workspace-wide access. ### Guests Context: Arcweave docs > Introduction > Quick tour > Collaboration > Workspaces > Guests Guests are users with access to one or more specific projects, without full workspace access. See [Your workspace](https://docs.arcweave.com/introduction/quick-tour/workspace) for details. ## Projects Context: Arcweave docs > Introduction > Quick tour > Collaboration > Projects Arcweave offers two in-project tools for team communication and feedback: notes and comments. ### Notes Context: Arcweave docs > Introduction > Quick tour > Collaboration > Projects > Notes ![Arcweave's project screen open at the Interactive Fiction Example project, highlighting the board's notes with orange rectangles.](https://docs.arcweave.com/assets/castle-notes.XC_xHnxw.png) **Notes** are colorful, rich text boxes you can place anywhere on a board — ideal for leaving context, flagging areas for review, or guiding collaborators through your project structure. > Read all about [notes](https://docs.arcweave.com/project-items/notes) under **Project Items**. ### Comments Context: Arcweave docs > Introduction > Quick tour > Collaboration > Projects > Comments ![An orange arrow pointing at the Comments icon, at the bottom menu of an Arcweave project.](https://docs.arcweave.com/assets/castle-comments.C04AIHDJ.png) For direct team communication, **comments** offer a more focused channel. Drag the **Comment** icon from the bottom menu onto any board area to place one. Comments support **replies** and **@mentions**, and the comments sidebar can [filter](https://docs.arcweave.com/project-items/comments#filters) them, for example to show only comments you are involved in. Users receive **email notifications** according to their [email notification settings](https://docs.arcweave.com/project-items/comments#email-notification-settings), which can include all comments, mentions and replies only, or none. > Read all about [comments](https://docs.arcweave.com/project-items/comments) under **Project Items**. # Share & export Source: https://docs.arcweave.com/introduction/quick-tour/share-export Section: Introduction > Quick tour Description: Quick tour of sharing projects with collaborators or viewers and exporting them to other formats and game engines Arcweave makes it easy to share your work with others to review and collaborate. ## Share to collaborate Context: Arcweave docs > Introduction > Quick tour > Share & export > Share to collaborate The simplest way to collaborate in Arcweave is by sharing just one project. > ℹ️ For advanced team management features like role control and workspace-wide visibility, see [Workspaces](https://docs.arcweave.com/introduction/quick-tour/workspace). (Next page) ![The Arcweave window showing an open project and its "Share" modal. The modal allows the user to invite more collaborators to the project and to configure the project's private or public state.](https://docs.arcweave.com/assets/share.Dygv2dx1.png) To collaborate with others on your project: 1. Click the **Share** button in the top menu. 2. Enter the email address of the person you want to invite. 3. Choose their role: **Commenter** or **Editor**. 4. Click **Invite**. Repeat these steps to invite more people. Inviting people requires the [**Manage memberships**](https://docs.arcweave.com/workspaces/roles#list-of-permissions) permission, which workspace owners have by default. In Pro and Team workspaces, the **Editor** role is marked **Billable**, because guest editors occupy a paid [seat](https://docs.arcweave.com/workspaces/billing-plans#seats). Commenters are free. Your collaborators will receive an email invitation to join the project. Once they accept, you'll be able to work together in real time. Your updates will sync instantly across all team members. To point a collaborator to a specific board or item, use its **Copy link** menu action. The link opens that destination in the language you are currently viewing. See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position) for supported items and menu locations. ## Share to view & play Context: Arcweave docs > Introduction > Quick tour > Share & export > Share to view & play You can generate a public, **read-only link** to share your project externally: 1. Click the **Share** button in the top menu. 2. In the dropdown next to **Anyone with the link**, choose one of the following: - **Can play only**: Allows people to play your project without viewing its design. - **Can view & play**: Also grants read-only access to the project's design: its boards, components, and variables. 3. Click **copy link** under **Anyone with the link** to copy the project's link. ![Arcweave's project screen having the Share modal open](https://docs.arcweave.com/assets/share-public.-msafp79.png) This makes it easy to share progress with testers or clients without inviting them as collaborators. It also lets you distribute your project in a playable form while keeping the design private. > ✅ You can also [embed your project's Play Mode in HTML](https://docs.arcweave.com/project-tools/share#embed-play-mode-in-html), allowing users to play it in its own window on a webpage. ## Export Context: Arcweave docs > Introduction > Quick tour > Share & export > Export Arcweave supports multiple export formats to help you share, present, or integrate your narrative data into other platforms and game engines. ![The Arcweave window showing an open project and its "Export" modal currently open at the "Engine" tab, showing options for Export for Godot, Unity and Unreal. There is also a checkbox for including the project assets in the exported zip file.](https://docs.arcweave.com/assets/export_engine.BesxZF0i.png) To export your project: 1. Click the **Export project** icon in the top menu. 2. Choose from the available formats: - **JSON**: Fully structured data for integration into any platform. - **Spreadsheet**: Your project's data as CSV files or, in Pro/Team workspaces, an XLSX file, for review, analysis, or translation. - **Image**: Printable version of your project's boards for presentations or reviews. - **Engine**: JSON exports that work with our official Unity, Unreal Engine, and Godot Engine [integrations](https://docs.arcweave.com/integrations/overview). - **Markdown**: A text document of your story, for proofreading or sharing dialogue with voice actors (Pro/Team workspaces only). - **PDF**: Lossless printable version of your project's boards (Pro/Team workspaces only). - **Backup**: Save your project on your drive as a backup (Pro/Team workspaces only). These export formats make it easy to adapt your Arcweave project to different workflows. > ℹ️ You can bring exported JSON files, and backup files in Pro/Team workspaces, back into Arcweave by [importing projects](https://docs.arcweave.com/workspaces/projects#import-projects) in your workspace. > ✅ To **automate import and export** as part of your pipeline, use the [REST API](https://docs.arcweave.com/rest-api/overview) (Team workspaces only). # Your workspace Source: https://docs.arcweave.com/introduction/quick-tour/workspace Section: Introduction > Quick tour Description: Quick tour of Arcweave workspaces, including inviting workspace users and changing workspace settings As mentioned at the beginning of this tour, upon creating your Arcweave account you also get your first **workspace**. [Workspaces](https://docs.arcweave.com/workspaces/overview) are collaborative spaces that hold your projects and allow your team to work efficiently. ## Workspace users Context: Arcweave docs > Introduction > Quick tour > Your workspace > Workspace users In the [People](https://docs.arcweave.com/workspaces/people) section of your workspace, you can see all its users. A workspace's users can be of the following kinds. ### Workspace members Context: Arcweave docs > Introduction > Quick tour > Your workspace > Workspace users > Workspace members **Members** are users with workspace-wide access: - Workspace owners - Workspace editors - Workspace commenters - Members with [custom roles](https://docs.arcweave.com/workspaces/roles#add-new-roles) (Team workspaces only) ![The People section of Arcweave's workspace environment, showing the Members tab, with 3 users as members.](https://docs.arcweave.com/assets/people-members.CMM_gLcx.png) ### Workspace guests Context: Arcweave docs > Introduction > Quick tour > Your workspace > Workspace users > Workspace guests **Guests** are users with access to one or more specific projects, without full workspace access: - Project editors - Project commenters ![The People section of Arcweave's workspace environment, showing the Guests tab, with 4 users as guests.](https://docs.arcweave.com/assets/people-guests.e-v37mc2.png) ## Workspace settings Context: Arcweave docs > Introduction > Quick tour > Your workspace > Workspace settings To navigate your workspace's settings, you must exit _The Castle._ Click the **Workspace** icon at the very top left of your Arcweave window, in your browser, to return to the **Projects** page of your workspace. Workspaces, their pages, and their settings will be thoroughly analyzed in the [Workspaces](https://docs.arcweave.com/workspaces/overview) section of this documentation. # Manage your subscriptions Source: https://docs.arcweave.com/introduction/quick-tour/manage-subscriptions Section: Introduction > Quick tour Description: Common subscription scenarios, such as upgrading a Basic or Pro workspace and adding users to a workspace This page provides a first glance on managing your workspaces and subscription changes, with links to the relevant pages. > ✅ For a detailed overview of subscription options and practical examples (including how to change plans and adjust the number of users), visit [Workspace plans](https://docs.arcweave.com/workspaces/billing-plans) in the **Workspaces** section of this documentation. ## Arcweave subscriptions Context: Arcweave docs > Introduction > Quick tour > Manage your subscriptions > Arcweave subscriptions Arcweave [accounts](https://docs.arcweave.com/account/overview) are free. An Arcweave account can be associated with any number and combination of workspaces, each of which has its own subscription. Arcweave workspaces can fall under one of the following subscription plans: - **Basic**: Free workspace with content and feature limitations. - **Pro**: Removes most limitations and increases the [upload size limit](https://docs.arcweave.com/project-items/assets/overview#asset-upload-limits). - **Team**: Unlocks all features and further increases the upload size limit. To compare the three workspace types, see **Workspace comparison** on the [Workspace plans](https://docs.arcweave.com/workspaces/billing-plans#workspace-comparison) or visit the [Pricing page](https://arcweave.com/pricing) on Arcweave's website. ## Upgrade from Basic Context: Arcweave docs > Introduction > Quick tour > Manage your subscriptions > Upgrade from Basic As your projects and teams grow, it is likely that a Basic workspace will no longer meet your needs; the plan is designed for small-scale use and early exploration. Upgrading ensures you have room to scale your content and unlock essential workflow tools. To upgrade your Basic workspace see [Workspace plans](https://docs.arcweave.com/workspaces/billing-plans) > [Upgrade Basic](https://docs.arcweave.com/workspaces/billing-plans#upgrade-basic) in the **Workspaces** section of this documentation. ## Upgrade from Pro Context: Arcweave docs > Introduction > Quick tour > Manage your subscriptions > Upgrade from Pro The Pro plan unlocks most of Arcweave's tools, but a Team workspace offers access to the advanced features of [history](https://docs.arcweave.com/project-tools/history), [localization](https://docs.arcweave.com/project-tools/localization), [REST API access to read and write project data](https://docs.arcweave.com/workspaces/api), and [custom workspace roles](https://docs.arcweave.com/workspaces/roles#add-new-roles). To upgrade your Pro workspace to Team see [Workspace plans](https://docs.arcweave.com/workspaces/billing-plans) > [Upgrade Pro to Team](https://docs.arcweave.com/workspaces/billing-plans#upgrade-pro-to-team) in the **Workspaces** section of this documentation. ## Add workspace users Context: Arcweave docs > Introduction > Quick tour > Manage your subscriptions > Add workspace users You can add new users to your workspace at any time and see all of them in the workspace's [People](https://docs.arcweave.com/workspaces/people) section, under **Members** and **Guests**. ![The People section of Arcweave's workspace environment, showing the Members tab, with 3 users as members.](https://docs.arcweave.com/assets/people-members.CMM_gLcx.png) To add [workspace members](https://docs.arcweave.com/workspaces/roles#workspace-members) (workspace-level collaborators), navigate to **People** → **Add Member**, enter the collaborator's email, and assign a role. To add [workspace guests](https://docs.arcweave.com/workspaces/roles#workspace-guests) (project-level collaborators), open the relevant project, go to **Share**, and assign project-specific roles directly. > ✅ In a Basic workspace, adding users is for free. Basic workspace limitations apply regardless of the number of users. > ℹ️ Pro and Team workspaces are billed based on the number of their **billable seats**. # Glossary Source: https://docs.arcweave.com/introduction/glossary Section: Introduction Description: Glossary of Arcweave terms—such as board, element, connection, branch, jumper, component, attribute, variable, and Arcscript—with short definitions and links to their full pages Many Arcweave terms are everyday words with a specific meaning in Arcweave. This page defines each one in a sentence and links to its full documentation. For how the main building blocks fit together, see [Core concepts](https://docs.arcweave.com/introduction/core-concepts). ## A Context: Arcweave docs > Introduction > Glossary > A - **AI credits**: The monthly allowance your workspace spends when you use AI tools. See [Monthly AI credits](https://docs.arcweave.com/project-tools/ai-features/overview#monthly-ai-credits). - **Arcscript**: Arcweave's simple scripting language, used to change and check variables in branches, element content, and connection labels. See [Arcscript](https://docs.arcweave.com/project-items/arcscript). - **Arcscript segment**: A single line of Arcscript inside an element's content or a connection's label. See [Arcscript segments](https://docs.arcweave.com/project-items/arcscript#arcscript-segments). - **Asset**: An image, audio, or video file you upload to a project. See [Assets](https://docs.arcweave.com/project-items/assets/overview). - **Attribute**: A labeled piece of data stored in a board, component, or element, such as a character's age. See [Attributes](https://docs.arcweave.com/project-items/attributes). ## B Context: Arcweave docs > Introduction > Glossary > B - **Board**: A canvas where you draw part of your story as a flowchart. A project can have many boards. See [Boards](https://docs.arcweave.com/project-items/boards). - **Board folder**: A folder that groups boards in the project's **Boards** section. See [Board folders](https://docs.arcweave.com/project-items/boards#board-folders). - **Board variable**: A variable stored as an attribute on a board and used in Arcscript as `board_id.variable_id`. See [Board variables](https://docs.arcweave.com/project-items/variables/board). - **Branch**: A board item that chooses which path the story takes, using `if`, `elseif`, and `else` conditions. See [Branches](https://docs.arcweave.com/project-items/branches). ## C Context: Arcweave docs > Introduction > Glossary > C - **Comment**: A message thread that workspace members and guests leave on a board to discuss the project. Comments aren't part of the story. See [Comments](https://docs.arcweave.com/project-items/comments). - **Component**: A reusable story object, such as a character, location, or item. Components don't sit on boards; you attach them to elements or mention them in text. See [Components](https://docs.arcweave.com/project-items/components). - **Component variable**: A variable stored as an attribute on a component and used in Arcscript as `component_id.variable_id`. See [Component variables](https://docs.arcweave.com/project-items/variables/component). - **Connection**: An arrow from an element or branch to the next item (an element, branch, or jumper), setting the order of the story. See [Connections](https://docs.arcweave.com/project-items/connections). - **Cover**: The image shown at the top of an element or component. Elements can also use a video. See [Element covers](https://docs.arcweave.com/project-items/elements#element-covers). - **Custom ID**: The name you use to refer to a board, component, or attribute in Arcscript. See [Custom ID](https://docs.arcweave.com/project-items/components#custom-id). ## D Context: Arcweave docs > Introduction > Glossary > D - **Debugger**: A Play Mode panel where project owners and editors track variables while playtesting. See [Debugger](https://docs.arcweave.com/project-tools/play-mode/debugger). - **Design Assistant**: Arcweave's AI assistant. It answers questions about your project and makes changes you ask for. See [Design Assistant](https://docs.arcweave.com/project-tools/ai-features/design-assistant). ## E Context: Arcweave docs > Introduction > Glossary > E - **Element**: A box on a board that holds one moment of your story, such as a scene or a line of dialogue, in a title and content. See [Elements](https://docs.arcweave.com/project-items/elements). - **Export**: Downloading your project's data in another format, such as JSON, a spreadsheet, PDF, or game engine files. See [Export](https://docs.arcweave.com/project-tools/export). ## F Context: Arcweave docs > Introduction > Glossary > F - **Flowchart**: Your story drawn on a board as boxes (elements) joined by arrows (connections). See [Flowchart analysis](https://docs.arcweave.com/introduction/quick-tour/flowchart). ## G Context: Arcweave docs > Introduction > Glossary > G - **Global variable**: A variable that belongs to the whole project rather than to a board or component. See [Global variables](https://docs.arcweave.com/project-items/variables/global). - **Guest**: A person invited to specific projects without joining the workspace. See [Workspace guests](https://docs.arcweave.com/workspaces/roles#workspace-guests). ## H Context: Arcweave docs > Introduction > Glossary > H - **History**: The record of your project's previous versions, which you can view and restore. See [History](https://docs.arcweave.com/project-tools/history). ## J Context: Arcweave docs > Introduction > Glossary > J - **Jumper**: A shortcut on a board. When the story reaches a jumper, it continues at the jumper's target element, on the same board or another one. See [Jumpers](https://docs.arcweave.com/project-items/jumpers). ## L Context: Arcweave docs > Introduction > Glossary > L - **Label**: Text on a connection. In Play Mode, it becomes the text of the option the player clicks. See [Labels](https://docs.arcweave.com/project-items/labels). - **Localization**: Translating your project into other languages with Arcweave's built-in tools. See [Localization](https://docs.arcweave.com/project-tools/localization). ## M Context: Arcweave docs > Introduction > Glossary > M - **Member**: A person who belongs to a workspace and can access its projects, with permissions set by their role. See [Workspace members](https://docs.arcweave.com/workspaces/roles#workspace-members). - **Mention**: A link to a component or board inside rich text, created by typing `@`. See [Mentions](https://docs.arcweave.com/project-tools/mentions). ## N Context: Arcweave docs > Introduction > Glossary > N - **Note**: A sticky note on a board for ideas, instructions, or reminders. Notes aren't part of the story. See [Notes](https://docs.arcweave.com/project-items/notes). ## O Context: Arcweave docs > Introduction > Glossary > O - **Option**: A choice the player clicks in Play Mode. Options come from the current element's outgoing connections; a connection's label is the option's text. See [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview#breakdown). ## P Context: Arcweave docs > Introduction > Glossary > P - **Play Mode**: Arcweave's built-in player, where you play your project as a choice-based game. See [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview). - **Project**: One story or game, with its boards, components, assets, and variables. See [Projects](https://docs.arcweave.com/workspaces/projects). - **Project template**: A ready-made project to start from, such as the _Interactive Fiction Example_ (_The Castle_). See [Project templates](https://docs.arcweave.com/workspaces/projects#project-templates). ## R Context: Arcweave docs > Introduction > Glossary > R - **Role**: A set of permissions, such as Owner, Editor, or Commenter, that decides what a person can do in a workspace or project. See [Workspace roles](https://docs.arcweave.com/workspaces/roles). ## S Context: Arcweave docs > Introduction > Glossary > S - **Starting element**: The element where Play Mode begins the story. See [Set Play Mode start](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#set-play-mode-start). ## T Context: Arcweave docs > Introduction > Glossary > T - **Target element**: The element a jumper points to. See [Jumpers](https://docs.arcweave.com/project-items/jumpers). ## V Context: Arcweave docs > Introduction > Glossary > V - **Variable**: A value the story remembers and can change during play, such as whether the player has found a key. Variables can be global, board, or component variables. See [Variables](https://docs.arcweave.com/project-items/variables/overview). - **Visitor**: Someone who views a public project or its Play Mode through a link, without needing an Arcweave account. See [Project visitors](https://docs.arcweave.com/workspaces/roles#project-visitors). ## W Context: Arcweave docs > Introduction > Glossary > W - **Workspace**: Your team's space in Arcweave. It holds projects and the people who work on them, and has its own plan (Basic, Pro, or Team). See [Workspaces](https://docs.arcweave.com/workspaces/overview). # Arcweave tutorials Source: https://docs.arcweave.com/tutorials/overview Section: Tutorials Description: Tutorials in video and text introducing you to Arcweave's core and advanced features and integrations This collection of tutorials is designed to: - Help beginners get started. - Support advanced users in solving specific design and narrative challenges. This section includes the following tutorials: - [Basic Arcweave](https://docs.arcweave.com/tutorials/basic/overview): Ease into mastering Arcweave's core features, progressing towards more advanced techniques and logic workflows. - [Style Editor](https://docs.arcweave.com/tutorials/style-editor/overview): Learn how to use Arcweave's [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor) to customize and style your story with CSS. - **Game engine integration**: Follow step-by-step instructions to integrate Arcweave with your game engine of choice: - [Unity](https://docs.arcweave.com/tutorials/unity/overview) - [Unreal Engine](https://docs.arcweave.com/tutorials/unreal/overview) - [Godot Engine](https://docs.arcweave.com/tutorials/godot/overview). - [AI tools](https://docs.arcweave.com/tutorials/ai-tools/overview): Explore Arcweave's AI-powered tools. > ✅ In the **REST API** section you can find a short tutorial on how to [make your first write](https://docs.arcweave.com/rest-api/overview#make-your-first-write) using Arcweave's REST API. This feature is available in Team workspaces only. # Basic Arcweave tutorial Source: https://docs.arcweave.com/tutorials/basic/overview Section: Tutorials Description: A beginner's essential, this series of text and video tutorials covers Arcweave's core features This collection of tutorials is designed to help beginners get started with Arcweave's core features and to guide them toward mastering more advanced techniques and logic workflows. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) or in the embed window below, while you can explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). Embedded content: https://arcweave.com/embed/Qz0PXOZ0Ya/play ## Tutorial contents Context: Arcweave docs > Tutorials > Basic Arcweave tutorial > Tutorial contents 1. [Arcweave overview](https://docs.arcweave.com/tutorials/basic/pt-1) 2. [Your first project](https://docs.arcweave.com/tutorials/basic/pt-2) 3. [Format text](https://docs.arcweave.com/tutorials/basic/pt-3) 4. [Play Mode functionalities](https://docs.arcweave.com/tutorials/basic/pt-4) 5. [Components & icons](https://docs.arcweave.com/tutorials/basic/pt-5) 6. [Mentions](https://docs.arcweave.com/tutorials/basic/pt-6) 7. [Notes](https://docs.arcweave.com/tutorials/basic/pt-7) 8. [Image assets](https://docs.arcweave.com/tutorials/basic/pt-8) 9. [Jumpers](https://docs.arcweave.com/tutorials/basic/pt-9) 10. [Global variables](https://docs.arcweave.com/tutorials/basic/pt-10) 11. [Branches](https://docs.arcweave.com/tutorials/basic/pt-11) 12. [Text with logic](https://docs.arcweave.com/tutorials/basic/pt-12) 13. [Functions show & roll](https://docs.arcweave.com/tutorials/basic/pt-13) 14. [Share & export](https://docs.arcweave.com/tutorials/basic/pt-14) 15. [Polish the project](https://docs.arcweave.com/tutorials/basic/pt-15) 16. [Import & export project](https://docs.arcweave.com/tutorials/basic/pt-16) 17. [More project features](https://docs.arcweave.com/tutorials/basic/pt-17) 18. [Comments](https://docs.arcweave.com/tutorials/basic/pt-18) 19. [Function visits](https://docs.arcweave.com/tutorials/basic/pt-19) 20. [Advanced connections & labels](https://docs.arcweave.com/tutorials/basic/pt-20) 21. [Audio assets](https://docs.arcweave.com/tutorials/basic/pt-21) # Basic Arcweave tutorial | Part 1: Arcweave overview Source: https://docs.arcweave.com/tutorials/basic/pt-1 Section: Tutorials > Basic Arcweave Description: A short overview of the Arcweave project environment in text and video formats Welcome to the first part of the Arcweave Basics tutorial series. On this page, we'll use the [Interactive Fiction Example](https://docs.arcweave.com/workspaces/projects#project-templates) as a walkthrough of Arcweave's environment. We will see our first items and features: [boards](https://docs.arcweave.com/project-items/boards), [elements](https://docs.arcweave.com/project-items/elements), and [connections](https://docs.arcweave.com/project-items/connections), as well as the [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview), where you run your project as a choice-based game. ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 1: Arcweave overview > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=Dfm6dKQH3I0 > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ On this page we'll study the **Interactive Fiction Example** (aka _The Castle)._ On the following pages, we will be building a project step-by-step. You can play that project's finished version [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Open the project Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 1: Arcweave overview > Open the project The project template called **Interactive Fiction Example** is a great starting point for exploring Arcweave's features before building your own. ![The Projects section of the Arcweave workspace environment, showing the thumbnail of the default, sample project.](https://docs.arcweave.com/assets/projects-page-free.D570iK2y.png) If your workspace does not have this project (its title is _The Castle),_ you can recreate it: 1. Go to the workspace's **Projects** section. 2. Click the **+ New Project** button. 3. Select the **Interactive Fiction Example** template from the menu. ![The Projects section of an Arcweave workspace, with the "Create project" modal open, showing the available project templates.](https://docs.arcweave.com/assets/project-templates.cASA2VSk.png) ## Project environment Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 1: Arcweave overview > Project environment The Arcweave interface is divided into two main areas: the **Board** and the **Sidebar**. ### Current board Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 1: Arcweave overview > Project environment > Current board The Board is your main workspace. ![The Arcweave project environment with an orange rectangle highlighting the current board area.](https://docs.arcweave.com/assets/castle-open-board.CBDsR0ZS.png) It displays your story as a **diagram**, where **elements** (the building blocks of your narrative) are connected to each other via labeled **connections**. ### Sidebar Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 1: Arcweave overview > Project environment > Sidebar The left sidebar sits alongside the current board. ![The Arcweave project environment with an orange rectangle highlighting the left sidebar.](https://docs.arcweave.com/assets/castle-sidebar.DNtBNczK.png) It gives you access to four key sections: - **Boards**: A list of all the boards you've created in your project. Complex projects can have multiple boards to keep things organized. - **Components**: Entities you create to represent anything relevant to your game: characters, locations, items, and more. Components can be created once and reused across multiple diagrams. - **Assets**: A collection of all the images, audio, and videos you've uploaded to use in your project. - **Global variables**: This is where you define the global variables used throughout your project (e.g., for tracking player choices or game state). We'll cover each of these sections in detail in later tutorials. For now, it's enough to know where to find them. ## Play Mode Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 1: Arcweave overview > Play Mode Arcweave includes a built-in **Play Mode** that lets you run and test your project at any time. To enter Play Mode, click the **Play icon** at the top of the interface. ![An orange arrow pointing at the Play Mode button of an Arcweave project's top menu.](https://docs.arcweave.com/assets/play-button.Cx3qNU9M.png) In Play Mode, you'll see: 1. The **cover image** of the current element (if one has been assigned). 2. The **text content** of the current element. 3. One or more **clickable choices**, which correspond to the labeled connections leading out of that element. ### How Play Mode maps to the board Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 1: Arcweave overview > Play Mode > How Play Mode maps to the board Switching back to the Board, you can see how Play Mode elements correspond to what's on the diagram. ![A split-screen view of an Arcweave project and its Play Mode, with both sides focusing on the starting element. Orange rectangles and arrows highlight how the element's cover becomes the featured image in Play Mode, and how the connection's label appears as an option button.](https://docs.arcweave.com/assets/play-split-arrows.Bffgc1CY.png) - The **cover image** comes from an image assigned to the element. - The **text content** is authored directly inside the element. - Each **labeled connection** (arrow) leading out of an element becomes a **clickable choice** in Play Mode. ## Set Play Mode start Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 1: Arcweave overview > Set Play Mode start When you enter Play Mode, the story always begins at a designated **starting element**. You can identify the starting element by the **star icon** displayed on it. Hovering over the star icon shows a tooltip identifying the element as the Play Mode start. A project has a single starting element, regardless of how many boards it has. ### Changing the starting element Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 1: Arcweave overview > Set Play Mode start > Changing the starting element You can reassign the starting element at any time: 1. Right-click on any element in the Board. 2. Select **Play Mode > Set Play Mode start** from the context menu. The next time you enter Play Mode, the story will begin from the newly designated element. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 1: Arcweave overview > What's next You now have a high-level overview of the Arcweave environment: the Board, the Sidebar, Play Mode, and how the starting element works. In the next tutorial, we'll start building things from the ground up by **creating a new project from scratch**. In the meantime, feel free to explore _The Castle_ example project on your own — play through the story, inspect the elements and connections, and poke around the Sidebar sections to get comfortable with the interface. # Basic Arcweave tutorial | Part 2: Your first project Source: https://docs.arcweave.com/tutorials/basic/pt-2 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on creating your first Arcweave project This tutorial walks you through creating a new Arcweave project from scratch, setting up boards, adding elements, and connecting them to build a simple interactive story. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 2: Your first project > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=PhDZmmVnOis > ⚠️ This video does not reflect the latest updates to Arcweave's UI. ## Create a new project Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 2: Your first project > Create a new project Let's first create a new project. To do this: 1. Close any open projects. From inside your open project, click the **Workspace** button at the top left corner of the project environment. 2. Go to your workspace's **Projects** section. 3. From the projects list, click the big orange button that says **+ New Project**, near the top right of your window. 4. From the templates list, choose **Blank Project**. Your new project opens automatically. Click the default project name at the top and rename it — for example, _Tutorial._ ## Work with boards Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 2: Your first project > Work with boards Every new project comes with one board called _Main Board_. You can create additional boards from the sidebar. To add a new board, go to the sidebar, find the **Boards** section, and click **Create board** (the **+** icon in the section header). To rename it, right-click the board and choose **Rename**. ## Add elements Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 2: Your first project > Add elements Elements are the building blocks of your story in Arcweave. They live on boards and hold the content the player encounters. There are three ways to add an element to a board: - Double-click on an empty area of the board. - Right-click an empty area of the board and choose **Create > Element**. - Drag the element icon (**Drag new element**) from the bottom menu onto the board. ### Delete elements Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 2: Your first project > Add elements > Delete elements To delete an element, select it and press `Delete` or `Backspace`, or right-click and choose **Delete selection**. To select multiple elements at once, switch to [Select mode](https://docs.arcweave.com/project-tools/interface/bottom-menu#pan-select-icon), then click and drag from empty board space to draw a selection rectangle. This replaces the current selection. See [Select board items](https://docs.arcweave.com/project-tools/interface/mouse-actions#select-board-items) for ways to add or remove individual items or groups from the selection. ### Snap to grid Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 2: Your first project > Add elements > Snap to grid If you prefer your elements aligned to a grid, click the cog icon in the top menu to open [Project Settings](https://docs.arcweave.com/project-tools/settings#snap-to-grid) and select **Snap to grid**. ## Write element content Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 2: Your first project > Write element content To write in an element: 1. Double-click its title area (the colored top part) and type a title (for example, _Wake up)._ 2. Press `Tab` to move to the content area and type some text (for example, _You wake up from a nightmare, gasping for breath.)_ 3. Press `Escape` when done. ## Set starting element Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 2: Your first project > Set starting element The starting element is the first thing the player sees when the story runs. To set it, right-click your first element and choose **Play Mode > Set Play Mode start**. A star icon marks the starting element. ## Run the project in Play Mode Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 2: Your first project > Run the project in Play Mode To preview your story, click the **Play** icon (**Play Mode**) in the top menu. Play Mode opens in a new browser tab and displays your starting element's content. > ✅ Once Play Mode is open in its own browser tab, you don't need to click the play icon again after making changes. Simply switch back to that tab; Arcweave will have already refreshed the current element. ## Connect elements Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 2: Your first project > Connect elements A single element with no connections is a dead end. To continue the story, create a second element (for example, titled _Get up_) and connect the two. To connect elements, hover over the edge of an element until the cursor changes to a crosshair, then drag from that edge to the target element. Now when you run the project, the first element will display a clickable link to the second. > ✅ When an element is selected, you can use [keyboard shortcuts](https://docs.arcweave.com/project-tools/interface/keyboard-shortcuts#element-creation-connection) to instantly create a new connected element. Press **Ctrl + Alt/Option/Cmd + an arrow key** to create the new element in the direction of the arrow. ### Reassign and remove connections Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 2: Your first project > Connect elements > Reassign and remove connections - To reassign a connection, grab either end of it and drag it to a different element. - To remove a connection, select it and press `Delete` or `Backspace`, or right-click and choose **Delete selection**. ## Create choices Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 2: Your first project > Create choices The real power of interactive fiction comes from giving players meaningful choices. To create a branching path, add two new elements and connect them both from the same source element. For example, from _Get up,_ you could connect to: - _Go to the office_ - _Take a shower_ When the player reaches the _Get up_ element in Play Mode, both options will appear as clickable choices. By default, the text shown for each choice is the title of the destination element. ## Add labels to connections Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 2: Your first project > Add labels to connections Labels let you display different choice text to the player without changing element titles. This is useful when you want the clickable option to read differently from the element name. To add a label, double-click on a connection. A label field appears — type your text, then press `Escape` or `Tab` to confirm. You can also right-click a connection and choose **Add label**. Once labels are set, Play Mode will display the label text instead of the element title for each choice. > ✅ Labels can contain as much text as you need, including line breaks; there is no practical length restriction. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 2: Your first project > What's next You now have a working Arcweave project with multiple elements, connections, and player choices. In the next tutorial, you'll learn how to format text in elements and connections to give your story more visual structure. # Basic Arcweave tutorial | Part 3: Format text Source: https://docs.arcweave.com/tutorials/basic/pt-3 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on formatting your project's rich text In this tutorial, you will learn how to format text inside elements, apply color themes to elements and connections, and change the visual style of connections in Arcweave. ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 3: Format text > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=xEb3JKh4vls > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Format element text Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 3: Format text > Format element text Arcweave uses formatted text throughout the editor, giving you rich text controls directly inside elements. To open the text editor, double-click on any element. A formatting toolbar will appear at the element's top (or bottom, if there is not enough space). ![Arcweave's project environment, while editing an element. An orange arrow and an orange rectangle emphasize the position of the formatting bar above the element content's rich text field.](https://docs.arcweave.com/assets/rich-text-formatting-menu.s-yo582I.png) With text selected, you can apply the following formatting: - **Bold** — emphasize key terms or names. - _Italic_ — use for titles, foreign words, or subtle stress. - Underline — draw attention to specific phrases. - **Block quote** — make a paragraph stand out as a quote or a descriptive aside. Use this format for in-world signs, notes, or flavour text. ## Add and remove links Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 3: Format text > Add and remove links You can attach hyperlinks to any selected text inside an element — useful for research notes, world-building references, or external resources. ![An element in edit mode. An orange rectangle emphasizes the Link button in the rich text formatting menu. A similar rectangle emphasizes a group of words formatted as a link inside the element's text content.](https://docs.arcweave.com/assets/element-edit-link.DZG9BnWG.png) ### Add links Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 3: Format text > Add and remove links > Add links 1. Select the text you want to turn into a link. 2. Click the **link** button in the formatting toolbar. 3. Enter the URL. 4. Press **Enter** to confirm. ### Remove links Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 3: Format text > Add and remove links > Remove links 1. Select the linked text again. 2. Click the **link** button. 3. Delete the URL from the field. 4. Press **Enter** to confirm. ## Apply element color themes Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 3: Format text > Apply element color themes Color coding is a powerful and intuitive way to visually organize your project at a glance. You can assign color themes to elements to communicate meaning, e.g. to mark important plot points in blue, or negative outcomes in red. To apply a color theme to an element: 1. Right-click the element on the board. 2. Select the desired **theme color** from the context menu. > ✅ Color coding is personal; there is no universal convention. > ℹ️ Whichever color theme you choose last becomes the default for the **next** element you create. This means you can set your preferred color and keep working without changing it each time. To verify this, try the following: 1. Change an element's theme to any color. 2. Create another element. It will automatically use the last color theme you selected. ## Apply connection color themes Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 3: Format text > Apply connection color themes Connections can also be color-coded, following the same logic as elements. To apply a color to a connection: 1. Right-click the connection on the board. 2. Select the desired **theme color** from the context menu. > ℹ️ Whichever color theme you choose last becomes the default for the **next** connection you create. This means you can set your preferred color and keep working without changing it each time. ## Change connection styles Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 3: Format text > Change connection styles Beyond color, you can also change the visual form of a connection. Arcweave offers three styles: | Style | Description | | ------------- | -------------------------------------------------- | | **Bezier** | The default curved style. | | **Straight** | A direct line between two elements. | | **Flowchart** | Right-angle lines, similar to a flowchart diagram. | To change a connection's style: 1. Right-click the connection on the board. 2. Choose the desired style icon among **Bezier**, **Straight**, or **Flowchart**. > ℹ️ Whichever connection style you choose last becomes the default for the **next** connection you create. This means you can set your preferred style and keep working without changing it each time. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 3: Format text > What's next Now that your elements and connections are formatted and color-coded, you're ready to explore Play Mode. The next tutorial covers essential Play Mode functionalities that will help you playtest your project efficiently. # Basic Arcweave tutorial | Part 4: Play Mode functionalities Source: https://docs.arcweave.com/tutorials/basic/pt-4 Section: Tutorials > Basic Arcweave Description: Text and video tutorial on Arcweave Play Mode features This part of the tutorial covers the following Play Mode features: - [Restart](https://docs.arcweave.com/tutorials/basic/pt-4#restart): Replay a story from the beginning. - [Edit in Play Mode](https://docs.arcweave.com/tutorials/basic/pt-4#edit-in-play-mode): Edit text and reorder option buttons directly in Play Mode. - [Components](https://docs.arcweave.com/tutorials/basic/pt-4#components-in-play-mode): See how attached components appear in Play Mode. - [Debugger](https://docs.arcweave.com/tutorials/basic/pt-4#debugger): Inspect and test variable values during a playthrough. - [Undo last choice](https://docs.arcweave.com/tutorials/basic/pt-4#undo-last-choice): Step back to the previous element. - [Quickstart from any element](https://docs.arcweave.com/tutorials/basic/pt-4#quickstart-from-any-element): Start a playthrough from any element. - [Next element](https://docs.arcweave.com/tutorials/basic/pt-4#next-element): Advance through linear passages without option buttons. ## Video tutorial I Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Video tutorial I Watch this part of the tutorial as a video: Video: https://www.youtube.com/watch?v=ibUmh3VLsR0 > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can [play the finished Tutorial Project](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and [explore its boards and structure](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Enter Play Mode Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Enter Play Mode In your project, press **Play** to enter Play Mode. Alternatively, right-click an element and select [**Play Mode > Quickstart Play Mode from here**](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#quickstart-play-mode-from-here). ## Restart Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Restart To replay a story from the beginning, press **Restart**. It is on the left side of the Play Mode menu. ![Arcweave Play Mode with an orange arrow pointing at the Restart button in the top menu.](https://docs.arcweave.com/assets/play-mode-restart.CQ4BTfFQ.png) > ℹ️ Restarting a story with **Restart** resets all [global, board, and component variables](https://docs.arcweave.com/project-items/variables/overview#variable-scope) and all [element visits](https://docs.arcweave.com/tutorials/basic/pt-19). ## Edit in Play Mode Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Edit in Play Mode In Play Mode, click [**Edit content**](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#edit-content-in-play-mode) (the pencil icon in the top menu) or double-click the text content to enter edit mode. ![Play Mode with Edit content enabled: the pencil button in the top menu, the Editing indicator, and editable element text and option labels.](https://docs.arcweave.com/assets/play-mode-edit-content.CPnglMqz.gif) ### Edit text Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Edit in Play Mode > Edit text In edit mode, click anywhere in the element's text or in an option's label to edit it. Press **Esc** or click outside the text area to stop editing. ### Reorder options Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Edit in Play Mode > Reorder options In edit mode, drag an option by the grip handle on its left (or by its border) to reorder it. Changes are saved automatically. Press **Esc** or click outside the text area to stop editing. > ✅ For more details, see [Using Play Mode](https://docs.arcweave.com/project-tools/play-mode/using-play-mode). ## Video tutorial II Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Video tutorial II This video covers additional Play Mode features, described in the sections below. Video: https://www.youtube.com/watch?v=MbX5IGGKHfY > ⚠️ This video does not reflect the latest updates to Arcweave's UI. ## Components in Play Mode Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Components in Play Mode The first part of the video above explains how attached **components** appear in Play Mode. > ✅ Components are covered in the [next part of this tutorial](https://docs.arcweave.com/tutorials/basic/pt-5), so you can skip this section for now and return to it later. Displaying components in Play Mode is particularly useful for dialogue-heavy projects and brings Play Mode closer to a **visual novel style**: you can display a background image while characters (or other components) appear separately, layered on top. > ✅ For a full visual novel look, see the [visual novel tutorial](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel). Components are not limited to characters. You can attach items, spells, weapons, clues, or any other entity your story needs, and they appear in Play Mode alongside the element's content. If an element has no cover image, its components expand to fill the space normally reserved for the cover. When an element has multiple components, they share that space equally. ## Debugger Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Debugger To open the Debugger, click the **bug icon** in the Play Mode menu. ![Arcweave's Play Mode environment with the Debugger open and the current board's variables displayed.](https://docs.arcweave.com/assets/play-mode-debugger.CaTP6wLt.png) ### Previous and current values Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Debugger > Previous and current values The Debugger groups your project's global, board, and component variables. Each variable is listed in a row with its name and two value columns: - **Previous value**: The variable's value before the current element is rendered, that is, before any Arcscript in the element's content executes. - **Current value**: The variable's value after the current element is rendered, that is, after any Arcscript in the element's content has executed. When an element contains no Arcscript, both columns show the same value. When it contains an assignment or calculation, compare the two columns to see its exact effect. ### Color indicators Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Debugger > Color indicators The Debugger highlights a variable's value in **orange** when either of the following is true: - You edited the value manually during the playthrough. - The **Previous value** and **Current value** differ. ### Test variables Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Debugger > Test variables The **Previous value** column is editable. During a playthrough, you can click any value and change it to test how different states affect an element's outcome. The element's Arcscript still runs against the value you set, so the **Current value** column reflects the script's effect on your manual input. This lets you test edge cases and alternative branches without replaying the story to reach the required state. ## Story navigation Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Story navigation ### Undo last choice Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Story navigation > Undo last choice After making a choice, click **Undo last choice** in the Debugger header to return to the previous element with its saved variables, visits, and rendered content. See [Undo last choice](https://docs.arcweave.com/project-tools/play-mode/debugger#undo-last-choice) for details. ### Quickstart from any element Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Story navigation > Quickstart from any element As shown in [Part 1 of this tutorial](https://docs.arcweave.com/tutorials/basic/pt-1#set-play-mode-start), you can set the story's starting element by right-clicking an element and choosing **Play Mode > Set Play Mode start**. This marks the element with a star icon and makes it the entry point each time you press **Play**. Changing the starting element repeatedly to test different parts of your story can be tedious. Instead, use **Quickstart Play Mode from here**: 1. In the board, right-click any element. 2. Select **Play Mode > Quickstart Play Mode from here**. This opens a **new browser tab** and starts the playthrough from that element, without changing your project's designated starting element. The main **Play** button still starts from the original starting element, which makes Quickstart ideal for testing specific scenes or branches in isolation. > ℹ️ If you started the playthrough with **Quickstart Play Mode from here**, **Restart** restarts it from that same element, regardless of the project's starting element. ### Next element Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > Story navigation > Next element When only one option is available and its labels produce no text, Play Mode shows a **blinking arrow** instead of an option button. Click the element's content area to continue to the next element. Arcweave checks this _after evaluating branches and label Arcscript,_ so multiple outgoing connections can still lead to a single available option. A label containing only variable assignments or conditional text that produces nothing in the current playthrough can still result in the arrow. To force the creation of a button for a single option, give its path a label that produces text, such as "Continue". > ℹ️ See [labels across branches](https://docs.arcweave.com/project-items/labels#labels-across-branches) for paths with several labels. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 4: Play Mode functionalities > What's next The next part of this tutorial covers [components](https://docs.arcweave.com/tutorials/basic/pt-5) and introduces the built-in icon library you can use in your project. # Basic Arcweave tutorial | Part 5: Components & icons Source: https://docs.arcweave.com/tutorials/basic/pt-5 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on Arcweave components and the icon library [Components](https://docs.arcweave.com/project-items/components) are one of Arcweave's most versatile features. They let you represent any meaningful object in your story (characters, locations, inventory items, abstract concepts like emotions or pieces of information) and then connect them to your board elements to make your narrative easier to navigate and manage. The [icon library](https://docs.arcweave.com/project-tools/icon-library) is a built-in collection of symbols and icons that you can use as art for your Components. ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=BqkAUNv0q0M > ⚠️ This video does not reflect the latest updates to Arcweave's attributes, which now support more types (and are not called "text fields" anymore). See [Attributes](https://docs.arcweave.com/project-items/attributes) for more details. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Why components Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > Why components In a typical interactive story, you'll have characters, places, things, and ideas that recur across many scenes. Components give these entities a home: a dedicated card where you can store their attributes, backstory, relationships, and inventory. Once created, components can be attached to board elements, dragged between them, and used to quickly locate every scene where a particular character or object appears. ![An open component storing a magical spell, with the component's attributes storing the spell's stats and specs.](https://docs.arcweave.com/assets/components-intro.BKzGX-79.jpg) ## Create components Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > Create components ![The Arcweave project environment with an orange rectangle emphasizing the Components section of the left sidebar.](https://docs.arcweave.com/assets/components-sidebar.DNiuAhMt.png) 1. Go to the **Components** section in the sidebar. 2. Click **Create component** (the person icon with a **+** sign in the section header). 3. Click on the default title and replace it with your component's name (e.g. _Jillian Linetti)._ ## Attributes Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > Attributes In Arcweave, **attributes** are fields that let you store extra information inside [boards](https://docs.arcweave.com/project-items/boards), [components](https://docs.arcweave.com/project-items/components), and [elements](https://docs.arcweave.com/project-items/elements). See [Attributes](https://docs.arcweave.com/project-items/attributes) for more information. All three item types support the following attributes: - String Field - Rich Text Field - Component List - Asset List Boards and components additionally support **Boolean**, **Integer**, and **Float** attributes. On boards and components, these types and String Field appear in the **Variables** group and act as [scoped variables](https://docs.arcweave.com/project-items/variables/overview#variable-scope). Elements support only the four shared attribute types listed above. ### Add attributes Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > Attributes > Add attributes You can enrich a component with as many custom attributes as you need. 1. In the component dialog, click **Add attribute**. 2. Select the type of attribute (see above). 3. Type the attribute name (e.g. _Dramatic function_ or _Backstory,_ etc.) and press **Tab**. 4. Enter the content for that attribute. ### Reorder and resize attributes Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > Attributes > Reorder and resize attributes - To **reorder** attributes, drag them by the grip (dots) icon at their top left into the position you want. - To **resize** an attribute between full and half width, open its three-dot menu (**•••**) and select **Resize**. ## Set component covers Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > Set component covers To make a component more visually distinctive, you can use Arcweave's built-in icon library and pick an icon to set as **component cover**: 1. Hover over the component's icon area and click **Change cover**. 2. Choose the **Icon Library** tab. 3. Browse the icon library and select an icon to set as cover. For example, searching _head_ returns a wide selection of face icons. The new icon will appear both on the component card and in the sidebar. > ℹ️ Besides **Icon Library**, you can also select **My Assets** (your own uploaded images) or **Generate** (use Arcweave's [AI Image Generator](https://docs.arcweave.com/project-tools/ai-features/image-generator) to generate an image cover.) ## Duplicate components Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > Duplicate components If you need to create a similar component quickly, you can duplicate an existing one instead of starting from scratch. 1. Right-click the component in the sidebar. 2. Select **Duplicate**. 3. Open the duplicate and update its name and content as needed. > ℹ️ To duplicate board elements, copy and paste them (**Ctrl/Cmd + C**, then **Ctrl/Cmd + V**). ## Attach components to components Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > Attach components to components Components can contain references to other components. This is useful for modelling relationships (e.g. family members) or inventories (e.g. items a character carries). ### Link characters to each other Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > Attach components to components > Link characters to each other 1. Open a character component (e.g. _Horace Linetti)._ 2. Click **Add attribute**, choose **Component List**, and give it a name (e.g. _Family_). 3. Drag another component (e.g. _Jillian Linetti)_ into the list. 4. Click the attached component to open it directly from within the parent. ### Create a character inventory Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > Attach components to components > Create a character inventory 1. First, create the item components you need (e.g. _Dice, Top hat, Gold watch)._ 2. Open the character component you want to assign items to. 3. Click **Add attribute**, choose **Component List**, and name it _Inventory._ 4. Drag the item components into the list. 5. Reorder items within the list by dragging them. ## Organize components with folders Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > Organize components with folders As your project grows, you can keep the sidebar tidy by grouping components into folders. 1. In the **Components** section header, click **Create folder** (the folder icon with a **+** sign). Alternatively, hover over a component or folder, click its **+** icon, and choose **Create folder**. 2. Name the folder (e.g. _Characters)._ 3. Drag components into the folder. 4. Repeat to create additional folders (e.g. _Items_). You can also create **subfolders** by adding a folder inside an existing one. ## Attach components to elements Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > Attach components to elements Attaching components to elements lets you see at a glance which characters, items, or locations are involved in a given scene. ![Animated GIF demonstrating how to attach a component to an element and then how to remove the attachment.](https://docs.arcweave.com/assets/drag-component.1SxFaBei.gif) 1. From the sidebar, drag a component directly onto an element on the board. 2. Repeat for any other components relevant to that scene. Once attached, components appear visually on the element. If the element's layout looks off, adjust it: 1. Select the element. 2. Adjust its size. Either: - Drag its sides or corners to manually adjust the element's height and width. - Double-click the element's orange bounding rectangle. Arcweave will automatically resize the element to fit its content at the chosen width. ## (Re)move attached components Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > (Re)move attached components - To **remove** a component from an element, drag it out of the element onto an empty area of the board. - To **move** a component, drag it from one element to another. - You can attach the **same component multiple times** to the same element if needed. ## Create elements from components Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > Create elements from components You can quickly scaffold a new element around a component directly from the sidebar: 1. Drag a component from the sidebar onto an empty area of the board. Arcweave creates a new element with the component's name as the title and the component attached automatically. This is a fast way to start building a scene around a specific character or object. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 5: Components & icons > What's next After learning all there is about components, the next tutorial will teach you how to mention both components and boards in your project and why this is useful. # Basic Arcweave tutorial | Part 6: Mentions Source: https://docs.arcweave.com/tutorials/basic/pt-6 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on Arcweave components and board mentions Mention components and boards to easily access them and keep them up to date with any changes of name. > ℹ️ This tutorial does not refer to [mentioning users in comments](https://docs.arcweave.com/project-items/comments#user-mentions). ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 6: Mentions > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=BgLwvMyyDw8 > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Why mentions Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 6: Mentions > Why mentions As a project grows, it can become increasingly difficult to keep track of all its parts. You may have boards for outlines, scenes, and dialogue trees, as well as components for characters, locations, items, and scenery. Navigating to a specific element or updating something (like a character's name) across the entire project can quickly turn into a manual and error-prone process. Arcweave's [mentions](https://docs.arcweave.com/project-tools/mentions) feature solves this by creating a live, organic connection between the parts of your project. When you mention a component or a board in your text, that reference stays in sync automatically: rename the component or board and every mention updates with it. ## Search Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 6: Mentions > Search Before diving into mentions, it's worth remembering that Arcweave has a built-in search tool. ![Arcweave's project screen, with the search field open and showing results for the term "crusader" in the Interactive Fiction Example project.](https://docs.arcweave.com/assets/search._53j8hnX.png) To search your project for any text occurrence: 1. Click **Search project** (the magnifying glass icon at the top right of your screen). 2. Type any word or phrase in the search field. Arcweave will list every item that contains it. 3. Click a search result to locate the respective item. Search is useful for finding anything, including components by name, but it doesn't allow renaming. For that, mentions are the appropriate tool. ## Mention components Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 6: Mentions > Mention components ### What they are Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 6: Mentions > Mention components > What they are Mentioning a component links its name in your text with the component itself. In the rich text, names of mentioned components appear in **orange text**. ![Animated GIF demonstrating how to mention an existing component.](https://docs.arcweave.com/assets/mention.DQykf4Hg.gif) ### What they do Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 6: Mentions > Mention components > What they do Mentions: - Act as **clickable links** to the component. - Automatically reflect any name changes. ### Where they appear Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 6: Mentions > Mention components > Where they appear You can insert mentions by typing in any field of rich text: - Title or content of [elements](https://docs.arcweave.com/project-items/elements) - [Notes](https://docs.arcweave.com/project-items/notes) - Rich text [attributes](https://docs.arcweave.com/project-items/attributes) - Connection [labels](https://docs.arcweave.com/project-items/labels) > ℹ️ Mentions are not visually styled in Play Mode; they appear as regular text. ### Add mentions Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 6: Mentions > Mention components > Add mentions To insert a component mention: 1. Open a field of rich text (element title or content, label, or note). 2. Place your cursor where you want the mention to appear. 3. Type the `@` character. A dropdown list of your project's components appears. 4. Start typing the component's name and select it from the list. ![Example of mentioning a component by typing the @ character followed by a few letters of the component's name. A list opens, from which the user can choose an existing component or create a new one.](https://docs.arcweave.com/assets/mentions-overview.BgVMv8af.jpg) The mention is now embedded in your text. It renders as a highlighted, clickable link. Clicking it opens the referenced component directly. ### Rename mentioned component Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 6: Mentions > Mention components > Rename mentioned component When you rename a component, every mention of it across the project updates its displayed text to match the new name. No need to manually find and replace. To test this: 1. Open the component you have mentioned. 2. Edit the component's name. 3. Return to any rich text field that mentions it. The mention text reflects the new name immediately. > ⚠️ Automatic updates only apply to text that uses mentions. Any occurrence where you typed the name manually will not update. Make sure to use mentions wherever you want changes to propagate. ## Mention boards Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 6: Mentions > Mention boards Besides components, you can **also mention boards** in any rich text field of your project. This is useful for cross-referencing different areas of your project. The process is identical to mentioning a component: 1. Place your cursor in a rich text field. 2. Type `@` and begin typing the board's name. 3. Select the board from the dropdown. Just like component mentions, board mentions stay in sync: if you rename the board, the mention text updates everywhere it appears. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 6: Mentions > What's next Using mentions is especially valuable when collaborating with a team. If one person renames a character or restructures a board, every reference in the project updates automatically. Nothing gets left behind and the whole project stays in sync. The next tutorial will introduce Arcweave notes and suggest how they can help with your project collaboration and management. # Basic Arcweave tutorial | Part 7: Notes Source: https://docs.arcweave.com/tutorials/basic/pt-7 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on using Arcweave notes Learn how [notes](https://docs.arcweave.com/project-items/notes) work in Arcweave. Notes are a dedicated entity in Arcweave designed for communication between writers, designers, and developers. They are not for the players to experience. While elements are the building blocks of your narrative, notes serve as the sticky pieces of paper in your project: a place to leave comments for collaborators, reminders for yourself, explanations of complex story logic, dialogue subtext, or the reasoning behind a particular design decision. ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 7: Notes > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=I1lopewUx84 > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Notes vs. elements Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 7: Notes > Notes vs. elements Before creating a note, it's worth understanding what sets notes apart from elements. Unlike elements: - Notes cannot have connections to other board items. - They cannot have attachments like components or assets. - They cannot contain code. This is by design. Notes do not participate in the narrative tree; they exist purely as a communication tool for the people building the project. ## Create notes Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 7: Notes > Create notes There are two ways to create a note on the board: - Right-click an empty area of the board and select **Create > Note** from the context menu. - Click and drag the **Drag new note** icon from the bottom menu onto the board. Having created the note, double-click its body to edit its content. ## Change note colors Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 7: Notes > Change note colors Notes support color customization, making it easy to visually organize them by type or topic. For example, you can use one note color for story logic and another for technical reminders. To change a note's color, right-click the note and select a color from the color picker in the context menu. ## Format notes text Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 7: Notes > Format notes text Notes support **rich text formatting**, just like elements. ![Arcweave's project environment, while editing a note. An orange rectangle emphasizes the position of the formatting bar above the note's rich text field.](https://docs.arcweave.com/assets/rich-text-formatting-menu-note.CkAZNSTW.png) While editing a note, use the formatting menu to apply: - Bold, italic, and underline formatting: Emphasize your text as you want. - Links: Add URLs to web pages and attach references, research, or resources directly to notes for easy access. - Mentions of components and boards (see [previous part](https://docs.arcweave.com/tutorials/basic/pt-6) of this tutorial): Cross-reference parts of your project directly from a note. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 7: Notes > What's next Now that you know how to work with notes, the next tutorial covers how you can add and use images in your Arcweave project. # Basic Arcweave tutorial | Part 8: Image assets Source: https://docs.arcweave.com/tutorials/basic/pt-8 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on using images as assets in Arcweave projects Learn how to upload and use [image assets](https://docs.arcweave.com/project-items/assets/images) in Arcweave. [Assets](https://docs.arcweave.com/project-items/assets/overview) are the media files you upload to use in your project. > ℹ️ This tutorial page and the video tutorial below do not refer to video and audio assets. For audio assets, see [this tutorial page](https://docs.arcweave.com/tutorials/basic/pt-21). > For video assets, refer to [their documentation](https://docs.arcweave.com/project-items/assets/video). ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Video tutorial Watch this tutorial as a video: > ℹ️ This older video does not include the more recent features of [audio](https://docs.arcweave.com/project-items/assets/audio) and [video assets](https://docs.arcweave.com/project-items/assets/video). Video: https://www.youtube.com/watch?v=zBki8mSDtWY > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Why assets Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Why assets While the icon library is great for abstract or symbolic imagery, image assets let you bring your own pictures into Arcweave (photographs, illustrations, concept art, and more) and apply them as covers on elements and components. ## Assets section Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Assets section ![The Arcweave project environment with an orange rectangle emphasizing the Assets section of the left sidebar.](https://docs.arcweave.com/assets/assets-sidebar.CKLkshad.png) You can find your project's assets in the sidebar under **Assets**. ## Supported file types Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Supported file types Arcweave supports the following image file types, which you can use as assets: - `.jpg` / `.jpeg` - `.png` - `.gif` - `.webp` > ℹ️ `.gif` files animate in Play Mode only. In the board view, they appear as static images. > ℹ️ Uploaded images can be up to **8192 x 8192 pixels**. ## Upload assets Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Upload assets There are two easy ways to upload assets to your project. ### Use context menu Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Upload assets > Use context menu The first way to upload one or more assets is by clicking the **Create asset** button found in the Assets section of your project. 1. In the sidebar, click the **Assets** tab. 2. Click **Create asset** (the **+** icon). 3. Click **Upload assets...** from the context menu. 4. Choose an image file from your computer. The uploaded file will appear in your project's Assets section immediately after the upload completes. ### Drag and drop Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Upload assets > Drag and drop The second, even easier way is to drag one or more images and drop them directly into the Arcweave browser tab. - **Drop them anywhere**: The asset will be saved in the root of the Assets section. - **Drop them into a specific asset folder**: The asset will be saved in that folder within the Assets section. ## Organize assets Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Organize assets ### Create asset folders Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Organize assets > Create asset folders Just as with components, you can create folders (and subfolders) to keep your assets organized. 1. Click the **+** icon next to any asset or asset folder 2. Select **Create folder** from the menu that appears. 3. Give the folder a name (e.g., _Characters_ or _Locations)._ Repeat this process to create as many folders as you need. > ✅ Nest subfolders inside other folders to build a deeper organizational structure. ### Move assets Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Organize assets > Move assets To move an existing asset into a folder or a different position in the order, use drag and drop. > ℹ️ You cannot select multiple assets for moving. ### Upload assets into folders Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Organize assets > Upload assets into folders To save time, you can upload new assets straight into a specific folder instead of dragging them later. 1. Hover over the target folder row in the Assets panel. 2. Click the **+** icon that appears next to the folder name. 3. Select **Upload assets...** and choose your file. The file will land directly inside that folder. ## Rename an asset Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Rename an asset 1. Right-click on the asset you want to rename. 2. Select **Rename** from the context menu. 3. Type the new name and confirm. > **Note:** Renaming an asset does not affect the original file's extension. Only the display name changes. ## Set assets as element covers Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Set assets as element covers You can assign an image asset as the cover image of an element on your board. There are two ways to do this. ### Use context menu Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Set assets as element covers > Use context menu First, you can set an asset as element cover using the **Set cover** menu option: 1. Right-click on the element. 2. Select **Cover > Set cover**. 3. In the dialog that opens, go to the **My Assets** tab. 4. Browse to the image you want and click it to apply. The image will appear as the element's cover. If the text is pushed down, resize the element's height to suit your layout. ### Drag and drop Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Set assets as element covers > Drag and drop The second way to set an image asset as element cover is to drag the image directly from the Assets section and drop onto the element. ## Replace element covers Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Replace element covers If you change your mind about an element's cover, just reset its cover using either of the two ways described above. ## Remove element covers Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Remove element covers To remove a cover entirely, right-click the element and select **Cover > Remove cover**. ## Component covers Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Component covers Image assets can also be used as component covers. ### Change component covers Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Component covers > Change component covers Not sure if you've noticed, but components always come with a cover. Upon their creation, their default cover is the generic icon of a person. This is why there is no **Set cover** option for components; only **Change cover**. To assign an image asset as component cover: 1. In the **Components** section, click on any component to open it. 2. Hover your mouse over the current cover (be it an icon or another asset) and click the orange button that appears, saying **Change cover**. 3. On the appearing panel, go to the **My Assets** tab, navigate to the correct folder, and select the image you want to use. The updated cover will be reflected everywhere that component appears across the project. ## Replace assets Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > Replace assets Sometimes you need to swap out an image that is already in use. For example, to replace a placeholder sketch with the final artwork. Arcweave lets you replace an asset globally in a project, updating all its occurrences in a single action. 1. In the **Assets** section, right-click on the asset you want to replace. 2. Select **Replace asset...**. 3. Choose the new image file. The new image will immediately replace the old one everywhere it was used in the project. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 8: Image assets > What's next In this tutorial you learned how to upload and organize assets in folders and apply them as element or component covers. The next tutorial will teach you all there is to know about **jumpers**, which you will use to jump from one element to another within your project. # Basic Arcweave tutorial | Part 9: Jumpers Source: https://docs.arcweave.com/tutorials/basic/pt-9 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on using jumpers in Arcweave projects Learn how to use [jumpers](https://docs.arcweave.com/project-items/jumpers) to connect board items that are far apart or in different [boards](https://docs.arcweave.com/project-items/boards). Jumpers are a powerful tool that let you move from one element to another across different boards, without using arrow connections. This tutorial shows you how to use jumpers to break a long story into manageable segments, each living on its own board. ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 9: Jumpers > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=gqOoSzDFrrg > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Diagram types Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 9: Jumpers > Diagram types Before adding jumpers, it helps to understand the two kinds of diagrams we'll work with in this tutorial. **Event-based**: Used on boards like the _Beginning_ board (the board with your story's opening events, such as the one you built in [Part 2](https://docs.arcweave.com/tutorials/basic/pt-2); rename it _Beginning_ if you haven't already). The narrative starts on the left, progresses right, branches out, and reaches an ending. **Each element describes an event** and the story moves forward: as a rule, there are no arrows leading back to earlier elements. **Location-based**: Used in the Apartment board (which we'll create right after), where the diagram represents a physical space, like an apartment. **Each element describes a room** or other **location** and the player can move back and forth between the room-elements. Because the player can move between rooms, connections generally go in both directions. ## The apartment board Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 9: Jumpers > The apartment board So let's create our location-based diagram that represents the game's world: the apartment that you explore. 1. Create a new board and name it _Apartment._ 2. Add one element per room: _Living room, Kitchen,_ and _Bathroom._ 3. Give all room-elements the same color so they are visually grouped. 4. Assign a cover image to each element using the relevant assets from the asset panel. 5. Connect the rooms: 1. From the _Living room,_ draw connections to the Kitchen and to the Bathroom. 2. Draw return connections from the _Kitchen_ back to the _Living room_, and from the _Bathroom_ back to the _Living room_. 6. Add labels to each connection: _Go to kitchen_, _Go to bathroom_, _Back to living room_, etc. 7. Set _Living room_ as the starting element and run a quick test to confirm navigation works correctly. > ⚠️ In a location-based diagram, always add **return connections**. Without them, the player reaches a room and gets stuck with no way to navigate back. ## Connect the boards Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 9: Jumpers > Connect the boards Now connect the Beginning board to the Apartment board using a jumper. 1. Go to the _Beginning_ board. 2. Select the element where the player arrives at the apartment (for example, _Horace opens the door_) and polish it: add a cover image and a few lines of content. 3. Right-click on an empty area of the board and choose **Create > Jumper**, or drag a new jumper from the jumper icon (**Drag new jumper**) in the bottom menu. 4. Assign the _Living room_ element as the jumper's target element. You can do this in any of the following ways: - Use **Search**: look up "living room" and, from the search results, drag the element with title _Living room_ and drop it into the empty jumper. - From _Boards_ section: from the sidebar, find and expand the _Apartment_ board. Do not click the board itself, just click the expand arrow next to it. Then, find the _Living room_ element in the element list and drag it into the jumper. 5. Draw a connection from the apartment-arrival element to the jumper. Add a label such as _Look around_. 6. Set the first element of the _Beginning_ board as the starting element (**Play Mode > Set Play Mode start**) and run the story to confirm the jump works end-to-end. > ✅ You don't need to first create an empty jumper: drag an element directly from the sidebar or the **Search** field onto an empty area of the board; Arcweave automatically creates a jumper pointing to that element. > ✅ Another handy way to assign a target element to a jumper is to copy the desired element (right-click and **Copy**, or **Ctrl/Cmd + C**) and then use [Paste as jumper](https://docs.arcweave.com/project-items/jumpers#assign-jumper-targets) on an empty jumper or anywhere on the board. ## Jump to endings Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 9: Jumpers > Jump to endings Jumpers are also useful for routing multiple story paths to a small set of shared destinations, such as all your game's endings. ### Endings board Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 9: Jumpers > Jump to endings > Endings board You can keep all the endings of your story in one board: 1. Create a new board and name it _Endings_. 2. Add an element for each ending you need, for example: - _Failure to enter the apartment_ (color: red) - _Success!_ (color: green) - _Defeated by the demon_ (color: red), etc. ### Connect to an ending Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 9: Jumpers > Jump to endings > Connect to an ending Using one of the methods described in [Connect the boards](https://docs.arcweave.com/tutorials/basic/pt-9#connect-the-boards), above, create a jumper to the _Failure to enter the apartment_ element in the _Endings_ board. You can lead the story to this abrupt ending if the player chooses not to take a shower before knocking the apartment's door. Connect that branch of the story flow to the _Failure to enter the apartment_ jumper and you're set. ## Replace target elements Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 9: Jumpers > Replace target elements If you need to change the target element of a jumper, drag the new target element from the sidebar or search directly onto the existing jumper. The jumper updates immediately. ## Add restart jumpers Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 9: Jumpers > Add restart jumpers To let the player restart the story from any ending: 1. Create a jumper that targets the **starting element** of the _Beginning_ board. 2. Connect all ending elements to this jumper. > ⚠️ When you later introduce variables, remember to add code that resets them whenever the player restarts. For now, the jump itself is enough. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 9: Jumpers > What's next You've now seen the use and benefits of jumpers. In the next tutorial, you'll add **variables** to your story, to give it logic and control its flow based on what has already happened. # Basic Arcweave tutorial | Part 10: Global variables Source: https://docs.arcweave.com/tutorials/basic/pt-10 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on using global variables in Arcweave projects Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. Learn how to define [global variables](https://docs.arcweave.com/project-items/variables/global) and assign them values. ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 10: Global variables > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=SOfA486HIog > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Why variables Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 10: Global variables > Why variables In previous tutorials, we saw how to create choices that immediately lead to different outcomes: the player chooses A over B and reads the contents of element A and not B. But what if you want choices that influence _later_ parts of the game? For example, what if there is a locked door that opens only when the player finds the appropriate key? How do you check whether the player has it? To do this, you need **variables**. Variables store pieces of information in the computer's memory so you can access them later in the game. ## Variable types Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 10: Global variables > Variable types In Arcweave, variables can hold the following types of values: - **Integer**: A whole number, e.g. `1`, `-200`, and `0`. - **Float**: A decimal number, e.g. `5.34`, `1.0`, `-3.5`, and `0.0`. - **String**: A word or sentence, like the name of a character, e.g. `Galandriel` or any combination of letters, numbers, and special characters like `1234%hello`. - **Boolean**: A binary variable that can be either `true` or `false`. ## Variable scopes Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 10: Global variables > Variable scopes Variables are always present in memory and can be accessed from anywhere in your project at any time. Arcweave supports global and scoped variables: - [Global variables](https://docs.arcweave.com/project-items/variables/global): variables accessed directly by their name, e.g. `score`. - [Board variables](https://docs.arcweave.com/project-items/variables/board): variable attributes accessed by the board custom ID and attribute custom ID, e.g. `board_id.var_id`. - [Component variables](https://docs.arcweave.com/project-items/variables/component): variable attributes using the same `component_id.var_id` syntax. In this tutorial we will focus on global variables. ## Locked drawer mechanic Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 10: Global variables > Locked drawer mechanic To demonstrate variables in action, we'll add a locked drawer in the kitchen and a hidden key in the bathroom. ### Add the drawer Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 10: Global variables > Locked drawer mechanic > Add the drawer 1. Go to the _Kitchen_ element of your _Apartment_ board. 2. Add a new element next to it, title it _Searching cabinets,_ and connect the _Kitchen_ element to it. 3. Label the connection _Search the cabinets_. 4. In the new element, write text describing what the player finds: a locked drawer with nothing else of interest. 5. Add a return connection back to the Kitchen element, so the player is not stuck in the _Searching cabinets_ element. ### Add the key Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 10: Global variables > Locked drawer mechanic > Add the key 1. Go to the _Bathroom_ element. 2. Add a new element titled _Bathroom mirrors_ and connect it to the Bathroom, labelling the connection _Examine the mirrors._ 3. Add content to the mirrors element describing what the player sees: _When you stand at the centre of the room, both mirrors reflect the same corner: the top part of the door._ 4. From the _Bathroom mirrors_ element, add another element, give it the title _Finding the key,_ and draw a connection to it from _Bathroom mirrors._ Label the connection: _Examine the corner above the door._ 5. In the _Finding the key_ element, add the text that describes the player finding the key: _You run your fingertips along the door's top frame. You stop, as they touch something small and jagged. It's a key! You put it in your pocket._ 6. Add a key image or icon as element cover, as we've described in the [Assets part](https://docs.arcweave.com/tutorials/basic/pt-8) of this tutorial. 7. Connect back to the _Bathroom_ element or, even better, use a jumper to keep the board cleaner. ### Test, but... Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 10: Global variables > Locked drawer mechanic > Test, but... Set the _Living room_ as the starting element (**Play Mode > Set Play Mode start**), then run the project. You can navigate to the bathroom, examine the mirrors, examine the corner above the door, and find the key. However, you'll notice a problem: you can repeat this sequence as many times as you want, finding the key over and over again. This is because **we haven't stored the information** of having found the key anywhere. No matter how logical the intent, the game will not keep track of it unless we use variables. ## Create a global variable Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 10: Global variables > Create a global variable 1. Go to the lower-left side of the screen and click **Global variables**. 2. Click **+ New variable**. 3. Name it `has_key`. 4. Set the type to **Boolean**. 5. Set the initial value to `false`, since the player does not start the game with the key. 6. Press **Esc** or click outside the **Global variable dialog** to close it. Now, all we need to do is use the variable in two points of the story: 1. **When the player finds the key**, the variable will change from `false` to `true`. This is called a **value assignment**. 2. When the player tries opening the locked drawer. This will be a **condition evaluation** that checks whether the player has the key. Let's see these one by one. ## Assign the variable Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 10: Global variables > Assign the variable ### Insert the assignment Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 10: Global variables > Assign the variable > Insert the assignment We need the `has_key` variable to change from `false` to `true` when the player picks up the key. 1. Go to the _Finding the key_ element. 2. Double click the element's body to edit its content, place your cursor at the end of the text, and press **Return** to create a new line. 3. In the formatting menu, click **Arcscript** (the **<>** icon) to insert an Arcscript code segment. 4. Inside the Arcscript segment, type: `has_key = true`. > ✅ Arcweave's auto-complete will assist you when typing Arcscript. The element should look like this: ```arcweave-html You run your fingertips along the door's top frame. You stop, as they touch something small and jagged. It's a key! You put it in your pocket. has_key = true ``` ### Test the assignment Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 10: Global variables > Assign the variable > Test the assignment Arcweave has a built-in [debugger](https://docs.arcweave.com/project-tools/play-mode/debugger) you can use to inspect variable values as you play through a project. The debugger shows all variables and their values: - Previous value: The variable's value before visiting the current element. - Current value: The variable's value after visiting the current element (and thus having executed any code included in it). To open the debugger: 1. In the project environment, click the **Play** icon (**Play Mode**) in the top menu. 2. Once in Play Mode, hover at the top of your browser window; this causes the **Play Mode menu** to appear. 3. Click **Debug**, the orange bug icon at the right side of the menu. At the start of the game, `has_key` shows as `false`. Navigate to the bathroom, examine the mirrors, examine the corner above the door, and pick up the key. The debugger panel refreshes and shows `has_key` is now `true`. > ✅ The debugger is particularly useful when things don't go as expected and you need to track how variable values change as the player moves through the project. ## Prepare for branching Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 10: Global variables > Prepare for branching We've now assigned the variable, but we still haven't prevented the player from repeatedly finding and refinding the key. To do that, we need to show different content depending on the value of `has_key`: - If `has_key` is `false` → let the player find the key. - If `has_key` is `true` → show the mirror room again, but with no key to find. To support these two outcomes, duplicate the _Bathroom mirrors_ element and update each version: 1. Copy and paste the mirrors element. 2. Rename the original to something like _Bathroom mirrors – first time._ 3. Rename the copy to _Bathroom mirrors – has key._ 4. In the "has key" version, remove any text or connection that leads to finding the key. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 10: Global variables > What's next You now have two separate paths ready. In the next tutorial, we will add **branches** to control which version the player sees based on the value of `has_key`. # Basic Arcweave tutorial | Part 11: Branches Source: https://docs.arcweave.com/tutorials/basic/pt-11 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on using branches to divert the flow in Arcweave projects Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. Learn how to use [branches](https://docs.arcweave.com/project-items/branches) with `if` / `elseif` / `else` statements to direct your story's flow. In the previous tutorial, we created a variable to track whether the player has the key, and learned how to set it from `false` to `true` when the player discovers it. Now we'll use Arcweave's **branches** to give the player different outcomes based on that variable's value. ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=k67gFLzUUWI > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Create a branch Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Create a branch To create a branch, either: - Right-click on the board and choose **Create > Branch**, or - Drag the **branch icon** from the toolbar into the board. The new branch already has an `if` statement waiting to be filled in. ## The `if` part Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > The `if` part ### Write the `if` condition Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > The `if` part > Write the `if` condition An `if` statement checks whether a condition is **true** or **false**. Double-click the branch's `if` condition and type the expression below. The branch already displays the `if` keyword, so type only the expression after it: ```arcscript has_key == true ``` > **Note:** Do not confuse `=` with `==`: > > - `=`: Assigns a value to a variable, e.g. `has_key = true` assigns the `true` value to the `has_key` variable. > - `==`: Signals **comparison**, i.e. checks whether two things are equal, as in the above case. There are alternative ways to write the same condition in Arcscript, for example: ```arcscript has_key is true ``` Or, since `has_key` is a boolean that can only be `true` or `false`, you can omit the last part entirely: ```arcscript has_key ``` When the variable is `true`, the whole condition is `true` and the `if` statement fires. ### Connect the `if` output Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > The `if` part > Connect the `if` output Draw a connection from the branch's `if` output to the element _Bathroom mirrors – has key_ (created in [Part 10](https://docs.arcweave.com/tutorials/basic/pt-10#prepare-for-branching)). This is where the player will be sent when they already have the key. ## The `else` part Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > The `else` part ### Add an `else` condition Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > The `else` part > Add an `else` condition Right-click the branch and choose **Add else**. `else` conditions cannot be edited. They are implicitly defined as the alternative that applies when none of the preceding conditions are met. ### Connect the `else` output Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > The `else` part > Connect the `else` output Connect the `else` output to the _Bathroom mirrors – first time_ element. ## Finish connections Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Finish connections ### Connect the branch's input Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Finish connections > Connect the branch's input Update the _Examine the mirrors_ connection from the _Bathroom_ element so that it **now leads to the branch**: drag its arrowhead from the mirrors element onto the branch. ### Create returns Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Finish connections > Create returns Make sure both outcomes include an option to return to the main bathroom element. ## Review the logic Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Review the logic The full flow looks like this: 1. Player reaches the bathroom and chooses to examine the mirrors. 2. The branch checks the value of `has_key`. 3. If the player **has** the key → they see the "having the key" description, then can go back. 4. If the player **does not** have the key → they see the hiding place, can examine it, find the key, then go back. ## Another branch: the kitchen Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Another branch: the kitchen Let's apply the same logic to the kitchen. Here, the goal is different: if the player has the key, an **extra choice** appears: _Unlock the drawer._ If they don't have the key, that choice doesn't appear at all. 1. Create a new element for the outcome of unlocking the drawer and title it _Find the diamond ring._ 2. Connect the _Searching cabinets_ element (from [Part 10](https://docs.arcweave.com/tutorials/basic/pt-10#add-the-drawer)) to a new branch whose `if` condition is `has_key`, and connect the branch's `if` output to the _Find the diamond ring_ element. 3. Label that output connection: _Unlock the drawer._ There is no `else` expression here. If the `if` condition is not satisfied, the option to unlock the drawer doesn't appear to the player at all. ## Understand the two branch patterns Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Understand the two branch patterns You've now used branches in two distinct ways and it's worth understanding the difference: - `if` / `else` (bathroom): The branch always diverts the flow somewhere: either the `if` path or the `else` path. - `if` only (kitchen): If the condition is not met, nothing happens; the choice associated with the branch doesn't appear to the player. Choose the pattern that fits the experience you want to create. ## Test the game Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Test the game Run the project in Play Mode from the beginning to verify both branches work correctly: 1. **Bathroom (no key):** Examine the mirrors → see the hiding spot → examine the corner → find the key. 2. **Bathroom (with key):** Examine the mirrors again → the hiding spot option is gone. 3. **Kitchen (no key):** Search the cabinets → no option to unlock the drawer appears. 4. **Kitchen (with key):** Search the cabinets → the _Unlock the drawer_ option appears → find the ring. ## Deeper dive into branches Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Deeper dive into branches In the following section of this page, we'll explore `elseif` statements and additional logic variants you can use to build more complex branching structures. Video: https://www.youtube.com/watch?v=gUI5Dm_pG2Y ## Add alternative drawer action Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Add alternative drawer action In the sections above, we added the ability to unlock a drawer if the player carries a key. Now we'll add an alternative action, using brute force, for players who don't have the key. There are two approaches to this, and which one you choose depends on the experience you want to create. ### Only if without key Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Add alternative drawer action > Only if without key In this approach, players who have the key can only unlock the drawer and players without the key can only attempt to force it open. 1. Add a new element to your board and give it the title _Brutally nothing._ 2. Connect the _Searching cabinets_ element to a branch that checks whether the player carries the key: `if has_key`. 3. Add an `else` statement to that branch and connect it to the _Brutally nothing_ element. 4. Update your labels so the `if` path reads _Unlock the drawer_ and the `else` path reads _Use brute force._ ### Brute force always available Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Add alternative drawer action > Brute force always available In this approach, brute force is always available to the player, but unlocking the drawer is only shown if they have the key. Assuming you've first taken the previous steps: 1. Connect the _Brutally nothing_ element directly from _Searching cabinets,_ bypassing the key-checking branch entirely. 2. Remove the `else` statement from the branch. (Right-click the branch and select "Remove else.") > ✅ It depends on the player experience you want to create: think about what you want the player to be able to do at each point in the story and place your branches accordingly. ## State machine Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > State machine Now that the player can find a ring by unlocking the drawer, we need to track whether they've found it, otherwise they'll be able to keep searching and finding it indefinitely. Instead of a simple boolean (`has_ring`, `true` or `false`), we'll use an **integer**, so the ring can have multiple meaningful states. 1. Go to **Global variables** and click **+ New variable**. 2. Name it `ring_state`. 3. Set the type to **Integer**. 4. Set the initial value to `0`. Use the following values to represent each state: | Value | State | | ----- | ---------------------------------------- | | `0` | The ring has not been found yet | | `1` | The player has taken the ring | | `2` | The player has given the ring to someone | > ✅ You can keep this list of states on a note on your board, to remind your future self or other collaborators what each value means. ### Set ring state Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > State machine > Set ring state When the player finds the ring, you need to update `ring_state` to `1`: 1. Select the element where the player discovers the ring. 2. Add an Arcscript segment using the **Arcscript** icon in the formatting menu (or press **Ctrl/Cmd+Shift+C**). 3. Type the following: `ring_state = 1`. Your element may look like this: ```arcweave-html You unlock the drawer and find... Wow! This ring must be half a carat... Not that you know much about carats. ring_state = 1 ``` ### Handle all ring states Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > State machine > Handle all ring states Rather than simply blocking the search option once the ring is found, we can keep it available but have it return a different response depending on the ring state. We can do this with an `elseif` statement: 1. Connect the _Kitchen_ element to a new branch and label the connection _Search the cabinets._ 2. Set up the following conditions: - **If** `ring_state == 0` → Proceed normally. The player searches and may find the ring. - **Else if** `ring_state == 1` → Show a response like: _"You are already carrying the ring."_ Then return to the kitchen. - **Else** (covers `ring_state == 2`) → Show a response like: _"You've given the ring away."_ Then return to the kitchen. This branch covers all possible outcomes (`0`, `1`, or `2`), so the _Search the cabinets_ option is always visible to the player. It is the response that changes based on what has already happened in the story. ![Arcweave project environment showing the flowchart section including Kitchen, searching the cabinets, and opening the drawer to find the ring, along with their alternative outcomes.](https://docs.arcweave.com/assets/basic-kitchen.CmR8cB42.png) > ✅ Color-code your elements to make the flow easier to read at a glance: mark the outcomes of _already have ring_ and _ring given away_ in red, since they block action and don't advance the plot. ## Create ring-giving scene Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Create ring-giving scene Now let's set up a scene where the player can give the ring to a character. This switches the ring state to `2`. ### Create ring-giving element Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Create ring-giving scene > Create ring-giving element 1. Create a new element next to the _Living room_ element: _Horace takes the ring._ 2. Add Horace's picture as the element cover if you have one. 3. Add an Arcscript segment: `ring_state = 2` The element can have content similar to the following: ```arcweave-html Horace clears his throat, startling you. You didn't see him standing by the curtain. "Um... Did you by any chance find my grandmother's ring?" "I did," you reply and you give him the ancient heirloom. He pockets it. "Thanks. Stick around for as long as you like," he says generously, "But do leave, eventually." ring_state = 2 ``` ### Scene conditions Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Create ring-giving scene > Scene conditions The scene where the player gives the ring to Horace should only appear when the player is carrying the ring (i.e., `ring_state == 1`) and travels from the kitchen to the living room. 1. Add a **branch** on the path that goes from the kitchen to the living room. 2. Set up the conditions as follows: - `if ring_state == 1`: Connect to the _Horace takes the ring_ element. - `else`: Connect directly to _Living room._ 3. Add an output connection from _Horace takes the ring_ to _Living room._ ## Test the full flow Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > Test the full flow Run the project from the beginning. Keep the Debugger open and verify the following: 1. Without the key, only the brute force option appears when searching the cabinets. 2. After finding the key, you get the option that you expect, based on your choice between the [suggestions above](https://docs.arcweave.com/tutorials/basic/pt-11#add-alternative-drawer-action). 3. After unlocking the drawer and taking the ring, `ring_state` becomes `1`. 4. Searching the cabinets again returns the _"already carrying the ring"_ message. 5. Returning to the living room with the ring triggers the scene where _Horace takes the ring,_ while `ring_state` becomes `2`. 6. Searching the cabinets after giving the ring away returns the _"you've given the ring away"_ message. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 11: Branches > What's next You've now built a multi-state story variable with `elseif` logic that responds to everything the player has done. In the next tutorial, you'll explore how to manipulate text responses with logic directly, without needing to create separate branches for each outcome. # Basic Arcweave tutorial | Part 12: Text with logic Source: https://docs.arcweave.com/tutorials/basic/pt-12 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on writing conditional text in Arcweave projects Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. Add logic to an [element](https://docs.arcweave.com/project-items/elements)'s text content. ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 12: Text with logic > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=UkWDo_sZPP0 > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Text with logic Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 12: Text with logic > Text with logic In the previous part of this tutorial, you learned how to use branches to control narrative flow with `if`, `elseif`, and `else` statements. In this part, you'll learn how to write Arcscript logic **inside element content** to dynamically change the text a player sees. This is a classic technique in interactive fiction. A location description can differ depending on whether it's day or night, or whether the player is visiting for the first time or not. This helps the game stay fresh and avoid annoying levels of repetition. In our tutorial game, we'll use variables to shape NPC dialogue based on the player's earlier choices. ## New variable Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 12: Text with logic > New variable We want to track whether the player has taken a shower before their appointment. To do this, we need a new variable. 1. Open the **Global variable dialog**. 2. Create a new variable named `shower_taken`. 3. Set its type to **Boolean**. 4. Set its initial value to **false**. ## Variable assignment Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 12: Text with logic > Variable assignment Now we need to assign `true` to `shower_taken` when the player chooses to shower. 1. Navigate to the _Beginning_ board and locate the element where the player takes a shower (for example, _Take a shower_ from [Part 2](https://docs.arcweave.com/tutorials/basic/pt-2#create-choices)). 2. Open the element and add a code segment at its end: `shower_taken = true` 3. Connect the shower element to the element where the player arrives at the apartment (_Horace opens the door_ in [Part 9](https://docs.arcweave.com/tutorials/basic/pt-9#connect-the-boards)), so the player can proceed to the appointment after showering. Also make sure that the path that skips the shower leads directly to the same apartment-arrival element. This way, both paths are available to the player: with shower or without. ## Conditional element text Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 12: Text with logic > Conditional element text Now let's make the dialogue at the apartment door (the _Horace opens the door_ element) react to whether the player has showered. ![An element in edit mode. An orange rectangle emphasizes the Arcscript button in the rich text formatting menu. A similar rectangle emphasizes a paragraph formatted as Arcscript code segment inside the element's text content.](https://docs.arcweave.com/assets/element-edit-arcscript.tIg7kegi.png) > ✅ You already know how to add Arcscript segments by clicking **Arcscript** (the **<>** icon in the formatting menu). You can do the same using the keyboard: press **Ctrl+Shift+C** or **Cmd+Shift+C**. So, the content of the _Horace opens the door_ element can be: ```arcweave-html Horace Linetti opens the door and lets you in. if shower_taken "You're late!" he says. else "Good Lord! You smell as if you've spent the night on an office floor," he says, fanning the air with his hand. endif You enter the apartment. As you marvel at the design of the living room, he disappears towards the bedrooms. "Let me know if you find my grandmother's ring," he hollers. ``` > ⚠️ Every `if` statement must be closed with a respective `endif` or Arcweave will display an error symbol at the element's bottom-right corner. > ✅ Notice how Arcweave takes care of conditional text's indentation. Any rich text that is enclosed by `if` and `endif` is automatically indented. ## Test Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 12: Text with logic > Test Let's test what we've built. Set the first element of the _Beginning_ board as the starting element (**Play Mode > Set Play Mode start**) and enter Play Mode. Try both paths: 1. **Skip the shower**: Go straight to the appointment and knock the door. Horace lets you in, commenting on your odor. 2. **Shower first**: Take the shower, go to the appointment, and knock the door. Horace says _"You're late."_ ## Paragraph breaks Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 12: Text with logic > Paragraph breaks You may notice that text on either side of a code segment renders on the same line, forming one large paragraph. This happens because **code segments do not automatically insert a paragraph break**. To control where breaks appear, manually press **Enter** before or after the `if` expression. Until you are more experienced, it will take some testing to see what works best for each case. ## Nested `if` statements Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 12: Text with logic > Nested `if` statements Arcscript supports nested `if` statements: `if`/`endif` blocks placed inside other `if`/`endif` blocks. This allows you to combine multiple conditions. > ✅ We call them `if`/`endif` blocks since `if` and `endif` are the absolutely essential statements of a conditional block. `elseif`/`else` can still be part of these blocks. In this example, we'll add nested conditional text to the _Bathroom_ element: ```arcweave-html Marble and gold. You never really understood some people's extravagance. The bathtub is huge. if shower_taken It must be such a different experience from showering in one's office. if not has_key But you need to focus, see if you can find anything, here. endif else Mmm... You wonder if it's too much asking the Linettis if you could take a quick shower, here. You'd do them a favour, after all. endif ``` > ⚠️ Notice how the inner `if` block closes with its `endif` statement, before the outer `else` comes. If the inner block is left open, the `else` will be treated as belonging to the inner `if`, not the outer one. ## Logical operators Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 12: Text with logic > Logical operators You can combine multiple conditions in a single `if` statement using the logical operators `and` and `or`. ### `and` Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 12: Text with logic > Logical operators > `and` The following code shows text only if _the player has not showered_ AND _is carrying the ring_ (i.e., `ring_state` equals `1`): ```arcweave-html if not shower_taken and ring_state == 1 You may stink, but look at that ring! endif ``` _Both_ conditions must be true for the block to render. > ℹ️ The `and` keyword can also be written as `&&`. ### `or` Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 12: Text with logic > Logical operators > `or` The following code shows text only if EITHER _the player has not showered_ OR _is carrying the ring:_ ```arcweave-html if not shower_taken or ring_state == 1 ... endif ``` The block renders if _either_ condition is true. > ℹ️ The `or` keyword can also be written as `||`. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 12: Text with logic > What's next In this tutorial you learned how to assign variable values and create conditional, dynamic text. In the next tutorial, we'll explore two built-in functions that make your text and outcomes even more dynamic. # Basic Arcweave tutorial | Part 13: Functions `show` & `roll` Source: https://docs.arcweave.com/tutorials/basic/pt-13 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on Arcscript's show and roll functions for displaying text and rolling dice Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. Learn more about manipulating outcomes using two [Arcscript functions](https://docs.arcweave.com/project-items/arcscript#built-in-functions): - [`show`](https://docs.arcweave.com/project-items/arcscript#show): Render the value of a variable as text for the player to see. - [`roll`](https://docs.arcweave.com/project-items/arcscript#roll): Generate random integer numbers, imitating die rolls. The `show` and `roll` functions are two of Arcweave's core Arcscript tools for rendering dynamic content and introducing randomness into your stories. This tutorial walks you through how each function works and how to combine them to create compelling, unpredictable narrative outcomes. ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=Vxj0kyzBt8g > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## `show` Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > `show` ### Simple use Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > `show` > Simple use The `show` function renders whatever is placed inside its parentheses, inline with any surrounding text. For example: ```arcweave-html gold = 100 You now have show(gold) gold coins in your purse. ``` This renders as: _You now have 100 gold coins in your purse._ ### Multiple arguments Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > `show` > Multiple arguments Multiple arguments of `show` must be separated by a comma. Study the following example: ```arcscript name = "Burton" times_said = 100 admits = true show("My name is ", name, " and I've said it ", times_said, " times already: it is all ", admits, "!" ) ``` This renders as: _My name is Burton and I've said it 100 times already: it is all true!_ > ⚠️ Notice the spaces needed in the above syntax to properly render the sentence (as in `"My name is "`). The space character is part of a **string**, so it must be included in quotation marks. ### Line breaks Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > `show` > Line breaks If you need line breaks to be rendered before or after the `show` content, you can add them to the rich text that wraps the `show` Arcscript segment. You may also add line breaks in `show`'s arguments using the `\n` character inside a string: ```arcweave-html These are a few of my favorite things: show(raindrops, "\n", roses, "\nand whiskers on kittens.") ``` Assuming `0` and `1.5` are the values of `raindrops` and `roses` respectively, the above element renders as follows: _These are a few of my favorite things:_ _0_\ _1.5_\ _and whiskers on kittens._ ## Add player morale Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > Add player morale Let's now add `show` to our tutorial game. Suppose we want to add a morale score to our player. To do this, we will follow these steps: 1. Create a `player_morale` variable (integer). 2. When the game starts, `player_morale` will be assigned a random value. We'll do this using `roll` (see next section on this page). 3. We will introduce the morale to the player in the first couple of elements with a smooth use of `show`. ### Create morale variable Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > Add player morale > Create morale variable Create a new integer variable: 1. Go to **Global variables** and click **+ New variable**. 2. Name the new variable `player_morale`, make it an **Integer**, and give it any value to begin with. Since it will be assigned a new value at random, we won't care about the value filled in here. ### Introduce morale Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > Add player morale > Introduce morale We can introduce the morale score to the player in one of the first elements, e.g. the _Office._ Moreover, we can add a short, conditional comment by the narrator, depending on whether the value of `player_morale` is high or mediocre. > ✅ The Arcscript segment that includes the `roll` function will be explained a little further below. ```arcweave-html You rub your eyes. You are on the floor. Your office. It's midday. And you have work to do. You start with a morale of player_morale = roll(6, 3) show(player_morale, ".") if player_morale < 12 It's not that great, to be honest, but you have to work with what you've got. elseif player_morale >= 12 and player_morale < 18 It's a pretty good morale to start with. else You feel really elevated! endif Going through your diary, you see that you can barely make it on time for your appointment with the Linetti siblings. Something about a lost heirloom. You can read their folder while on the bus. But you must go, now! Still, you stink... ``` ### Reassign and `show` Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > Add player morale > Reassign and `show` During the game, whenever `player_morale` changes, you can use an assignment expression followed by a call to `show`, to update the morale score and notify the player of the change. For example: ```arcscript player_morale -= 2 show("Your morale is now ", player_morale, ".") ``` ## `roll` Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > `roll` The `roll` function generates a random integer in the style of tabletop RPG dice rolls. ### `roll(m)` Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > `roll` > `roll(m)` `roll(m)` returns a random number between `1` and `m` (inclusive), equivalent to rolling an `m`-sided die (d`m`). For example, `roll(6)` simulates rolling **1d6** (a 6-sided die). ### `roll(m, n)` Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > `roll` > `roll(m, n)` `roll(m, n)` is equivalent to rolling `n` `m`-sided dice and adding the results together. Therefore, the number returned is between `n` and `m * n`. Example: `roll(6, 3)` simulates rolling **3d6**, which is the classic roll for ability scores in _Dungeons & Dragons._ > ⚠️ Note that the probability distribution when rolling multiple dice is not uniform, but forms a bell curve, since most results cluster around the average. ### Assign initial morale Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > `roll` > Assign initial morale As we saw in the element above, to randomly assign the initial morale value, we use: ```arcscript player_morale = roll(6, 3) ``` Let's see a few more ways we can use `roll` in our game. ### Randomize stat changes Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > `roll` > Randomize stat changes Instead of deducting a fixed number of morale points, you can deduct a random amount: ```arcscript player_morale -= roll(4) ``` This deducts a random value between `1` and `4`. If you want a minimum result of `0` instead of `1`, roll one die size higher and subtract `1`: ```arcscript player_morale -= roll(5) - 1 ``` ### Store `roll` results Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > `roll` > Store `roll` results To track the result of a roll in the debugger, assign it to a dedicated variable first: ```arcscript roll_result = roll(5) - 1 player_morale -= roll_result ``` After you create `roll_result` as a global **Integer** variable (in **Global variables**, like `player_morale`), you can watch its value change in the debugger panel as you replay the project. Moreover, storing the `roll` result in a `roll_result` variable lets you reuse it repeatedly in conditions, such as in branches. ## `roll` in branches Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > `roll` in branches Beyond modifying stats, `roll` is useful for making events happen with some randomness. To do this, you need to roll and then check all possible results in a branch, diverting the flow accordingly. ### A warning Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > `roll` in branches > A warning Consider the following branch: - `if roll(4) == 1`... - `elseif roll(4) == 2`... - `elseif roll(4) == 3`... - `else`... Can you tell what is wrong with it? The problem with the above branch is that, instead of rolling once and comparing the result with each of the possible numbers `1`, `2`, `3`, and `4`, each condition includes a _new call_ to `roll`, which generates a _new result._ This produces unpredictable branch behavior. ### Store the `roll` result Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > `roll` in branches > Store the `roll` result This is where storing the `roll` result is important. Instead of calling `roll` in the branch, call it in the content of any element _before_ the branch, storing the result in the `roll_result` variable. You can do this with just one Arcscript segment: ```arcscript roll_result = roll(4) ``` Then, connect this element with the branch and check the value of `roll_result` against all possible roll outcomes: - `if roll_result == 1`... - `elseif roll_result == 2`... - `elseif roll_result == 3`... - `else`... ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 13: Functions `show` & `roll` > What's next Use `show` to display variable values to the player and `roll` to introduce chance for stat changes, character encounters, or any outcome you want to leave to fate. The next tutorial will teach you how to share and export your project. # Basic Arcweave tutorial | Part 14: Share & export Source: https://docs.arcweave.com/tutorials/basic/pt-14 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on sharing and exporting your Arcweave project Learn how to [share](https://docs.arcweave.com/project-tools/share) and [export](https://docs.arcweave.com/project-tools/export) your project and get a glimpse of Arcweave's real-time [collaboration](https://docs.arcweave.com/introduction/quick-tour/collaboration). ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 14: Share & export > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=x3wEiJdyaT8 > ⚠️ This video does not reflect the latest updates to sharing and exporting your project, as each of these two features now has its own button in the menu. See [Share](https://docs.arcweave.com/project-tools/share) and [Export](https://docs.arcweave.com/project-tools/export) pages for more details. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Project visibility Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 14: Share & export > Project visibility By default, an Arcweave project is **private**, meaning it can only be accessed and played by the members of its workspace. ### Make a project public Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 14: Share & export > Project visibility > Make a project public You can change a project's visibility, so it is accessible by anyone for play or study: 1. Click **Share** in the top menu. 2. In the Share modal, use the dropdown at the bottom next to "Anyone with the link..." to control public access. Select one of the following options: - **Can view & play**: Grants access to both the project's boards and Play Mode. - **Can play only**: Grants access only to the project's Play Mode. - **Has no access**: Prevents any public access to the project. 3. Click **copy link**, under **Anyone with the link**, to copy the project's URL to your clipboard for sharing. ![Arcweave's project screen showing the Share modal](https://docs.arcweave.com/assets/share-public.-msafp79.png) > ✅ The option **can play only** is especially useful if you want to let the public play your game without revealing what's under the hood. > ℹ️ Users accessing a project through a public link are called [project visitors](https://docs.arcweave.com/workspaces/roles#project-visitors). They do _not_ need an Arcweave account to view or play the project. ### Share with collaborators Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 14: Share & export > Project visibility > Share with collaborators If you'd rather keep the project private but share it with select people, you can invite them to become either **editors** or **commenters**. ![The Arcweave window showing an open project and its "Share" modal. The modal allows the user to invite more collaborators to the project and to configure the project's private or public state.](https://docs.arcweave.com/assets/share.Dygv2dx1.png) To invite a user to a project: 1. Click **Share** in the top menu. 2. Enter their email under **Email address**. 3. Choose a role: **Commenter** or **Editor**. 4. Click **Invite**. > ℹ️ Such project collaborators are called [guests](https://docs.arcweave.com/workspaces/roles#workspace-guests). > ⚠️ Guest editors count toward billing (1 seat each). See more on [adding](https://docs.arcweave.com/workspaces/billing-plans#add-seats) and [removing seats](https://docs.arcweave.com/workspaces/billing-plans#remove-seats) on the **Workspace plans** page. ### Remove collaborators Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 14: Share & export > Project visibility > Remove collaborators To remove someone's access, go back to the sharing panel and remove them from the project. ## Share a specific item Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 14: Share & export > Share a specific item To point a collaborator to part of your story, right-click an element on the board and select **Copy link**. Make sure only that element is selected. Paste the copied URL into your message; opening it centers the element in the language you were viewing. The recipient needs access to the project's boards. You can also copy links to boards, jumpers, notes, branches, connections, and components. See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position) for their menu locations. ## Real-time collaboration Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 14: Share & export > Real-time collaboration Editors can collaborate on a project in real time. While an invited editor is working, you'll see their cursor move around the board as they make changes. You're free to keep working elsewhere in the project at the same time. ## Export options Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 14: Share & export > Export options To export your project, click **Export project** (the download icon) in the top menu. You'll find the following formats to choose from: - [JSON](https://docs.arcweave.com/project-tools/export#export-as-json): Exports a JSON file of the project. JSON is a generic format for storing the project's data, and it's the way to go if you want to use the project further down the line. (Also see **Game engine JSON**, below.) - [Spreadsheet](https://docs.arcweave.com/project-tools/export#export-as-spreadsheet): Exports the project in CSV or Excel (Pro & Team workspaces only) format. - [Image](https://docs.arcweave.com/project-tools/export#export-as-image-file): Exports a board as image file. - [Game engine JSON](https://docs.arcweave.com/project-tools/export#export-for-game-engines): Exports a JSON file for the popular game engines Unity, Unreal Engine, and Godot Engine. - [Markdown](https://docs.arcweave.com/project-tools/export#export-as-markdown): Exports the project as a Markdown document (Pro & Team workspaces only). - [PDF](https://docs.arcweave.com/project-tools/export#export-as-pdf): Exports a board as PDF (Pro & Team workspaces only). - [Backup](https://docs.arcweave.com/project-tools/export#export-project-backup): Exports a backup of the project in `.arcw` format (Pro & Team workspaces only). > ✅ The **JSON** and **Game engine JSON** exports provide the option to also export the project's **assets**. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 14: Share & export > What's next You now know how to control who can access your project and how to export it for use elsewhere, whether that's sharing a playable link, bringing in collaborators, or pulling the project's data into another tool. In the next part of this series, we'll do some housekeeping on our tutorial project and add its finishing touches. # Basic Arcweave tutorial | Part 15: Polish the project Source: https://docs.arcweave.com/tutorials/basic/pt-15 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on polishing the project and tying up loose ends Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. Polish this tutorial's project: delete unused [boards](https://docs.arcweave.com/project-items/boards), merge [elements](https://docs.arcweave.com/project-items/elements), and make better use of the morale score system. ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=yJTKE05fMN8 > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). --- ## Clean up the project Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Clean up the project To clean up the project, you can: - Delete any "dummy" elements or boards used purely for demonstration. - Delete any empty boards. - Remove unused formatting. - Delete unused variables. For example, the `roll_result` variable we used earlier to deduct from the player's morale is no longer needed once we change how morale is calculated (see below). ## Initial morale Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Initial morale If you followed [Part 13](https://docs.arcweave.com/tutorials/basic/pt-13#add-player-morale), your starting element already rolls the player's initial morale. This section puts that setup together. If your project still assigns a fixed value instead, replace it with a dice roll. ### Roll for initial morale Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Initial morale > Roll for initial morale In the element where morale is first set, replace the fixed value with a dice roll: ```arcscript player_morale = roll(6,3) ``` This rolls **three six-sided dice** and assigns the result to `player_morale`. ### Show initial morale Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Initial morale > Show initial morale Next, let's render the result to the player. In the element's text, show the value and add some text that introduces it: ```arcweave-html You start with a morale of show(player_morale, ".") ``` ### Morale commentary Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Initial morale > Morale commentary We can let the game comment on the player's initial morale, by adding some conditional text: ```arcweave-html if player_morale < 12 It's not that great, to be honest, but you have to work with what you've got. elseif player_morale >= 12 and player_morale <18 It's a pretty good morale score to start with. else Perfect morale score! You feel super elevated! endif ``` ### Put it all together Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Initial morale > Put it all together Putting all of the above together, the starting element looks like this: ```arcweave-html You rub your eyes. You are on the floor. Your office. It's midday. And you have work to do. You start with a morale of player_morale = roll(6,3) show(player_morale, ".") if player_morale < 12 It's not that great, to be honest, but you have to work with what you've got. elseif player_morale >= 12 and player_morale <18 It's a pretty good morale score to start with. else Perfect morale score! You feel super elevated! endif ``` > ✅ Test this in Play Mode. Due to the initial value being randomized, you'll see different outcomes each time you restart the story. ## Add morale check Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Add morale check There's not much point in having a stat like morale if it never affects anything. Let's add a **morale check** at a key moment in the story: when Horace opens the door and comments on the player being late (or dirty). ### Add a penalty Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Add morale check > Add a penalty First, let's add a penalty for not having showered. Inside the element where Horace opens the door, type: ```arcweave-html Horace Linetti opens the door and lets you in. if shower_taken "You're late!" he says. else "Good Lord! You smell as if you've spent the night on an office floor," he says, fanning the air with his hand. player_morale = player_morale - 2 endif ``` ### Roll the check Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Add morale check > Roll the check Next, we add the actual check: we'll roll a 20-sided die and compare it against the player's morale. As an extra rule, if the player has maximum morale (18), the check is considered a success. Add the following to the element content: ```arcweave-html if player_morale >= roll(20) or player_morale == 18 You enter the apartment. As you marvel at the design of the living room, he disappears towards the bedrooms. "Let me know if you find my grandmother's ring," he hollers. else You freeze with shame. Without a word, you turn around and leave. endif ``` ### Store the result Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Add morale check > Store the result Right now, the outcome of the check only affects the text shown inside that one element; it does not affect the options or the rest of the story. To fix this, we need to store the result in a **variable** so we can evaluate it anywhere else needed. 1. Create a new **Boolean** variable called `morale_check_success`, with initial value set to `false`. 2. Inside the element content, plant accordingly the assignment of the `morale_check_success` variable: ```arcweave-html if player_morale >= roll(20) or player_morale == 18 morale_check_success = true You enter the apartment. As you marvel at the design of the living room, he disappears towards the bedrooms. "Let me know if you find my grandmother's ring," he hollers. else morale_check_success = false You freeze with shame. Without a word, you turn around and leave. endif ``` > ✅ For safety, explicitly set the variable to `false` in the `else` branch, even if `false` is also its initial value. --- ### Complete element content Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Add morale check > Complete element content So, the complete element content is now: ```arcweave-html Horace Linetti opens the door and lets you in. if shower_taken "You're late!" he says. else "Good Lord! You smell as if you've spent the night on an office floor," he says, fanning the air with his hand. player_morale = player_morale - 2 endif if player_morale >= roll(20) or player_morale == 18 morale_check_success = true You enter the apartment. As you marvel at the design of the living room, he disappears towards the bedrooms. "Let me know if you find my grandmother's ring," he hollers. else morale_check_success = false You freeze with shame. Without a word, you turn around and leave. endif ``` ### Branch the outputs Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Add morale check > Branch the outputs After this element, add a **branch** that evaluates the `morale_check_success` variable and diverts the flow accordingly: - If `true` → You continue to the living room. - If `false` → You walk away. > ✅ Test it in Play Mode with **Debug** mode turned on so you can watch the variables update in real time. Try it both with and without showering to confirm both outcomes work as expected. ## Reset variables on restart Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Reset variables on restart If your project has restart jumpers (see [Add restart jumpers](https://docs.arcweave.com/tutorials/basic/pt-9#add-restart-jumpers) in Part 9), be careful: once your project has several variables, jumping straight back to the start without resetting them can cause the story to behave incorrectly. (The **Restart** button in Play Mode's menu already resets all variables and visits.) Not every variable should be reset, though. For example, a variable that counts how many times the player has died should usually persist across restarts, since that's the entire point of tracking it. In this project, however, we want a clean slate every time, so in the story's starting element we reset: - `morale_check_success`: No need to reset; it gets recalculated before it's used. - `player_morale`: No need to reset; it gets recalculated before it's used. - `shower_taken`: Reset to `false` - `ring_state`: Reset to `0` - `has_key`: Reset to `false` Since resetting the first two variables does no harm, you can reset all of them at once: add an Arcscript segment with `resetAll()` at the top of the starting element's content. `resetAll()` resets every global, board, and component variable to its initial value; to keep some of them unchanged, pass them as arguments, e.g. `resetAll(player_morale)`. It does not reset element visits; use `resetVisits()` for that. ## Simplify unnecessary branches Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Simplify unnecessary branches Branches are useful when they affect the **flow** of the story or the player's available actions. They're overkill, however, when their only job is to change which text gets rendered; that's a job for code _inside_ an element instead. In the bathroom, for example, there is a branch diverting to two nearly identical elements. Their only difference is the displayed text depending on whether the player has picked up the key. We can simplify this by merging the two elements into one and using Arcscript in the element's content to create conditional text: ```arcweave-html Two identical mirrors over two identical sinks. You wonder whether the siblings have to do everything simultaneously. if !has_key Hey, wait a second. These two mirrors are not positioned fully flat on the wall. They actually... When you stand at the centre of the room, they both reflect the same corner: the top part of the door. endif ``` Afterwards, we need to fix the option of examining the door, so it doesn't happen again and again. Add a new branch after the above element that checks whether the player already has the key: - `if not has_key` → Go to the element where the key is found. > ✅ The branch only has an `if` statement. If the player already has the key, there is no other option than to go back. Play through this section again to confirm that examining the mirrors behaves correctly whether or not the player has already found the key. ## Adding a project cover Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > Adding a project cover As a final polishing touch, let's give the project a cover image: 1. Exit the project by clicking the **Workspace** icon at the top left of your window. 2. Find your project thumbnail in the list, click the three dots **•••**, and select **Upload cover**. 3. Select an image from your drive and upload it. Your project now has a cover, which will be shown in your project list and when sharing the project with others. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 15: Polish the project > What's next This project is now finished! The following pages and their videos demonstrate more features, the next one being importing & exporting projects in a [Pro or Team](https://docs.arcweave.com/workspaces/billing-plans) workspace. # Basic Arcweave tutorial | Part 16: Import & export project Source: https://docs.arcweave.com/tutorials/basic/pt-16 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on importing and exporting Arcweave projects If you are an [owner or editor](https://docs.arcweave.com/workspaces/roles#workspace-members) in a [Pro or Team](https://docs.arcweave.com/workspaces/billing-plans) workspace, you can export any of its projects as an `.arcw` file. This format is a project backup, which you can later re-import into any Pro or Team workspace. This page also includes some project exporting & sharing features not included in [Part 14: Share & export](https://docs.arcweave.com/tutorials/basic/pt-14) of this tutorial. ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 16: Import & export project > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=ElCzGpCzn-A > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Export project backup Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 16: Import & export project > Export project backup To save a backup of your project to your drive: 1. Open the project. 2. Click **Export project** (the download icon) in the top menu. 3. Choose **Backup**. 4. Click **Export** and save the file to your drive. > ℹ️ This option is available to [owners and editors](https://docs.arcweave.com/workspaces/roles#workspace-members) of [Pro and Team](https://docs.arcweave.com/workspaces/billing-plans) workspaces only. ## Import project backup Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 16: Import & export project > Import project backup To import a project as an `.arcw` file: 1. Go to the **Projects** section of your workspace. 2. Click the **Import** button at the top right. 3. Choose **Arcweave File**. 4. Select the `.arcw` file from your device and upload it. ![The Projects section of an Arcweave workspace, with an orange arrow pointing at the "Import" button at the top right of the screen.](https://docs.arcweave.com/assets/import-project.CzEYalxL.png) Once the import is complete, the project will appear in your workspace's **Projects** section, prefixed with _Restored -_. You can rename it as you wish. > ℹ️ This option requires [Import projects permission](https://docs.arcweave.com/workspaces/roles#list-of-permissions) in a [Pro or Team](https://docs.arcweave.com/workspaces/billing-plans) workspace. ## Import JSON file Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 16: Import & export project > Import JSON file To import a project as a JSON file: 1. Go to the **Projects** section of your workspace. 2. Click the **Import** button at the top right. 3. Choose **JSON File**. 4. Select the `.json` file from your device and upload it. > ℹ️ This option requires [Import projects permission](https://docs.arcweave.com/workspaces/roles#list-of-permissions) and is available in all workspaces, subject to their project and item limits. ## Export JSON without assets Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 16: Import & export project > Export JSON without assets A simple but convenient feature, available to all users including [owners and editors](https://docs.arcweave.com/workspaces/roles#workspace-members) of [Basic](https://docs.arcweave.com/workspaces/billing-plans) workspaces, is the ability to export your project data as a JSON file without also downloading all of the project's assets. To do this: 1. Open the project. 2. Click **Export project** (the download icon) in the top menu. 3. Choose **JSON**. 4. Deselect the **Include assets** checkbox. 5. Click **Export** and save the file to your drive. > ✅ If you export to JSON often, this saves you from the unnecessary asset downloads. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 16: Import & export project > What's next You now know how to back up your projects via import and export, as well as how to export JSON files without assets. In the next tutorial, we'll continue exploring some features of project editing. # Basic Arcweave tutorial | Part 17: More project features Source: https://docs.arcweave.com/tutorials/basic/pt-17 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on quality-of-life improvements in Arcweave's project environment This tutorial covers several quality-of-life improvements available in Arcweave's project environment: - Alternative [ways to create jumpers](https://docs.arcweave.com/tutorials/basic/pt-17#ways-to-create-jumpers) - [Component references](https://docs.arcweave.com/tutorials/basic/pt-17#component-references) - [Creating components by mentioning](https://docs.arcweave.com/tutorials/basic/pt-17#create-components-by-mentioning) - [Sticky connections](https://docs.arcweave.com/tutorials/basic/pt-17#sticky-connections) (Connections that stick to a specific side of an element) - [Automatic and manual height](https://docs.arcweave.com/tutorials/basic/pt-17#automatic-manual-item-height) of elements and notes - [YouTube video embeds as element covers](https://docs.arcweave.com/tutorials/basic/pt-17#youtube-embeds-as-element-covers) ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 17: More project features > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=qAyNvVja90s > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Ways to create jumpers Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 17: More project features > Ways to create jumpers There are 3 ways to create a non-empty jumper in Arcweave. ### Create jumpers from Boards section Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 17: More project features > Ways to create jumpers > Create jumpers from Boards section The first way to create a jumper (and the way we've already mentioned) is to drag an element from the **Boards section** of the left sidebar into an empty area of the board. Use this method when you have located the target element in the left sidebar. 1. Go to the **Boards** section of the left sidebar. 2. Find the board where the desired element is. 3. Expand the board by clicking on the drop-down arrow next to its icon. 4. Find the element by its name. 5. Drag and drop the element into the empty jumper (or an empty area of the board). ### Create jumpers from Search field Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 17: More project features > Ways to create jumpers > Create jumpers from Search field If you don't know where the target element is, look it up in Arcweave's **Search**. Then, you can drag it from the search results into the board: 1. Click **Search project** at the right side of the top menu. 2. Look up the desired element, typing part of its text content or title in the search field. 3. From the search results, drag the element into an empty area of the board. ### Create jumpers by pasting Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 17: More project features > Ways to create jumpers > Create jumpers by pasting When you can easily access the target element in a board, you don't need to search for it again. Instead, you can copy and paste it as jumper: 1. In the board, click the element to **select** it. 2. Copy the element: - Press **Ctrl/Cmd + C** or - Right-click and select **Copy** from the menu. 3. Paste as jumper: - Right-click an empty area of the board and select **Paste as jumper** from the menu or - Press **Ctrl/Cmd + Shift + V**. > ✅ Arcweave has a long list of [keyboard shortcuts](https://docs.arcweave.com/project-tools/interface/keyboard-shortcuts). Make sure you check them out! ## Component references Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 17: More project features > Component references In [Part 5 of this tutorial](https://docs.arcweave.com/tutorials/basic/pt-5), you learned how to attach components to elements and other components. In [Part 6](https://docs.arcweave.com/tutorials/basic/pt-6) you learned how to mention a component in rich text content. Overall, you can attach or mention components in the following items: - **Elements** - Attach to element - Mention in element content - Mention in element title - **Components** - Attach to component list attribute - Mention in content of rich text attribute - **Labels** - Mention in label text - **Notes** - Mention in note content As the component attachments and mentions increase, it can be useful to see a report of everywhere a given component appears: 1. Go to the **Components** list in the left sidebar. 2. Right-click a component and select **References**. This shows every element, component, connection label, and note where the selected component is attached or mentioned. Clicking any entry in the list takes you directly to the item that includes the reference. ## Create components by mentioning Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 17: More project features > Create components by mentioning You already know how to mention an existing component in the rich text of an element, note, label, or attribute. What you may not know is that **mentioning a non-existing component will create it**. For example, typing `@dead_frog` in an element's text shows an option to create a new component called **dead frog**. Pressing Enter creates the component automatically, and it becomes immediately available in your Components list. > ✅ Use an underscore in place of a space when typing a multi-word mention. ## Sticky connections Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 17: More project features > Sticky connections By default, connections between board items automatically reposition themselves, moving from side to side, or top to bottom, when you reposition the items in relation to each other. ### Make connections sticky Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 17: More project features > Sticky connections > Make connections sticky To make a connection **stick to a specific side** of an element, a jumper, or a branch instead: 1. Grab the connection's arrowhead or tail. 2. Drag it **close to the edge** of the item (not into the body of the item), until you see an **orange border highlighting that side**. 3. Drop it there. The connection now stays fixed to that side of the item, regardless of how you reposition the connected items. ### Revert connections to auto Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 17: More project features > Sticky connections > Revert connections to auto To revert a connection to its default, automatic behavior: 1. Grab the connection's arrowhead or tail. 2. Drag it **into the body** of the item (not just the side) until the **entire border is highlighted in orange**. 3. Drop it there. The connection returns to its automatic state. ## Automatic / manual item height Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 17: More project features > Automatic / manual item height New elements and notes automatically adjust their height to fit their text content. You can however manually resize an element or note to a specific height: - Drag the top or bottom side. - Drag a corner in a way that also changes the height. > ✅ A scroll bar appears if the content exceeds the visible area. To revert to automatic height, **double-click the orange border** of the element or note. This resizes the item to fit its content and returns it to "auto" height behavior. ## YouTube embeds as element covers Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 17: More project features > YouTube embeds as element covers You can embed a YouTube video directly as an element's cover. 1. Right-click the element and choose **Cover > Set cover**. 2. Select the **Embed** tab. 3. Paste the YouTube video's link in the respective field. 4. Select whether the video should **Autoplay** when the element loads and whether player controls should be available to the viewer (**Show controls**). 5. Click **Embed Video**. The video's YouTube thumbnail is used as the element's cover. In Play Mode, the video plays directly over the element's content and any attached components. This feature can be used to include a video reference alongside your content, or to build a fully interactive movie that takes advantage of Arcweave's state handling (variables and conditions) to drive the story. > ✅ Arcweave also supports [video assets](https://docs.arcweave.com/project-items/assets/video), allowing you to assign videos as element covers. Among its project templates, see **Interactive Movie Example**, which demonstrates this feature. # Basic Arcweave tutorial | Part 18: Comments Source: https://docs.arcweave.com/tutorials/basic/pt-18 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on posting and replying to Arcweave user comments Learn how to use [comments](https://docs.arcweave.com/project-items/comments) in Arcweave projects, to collaborate with your team. ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 18: Comments > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=RQn9FRKmsM0 > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Create a comment Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 18: Comments > Create a comment There are two ways to create a comment: 1. Right-click anywhere on a board and choose **Create > Comment**. 2. Drag the comment icon (which looks like a speech balloon) from the bottom toolbar into anywhere inside your board. ![Arcweave's project environment. An orange arrow shows how to drag a new comment using the "new comment" icon, at the bottom menu.](https://docs.arcweave.com/assets/comments-drag.Cmgj1YXP.png) Once created, you can start typing your comment right away. When you're done, either click **Post**, or press **Ctrl+Enter** (Windows) / **Cmd+Enter** (Mac). ## Manage comments Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 18: Comments > Manage comments Comments are flexible and can be managed directly on the board: - **Open** a comment by clicking it on the board or the [Comments list](https://docs.arcweave.com/tutorials/basic/pt-18#comments-list). - **Move** a comment by dragging it around the board. - **Select** a comment with a rectangle selection. (Clicking opens it.) - **Cut and paste** a comment to relocate it. - **Reply** to a comment to keep a conversation going. - **Edit** a comment or a reply at any time. - **Delete** a reply, or an entire comment thread. ![Arcweave's project environment. Two orange arrows point at a comment pin in the board and at the comment in the sidebar. Clicking on either opens the comment.](https://docs.arcweave.com/assets/comments-open.CKSZB69L.png) ### Resolving a thread Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 18: Comments > Manage comments > Resolving a thread Once a thread of comments has been addressed, you can mark it as resolved by ticking the **Resolve thread** icon. A checkmark will then appear on the comment's icon to indicate its resolved status. ## Comments list Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 18: Comments > Comments list ![Arcweave's project environment, with orange arrows pointing at the Comments icon (opening the comments sidebar) and the "create new comment" icon at the bottom menu. An orange rectangle shows two comment pins in the current board, one resolved and one unresolved. A comment pin looks like the speech bubble icon. A resolved comment pin (when visible) is of a darker color than the unresolved one.](https://docs.arcweave.com/assets/comments-general.Dlfmw-tR.png) You can find a list of all the project's comments by clicking the comment icon in the top-right menu. Any comment you create will appear here. Clicking on a comment from the list takes you directly to that comment's position on the board. Resolved comments are marked with a tick symbol in the list as well. If you'd like to omit resolved comments from the list without deleting them: 1. Click the **Filters** button in the **Comments** panel (top right). 2. Untick **Show resolved comments**. This setting also hides resolved comments on the board itself. ## Email notifications Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 18: Comments > Email notifications The **Comment notifications** icon, at the top left of the **Comments** panel, manages your email notifications. Choose **All comments** to receive an email whenever a collaborator posts a comment or a reply, **Mentions and replies only**, or **None**. > ℹ️ You can mention collaborators in comments. See the [Comments](https://docs.arcweave.com/project-items/comments#user-mentions) for details. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 18: Comments > What's next After getting a taste of collaborating through comments, in the next part of the tutorial you will learn about `visits`, a function that counts how many times the player has visited an element during play. # Basic Arcweave tutorial | Part 19: Function `visits` Source: https://docs.arcweave.com/tutorials/basic/pt-19 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on the function that counts element visits Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. Use [`visits`](https://docs.arcweave.com/project-items/arcscript#visits) to get the number of times an element has been loaded (i.e. _visited)_ in Play Mode. ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=95zK_2vOlmk > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Why track visits Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > Why track visits So far, to track whether the player has visited parts of the story (that is, whether they've performed specific actions or received specific pieces of information), we've been using **global variables**. The downside of this approach is that the global variables list can quickly get out of control: you end up with tons of variables, one for every story or dialogue case that needs to be checked later on, causing major clutter. To solve this issue, Arcweave offers **visits**, a function that **returns how many times the player has visited a specific element**. > ✅ For scoped alternatives to global variables, see [Board variables](https://docs.arcweave.com/project-items/variables/board) and [Component variables](https://docs.arcweave.com/project-items/variables/component). ## Demo project Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > Demo project As a demo, we'll be using a short project called _In a tavern._ You can see its boards [here](https://arcweave.com/app/project/7rEYzYG6P3) and play it below: Embedded content: https://arcweave.com/embed/7rEYzYG6P3/play ## `visits` in elements Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > `visits` in elements We can call `visits` from an element's Arcscript segments. ### Demo study: element Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > `visits` in elements > Demo study: element In the demo project _In a tavern,_ go to the **Beginning** board and find the element titled _Sigh._ Here, we have used the `visits` function in a simple way: in the dialogue with the druid, we've added an `if` statement that checks whether the player has already asked the necromancer for money. Notice the `if` statement included in its content: ```arcweave-html "I see," you sigh. if visits(asking_necromancer) > 0 "At least, I had _something_ in my pockets," says the druid, glaring at Solon. endif ``` > ℹ️ Remember: `visits` tells you how many times an element has been visited. If the visits count of the element **Asking Necromancer** is greater than `0`, this means we've already spoken to the necromancer. ### Add `visits` to elements Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > `visits` in elements > Add `visits` to elements To recreate the above element: 1. Create a new element. 2. Double click its body and type its rich text content as usual. 3. Create a new line and start an Arcscript segment (**Ctrl/Cmd + Shift + C**). 4. Type in a conditional expression that uses `visits`: e.g. `if visits()` 5. Press Enter and type some rich text, e.g. "You've already spoken with the necromancer." 6. Close with an `endif`, as you already know from [Part 12](https://docs.arcweave.com/tutorials/basic/pt-12) of this tutorial. 7. Specify the argument of `visits`, i.e. what goes between the parentheses. This will be the title of the element you want to get the visits of. This is how you fill it in: 1. Place your cursor between the parentheses of `visits()`. 2. Type the `@` character (just as you would when mentioning a component or a board). This brings up a pop-up list of elements you can choose from. 3. Continue typing to narrow down the selection, and select **Asking Necromancer**. 4. The argument will be automatically filled in (in snake case): `asking_necromancer`. ## `visits` in branches Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > `visits` in branches We can also call `visits` from inside a branch. ### Demo study: branch Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > `visits` in branches > Demo study: branch From the same element as before (titled _Sigh),_ one of the output connections leads to a branch. Its `if` condition is: ```arcscript visits(asking_necromancer) > 0 ``` This branch diverts to a new element where the player can give the Druid a pat on the back. In Play Mode, this extra line and the extra option will only appear if the player has already visited the _Asking Necromancer_ element. ### Add `visits` to branches Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > `visits` in branches > Add `visits` to branches To include a `visits` call in a branch: 1. Create a new branch. 2. Double-click its `if` condition and type an expression that uses `visits`, e.g. `visits()`... The branch already displays the `if` keyword, so don't type it. 3. Specify the argument of `visits`, i.e. what goes between the parentheses. This will be the title of the element you want to get the visits of. This is how you fill it in: 1. Place your cursor between the parentheses of `visits()`. 2. Type the `@` character (just as you would when mentioning a component or a board). This brings up a pop-up list of elements you can choose from. 3. Continue typing to narrow down the selection, and select **Asking Necromancer**. 4. The argument will be automatically filled in (in snake case): `asking_necromancer`. ## Element titles in `visits` Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > Element titles in `visits` When used as an argument of `visits`, an element's title is automatically converted to **snake_case** (i.e. all words are in lowercase, with underscores instead of spaces), while the `@` character disappears once the element is selected. This happens under the hood: what you see isn't plain text code. In fact, the function's argument becomes a **link to the source element**. Clicking it will take you directly to the element it refers to, which is very convenient. ## Simplified syntax Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > Simplified syntax As mentioned, the `visits` function returns the number of visits, which is an integer. Very often, though, we don't care about the exact count; we only care about whether an element has or hasn't been visited at all. In these cases, we can simplify the syntax. Arcweave treats zero visits as `false` and any other number of visits as `true`, so this condition... ```arcscript visits(asking_necromancer) > 0 ``` ... can be simplified to: ```arcscript visits(asking_necromancer) ``` This is still valid, and functions the same way — it's a convenient shorthand for the very common case of only caring _whether_ something has happened, not _how many times_. ## `visits` without argument Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > `visits` without argument ### First time descriptions Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > `visits` without argument > First time descriptions If you're calling `visits` from inside an element and want to reference that same element, you can call the function without any arguments. This makes it easier to add first-time descriptions in an element, i.e. text that only appears the first time the element is visited: ```arcweave-html You enter the tavern. if visits() == 1 Whoa, you've never been in such a place before! endif You approach the bartender. ``` ### Varying text per visit Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > `visits` without argument > Varying text per visit A variation of the above is creating text that differs with every visit. Let's say we expect the player to visit an element several times. If we don't want the player to keep getting the same response every time they loop back, we can modify the content based on how many times they've visited the element, using `visits` without an argument. This is done in the demo project's element titled _Ask about skeleton:_ ```arcweave-html if visits() == 1 "I see you remembered to bring your skeleton along, though. Carrying a pouch would have been too much?" elseif visits() == 2 "Are you sure the skeleton has no money?" you ask. Solon Blasphemius shrugs. else You don't bother asking him again. endif ``` ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 19: Function `visits` > What's next This was a more demanding chapter, but now you've learned one of the most powerful functions of Arcscript! In the next part of the tutorial, you'll learn how to use Arcscript in labels, as well as an alternative way to create and connect items in a board. # Basic Arcweave tutorial | Part 20: Advanced connections & labels Source: https://docs.arcweave.com/tutorials/basic/pt-20 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on advanced functionalities of connections and labels Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. This tutorial covers a few recent additions to Arcweave's **connections** and **labels**: a faster way to create new connections, and the ability to use Arcscript inside connection labels to change text dynamically or assign variables. ## Video tutorials Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 20: Advanced connections & labels > Video tutorials Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=uMaqLWjoMvQ > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Drop connections to create board items Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 20: Advanced connections & labels > Drop connections to create board items So far you have seen how to connect two existing board items (elements, branches, or jumpers): first create the items and then draw a connection from one to the other. You can also drag a new connection and **drop it directly onto an empty area of the board**. This opens a menu where you can choose to create a new element, jumper, or branch. This removes the extra step of creating the item first and then connecting it, letting you build out your diagram with single actions. > ✅ When an element is selected, you can use [keyboard shortcuts](https://docs.arcweave.com/project-tools/interface/keyboard-shortcuts#element-creation-connection) to instantly create a new connected element. Press **Ctrl + Alt/Option/Cmd + an arrow key** to create the new element in the direction of the arrow. ## Arcscript in labels Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 20: Advanced connections & labels > Arcscript in labels You have already seen Arcscript living inside elements and branches. Time to learn that **connection labels can also take Arcscript**. This lets you manipulate a label's text based on conditions or make variable assignments directly on a connection. In Play Mode, the Arcscript in labels executes: - **When the label text is rendered as an option button** This execution _does not change the game state._ It solely allows the option text to get evaluated accordingly so its button can be rendered. - **When the player chooses the respective option** (i.e. presses an option button) This execution _changes the game state,_ as the story flow advances to the next element. ### Conditional text in labels Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 20: Advanced connections & labels > Arcscript in labels > Conditional text in labels You can use Arcscript to change what a label says depending on how many times the player has passed through it. For example, in the demo project _In a tavern_ (see [Part 19](https://docs.arcweave.com/tutorials/basic/pt-19#demo-project)), take a label that reads: > Are you sure the skeleton has no money? To make the label change on repeat visits, split the sentence where you want the condition to apply, then insert a code segment. You can add a code segment the same way you would inside an element: - Click the **Arcscript segment** icon, or - Use the shortcut **Ctrl/Cmd+Shift+C** Inside the segment, check how many times the element has been visited using the `visits()` function: ```arcweave-html "Are you if visits(ask_about_skeleton) > 1 absolutely endif sure the skeleton has no money?" ``` With this in place, the first time the player reaches the _Ask about skeleton_ element, the label reads: > Are you sure the skeleton has no money? Because the visit count is exactly `1` at that point, the condition isn't met. On every subsequent visit, the condition evaluates to true and the label becomes: > Are you absolutely sure the skeleton has no money? You can also apply formatting — such as italics — to the inserted text to give it extra emphasis. To test this, run the project from that point using **Quickstart Play Mode from here**. On the first visit, the label shows the plain version of the question. Selecting the option and returning to it again shows the updated version with "absolutely" included, and it continues to appear on every visit after that. ### Variable assignments in labels Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 20: Advanced connections & labels > Arcscript in labels > Variable assignments in labels You can also use a connection label to change a variable's value when the player picks a specific option. For example, suppose two connections lead out of the same element with two different responses: - **"Oh, well."** — a more accepting response - **"You're all unbelievable."** — a more negative response Since the second option is negative, you might want it to reduce the party's morale. To do this, add an Arcscript segment to that connection's label: ```arcweave-html "You're all unbelievable." morale -= 1 ``` For the more accepting option, you could instead reward the player: ```arcweave-html "Oh, well." morale += 1 ``` Both connections lead to the same destination element, but different variable assignments happen along the way depending on which one the player chooses. To test this, run the project from that point using **Quickstart Play Mode from here** and open the **Debugger** to watch the `morale` variable change: - `morale` starts at `10`. - Choosing **"Oh, well."** increases it to `11`. - Clicking **Undo last choice** in the Debugger and instead choosing **"You're all unbelievable."** decreases it to `9`. ## Demo: a quiz Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 20: Advanced connections & labels > Demo: a quiz Variable assignments inside labels can be combined to build a multiple-choice quiz. In the demo project _In a tavern,_ see the board titled _Quiz_. It has one element per question, and one connection per answer, each assigning a different score to a variable depending on the option chosen. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 20: Advanced connections & labels > What's next You've now seen two ways to speed up and extend your use of connections: drag a connection onto empty space to quickly create new board items and use Arcscript inside labels to change text dynamically or assign variables. Try adding conditional text or a scoring system to one of your own connections to get a feel for how they work together. The next part of the tutorial will familiarize you with audio assets. # Basic Arcweave tutorial | Part 21: Audio assets Source: https://docs.arcweave.com/tutorials/basic/pt-21 Section: Tutorials > Basic Arcweave Description: Text & video tutorial on using audio assets in your Arcweave projects In this tutorial, we'll show how to add and manage audio in your Arcweave projects. You can add music and sounds to your projects to create a much more immersive interactive experience. Arcweave manages audio clips the same way it manages images. You can use the **Assets** tab in the sidebar to upload and access all your audio files. ## Video tutorial Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Video tutorial Watch this tutorial as a video: Video: https://www.youtube.com/watch?v=Kk_2HRB7xd8 > ⚠️ This video does not reflect the latest updates to Arcweave's UI. > ✅ You can play the finished version of the Tutorial Project [here](https://arcweave.com/app/project/Qz0PXOZ0Ya/play) and explore its diagrams and structure [here](https://arcweave.com/app/project/Qz0PXOZ0Ya). ## Upload audio assets Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Upload audio assets Just as with images, it's good practice to keep an organized folder structure for your audio files inside the **Assets section** of your left sidebar. ![The Arcweave project environment with an orange rectangle emphasizing the Assets section of the left sidebar.](https://docs.arcweave.com/assets/assets-sidebar.CKLkshad.png) To upload a new audio file: 1. Click **Create asset** (the **+** icon) in the **Assets** section. 2. Select **Upload assets...** from the menu. 3. Select one or more audio files from your drive. Arcweave supports `.mp3`, `.ogg`, `.wav`, and `.webm` files to be used as audio assets. > ✅ You can also drag assets from your file manager straight into Arcweave's project window. See the [page on Assets](https://docs.arcweave.com/project-items/assets/overview#upload-assets) in this documentation. For example, you could upload: - A tavern ambience/atmosphere loop - A zombie growl sound effect - A short guitar music loop ## Preview audio assets Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Preview audio assets You can play, test, and adjust the volume of an audio asset directly from the left sidebar's **Assets section**: 1. In your **Assets section**, click on the audio asset you want to preview. 2. Click the **Play** button to listen to the clip. 3. Use the **volume slider** to adjust the volume. 4. Optionally, set **Fade in** and **Fade out** durations in milliseconds. > ✅ The asset's volume and fades are defaults for **all instances** of that asset throughout the project. You can [override them for a single instance](https://docs.arcweave.com/tutorials/basic/pt-21#override-the-asset-defaults). ## Attach audio to elements Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Attach audio to elements To attach an audio asset to an element, simply drag and drop it from the Assets section into the element's body, the same way you would attach images or components. Once attached, a new section appears at the bottom of the element listing its audio attachments. You can test how the audio plays by entering Play Mode. ### Attach multiple audio assets Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Attach audio to elements > Attach multiple audio assets You can attach multiple assets to the same element and you can even attach the **same** asset multiple times. Each attachment is its own independent instance of that audio clip. ### Set audio behavior Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Attach audio to elements > Set audio behavior Once you attach an audio asset to an element, you can set its playback behavior. See [Audio behavior](https://docs.arcweave.com/tutorials/basic/pt-21#audio-attachment-behavior) below. ### Remove audio attachment Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Attach audio to elements > Remove audio attachment To remove an audio instance from an element, drag it out of the element and drop it onto an empty area of the board. You can also drag a clip instance from one element directly onto another. ## Volume control in Play Mode Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Volume control in Play Mode While playing your project, you can adjust the volume from the Play Mode top menu: 1. Hover near the top of your browser window to reveal the Play Mode top menu. 2. On the right side of the menu, click the **Audio** icon (a speaker) to open the volume controls. 3. Drag the volume slider to turn the volume down, or click the mute icon next to the slider to silence the audio entirely during a playthrough. > ✅ The debug icon is only accessible to the project's owners and editors, but the volume control is available to **anyone** playing the game. ## Audio attachment behavior Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Audio attachment behavior So far, the settings we've covered (the asset's volume and fades) apply at the **asset** level, as defaults for every instance of that clip across the project. However, you can also configure each attachment at the **instance** level, meaning the settings only affect that specific attachment. To access these settings, click on an audio instance attached to an element. This opens the **Audio reference** dialog, with a volume slider and the following **Play mode settings**: ### Loops and one-shots Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Audio attachment behavior > Loops and one-shots 1. By default, a newly attached instance is set to **Play clip once**, which is why clips stop after playing through a single time. 2. To make a clip loop, select **Loop clip**. If you run the project in Play Mode, the clip will now restart automatically every time it finishes playing. 3. The third option, **Stop playing all instances of this clip**, lets you stop a loop that was started on an earlier element. For example, if a guitar loop starts on one element, you can attach the same guitar asset to a later element and set that instance to stop all instances of the clip. This way, when the player reaches the new element, the loop ends. > ✅ The stop option stops **all** instances of that clip, whether they're looping or not. If multiple instances of the same asset are attached to different elements, a single "stop" instance will stop every one of them. ### Add a delay Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Audio attachment behavior > Add a delay You can also delay when an instance starts playing. This is useful, for example, if you want to establish a scene with an ambience track first, then introduce music a few seconds later. To add a delay: 1. Click on the audio instance. 2. Find the **Delay** field. 3. Enter a delay in milliseconds (e.g., `3000` for a 3-second delay). ### Fade in and out Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Audio attachment behavior > Fade in and out Use **Fade in** and **Fade out** to ease a clip in when it starts and out when it stops, instead of cutting it abruptly. Enter durations in milliseconds. A clip set to **Play clip once** also fades out at its end, and a stop instance fades out the clips it stops. ### Stop when leaving the element Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Audio attachment behavior > Stop when leaving the element Select **Auto-stop on element exit** to stop the clip as soon as the player moves to another element. This is handy for a line of narration or a sound that belongs to a single scene. ### Override the asset defaults Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Audio attachment behavior > Override the asset defaults The instance's volume, **Fade in**, and **Fade out** start with the asset's values. Changing them in the **Audio reference** dialog affects only this instance. To use the asset's value again, click **Reset to asset default** (the circular arrow icon) next to the setting. See [Audio reference settings](https://docs.arcweave.com/project-items/assets/audio#audio-reference-settings) for details. ## Refresh Play Mode Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > Refresh Play Mode Changes to an audio instance take effect the next time the clip starts playing. If a change doesn't seem to apply, refresh the Play Mode tab. ## What's next Context: Arcweave docs > Tutorials > Basic Arcweave > Basic Arcweave tutorial | Part 21: Audio assets > What's next You now know how to upload audio assets, attach them to elements, control volume both in the editor and in Play Mode, and configure instance-specific behavior like looping, stopping, delays, and fades. Next, take a look at all the features of [assets](https://docs.arcweave.com/project-items/assets/overview) in this documentation, including **video**. Combining audiovisuals with your storytelling will help you create a richer, more immersive experience for your players. From here, you can continue exploring the documentation pages for any specific features you'd like to learn more about. If you have questions along the way, you can also find answers in [our Discord server](https://discord.gg/t6RqXYXRfJ). # Style Editor tutorials Source: https://docs.arcweave.com/tutorials/style-editor/overview Section: Tutorials Description: Tutorials on styling Play Mode with Arcweave's Style Editor and CSS, from basic selectors to a visual novel layout This section includes the following tutorials: - [Arcweave CSS basics](https://docs.arcweave.com/tutorials/style-editor/css-basics): Learn how to use Arcweave's [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor) to customize and style your story. - [Visual novel CSS](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel): Dive deeper into advanced CSS functionality and style your Arcweave story as a visual novel. # Arcweave CSS basics tutorial Source: https://docs.arcweave.com/tutorials/style-editor/css-basics Section: Tutorials > Style Editor Description: A tutorial teaching you Arcweave's main CSS selectors and how to target them The [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor) of Arcweave's Play Mode uses CSS and gives you full control over how your prototype looks in regard to text styling, layout, and color palette. This how-to guide teaches you how to customize your Arcweave game with the Style Editor. It iterates through the available CSS selectors, shows how they affect your Play Mode interface, and demonstrates simple, efficient examples of changes you can apply with ease. For the complete DOM structure, defaults, and CSS precedence rules, use the [Play Mode styling reference](https://docs.arcweave.com/project-tools/play-mode/styling-reference). The same CSS works through the [REST API](https://docs.arcweave.com/rest-api/css) and [MCP tools](https://docs.arcweave.com/integrations/mcp#style-play-mode). ## Access the Style Editor Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Access the Style Editor To open the Style Editor: 1. Click the **Play Mode** button (▶) in the project's top menu bar. Play Mode opens in a new browser tab. 2. Select the **Style Editor** (🎨 palette icon) on Play Mode's top bar. If the bar has faded out, move the pointer to the top of the window. 3. Write your CSS directly in the panel; changes appear instantly. 4. Press **Save changes** to save the CSS in your project. The Style Editor is available to project owners and editors. ![Arcweave's Play Mode screen, with the Style Editor sidebar open on the right, showing a block of CSS code affecting the playthrough's appearance on the left: the option buttons are semi-transparent and the cover image is full screen.](https://docs.arcweave.com/assets/play-style-editor.cx55xf1r.png) > ⚠️ If the **Save changes** button is disabled, your CSS has errors. Click the error count at the bottom of the panel to see each error with its line number, then fix them. The Style Editor previews your changes live. Keep a copy of existing CSS before replacing it so you can restore it later. ## Containers Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Containers ### Prototype wrapper Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Containers > Prototype wrapper The **prototype wrapper** centers the story content and adds top spacing. It sits inside the scrollable `.prototype__root`; the outer page is `.prototype`. You can target it with the `prototype__wrapper` class. > ℹ️ Notice the **double underscore** `__` used in the class names. For example, you can use it to perform the following changes: - Change the background color - Add some padding at the top - Change font - Set the font as bold ![Arcweave's Play Mode environment, with the font and background color changed based on the CSS code that follows in the article.](https://docs.arcweave.com/assets/css-prototype-wrapper.DwyNTH24.png) The code snippet for these changes is the following: ```css @import url('https://fonts.googleapis.com/css2?family=Schoolbell&display=swap'); .prototype__wrapper { background-color: #143340; padding-top: 100px; font-family: 'Schoolbell', cursive; font-weight: 600; } ``` > ✅ Remember to include an `@import` directive when importing fonts. ### Prototype content Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Containers > Prototype content Your story's elements don't just float freely inside the prototype wrapper; they're organized within their own container called **prototype content**. You can target the `prototype__content` class to control the display of the following parts of the rendered element: - Header (element cover and attached components) - Text content - Option buttons Use this class to make layout and style adjustments like the following: - Make the prototype content narrower - Change the color of just the content area - Change font - Add some margin around the content - Add border radius (soft corners) to the content area ![Arcweave's Play Mode environment with the Style Editor open and the Play Mode window styled according to the code that follows in the article.](https://docs.arcweave.com/assets/css-prototype-content.DqbZY-DX.png) ```css @import url('https://fonts.googleapis.com/css2?family=Schoolbell&display=swap'); .prototype__content { max-width: 50%; background-color: #143340; font-family: 'Schoolbell'; border-radius: 25px; margin: 50px; } ``` > ✅ As you've probably noticed, you can change the font using either class: `prototype__wrapper` or `prototype__content`. However, it's best practice to target the text content in the editor, as described in [Styling text](https://docs.arcweave.com/tutorials/style-editor/css-basics#styling-text) below. ### Prototype header Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Containers > Prototype header The **prototype header** is the area that holds the elements' following items: - The element's **cover** (image, video, YouTube embed, or icon) - Attached **components** Target it by using the `prototype__header` class. For example, to make the header area narrower than the text content, use the following snippet: ```css .prototype__header { max-width: 50%; margin: auto; } ``` > ℹ️ The `margin: auto;` line centers the image. ![Arcweave's Play Mode with the Style Editor open. The CSS code causes the header image and the components underneath it to occupy a narrower area.](https://docs.arcweave.com/assets/css-prototype-header-1.Z8-R3aTE.png) You can also color this area (and make corners rounded) with the following snippet: ```css .prototype__header { max-width: 60%; margin: auto; padding: 20px; background-color: darkred; border-radius: 25px; } ``` ![Arcweave's Play Mode with the Style Editor open. The CSS code causes the header image and the components to be wrapped in a red box with rounded corners.](https://docs.arcweave.com/assets/css-prototype-header-2.Cr5X88RD.png) If an element has attached components and no cover, the components will take the cover's place in the prototype header area. ![Arcweave's Play Mode with the Style Editor open. The current element has no image cover, so the 2 attached components both occupy the image's place, wrapped in a red box with rounded corners.](https://docs.arcweave.com/assets/css-prototype-header-3.CiUDJBND.png) ### Prototype body Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Containers > Prototype body The **prototype body** contains the text content and the option buttons. Target it using the class `prototype__body`. See **prototype text**, below, for its usage. ### Prototype text Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Containers > Prototype text The **prototype text** is a sub-container and contains only the text content. Target it using the class `prototype__text`. The following example uses a combination of prototype body and prototype text to: - Narrow the text / buttons area setting the `max-width` of `prototype__body` to `95%`. - Narrow the text content width setting the `max-width` of `prototype__text` to an extra `90%`. - Center both `prototype__header` and `prototype__body` with `margin: auto`. - Center the text block with `margin: auto` on `prototype__text`, and center-align its lines with `text-align: center`. - Change all background colors. - Give them some padding. - Detach them from each other using `margin` and `margin-top`. > ℹ️ Notice that centering the `prototype__body` is not the same as setting the text to be center-aligned. Feel free to experiment with the code snippets, to better understand exactly what each property does. ![Arcweave's Play Mode with the Style Editor open. The current element's various containers are separately styled as boxes with rounded corners and different shades of blue and dark cyan.](https://docs.arcweave.com/assets/css-prototype-header-content-text.D4FzZHOp.png) This is the code snippet that produces this result: ```css @import url('https://fonts.googleapis.com/css2?family=Schoolbell&display=swap'); .prototype__content { background-color: #09181f; border-radius: 25px; margin: 30px auto; } .prototype__header { max-width: 60%; margin: auto; padding: 20px; background-color: #004347; border-radius: 25px; } .prototype__body { max-width: 95%; margin: auto; background-color: #14403e; padding: 20px; margin-top: 20px; border-radius: 25px; } .prototype__text { font-family: 'Schoolbell', cursive; max-width: 90%; margin: auto; text-align: center; } ``` ### Prototype options Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Containers > Prototype options **Prototype options** (notice the plural, _options_) is the container of the option buttons. Target it using the `prototype__options` class. > ✅ One way to style specific option buttons is by targeting the respective children of the `.prototype__options` (see further below, under [Style specific options](https://docs.arcweave.com/tutorials/style-editor/css-basics#style-specific-options)). ## Styling text Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Styling text Although you can perform some text styling by targeting the containers described above, you need to target the text itself to go even deeper. ### Editor Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Styling text > Editor The **editor** is a sub-container of prototype text containing the rich text of your elements. It can be targeted using the `editor` class. This article contains a couple of cases where the editor comes in handy, the first one following right below. ### Editor content Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Styling text > Editor content To target the text content of your elements, use the full selector `.prototype__text .editor .editor-content`. Arcweave sets the default text color, font size, and padding on `.prototype__body .editor .editor-content`, so a shorter selector such as `.editor-content` alone does not override them. The following snippet increases the font size of the text content and changes its color: ```css .prototype__text .editor .editor-content { font-size: 28px; color: darkseagreen; } ``` ## Prototype media Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Prototype media The element cover renders inside the `prototype__media` container. Target an image cover with `.prototype__media img.single` and a video cover with `.prototype__media video`: ```css .prototype__media img.single { border-radius: 25px; } .prototype__media video { border-radius: 25px; } ``` When an element has no cover, its attached components appear inside `prototype__media` instead. The `single` class keeps the image rule from also matching component images. ## Prototype components Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Prototype components Components are contained in the **prototype components** container, which you can target with the `prototype__components` class. To target the components themselves, use the selector `.prototype__components .comp`. Here's an example of targeting components and their container to manipulate their size and remove their default border radius. ![Arcweave's Play Mode with the Style Editor open. The current element's attached components are styled like frames on a strip of film, with a desaturated blueish background.](https://docs.arcweave.com/assets/css-prototype-components-1.BzknPw07.png) ```css .prototype__components { height: 120px; padding: 10px; background: #123a54; grid-gap: 5px; } .prototype__components .comp { height: 100px; background: darkred; border-radius: 0px; } ``` If you wish to completely omit components from the Play Mode experience, use `display: none`: ```css .prototype__components { display: none; } ``` ## Prototype option Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Prototype option Option buttons render as clickable `div` elements with the `prototype__option` class. (Don't confuse with the parent container `prototype__options`, in plural, mentioned [further above](https://docs.arcweave.com/tutorials/style-editor/css-basics#prototype-options).) ![Arcweave's Play Mode with the Style Editor open. The element's option buttons are aligned centrally and have sharp contrast of black and white.](https://docs.arcweave.com/assets/css-prototype-option.DaNfIAjs.png) This example goes for a high-contrast, no-transition, rounded and centered buttons. ```css .prototype__option { max-width: 80%; margin: 10px auto; text-align: center; border-radius: 30px; border: 1px solid #292d2d; background: none; color: #eaeaea; transition: none; } .prototype__option:hover { color: black; background: white; } ``` ### Style visited options Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Prototype option > Style visited options When an option leads to an element that has already been visited in the current playthrough, Arcweave adds the `visited` class to that option button. You can target those options with `.prototype__option.visited`. For example, the following CSS dims choices that lead to previously visited elements: ```css .prototype__option.visited { opacity: 0.55; } ``` ## Advanced styling Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Advanced styling ### Style specific elements Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Advanced styling > Style specific elements The Style Editor allows you not only to globally style _every_ element, but also style specific elements differently from the others. Each element in your prototype has its own unique **element ID**. Including an element ID as a CSS selector allows you to target the specific element for CSS styling. To do this, follow the next steps: #### 1. Copy the element ID Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Advanced styling > Style specific elements > 1. Copy the element ID An element's ID looks like this: `81a30674-aa09-4eb8-8484-59298d37f984`. You can get that UUID from the API/MCP element record, or copy it in Arcweave: **Debugger** (Play Mode environment): 1. Play the story until you reach the desired element. 2. Open the [Debugger](https://docs.arcweave.com/project-tools/play-mode/debugger). 3. Click the **ID** button in the **Element** row (not the **Board** row). 4. Next to **UUID**, press the copy button. **Element Properties** (Project environment): 1. Locate and right-click the desired element in its board. 2. Select **Properties**. 3. Go to the **Details** tab. 4. Next to **Element ID**, press the clipboard button. #### 2. Add the element ID to the CSS selectors Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Advanced styling > Style specific elements > 2. Add the element ID to the CSS selectors After copying the element's UUID, prefix it with `#el-` to form `#el-[element-id]`. A DOM ID copied from the browser already includes `el-`, so do not add it twice. This ensures that your styles apply only to that specific element when rendered in Play Mode. Here's an example showing how to target both the editor content and the prototype content of a single element: ```css @import url('https://fonts.googleapis.com/css2?family=Schoolbell&display=swap'); #el-81a30674-aa09-4eb8-8484-59298d37f984 .prototype__text .editor .editor-content { color: darkseagreen; } #el-81a30674-aa09-4eb8-8484-59298d37f984 .prototype__content { max-width: 50%; background-color: #143340; font-family: 'Schoolbell'; border-radius: 25px; margin: 50px; } ``` ### Style specific options Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Advanced styling > Style specific options Style specific options in either of the following ways: - Target a **specific option by its position** inside the [prototype options](https://docs.arcweave.com/tutorials/style-editor/css-basics#prototype-options) container (`prototype__options` class) - Target **connections of specific color**. #### Style nth child of prototype options Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Advanced styling > Style specific options > Style nth child of prototype options In normal playback, choices are direct children of `.prototype__options`. Edit content mode can wrap each choice in `.prototype-option-row`. Target the position at the container level in both forms: ```css /* First visible choice, in playback and edit mode. */ .prototype__options > .prototype__option:first-child, .prototype__options > .prototype-option-row:first-child > .prototype__option { border: 2px solid #60a5fa; } ``` To target the second choice of a specific element: ```css #el-81a30674-aa09-4eb8-8484-59298d37f984 .prototype__options > .prototype__option:nth-child(2), #el-81a30674-aa09-4eb8-8484-59298d37f984 .prototype__options > .prototype-option-row:nth-child(2) > .prototype__option { font-weight: bold; } ``` These selectors mean the first or second **currently displayed choice**, not a particular connection. Branch conditions and reordering can change which choice occupies that position. A single unlabelled path shows an [advance arrow](https://docs.arcweave.com/project-tools/play-mode/styling-reference#conditional-content-and-the-advance-arrow) instead of a choice. Connection UUIDs are not exposed as DOM IDs; use a theme class when it better expresses the styling you want. #### Style connections of specific color Context: Arcweave docs > Tutorials > Style Editor > Arcweave CSS basics tutorial > Advanced styling > Style specific options > Style connections of specific color In Arcweave, you can [change the color theme](https://docs.arcweave.com/project-items/connections#change-color-theme) of connections. In the Style Editor, you can then target connections of specific colors, to style their respective option buttons. For example, to target the option corresponding to the pink connection of any element, add the following code: ```css .prototype__option.pink { ... } ``` The colors used as connection themes are: Color Selector ██████████ .prototype__option.pink ██████████ .prototype__option.red ██████████ .prototype__option.purple ██████████ .prototype__option.lightBlue ██████████ .prototype__option.cyan ██████████ .prototype__option.moss ██████████ .prototype__option.green ██████████ .prototype__option.gold ██████████ .prototype__option.brown ██████████ .prototype__option.default ██████████ .prototype__option.orange ██████████ .prototype__option.blue ![Arcweave Play Mode option buttons styled according to their connection color themes.](https://docs.arcweave.com/assets/css-option-color.DgpRz8bs.png) # Visual novel CSS tutorial Source: https://docs.arcweave.com/tutorials/style-editor/css-visual-novel Section: Tutorials > Style Editor Description: A tutorial teaching you how to style your story as a visual novel using Arcweave's Style Editor and CSS Visual novels are one of the most popular storytelling formats in interactive fiction. With their full-screen backgrounds, character sprites, and dialogue boxes, they create an immersive reading experience that draws players into your story. ![Arcweave Play Mode styled as a visual novel, with a full-screen background, character sprite, dialogue box, and option buttons.](https://docs.arcweave.com/assets/css-visual-novel-general.BJSOtJqe.png) This tutorial helps you achieve this polished look in Arcweave's Play Mode using the [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor) and some advanced CSS. It teaches you how to: - [Set up your project with element covers and character components](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel#set-up-your-project) - [Access the Style Editor](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel#access-the-style-editor) - [Turn your element covers into full-screen background images for each scene](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel#scene-backgrounds) - [Create character components and position them as sprites at the bottom of the screen](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel#character-sprites) - [Create a stylish dialogue box with scrollable text](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel#dialogue-box) - [Style choice buttons and place them above your dialogue](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel#option-buttons) - [Make everything responsive for mobile devices](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel#mobile-responsiveness) - [Style specific words and paragraphs for emphasis](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel#style-specific-text) - [Style specific options](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel#style-specific-options) - [Experiment further with advanced tips](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel#styling-tips) - [Troubleshoot common problems](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel#troubleshooting) ## Set up your project Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Set up your project The visual novel interface has specific visual parts. Before diving into CSS, you must first set your Arcweave project up in a way that these parts get represented as follows: 1. **Scene backgrounds**: The scenic backdrop for each scene, in full screen. In the Arcweave project, these will be represented by [element covers](https://docs.arcweave.com/project-items/elements#element-covers). 2. **Character sprites**: The characters that appear or speak in a dialogue scene. They are represented by [components](https://docs.arcweave.com/project-items/components) and their cover images. 3. **Dialogue box**: The text box where the game's dialogue appears in [rich text](https://docs.arcweave.com/project-tools/rich-text#formatting-menu). If the content is long, a scrollbar appears. 4. **Option buttons**: The player choices. In Arcweave, these are created with connections and [labels](https://docs.arcweave.com/project-items/labels). ## Access the Style Editor Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Access the Style Editor In order to type your CSS code, you first need to access Arcweave's [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor). ![Arcweave's Play Mode with the Style Editor open at the right side of the screen. The styling is currently Arcweave's default, and the CSS code field is empty.](https://docs.arcweave.com/assets/css-access.50YdHqSn.png) To open the Style Editor: 1. Open your project and click the **Play Mode** button (▶) in the top menu bar. Play Mode opens in a new browser tab. 2. In Play Mode, click the **Style Editor icon** (🎨 palette icon) in the top bar. If the bar has faded out, move the pointer to the top of the window. The Style Editor is available to project owners and editors. The Style Editor shows you the current CSS and previews your changes as you type. Save a copy of existing project CSS before replacing it. The snippets below build one stylesheet in order; the [complete code template](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel#complete-code-template) combines them. This recipe uses **image element covers and image component covers**. Its selectors stay inside the story root. See the [Play Mode styling reference](https://docs.arcweave.com/project-tools/play-mode/styling-reference) for the rendered structure, other cover types, edit mode differences, and API/MCP styling workflows. ## Scene backgrounds Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Scene backgrounds ### Background assets Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Scene backgrounds > Background assets As these are the backdrops for your scenes, use high-resolution images that look good in full screen; a width of `1920` pixels is a good baseline. Feel free to study and replicate the background assets used in the [Visual Novel Example](https://docs.arcweave.com/workspaces/projects#project-templates) project template (sized `2816` x `1536` pixels). > ⚠️ **Responsiveness**: Keep in mind that players who access your game on mobile devices will see only a vertical section of your background. Make sure the essential details are near the center, since players may miss areas on the left and right. ![Comparison showing that mobile screens show a narrower vertical crop of a wide visual novel background.](https://docs.arcweave.com/assets/visual-novel-responsive.NLszQy61.png) ### Element covers Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Scene backgrounds > Element covers In the Arcweave project, scene backgrounds will be represented by [element covers](https://docs.arcweave.com/project-items/elements#element-covers). Attach the desired background to the elements of your scene as covers. ![Arcweave project environment showing element cover images used as scene backgrounds.](https://docs.arcweave.com/assets/css-element-covers.DH58s8nw.png) ### Background CSS Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Scene backgrounds > Background CSS By default, element covers and attached components render as shown in the picture below. ![Default Arcweave Play Mode layout before applying the visual novel CSS.](https://docs.arcweave.com/assets/css-default.DlrmO8t4.png) First, create a stage that fills the available Play Mode area. This positions the story inside the player and removes the default content width and padding. The `--vn-*` variables keep the dialogue, choices, and sprites aligned as the available height changes. The `56px` top allowance keeps choices and sprites below the player toolbar. The background extends behind it. Then stretch image covers over the stage: **CSS code extract** ```css /* Define a stage inside the available Play Mode area. */ .prototype__root { position: relative; --vn-gap: clamp(12px, 2.5vw, 32px); --vn-top-clearance: 56px; --vn-dialogue-height: min(34%, 300px); --vn-dialogue-text: #ffffff; --vn-dialogue-shadow: 2px 2px 4px rgba(0, 0, 0, 0.6); } .prototype__root .prototype__wrapper { padding: 0; } .prototype__root .prototype__content { position: absolute; inset: 0; width: 100%; max-width: none; min-height: 0; padding: 0; overflow: hidden; } .prototype__root .prototype__header { display: contents; } /* The image fills the stage, including the area behind the dialogue. */ .prototype__root .prototype__media { position: absolute; inset: 0; z-index: 1; } .prototype__root .prototype__media img.single { width: 100%; height: 100%; object-fit: cover; } ``` Your background images now should fill the whole width and height of the Play Mode window. ![Arcweave's Play Mode. The Style Editor is open on the right, while a background image fills the rest of the window. The CSS code is the one described right after this image.](https://docs.arcweave.com/assets/css-background.U9FalptO.png) ## Character sprites Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Character sprites ### Character assets Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Character sprites > Character assets For the character sprites, use **PNG portraits with transparent backgrounds**. See the character assets of the Visual Novel Example, like the one below. ![A transparent-background PNG character sprite intended for a visual novel scene.](https://docs.arcweave.com/assets/css-visual-novel-sprite.Cs1W3QOM.png) ### Character components Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Character sprites > Character components Use [components](https://docs.arcweave.com/project-items/components) to signify dialogue speakers and characters present in a scene. Add covers to those components using the character images you uploaded as project assets. ![Arcweave component settings showing a character image assigned as the component cover.](https://docs.arcweave.com/assets/css-component-cover.BVgdSygd.png) Then, attach the character components to the elements where they appear. ### Character emotions Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Character sprites > Character emotions To have a character appear with a variety of facial expressions, you need to do the following: 1. Upload a **different asset** (PNG image) for each facial expression. 2. Create a **different component** for each facial expression. 3. Attach the component with the desired expression to each element of the character's scene. ### Character CSS Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Character sprites > Character CSS Use the code snippet below to make character sprites appear at the bottom of the screen, standing above the dialogue box: **CSS code extract** ```css /* Bound sprites between the toolbar and the dialogue, so they fit. */ .prototype__root .prototype__components { position: absolute; top: var(--vn-top-clearance); bottom: calc(var(--vn-dialogue-height) + var(--vn-gap)); left: 0; right: 0; height: auto; margin: 0; padding: 0 var(--vn-gap); box-sizing: border-box; display: flex; align-items: flex-end; justify-content: center; gap: 3%; z-index: 2; } .prototype__root .prototype__components > .comp { flex: 1 1 0; width: 0; min-width: 0; height: 100%; max-height: 100%; /* Component images have an inline aspect-ratio; remove that square box. */ aspect-ratio: auto !important; background: none; object-fit: contain; object-position: center bottom; filter: drop-shadow(0 0 20px rgba(0, 0, 0, 0.5)); } .prototype__root .prototype__components > .flex-fix { display: none; } ``` > If you attach several image components, `display: flex` gives each a share of the available width. `object-fit: contain` keeps the full image visible in that space. Large transparent margins inside a PNG still reduce the visible character size; crop those margins in the asset itself. ![Arcweave's Play Mode. The Style Editor is open. Two character components appear floating as character sprites in front of a background image.](https://docs.arcweave.com/assets/css-sprites.B5VQeyKt.png) The sprite region has a top and bottom boundary instead of adding a fixed bottom offset to a viewport height. This prevents the sprites from extending above the screen on shorter displays. The targeted `!important` overrides the inline `aspect-ratio` on component images; the other declarations use normal specificity. ## Dialogue box Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Dialogue box The **dialogue box** scrolls independently when text is long. `.prototype__body` contains both the text and the choices, so keep it as a full-stage layer and draw the dialogue panel on `.prototype__text`. Its height resolves against that layer, and `box-sizing: border-box` includes the padding and border in that height. The full-stage layer ignores pointer events in its empty areas. The text and options restore pointer events so reading, scrolling, and choosing still work. ![Visual novel dialogue box rendered near the bottom of Arcweave Play Mode.](https://docs.arcweave.com/assets/css-dialogue.DoUxsxAi.png) **CSS code extract** ```css /* The body contains both dialogue and choices. Keep its full stage height. */ .prototype__root .prototype__body { position: absolute; inset: 0; z-index: 3; pointer-events: none; } /* Put the dialogue panel on the text container, not their shared parent. */ .prototype__root .prototype__text { position: absolute; bottom: var(--vn-gap); left: var(--vn-gap); right: var(--vn-gap); height: var(--vn-dialogue-height); min-height: 0; box-sizing: border-box; padding: 20px 32px; overflow: auto; overflow-wrap: anywhere; overscroll-behavior: contain; pointer-events: auto; color: var(--vn-dialogue-text); background: linear-gradient( 135deg, rgba(30, 41, 59, 0.9) 0%, rgba(15, 23, 42, 0.98) 100% ); border: 2px solid #475569; border-radius: 15px; backdrop-filter: blur(10px); box-shadow: 0 10px 40px rgba(0, 0, 0, 0.5); scrollbar-width: thin; scrollbar-color: #94a3b8 transparent; } .prototype__root .prototype__text .editor .editor-content { color: var(--vn-dialogue-text); font-size: 28px; line-height: 1.6; font-family: 'Segoe UI', 'Noto Sans', sans-serif; text-shadow: var(--vn-dialogue-shadow); padding: 0; } /* Match the edit outline to the text's zero padding. */ .prototype__root .prototype-content-editor.is-content-editable .editor.read-only::after, .prototype__root .prototype-content-editor.is-content-editable .editor-input .editor::after { inset: 0; } ``` `overflow: auto` needs a bounded height to create a useful scroll area. Keep the height and overflow rules together. The more specific `.prototype__text .editor .editor-content` selector also overrides Arcweave's default text padding and typography without changing choice labels. The final rule removes the default edit-outline inset so the blue outline fits this zero-padding text box, including short text. ## Option buttons Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Option buttons According to the classic visual novel style, player choices should appear above the dialogue box. ![Visual novel option buttons displayed above the dialogue box in Arcweave Play Mode.](https://docs.arcweave.com/assets/css-options.DPl9of6R.png) A fixed bottom offset alone is insufficient: five long choices can extend past the top of the screen. Limit the list to the space between the toolbar and dialogue, then let it scroll. The horizontal padding leaves room for edit mode's drag handles. This recipe changes colors on hover without scaling buttons outside the scroll area. **CSS code extract** ```css /* A long list scrolls in the space above the dialogue. */ .prototype__root .prototype__options { position: absolute; bottom: calc(var(--vn-dialogue-height) + 2 * var(--vn-gap)); left: var(--vn-gap); right: var(--vn-gap); width: auto; max-width: 800px; max-height: calc( 100% - var(--vn-dialogue-height) - 3 * var(--vn-gap) - var(--vn-top-clearance) ); margin: 0 auto; padding: 8px 28px; box-sizing: border-box; overflow: auto; overscroll-behavior: contain; pointer-events: auto; scrollbar-width: thin; scrollbar-color: #94a3b8 transparent; } .prototype__root .prototype__option { --prototype-option-background: linear-gradient(135deg, #334155, #1e293b); --prototype-option-background-hover: linear-gradient( 135deg, #475569, #334155 ); background: var(--prototype-option-background); border: 2px solid #60a5fa; border-radius: 24px; padding: 14px 24px; margin: 0 0 12px; color: #ffffff; font-size: 22px; line-height: 1.5; font-weight: 600; overflow-wrap: anywhere; cursor: pointer; transition: background 0.2s, border-color 0.2s; } .prototype__root .prototype__option:hover { background: var(--prototype-option-background-hover); border-color: #a78bfa; } ``` ## Mobile responsiveness Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Mobile responsiveness The stage-relative heights already adapt to the available player area. Add separate rules for narrow screens and short screens: a phone in landscape may be wider than the portrait breakpoint while having much less vertical space. Keep these rules after the base styles. Media queries use the browser viewport (or the iframe viewport when embedded), so also test with the Style Editor and Debugger open. **CSS code extract** ```css /* Narrow screens, including phones in portrait. */ @media (max-width: 700px) { .prototype__root { --vn-gap: 12px; --vn-dialogue-height: min(36%, 220px); } .prototype__root .prototype__text { padding: 14px 18px; } .prototype__root .prototype__text .editor .editor-content { font-size: 20px; } .prototype__root .prototype__option { font-size: 18px; padding: 10px 16px; } } /* Short screens, including phones in landscape. */ @media (max-height: 500px) { .prototype__root { --vn-gap: 8px; --vn-dialogue-height: 38%; } .prototype__root .prototype__text { padding: 10px 16px; } .prototype__root .prototype__text .editor .editor-content { font-size: 18px; line-height: 1.5; } .prototype__root .prototype__option { font-size: 16px; padding: 8px 14px; margin-bottom: 8px; } } ``` ## Style specific text Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Style specific text You can emphasize a character's name with color, highlight clues, or give sound effects their own typography. Arcweave's rich-text formatting provides the HTML tags you can target without adding custom classes. ### How it works Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Style specific text > How it works When you format text in Arcweave's editor (italic, bold, underline), it generates standard HTML tags: - **Italic** creates `` tags - **Bold** creates `` tags - **Underline** creates `` tags We can target these tags with CSS and override their default appearance. The key is to use the **element ID** to make sure we only affect specific elements, not every italic word in your entire story. ### Find element IDs Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Style specific text > Find element IDs Use the element's **UUID**, not its title. In Play Mode, open the [Debugger](https://docs.arcweave.com/project-tools/play-mode/debugger), click the **ID** button in the **Element** row, and copy the **UUID**. You can also copy it from the element's **Properties → Details → Element ID**, and API/MCP project data provides the same element UUID. For example, the UUID `cb35db92-3c07-41bf-9c45-580ad6b891b4` becomes the CSS selector `#el-cb35db92-3c07-41bf-9c45-580ad6b891b4`. The Debugger copies the raw UUID; add `#el-` once. In the examples below, replace `your-element-uuid` with that raw UUID. ### Step-by-step process Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Style specific text > Step-by-step process **1\. Format text in the editor** Go to your element and edit it: - Highlight the word or phrase you want to style - Apply a format: **Italic**, **Bold**, or **Underline** - This creates the HTML tag we'll target with CSS **2\. Write the CSS** Now in the Style Editor, target that specific formatted text: **CSS code extract** ```css /* Target italic text in a specific element and make it red */ #el-your-element-uuid .prototype__text .editor .editor-content em { color: red; font-style: normal; /* Remove the default italic effect */ } ``` ### Practical examples Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Style specific text > Practical examples #### Example 1: Character names in color Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Style specific text > Practical examples > Example 1: Character names in color Make character names appear in their signature color: **In Arcweave:** Format "Alice" with italic. **CSS:** **CSS code extract** ```css #el-your-element-uuid .prototype__text .editor .editor-content em { color: #60a5fa; /* Blue for Alice */ font-style: normal; font-weight: bold; } ``` #### Example 2: Important clues Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Style specific text > Practical examples > Example 2: Important clues Highlight clues that players should remember: **In Arcweave:** Format clue words with bold. **CSS:** **CSS code extract** ```css #el-your-element-uuid .prototype__text .editor .editor-content strong { color: #fbbf24; /* Gold color */ font-weight: 900; text-shadow: 0 0 10px rgba(251, 191, 36, 0.5); /* Glow effect */ } ``` #### Example 3: Sound effects Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Style specific text > Practical examples > Example 3: Sound effects Create stylized sound effects: **In Arcweave:** Format "crash" with underline. **CSS:** **CSS code extract** ```css #el-your-element-uuid .prototype__text .editor .editor-content u { text-decoration: none; /* Remove underline */ color: #ef4444; font-family: 'Impact', sans-serif; font-size: 1.2em; font-style: italic; letter-spacing: 2px; } ``` #### Example 4: Targeting specific paragraphs Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Style specific text > Practical examples > Example 4: Targeting specific paragraphs You can also style entire paragraphs using `nth-child`: **CSS code extract** ```css /* Style the first paragraph differently (maybe it's narration) */ #el-your-element-uuid .prototype__text .editor .editor-content p:first-child { color: #a78bfa; font-style: italic; font-size: 0.9em; } /* Style the second paragraph (maybe it's a character speaking) */ #el-your-element-uuid .prototype__text .editor .editor-content p:nth-child(2) { color: #60a5fa; font-weight: bold; } ``` ### Creative uses Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Style specific text > Creative uses Here are some creative ways to use this technique: **1\. Dialogue with different character voices:** **CSS code extract** ```css /* Character 1 - uses italic */ #el-your-element-uuid .prototype__text .editor .editor-content em { color: #60a5fa; font-style: normal; font-weight: 600; } /* Character 2 - uses bold */ #el-your-element-uuid .prototype__text .editor .editor-content strong { color: #f472b6; font-weight: 700; } /* Narrator - uses underline */ #el-your-element-uuid .prototype__text .editor .editor-content u { text-decoration: none; color: #a78bfa; font-style: italic; } ``` **2\. Thoughts vs. spoken dialogue:** **CSS code extract** ```css /* Inner thoughts in italic */ #el-your-element-uuid .prototype__text .editor .editor-content em { color: #94a3b8; font-style: italic; opacity: 0.8; } ``` **3\. Highlighted decisions in the dialogue:** **CSS code extract** ```css /* Highlight bold text that introduces a decision */ #el-your-element-uuid .prototype__text .editor .editor-content strong { color: #fbbf24; font-weight: bold; text-decoration: underline; } ``` ### Scope and formatting Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Style specific text > Scope and formatting Use the element selector when a rule belongs to one scene, and `.prototype__text .editor .editor-content` to limit it to dialogue. A global selector such as `em` can also affect the player UI. For intentional story-wide formatting, use `.prototype__root .prototype__text .editor .editor-content em`. These examples reuse italic, bold, and underline formatting as three visual conventions. Reusing a format changes its appearance everywhere matched by that rule; keep ordinary emphasis readable and use paragraph selectors where that is more appropriate. Paragraph positions also change if you insert text or render different content with Arcscript. ## Style specific options Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Style specific options Use the instructions in the CSS basics guide to [style specific options](https://docs.arcweave.com/tutorials/style-editor/css-basics#style-specific-options) of either all elements or specific elements. ## Complete code template Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Complete code template This combines the five layout snippets above. Add scene-specific text rules after it if needed. It replaces the default reading layout with a visual novel stage; check long dialogue and choices before publishing. **CSS code extract** ```css /* Define a stage inside the available Play Mode area. */ .prototype__root { position: relative; --vn-gap: clamp(12px, 2.5vw, 32px); --vn-top-clearance: 56px; --vn-dialogue-height: min(34%, 300px); --vn-dialogue-text: #ffffff; --vn-dialogue-shadow: 2px 2px 4px rgba(0, 0, 0, 0.6); } .prototype__root .prototype__wrapper { padding: 0; } .prototype__root .prototype__content { position: absolute; inset: 0; width: 100%; max-width: none; min-height: 0; padding: 0; overflow: hidden; } .prototype__root .prototype__header { display: contents; } /* The image fills the stage, including the area behind the dialogue. */ .prototype__root .prototype__media { position: absolute; inset: 0; z-index: 1; } .prototype__root .prototype__media img.single { width: 100%; height: 100%; object-fit: cover; } /* Bound sprites between the toolbar and the dialogue, so they fit. */ .prototype__root .prototype__components { position: absolute; top: var(--vn-top-clearance); bottom: calc(var(--vn-dialogue-height) + var(--vn-gap)); left: 0; right: 0; height: auto; margin: 0; padding: 0 var(--vn-gap); box-sizing: border-box; display: flex; align-items: flex-end; justify-content: center; gap: 3%; z-index: 2; } .prototype__root .prototype__components > .comp { flex: 1 1 0; width: 0; min-width: 0; height: 100%; max-height: 100%; /* Component images have an inline aspect-ratio; remove that square box. */ aspect-ratio: auto !important; background: none; object-fit: contain; object-position: center bottom; filter: drop-shadow(0 0 20px rgba(0, 0, 0, 0.5)); } .prototype__root .prototype__components > .flex-fix { display: none; } /* The body contains both dialogue and choices. Keep its full stage height. */ .prototype__root .prototype__body { position: absolute; inset: 0; z-index: 3; pointer-events: none; } /* Put the dialogue panel on the text container, not their shared parent. */ .prototype__root .prototype__text { position: absolute; bottom: var(--vn-gap); left: var(--vn-gap); right: var(--vn-gap); height: var(--vn-dialogue-height); min-height: 0; box-sizing: border-box; padding: 20px 32px; overflow: auto; overflow-wrap: anywhere; overscroll-behavior: contain; pointer-events: auto; color: var(--vn-dialogue-text); background: linear-gradient( 135deg, rgba(30, 41, 59, 0.9) 0%, rgba(15, 23, 42, 0.98) 100% ); border: 2px solid #475569; border-radius: 15px; backdrop-filter: blur(10px); box-shadow: 0 10px 40px rgba(0, 0, 0, 0.5); scrollbar-width: thin; scrollbar-color: #94a3b8 transparent; } .prototype__root .prototype__text .editor .editor-content { color: var(--vn-dialogue-text); font-size: 28px; line-height: 1.6; font-family: 'Segoe UI', 'Noto Sans', sans-serif; text-shadow: var(--vn-dialogue-shadow); padding: 0; } /* Match the edit outline to the text's zero padding. */ .prototype__root .prototype-content-editor.is-content-editable .editor.read-only::after, .prototype__root .prototype-content-editor.is-content-editable .editor-input .editor::after { inset: 0; } /* A long list scrolls in the space above the dialogue. */ .prototype__root .prototype__options { position: absolute; bottom: calc(var(--vn-dialogue-height) + 2 * var(--vn-gap)); left: var(--vn-gap); right: var(--vn-gap); width: auto; max-width: 800px; max-height: calc( 100% - var(--vn-dialogue-height) - 3 * var(--vn-gap) - var(--vn-top-clearance) ); margin: 0 auto; padding: 8px 28px; box-sizing: border-box; overflow: auto; overscroll-behavior: contain; pointer-events: auto; scrollbar-width: thin; scrollbar-color: #94a3b8 transparent; } .prototype__root .prototype__option { --prototype-option-background: linear-gradient(135deg, #334155, #1e293b); --prototype-option-background-hover: linear-gradient( 135deg, #475569, #334155 ); background: var(--prototype-option-background); border: 2px solid #60a5fa; border-radius: 24px; padding: 14px 24px; margin: 0 0 12px; color: #ffffff; font-size: 22px; line-height: 1.5; font-weight: 600; overflow-wrap: anywhere; cursor: pointer; transition: background 0.2s, border-color 0.2s; } .prototype__root .prototype__option:hover { background: var(--prototype-option-background-hover); border-color: #a78bfa; } /* Narrow screens, including phones in portrait. */ @media (max-width: 700px) { .prototype__root { --vn-gap: 12px; --vn-dialogue-height: min(36%, 220px); } .prototype__root .prototype__text { padding: 14px 18px; } .prototype__root .prototype__text .editor .editor-content { font-size: 20px; } .prototype__root .prototype__option { font-size: 18px; padding: 10px 16px; } } /* Short screens, including phones in landscape. */ @media (max-height: 500px) { .prototype__root { --vn-gap: 8px; --vn-dialogue-height: 38%; } .prototype__root .prototype__text { padding: 10px 16px; } .prototype__root .prototype__text .editor .editor-content { font-size: 18px; line-height: 1.5; } .prototype__root .prototype__option { font-size: 16px; padding: 8px 14px; margin-bottom: 8px; } } ``` ## Quick customization guide Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Quick customization guide | To change | Target | Property | | ----------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | | Dialogue height and sprite baseline | `.prototype__root` | `--vn-dialogue-height` | | Space around and between panels | `.prototype__root` | `--vn-gap` | | Space reserved below the toolbar | `.prototype__root` | `--vn-top-clearance` | | Dialogue text size | `.prototype__root .prototype__text .editor .editor-content` | `font-size` | | Dialogue text color | `.prototype__root` | `--vn-dialogue-text` | | Dialogue panel background | `.prototype__root .prototype__text` | `background` | | Scrollbar color | `.prototype__root .prototype__text` and `.prototype__root .prototype__options` | `scrollbar-color` | | Choice colors | `.prototype__root .prototype__option` | `--prototype-option-background`, `--prototype-option-background-hover`, `color` | | Choice shape | `.prototype__root .prototype__option` | `border-radius` | Changing the shared layout variables moves the related parts together. Avoid replacing them with independent pixel offsets that can overlap on small screens. ## Styling tips Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Styling tips ### Color themes Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Styling tips > Color themes Add these overrides after the template. Change the dialogue background on `.prototype__text`; `.prototype__body` spans the entire stage. #### Dark & mysterious theme Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Styling tips > Color themes > Dark & mysterious theme ```css .prototype__root .prototype__text { background: linear-gradient( 135deg, rgba(15, 15, 25, 0.9) 0%, rgba(5, 5, 15, 0.95) 100% ); } ``` #### Light & airy theme Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Styling tips > Color themes > Light & airy theme Change the text and remove its dark shadow together with the background. If you added scene-specific emphasis colors, choose darker versions of those colors for this theme too. ```css .prototype__root { --vn-dialogue-text: #172033; --vn-dialogue-shadow: none; } .prototype__root .prototype__text { background: linear-gradient( 135deg, rgba(240, 240, 250, 0.85) 0%, rgba(220, 220, 240, 0.95) 100% ); } ``` ### Custom fonts Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Styling tips > Custom fonts Want a different font? Add a valid Google Fonts import at the top: ```css @import url('https://fonts.googleapis.com/css2?family=Lora&display=swap'); .prototype__root .prototype__text .editor .editor-content { font-family: 'Lora', serif; } ``` ### Scrollbar Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Styling tips > Scrollbar Use a contrasting thumb color for both scroll areas: ```css .prototype__root .prototype__text, .prototype__root .prototype__options { scrollbar-color: #60a5fa transparent; } ``` The operating system may hide scrollbars until scrolling starts. Check that wheel and touch scrolling reach the final paragraph and final option, even if a scrollbar is not always visible. ### Text overflow Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Styling tips > Text overflow Test a scene with long dialogue and at least five multi-line choices. Scroll each area to its end. Repeat on desktop, a portrait phone, and a short landscape screen; verify the last choice remains selectable and no panel covers the toolbar. Also check a scene with only an unlabeled outgoing connection: its advance arrow stays at the end of the dialogue rather than becoming a choice button. ### Further styling Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Styling tips > Further styling You now have a solid foundation and a beautiful visual novel interface. To take this even further, try the following ideas: - **Add animations**: Try `transition` and `transform` properties for fade-ins. - **Custom buttons for specific choices**: Combine element UUID selectors with the [option targeting rules](https://docs.arcweave.com/tutorials/style-editor/css-basics#style-specific-options). Choices do not expose connection UUIDs as HTML IDs. - **Day/night themes**: Use element UUID selectors to apply different colors to specific scenes. - **Sound effects**: Combine your CSS with Arcweave's audio features. - **Character portraits**: Try different positioning for character components. - **Text effects**: Experiment with glowing text, shadows, and animations. - **Create a name tag system**: Use paragraph targeting to style character names. > ✅ Remember: CSS is all about experimentation. Don't be afraid to adjust values, try different colors, or completely redesign elements. The Style Editor updates in real-time, so you can see your changes immediately. ## Troubleshooting Context: Arcweave docs > Tutorials > Style Editor > Visual novel CSS tutorial > Troubleshooting - **Characters are cut off:** Keep the top and bottom bounds on `.prototype__components`, and `object-fit: contain` on its images. Remove old `height: 60vh` or `bottom: 350px` rules. Increasing a fixed sprite height can make clipping worse. - **Characters look small:** Check the transparent margins in the PNG and how many components share the row. The template fits the whole image into each character's available space. - **Choices extend above the screen:** Keep the `max-height` and `overflow: auto` rules on `.prototype__options`. All geometry should use the same `--vn-dialogue-height` and `--vn-gap` values. - **Dialogue does not scroll:** Check the bounded height and `overflow: auto` on `.prototype__text`. Its parent `.prototype__body` must still span the stage. Older tutorial rules that put the dialogue box on `.prototype__body` conflict with this template. - **Text is hard to read:** Increase the dialogue background opacity and check text contrast. A light background also needs dark text and no dark text shadow, as shown in [Light & airy theme](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel#light-airy-theme). - **Landscape layout is cramped:** Keep the `max-height` media query as well as the `max-width` query. Test in the actual player or iframe size, with and without editing panels. - **Scene-specific rules do not match:** Use `#el-` followed by the raw element UUID, exactly once. Copy the UUID from the Debugger's **Element** row, not the **Board** row; an element title is not an HTML ID. - **API/MCP changes are missing in an open player:** Fully reload Play Mode after saving CSS through those interfaces. Read back the saved CSS and follow the [styling workflow](https://docs.arcweave.com/project-tools/play-mode/styling-reference#save-and-verify-styles). # Unity integration tutorial Source: https://docs.arcweave.com/tutorials/unity/overview Section: Tutorials Description: Overview of the tutorial on Arcweave's plugin for Unity This series walks you through a step-by-step integration of Arcweave and Unity, in text and video. ![Screenshot from the Unity example.](https://docs.arcweave.com/assets/unity-example.C-xtGpTC.png) - [Part 1: Install & set up](https://docs.arcweave.com/tutorials/unity/pt-1): Set up your Unity project, install the Arcweave Unity plugin, import your first Arcweave project, and verify that your story runs in Unity. - [Part 2: Demo scene architecture](https://docs.arcweave.com/tutorials/unity/pt-2): Dive into the demo scene to see how narrative data flows into the game. Learn about the event-driven architecture, how your Unity project controls story progression, and how the UI reacts dynamically to narrative events. - [Part 3: Arcweave project structure](https://docs.arcweave.com/tutorials/unity/pt-3): Explore how Arcweave projects map to gameplay systems. You'll learn how to organize dialogue by NPC, manage global variables, define dialogue entry/exit points, and use Arcscript and components to shape narrative flow. - [Part 4: The 3D demo project](https://docs.arcweave.com/tutorials/unity/pt-4): See how a full 3D RPG scene integrates with Arcweave. You'll wire up NPC interactions, control game state through a central manager, and use Arcweave variables and components to drive UI, environment, and gameplay behavior. - [Part 5: Customize the template](https://docs.arcweave.com/tutorials/unity/pt-5): Customize your project by adding an NPC and setting up an alternative way to trigger dialogue that uses Arcweave components. By the end of the series, you'll understand how Arcweave handles story logic and data, how Unity consumes that data, and how to connect the two in a clean, scalable way. # Unity tutorial | Part 1: Install & set up Source: https://docs.arcweave.com/tutorials/unity/pt-1 Section: Tutorials > Unity Description: Unity tutorial part 1, installing the Arcweave plugin, exporting and importing project data, and connecting it to ArcweavePlayer This tutorial walks you through installing the Arcweave Unity Plugin, exporting a narrative project from Arcweave, and importing it into Unity. ## Video tutorial Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 1: Install & set up > Video tutorial You can watch the video version of this tutorial below. Video: https://www.youtube.com/watch?v=E3E3h5ktnNI ## Create a Unity project Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 1: Install & set up > Create a Unity project If you already have a Unity project, skip to [Download the plugin](https://docs.arcweave.com/tutorials/unity/pt-1#download-the-plugin). Open Unity Hub and click **New project** in the top right. ![Unity Hub with the New Project button highlighted](https://docs.arcweave.com/assets/unity-new-project-.D_9RfGpQ.png) 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 Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 1: Install & set up > 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](https://github.com/arcweave/arcweave-unity-plugin)** Click the green **Code** button, then select **Download ZIP**. ![GitHub repository page with Code dropdown open and Download ZIP highlighted](https://docs.arcweave.com/assets/unity-plugin-github.DlaCZQ3l.png) 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 Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 1: Install & set up > 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. ![Dragging the Arcweave folder from file explorer into Unity's Assets panel.](https://docs.arcweave.com/assets/unity-install-plugin-1.Bk1PR_48.png) 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 Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 1: Install & set up > Export for Unity The demo scene is empty until you provide narrative data from Arcweave. Log in to your Arcweave workspace at [arcweave.com](https://arcweave.com). For this tutorial, open the **Game Engine Example** project. If it is not in your workspace, click **+ New project**. ![Arcweave workspace screenshot, with the "New Project" button highlighted.](https://docs.arcweave.com/assets/workspaces-new-project.DPv-Ss89.png) Then select the **Game Engine Example** template. ![Arcweave workspace, Projects section, showing thumbnails of project templates, with the template of the Game Engine Example highlighted.](https://docs.arcweave.com/assets/project-templates-engines.CkDhZ3Sy.png) 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**. ![Arcweave Export dialog with Engine tab selected, Unity option selected, and "Include assets" also selected.](https://docs.arcweave.com/assets/unity-export.D0gb58KH.png) 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 Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 1: Install & set up > 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 Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 1: Install & set up > Import into Unity ### Add the files to your Unity project Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 1: Install & set up > 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 Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 1: Install & set up > Import into Unity > 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**. ![Unity UI showing the menus for creating the ArcweaveProjectAsset](https://docs.arcweave.com/assets/unity-create-arcweaveasset.GlLbLQx4.png) 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 Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 1: Install & set up > Import into Unity > Explore with Project Viewer In the Inspector of your ArcweaveProjectAsset, click **Open Project Viewer**. ![Unity environment showing the Inspector of the Arcweave Project Asset. An orange rectangle and an orange arrow highlight a button that says "Open project viewer."](https://docs.arcweave.com/assets/unity-open-viewer.Dm-uuTu5.png) 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. ![Arcweave Project Viewer window inside Unity showing boards and connected elements](https://docs.arcweave.com/assets/unity-viewer.CQOb6qK_.png) This lets you browse your narrative without leaving the editor. ### Connect the asset to the ArcweavePlayer Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 1: Install & set up > Import into Unity > 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. ![Unity environment showing ArcweavePlayer's inspector. An orange arrow points from the Arcweave Project Asset called MyStory into the AW field, where you should drag it in the Inspector.](https://docs.arcweave.com/assets/unity-arcweaveasset-connect.CGn8kaf0.png) Press **Play**. The demo UI will display the Arcweave narrative project you imported. ### Troubleshooting: UI buttons not responding Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 1: Install & set up > Import into Unity > 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 Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 1: Install & set up > 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](https://docs.arcweave.com/workspaces/billing-plans) 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](https://docs.arcweave.com/workspaces/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](https://docs.arcweave.com/project-tools/settings#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](https://docs.arcweave.com/project-tools/localization) project. Unity will connect to Arcweave's servers and import the latest version of the project automatically. ## Summary Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 1: Install & set up > 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. # Unity tutorial | Part 2: Demo scene architecture Source: https://docs.arcweave.com/tutorials/unity/pt-2 Section: Tutorials > Unity Description: Unity tutorial part 2, the demo scene hierarchy, the ArcweavePlayer and ArcweavePlayerUI scripts, and the event-driven loop This tutorial walks you through the internal architecture of the Arcweave Unity Plugin's Demo Scene. By the end, you'll understand exactly how data flows from Arcweave through the plugin into your UI, and how user interactions drive the story forward. ## Video tutorial Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > Video tutorial You can watch the video version of this tutorial below. Video: https://www.youtube.com/watch?v=kZhOHi5GmSk ## Scene hierarchy overview Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > Scene hierarchy overview In Unity, open the Demo Scene: 1. Navigate to the Unity folder **Assets > Arcweave > Demo**. 2. Double-click **ArcweaveDemoScene**. Once the scene opens, look at the **Hierarchy** panel. At the root level there are three main GameObjects: - [ArcweavePlayer](https://docs.arcweave.com/tutorials/unity/pt-2#arcweaveplayer): Manages the project's narrative. - [@ArcweavePlayerUI](https://docs.arcweave.com/tutorials/unity/pt-2#arcweaveplayerui): Manages the UI related to the project's narrative. - [EventSystem](https://docs.arcweave.com/tutorials/unity/pt-2#eventsystem): Unity's event system, which handles UI input such as button clicks. > ℹ️ Both **ArcweavePlayer** and **@ArcweavePlayerUI** use the Arcweave plugin for Unity. To learn more about how the plugin works, visit its [GitHub repository](https://github.com/arcweave/arcweave-unity-plugin#plugin-documentation). We'll start with **ArcweavePlayer**, the narrative brain that drives story flow, then move to **@ArcweavePlayerUI**, which listens to its events and updates the visuals. ## ArcweavePlayer Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > ArcweavePlayer ### Overview Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > ArcweavePlayer > Overview #### Hierarchy Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > ArcweavePlayer > Overview > Hierarchy The **ArcweavePlayer** GameObject is the system's narrative manager. It has no child objects and no visual representation; it is purely logic. ![Unity's environment with an orange arrow pointing at the ArcweavePlayer game object in the project's Hierarchy.](https://docs.arcweave.com/assets/unity-hierarchy-2.BdYffQW6.png) #### Inspector Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > ArcweavePlayer > Overview > Inspector Selecting the **ArcweavePlayer** in the Hierarchy reveals a single component in the Inspector with three public fields: - **ArcweavePlayer script**: The object's script; see right below. - **Aw**: The `ArcweaveProjectAsset` reference. This is the imported Arcweave project, i.e. the story data the player will run. - **Auto Start**: When checked, the narrative begins automatically when the scene loads. When unchecked, you call `PlayProject()` manually, which is useful if you want to show a title screen first. ### Script Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > ArcweavePlayer > Script The real power of the ArcweavePlayer component lies in its script. Open `ArcweavePlayer.cs` in your code editor to follow along. #### Events Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > ArcweavePlayer > Script > Events `ArcweavePlayer` exposes five events that form the communication bridge between narrative logic and visual presentation. The player handles only story flow; when the narrative state changes, it fires an event. `ArcweavePlayerUI` listens and reacts. This is a classic **observer pattern**. | Event | When it fires | What it passes | | ------------------ | ------------------------------------ | ---------------------------------------------- | | `onProjectStart` | Once, when the narrative begins | The `Project` object | | `onElementEnter` | Every time a new element is entered | The `Element` object | | `onElementOptions` | When the player has multiple choices | An `Options` object + a callback `Action` | | `onWaitInputNext` | When there is only one path forward | A callback `Action` | | `onProjectFinish` | When the story reaches an endpoint | The `Project` object | `onElementOptions` passes a callback that accepts an integer — the index of the chosen path. `onWaitInputNext` passes a callback without parameters, since there is no choice to make. Without these events, the UI would have no way to know when to refresh content, create buttons, or show a restart screen. #### Methods Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > ArcweavePlayer > Script > Methods `Start()`: Unity's built-in method. If `autoStart` is true, it calls `PlayProject()`. --- `PlayProject()`: Initializes and starts the narrative. 1. Verifies the `Aw` field is assigned. 2. Calls `aw.Project.Initialize()`, resetting all variables to defaults and all visit counts to zero. 3. Fires `onProjectStart` if any listeners are subscribed. 4. Calls `Next(aw.Project.StartingElement)` to jump to the first element. --- `Next(Path path)`: Called when the player selects an option or clicks **Continue**: 1. Calls `path.ExecuteAppendedConnectionLabels()` to run any Arcscript on the connection (e.g. `has_key = true`, `player_health -= 10`). 2. Calls `Next(path.TargetElement)` to advance to the target element. --- `Next(Element element)`: The heart of the system: 1. Stores the element as `currentElement`. 2. Increments `currentElement.Visits`. 3. Fires `onElementEnter`. 4. Calls `currentElement.GetOptions()` to evaluate all branch conditions and determine available paths. 5. Branches on the result: - **No paths** → the story is over; fire `onProjectFinish`. - **Paths + options** → fire `onElementOptions` with the choices and a callback; return and wait for user input. `hasOptions` is true when there are multiple paths, or a single path with a label. - **Paths, no options** → a single unlabeled path (a "Continue" moment); fire `onWaitInputNext` with a callback; return and wait. --- `Save()` and `Load()`: The save system stores the current element's ID and all variable states as JSON in Unity's `PlayerPrefs`. Loading retrieves them, restores variable states via `LoadVariables()`, and calls `Next(element)` to jump back to the saved story point. ## @ArcweavePlayerUI Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > @ArcweavePlayerUI ### Overview Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > @ArcweavePlayerUI > Overview #### Hierarchy Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > @ArcweavePlayerUI > Overview > Hierarchy This GameObject holds the **ArcweavePlayerUI** component and all the visual UI structure underneath it. The `@` prefix is a naming convention to keep it visually distinct in the Hierarchy. ![Unity's environment with an orange rectangle emphasizing the ArcweavePlayerUI game object and its children in the project's Hierarchy.](https://docs.arcweave.com/assets/unity-hierarchy-1.Cien5V7c.png) To see the UI layout clearly, switch to the **Scene** tab and enable **2D view** from the Scene view toolbar. Zoom out with the scroll wheel if needed. Expanding `@ArcweavePlayerUI` in the Hierarchy reveals the following structure under a root **Panel**: - **TopSection**: Visual imagery and the save/load controls at the top of the screen - **VisualContainer** - **ComponentCoverWrapper > FirstComponentCover**: A `RawImage` that displays character portraits or entity images - **CoverWrapper > Cover**: A `RawImage` that displays the element's main cover image - **ControlsContainer**: Save/load buttons - **Save** (with a Text child) - **Load** (with a Text child) - **ContentContainer** - **Content**: The `Text` component that displays dialogue or story content - **OptionsContainer**: The interactive choice buttons area - **Button**: A template button that gets cloned dynamically for each player option, with a **Text** child for the button label #### Inspector Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > @ArcweavePlayerUI > Overview > Inspector Select `@ArcweavePlayerUI` and look at the **ArcweavePlayerUI** component in the Inspector. Its fields are organized into sections: - **Core**: The **Player** field references the `ArcweavePlayer` GameObject. This is the critical link: it tells the UI which narrative player to listen to. - **Text Display**: References to the `Content` text component, plus fallback strings for empty content, empty option labels, the continue button, and the restart button. - **Images**: The **Cover** and **Component Cover** fields reference the `Cover` and `FirstComponentCover` `RawImage` components. - **Buttons**: References to the `Button` template, the `Save` button, and the `Load` button. - **Animation**: - **Enable Fade** (checked by default) - **Crossfade Time** (0.5 seconds by default) for smooth transitions These references tell `ArcweavePlayerUI` exactly which UI elements to update when narrative events fire. ### Script Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > @ArcweavePlayerUI > Script Now that the Inspector references are wired up, select `@ArcweavePlayerUI` and open the script `ArcweavePlayerUI.cs`, to see how the component uses them at runtime. The sections below follow the script from top to bottom: #### Initialization & cleanup Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > @ArcweavePlayerUI > Script > Initialization & cleanup `OnEnable()`: Runs when the GameObject becomes active: 1. Deactivates the button template (`buttonTemplate.gameObject.SetActive(false)`). 2. Initializes both images to invisible (alpha 0). 3. Connects the Save and Load buttons with their methods. 4. Hides the Load button if no save file exists. 5. Subscribes to four of the player's five events (all except `onProjectStart`): - `onElementEnter` - `onElementOptions` - `onWaitInputNext` - `onProjectFinish` `OnDisable()`: Unsubscribes from all events to prevent memory leaks, when the GameObject is disabled or destroyed. #### Save & load Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > @ArcweavePlayerUI > Script > Save & load `Save()` and `Load()` are simple wrapper methods for the UI buttons. `Save()`: Calls the ArcweavePlayer's `Save()` method (see ArcweavePlayer > [Script](https://docs.arcweave.com/tutorials/unity/pt-2#script)). It also enables the **Load button**, so the player knows a saved file exists. `Load()`: Clears any existing player option buttons and then calls ArcweavePlayer's `Load()` method which jumps to the saved element. This fires the event `onElementEnter` (see below), which rebuilds the UI. #### Event handler methods Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > @ArcweavePlayerUI > Script > Event handler methods `OnElementEnter`: Fires every time a new element is entered: 1. Calls `DisplayContent(e)` to update the dialogue text. 2. Calls `DisplayImage(cover, e.GetCoverOrFirstComponentImage())` to update the main cover. If the element has no cover, the first component's cover is used as a fallback. 3. If the element has its own cover, also shows the component cover in the `componentCover` slot; otherwise hides it. `OnElementOptions`: Fires when there are multiple choices. Loops through `options.Paths` and calls `MakeButton()` for each, passing a lambda that invokes `callback(index)` when clicked. `OnWaitInputNext`: Fires for single-path moments. Calls `MakeButton()` once with the "Continue" label. `OnProjectFinish`: Fires when the story ends. Calls `MakeButton()` with the "Restart" label, passing `player.PlayProject` as the callback. #### Display & image methods Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > @ArcweavePlayerUI > Script > Display & image methods `DisplayContent`: Handles the story content and how it appears on the screen: 1. If the element has content, calls `e.RunContentScript()` to evaluate all Arcscript and populate `RuntimeContent`. Skipping this would leave raw Arcscript markup visible. 2. Sets `content.text` to `RuntimeContent` or the "No Content" fallback if empty. 3. Fades the text in over `crossfadeTime` seconds if `enableFade` is true, or sets alpha to 1 instantly otherwise. `FadeImage`: A coroutine that handles smooth image transitions: 1. If fade is enabled, the current image is visible, and the texture is changing: fade out the old image first. 2. Assign the new texture, call `UpdateAspectRatio()` to maintain correct proportions, then fade in. 3. If the texture is null, hide and clear the image. `UpdateAspectRatio`: Calculates the texture's width-to-height ratio and updates the `AspectRatioFitter` component so images are never stretched or squashed. #### Button management Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > @ArcweavePlayerUI > Script > Button management `MakeButton`: Creates and displays an option button: 1. Instantiates a clone of the button template, parented to the same container. 2. Sets the button visible and adds it to `tempButtons` for later cleanup. 3. Sets the label text. 4. Fades in the button (or sets alpha to 1 instantly). 5. Adds a click listener that first calls `ClearTempButtons()` to destroy all existing buttons, then invokes the `onClick` callback to trigger `Next()` in the player. `ClearTempButtons()`: Destroys all GameObjects in `tempButtons` and clears the list, preventing old choices from accumulating on screen. ## EventSystem Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > EventSystem Unity's standard event system, required for handling UI clicks and interactions. Its input module must match the project's **Active Input Handling** setting; see [Troubleshooting: UI buttons not responding](https://docs.arcweave.com/tutorials/unity/pt-1#troubleshooting-ui-buttons-not-responding). ## Play and inspect Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > Play and inspect To observe the full flow, set up a split view in the Unity Editor with the Hierarchy, Game view, and Inspector visible simultaneously. In the Project window, select your ArcweaveProjectAsset (for example, `MyStory`) so you can watch the project's variables in the Inspector. The **ArcweavePlayer** Inspector only shows its **Aw** and **Auto Start** fields. Click **Play**. ![Unity Editor in Play mode showing Game view with dialogue and option buttons, Hierarchy, and Inspector showing the variables of the Arcweave Project Asset](https://docs.arcweave.com/assets/unity-play-variables.MoEJg4ct.png) Here is what happened the moment Play was pressed: 1. `Start()` ran → `autoStart` is true → `PlayProject()` fired. 2. `aw.Project.Initialize()` reset all variables (`have_potion = false`, `healer_health = 50`, `wanda_health = 20`). 3. `Next(StartingElement)` was called → `currentElement.Visits` incremented → `onElementEnter` fired. 4. `GetOptions()` found two paths → `onElementOptions` fired → `MakeButton()` created two `Button(Clone)` GameObjects under `OptionsContainer`. Click **Go to Healer**. The old buttons are destroyed, the callback invokes `Next(path)`, `ExecuteAppendedConnectionLabels()` runs any Arcscript on that connection, and `Next(targetElement)` advances the story. `onElementEnter` fires again, the UI updates with the Healer's dialogue and a new cover image. Continue through the story to the point where you receive a potion. Watch the Inspector: when `DisplayContent()` calls `e.RunContentScript()`, the Arcscript embedded in the element's content executes and `have_potion` changes from `false` to `true`. Navigate to Wanda and examine her. Because `have_potion` is `true`, the branch condition allows the "Give her the potion" option to appear. Choosing it leads to an element whose content Arcscript (`wanda_health += 50`) runs when `DisplayContent()` calls `RunContentScript()`, so `wanda_health` updates accordingly. ## Event-driven loop Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 2: Demo scene architecture > Event-driven loop Here is a summary of the game loop: 1. **Button clicked** → `ClearTempButtons()` destroys old buttons → callback invokes `Next(path)`. 2. `ExecuteAppendedConnectionLabels()` runs connection label Arcscript → variables update. 3. `Next(targetElement)` advances the story → `Visits` increments → `onElementEnter` fires. 4. **UI updates** → `DisplayContent()` and `DisplayImage()` refresh text and images → new buttons are created via `MakeButton()`. The architecture is deliberately decoupled: - `ArcweavePlayer` manages story flow, evaluates conditions, and broadcasts events. It knows nothing about the UI. - `ArcweavePlayerUI` listens to those events and updates visuals. It makes no narrative decisions. - **Variables** track state across the entire playthrough. - **Arcscript** drives logic through content and connection labels. Because everything communicates through events, you can extend the system freely — add sound effects, trigger animations, or integrate with any game system — simply by subscribing to the same five events. # Unity tutorial | Part 3: Arcweave project structure Source: https://docs.arcweave.com/tutorials/unity/pt-3 Section: Tutorials > Unity Description: Unity tutorial part 3, how the demo's Arcweave project uses boards, variables, branches, Arcscript, and components This tutorial covers the Arcweave project that drives the **Arcweave Unity Example**, a 3D RPG demonstrating Arcweave's integration with Unity. You can find the example on [its GitHub repo](https://github.com/arcweave/arcweave-unity-example). Before opening Unity and playing the demo, it's worth understanding how the data is structured on the Arcweave side, because that is where the project's narrative logic lives. Once you understand how the project is organized, wiring it up in Unity becomes straightforward. > **Prerequisites:** This tutorial is part of a series on Arcweave's Unity integration. It assumes you have completed [Part 1](https://docs.arcweave.com/tutorials/unity/pt-1) and [Part 2](https://docs.arcweave.com/tutorials/unity/pt-2), where you installed the plugin and explored a simple 2D scene. ## Video tutorial Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 3: Arcweave project structure > Video tutorial You can watch the video version of this tutorial below. Video: https://www.youtube.com/watch?v=33DtZciyCx0 ## Project overview Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 3: Arcweave project structure > Project overview ### Boards Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 3: Arcweave project structure > Project overview > Boards Open the Arcweave project used for the Unity demo. The first thing to examine is the board list on the left side of the editor. ![The Arcweave editor with the board list visible on the left sidebar, showing the Healer and Wanda boards](https://docs.arcweave.com/assets/unity-aw-project-boards.DMyO5lQy.png) The project has three boards: - **Starting Board**: Contains the starting element for testing the project in Arcweave's Play Mode. We won't be using this board in the Unity 3D project, although the [2D demo scene](https://docs.arcweave.com/tutorials/unity/pt-2) uses it, as we saw in Part 2. - **Dialogues** (folder): - **Healer Dialogue**: The dialogue tree between the player and the healer NPC. - **Wanda Dialogue**: The dialogue tree between the player and Wanda, the injured NPC. In the 3D demo we'll explore next, the relevant boards are **Healer Dialogue** and **Wanda Dialogue**, and _their names are not decorative._ As we'll see [in the next part of this tutorial](https://docs.arcweave.com/tutorials/unity/pt-4#dialoguetrigger), these names are the only connection between an NPC and their dialogue, in Unity. ## Global variables Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 3: Arcweave project structure > Global variables Before going into the boards, open the **Global variable dialog** from the project sidebar. ![The Global variable dialog showing have_potion (boolean), healer_health (integer), and wanda_health (integer)](https://docs.arcweave.com/assets/unity-aw-project-variables.eldkdosF.png) The project defines three variables: - `have_potion` — boolean, default `false` - `healer_health` — integer, default `50` - `wanda_health` — integer, default `20` In Unity, the `ArcweaveHealthUI` component on each NPC reads from this list, using the variable name as a string key to get the current value. Arcweave owns the values; Unity reads them. If you add a new variable here, it becomes accessible in Unity after you re-import the project — no code changes required. ## Boards and dialogue flow Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 3: Arcweave project structure > Boards and dialogue flow ### Entry and exit points Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 3: Arcweave project structure > Boards and dialogue flow > Entry and exit points Open the **Healer Dialogue** board. This is a graph where each box is an element, a moment in the dialogue, and the arrows are connections representing the paths a player can follow. The first thing to identify is the entry point. Unity needs to know when a conversation starts so it can lock player movement, and when it ends so it can return control. Locate the first element of the dialogue. The icon at its top right corner shows that the element has attributes: hover over it to preview them, or double-click it (or right-click the element and select **Properties**) to open the **Element Properties** dialog on its **Attributes** tab. ![An element's attributes panel showing its dialogue_start tag. Orange shapes highlight the element's attributes icon and the panel itself.](https://docs.arcweave.com/assets/unity-aw-project-element-attributes.BpNsySmt.png) This element has an attribute named `tag` with the value `dialogue_start`. When Unity opens a board for an NPC, it searches for this tag to know where to begin. Without it, the entry point is unpredictable. **Always tag the first element explicitly.** The element's content holds the Healer's opening line — the text Unity displays in the dialogue box when this element is reached. At the other end of the graph, there is a final element tagged `dialogue_end`. When Unity detects this tag, it closes the dialogue and returns control to the player. This is your explicit exit point. The tag string must match what Unity expects — the default is `dialogue_end`. ### Player choices Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 3: Arcweave project structure > Boards and dialogue flow > Player choices The outgoing connections from an element represent the player's choices. Each connection label becomes a button in the UI — for example, _Ask for help_ or _"I'm sorry, wrong turn."_ ### Arcscript in elements Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 3: Arcweave project structure > Boards and dialogue flow > Arcscript in elements Some elements contain Arcscript. Look for elements whose content includes an expression such as `have_potion = true`. ![An element with Arcscript content visible, showing have_potion = true](https://docs.arcweave.com/assets/unity-aw-project-element-arcscript.A-221Ax3.png) This script runs when the player arrives at that element — before the element content is rendered. That is the moment `have_potion` flips from `false` to `true`. ### Branches Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 3: Arcweave project structure > Boards and dialogue flow > Branches The project also includes [branches](https://docs.arcweave.com/project-items/branches), project items that evaluate conditions and direct the flow accordingly. Open the **Wanda Dialogue** board and notice the branch with the condition `if have_potion`. Arcweave evaluates the expression `have_potion` to decide whether the player option to _Give her the potion_ should be available. ![The branch that evaluates "if have_potion" in Wanda's board](https://docs.arcweave.com/assets/unity-aw-project-branch.BBQ2i8Lk.png) ## Components and attributes Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 3: Arcweave project structure > Components and attributes Navigate to the **Components** section in the project sidebar. Components in Arcweave are reusable data containers, named objects that hold attributes. They don't drive narrative flow; they hold configuration that scripts in Unity read. ### The Environment component Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 3: Arcweave project structure > Components and attributes > The Environment component Open the component named **Environment**. ![The Environment component with its Time and Weather attributes visible](https://docs.arcweave.com/assets/unity-aw-project-component-environment.DPbzlO5i.png) It has two attributes: - `Time`: A string, either `Day` or `Night` - `Weather`: A string, either `Clear` or `Rain` In Unity, a script reads these values when the project loads and updates the scene accordingly — showing the skybox by day or a solid night color by night, and starting or stopping the rain particle system. To change the weather or time of day in the game, update the attribute value here and re-import in Unity. No code changes needed. ### Character components Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 3: Arcweave project structure > Components and attributes > Character components Each NPC has its own component named after them: **Healer** and **Wanda Elandor**. ![Wanda's component showing the Color, Race, and obj_id attributes](https://docs.arcweave.com/assets/unity-aw-project-component-wanda.Bd03i9U7.png) Open Wanda's component to see its attributes: - `Color`: A color string, for example `Blue` - `Race`: A text description of the character - `obj_id`: A custom string that can be used to reference this component from Unity In Unity, the `Color` attribute controls the fill color of the character's health bar slider. The `obj_id` can be used to match components from Unity code when a name-based lookup isn't sufficient. String Field component attributes also import as scoped variables when both the attribute and its component have custom IDs. Their Arcscript and Unity scope uses the component custom ID, so Wanda's `Color` attribute (custom ID `color`) on the component with custom ID `wanda_elandor` is available as `wanda_elandor.color`. The demo handlers still look these attributes up by component and attribute name; `ArcweaveSceneController` uses the scoped variable's current value when one exists. ### Components attached to elements Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 3: Arcweave project structure > Components and attributes > Components attached to elements Components can also be attached to individual elements. ![Arcweave environment. Elements in the board with components attached, showing the component cover image thumbnails.](https://docs.arcweave.com/assets/unity-aw-project-component-attached.BozowowP.png) When an element's first attached component has a cover image, Unity displays that image as the character portrait during dialogue. To show a character portrait during a specific line of dialogue: attach a component with a cover image to the relevant element, as its first component. ## Summary Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 3: Arcweave project structure > Summary The Arcweave project follows a few consistent rules that everything else builds on: **Boards are named after NPCs.** Each NPC in Unity references their board by name. The string must match exactly. **Variables are typed and can be global or scoped.** This template keeps its main story-state variables global. String Field, Boolean, Integer, and Float board and component attributes are also available through their owner scope when both the attribute and its owner have custom IDs. **Tags control flow entry and exit.** `dialogue_start` tells Unity where to begin a conversation; `dialogue_end` tells it when to return to gameplay. Both must match the strings Unity expects. **Components hold configuration.** The `Environment` component drives scene visuals. Character components drive properties like the health bar slider color. This project is intentionally small — two NPCs, three variables, a handful of components — but the pattern scales. More NPCs means more boards. More gameplay effects means more variables and components. The architecture stays the same. # Unity tutorial | Part 4: The 3D demo project Source: https://docs.arcweave.com/tutorials/unity/pt-4 Section: Tutorials > Unity Description: Unity tutorial part 4, the 3D demo project with its GameManager, NPC dialogue triggers, and extension patterns This tutorial walks through a full 3D RPG demo that shows how each piece of an Arcweave project connects to a Unity scene. You will see characters you can walk up to, conversations that change health bars and environmental effects, and a world that reacts to story choices. ## Video tutorial Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > Video tutorial You can watch the video version of this tutorial below. Video: https://www.youtube.com/watch?v=qPq1QCNuYnQ ## Download project Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > Download project Download the 3D demo project [from GitHub](https://github.com/arcweave/arcweave-unity-example). Click the green **Code** button, then **Download ZIP**. Extract it and open Unity Hub. ![GitHub repository page showing the green Code button and Download ZIP option](https://docs.arcweave.com/assets/unity-demo-download.F-TdvLwd.png) In Unity Hub, click **Open → Add project from disk**, select the `arcweave-unity-example` root folder, and open it. Unity will import assets on first load; this may take a minute. Once loaded, navigate to **Assets > Scenes** and double-click **Demo Scene** to open the scene. ## What the demo does Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > What the demo does Before diving into the wiring, it helps to see the demo running. Hit **Play** in the Editor. ![The village scene in Unity's Play mode, showing the Player and two NPCs and health bars above them.](https://docs.arcweave.com/assets/unity-demo-play.Zrzm30g6.png) You are in a small village with two NPCs. Notice the health bar above them. That value is driven by an Arcweave variable, not set manually in Unity. Walk toward the Healer until a prompt appears, then press **E**. The player freezes, the camera locks, and the dialogue UI slides in: the same **ArcweavePlayerUI** covered in the earlier tutorials. ![The dialogue UI appearing after pressing E near the Healer NPC](https://docs.arcweave.com/assets/unity-demo-play-2.D7MD8OtY.png) Make a choice and work through the conversation. When it ends, movement is restored and you return to the world. Now walk to Wanda. She has low health. If you got a potion during the Healer conversation, you will see the option to give it here. Watch the bar above her head update immediately when you do. Finally, press **Escape** during gameplay. The game pauses and an import menu appears. This is how you re-import the Arcweave project at any time, from the web or a local JSON file, without rebuilding or redeploying. ![The importer UI that appears when pressing Escape](https://docs.arcweave.com/assets/unity-demo-play-settings.D9E7MBG5.png) Press **Escape** again to close it, then stop Play mode. ## Scene hierarchy overview Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > Scene hierarchy overview Open the Hierarchy panel and expand all top-level objects. **ArcweavePlayer** and **ArcweavePlayerUI** work as described in [Part 2](https://docs.arcweave.com/tutorials/unity/pt-2), with a few demo-specific additions: **Auto Start** is off, because each NPC's dialogue trigger starts its own conversation, and **ArcweavePlayerUI** ends the conversation when it reaches an element marked as a dialogue end. Five additional systems build on top of them. ## GameManager GameObject Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > GameManager GameObject Select the **GameManager** object and look at its Inspector. ![Unity's environment. An orange arrow is pointing at the GameManager object in the scene Hierarchy.](https://docs.arcweave.com/assets/unity-hierarchy-3.4FrYq7W5.png) ### GameManager component Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > GameManager GameObject > GameManager component The first component of the GameManager GameObject is **GameManager**. It is a singleton with three states: `Gameplay`, `Dialogue`, and `Paused`. It holds references to all major scene objects (**ArcweaveUI**, **ImporterUI**, **PlayerController**, **ThirdPersonCamera**) and enables or disables them as the state changes. Two string fields control how dialogue boundaries are identified: - **dialogueStartTag**: defaults to `dialogue_start` - **dialogueEndTag**: defaults to `dialogue_end` These strings must match exactly the tags placed on elements in the Arcweave boards. There are also two optional fields: - **dialogueStartComponentName** - **dialogueEndComponentName** When filled in, the demo first looks for an element carrying an Arcweave **component** with that name, and falls back to matching the tag value if no element has it. Use this when you prefer to mark entry and exit points with a dedicated component rather than a tag string. When the state becomes `Paused`, triggered by pressing Escape, **GameManager** shows the **ImporterUI**. ### ArcweaveSceneController component Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > GameManager GameObject > ArcweaveSceneController component The GameManager GameObject also has the component **ArcweaveSceneController**. ![The Unity environment. An orange arrow is pointing at the GameManager game object in the Hierarchy, while an orange rectangle emphasizes the Arcweave Scene Controller component in the Inspector.](https://docs.arcweave.com/assets/unity-arcweavescenecontroller.C5btuski.png) **ArcweaveSceneController** reads scene configuration from the Arcweave project on three occasions: - When the scene starts - When the narrative reaches an element with no outgoing paths (`onProjectFinish`) - When a new project is imported (`onImportSuccess`) It draws its **Time** (`Day`/`Night`) and **Weather** (`Clear`/`Rain`) values from the Arcweave project's **Environment** component. The component and these two Arcweave attributes link with the following fields in **ArcweaveSceneController**'s Inspector: - **Component Name**: Set to `Environment`; the Arcweave component to read. - **Time Attribute**: Set to `Time`; it controls the camera's clear flags; Skybox for day, solid black for night. - **Particle Attribute**: Set to `Weather`; it controls whether particle systems in the scene are playing. Change the attribute values in Arcweave's **Environment** component, reimport, and the environment updates automatically. ## NPC GameObjects Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > NPC GameObjects Let's now have a look at the components of our NPC GameObjects. ### DialogueTrigger Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > NPC GameObjects > DialogueTrigger Select any NPC in the Hierarchy and find the **DialogueTrigger** component in its Inspector. ![The Unity environment. An orange arrow is pointing at the Healer NPC game object in the Hierarchy, while an orange rectangle emphasizes the Dialogue Trigger component in the Inspector.](https://docs.arcweave.com/assets/unity-dialoguetrigger.C7DqpGaS.png) **DialogueTrigger** runs every frame, measuring the distance between the NPC and the player. When the player is close enough and presses the interaction key, this component starts the dialogue flow. The key field is **Specific Board Name**. This string must match exactly the name of a board in the Arcweave project (`Healer Dialogue`, `Wanda Dialogue`, and so on). That single string is the only link between an NPC and their dialogue. If you rename a board in Arcweave without updating the Unity Inspector, the connection will break and the NPC will have nothing to say. Other configurable fields: - **Trigger Distance**: How close the player must be before the prompt appears - **Interaction Key**: Key to press (default: E) - **Interaction Text**: Reference to the 3D TextMeshPro label above the NPC's head > ✅ With **Gizmos** enabled in the Scene view, select an NPC to see its trigger radius as a yellow wire sphere. ### ArcweaveHealthUI Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > NPC GameObjects > ArcweaveHealthUI Select an NPC that has a health bar. Find **ArcweaveHealthUI** in its Inspector. ![The Unity environment. An orange arrow is pointing at the Healer NPC game object in the Hierarchy, while an orange rectangle emphasizes the Arcweave Health UI component in the Inspector.](https://docs.arcweave.com/assets/unity-arcweavehealthui.DItoYWqO.png) **ArcweaveHealthUI** reads a health variable from the Arcweave project every frame and pushes its value to a UI Slider. The relevant fields are: - **Health Variable Name**: the name of the Arcweave variable (e.g. `wanda_health`) - **Health Bar**: the UI Slider above the NPC's head - **Max Health**: sets the slider's full scale The component also updates on `onProjectFinish` and `onImportSuccess` to stay in sync after imports. A separate **Slider Color** section lets you point to an Arcweave component attribute containing an HTML color string: a hex value such as `#FF0000` or a color name such as `Red`. When the project loads, that color is applied to the slider fill. Change the color in Arcweave, reimport, and the bar updates; no code required. ### ArcweaveObjectActivation Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > NPC GameObjects > ArcweaveObjectActivation Select an NPC that has **ArcweaveObjectActivation** in its Inspector. ![The Unity environment. An orange arrow is pointing at the Healer NPC game object in the Hierarchy, while an orange rectangle emphasizes the Arcweave Object Activation component in the Inspector.](https://docs.arcweave.com/assets/unity-arcweaveobjectactivation.BWOX6_KA.png) This component shows or hides a GameObject based on a boolean Arcweave variable. Two fields: - **Target Object**: the GameObject to activate or deactivate - **Activation Variable Name**: the boolean variable to watch The logic is inverted: while the variable is `false`, the object is active. When the variable becomes `true`, the object is deactivated and stays inactive for the rest of the session, even if the variable later returns to `false`. A reimport (`onImportSuccess`) or `onProjectFinish` resets this. ## Extension patterns Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > Extension patterns Beyond the five systems above, the demo includes two reusable patterns for connecting Arcweave data to custom Unity behavior. > ℹ️ For specific details on how these scripts work, take a look at the README file in the [GitHub repository](https://github.com/arcweave/arcweave-unity-example) of the Unity example. ### ArcweaveAttributeHandler Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > Extension patterns > ArcweaveAttributeHandler Go to the **Assets > Scripts > Handlers** folder and open **ArcweaveAttributeHandler**. ![Unity's environment. An orange arrow points at the Arcweave Attribute Handler file in the project's folder system. The inspector shows a preview of its script.](https://docs.arcweave.com/assets/unity-arcweaveattributehandler.BpOcO9o3.png) **ArcweaveAttributeHandler** is an abstract base class that handles the boilerplate of finding a component by name, finding an attribute by name, and subscribing to the right events. You subclass it, override one method, and implement your behavior. ArcweaveHealthUI uses the same lookup pattern in its own code, without subclassing **ArcweaveAttributeHandler**: it reads a color string from an Arcweave attribute and applies it to the health bar slider fill. Any Arcweave attribute can drive any Unity object through a subclass of **ArcweaveAttributeHandler**. Full documentation is available in the GitHub repository. ### ArcweaveElementComponentHandler Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > Extension patterns > ArcweaveElementComponentHandler Go to the **Assets > Scripts > Handlers** folder and open **ArcweaveElementComponentHandler**. ![Unity's environment. An orange arrow points at the Arcweave Element Component Handler file in the project's folder system. The inspector shows a preview of its script.](https://docs.arcweave.com/assets/unity-arcweaveelementcomponenthandler.N1KClVBG.png) Where **ArcweaveAttributeHandler** reads data at project load time, **ArcweaveElementComponentHandler** reacts to components attached to specific dialogue **elements**, firing every time the player enters a new element during a conversation. The concrete example in the scene is **SwordSwingHandler**. Its **Component Name** field is set to `attack`. When the dialogue reaches an element that has the `attack` component attached, this handler fires and permanently enables the player's sword swing ability; left-click now triggers the attack animation. The component's presence on the element is the trigger itself. This pattern is covered in more detail in the next tutorial. > ℹ️ For specific details on how these scripts work, take a look at the README file in the [GitHub repository](https://github.com/arcweave/arcweave-unity-example) of the Unity example. ## How it all connects Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 4: The 3D demo project > How it all connects The clearest way to understand these systems working together is to watch variables change during Unity's Play mode. ![Unity Editor in Play mode showing Game view with dialogue and option buttons, Hierarchy, and Inspector showing the variables of the Arcweave Project Asset](https://docs.arcweave.com/assets/unity-play-variables.MoEJg4ct.png) In the Project window, select the ArcweaveProjectAsset assigned to **ArcweavePlayer**'s **Aw** field (`ArcweaveProjectAssetV2` in **Assets > Arcweave**) so the Inspector shows the project's variables, then enter Play mode. **Approaching the Healer.** **DialogueTrigger** measures distance every frame. While outside the trigger radius, no prompt appears. **Stepping inside the radius.** The prompt appears. Press **E**. Under the hood: **DialogueTrigger** called `GameManager.Instance.StartDialogue()`. **GameManager** switched to `GameState.Dialogue`, disabling **PlayerController** and **ThirdPersonCamera**, showing **ArcweaveUI**, and unlocking the cursor. Then **DialogueTrigger** ran `FindAndStartNPCDialogue()`, which searched the Arcweave project for a board named `Healer Dialogue`, found the element tagged `dialogue_start` inside it, and called `arcweavePlayer.Next()` on it. From there, `onElementEnter` fires and **ArcweavePlayerUI** updates, exactly as described in the earlier tutorials. **Making a choice.** Watch `have_potion` in the Inspector. Click **"Ask for help"**, then **Continue**. `have_potion` now becomes `true`. Each button click invokes the player's callback, which runs any Arcscript in the connection labels and enters the next element. When **ArcweavePlayerUI** displays the Healer's reply, it calls `RunContentScript()`, which executes the Arcscript `have_potion = true` embedded in that element's content. **Ending the Healer dialogue.** The Healer's reply is tagged `dialogue_end`. When you click its button, **ArcweavePlayerUI** calls the active **DialogueTrigger**'s `EndDialogue()`, which calls `GameManager.Instance.EndDialogue()`. State returns to `Gameplay` and controls are restored. If the narrative reaches an element with no outgoing paths instead, `onProjectFinish` ends the dialogue the same way. **Walking to Wanda.** Because `have_potion` is `true`, `GetOptions()` evaluated the condition on the "Give her the potion" path as true, and the button is visible after you examine her. If you had visited Wanda first, without the potion, this option would not have appeared. **Giving the potion.** Watch `wanda_health` in the Inspector jump to 70. The health bar responds at the same frame; **ArcweaveHealthUI** polled the variable in `Update` and pushed the new value to the Slider. # Unity tutorial | Part 5: Customize the template Source: https://docs.arcweave.com/tutorials/unity/pt-5 Section: Tutorials > Unity Description: Unity tutorial part 5, extending the template with new variables, components, and a dialogue board, then re-importing into Unity Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. In this tutorial, you'll add a Fighter NPC who teaches the player combat, for a price. The result depends on whether the player can afford the training. You'll use Arcweave components to mark where each dialogue starts and ends, and to signal Unity when to enable the attack animation. ## Expanded project Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Expanded project This tutorial focuses on expanding Arcweave's original Game Engine Example template. You can play the expanded version in the embedded window below and see its boards [here](https://arcweave.com/app/project/4OlzN3zlqP): Embedded content: https://arcweave.com/embed/4OlzN3zlqP/play ## Video tutorial Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Video tutorial You can watch the video version of this tutorial below. Video: https://www.youtube.com/watch?v=cuisZChIn5k ## Set up variables Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Set up variables Open your Arcweave project and navigate to the **Global variable dialog**. Add two new variables: - `gold`: integer, default `50`. The player starts with exactly enough to pay for training. - `sword_locked`: boolean, default `true`. The player starts without combat training. ![Global variable dialog showing gold and sword_locked variables](https://docs.arcweave.com/assets/unity-aw-project-variables-add.mP2x3OuF.png) `sword_locked` is the narrative flag that tracks the player's state. It starts as `true` (not yet trained), drives the conditional text in the dialogue, and controls which branch the player can take. ## Create components Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Create components In the Components panel, create four components: - `dialogue_start`: marks the element where a conversation begins. Unity looks for this component name, as configured on the `GameManager`, to find the entry point. No attributes needed. - `dialogue_end`: marks the exit element. When Unity detects it, the dialogue closes and gameplay resumes. - `Fighter`: the character component. Attach a portrait image here; the filename (e.g. `fighter.png`) must match the file you'll place in Unity's `Resources/` folder. - `attack`: the gameplay signal. When the dialogue reaches an element with this component attached, a Unity script detects it and enables the attack ability on the player. No attributes needed, just the name matters. > ⚠️ The component names' capitalization does not need to follow a specific protocol, but make sure you are consistent between your Arcweave and Unity projects. Here, we're using snake case, except for the `Fighter` component, in order for it to match the other character components. ![Arcweave's project environment with orange rectangles highlighting the four new aforementioned components.](https://docs.arcweave.com/assets/unity-aw-project-components-expand.DUSWjY8t.png) Two components handle dialogue flow, one handles the portrait, and one triggers gameplay. ## Build the Fighter Dialogue board Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Build the Fighter Dialogue board In your **Dialogues** board folder, create a new board named **Fighter Dialogue**. This name must match the name Unity will use to locate the fighter dialogue tree. ### Dialogue starting element Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Build the Fighter Dialogue board > Dialogue starting element Let's now create the starting element of the fighter dialogue. Create a new element inside the **Fighter Dialogue** board and attach the `Fighter` and `dialogue_start` components to it, in that order. > ⚠️ Attach the `Fighter` component first. The dialogue UI shows the cover image of the element's first attached component as the portrait, so a marker component such as `dialogue_start` must come after the character component. ![Arcweave project environment. An orange rectangle emphasizes the starting element of the fighter dialogue, which includes text content and Arcscript.](https://docs.arcweave.com/assets/unity-aw-project-fighter-hub-element.CNyK36TT.png) This element's content will use conditional text to show different dialogue depending on the player's state. Type in the following content and [Arcscript](https://docs.arcweave.com/project-items/arcscript#add-arcscript): ```arcweave-html if sword_locked I see your blade is untested. Allow me to teach you its secrets and refine your skill. It will cost you 50 Gold. else Ah, a seasoned fighter! How many tales does your blade whisper from its edge? endif ``` Arcweave evaluates `sword_locked` and displays only the matching text. ### Player options Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Build the Fighter Dialogue board > Player options The dialogue's starting element has the following two output [connections](https://docs.arcweave.com/project-items/connections): #### 1. Evaluating gold Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Build the Fighter Dialogue board > Player options > 1. Evaluating gold The first connection leads to a [branch](https://docs.arcweave.com/project-items/branches) that evaluates the player's gold and fighting skills: - **If** the player has not been trained yet and also has the gold to pay for their training (i.e. `if gold >= 50 and sword_locked`), they then can choose to pay and unlock their fighting skills. This path leads to the training element (see further below). - **Else if** the player has not been trained yet, but cannot afford it (i.e. `elseif gold < 50 and sword_locked`), the Fighter tells them to come back with more gold. - **Else** (if the player has been already trained), they can boast about their fighting achievements. ![Arcweave's project environment highlighting the described branch and its conditions.](https://docs.arcweave.com/assets/unity-aw-project-fighter-hub-branch.BFzIa6fA.png) #### 2. Escape clause Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Build the Fighter Dialogue board > Player options > 2. Escape clause The second player option is an unconditional "goodbye" route, which leads to an element with the `dialogue_end` component attached. > ✅ Including unconditional output connections safeguards your dialogue from running out of player options in cases where required conditions are not met. ### Training element Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Build the Fighter Dialogue board > Training element The first output of our [evaluating branch](https://docs.arcweave.com/tutorials/unity/pt-5#_1-evaluating-gold) leads to this element, where training takes place. #### Variables Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Build the Fighter Dialogue board > Training element > Variables Type the following Arcscript in the element's content: ```arcscript gold -= 50 sword_locked = false ``` 50 gold coins are deducted and `sword_locked` flips to `false`. From this point on, the [dialogue's starting element](https://docs.arcweave.com/tutorials/unity/pt-5#dialogue-starting-element) shows the "seasoned fighter" text instead of the training offer. `sword_locked` is the narrative variable: it shapes the dialogue text and determines which branch path the player can take. To notify Unity to unlock the attack animation, attach the `attack` component to the training element. See right below. #### Components Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Build the Fighter Dialogue board > Training element > Components Attach the following components to the training element: `Drake Miles`, `attack`, and `dialogue_end`. ![Arcweave project environment. An orange rectangle emphasizes the components that have been attached to an element. One of them is the Attack component.](https://docs.arcweave.com/assets/unity-aw-project-attach-attack.DFULsg7m.png) This is why: - `Drake Miles`: Since the player is the speaker, we attach the `Drake Miles` component. - `attack`: To trigger Unity to unlock the fighting player skill (and its animation), attach the `attack` component to the training element; this is the event Unity will listen for. - `dialogue_end`: Although the flow continues in the Arcweave project (the training element has an output connection leading to a jumper), we want the dialogue to end here in our Unity game. ## Export from Arcweave Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Export from Arcweave 1. Go to **Export**. 2. Select the **Engine** tab. 3. Select **Export for Unity**. 4. Check **Include assets**. 5. Press **Export** and save the compressed `.zip` file to your drive. 6. Extract the `.zip` file and notice the `project.json` file it includes. You'll use it in the next step, below. ![Arcweave Export dialog with Engine tab selected, Unity option selected, and "Include assets" also selected.](https://docs.arcweave.com/assets/unity-export.D0gb58KH.png) ## Import into Unity Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Import into Unity ### Import new JSON Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Import into Unity > Import new JSON 1. In the Unity editor, import the new `.json` file by dragging it from the file explorer into the project folder **Assets > Arcweave**. ![Unity environment. An orange arrow shows how the user should drag the json file from the OS file explorer into the Unity editor folder system.](https://docs.arcweave.com/assets/unity-import-json.DUrwGZhN.png) 2. Select the `ArcweaveProjectAsset` and notice its field **Project JSON File** in the Inspector. Drag the new `.json` file from **Assets > Arcweave** into that field. ![Unity environment. An orange arrow shows how the user should drag the json file into the Arcweave Project Asset's relevant Inspector field.](https://docs.arcweave.com/assets/unity-assign-json.B59sv2h1.png) 3. Click **Import Project FromJson**. ![Unity environment. An orange rectangle singles out the button saying "Import Project FromJson", in the Inspector of the Arcweave Project Asset.](https://docs.arcweave.com/assets/unity-click-import-project-from-json.B31qvG-p.png) 4. Once you've imported the project from the `.json` file, you will notice the new variables appearing in the Inspector. Confirm that both `gold: 50` and `sword_locked: true` are present. ![Unity environment. An orange rectangle shows the project's variables, in the Arcweave Project Asset's Inspector.](https://docs.arcweave.com/assets/unity-sword-training-variables.CDF1_B3u.png) ### Import fighter asset Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Import into Unity > Import fighter asset For the fighter portrait to appear during dialogue, we need to import the new fighter image asset: in Unity's **Project** panel, open **Assets > Resources** and drag `fighter.png` into it. ![Unity environment. An orange arrow shows how the user should drag the fighter image from the OS file explorer into the Assets > Resources folder of the Unity editor.](https://docs.arcweave.com/assets/unity-import-asset.BjUOKFPh.png) When the dialogue reaches an element whose first attached component is `Fighter`, **@ArcweavePlayerUI** loads that component's cover image from a `Resources` folder by filename (without the extension). The only rule: the filename in **Assets > Resources** must match the asset name in the Arcweave project. ## Configure dialogue components Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Configure dialogue components Select `GameManager` in the Hierarchy and open the Inspector. Find the **Dialogue Tags** section. ![Unity environment. An orange rectangle shows the Dialogue Tags fields in the Inspector of the Game Manager game object.](https://docs.arcweave.com/assets/unity-dialogue-tags.CBrILB3k.png) The first two fields (`dialogue_end` and `dialogue_start`) are text-based defaults used by the existing **Healer Dialogue** and **Wanda Dialogue** boards. Fill in the last two empty fields: - **Dialogue Start Component Name**: `dialogue_start` - **Dialogue End Component Name**: `dialogue_end` When the game evaluates an element, it checks for a component named `dialogue_start` first. If it doesn't find one, it falls back to the text attribute check, so existing boards keep working without any changes. ## Fighter GameObject Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Fighter GameObject ### Add fighter 3D model Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Fighter GameObject > Add fighter 3D model 1. In the Project panel, navigate to the folder **Assets > KayKit_Adventurers_1.0_FREE > Characters > fbx**. 2. Drag the **Barbarian** 3D model into the scene and position it as needed. ![Unity environment. An orange arrow shows how the user should drag the Barbarian 3D model from the Unity editor folder system into the scene.](https://docs.arcweave.com/assets/unity-drag-fighter-model.BN6h_Xz-.png) 3. In the scene Hierarchy, rename the GameObject from "Barbarian" to "**Fighter**." ### Add Dialogue Trigger component Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Fighter GameObject > Add Dialogue Trigger component We must now add the **Dialogue Trigger** component to the Fighter GameObject. This way, the player can trigger the dialogue when approaching the fighter. 1. In the Project panel, navigate to **Assets > Scripts > Game** and locate the **ArcweaveDialogueTrigger** script. 2. Drag the **ArcweaveDialogueTrigger** script into the Inspector of the **Fighter** GameObject. The [Dialogue Trigger](https://docs.arcweave.com/tutorials/unity/pt-4#dialoguetrigger) component will be added. ![Unity environment. An orange arrow shows how the user should drag the Arcweave Dialogue Trigger script into the inspector of the Fighter game object.](https://docs.arcweave.com/assets/unity-dialogue-trigger.B0gtPCXu.png) 3. Configure the following fields of the **Dialogue Trigger** component: **Specific Board Name**: Type `Fighter Dialogue`. This must match the board name in the Arcweave project exactly. ![Unity environment. An orange rectangle shows the field called Specific Board Name.](https://docs.arcweave.com/assets/unity-dialogue-trigger-board-name.4Iwfu4Vd.png) **Arcweave Player**: Drag the **ArcweavePlayer** GameObject from the Hierarchy and drop it into this field. ![Unity environment. An orange arrow shows how the user should drag the Arcweave Player game object from the Hierarchy and into the Arcweave Player field of the Fighter game object's Inspector.](https://docs.arcweave.com/assets/unity-fighter-arcweave-player.BYRV6Plz.png) **Interaction Text**: 1. Open the **Assets > Prefabs** folder in the **Project** panel. 2. Drag the **InteractionText** prefab from the **Prefabs** folder and drop it onto the **Fighter** GameObject in the Hierarchy. ![Unity environment. An orange arrow shows how the user should drag the InteractionText prefab to the Fighter game object in the Hierarchy.](https://docs.arcweave.com/assets/unity-fighter-interaction-text.CtT21my5.png) 3. Then, drag the **InteractionText** child from the Hierarchy into the **Interaction Text** field, under **UI Settings** of the Fighter Inspector to assign it. ![Unity environment. An orange arrow shows how the user should drag the Interaction Text child of the Fighter game object from the Hierarchy into the relevant field of the Inspector.](https://docs.arcweave.com/assets/unity-fighter-interaction-text-2.Cnl3O6D7.png) When the player walks into range and presses E, Unity looks for the board named `Fighter Dialogue`, finds the element with the `dialogue_start` component, and begins the conversation. ## Enable the attack animation Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Enable the attack animation ### Add SwordSwingHandler Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Enable the attack animation > Add SwordSwingHandler 1. Go to Unity's Project panel and open the **Assets > Scripts > Handlers** folder. 2. Select the **Player** GameObject in the Hierarchy. 3. Drag the **SwordSwingHandler** script from the Handlers folder into the Player Inspector. ![Unity environment: an orange arrow shows the dragging gesture from the Project panel into the Player GameObject Inspector.](https://docs.arcweave.com/assets/unity-fighter-add-swordswing.Dv6NReaJ.png) This adds the Sword Swing Handler component to the Player. ![Unity environment: an orange rectangle emphasizes the Sword Swing Handler component in the Player GameObject Inspector.](https://docs.arcweave.com/assets/unity-fighter-swordswing-fields.8NQQdUdn.png) This script extends `ArcweaveElementComponentHandler`. It listens to every element the dialogue passes through, and when it finds one with the `attack` component attached, it calls `EnableSwordSwing()` on the player. Configure its three fields: - **Arcweave Player**: Drag the ArcweavePlayer GameObject from the Hierarchy and drop it into this field. ![Unity environment: an orange arrow shows how the user should drag the ArcweavePlayer GameObject from the Hierarchy and drop it into the Arcweave Player field of the Player GameObject Inspector.](https://docs.arcweave.com/assets/unity-swordswing-arcweaveplayer.CRVRSRgf.png) - **Component Name**: Type `attack`. This must match the Arcweave component name exactly (case-sensitive). ![Unity environment: an orange rectangle emphasizes the field Component Name in the Inspector of the Player GameObject.](https://docs.arcweave.com/assets/unity-swordswing-componentname.BAZx4i8W.png) - **Player Controller**: Drag the `Player` GameObject from the Hierarchy and drop it into this field. ![Unity environment: an orange arrow shows how the user should drag the Player GameObject from the Hierarchy into the Player Controller field of the Sword Swing Handler component.](https://docs.arcweave.com/assets/unity-swordswing-playercontroller.GPJJHbbx.png) ### Set up the Animator Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Enable the attack animation > Set up the Animator 1. Select the **Player** GameObject in the Hierarchy 2. Locate the **Animator** component in the Inspector 3. Double-click the **Controller** asset to open the animator graph in the Animator window. ![Unity environment: an orange rectangle emphasizes the Player GameObject in the Hierarchy, while another one shows the Animator component in the Inspector. A smaller rectangle within it shows the Controller field, which is occupied by the Character Animator object.](https://docs.arcweave.com/assets/unity-player-animator.DCXjBYks.png) Right-click on an empty area of the graph and select **Create State > Empty**. ![Unity environment, the Animator tab: an orange arrow shows the context menu appearing when the user right-clicks. An orange rectangle shows Create State and Empty.](https://docs.arcweave.com/assets/unity-player-animator-createstate.DBOiDqEx.png) Rename the state `Attack`. ![Unity environment, the Animator tab: an orange rectangle shows the new state node, while an orange arrow shows the state being renamed to Attack.](https://docs.arcweave.com/assets/unity-player-animator-rename.CDzf5HGL.png) With the state selected, click the object picker button (on the right side of the **Motion** field), to browse the available animation clips. ![Unity environment, the Animator tab: an orange rectangle shows the new state node, while an orange arrow points at the object picker button.](https://docs.arcweave.com/assets/unity-player-animator-motion.ChZiwvrw.png) Select the attack animation clip named **1H_Melee_Attack_Slice_Diagonal** and assign it to the **Motion** field in the Inspector. ![Unity environment, the Animator tab: a browser allows selection of the available animation clips. Orange rectangles show the selected Melee Attack Slice Diagonal clip.](https://docs.arcweave.com/assets/unity-player-animator-clip.CUDuRCJc.png) Now add the transitions: 1. Right-click **Any State** and drag a transition to the **Attack** state. 2. Right-click the **Attack** state and drag a transition to **Exit**. The final animation graph should look like the one in the image below: ![Unity environment, the Animator tab: an orange rectangle emphasizes the whole animation graph.](https://docs.arcweave.com/assets/unity-player-animator-states.aj3mEUA5.png) In the Parameters panel, click **+**, add a **Trigger**, and name it `Attack`. ![Unity environment, the Animator tab: an orange arrow points at the + button. An orange rectangle emphasizes the Trigger selection of the context menu.](https://docs.arcweave.com/assets/unity-player-animator-trigger.Ba8zbAd_.png) Select the **Any State → Attack** transition. In the Inspector, uncheck **Has Exit Time** so the animation fires immediately on input rather than waiting for the current clip to finish. ![Unity environment, the Animator tab: an orange arrow points at the transition between Any State and Attack, while an orange rectangle shows the "Has Exit Time" unchecked.](https://docs.arcweave.com/assets/unity-player-animator-hasexittime.ByEEx3N_.png) To the same transition, add a condition: `Attack`. ![Unity environment, the Animator tab: an orange arrow points at the transition between Any State and Attack, while an orange rectangle shows the Conditions field set to Attack.](https://docs.arcweave.com/assets/unity-player-animator-condition.DS5lnUOs.png) > ✅ The **Attack → Exit** transition can keep **Has Exit Time** checked; this lets the animation finish naturally before returning to idle. > ✅ If you're using the template Player from this project, the Animator is already configured. Finally, set the animation parameters in Player: 1. Select the **Player** GameObject in the Hierarchy. 2. In the **Player Controller** component, locate the **Animation Parameters**. 3. Type `Attack` in both fields of **Attack Animator Param** and **Attack State Name**. ![Unity environment: an orange arrow points at the Player GameObject in the Hierarchy. An orange rectangle shows the two fields of Attack Animator Param and Attack State Name in the Player Controller Inspector.](https://docs.arcweave.com/assets/unity-player-animator-parameters.CGfcWATL.png) These tell the script the name of the trigger that activates the attack and the name of the attack animation. ### The full chain Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Enable the attack animation > The full chain When the player chooses to train: 1. The Arcweave project's Arcscript runs in the training element (`gold -= 50`, `sword_locked = false`). 2. `ArcweavePlayer` fires `onElementEnter` for the training element, which has the `attack` component attached. 3. `SwordSwingHandler` detects the `attack` component and calls `EnableSwordSwing()` on the `PlayerController`. 4. From that point on, left-clicking triggers the attack animation. ## Test in Play mode Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Test in Play mode Enter Play mode. Walk to the Fighter and press E. ![Unity environment, during playtesting. The player is in dialogue with the fighter NPC, during the fighter's "I see your blade is untested..." line.](https://docs.arcweave.com/assets/unity-fighter-test.Cy_dhAeG.png) - The starting element shows the training offer because `sword_locked` is `true`. - The branch evaluates `gold >= 50 and sword_locked` as true, so the training path is available. - After choosing it, `SwordSwingHandler` detects the `attack` component and calls `EnableSwordSwing()`. You can see `canSwing` flip to `true` on the PlayerController in the Inspector. - Close the dialogue and left-click: the attack animation plays. - Return to the Fighter: `sword_locked` is now `false`, so the starting element shows the "seasoned fighter" line and the training path is no longer available. ## Build the project Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Build the project Go to **File → Build Profiles** (**File → Build Settings** in Unity versions before Unity 6), confirm the scene is in the scene list and the platform is selected, then click **Build**. After the build completes, open the output folder. Alongside the executable and data folder, you'll find an `arcweave/` folder with an `arcweave/resources/` subfolder inside. This is created automatically by `ArcweaveBuildProcessor.cs` after every build. It also copies `project.json` from `Assets/Arcweave/` if one is present. That `arcweave/` folder is what makes it possible to update narrative without rebuilding. ## Update dialogue after shipping Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Update dialogue after shipping ### From a local JSON file Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Update dialogue after shipping > From a local JSON file Edit the Fighter dialogue in Arcweave, export it for Unity again, and copy the new `project.json` into the `arcweave/` folder next to the executable. The next time the game launches, `RuntimeArcweaveImporter` loads it automatically, with no Unity rebuild required. If the game is already running, press Escape to open the import panel and click **Import from local JSON** to reload immediately. ### From the REST API Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Update dialogue after shipping > From the REST API In the import panel, fill in: - **API**: an API key with **Read projects** enabled from your workspace's [API section](https://docs.arcweave.com/workspaces/api). The REST API is available to Team workspaces only. - **Project Hash**: from [Project settings](https://docs.arcweave.com/project-tools/settings#project-hash). Click **Web Import**. The game pulls the latest version directly from Arcweave. The designer saves in Arcweave; you test in the running build. ## Summary Context: Arcweave docs > Tutorials > Unity > Unity tutorial | Part 5: Customize the template > Summary For any new NPC and mechanic in this template, the workflow is: 1. **In Arcweave**: add variables; create components (`dialogue_start`, `dialogue_end`, character portrait, gameplay components like `attack`); build the board with conditional text and branches; attach components to elements to signal Unity at the right narrative moment; export. 2. **In Unity, import**: update the `ArcweaveProjectAsset`. 3. **In Unity, GameManager**: fill in `Dialogue Start Component Name` and `Dialogue End Component Name`. 4. **In Unity, NPC**: add the character, rename it, add `ArcweaveDialogueTrigger` with the correct board name. 5. **In Unity, portrait**: place the image in `Assets/Resources/` with the same filename as in Arcweave. 6. **In Unity, gameplay**: add the appropriate handler script (an `ArcweaveElementComponentHandler` subclass) to the relevant GameObject, set the component name to watch, and wire up the target. 7. **Build**: the `arcweave/` folder is created automatically. Drop in a new `project.json` or use the import panel to update without rebuilding. The Arcweave project is where the narrative lives; Unity is where it runs. Variables shape the story, components trigger the gameplay, and the two sides stay connected even after shipping. # Unreal Engine integration tutorial Source: https://docs.arcweave.com/tutorials/unreal/overview Section: Tutorials Description: A tutorial introducing you to Arcweave's plugin for Unreal Engine This tutorial introduces the Arcweave [plugin for Unreal Engine](https://docs.arcweave.com/integrations/unreal). By the end of this short collection of videos, you'll know how to: 1. [Install the plugin](https://docs.arcweave.com/tutorials/unreal/overview#_1-install) 2. [Understand the plugin's core classes and functions](https://docs.arcweave.com/tutorials/unreal/overview#_2-classes-functions) 3. [Connect your Arcweave project](https://docs.arcweave.com/tutorials/unreal/overview#_3-connect-your-project) 4. [Fetch your story data into the Unreal Editor and the game build](https://docs.arcweave.com/tutorials/unreal/overview#_4-fetch-your-story-data) 5. [Put everything together in an example game](https://docs.arcweave.com/tutorials/unreal/overview#_5-example-game) > ✅ The example game described in this tutorial uses Arcweave's [Game Engine Example](https://docs.arcweave.com/workspaces/projects#project-templates) project template. > ℹ️ For written installation steps and the plugin's classes and functions, see [Unreal Engine integration](https://docs.arcweave.com/integrations/unreal#plugin-installation). ## 1. Install Context: Arcweave docs > Tutorials > Unreal Engine integration tutorial > 1. Install Video: https://www.youtube.com/watch?v=Ws_Cz-IQQYg ## 2. Classes & functions Context: Arcweave docs > Tutorials > Unreal Engine integration tutorial > 2. Classes & functions Video: https://www.youtube.com/watch?v=6Q7aEAFtAVU ## 3. Connect your project Context: Arcweave docs > Tutorials > Unreal Engine integration tutorial > 3. Connect your project Video: https://www.youtube.com/watch?v=HmBD-aIcW6E ## 4. Fetch your story data Context: Arcweave docs > Tutorials > Unreal Engine integration tutorial > 4. Fetch your story data Video: https://www.youtube.com/watch?v=IsLsv1q88Bw ## 5. Example game Context: Arcweave docs > Tutorials > Unreal Engine integration tutorial > 5. Example game Video: https://www.youtube.com/watch?v=RdaCcYEMG58 # Godot Engine integration tutorial Source: https://docs.arcweave.com/tutorials/godot/overview Section: Tutorials Description: A tutorial introducing you to Arcweave's plugin for Godot Engine This tutorial introduces the Arcweave [plugin for Godot Engine](https://docs.arcweave.com/integrations/godot). By the end of this short video series, you'll know how to: 1. [Install and activate the plugin](https://docs.arcweave.com/tutorials/godot/overview#_1-install-activate) 2. [Use it in a simple Play Mode Godot game](https://docs.arcweave.com/tutorials/godot/overview#_2-play-mode-in-godot) 3. [Connect and navigate the example game](https://docs.arcweave.com/tutorials/godot/overview#_3-example-game-playthrough) 4. [Navigate the project's scenes and scripts](https://docs.arcweave.com/tutorials/godot/overview#_4-scenes-scripts) 5. [Fetch your story data into Godot, both in the editor and in a game build](https://docs.arcweave.com/tutorials/godot/overview#_5-test-in-runtime) > ✅ The example game described in this tutorial uses Arcweave's [Game Engine Example](https://docs.arcweave.com/workspaces/projects#project-templates) project template. > ℹ️ The plugin requires the **.NET** version of Godot Engine. For written installation steps and the plugin's API, see [Godot Engine integration](https://docs.arcweave.com/integrations/godot#requirements). ## 1. Install & activate Context: Arcweave docs > Tutorials > Godot Engine integration tutorial > 1. Install & activate Video: https://www.youtube.com/watch?v=SGrg3DAHiRA ## 2. Play Mode in Godot Context: Arcweave docs > Tutorials > Godot Engine integration tutorial > 2. Play Mode in Godot Video: https://www.youtube.com/watch?v=6WDjRaOtdd0 ## 3. Example game playthrough Context: Arcweave docs > Tutorials > Godot Engine integration tutorial > 3. Example game playthrough Video: https://www.youtube.com/watch?v=RASdYz7qyVo ## 4. Scenes & scripts Context: Arcweave docs > Tutorials > Godot Engine integration tutorial > 4. Scenes & scripts Video: https://www.youtube.com/watch?v=ZWhQz-SVncQ ## 5. Test in runtime Context: Arcweave docs > Tutorials > Godot Engine integration tutorial > 5. Test in runtime Video: https://www.youtube.com/watch?v=ZeBuHkxrNYU # AI tools tutorial Source: https://docs.arcweave.com/tutorials/ai-tools/overview Section: Tutorials Description: Video tutorial on Arcweave's Element Generator, Element Enhancer, Image Generator, and Design Assistant This short video tutorial series introduces Arcweave's AI tools: - [Element Generator & Element Enhancer](https://docs.arcweave.com/tutorials/ai-tools/element-generator-enhancer) - [Image Generator](https://docs.arcweave.com/tutorials/ai-tools/image-generator) - [Design Assistant](https://docs.arcweave.com/tutorials/ai-tools/design-assistant) For written instructions on each tool, see the [AI tools](https://docs.arcweave.com/project-tools/ai-features/overview) section. # Element Generator / Enhancer Source: https://docs.arcweave.com/tutorials/ai-tools/element-generator-enhancer Section: Tutorials > AI tools Description: Video tutorial on Arcweave's Element Generator, which creates new elements, and Element Enhancer, which refines existing ones This video tutorial shows Arcweave's [Element Generator](https://docs.arcweave.com/project-tools/ai-features/element-generator), which creates new elements from a prompt, and [Element Enhancer](https://docs.arcweave.com/project-tools/ai-features/element-enhancer), which refines existing elements. For the written reference, see those pages. Video: https://www.youtube.com/watch?v=x86KqQZuKJI # Image Generator Source: https://docs.arcweave.com/tutorials/ai-tools/image-generator Section: Tutorials > AI tools Description: Video tutorial on Arcweave's Image Generator, which creates image assets for your project with generative AI This video tutorial shows Arcweave's [Image Generator](https://docs.arcweave.com/project-tools/ai-features/image-generator), which creates image assets for your project with generative AI. For written instructions, see that page. Video: https://www.youtube.com/watch?v=mBlagOinKCU # Design Assistant Source: https://docs.arcweave.com/tutorials/ai-tools/design-assistant Section: Tutorials > AI tools Description: Video tutorial on Arcweave's Design Assistant, the AI assistant that explores, brainstorms, and edits your project This video tutorial shows Arcweave's [Design Assistant](https://docs.arcweave.com/project-tools/ai-features/design-assistant), the AI assistant that helps you explore, brainstorm, and edit your project. For written instructions, including how to access it, make edits, and track AI credits, see that page. Video: https://www.youtube.com/watch?v=N9CS0Ihs1F8 # Project items Source: https://docs.arcweave.com/project-items/overview Section: Project Items Description: Guide to all items used in your Arcweave project and how they relate to each other In Arcweave, a [project](https://docs.arcweave.com/workspaces/projects) holds the structure and content of your interactive story, allowing you to design, test, share, and export it. > ℹ️ New to Arcweave? [Core concepts](https://docs.arcweave.com/introduction/core-concepts) introduces these items in plain terms before you dive into the reference pages. This section covers all the Arcweave items you can use to build your story. You will learn everything there is to know about the following: - [Boards](https://docs.arcweave.com/project-items/boards) are the canvases where you design your story flowcharts. - Use [elements](https://docs.arcweave.com/project-items/elements) and [connections](https://docs.arcweave.com/project-items/connections) to map out story events and write scenes or dialogue trees. To connect distant elements, create [jumpers](https://docs.arcweave.com/project-items/jumpers)—shortcuts that continue the story at an element elsewhere, on the same board or another one. These items define how your story flows. - Represent story objects with [components](https://docs.arcweave.com/project-items/components), storing data in the form of [attributes](https://docs.arcweave.com/project-items/attributes). - Add logic using [variables](https://docs.arcweave.com/project-items/variables/overview), [Arcscript](https://docs.arcweave.com/project-items/arcscript), and [branches](https://docs.arcweave.com/project-items/branches). - Add image and sound [assets](https://docs.arcweave.com/project-items/assets/overview) to enrich your story with visuals and audio. - Use [notes](https://docs.arcweave.com/project-items/notes) and [comments](https://docs.arcweave.com/project-items/comments) to communicate with collaborators—or your future self. To send someone directly to a board, element, jumper, note, branch, connection, or component, use its **Copy link** action. See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position). ## How project items relate Context: Arcweave docs > Project Items > How project items relate A project's story flow lives on its boards. Components, assets, and global variables belong to the whole project and can be used from any board. | Item | Where it lives | What it holds | How it relates to other items | | --------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Board](https://docs.arcweave.com/project-items/boards) | The project's **Boards** section, optionally in board folders. | Elements, connections, branches, jumpers, notes, and comments; board attributes. | Its variable-type attributes are [board variables](https://docs.arcweave.com/project-items/variables/board); boards can be [mentioned](https://docs.arcweave.com/project-tools/mentions) in text. | | [Element](https://docs.arcweave.com/project-items/elements) | A board. | A title and rich text content with optional Arcscript segments; a cover, audio, attached components, and attributes. | Sends and receives connections; can be the target of jumpers. | | [Connection](https://docs.arcweave.com/project-items/connections) | A board. | An optional [label](https://docs.arcweave.com/project-items/labels) with text and Arcscript, shown as option text in Play Mode. | Goes from an element or branch to an element, branch, or jumper on the same board. | | [Branch](https://docs.arcweave.com/project-items/branches) | A board. | `if` and `elseif` conditions written in Arcscript, and an optional `else`. | Receives connections; has at most one output connection per condition. | | [Jumper](https://docs.arcweave.com/project-items/jumpers) | A board. | A link to a target element. | Receives connections and continues the flow at its target element, which can be on another board; has no output connections. | | [Note](https://docs.arcweave.com/project-items/notes) | A board. | Rich text annotations. | Not part of the flow; has no connections, components, or Arcscript. | | [Component](https://docs.arcweave.com/project-items/components) | The project's **Components** section. | A name, custom ID, cover, and attributes. | Attached to elements, mentioned in text, and listed in Component List attributes; its variable-type attributes are [component variables](https://docs.arcweave.com/project-items/variables/component). | | [Attribute](https://docs.arcweave.com/project-items/attributes) | A board, component, or element. | A label and a value of a given type. | Component List and Asset List attributes reference components and assets; Boolean, Integer, Float, and String Field attributes of boards and components act as variables. | | [Variable](https://docs.arcweave.com/project-items/variables/overview) | Global (project), board, or component scope. | A value that can change during play. | Read and changed by Arcscript in element content and labels; read by branch conditions. | | [Asset](https://docs.arcweave.com/project-items/assets/overview) | The project's **Assets** section. | Image, audio, and video files. | Used as element and component covers, element audio and video, and in Asset List attributes. | In [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview), the story starts at the starting element and follows connections from element to element. Connection labels become the options the player chooses, branches send the flow down the connection of the first condition that is true, and jumpers continue the flow at their target element. Along the way, [Arcscript](https://docs.arcweave.com/project-items/arcscript) in element content and labels reads and changes variables, and branch conditions read them to choose a path. # Boards Source: https://docs.arcweave.com/project-items/boards Section: Project Items Description: Create, organize, and manage boards and board folders, the canvases that hold your story flowcharts, plus performance and usage tips In Arcweave, your story's flow takes place on one or more **boards**—the canvases where you build your story flowcharts. A board is where you visually map out scenes, dialogue, choices, and logic. ![An open Arcweave project showing the current board and its flowchart.](https://docs.arcweave.com/assets/project-general.Cw-i8z_y.png) ## Usage examples Context: Arcweave docs > Project Items > Boards > Usage examples There are no restrictions on how you use a board. It can visually represent a story chapter, a dialogue scene, a game level, or even an algorithm. Some examples include: - **Story parts**: Chapters, scenes, or levels—you decide what they are. Keep each one on its own board. - **Synopses**: Outline your entire narrative in a single board before zooming into individual scenes on separate boards. - **Subplots**: Keep main and secondary plots distinct by mapping each one on a different board. - **Dialogue**: Create a separate board for each NPC dialogue tree, and group them in a folder named "Dialogue Trees." - **Locations**: Build geography-based diagrams to give an overview of your game's terrain or specific areas. - **Puzzle dependencies**: Design puzzle logic and dependencies to avoid issues—like locking a drawer while the key's still inside! - **Storyboards**: Use [assets](https://docs.arcweave.com/project-items/assets/overview) as [element covers](https://docs.arcweave.com/project-items/elements#element-covers) to visually narrate your story. ## Usage tips Context: Arcweave docs > Project Items > Boards > Usage tips When working on your flowcharts, keep the following in mind: - Use multiple boards to keep your project modular, clear, and easy to navigate. - Use [jumpers](https://docs.arcweave.com/project-items/jumpers) to connect flowcharts across boards. - Group related boards into board folders for better organization. ## Board folders Context: Arcweave docs > Project Items > Boards > Board folders To organize your boards efficiently, Arcweave lets you create your own structure of board folders within your project. ## Boards section Context: Arcweave docs > Project Items > Boards > Boards section Once inside a project, you can view and manage your boards and folders in the **Boards** section, located in the lower half of Arcweave's left sidebar. ![The project environment with an orange rectangle emphasizing the position of the Boards section.](https://docs.arcweave.com/assets/boards-sidebar.ByQxC37P.png) Expand a board in this section to see an outline of its elements, connections, branches, jumpers, and notes. Click an item to zoom to it on the board. See [Board contents](https://docs.arcweave.com/project-tools/interface/left-sidebar#board-contents). ## Create boards or folders Context: Arcweave docs > Project Items > Boards > Create boards or folders ### At section top Context: Arcweave docs > Project Items > Boards > Create boards or folders > At section top To create a new board or folder at the top of the **Boards** section: - Go to the header of the **Boards** section. - Click **Create board** (**+** icon) or **Create folder** (**folder** icon). ### At section bottom Context: Arcweave docs > Project Items > Boards > Create boards or folders > At section bottom To create a new board or folder at the bottom of the **Boards** section: - Right-click on an empty area of the **Boards** section. - Select **Create board** or **Create folder** from the menu. ### Above existing board Context: Arcweave docs > Project Items > Boards > Create boards or folders > Above existing board To create a new board or folder above an existing board in the **Boards** section: - Right-click on the existing board's name. - Select **Create board** or **Create folder** from the menu. Or: - Hover the mouse cursor over the existing board's name. - Click on the **(+)** icon that appears. - Select **Create board** or **Create folder** from the menu. ### Inside existing folder Context: Arcweave docs > Project Items > Boards > Create boards or folders > Inside existing folder To create a new board or folder inside an existing folder: - Right-click on the existing folder's name. - Select **Create board** or **Create folder** from the menu. Or: - Hover the mouse cursor over the folder's name. - Click on the **(+) icon** that appears. - Select **Create board** or **Create folder** from the menu. ## Delete boards / folders Context: Arcweave docs > Project Items > Boards > Delete boards / folders To delete a board or folder: - Right-click on its name, on the **Boards** section. - Select **Delete**. > ⚠️ Deleting a board folder will also delete all its contents. You can undo the action. > ℹ️ A project must keep at least one board. **Delete** is unavailable for the project's last remaining board, or for a folder that contains it. > ℹ️ When deleting a board, all [mentions](https://docs.arcweave.com/project-tools/mentions) of this board will be removed as well. ## Rename boards / folders Context: Arcweave docs > Project Items > Boards > Rename boards / folders To rename a board or folder: - Right-click on its name, on the **Boards** section. - Select **Rename** from the menu. You can also rename the currently open board from the [top menu](https://docs.arcweave.com/project-tools/interface/top-menu). You will find the current board's name next to the project name, on the left of the menu. Click it once to rename it. ## Duplicate boards Context: Arcweave docs > Project Items > Boards > Duplicate boards To duplicate a board: - Right-click on its name, on the **Boards** section. - Select **Duplicate**. > ℹ️ Duplicating board folders is not allowed. ## Open boards Context: Arcweave docs > Project Items > Boards > Open boards To open a board, go to your **Boards** section on the sidebar and click on its name. Your current board area will switch to display its contents. ## Copy a board link Context: Arcweave docs > Project Items > Boards > Copy a board link Right-click the board's name in the sidebar's **Boards** section and select **Copy link**. Opening the link switches to that board and restores its saved position and zoom. Board folders do not have this action. The link includes the current project language. See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position) for access requirements and how to share a particular board view. ## Board performance Context: Arcweave docs > Project Items > Boards > Board performance If board navigation, selection, or connection editing feels slower than expected, see [Troubleshooting](https://docs.arcweave.com/project-tools/troubleshooting#board-performance). Board performance can also vary depending on the selected board renderer in [Project Settings](https://docs.arcweave.com/project-tools/settings#board-renderer). ## Mention boards Context: Arcweave docs > Project Items > Boards > Mention boards You can create links to your boards while editing rich text in elements, notes, attributes, and labels. This kind of link is called a **mention** and you initiate it by typing the character `@` followed by a board name. Read more on [mentions](https://docs.arcweave.com/project-tools/mentions) under the section of **Project tools**. > ℹ️ You can also mention [components](https://docs.arcweave.com/project-items/components#mention-components). ## Board properties Context: Arcweave docs > Project Items > Boards > Board properties To access the properties of any board: 1. Locate the board in the **Boards** section of the left sidebar 2. Right-click the board's name and select **Properties** from the menu. To access the properties of the current board: 1. Right-click in an empty board area. 2. Select **Board Properties**. The properties that you can access are the following: ### Board ID Context: Arcweave docs > Project Items > Boards > Board properties > Board ID Each board has a **unique identifier** in the form of: `81a30674-aa09-4eb8-8484-59298d37f984` (version 4 UUID) > ℹ️ Uses of this board ID include accessing the board in the project's [JSON](https://docs.arcweave.com/integrations/json). ### Custom ID Context: Arcweave docs > Project Items > Boards > Board properties > Custom ID Besides its UUID, every regular board has an editable custom ID. Arcweave generates it when the board is created and uses it to scope the board's [attribute variables](https://docs.arcweave.com/project-items/variables/board). To edit a board custom ID: 1. Right-click the board in the **Boards** section and select **Attributes**. 2. Select the custom ID beneath the panel title and enter a new value. The custom ID cannot be removed, must be unique across all boards and components, and must follow the [variable naming rules](https://docs.arcweave.com/project-items/variables/overview#variable-names-and-custom-ids). Renaming it updates existing Arcscript references automatically. ### Attributes Context: Arcweave docs > Project Items > Boards > Board properties > Attributes Regular boards can store [attributes](https://docs.arcweave.com/project-items/attributes), including String Field, Boolean, Integer, and Float attributes that act as [board variables](https://docs.arcweave.com/project-items/variables/board). To open a board's attributes, right-click it in the **Boards** section and select **Attributes**. Boards with attributes also display an attributes button next to their name. Board folders cannot contain attributes. To [add](https://docs.arcweave.com/project-items/attributes#create-attributes), [edit](https://docs.arcweave.com/project-items/attributes#edit-attributes), or [remove](https://docs.arcweave.com/project-items/attributes#delete-attributes) a board's attributes, see the **Attributes** page. ### Content Context: Arcweave docs > Project Items > Boards > Board properties > Content This section displays the board's item count by type: - [Elements](https://docs.arcweave.com/project-items/elements) - [Connections](https://docs.arcweave.com/project-items/connections) - [Notes](https://docs.arcweave.com/project-items/notes) - [Jumpers](https://docs.arcweave.com/project-items/jumpers) - [Branches](https://docs.arcweave.com/project-items/branches) - [Comments](https://docs.arcweave.com/project-items/comments) ### Total words Context: Arcweave docs > Project Items > Boards > Board properties > Total words This section displays the **board's word count**, adding together words in element titles, element content, and connection labels in the currently selected language. Arcscript blocks and notes are not counted. For the title and content breakdown of an individual element, see [element word count](https://docs.arcweave.com/project-items/elements#word-count). ### Total characters Context: Arcweave docs > Project Items > Boards > Board properties > Total characters This section displays the **board's character count** for the same text: element titles, element content, and connection labels in the currently selected language. Arcscript blocks and notes are not counted. # Elements Source: https://docs.arcweave.com/project-items/elements Section: Project Items Description: Elements are the board items that hold your story text and build your flowcharts **Elements** are the main board items in Arcweave and the building blocks of your flowcharts. Each element holds a small fragment of your story in a **title** and a rich text **content** area. It can also carry a cover image or video, attached components and audio, [Arcscript](https://docs.arcweave.com/project-items/arcscript) (Arcweave's scripting language), and [attributes](https://docs.arcweave.com/project-items/attributes) (labeled pieces of data). ![Arcweave's project environment with several orange rectangles emphasizing the open board's elements](https://docs.arcweave.com/assets/castle-elements.BNOtGi5V.png) By connecting elements together with [connections](https://docs.arcweave.com/project-items/connections), you create your story flow, allowing the player to make choices and progress through your game. > ✅ Play-test the flow of your elements and connections in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview). ## Create elements Context: Arcweave docs > Project Items > Elements > Create elements ### Create independent elements Context: Arcweave docs > Project Items > Elements > Create elements > Create independent elements To create an element, do any of the following: - Double-click on an empty area of the current board. - Drag and drop the **New element icon** (at the left of the [bottom menu](https://docs.arcweave.com/project-tools/interface/bottom-menu)) on an empty area of the current board. - Right-click on an empty area of the current board and select **Create > Element** from the menu. ![Arcweave's project environment. Animated GIF image demonstrating how to create an element with three possible ways: double-clicking an empty area of the board, dragging and dropping the "new element icon", and right-clicking and selecting "create element" from the context menu.](https://docs.arcweave.com/assets/element-create.CDTQmixS.gif) ### Create connected elements Context: Arcweave docs > Project Items > Elements > Create elements > Create connected elements To create a new element that is already connected, drag a connection from an element's edge or a branch's output and drop it on an empty area of the board. In the menu that opens, select **Create element here**. See [Create connections](https://docs.arcweave.com/project-items/connections#with-drag-and-drop). When an element is selected, you can use [keyboard shortcuts](https://docs.arcweave.com/project-tools/interface/keyboard-shortcuts#element-creation-connection) to instantly create and connect a new element in one action. Press **Ctrl + Alt/Option/Cmd + an arrow key**. A new element is created and automatically connected to the first one. > ✅ The new element is automatically selected. To edit it, press **Enter** and start typing. ## Select elements Context: Arcweave docs > Project Items > Elements > Select elements Click an element to select it. To select multiple items, see [Select board items](https://docs.arcweave.com/project-tools/interface/mouse-actions#select-board-items). ## Copy an element link Context: Arcweave docs > Project Items > Elements > Copy an element link Right-click an element on the board or in the sidebar's **Boards** section and select **Copy link**. On the board, select only that element to make the action available. Opening the link centers the element on its board in the language active when you copied it. See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position) for access requirements. ## Delete elements Context: Arcweave docs > Project Items > Elements > Delete elements To delete an element, you can do either of the following: - Select the element and press **Delete** or **Backspace**. - Right-click on it and select **Delete selection** from the menu. ## Edit elements Context: Arcweave docs > Project Items > Elements > Edit elements Each element has a **title** (the top, coloured part) and a **content** area (the main black part). To edit either, simply double-click on it. To cycle editing between title and content, press the **tab key**. Format the element's title and content using [rich text](https://docs.arcweave.com/project-tools/rich-text). To exit editing mode press **Esc** or click on an empty area of the board. > ✅ Project owners and editors can also edit element content in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#edit-content-in-play-mode) while playtesting, without returning to the board. ## Resize elements Context: Arcweave docs > Project Items > Elements > Resize elements To resize an element manually, select it and drag any of its corners or edges. To set it to **auto-resize**, so it continuously adjusts to fit its content, double-click any edge or corner handle. ![Arcweave's project environment. Animated GIF image demonstrating how to resize an element by dragging its bottom border.](https://docs.arcweave.com/assets/element-resize.-250_7kf.gif) ## Change element theme Context: Arcweave docs > Project Items > Elements > Change element theme To change the color theme of an element, right-click on it and select one of the available colors from the menu's color picker. ![Arcweave's project environment. The element context menu is open (revealed by right-clicking the element in the board). An orange rectangle emphasizes the section where the theme color picker is.](https://docs.arcweave.com/assets/element-change-theme.C35tM9G7.png) ## Element covers Context: Arcweave docs > Project Items > Elements > Element covers Elements can have a **cover**: an image, icon, or video that renders in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview), above the element's text content. ![A split screen view of an Arcweave project and its Play Mode. The focus in both sides is the starting element, with orange rectangles and an arrow emphasizing how the element's cover renders as featured image in Play Mode](https://docs.arcweave.com/assets/element-cover.Bk1ScTyU.png) As covers, you can use one of the following: - [Image assets](https://docs.arcweave.com/project-items/assets/images) - [Video assets](https://docs.arcweave.com/project-items/assets/video) - Icons from Arcweave's [built-in icon library](https://docs.arcweave.com/project-tools/icon-library) - [YouTube video embeds](https://docs.arcweave.com/project-items/elements#youtube-embeds-as-element-covers) ### Assets as element covers Context: Arcweave docs > Project Items > Elements > Element covers > Assets as element covers [Images](https://docs.arcweave.com/project-items/assets/images) and [video assets](https://docs.arcweave.com/project-items/assets/video) can be assigned as element covers. In Play Mode, both images and videos are rendered above the element's text content. > ℹ️ For configuring video asset playback behavior, see the page on [Video assets](https://docs.arcweave.com/project-items/assets/video#playback-behavior). #### Drag and drop assets to set as element covers Context: Arcweave docs > Project Items > Elements > Element covers > Assets as element covers > Drag and drop assets to set as element covers To easily assign an image or video asset, drag it from the [Assets section](https://docs.arcweave.com/project-items/assets/overview#assets-section) of your project and drop it into the element. ![Arcweave's project environment. Animated GIF image demonstrating how you can drag an asset from the Assets section into an element, to assign it as element cover.](https://docs.arcweave.com/assets/element-cover-drag.CdV_QxYB.gif) #### Use context menu to set element covers Context: Arcweave docs > Project Items > Elements > Element covers > Assets as element covers > Use context menu to set element covers You can also assign a cover to an element using the element's context menu. This opens your options to icons, YouTube embed, and image generation. To set a cover using the context menu: 1. Right-click on the element. 2. Select **Cover > Set cover** in the context menu. ![Screenshot of Arcweave's project environment. The element context menu is open, and an orange rectangle is emphasizing the "Set cover" option.](https://docs.arcweave.com/assets/element-set-cover-menu.CCl43IkV.png) 3. Select a tab: - **My Assets**: Select an [image](https://docs.arcweave.com/project-items/assets/images) or [video asset](https://docs.arcweave.com/project-items/assets/video). - **Icon Library**: Select an icon from Arcweave's built-in [icon library](https://docs.arcweave.com/project-tools/icon-library). - **Embed**: Embed a YouTube video. (See [below](https://docs.arcweave.com/project-items/elements#youtube-embeds-as-element-covers)) - **Generate**: Use Arcweave's [Image generator](https://docs.arcweave.com/project-tools/ai-features/image-generator) to generate a cover. ![The modal for setting an element cover, open at the My Assets tab, showing the project's available image assets.](https://docs.arcweave.com/assets/element-set-cover-modal.CbIq1-uM.png) 4. Choose an image or video asset, an icon, or paste a YouTube video URL, accordingly. > ℹ️ To use your own images in a project, you must upload them as [assets](https://docs.arcweave.com/project-items/assets/overview). ### YouTube embeds as element covers Context: Arcweave docs > Project Items > Elements > Element covers > YouTube embeds as element covers You can embed a YouTube video as an element cover. In Play Mode, embedded YouTube videos are rendered above the element's text content. To embed a YouTube video as an element cover, perform the following steps: 1. Right-click the element and select **Cover > Set cover** in the context menu. 2. Select the **Embed** tab. 3. Paste a YouTube video URL in the relevant field. 4. Configure video's playback behavior: - **Autoplay**: Video plays automatically when element loads. - **Show controls**: Player has access to video controls (play, pause, seek bar). 5. Click **Embed Video**. ![Arcweave's project environment. An element's "Set cover" modal is open, and an orange arrow is pointing at the "Embed" tab.](https://docs.arcweave.com/assets/element-set-cover-modal-embed.CD0VIuMp.png) ### Generate covers Context: Arcweave docs > Project Items > Elements > Element covers > Generate covers You can also use Arcweave's Image Generator to do either of the following: - [Generate element covers](https://docs.arcweave.com/project-tools/ai-features/image-generator#set-covers): Submit a prompt and image orientation preferences; Arcweave generates a relevant image and assigns it as the element cover. ![Arcweave's project environment. An element's "Set cover" modal is open, and an orange arrow is pointing at the "Generate" tab.](https://docs.arcweave.com/assets/element-set-cover-modal-generate.8bMrfeKi.png) - [Auto-generate element covers](https://docs.arcweave.com/project-tools/ai-features/image-generator#auto-generate-covers): Let Arcweave generate an element cover using the element title and content as context, without requiring a prompt. Right-click the element and select **AI > Auto-generate cover**. ![Screenshot of Arcweave's project environment. The element context menu is open, and an orange rectangle is emphasizing the "Auto-generate cover" option.](https://docs.arcweave.com/assets/element-set-cover-menu-autogenerate.D4c_9tEn.png) > ✅ For detailed instructions, see [Image Generator](https://docs.arcweave.com/project-tools/ai-features/image-generator). ### Change element covers Context: Arcweave docs > Project Items > Elements > Element covers > Change element covers To change an element's cover, simply set a new cover to the element in any of the ways described above. ### Remove element covers Context: Arcweave docs > Project Items > Elements > Element covers > Remove element covers To remove an element's cover, right-click on the element and select **Cover > Remove cover**. ## Audio attachments Context: Arcweave docs > Project Items > Elements > Audio attachments Elements can optionally have one or more attached audio assets. The audio assets play during [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview), upon the element's rendering, as loops or one-shots. ### Attach audio assets Context: Arcweave docs > Project Items > Elements > Audio attachments > Attach audio assets To attach an audio file to an element, take the following steps: 1. Upload the audio file to your project (see [Assets](https://docs.arcweave.com/project-items/assets/overview#upload-assets)). 2. Locate the asset in your project's **Assets** section. 3. Drag and drop the asset from your **Assets** section into the element. Once attached, click the asset on the element to open its **Audio reference** dialog, where you can set its behavior, delay, fades, volume, and auto-stop. See [Audio reference settings](https://docs.arcweave.com/project-items/assets/audio#audio-reference-settings). ### Move audio assets Context: Arcweave docs > Project Items > Elements > Audio attachments > Move audio assets To **move** audio assets between elements, drag them from one element and drop them into another. ### Remove audio assets Context: Arcweave docs > Project Items > Elements > Audio attachments > Remove audio assets To **remove** an attached audio asset, drag and drop it from the element to an empty area of the board. > ℹ️ Removing an audio asset from an element simply removes the reference and does not delete the asset. ## Attach components Context: Arcweave docs > Project Items > Elements > Attach components You can attach components to an element to visually reference them in the story flow, both in the boards and in Play Mode. See [components](https://docs.arcweave.com/project-items/components) for all information. To share an attached component, right-click its reference on the board and select **Copy link**. The link opens the component's dialog. See [Copy a component link](https://docs.arcweave.com/project-items/components#copy-a-component-link). ## Add Arcscript Context: Arcweave docs > Project Items > Elements > Add Arcscript You can add [Arcscript segments](https://docs.arcweave.com/project-items/arcscript#arcscript-segments)—single lines of code that run when the story reaches the element—to your element content, assigning values to variables or manipulating the text output. ![A label and an element with contents that include rich text and Arcscript code.](https://docs.arcweave.com/assets/element-label-richtext-arcscript.CBFrUdz9.png) To insert an Arcscript segment into an element's content, see [Add Arcscript](https://docs.arcweave.com/project-items/arcscript#add-arcscript) on the Arcscript page. ## Element properties Context: Arcweave docs > Project Items > Elements > Element properties To access an element's properties, right-click the element and select **Properties**. This opens the element's Properties panel, which has the following tabs: - **Attributes**: The element's [attributes](https://docs.arcweave.com/project-items/attributes), if any. - **Details**: Element ID, word count, and character count. ### Attributes Context: Arcweave docs > Project Items > Elements > Element properties > Attributes An element's **Attributes** tab contains the element's attributes, if any. An element can hold the following four types of attributes: - Rich Text Field - String Field - Component List - Asset List > ℹ️ These four types are also available to [boards](https://docs.arcweave.com/project-items/boards) and [components](https://docs.arcweave.com/project-items/components). Boards and components additionally support Boolean, Integer, and Float attributes; together with String Field, they act as [scoped variables](https://docs.arcweave.com/project-items/variables/overview#variable-scope). To [add](https://docs.arcweave.com/project-items/attributes#create-attributes), [edit](https://docs.arcweave.com/project-items/attributes#edit-attributes), or [remove](https://docs.arcweave.com/project-items/attributes#delete-attributes) an element's attributes, see the **Attributes** page. ### Details Context: Arcweave docs > Project Items > Elements > Element properties > Details An element's **Details** tab contains the following information: #### Element ID Context: Arcweave docs > Project Items > Elements > Element properties > Details > Element ID Each element has a **unique identifier** in the form of: `81a30674-aa09-4eb8-8484-59298d37f984` (version 4 UUID) Uses of this element ID include: - Accessing the element in the project's [JSON](https://docs.arcweave.com/integrations/json). - Targeting the element for CSS styling in the [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor); see the [CSS basics guide](https://docs.arcweave.com/tutorials/style-editor/css-basics#style-specific-elements). #### Word count Context: Arcweave docs > Project Items > Elements > Element properties > Details > Word count The element Details tab includes a word count breakdown: - Words in title - Words in content - Total words It shows the same breakdown for characters: **Characters in title**, **Characters in content**, and **Total characters**. > ℹ️ Word and character counts do not include Arcscript segments in the element's content (see [Add Arcscript](https://docs.arcweave.com/project-items/elements#add-arcscript) above). ## Element references Context: Arcweave docs > Project Items > Elements > Element references Arcweave provides easy access to an element's **references**. These can be: - The **jumpers** targeting the element - The **Arcscript expressions** that mention the element (e.g. a `visits()` expression—see syntax of [`visits` function in Arcscript page](https://docs.arcweave.com/project-items/arcscript#visits).) To access an element's references: 1. Right-click the element, in either of the two locations: - In the board where it lies ![Screenshot of Arcweave's project environment. The element context menu is open (revealed by right-clicking an element in the current board), and an orange rectangle is emphasizing the "References" option.](https://docs.arcweave.com/assets/elements-references-menu-inboard.VkWV16vw.png) - In the **Boards** section of the left sidebar ![Screenshot of Arcweave's project environment. The element context menu is open (revealed by right-clicking an element in the Boards section of the sidebar), and an orange rectangle is emphasizing the "References" option.](https://docs.arcweave.com/assets/elements-references-menu-boardsection.BByWPy8k.png) 2. Select **References**. In the modal that opens, you will see all references of the element in elements, jumpers, connection labels, and branches. ![Screenshot of Arcweave's project environment. The element references modal is open, showing the element's references.](https://docs.arcweave.com/assets/elements-references-modal.lRnP9Fas.png) To visit any of the referencing items, **click on the reference**. > ✅ Use the modal's left sidebar to view all references or to filter the ones in elements, jumpers, connection labels, or branches. # Connections Source: https://docs.arcweave.com/project-items/connections Section: Project Items Description: Connections link elements, branches, and jumpers into your story flow; create, move, reorder, customize, and reroute them **Connections** are arrows that connect board items together ([elements](https://docs.arcweave.com/project-items/elements), [branches](https://docs.arcweave.com/project-items/branches), and [jumpers](https://docs.arcweave.com/project-items/jumpers)), creating your project's flow. > ℹ️ [Notes](https://docs.arcweave.com/project-items/notes) and [comments](https://docs.arcweave.com/project-items/comments) are not part of the project's flow and cannot be connected. In [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview), connections render as **option buttons**, allowing the player to progress the story by making choices. Connections can also carry [labels](https://docs.arcweave.com/project-items/labels), which render as the option buttons' text. ![Split screen of an Arcweave board and its Play Mode. Orange rectangles and arrows emphasize how the connections' labels render as option buttons in Play Mode.](https://docs.arcweave.com/assets/connections-labels-options.3BPh55cY.png) ## Sources & targets Context: Arcweave docs > Project Items > Connections > Sources & targets ![Screenshot showing an element, titled "Source," connected with another, titled "Target," via a connection. The connection has a label that says "Connect!"](https://docs.arcweave.com/assets/connections-source-target.9E84Pp3B.png) Connections progress the story flow from a **source** item (arrow-tail end) to a **target** item (arrow-head end). ### Output connections Context: Arcweave docs > Project Items > Connections > Sources & targets > Output connections From the perspective of the source item, a connection is an **output**. Only elements and branches can have output connections. [Jumpers](https://docs.arcweave.com/project-items/jumpers) cannot act as connection sources. ### Input connections Context: Arcweave docs > Project Items > Connections > Sources & targets > Input connections Conversely, from the perspective of the target item, a connection is an **input**. All elements, branches, and jumpers can receive input connections. ### Number of connections Context: Arcweave docs > Project Items > Connections > Sources & targets > Number of connections The following rules apply to the number of connections an item can have: - Elements, branches, and jumpers can have unlimited input connections. - Elements can have unlimited output connections. - Branches can have one output connection per condition. - Jumpers cannot have output connections. The screenshot below demonstrates these rules. ![Demonstration of how an element, a branch, and a jumper can have input and output connections.](https://docs.arcweave.com/assets/connections-number.ChYENsBD.png) ## Create connections Context: Arcweave docs > Project Items > Connections > Create connections Creating a connection is an intuitive process: you drag from the source ([element](https://docs.arcweave.com/project-items/elements) or [branch](https://docs.arcweave.com/project-items/branches)) and drop onto a target (element, branch, or [jumper](https://docs.arcweave.com/project-items/jumpers)) with your mouse. An alternative is to use [keyboard shortcuts](https://docs.arcweave.com/project-items/connections#with-keyboard-shortcuts). This reduces context switching between mouse and keyboard, helping you focus on typing. ### With drag and drop Context: Arcweave docs > Project Items > Connections > Create connections > With drag and drop The simplest way to create a connection is by dragging and dropping: 1. **Drag from the source**: Depending on the connection's intended source, do the following: - **Element**: Drag from any edge. - **Branch**: Drag from one of its outputs. 2. **Drop onto the target**: Drop the connection's endpoint on either of the following: - **Empty board space**: A menu opens. Choose **Create element here**, **Create jumper here**, or **Create branch here** to create a new item, connected as the target. - **An existing item**: The item becomes the connection's target. Where you drop determines whether the connection is [automatic or fixed](https://docs.arcweave.com/project-items/connections#automatic-and-fixed-connections). ![The menu appearing when dropping a new connection to empty board space offers options to create new element, jumper, and branch at that spot.](https://docs.arcweave.com/assets/connections-create-here.XNjPypMX.png) ### With keyboard shortcuts Context: Arcweave docs > Project Items > Connections > Create connections > With keyboard shortcuts #### Create a connected element Context: Arcweave docs > Project Items > Connections > Create connections > With keyboard shortcuts > Create a connected element You can also create a **connection leading to a new element** using [keyboard shortcuts](https://docs.arcweave.com/project-tools/interface/keyboard-shortcuts#element-creation-connection): 1. Select an element. 2. Press **Ctrl + Alt/Option/Cmd + an arrow key**. A new element is created in the direction of the arrow and connected to the first element. > ✅ The new element is selected automatically. To edit it, press **Enter** and start typing. #### Edit the label of the new connection Context: Arcweave docs > Project Items > Connections > Create connections > With keyboard shortcuts > Edit the label of the new connection To add or edit the label of the connection you just created (and assuming your new element is currently selected) you need to first select the connection: 1. Press **Ctrl/Cmd + the opposite arrow key**, meaning the arrow that points back toward the first element. For example, if you pressed **Right arrow** to create the new element, press **Left arrow** to select the connection. 2. Press **Enter** to edit the connection's label. ## Automatic and fixed connections Context: Arcweave docs > Project Items > Connections > Automatic and fixed connections Each end of a connection attaches to its item through a **handle**, which can be **automatic** or **fixed**: - **Automatic handle**: - Attaches to the **nearest edge** of the item. - **Switches edges automatically** as the source and target items move. - **Fixed handle**: - Stays **locked to a specific side** of the item. - **Does not change sides**, even if the items move. > ℹ️ By default, a connection's source handle is in automatic mode. ### Set the handle mode Context: Arcweave docs > Project Items > Connections > Automatic and fixed connections > Set the handle mode The same gesture sets the mode whether you are creating a connection or moving an existing handle. Drag the handle and drop it: - **On the item's body**: The handle becomes **automatic**. Before you release, the item's entire perimeter is highlighted in orange. - **On a specific edge**: The handle becomes **fixed**. Before you release, that edge is highlighted in orange. ![Screen recording demonstrating the different ways the target gets highlighted when the user drops in the body or on a specific edge.](https://docs.arcweave.com/assets/connections-drag-drop.B43Er2sX.gif) To switch an existing handle between modes, drag it away from its current position and drop it using the rules above. ## Delete connections Context: Arcweave docs > Project Items > Connections > Delete connections You can delete a connection in any of the following three ways: - Select it and press **Delete** or **Backspace**. - Right-click and choose **Delete selection**. - Drag either of its handles to empty board space. ## Select connections Context: Arcweave docs > Project Items > Connections > Select connections Click a connection to select it. To select multiple items, see [Select board items](https://docs.arcweave.com/project-tools/interface/mouse-actions#select-board-items). ## Copy a connection link Context: Arcweave docs > Project Items > Connections > Copy a connection link With only the connection selected, right-click the connection or its label on the board and select **Copy link**. Opening the link takes you to the connection's area on its board in the language active when you copied it. See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position) for access requirements. ## Move connections Context: Arcweave docs > Project Items > Connections > Move connections Each endpoint of a connection has a **handle** that you use to drag and drop with your mouse or trackpad. ### Change source Context: Arcweave docs > Project Items > Connections > Move connections > Change source To change a connection's source, drag the connection's source handle and drop it on a new board item. ### Change target Context: Arcweave docs > Project Items > Connections > Move connections > Change target To change a connection's target, drag its target handle and drop it on a new board item. ### Change handle mode Context: Arcweave docs > Project Items > Connections > Move connections > Change handle mode To switch a handle between automatic and fixed, see [Automatic and fixed connections](https://docs.arcweave.com/project-items/connections#automatic-and-fixed-connections). ## Reorder connections Context: Arcweave docs > Project Items > Connections > Reorder connections Connections render as **player options** in Arcweave's [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview). They also render in the order in which they were added to the flowchart. To reorder an element's output connections: 1. Right-click the element on the board. 2. Select **Play Mode > Quickstart Play Mode from here**. 3. Once in Play Mode, press **Edit content** (the **pencil** icon in the top menu). 4. Drag an option by the grip handle on its left, or by its border, to reorder it. Changes are saved automatically. See [Reorder options](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#reorder-options) for details. ## Customize connections Context: Arcweave docs > Project Items > Connections > Customize connections ### Change color theme Context: Arcweave docs > Project Items > Connections > Customize connections > Change color theme To change a connection's color theme, right-click the connection and select one of the available colors from the menu. ### Change type Context: Arcweave docs > Project Items > Connections > Customize connections > Change type Arcweave supports three connection types: - **Bezier** (default): Smooth curve - **Straight**: Straight line - **Flowchart**: Right-angled line with rounded corners To change the type, right-click the connection and choose from the available icons. > ✅ Your last selected type becomes the default for new connections. ## Edit connection paths Context: Arcweave docs > Project Items > Connections > Edit connection paths By default, Arcweave routes **Bezier** and **Flowchart** connections automatically. You can reshape their paths to avoid overlapping items or to make your board easier to read. **Straight** connections can't be reshaped. To reshape a connection: 1. Click the connection to select it. Path handles appear on it: - **Bezier**: two handles on the curve. - **Flowchart**: a handle on each straight segment you can move. 2. Drag a handle. The connection's endpoints stay attached to their items. - **Bezier**: the curve bends through the dragged handle while the other handle stays in place. - **Flowchart**: the segment moves, and the adjacent segments adjust to keep the right angles. Guides show when the segment aligns with nearby geometry; hold **Alt** while dragging to bypass snapping. 3. Release to save the new path. Press **Escape** before releasing to cancel the drag. Each drag is a single change that you can undo. Handles hide when the connection is too short for them, and they don't appear in image or PDF exports. To restore the automatic path, **double-click** (or double-tap) one of the connection's path handles. Changing the connection's [type](https://docs.arcweave.com/project-items/connections#change-type) also restores automatic routing. When you move an element, customized **Flowchart** segments stay attached to it, and moving both connected items together moves the whole path. Pasting, duplicating, and exporting keep customized paths. > ℹ️ Right-click a path handle to open the connection's context menu. # Labels Source: https://docs.arcweave.com/project-items/labels Section: Project Items Description: Connection labels become option text in Play Mode; create, edit, and position labels and use Arcscript in them Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. [Connections](https://docs.arcweave.com/project-items/connections) can include **labels**: text fields that render as **option text** in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview). ![Split screen of an Arcweave board and its Play Mode. Orange rectangles and arrows emphasize how the connections' labels render as option buttons in Play Mode.](https://docs.arcweave.com/assets/connections-labels-options.3BPh55cY.png) Labels support the following powerful features: - Rich text formatting: Create option text that includes bold, italics, underline, strikethrough, and links. - [Mentions](https://docs.arcweave.com/project-tools/mentions) of [components](https://docs.arcweave.com/project-items/components) and [boards](https://docs.arcweave.com/project-items/boards). - [Arcscript](https://docs.arcweave.com/project-items/arcscript): - Write dynamic option text that changes based on the story state. - Apply variable changes when the option is selected. ## Create labels Context: Arcweave docs > Project Items > Labels > Create labels You can add a label to a [connection](https://docs.arcweave.com/project-items/connections) in either of the following ways: - Double-click the connection. - Right-click the connection and choose **Add label**. Type your text directly using [rich text](https://docs.arcweave.com/project-tools/rich-text). Press **Esc** or **Tab** to exit. ## Edit labels Context: Arcweave docs > Project Items > Labels > Edit labels To edit a label, do either of the following: - Double-click the label or its connection. - Right-click the label or its connection and choose **Edit label**. Format the label's content using [rich text](https://docs.arcweave.com/project-tools/rich-text). > ✅ Project owners and editors can also edit labels in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#edit-content-in-play-mode) while playtesting the story. Enable **Edit content**, then edit the option buttons for the current element. ## Copy a link to a label's connection Context: Arcweave docs > Project Items > Labels > Copy a link to a label's connection With only the connection selected, right-click its label and select **Copy link**. The link opens the connection's area on its board. See [Copy a connection link](https://docs.arcweave.com/project-items/connections#copy-a-connection-link). ## Resize labels Context: Arcweave docs > Project Items > Labels > Resize labels To manually resize a label's width: 1. Click the label to select it. 2. Drag the label's left or right border and release at the desired width. ## Reposition labels Context: Arcweave docs > Project Items > Labels > Reposition labels To change the position of a label on the same connection, **click and drag the label** along the connection and release it at the desirable point. ## Delete labels Context: Arcweave docs > Project Items > Labels > Delete labels To delete a label, do any of the following: - Click the label to select it and press Backspace or Delete. - Right-click the label and choose **Remove label**. - Clear the text and press **Esc** or **Tab**. ## No labels? Context: Arcweave docs > Project Items > Labels > No labels? Labels are not required for your story to run in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview), but they give you greater control and flexibility in shaping the player's experience. If an available option has no label text after Arcscript is evaluated, Arcweave uses the [target element's](https://docs.arcweave.com/project-items/connections#sources-targets) [title](https://docs.arcweave.com/project-items/elements#edit-elements) for its button text. If the target has no title, it uses the beginning of its content instead. When **only one option is available** and its labels produce **no text**, Play Mode shows a blinking arrow instead of an option button. Click the element's content area to continue. Arcweave checks this after evaluating branches and label Arcscript, so multiple outgoing connections can still lead to a single available option. A label containing only variable assignments, or conditional text that produces nothing in the current playthrough, can still result in the arrow. To show a button for a single option, give its path a label that produces text, such as **Continue**. See [labels across branches](https://docs.arcweave.com/project-items/labels#labels-across-branches) for paths with several labels. ## Arcscript in labels Context: Arcweave docs > Project Items > Labels > Arcscript in labels Connection labels support [Arcscript segments](https://docs.arcweave.com/project-items/arcscript), which allow the following features: - **Dynamic option text**: The option text changes based on conditions and variable values. - **Variable changes**: When the player selects an option, the variable changes calculated from its label Arcscript are applied to the playthrough. ### Add Arcscript Context: Arcweave docs > Project Items > Labels > Arcscript in labels > Add Arcscript To add an Arcscript segment while editing a label: 1. Press **Enter** to start a new line. 2. Convert the new line into an Arcscript segment: click the **Arcscript** icon (`<>`) in the toolbar or press **Ctrl/Cmd + Shift + C**. 3. Type your [Arcscript expression](https://docs.arcweave.com/project-items/arcscript#expressions). 4. Press **Enter** to exit the Arcscript segment and start a new rich text line. 5. Repeat step **2** if you need to convert the new line into a consecutive Arcscript segment. ### Evaluation & execution Context: Arcweave docs > Project Items > Labels > Arcscript in labels > Evaluation & execution Play Mode evaluates label Arcscript while preparing the available options: - The result determines the option text. Any variable changes calculated along the path are also available to later labels and branch conditions on that path. - Those variable changes are applied to the playthrough **only when the player selects the option**, before the target element's content is evaluated. Changes from options the player does not select are not applied. This allows for dynamic option text, as in the following example: ```arcweave-html Talk to if name_known Jefferson. else the moustached man. endif ``` ### Labels across branches Context: Arcweave docs > Project Items > Labels > Arcscript in labels > Labels across branches An option can follow several connections through [branches](https://docs.arcweave.com/project-items/branches) before reaching its target element, so one option can carry several labels. The board shows all of them, but Play Mode displays **only one** as the option text. The rest still run their Arcscript. Play Mode applies the following rules to every label on an option's path: - **Option text:** The option displays the text of the **last label on the path that produces text**. The text of earlier labels is not displayed. - **Arcscript:** Every label on the path is evaluated, in path order, including labels whose text is not displayed. Their variable changes are calculated and carried along the path. - **Branch conditions:** Each branch checks its conditions using the values calculated by the labels before it. - **Applying changes:** The variable changes calculated by **all** labels on the path are applied to the playthrough only when the player selects the option, before the target element's content is evaluated. A label produces no text when it is empty after evaluation: for example, when it contains only variable assignments, or conditional text whose condition is not met in the current playthrough. Such a label does not replace the earlier text. Because labels are evaluated every time options are prepared, the same path can display a different label's text in different playthroughs. If no label on the path produces text, the option uses the target element's title. See [No labels?](https://docs.arcweave.com/project-items/labels#no-labels). ### How Play Mode prepares an option across branches Context: Arcweave docs > Project Items > Labels > Arcscript in labels > How Play Mode prepares an option across branches For each path leaving the current element, Play Mode does the following: 1. Starts from the playthrough's current variable values. 2. Evaluates the label of the first connection, calculating its variable changes and its text. 3. At a branch, checks the conditions from top to bottom, using the values calculated so far, and follows the connection of the first condition that is met. If no condition is met, or the first met condition has no outgoing connection, the path ends at the branch and produces no option. 4. Evaluates the label of the next connection, continuing from the values calculated so far. If the label produces text, that text replaces the option's text. 5. Repeats steps 3 and 4 until the path reaches its target element. When the player selects the option, Play Mode applies the calculated variable changes to the playthrough and then loads the target element. If the player selects a different option, these changes are discarded. > ℹ️ Option text that uses `show()` or conditional text reflects the values calculated along the path, even though they have not yet been applied to the playthrough. See the [chain of branches example](https://docs.arcweave.com/project-items/labels#example-a-chain-of-branches). ### Example: labels before and after a branch Context: Arcweave docs > Project Items > Labels > Arcscript in labels > Example: labels before and after a branch Create a [global variable](https://docs.arcweave.com/project-items/variables/global) named `score`, with type **Integer** and initial value `0`. Connect an element named **Gate** to a branch, and connect the branch's `if` output to an element named **Garden**. Set the `if` condition to `score >= 1`, and [start Play Mode from Gate](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#quickstart-play-mode-from-here). On the connection from **Gate** to the branch, add this label: ```arcweave-html Try the gate score = score + 1 ``` On the connection from the branch to **Garden**, add: ```arcweave-html Enter the garden score = score + 2 ``` While preparing the option, Arcweave calculates `score = 1` from the first label. The branch uses that value, so its condition is met. The second label then calculates `score = 3` and replaces **Try the gate** with **Enter the garden** as the option text. The playthrough's `score` remains `0` until the player selects **Enter the garden**. It then becomes `3` before **Garden** loads. If you remove **Enter the garden** from the second label but keep its Arcscript, the option displays **Try the gate** and still changes `score` to `3` when selected. ### Example: a chain of branches Context: Arcweave docs > Project Items > Labels > Arcscript in labels > Example: a chain of branches This example follows the same rules through three branches. Create a global `score` variable of type **Integer**, with initial value `0`. Connect an element named **Start** to a chain of three branches, each with the condition `if true`, and connect the last branch to an element named **Target**. The finished path consists of the following items, in order. Each connection's label holds text, an Arcscript segment, or both: 1. Element: **Start** 2. Connection - Text: `Count to two` 3. Branch: `if true` 4. Connection - Arcscript: `score += 1` 5. Branch: `if true` 6. Connection - Arcscript: `score += 1` 7. Branch: `if true` 8. Connection - Text: `Your score:` - Arcscript: `show(score)` 9. Element: **Target** In Play Mode, **Start** shows a single option: **Your score: 2**. - **Count to two** is not displayed, because a later label on the path produces text. - The two middle labels produce no text, but their assignments are evaluated. The last label shows the calculated value, `2`. - The playthrough's `score` remains `0` while the option is displayed, and becomes `2` when the player selects it, before **Target** loads. # Jumpers Source: https://docs.arcweave.com/project-items/jumpers Section: Project Items Description: Jumpers link to a target element on any board; use cases and how to create, select, and retarget jumpers A jumper is a shortcut on a board: when the story flow reaches it, the story continues at the [element](https://docs.arcweave.com/project-items/elements) it points to, anywhere in the same project. Jumpers allow the connection of elements or [branches](https://docs.arcweave.com/project-items/branches) with other elements that are either far away or in different [boards](https://docs.arcweave.com/project-items/boards). Jumpers offer flexibility to your writing process and improve the readability of your project, allowing you to organize your story in small sections across multiple boards. The element a jumper links to is called **target element**. ## Use cases Context: Arcweave docs > Project Items > Jumpers > Use cases Consider the following use cases: ### Use multiple boards Context: Arcweave docs > Project Items > Jumpers > Use cases > Use multiple boards Structure your narrative by organizing it into sequences, scenes, and dialogue trees. Use [board folders](https://docs.arcweave.com/project-items/boards#board-folders) to group related sequences or acts, and create separate [boards](https://docs.arcweave.com/project-items/boards) for each scene or dialogue tree. This modular setup keeps your project organized and scalable—especially in complex or branching narratives. Once your boards are set up, use jumpers to connect story elements between them. ### Restart the story Context: Arcweave docs > Project Items > Jumpers > Use cases > Restart the story Let players restart the story by linking your ending elements back to the beginning. Use a jumper to connect the final node to the starting one—and don't forget to reset any relevant [variables](https://docs.arcweave.com/project-items/variables/overview)! > ℹ️ Reset variables using the Arcscript functions `reset` and `resetAll`. See [Built-in functions](https://docs.arcweave.com/project-items/arcscript#built-in-functions). ![Example of using a jumper to restart the story. Various ending elements connect to the same Start jumper. Their connection labels contain calls to the resetAll function, which resets all story variables.](https://docs.arcweave.com/assets/jumper-restart.ivZhukXw.png) ### Create loops Context: Arcweave docs > Project Items > Jumpers > Use cases > Create loops You can also use jumpers to create loops within a single board. For example, an element might connect to itself to increment a variable each time it's visited: ![Example of an element connecting to a jumper that has the element itself as a target.](https://docs.arcweave.com/assets/jumper-loop.CdidfJ3R.png) ## Create jumpers Context: Arcweave docs > Project Items > Jumpers > Create jumpers To create a jumper, take any of the three following actions: - **Right-click** on an empty area of the current board and select **Create > Jumper**. - Drag and drop the **New jumper** icon from the bottom menu's left corner to an empty area of the board. - Drop a connection end to an empty board area and select **Create jumper here**. (See [connections](https://docs.arcweave.com/project-items/connections).) These methods create an **empty jumper**. For a jumper to work, you must [assign it a target element](https://docs.arcweave.com/project-items/jumpers#assign-jumper-targets). ## Select jumpers Context: Arcweave docs > Project Items > Jumpers > Select jumpers Click a jumper to select it. To select multiple items, see [Select board items](https://docs.arcweave.com/project-tools/interface/mouse-actions#select-board-items). ## Copy a jumper link Context: Arcweave docs > Project Items > Jumpers > Copy a jumper link With only the jumper selected, right-click it on the board and select **Copy link**. Opening the link centers the jumper itself on its board, rather than following its target element. The link includes the current project language. See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position) for access requirements. ## Delete jumpers Context: Arcweave docs > Project Items > Jumpers > Delete jumpers To delete a jumper, do either of the following two: - Select it and press the **Delete** or **Backspace** key. - Right-click on it and select **Delete selection** from the menu. ## Assign jumper targets Context: Arcweave docs > Project Items > Jumpers > Assign jumper targets To assign a target element to a jumper, do any of the following: - Via **Copy/Paste**: this method is handy when you can easily access the target element in a board. - In the board, click on the element to **select** it. - Copy the element (either with **Ctrl/Cmd + C** or **right-click** and **Copy**). - Right-click your empty jumper (or an empty area of the board) and select **Paste as jumper** (or use the **Ctrl/Cmd + Shift + V** shortcut). - From the **Boards** section: use this method when you have located the target element in the left sidebar. - Go to the **Boards** section of the left sidebar. - Find the board where the target element is. - Expand the board by clicking on the drop-down arrow next to its icon. - Find the target element by its name. - Drag and drop the element into the empty jumper (or an empty area of the board). - From the **Search** field: use this method if you have the target element in your search results. - Search and find the desired element. - From the search results, drag the element into an empty jumper (or an empty area of the board). > ✅ Dragging an element from the **Boards** section or **Search** field, or pasting an element using **Paste as jumper** to an empty area of the board creates a jumper and assigns its target at the same time. ## Change jumper targets Context: Arcweave docs > Project Items > Jumpers > Change jumper targets To change a jumper's target, drag and drop the new target element into the jumper, using any of above methods. # Notes Source: https://docs.arcweave.com/project-items/notes Section: Project Items Description: Notes are rich text sticky notes on boards for ideas and reminders; create, edit, resize, and color them Arcweave's **notes** are simple, flexible sticky textboxes you can place on your boards to jot down ideas, instructions, or reminders. ![Part of an Arcweave board with orange rectangles emphasizing the notes.](https://docs.arcweave.com/assets/castle-notes.XC_xHnxw.png) They're great for organizing your thoughts, leaving comments for teammates, or planning what comes next, without affecting your story's flow. Notes share some features with [elements](https://docs.arcweave.com/project-items/elements): - ✅ [Rich text formatting](https://docs.arcweave.com/project-tools/rich-text#formatting-menu) - ✅ [Customizable color themes](https://docs.arcweave.com/project-items/notes#change-color-theme) - ✅ [Auto-resizing](https://docs.arcweave.com/project-items/notes#resize-notes) Notes differ from elements in the following aspects: - ❌ They do not have a title field. - ❌ They are not part of the flowchart and cannot have [connections](https://docs.arcweave.com/project-items/connections). - ❌ They cannot take [components](https://docs.arcweave.com/project-items/components) as attachments. - ❌ They cannot contain blockquotes or [Arcscript](https://docs.arcweave.com/project-items/arcscript). ## Create notes Context: Arcweave docs > Project Items > Notes > Create notes To create a note: - Right-click on an empty area of the current board and select **Create > Note**. Or: - Drag the **new note icon** from the bottom menu onto an empty area of the board. ![An orange arrow pointing at the note icon at the bottom menu.](https://docs.arcweave.com/assets/notes-icon.CkhDq441.png) ## Select notes Context: Arcweave docs > Project Items > Notes > Select notes Click a note to select it. To select multiple items, see [Select board items](https://docs.arcweave.com/project-tools/interface/mouse-actions#select-board-items). ## Copy a note link Context: Arcweave docs > Project Items > Notes > Copy a note link With only the note selected, right-click it on the board and select **Copy link**. Opening the link centers the note on its board in the language active when you copied it. See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position) for access requirements. ## Delete notes Context: Arcweave docs > Project Items > Notes > Delete notes To delete a note, do either of the following actions: - Select it and press **Delete** or **Backspace**. - Right-click on the note and select **Delete selection**. ## Edit notes Context: Arcweave docs > Project Items > Notes > Edit notes To edit a note, double-click its content. Format the note's content using [rich text](https://docs.arcweave.com/project-tools/rich-text). To exit editing mode, press **Esc** or click anywhere outside the note. ## Resize notes Context: Arcweave docs > Project Items > Notes > Resize notes To resize a note manually, select it and drag any of its corners or edges. To set it to **auto-resize**, so it continuously adjusts to fit its content, double-click any edge or corner handle. ## Change color theme Context: Arcweave docs > Project Items > Notes > Change color theme You can change the color of your notes, to color-code them by topic or purpose. To change a note's color theme, right-click on it and choose one of the available colors from the menu. ![A note's context menu which is used to set the note's color.](https://docs.arcweave.com/assets/notes-color.FmJiAjQB.png) # Assets Source: https://docs.arcweave.com/project-items/assets/overview Section: Project Items Description: How to upload and use assets in Arcweave projects **Assets** are media files you can upload to your Arcweave project to enrich the interactive experience with audiovisual elements. Arcweave supports the following asset types: - [**Image assets**](https://docs.arcweave.com/project-items/assets/images): Used as covers for [elements](https://docs.arcweave.com/project-items/elements) and [components](https://docs.arcweave.com/project-items/components). - [**Audio assets**](https://docs.arcweave.com/project-items/assets/audio): Attached to elements to play automatically in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview), adding sound effects, background music, or narration. - [**Video assets**](https://docs.arcweave.com/project-items/assets/video): Attached to elements to play automatically in Play Mode, enabling video sequences, visual storytelling, or interactive movies. Assets help clarify your story, enhance immersion, and strengthen emotional impact. ## Assets section Context: Arcweave docs > Project Items > Assets > Assets section Inside any project, you can view and manage all uploaded assets and folders in the **Assets** section. This is located in the upper half of Arcweave's left sidebar, under the **Assets** tab. ![The Arcweave project environment with an orange rectangle emphasizing the Assets section of the left sidebar.](https://docs.arcweave.com/assets/assets-sidebar.CKLkshad.png) ## Asset folders Context: Arcweave docs > Project Items > Assets > Asset folders Arcweave allows you to create folders to organize your assets efficiently. You can build a custom folder structure to keep your project files clear and manageable. ## Upload assets Context: Arcweave docs > Project Items > Assets > Upload assets ### From file manager Context: Arcweave docs > Project Items > Assets > Upload assets > From file manager The simplest way to upload assets is by dragging media files from your operating system's file manager into Arcweave's window. You can: - **Drop anywhere**: Adds the files to the root of the [Assets section](https://docs.arcweave.com/project-items/assets/overview#assets-section). - **Drop into a specific position**: Adds the files to a specific folder or position within the Assets list. ### From Assets section Context: Arcweave docs > Project Items > Assets > Upload assets > From Assets section You can also upload files directly within the **Assets** section using the **Upload assets...** options. #### Upload assets to the top of the Assets section Context: Arcweave docs > Project Items > Assets > Upload assets > From Assets section > Upload assets to the top of the Assets section To upload a new asset at the top of your **Assets** list: 1. In the **Assets** section header, click **Create asset** (image icon with a plus). 2. Select **Upload assets...**. 3. Select one or more files from your device. #### Upload assets to the bottom of the Assets section Context: Arcweave docs > Project Items > Assets > Upload assets > From Assets section > Upload assets to the bottom of the Assets section To upload a new asset at the bottom of your **Assets** list: 1. Right-click an empty area in the **Assets** section. 2. Select **Upload assets...**. 3. Select one or more files from your device. #### Upload assets above existing assets Context: Arcweave docs > Project Items > Assets > Upload assets > From Assets section > Upload assets above existing assets To upload a new asset above an existing one: - Right-click the existing asset's name. - Select **Upload assets...** from the menu. Or: - Hover the mouse cursor over the existing asset's name. - Click the **(+) icon** that appears. - Select **Upload assets...** from the menu. #### Upload assets into existing folders Context: Arcweave docs > Project Items > Assets > Upload assets > From Assets section > Upload assets into existing folders To upload a new asset inside a folder: - Right-click the folder's name. - Select **Upload assets...** from the menu. Or: - Hover the mouse cursor over the folder's name. - Click the **(+) icon** that appears. - Select **Upload assets...**. ### Asset upload limits Context: Arcweave docs > Project Items > Assets > Upload assets > Asset upload limits Each workspace plan includes specific file sizes and storage limits: | Plan | Max file size | Total storage per project | | --------- | ------------: | ------------------------: | | **Basic** | 5 MB | 50 MB | | **Pro** | 100 MB | 1 GB | | **Team** | 400 MB | 10 GB | > ⚠️ **If I downgrade my plan, what happens to my assets?** Existing assets remain in your project. New uploads must fit the new plan's limits: each file must be within the maximum file size, and the project's total asset storage, including existing assets, must stay within the plan's limit. See [Downgrade to Basic](https://docs.arcweave.com/workspaces/billing-plans#downgrade-to-basic) in the Workspace plans page. ## Replace assets Context: Arcweave docs > Project Items > Assets > Replace assets You can replace an existing asset with a new file. Arcweave automatically updates all instances of that asset throughout the project, saving you from manually reassigning it. To replace an asset: 1. In the **Assets** section, right-click the asset you want to replace. 2. Select **Replace asset...**. 3. Select a new file from your device. ## Generate image asset Context: Arcweave docs > Project Items > Assets > Generate image asset ![Arcweave's project environment, showing the context menu in the assets section (revealed by right-clicking an asset). An orange rectangle emphasizes the option to Generate asset.](https://docs.arcweave.com/assets/assets-generate-image.wS1dcQGR.png) You can use Arcweave's [Image Generator](https://docs.arcweave.com/project-tools/ai-features/image-generator) to generate image assets. See [Image Generator: Use from the Assets section](https://docs.arcweave.com/project-tools/ai-features/image-generator#use-from-the-assets-section) for instructions. ## Create folders Context: Arcweave docs > Project Items > Assets > Create folders ### From Assets section Context: Arcweave docs > Project Items > Assets > Create folders > From Assets section You can create asset folders directly from your project's **Assets** section. #### Create a folder at the top of the Assets section Context: Arcweave docs > Project Items > Assets > Create folders > From Assets section > Create a folder at the top of the Assets section In the **Assets** section header, click **Create folder** (**folder** icon). #### Create a folder at the bottom of the Assets section Context: Arcweave docs > Project Items > Assets > Create folders > From Assets section > Create a folder at the bottom of the Assets section 1. Right-click an empty area in the **Assets** section. 2. Select **Create folder**. #### Create a folder above an existing asset Context: Arcweave docs > Project Items > Assets > Create folders > From Assets section > Create a folder above an existing asset - Right-click the asset's name. - Select **Create folder** from the menu. Or: - Hover the mouse cursor over the asset's name. - Click the **(+) icon** that appears. - Select **Create folder**. #### Create a subfolder inside an existing folder Context: Arcweave docs > Project Items > Assets > Create folders > From Assets section > Create a subfolder inside an existing folder - Right-click the folder's name. - Select **Create folder** from the menu. Or: - Hover the mouse cursor over the folder's name. - Click the **(+) icon** that appears. - Select **Create folder**. ## Rename assets or folders Context: Arcweave docs > Project Items > Assets > Rename assets or folders To rename an asset or folder: 1. Open the **Assets** section. 2. Right-click the asset or folder. 3. Select **Rename**. ## Asset references Context: Arcweave docs > Project Items > Assets > Asset references Arcweave provides easy access to an asset's **references**: the instances of the asset that are attached to elements or components. To access an asset's references: 1. Right-click the asset in the **Assets** section. 2. Select **References...**. ![Asset context menu with the References option highlighted.](https://docs.arcweave.com/assets/assets-references-menu.bTrx5lnq.png) In the modal that opens, you will see all references of the asset in elements (as a cover, audio attachment, or Asset List item) and components (as a cover or Asset List item). To visit any of the referenced elements or components, **click on the reference**. ![Asset references modal showing where an asset is used in the project.](https://docs.arcweave.com/assets/assets-references-modal.BjDlFNks.png) > ✅ Use the modal's left sidebar to view all references or to filter the ones in elements or components. ## Delete assets or folders Context: Arcweave docs > Project Items > Assets > Delete assets or folders To delete an asset or folder: 1. Open the **Assets** section. 2. Right-click the asset or folder. 3. Select **Delete**. > ℹ️ Deleting an asset removes all its instances from elements and components. > ⚠️ Deleting a folder also deletes all assets and subfolders contained within it. ## Preview assets Context: Arcweave docs > Project Items > Assets > Preview assets To preview an asset, click it in the **Assets** section. Each asset type has its own preview interface: see [image](https://docs.arcweave.com/project-items/assets/images#preview-image-assets), [audio](https://docs.arcweave.com/project-items/assets/audio#preview-audio-assets), and [video](https://docs.arcweave.com/project-items/assets/video#preview-video-assets) documentation for details. ## Use assets Context: Arcweave docs > Project Items > Assets > Use assets After uploading, you can use assets in the following ways: - **Image assets**: Set as covers for [elements](https://docs.arcweave.com/project-items/elements#element-covers) or [components](https://docs.arcweave.com/project-items/components#cover). - **Audio assets**: Attach to [elements](https://docs.arcweave.com/project-items/elements#audio-attachments) to play automatically in Play Mode. - **Video assets**: Set as covers for [elements](https://docs.arcweave.com/project-items/elements#element-covers) to play in Play Mode. # Image assets Source: https://docs.arcweave.com/project-items/assets/images Section: Project Items > Assets Description: How to add and use images in Arcweave projects Use image assets in Arcweave to add visual depth to your story, its objects, and scenes. Setting images as covers for [elements](https://docs.arcweave.com/project-items/elements#element-covers) or [components](https://docs.arcweave.com/project-items/components#cover) enhances immersion and gives players a stronger sense of the world they're navigating. ## Supported file types Context: Arcweave docs > Project Items > Assets > Image assets > Supported file types Arcweave supports the following image file types, which you can use as assets: - `.jpg` / `.jpeg` - `.png` - `.gif` - `.webp` > ℹ️ `.gif` files animate in Play Mode only. In the board view, they appear as static images. Uploaded images can be up to **8192 x 8192 pixels**. ## Preview image assets Context: Arcweave docs > Project Items > Assets > Image assets > Preview image assets You can preview images directly from the **Assets** section. This allows you to view the image in full size and also download it to your device. To preview an image asset: 1. Locate it in the **Assets** section. 2. Click the asset to open its full-size preview. 3. Click **Download** under the image preview, to save the image to your device. ## Element covers Context: Arcweave docs > Project Items > Assets > Image assets > Element covers You can add an image asset as element cover. See [elements](https://docs.arcweave.com/project-items/elements#element-covers) for instructions. ## Component covers Context: Arcweave docs > Project Items > Assets > Image assets > Component covers You can add an image asset as component cover. See [components](https://docs.arcweave.com/project-items/components#cover) for instructions. # Audio assets Source: https://docs.arcweave.com/project-items/assets/audio Section: Project Items > Assets Description: How to add and use audio in Arcweave projects Use audio assets in Arcweave to add music, sound effects, or narration to your interactive project. When you [attach an audio asset](https://docs.arcweave.com/project-items/elements#audio-attachments) to an element, it will automatically play when that element is rendered in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/using-play-mode). ## Supported file types Context: Arcweave docs > Project Items > Assets > Audio assets > Supported file types Arcweave supports the following audio formats: - `.mp3` - `.ogg` - `.wav` - `.webm` You can upload these file types as assets and attach them to elements in your project. ## Preview audio assets Context: Arcweave docs > Project Items > Assets > Audio assets > Preview audio assets You can preview audio directly from the **Assets** section and set the asset's default playback settings. To preview an audio asset: 1. Locate it in the **Assets** section. 2. Click the asset to open its preview. 3. Play the asset, seek through it, and adjust its **volume slider**. Use the speaker icon to mute or unmute it. 4. Optionally, set the asset's **Fade in** and **Fade out** durations in milliseconds. The volume and fade durations are the asset's defaults. Every [audio reference](https://docs.arcweave.com/project-items/assets/audio#audio-reference-settings) to the asset uses them unless it overrides them, helping you balance audio across your project. > ℹ️ Note: [Play Mode](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#control-audio-volume) has a volume slider to control the overall playback volume. ## Attach audio assets Context: Arcweave docs > Project Items > Assets > Audio assets > Attach audio assets To get the audio assets to play in your story, you need to attach them to elements. See [elements](https://docs.arcweave.com/project-items/elements#audio-attachments) for instructions. ## Audio reference settings Context: Arcweave docs > Project Items > Assets > Audio assets > Audio reference settings Each audio asset attached to an element is an **audio reference**. Click an attached audio asset on the element to open its **Audio reference** dialog, which has its own preview and volume slider, followed by its **Play mode settings**. Changes to a reference affect only that element's attachment, not the asset or its other references. ### Audio behavior Context: Arcweave docs > Project Items > Assets > Audio assets > Audio reference settings > Audio behavior Set the reference's playback behavior to one of the following: - **Play clip once**: Plays the audio a single time when the element is reached in the flow and rendered. - **Loop clip**: Continuously loops the audio until it is stopped. - **Stop playing all instances of this clip**: Stops playback of the specified audio asset wherever it is currently playing. ### Delay Context: Arcweave docs > Project Items > Assets > Audio assets > Audio reference settings > Delay To fine-tune playback timing, add a **Delay** in milliseconds before the audio starts. This allows you to synchronize sound with other actions or create dramatic timing effects. Each reference has its own delay, which defaults to `0`. ### Fades Context: Arcweave docs > Project Items > Assets > Audio assets > Audio reference settings > Fades - **Fade in**: Milliseconds for the audio to fade in from silence when it starts playing. - **Fade out**: Milliseconds for the audio to fade out when it stops. A **Play clip once** reference also fades out at the end of the clip. With **Stop playing all instances of this clip**, the reference's **Fade out** sets how the stopped clips fade out; **Delay**, **Fade in**, and **Auto-stop on element exit** don't apply. ### Auto-stop on element exit Context: Arcweave docs > Project Items > Assets > Audio assets > Audio reference settings > Auto-stop on element exit Select **Auto-stop on element exit** to stop the audio, using its fade out, when Play Mode moves to another element. Otherwise, the audio keeps playing until it ends or is stopped by another reference. ### Override asset defaults Context: Arcweave docs > Project Items > Assets > Audio assets > Audio reference settings > Override asset defaults A reference uses the asset's volume, **Fade in**, and **Fade out** unless you change them in the **Audio reference** dialog. A changed fade field is highlighted. To use the asset's value again, click **Reset to asset default** (the circular arrow icon) next to the volume slider or fade field. # Video assets Source: https://docs.arcweave.com/project-items/assets/video Section: Project Items > Assets Description: How to add and use video files in Arcweave projects Use video assets in Arcweave to add advanced visual storytelling, video sequences, or even create complete interactive movies. You can attach videos as [element](https://docs.arcweave.com/project-items/elements) covers and control their [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview) behavior. ## Supported file types Context: Arcweave docs > Project Items > Assets > Video assets > Supported file types Arcweave supports the following video file types, which you can use as assets: - `.mp4` - `.ogg` - `.webm` ## Preview video assets Context: Arcweave docs > Project Items > Assets > Video assets > Preview video assets You can preview videos directly from the **Assets** section. This allows you to view the videos in full size and also download them to your device. To preview a video asset: 1. Locate it in the **Assets** section. 2. Click the asset to open its preview. 3. Click **Download** under the video preview, to save the video file to your device. ## Element covers Context: Arcweave docs > Project Items > Assets > Video assets > Element covers You can add a video asset as element cover. See [elements](https://docs.arcweave.com/project-items/elements#element-covers) for instructions. > ℹ️ Video assets cannot be set as [component covers](https://docs.arcweave.com/project-items/components#cover). ## Playback behavior Context: Arcweave docs > Project Items > Assets > Video assets > Playback behavior When you set a video asset as an element cover, double-click its thumbnail within the element to open its **settings panel**. ![Settings panel for a video asset attached to an Arcweave element. The video shows two oxen and is attributed to Matthias Groeneveld from Pixabay.](https://docs.arcweave.com/assets/assets-video-settings.D8zqS1lH.png) In the settings panel, you can configure the video's playback behavior as follows: 1. **Play behavior** (checkboxes): - **Autoplay**: Automatically starts video playback when the element loads in Play Mode. _(Required if **Show controls** is disabled.)_ - **Show controls**: Displays standard video playback controls. _(Required if **Autoplay** is disabled.)_ - **Show options on video end**: Hides the element's option buttons until the video finishes playing. _(Available only when **Stop at end** is selected.)_ 2. **Stop behavior** (radio buttons): - **Stop at end**: Plays the video once and then stops. - **Loop**: Repeats the video indefinitely. # Components Source: https://docs.arcweave.com/project-items/components Section: Project Items Description: Components are reusable story objects, such as characters, locations, and items, that store information in attributes **Components** are Arcweave's reusable story objects, such as characters, locations, and items. They don't sit on boards or take part in the story flow; instead, each component stores information about one story object in its name, cover, and [attributes](https://docs.arcweave.com/project-items/attributes): labeled values, such as a character's age or backstory. You can attach components to [elements](https://docs.arcweave.com/project-items/elements), [mention](https://docs.arcweave.com/project-tools/mentions) them in text, and use their attributes as [component variables](https://docs.arcweave.com/project-items/variables/component) in Arcscript. Depending on its genre and theme, your story may include some of the following objects: - Characters - Locations - Items - Clues - Weapons - Magical spells - Emotions - Weather conditions - Memories - Time periods - All sorts of stats Components are very flexible: you can use them to represent any of the above, according to your project's needs. For example, the component below stores a magical spell, with its stats (level, range, description, and so on) stored as attributes. ![An open component storing a magical spell, with the component's attributes storing the spell's stats and specs.](https://docs.arcweave.com/assets/components-intro.BKzGX-79.jpg) You can find and manage your project's components and their folders on the upper part of Arcweave's sidebar, under the **Components** tab. ## Component folders Context: Arcweave docs > Project Items > Components > Component folders To organize your components efficiently, Arcweave lets you create your own structure of component folders within your project. ## Components section Context: Arcweave docs > Project Items > Components > Components section Once inside a project, you can view and manage your components and folders in the **Components** section, located in the upper half of Arcweave's left sidebar, under the **Components** tab. ![The Arcweave project environment with an orange rectangle emphasizing the Components section of the left sidebar.](https://docs.arcweave.com/assets/components-sidebar.DNiuAhMt.png) ## Create components or folders Context: Arcweave docs > Project Items > Components > Create components or folders ### At section top Context: Arcweave docs > Project Items > Components > Create components or folders > At section top To create a new component or folder at the top of the **Components** section: - Go to the header of the **Components** section. - Click **Create component** (**+** icon) or **Create folder** (**folder** icon). ### At section bottom Context: Arcweave docs > Project Items > Components > Create components or folders > At section bottom To create a new component or folder at the bottom of the **Components** section: - Right-click on an empty area of the **Components** section. - Select **Create component** or **Create folder** from the menu. ### Above existing component Context: Arcweave docs > Project Items > Components > Create components or folders > Above existing component To create a new component or folder above an existing component in the **Components** section: - Right-click on the existing component's name. - Select **Create component** or **Create folder** from the menu. Or: - Hover the mouse cursor over the existing component's name. - Click on the **(+) icon** that appears. - Select **Create component** or **Create folder** from the menu. ### Inside existing folder Context: Arcweave docs > Project Items > Components > Create components or folders > Inside existing folder To create a new component or folder inside an existing folder: - Right-click on the existing folder's name. - Select **Create component** or **Create folder** from the menu. Or: - Hover the mouse cursor over the existing folder's name. - Click on the **(+) icon** that appears. - Select **Create component** or **Create folder** from the menu. ## Delete components or folders Context: Arcweave docs > Project Items > Components > Delete components or folders To delete a component or folder: - Right-click on its name, on the **Components** section. - Select **Delete**. > ⚠️ Deleting a component folder will also delete all its contents. You can undo the action. > ℹ️ When deleting a component, all [mentions](https://docs.arcweave.com/project-tools/mentions) and references of this component will be removed as well. ## Rename components or folders Context: Arcweave docs > Project Items > Components > Rename components or folders To rename a component or folder: - Right-click on its name on the **Components** section. - Select **Rename** from the menu. You can also rename a component while [editing](https://docs.arcweave.com/project-items/components#edit-components) it. ## Duplicate components or folders Context: Arcweave docs > Project Items > Components > Duplicate components or folders To duplicate a component or folder: - Right-click on its name on the **Components** section. - Select **Duplicate**. Duplicating a folder also duplicates all the components and folders it contains. ## Copy a component link Context: Arcweave docs > Project Items > Components > Copy a component link Select **Copy link** from any of these menus: - Right-click the component in the sidebar's **Components** section. - Open the component and click the **three-dot (•••)** menu in its header. - Right-click a component reference attached to an element or included in a **Component List** attribute. Opening the link opens the component's dialog in the language active when you copied it. A reference's link opens the referenced component. Component folders and unsaved components do not have this action. See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position) for access requirements. People with read-only board access can also copy component links. ## Mention components Context: Arcweave docs > Project Items > Components > Mention components You can create links to your components while editing rich text in elements, notes, attributes, and labels. This kind of link is called a [mention](https://docs.arcweave.com/project-tools/mentions) and you initiate it by typing the character `@` followed by a component name. > ℹ️ You can also mention [boards](https://docs.arcweave.com/project-items/boards#mention-boards). ## Edit components Context: Arcweave docs > Project Items > Components > Edit components To open a component for editing, find it in the list of your components and click on its name or thumbnail. Each component consists of a **name**, a **custom ID**, a **cover image**, and a set of **attributes**. ### Name Context: Arcweave docs > Project Items > Components > Edit components > Name To rename a component, click on its name field, or choose **Rename** from the **three-dot (•••)** header menu to select the field for editing. You can also [rename a component](https://docs.arcweave.com/project-items/components#rename-components-or-folders) from the **Components** section. ### Custom ID Context: Arcweave docs > Project Items > Components > Edit components > Custom ID Every component has a custom ID, generated from its name. This ID scopes the component's [variables](https://docs.arcweave.com/project-items/variables/component). For example, an attribute with custom ID `health` on a component with custom ID `hero` is available in Arcscript as `hero.health`. Select the custom ID beneath the component name to edit it, or choose **Edit Custom ID** from the **three-dot (•••)** header menu to select the field. It cannot be removed, must be unique across all components and boards, and must follow the [variable naming rules](https://docs.arcweave.com/project-items/variables/overview#variable-names-and-custom-ids). Renaming it updates existing Arcscript references automatically. ### Cover Context: Arcweave docs > Project Items > Components > Edit components > Cover To change a component's cover image: 1. Hover the mouse cursor over the image. 2. Click on **Change cover**. 3. Select an image from the **My Assets** tab, or an icon from the **Icon Library** tab. You can also generate a cover in the **Generate** tab; see [Image Generator](https://docs.arcweave.com/project-tools/ai-features/image-generator#use-from-components). Alternatively, you can drag and drop an image asset from the sidebar into the component cover area. > ✅ An asset will also be created and attached to a component as cover when dropping an image file from your drive or browser at the top area of the component (while in component edit mode). > ⚠️ [Video assets](https://docs.arcweave.com/project-items/assets/video) cannot be used as component covers. ### Component attributes Context: Arcweave docs > Project Items > Components > Edit components > Component attributes Like [boards](https://docs.arcweave.com/project-items/boards), components can hold the following attribute types: - String Field - Boolean - Integer - Float - Rich Text Field - Component List - Asset List Component folders cannot contain attributes. String Field, Boolean, Integer, and Float attributes are [component variables](https://docs.arcweave.com/project-items/variables/component). See [Attributes](https://docs.arcweave.com/project-items/attributes) for more details about attributes that do not act as variables. To [add](https://docs.arcweave.com/project-items/attributes#create-attributes), [edit](https://docs.arcweave.com/project-items/attributes#edit-attributes), or [remove](https://docs.arcweave.com/project-items/attributes#delete-attributes) a component's attributes, see the **Attributes** page. ## Component properties Context: Arcweave docs > Project Items > Components > Component properties To access a component's properties: 1. Right-click the component in the **Components** section. 2. Select **Properties**. The component Properties panel displays the following information: ### Component ID Context: Arcweave docs > Project Items > Components > Component properties > Component ID Each component has a **unique identifier** in the form of: `81a30674-aa09-4eb8-8484-59298d37f984` (version 4 UUID) Click the **clipboard icon** to copy the component ID. Component IDs are useful when working with the project's [JSON](https://docs.arcweave.com/integrations/json) or integrating Arcweave with external tools and game engines. The UUID is different from the component's editable [custom ID](https://docs.arcweave.com/project-items/components#custom-id), which is used as an Arcscript variable scope. ### Words and characters Context: Arcweave docs > Project Items > Components > Component properties > Words and characters The component properties panel displays the component's word and character counts. These counts include the component name and the values of its String Field and Rich Text Field attributes. ## Component references Context: Arcweave docs > Project Items > Components > Component references Arcweave provides easy access to a component's **references**: the elements it is attached to, the Component List attributes that include it, and the element content, labels, notes, and attributes that mention it. To access a component's references: 1. Right-click the component in the **Components** section. 2. Select **References**. ![Arcweave's project environment. The Components context menu (revealed by right-clicking a component) is open, and an orange rectangle is emphasizing the References option.](https://docs.arcweave.com/assets/components-references-menu.DiFh2db9.png) In the modal that opens, you will see all references of the component in elements, components, connection labels, and notes. ![Arcweave's project environment. The Components reference modal is open, showing the references of a component.](https://docs.arcweave.com/assets/components-references-modal.DwF8QVD7.png) To visit any of the referenced elements or components, **click on the reference**. > ✅ Use the modal's left sidebar to view all references or to filter the ones in elements, components, labels, or notes. ## Attach to elements Context: Arcweave docs > Project Items > Components > Attach to elements You can also attach components to elements. To do this: 1. Go to your **Components** section on the sidebar. 2. Drag the component of your choice and drop it inside the element of your choice. ![Animated GIF demonstrating how to attach a component to an element and then how to remove the attachment.](https://docs.arcweave.com/assets/drag-component.1SxFaBei.gif) Use this feature to **create a visual reference** to the component during a plot point or dialogue beat and to **easily access** the component—just click on the attachment and the component will open. To share the attached component, right-click its reference on the board and select **Copy link**. See [Copy a component link](https://docs.arcweave.com/project-items/components#copy-a-component-link). > ℹ️ The attached components of an element also render on Play Mode. Drag and drop attached components to **reorder** them inside an element or to **move them** from one element to another. To **remove** an attached component, drag and drop it from the element to an empty area of the board. > ℹ️ Removing a component from an element simply removes the reference and does not delete the component. # Branches Source: https://docs.arcweave.com/project-items/branches Section: Project Items Description: Branches add conditional logic to flowcharts with if, elseif, and else conditions in Arcscript; create, edit, and connect them Branches are board items that carry **conditional logic**. By evaluating one or more conditions written in [Arcscript](https://docs.arcweave.com/project-items/arcscript), a branch determines which outgoing connection the game flow follows at runtime. ![A branch with the conditions "if items.bronze_key", "else-if items.potion_strength", "else" directs the flow to three possible output connections with the respective options: "Unlock the door", "Drink potion of strength and bash in", and "Sob inconsolably".](https://docs.arcweave.com/assets/branch-intro.Df5oSQNe.png) > ℹ️ The above example uses [board variables](https://docs.arcweave.com/project-items/variables/board): variable attributes on a board with the custom ID `items`, such as `bronze_key` and `potion_strength`. In [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview), a branch evaluates its conditions in order and sends the game flow down the connection that corresponds to the first condition satisfied. You can use this behavior to control precisely which options are presented to the player. ## Conditions and connections Context: Arcweave docs > Project Items > Branches > Conditions and connections ### Number of connections Context: Arcweave docs > Project Items > Branches > Conditions and connections > Number of connections A branch can have any number of incoming connections. Its outgoing connections correspond one-to-one with its conditions, structured as: - `if condition 1` → Connection 1 - `elseif condition 2` → Connection 2 - ... - `elseif condition n` → Connection n - `else` → Connection n+1 ### Number of conditions Context: Arcweave docs > Project Items > Branches > Conditions and connections > Number of conditions Logic dictates that a branch must have exactly one `if` condition, may have any number of `elseif` conditions, and may have at most one `else` condition. ### Condition expressions Context: Arcweave docs > Project Items > Branches > Conditions and connections > Condition expressions Each `if` and `elseif` condition holds a single Arcscript expression, such as `score > 3` or `has_key`. The branch supplies the `if` or `elseif` keyword, so you write only the expression, without `if`, `endif`, or other statements. ### Condition evaluation Context: Arcweave docs > Project Items > Branches > Conditions and connections > Condition evaluation Conditions are evaluated in order from top to bottom. In the example below, the `elseif` expression is redundant and will always be skipped: - `if score < 1000`... - `elseif score < 10`... - `else` The `else` condition applies to all cases not covered by the previous `if`/`elseif` conditions, therefore it does not take custom expressions. > ✅ Play-test your branch logic in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview). ## Branch usage Context: Arcweave docs > Project Items > Branches > Branch usage Branches connect with [elements](https://docs.arcweave.com/project-items/elements), [jumpers](https://docs.arcweave.com/project-items/jumpers), and other branches, permitting or blocking the narrative flow depending on their conditions and the current game state. ### Labels along a branch path Context: Arcweave docs > Project Items > Branches > Branch usage > Labels along a branch path Connections entering and leaving a branch can both have labels. When a path passes through one or more branches, the option displays the **last label that produces text** after Arcscript is evaluated. > ✅ A later label that produces no text keeps the earlier label's text. Every label on a branch path has **its Arcscript evaluated**, including labels whose text is replaced by a later label. Variable changes from all labels accumulate along the path, and a branch checks its conditions using the values calculated by the labels before it. These variable changes are applied to the playthrough **only when the player selects that option**, before its target element loads. See [Labels across branches](https://docs.arcweave.com/project-items/labels#labels-across-branches) for the rules, [How Play Mode prepares an option across branches](https://docs.arcweave.com/project-items/labels#how-play-mode-prepares-an-option-across-branches) for the evaluation order, and the [chain of branches example](https://docs.arcweave.com/project-items/labels#example-a-chain-of-branches). ### `if` branches Context: Arcweave docs > Project Items > Branches > Branch usage > `if` branches An `if`-only branch renders its connected option only when its condition is met. Otherwise, it blocks the story flow, providing no output. ![Arcweave project environment with an orange rectangle emphasizing a branch that only has an if condition: if item.bronze_key.](https://docs.arcweave.com/assets/branches-if.BU3TkMSy.png) In the above example, the branch evaluates the board variable `items.bronze_key`. If `true`, the option to unlock the door is presented. If `false`, no option appears instead. You can add multiple `if`-only branches to offer several independent conditional options. If the player satisfies more than one condition, they receive all corresponding options. ![Arcweave project environment with orange rectangles emphasizing 3 branches that only have if conditions. Each branch evaluates a variable relative to an item: the bronze key, the potion of strength, and the battle axe.](https://docs.arcweave.com/assets/branches-if-multiple.nOqK28oW.png) Below, you can see how the example above renders in Play Mode, if the player has all three items: ![Arcweave Play Mode environment. The Debugger is open and we can see that all three item variables are `true`. Each branch is evaluated and all 3 options appear as buttons.](https://docs.arcweave.com/assets/branches-if-multiple-play-mode.2b69blfU.png) ### elseif conditions Context: Arcweave docs > Project Items > Branches > Branch usage > elseif conditions To ensure the player receives **at most one** option from a set of possibilities, use a single branch with `elseif` conditions rather than multiple separate branches. In the following example, the options of using the key or the potion are bundled in the same branch, so only one option can be provided, even if the player has both items: ![Arcweave project environment. Two orange rectangles emphasize two branches. The first branch has an if condition (evaluating the bronze key) and an elseif condition (evaluating the potion of strength). The second branch only has an if condition (evaluating the battle axe).](https://docs.arcweave.com/assets/branches-if-elseif-multiple.u3_5Y6ge.png) Even if the player has the potion of strength, only using the bronze key will be available as an option. The bronze key takes priority, due to its higher position in the branch. ![Arcweave Play Mode environment with the Debugger visible. We can see that the values of all three items bronze key, potion of strength, and battle axe are true. Two option buttons are visible, though: the option to use the bronze key and the battle axe.](https://docs.arcweave.com/assets/branches-if-elseif-multiple-play-mode.BPxnMndr.png) The battle axe appears independently, since it is evaluated by its own branch. ### Fallback options Context: Arcweave docs > Project Items > Branches > Branch usage > Fallback options When using conditional options, get in the good habit of including at least one unconditional option (that is one without a branch). This can work as a fallback option, making sure the flow can continue regardless of the game state. In this example, the flow continues even if the player has none of the three items: ![Arcweave project environment where an orange rectangle emphasizes the fallback option of "walking away", compared to two more options that lead to branches.](https://docs.arcweave.com/assets/branches-if-elseif-multiple-safety.JvYksFEx.png) In Play Mode, only the fallback option is visible: ![Arcweave Play Mode environment with the Debugger visible. We can see that the values of all three items bronze key, potion of strength, and battle axe are false and only the fallback option "Walk away" is visible.](https://docs.arcweave.com/assets/branches-if-elseif-multiple-play-mode-safety.1cbUAYVu.png) ### else conditions Context: Arcweave docs > Project Items > Branches > Branch usage > else conditions Adding an `else` condition guarantees the branch always provides exactly one option, regardless of which conditions are met. ![Arcweave project environment showing a branch that includes `if`, `elseif`, and `else` conditions evaluating board variables.](https://docs.arcweave.com/assets/branches-if-elseif-else.DssujV9V.png) In this example, the branch provides the option to use only one object, even if the player has all three of them. ![Arcweave Play Mode environment with the Debugger visible. We can see that the values of all three items bronze key, potion of strength, and battle axe are true. Besides the fallback option "Walk away", the only other option visible is the one about the bronze key.](https://docs.arcweave.com/assets/branches-if-elseif-else-play-mode.oZzQwiZ8.png) > ✅ Read more about [variables](https://docs.arcweave.com/project-items/variables/overview) and [Arcscript](https://docs.arcweave.com/project-items/arcscript) on their respective pages. ## Create branches Context: Arcweave docs > Project Items > Branches > Create branches To create a branch, do any of the following: - Right-click on an empty board area and select **Create > Branch** from the menu. - Drag and drop the **New branch icon** (at the left of the [bottom menu](https://docs.arcweave.com/project-tools/interface/bottom-menu)) onto an empty board area. - Drag a connection from an element or another branch and drop it on an empty board area, then select **Create branch here**. The new branch is created as the connection's target. See [Create connections](https://docs.arcweave.com/project-items/connections#with-drag-and-drop). When you create a new branch, it contains only its required `if` condition. ## Select branches Context: Arcweave docs > Project Items > Branches > Select branches Click a branch to select it. To select multiple items, see [Select board items](https://docs.arcweave.com/project-tools/interface/mouse-actions#select-board-items). ## Copy a branch link Context: Arcweave docs > Project Items > Branches > Copy a branch link With only the branch selected, right-click it on the board and select **Copy link**. Opening the link centers the branch on its board in the language active when you copied it. See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position) for access requirements. ## Delete branches Context: Arcweave docs > Project Items > Branches > Delete branches To delete a branch, do either of the following: - Select it and press **Delete** or **Backspace**. - Right-click on it and select **Delete selection** from the menu. ## Edit branches Context: Arcweave docs > Project Items > Branches > Edit branches ### `if` conditions Context: Arcweave docs > Project Items > Branches > Edit branches > `if` conditions #### Edit `if` conditions Context: Arcweave docs > Project Items > Branches > Edit branches > `if` conditions > Edit `if` conditions To edit the `if` condition, double-click it. Press **Esc** to exit editing. > ⚠️ The `if` condition is required and cannot be added or removed. ### `elseif` conditions Context: Arcweave docs > Project Items > Branches > Edit branches > `elseif` conditions #### Add `elseif` conditions Context: Arcweave docs > Project Items > Branches > Edit branches > `elseif` conditions > Add `elseif` conditions To add an `elseif` condition, do either of the following: - Right-click the branch and choose **Add elseif**. - Press **Ctrl+Enter** or **Cmd+Enter** while editing another condition. The new `elseif` condition appears below the one you are editing. #### Remove `elseif` conditions Context: Arcweave docs > Project Items > Branches > Edit branches > `elseif` conditions > Remove `elseif` conditions To remove an `elseif` condition: 1. Double-click the `elseif` condition to enter editing mode. 2. Click the **(x) icon** that appears on the right side of the condition. #### Edit `elseif` conditions Context: Arcweave docs > Project Items > Branches > Edit branches > `elseif` conditions > Edit `elseif` conditions To edit an `elseif` condition, double-click it. Press **Esc** to exit editing. ### `else` conditions Context: Arcweave docs > Project Items > Branches > Edit branches > `else` conditions #### Add `else` conditions Context: Arcweave docs > Project Items > Branches > Edit branches > `else` conditions > Add `else` conditions To add an `else` condition, do either of the following: - Right-click the branch and choose **Add else**. - Press **Enter** while editing another condition, if the branch has no `else` condition yet. #### Remove `else` conditions Context: Arcweave docs > Project Items > Branches > Edit branches > `else` conditions > Remove `else` conditions To remove the `else` condition, right-click the branch and select **Remove else**. > ℹ️ A branch can have only one `else` condition. > ℹ️ The `else` condition matches all cases not covered by the preceding `if`/`elseif` conditions, therefore it takes no custom expression and cannot be edited. ## Change color theme Context: Arcweave docs > Project Items > Branches > Change color theme To change the color theme of a branch, right-click on it and select one of the available colors from the menu. # Attributes Source: https://docs.arcweave.com/project-items/attributes Section: Project Items Description: Storing information in boards, components, and elements using attributes Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. In Arcweave, **attributes** let you store information inside [boards](https://docs.arcweave.com/project-items/boards), [components](https://docs.arcweave.com/project-items/components), and [elements](https://docs.arcweave.com/project-items/elements). Board and component attributes can also provide scoped variables for your story logic. The following attribute types are available on boards, components, and elements: - Rich Text Field - String Field - Component List - Asset List Boards and components additionally support these variable-compatible attribute types: - Boolean - Integer - Float Attributes are particularly useful when you [integrate](https://docs.arcweave.com/integrations/overview) your story with other platforms or game engines. Attribute content does not render automatically in Play Mode. However, String Field, Boolean, Integer, and Float board and component attributes can be read and changed through Arcscript, and their values appear in the [Debugger](https://docs.arcweave.com/project-tools/play-mode/debugger). ## General structure Context: Arcweave docs > Project Items > Attributes > General structure All types of attributes follow the same basic structure: a _Label-Content_ pair. The label is the human-readable name of the attribute. The content is its value, whose data type depends on the attribute type. ## String field Context: Arcweave docs > Project Items > Attributes > String field Use string fields to store single-line, plain text values, like words, numbers, or short phrases. Example cases of the string field include the following: **Component attributes**: - A character's aliases, e.g. `Nickname`: `Yardbird` - A character's ability scores, e.g. `Charisma`: `12` - A weapon's damage die, e.g. `Damage`: `1d4` - A spell's specifications, e.g. `Duration`: `3 rounds` **Element attributes**: - Setting an element as starting (or ending) dialogue, e.g. `dialogue`: `start` - Tagging an element with properties required for a storylet or an event to trigger, e.g. `storylet`: `foo` Boards and components treat String Field attributes as scoped variables. Use the dedicated **Integer** or **Float** type when you need a numeric value. Elements do not support numeric attribute types; use a string field for numeric element metadata. These fields are particularly useful when [integrating](https://docs.arcweave.com/integrations/overview) with other platforms, as they don't contain any HTML tags. ## Rich text field Context: Arcweave docs > Project Items > Attributes > Rich text field Use rich text attributes when you want to store long, detailed, or formatted content in a board, component, or element attribute. Example cases of the rich text field include the following: - **Descriptions**: Write a short description for your character or location. - **Backstory**: Keep characters' backstories in their components for easy access. Rich Text attributes support basic formatting options such as **bold**, _italic_, underline, and ~~strikethrough~~. You can also include [mentions](https://docs.arcweave.com/project-tools/mentions) to reference components and boards in your project. > ⚠️ Do not confuse a rich text attribute of an element with the element's main content. Attributes are for internal use only and do _not_ appear in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview). ## Component lists Context: Arcweave docs > Project Items > Attributes > Component lists Use component lists when you need to attach an array of components to a board, component, or element. > ✅ Elements include a primary component list, visible in Play Mode, which is created by dragging a component directly into the element. Additional component lists can be added as element attributes; however, these are metadata only and do _not_ render in Play Mode. You can use this to list items and relations, as in the following examples: - **Character inventory**: add the items carried (as components) into a character's component. - **Spellbook**: list the spells they know. - **Character relations**: list other characters that have important relations to the component character. - **Contents**: in a location's component, list the items or characters found there. Component lists also have a **label field**, so name each of them according to your needs. ![An open component showing the component list attribute: a component list is used as an inventory list storing the item components the character is carrying.](https://docs.arcweave.com/assets/component-lists.Bq4qdfvh.jpg) The attached components appear with their thumbnail. Click on the thumbnail to open the attached component. ## Asset lists Context: Arcweave docs > Project Items > Attributes > Asset lists Use asset lists when you need to attach an array of image, audio, or video assets to a board, component, or element. > ✅ Elements already have their unique cover (image or video asset) and their attached audio clips (audio assets), which appear in Play Mode. Still, asset list attributes allow you to add additional image, audio, and video references as metadata, although they are not visible in Play Mode. The image below shows an element with all 4 types of attributes. ![Screenshot showing the open element properties modal, featuring all 4 types of element attributes. First, there is a component list called "Locations" that has two components. Then, there is a string attribute called "Year of construction" that has the value "1562." Third, an audio list called "Audio files" that has 3 audio files. Finally, a rich text attribute called "Backstory" that tells the backstory of the castle.](https://docs.arcweave.com/assets/element-attributes.-YEd--m5.png) ## Access attributes Context: Arcweave docs > Project Items > Attributes > Access attributes To create, edit, or delete an attribute, first open the item's attributes interface. ### Board attributes dialog Context: Arcweave docs > Project Items > Attributes > Access attributes > Board attributes dialog To access a board's attributes, right-click a regular board in the **Boards** section and select **Attributes**. Boards that already have attributes also display an attributes button next to their name. ### Component attributes panel Context: Arcweave docs > Project Items > Attributes > Access attributes > Component attributes panel To access a component's attributes, do the following: 1. Locate the component: - **Sidebar**: In the **Components** section - **Current board**: In an element where it is attached 2. Click the component to open its attributes panel. ### Element attributes panel Context: Arcweave docs > Project Items > Attributes > Access attributes > Element attributes panel To access an element's attributes, do the following: 1. Locate the element on your board. 2. Right-click the element and choose **Properties**. 3. In the Properties modal, switch to the **Attributes** tab, to reveal its attributes panel. ## Scoped variable attributes Context: Arcweave docs > Project Items > Attributes > Scoped variable attributes A String Field, Boolean, Integer, or Float attribute on a board or component becomes an Arcscript variable when the attribute and its owner have custom IDs. These are called [board variables](https://docs.arcweave.com/project-items/variables/board) and [component variables](https://docs.arcweave.com/project-items/variables/component). The Arcscript reference combines two IDs: - The owning board or component's **custom ID** is the scope. - The attribute's **custom ID** is the variable name. For example, an integer attribute with custom ID `health` on the component `hero` is referenced as `hero.health`: ```arcscript hero.health -= 10 show(hero.health) ``` The attribute label can be more descriptive and does not affect the Arcscript reference. Rich Text Field, Component List, and Asset List attributes remain metadata even if their exported data contains a `customId`. Arcweave generates a custom ID when you create a regular board or component. When you name a variable attribute, Arcweave generates its custom ID from its label. To edit an attribute custom ID, open its three-dot menu and select **Edit Custom ID**. To edit the scope, select the custom ID beneath a board title or component name. Renaming an ID updates existing Arcscript references automatically. ### Custom ID rules Context: Arcweave docs > Project Items > Attributes > Scoped variable attributes > Custom ID rules See [Variable names and custom IDs](https://docs.arcweave.com/project-items/variables/overview#variable-names-and-custom-ids) for the syntax, uniqueness, and reserved-name rules shared by global, board, and component variables. ## Create attributes Context: Arcweave docs > Project Items > Attributes > Create attributes After opening the relevant attributes interface, do either of the following: - To add an attribute at the end of the list, click **Add attribute** below the attributes and select the type you want to create. - To add an attribute after an existing one: 1. Hover the mouse cursor over the existing attribute. 2. Open its **three-dot menu** and select **Add Attribute**. 3. Select the type of attribute you want to create from the menu. The newly created attribute will appear below the clicked one. On boards and components, variable-compatible types appear in the **Variables** group of the type menu. **Integer** and **Float** are under **Number** in that group. ## Edit attributes Context: Arcweave docs > Project Items > Attributes > Edit attributes To edit an attribute, open the relevant attributes interface, then do either of the following: - **Label**: Click the attribute's label, type the new label, and press **Enter** or click outside the attribute. - **Content**: Click the attribute's content and edit its value. For component and asset lists, see [Add to list attributes](https://docs.arcweave.com/project-items/attributes#add-to-list-attributes). On board and component variable attributes, the label is only a human-readable description. Changing it does not change the attribute's custom ID, so existing Arcscript references keep working. To change how Arcscript references the attribute, [edit its custom ID](https://docs.arcweave.com/project-items/attributes#scoped-variable-attributes) instead. ## Add to list attributes Context: Arcweave docs > Project Items > Attributes > Add to list attributes ### Component lists Context: Arcweave docs > Project Items > Attributes > Add to list attributes > Component lists To add a component to a component list, do the following: 1. Open the relevant attributes interface. 2. Locate the component list attribute you want to use. 3. In the **Components** section of the sidebar, find the component you want to attach. 4. Drag and drop it into the component list. To share a listed component, right-click its reference and select **Copy link**. The link opens the referenced component's dialog. See [Copy a component link](https://docs.arcweave.com/project-items/components#copy-a-component-link). You can also **reorder components** within a list or **move them between lists** by dragging and dropping. ### Asset lists Context: Arcweave docs > Project Items > Attributes > Add to list attributes > Asset lists To add an asset to an asset list, do the following: 1. Open the relevant attributes interface. 2. Locate the asset list attribute you want to use. 3. In the **Assets** section of the sidebar, find the asset you want to attach. 4. Drag and drop it into the asset list. You can also **reorder assets** within a list or **move them between lists** by dragging and dropping. ## Resize attributes Context: Arcweave docs > Project Items > Attributes > Resize attributes By default, attributes span the **full width** of their interface, but you can resize an attribute to span only **half-width** and vice-versa. To resize an attribute, do the following: 1. Hover the mouse cursor over it. 2. Open the **three-dot menu** at the top right. 3. Select **Resize**. ## Reorder attributes Context: Arcweave docs > Project Items > Attributes > Reorder attributes To reorder an attribute, do the following: 1. Click and hold it from the **dots icon** that appears at its top left corner when you hover over it. 2. Drag and release it above or below another attribute. ## Delete attributes Context: Arcweave docs > Project Items > Attributes > Delete attributes To delete an attribute, do the following: 1. Hover the mouse cursor over it. 2. Open the **three-dot menu** at the top right. 3. Select **Delete**. # Arcscript Source: https://docs.arcweave.com/project-items/arcscript Section: Project Items Description: Arcweave's scripting language, use, syntax, and functions Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. Arcweave has its own scripting language, **Arcscript**, with basic scripting capabilities. You can use Arcscript in the following two ways: - As **conditions**, in [branches](https://docs.arcweave.com/project-items/branches). - As **segments**, in [element content](https://docs.arcweave.com/project-items/elements#add-arcscript) and [connection labels](https://docs.arcweave.com/project-items/labels#arcscript-in-labels). ## Arcscript in branches Context: Arcweave docs > Project Items > Arcscript > Arcscript in branches Arcscript is used in **branches** to control flow with `if`, `elseif`, and `else` conditions. ![Arcweave project environment showing a branch that includes `if`, `elseif`, and `else` conditions evaluating board variables.](https://docs.arcweave.com/assets/branches-if-elseif-else.DssujV9V.png) Branch conditions use the [expressions](https://docs.arcweave.com/project-items/arcscript#expressions) and [condition operators](https://docs.arcweave.com/project-items/arcscript#conditions) described on this page. For how a branch evaluates its conditions, see [branches](https://docs.arcweave.com/project-items/branches). ## Arcscript segments Context: Arcweave docs > Project Items > Arcscript > Arcscript segments Arcscript segments are single lines of code that you can add into the content of [elements](https://docs.arcweave.com/project-items/elements) and [labels](https://docs.arcweave.com/project-items/labels). ![A label and an element with contents that include rich text and Arcscript code.](https://docs.arcweave.com/assets/element-label-richtext-arcscript.CBFrUdz9.png) They support [assignment statements](https://docs.arcweave.com/project-items/arcscript#assignment-statements), [conditional statements](https://docs.arcweave.com/project-items/arcscript#conditional-statements), and calls to [built-in functions](https://docs.arcweave.com/project-items/arcscript#built-in-functions) such as `show()` or `reset()`. > ℹ️ In Play Mode, an Arcscript segment does not start a new paragraph. Text before and after a segment, including text produced by a conditional statement or `show()`, joins the same paragraph, separated by a space. To keep the text after a segment in a separate paragraph, leave an empty line after the segment. ## Add Arcscript Context: Arcweave docs > Project Items > Arcscript > Add Arcscript To insert an Arcscript segment into the content of an [element](https://docs.arcweave.com/project-items/elements) or connection [label](https://docs.arcweave.com/project-items/labels), you use the **Arcscript** icon of the [formatting menu](https://docs.arcweave.com/project-tools/rich-text), the one with the symbol `<>`. ![Arcweave's project environment, while editing an element. An orange arrow and an orange rectangle emphasize the position of the Arcscript icon in the formatting bar.](https://docs.arcweave.com/assets/arcscript-segments-icon.sqO3lJkR.png) 1. Double-click the element or label to enter content editing mode. 2. Place the cursor on the line where you want to insert the Arcscript segment. 3. Click the **Arcscript** icon (`<>`) in the formatting menu. 4. Press **Enter** to exit the Arcscript segment and continue writing in the next line. > ✅ You can also toggle an Arcscript segment using the shortcut **Ctrl/Cmd + Shift + C**. ## Auto-complete Context: Arcweave docs > Project Items > Arcscript > Auto-complete While you type in an Arcscript segment or branch condition, Arcweave provides auto-complete suggestions. ![Animated GIF demonstrating the auto-complete feature in Arcscript.](https://docs.arcweave.com/assets/auto-complete.8qWJtNCz.gif) Suggestions include: - Global variables, and board and component variables with their scope, such as `hero.health` - [Built-in functions](https://docs.arcweave.com/project-items/arcscript#built-in-functions) - The keywords `if`, `elseif`, `else`, and `endif` - The word operators `and`, `or`, `not`, and `is` - The literals `true` and `false` Use the arrow keys to select the relevant suggestion and press **Enter** or **Tab** to insert it in your code. Press **Esc** to close the suggestions. ## Variables and scope Context: Arcweave docs > Project Items > Arcscript > Variables and scope Global variables use their name directly. Board and component variables are String Field, Boolean, Integer, or Float attributes and use the owning board or component's custom ID as a scope: ```arcscript health = 100 castle.health = 10 hero.health = 20 ``` In this example, `health`, `castle.health`, and `hero.health` are three distinct variables. Unqualified names such as `health` resolve global variables only. Scoped variables support string, boolean, integer, and float values. See [Variable scope](https://docs.arcweave.com/project-items/variables/overview#variable-scope), [Board variables](https://docs.arcweave.com/project-items/variables/board), and [Component variables](https://docs.arcweave.com/project-items/variables/component) for setup instructions. ## Assignment statements Context: Arcweave docs > Project Items > Arcscript > Assignment statements Assignment statements are of the form of `variable = expression`. For example: ```arcscript x = 5 x = y + 5 name = "Tim" has_key = true ``` > ℹ️ Before using a variable, create it in **Global variables** or add a **String Field**, **Boolean**, **Integer**, or **Float** attribute to a board or component. Arcweave's auto-complete uses the variable's current name and scope. Arcscript also supports the following operations, with their respective operators: | Operation | Operator | Description | | :------------- | :------: | :-------------------------------------------------------------------------------- | | Addition | `+=` | Adds the right-hand value to the variable and assigns the result. | | Subtraction | `-=` | Subtracts the right-hand value from the variable and assigns the result. | | Multiplication | `*=` | Multiplies the variable by the right-hand value and assigns the result. | | Division | `/=` | Divides the variable by the right-hand value and assigns the result. | | Modulo | `%=` | Applies modulo to the variable using the right-hand value and assigns the result. | For example: ```arcscript x = 5 x += 10 x -= 2 ``` With string values, `+=` appends the right-hand text, for example `name += " Smith"`. The other compound operators cause an error when used with strings. ## Conditional statements Context: Arcweave docs > Project Items > Arcscript > Conditional statements Conditional statements are of the form: `if...`/`elseif...`/`else`/`endif`. > ℹ️ This section applies to conditional statements found in [elements](https://docs.arcweave.com/project-items/elements) and [labels](https://docs.arcweave.com/project-items/labels). Conditional statements in branches follow the same logic, but do not close with `endif` expressions. See [Condition evaluation](https://docs.arcweave.com/project-items/branches#condition-evaluation). Inside conditional statements you may have: - other statements (assignments, function calls, or conditionals). - text content. > ⚠️ The `if`, `elseif`, `else`, and `endif` segments of a conditional statement cannot be inside a blockquote, although the text between them can. Inside a blockquote, you can use assignments and function calls. Example of a conditional statement containing an assignment: ```arcscript if x == 5 y = 4 endif ``` Example of a conditional statement containing some text content: ```arcweave-html if wielding_shield The knight is wielding a large shield. endif ``` Example of a conditional statement containing some text content and a variable assignment: ```arcweave-html if hasKey You unlock the door! doorUnlocked = true else You cannot open the door endif ``` Example of using `elseif` for multiple outcomes: ```arcweave-html if age >= 18 Look at you! All grown up! type = "adult" elseif age > 0 You are not an adult yet. type = "child" else Are you sure you have been born? type = "unborn" endif ``` ## Expressions Context: Arcweave docs > Project Items > Arcscript > Expressions Arcscript supports expressions that use the following arithmetic operators: | Operator | Name | Description | | :------: | :------------- | :-------------------------------------------------------------- | | `+` | Addition | Adds two numbers, or joins them as text if either is a string. | | `-` | Subtraction | Subtracts the right-hand value from the left-hand value. | | `*` | Multiplication | Multiplies two numeric values. | | `/` | Division | Divides the left-hand value by the right-hand value. | | `%` | Modulo | Returns the remainder of a division between two numeric values. | | `(` `)` | Parentheses | Groups parts of an expression to control evaluation order. | Expressions may combine literals, function calls, and variables. Write string literals in double or single quotes, such as `"Tim"` or `'Tim'`. A minus sign before a value negates it, such as `-x`. ## Conditions Context: Arcweave docs > Project Items > Arcscript > Conditions ### Conditional operators Context: Arcweave docs > Project Items > Arcscript > Conditions > Conditional operators | Operator | Name | Description | | :------------: | :-------------------- | :----------------------------------------------------------------------------------- | | `==`, `is` | Equality | Checks whether two values are equal. `5` and `"5"` are not equal. | | `!=`, `is not` | Inequality | Checks whether two values are not equal. | | `>` | Greater than | Checks whether the left-hand value is greater than the right-hand value. | | `>=` | Greater than or equal | Checks whether the left-hand value is greater than or equal to the right-hand value. | | `<` | Less than | Checks whether the left-hand value is less than the right-hand value. | | `<=` | Less than or equal | Checks whether the left-hand value is less than or equal to the right-hand value. | ### Logical operators Context: Arcweave docs > Project Items > Arcscript > Conditions > Logical operators | Operator | Name | Description | | :----------: | :---------- | :--------------------------------------------------------------- | | `&&`, `and` | Logical AND | Evaluates to `true` if both conditions are true. | | `\|\|`, `or` | Logical OR | Evaluates to `true` if at least one condition is true. | | `!`, `not` | Logical NOT | Negates a condition, turning `true` into `false` and vice versa. | ## Built-in functions Context: Arcweave docs > Project Items > Arcscript > Built-in functions The functions that are currently supported in Arcscript: | Function | Returns | | ----------------------- | ---------------------------------------------------------------------------------------- | | `abs(n)` | The absolute value of a number | | `sqr(n)` | The square of a number | | `sqrt(n)` | The square root of a number | | `min(n1, n2, ...)` | The minimum of two or more numbers | | `max(n1, n2, ...)` | The maximum of two or more numbers | | `random()` | A random decimal between (and including) 0 and (excluding) 1, i.e. in `[0, 1)` | | `reset(v1, v2, ...)` | Has no return value; resets one or more given variables to their initial value | | `resetAll(v1, v2, ...)` | Has no return value; resets all variables, except the given ones, to their initial value | | `resetVisits()` | Has no return value; resets all elements' visits to 0 | | `roll(m, n)` | The sum of `n` rolls of an `m`-sided die (`n` defaults to 1) | | `round(n)` | The number rounded to the nearest integer | | `show(e1, e2, ...)` | Has no return value; renders the concatenation of its evaluated arguments as text | | `visits(el)` | The number of visits to an element; without an argument, to the current element | `reset()` and `resetAll()` apply to global, board, and component variables. Call `resetAll()` without arguments to reset every variable. ### `roll` Context: Arcweave docs > Project Items > Arcscript > Built-in functions > `roll` ![A part of an Arcweave flowchart demonstrating a simple use of the roll function: roll returns a value that gets stored in a variable. Then, a branch compares the variable with a number and diverts the flow accordingly.](https://docs.arcweave.com/assets/roll.CXzWJU8f.png) The `roll(m, n)` function simulates polyhedral die rolls from the classic tabletop RPGs. Roll takes up to 2 positive integers as its arguments: - `m`: the number of sides of the rolled die. - `n`: the number of dice rolled. The function returns a random integer between (and including both) `n` and `n*m`, i.e. `[n, n*m]`. > ✅ If `n = 1`, you can omit the second argument and simply type `roll(m)`. For example, rolling for a number from 1 to 12: ```arcscript damage = roll(12) ``` Example of rolling 3d6 (3 six-sided dice) for a character's ability scores in _Dungeons & Dragons:_ ```arcscript dexterity = roll(6, 3) ``` Example of a dynamic use, where the player suffers damage from `1` to `max_damage`: ```arcscript player_hp = player_hp - roll(max_damage) ``` But the `roll(m, n)` function can also be used in a conditional statement: ```arcweave-html if roll(max_damage) > player_hp Oops... This isn't good... endif ``` ### `show` Context: Arcweave docs > Project Items > Arcscript > Built-in functions > `show` The `show(e1, e2, ...)` function renders its arguments and concatenates them as one string. For example, the following: ```arcscript show("Your score is ", score, "/", max_score, ".") ``` ... for `score == 3` and `max_score == 256` renders: > Your score is 3/256. You can use the `show(e1, e2, ...)` function in combination with text content, in elements. For example: ```arcweave-html if roll(max_damage) > player_hp Oops... This isn't good... You have died. In this game you scored show(score, " out of ", max_score, ".") endif ``` ### `visits` Context: Arcweave docs > Project Items > Arcscript > Built-in functions > `visits` #### Call `visits()` with an `element` argument Context: Arcweave docs > Project Items > Arcscript > Built-in functions > `visits` > Call `visits()` with an `element` argument The `visits(element)` function returns the number of times a specific element has been visited during the current playthrough. The count includes the current visit: while the player is on an element for the first time, its count is `1`. The `element` argument must be a **mention** to an element. To mention an element inside `visits()`: 1. Place your cursor within the parentheses of `visits()`. 2. Type `@` and begin entering the element's title. You can mention elements from any board. 3. Select the correct element from the autocomplete list. > ✅ Mentioning an element in Arcscript works similarly to [mentioning a component or board](https://docs.arcweave.com/project-tools/mentions) in rich text fields. #### Call `visits()` without an argument Context: Arcweave docs > Project Items > Arcscript > Built-in functions > `visits` > Call `visits()` without an argument If `visits()` is called without an argument, it refers to the element the player is currently on: - When used inside an **element's content**, it refers to that element itself. - When used inside a **connection label** or **branch condition**, it refers to the element whose options are being prepared: the element where the option's path starts. > ✅ To reset the visits of all elements of your project, use the `resetVisits()` function. It is always called without arguments. #### Examples Context: Arcweave docs > Project Items > Arcscript > Built-in functions > `visits` > Examples In the following example, `examine_the_painting` is a mention of the **Examine the painting** element: ```arcweave-html The knight is guarding a mysterious gate. You see a name written above his head: "Conrad IV, Count of Exeter" if visits(examine_the_painting) > 1 You make a mental note of the knight's name. endif ``` And if we are already in the **Examine the painting** element, we can write: ```arcweave-html The knight is guarding a mysterious gate. You see a name written above his head: "Conrad IV, Count of Exeter" if visits() > 1 You make a mental note of the knight's name. endif ``` ## Errors Context: Arcweave docs > Project Items > Arcscript > Errors Arcweave checks your Arcscript as you write it. When a script has a syntax error, uses a variable that does not exist, calls a function with the wrong number of arguments, or mentions an element that does not exist, an **exclamation mark symbol** appears at the corner of the element, label, or branch condition that contains it. > ✅ Hover your mouse cursor over the symbol to see the error message and the line and column where the error occurs. Other errors occur only when Play Mode runs the script, such as dividing by zero or passing text to a function that expects a number. Play Mode shows these errors below the element's content or below its options. An option whose label causes an error is not shown, and a branch condition that causes an error counts as not met. # Variables Source: https://docs.arcweave.com/project-items/variables/overview Section: Project Items Description: How to create and use story variables in your Arcweave project Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. Arcweave uses **variables** to store data during play. These are the mechanism through which the game can "remember" what happens and progress accordingly. Variables are used in [branches](https://docs.arcweave.com/project-items/branches), as well as in [Arcscript segments](https://docs.arcweave.com/project-items/arcscript#arcscript-segments) within [elements](https://docs.arcweave.com/project-items/elements) and [labels](https://docs.arcweave.com/project-items/labels). ## Common use cases Context: Arcweave docs > Project Items > Variables > Common use cases You can use variables in the following ways. ### Assign values Context: Arcweave docs > Project Items > Variables > Common use cases > Assign values Assigning a value to a variable stores that value for later use in the game. You can assign values using any of [Arcscript's assignment statements](https://docs.arcweave.com/project-items/arcscript#assignment-statements). For example, if the player finds a key, you can store this information in a boolean variable named `has_key` (see [variable types](https://docs.arcweave.com/project-items/variables/overview#variable-types), below), assigning it the value `true` in an [Arcscript segment](https://docs.arcweave.com/project-items/arcscript#arcscript-segments). Then, the game will remember that the player has found the key. ![Arcweave's project environment, focused on an element's content that says "You found the key!" and an Arcscript segment says "has_key = true".](https://docs.arcweave.com/assets/branch-has-key-true.C3mzxS05.png) ### Evaluate in branches Context: Arcweave docs > Project Items > Variables > Common use cases > Evaluate in branches Evaluating a variable allows the game to read and use its value. [Branches](https://docs.arcweave.com/project-items/branches) can evaluate variables using `if`/`elseif`/`else` [conditions](https://docs.arcweave.com/project-items/branches#condition-evaluation) and direct the story flow accordingly. > ℹ️ For a full guide on Arcscript conditions and their syntax, see [Arcscript](https://docs.arcweave.com/project-items/arcscript) > [Conditional statements](https://docs.arcweave.com/project-items/arcscript#conditional-statements). In the same example as above, when the player finds the locked drawer, a [branch](https://docs.arcweave.com/project-items/branches) can decide whether they can open it, by evaluating the variable `has_key` in an `if` statement. ![Arcweave's project environment, focused on a branch of which the condition says "if has key". The branch leads to a connection of which the label says "Unlock the drawer".](https://docs.arcweave.com/assets/branch-has-key._4VTzFo3.png) ### Display dynamic text Context: Arcweave docs > Project Items > Variables > Common use cases > Display dynamic text Another common use of variables is to **display dynamic text content** in [elements](https://docs.arcweave.com/project-items/elements) and [labels](https://docs.arcweave.com/project-items/labels). In other words, the player gets to see different text output depending on the variables' values. #### Dynamic text using conditional statements Context: Arcweave docs > Project Items > Variables > Common use cases > Display dynamic text > Dynamic text using conditional statements One way of creating dynamic text output is by using conditional statements that output different text. For example, by using the integer `day` (see [Variable types](https://docs.arcweave.com/project-items/variables/overview#variable-types)), we can display a different message to the player as the weekend approaches. (Week starts from `1` = Monday.) ```arcweave-html if day >= 6 It's weekend! You stretch out in bed. No alarm, no rush. Bliss. elseif day >= 5 Weekend is almost here. You hum your favourite song all the way to work. else The week is still young. Lots of things to do. endif ``` > ℹ️ For a full guide on Arcscript conditions and their syntax, see [Arcscript](https://docs.arcweave.com/project-items/arcscript) > [Conditional statements](https://docs.arcweave.com/project-items/arcscript#conditional-statements). #### Dynamic text using the `show` function Context: Arcweave docs > Project Items > Variables > Common use cases > Display dynamic text > Dynamic text using the `show` function Another way to display dynamic text in elements and labels is by using the `show` function, which renders its arguments as text content. The following example uses the `coins` integer (see [Variable types](https://docs.arcweave.com/project-items/variables/overview#variable-types)) to store the player's riches: ```arcscript show("You have ", coins, " gold coins.") ``` > ℹ️ See [Arcscript](https://docs.arcweave.com/project-items/arcscript) > [`show`](https://docs.arcweave.com/project-items/arcscript#show) for more on the function's syntax and uses. ## Variable types Context: Arcweave docs > Project Items > Variables > Variable types The supported variable types are: - **Boolean**: A `true`/`false` value, useful for tracking flags, e.g. `has_key` or `met_daisy`. - **String**: A sequence of characters, used for names or any other text value, e.g. `happy` or `John Smith`. - **Integer**: A whole number, ideal for stats or counters, e.g. `dexterity` or `score`. - **Float**: A number with a decimal point, suited for precise measurements, e.g. `speed` or `temperature`. > ⚠️ Arcscript does not enforce strict type checking. When type conversion occurs, it follows JavaScript's type coercion rules. For board and component variables, the **String** type appears as **String Field** in the attributes menu. Every variable has an initial value. Play Mode starts with these values, and restarting Play Mode restores them for global, board, and component variables. ## Variable scope Context: Arcweave docs > Project Items > Variables > Variable scope Arcweave supports one global variable category and two scoped variable categories: | Category | Stored and managed in | Arcscript reference | | -------------------------------------------------------- | ------------------------------- | ------------------------ | | [Global variable](https://docs.arcweave.com/project-items/variables/global) | The **Global variable dialog** | `score` | | [Board variable](https://docs.arcweave.com/project-items/variables/board) | The **Board attributes dialog** | `castle.drawbridge_open` | | [Component variable](https://docs.arcweave.com/project-items/variables/component) | The component editor | `hero.health` | All three categories can be read and changed from anywhere in the project. For board and component variables, the scope qualifies the variable's name; it does not restrict where the variable is available. A component variable belongs to the component itself, so attaching that component to multiple elements does not create separate copies of its value. Board and component variables use the same underlying mechanism. A **String Field**, **Boolean**, **Integer**, or **Float** attribute becomes a scoped variable when both the attribute and its owning board or component have custom IDs. Rich Text, Component List, and Asset List attributes remain metadata and cannot be used as Arcscript variables. The owner's custom ID is the scope and the attribute's custom ID is the variable name. The attribute label is only a human-readable description and does not affect the Arcscript reference. Unqualified names such as `health` resolve global variables only, so `health`, `castle.health`, and `hero.health` can coexist as three distinct variables. ### Variable names and custom IDs Context: Arcweave docs > Project Items > Variables > Variable scope > Variable names and custom IDs Variable names and custom IDs must be valid Arcscript identifiers and cannot be Arcscript keywords or built-in function names. - A global variable name must start with a letter, `_`, or `$` and must be unique among global variables. - A board or component custom ID must start with a letter or `$` and must be unique across all regular boards and components. - A variable attribute custom ID must start with a letter, `_`, or `$` and must be unique among the attributes of its owner. - After the first character, these identifiers can contain letters, numbers, and underscores. A global variable name may match a board or component custom ID because unqualified and scoped references are distinct. For example, the global variable `hero` and the component variable `hero.health` can coexist. Arcweave generates a custom ID when you create a regular board or component. When you name a variable attribute, Arcweave generates its custom ID from its label. Renaming an owner or attribute custom ID updates existing Arcscript references automatically. ## Variables in Debugger Context: Arcweave docs > Project Items > Variables > Variables in Debugger When in Play Mode, you can monitor the variables and their values in the Debugger. See [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview) > [Debugger](https://docs.arcweave.com/project-tools/play-mode/debugger) for full instructions. # Global variables Source: https://docs.arcweave.com/project-items/variables/global Section: Project Items > Variables Description: How to create, manage, and use project-level variables in Arcweave **Global variables** are project-level variables that are not owned by a board or component. They are accessed without a scope. ## Global variables list Context: Arcweave docs > Project Items > Variables > Global variables > Global variables list To view and manage your project's global variables, click **Global variables** at the bottom of the [left sidebar](https://docs.arcweave.com/project-tools/interface/left-sidebar). ![Arcweave's project environment. An orange arrow points at the Global variables button, at the bottom of the left sidebar.](https://docs.arcweave.com/assets/global-vars-button.DJ5Zg1TN.png) This opens the **global variables list**, which includes the project's global variables along with their **name**, **type**, and **initial value**. ![The Global variable dialog in Arcweave, showing all the global variables of a project.](https://docs.arcweave.com/assets/variables-modal.BmdWUv-m.png) > ℹ️ A variable's **initial value** is the value it holds at the start of [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview). ## Create global variables Context: Arcweave docs > Project Items > Variables > Global variables > Create global variables To create a new variable follow the next steps: 1. Click **Global variables** at the bottom of the sidebar to open the **Global variable dialog**. 2. Click **+ New variable**. 3. Enter a unique variable name. 4. Select the variable's **type** from the dropdown menu. 5. Enter its **initial value**. > ℹ️ Arcweave will prevent you from entering an invalid initial value for a variable's type (e.g. a string like `"John Smith"` for an integer). See [Variable names and custom IDs](https://docs.arcweave.com/project-items/variables/overview#variable-names-and-custom-ids) for the naming rules. ## Use global variables Context: Arcweave docs > Project Items > Variables > Global variables > Use global variables Global variables are accessible from anywhere in the project using **just their name**, e.g. `score += 2`. An unqualified name always resolves a global variable, never a board or component variable. See [Common use cases](https://docs.arcweave.com/project-items/variables/overview#common-use-cases) in the Variables overview page for instructions and examples. ## Search global variables Context: Arcweave docs > Project Items > Variables > Global variables > Search global variables To locate a variable in the global variables list, start typing its name in the search field at the top of the **Global variable dialog**. ![The Global variable dialog in Arcweave, demonstrating the search function. The user has typed "play" in the search field, making only the variables player_health and player_roll appear in the list.](https://docs.arcweave.com/assets/variables-modal-search.CG-v2uBr.png) ## Filter global variables Context: Arcweave docs > Project Items > Variables > Global variables > Filter global variables For type-specific searches, you can filter your variables list by type: 1. Click the **Filter** icon at the right of the search field, at the top of the **Global variable dialog**. 2. Select the variable types you want to add to the search. ![The Global variable dialog in Arcweave, demonstrating how to filter variables by type. The filter for "string" has been selected, showing only string variables in the list.](https://docs.arcweave.com/assets/variables-modal-filter.DHE5jeeo.png) ## Reorder global variables Context: Arcweave docs > Project Items > Variables > Global variables > Reorder global variables To reorder variables: 1. Click **Global variables** at the bottom of the sidebar to open the **Global variable dialog**. 2. Click and hold the **handle icon** at the beginning of the variable's row. 3. Drag and drop the row to the desired position. ![The Global variable dialog in Arcweave, demonstrating how to reorder variables by dragging and dropping.](https://docs.arcweave.com/assets/variables-reorder.gT9EOVSZ.gif) ## Delete global variables Context: Arcweave docs > Project Items > Variables > Global variables > Delete global variables 1. Click **Global variables** at the bottom of the sidebar to open the **Global variable dialog**. 2. Locate the variable in the list. 3. Click the **three dots icon** at the end of its row. 4. Select **Delete variable**. ## Global variables in Debugger Context: Arcweave docs > Project Items > Variables > Global variables > Global variables in Debugger When in Play Mode, you can monitor the global variables and their values in the Debugger. ![Arcweave's Play Mode environment, with the Debugger sidebar open on the right. An orange rectangle emphasizes the list of the project's global variables.](https://docs.arcweave.com/assets/play-mode-global-variables.DVl9WnDF.png) See [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview) > [Debugger](https://docs.arcweave.com/project-tools/play-mode/debugger) for full instructions. # Board variables Source: https://docs.arcweave.com/project-items/variables/board Section: Project Items > Variables Description: How to create, manage, and use board-scoped variables in Arcweave Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. Board variables are **String Field**, **Boolean**, **Integer**, or **Float** [attributes](https://docs.arcweave.com/project-items/attributes) added to a board. These types appear in the **Variables** group of the **Add attribute** menu because Arcscript treats them as variables scoped to that board. ![Arcweave project environment showing an element and a branch that both include the board variable "items.battle_axe"](https://docs.arcweave.com/assets/variables-board-usage.C9PMguxY.png) Use a board variable from anywhere in the project by joining the board's **custom ID** and the variable's **custom ID** with a dot: ```arcscript castle.drawbridge_open = true ``` Unqualified names resolve global variables only. For example, `health` and `castle.health` can coexist and store different values. ## Create board variables Context: Arcweave docs > Project Items > Variables > Board variables > Create board variables 1. Right-click a regular board in the **Boards** section of the sidebar. 2. Select **Attributes** to open the **Board attributes dialog**. 3. Click **Add attribute** and select **String Field**, **Boolean**, **Number > Integer**, or **Number > Float** from the **Variables** group. 4. Enter the variable's label and initial value. The board already has a custom ID generated when the board was created. Arcweave generates the variable's custom ID from its label. Their Arcscript reference appears as `board_custom_id.variable_custom_id`. Board folders cannot contain attributes or variables. ## Use board variables Context: Arcweave docs > Project Items > Variables > Board variables > Use board variables Board variables can be read and changed from anywhere in the project. Their board custom ID is a namespace, not an access restriction. See [Common use cases](https://docs.arcweave.com/project-items/variables/overview#common-use-cases) for assignment, branch, and dynamic-text examples. ## Edit board and variable custom IDs Context: Arcweave docs > Project Items > Variables > Board variables > Edit board and variable custom IDs The board's custom ID appears below the title of the **Board attributes dialog**. Select it to edit the scope used by all variables on that board. To edit a variable's custom ID, open its three-dot menu and select **Edit Custom ID**. The variable label is for people reading the project; its custom ID is the member name used in Arcscript. Renaming either the board or attribute custom ID updates existing Arcscript references automatically. Custom IDs cannot be empty and must follow the [variable naming rules](https://docs.arcweave.com/project-items/variables/overview#variable-names-and-custom-ids). ## Manage board variables Context: Arcweave docs > Project Items > Variables > Board variables > Manage board variables Boards with attributes display an **attributes button** next to their name in the sidebar. Select it to open the **Board attributes dialog** directly. From there, you can: - Search and filter attributes. - Drag variables to reorder them. - Rename a variable or edit its custom ID from its three-dot menu. - Delete a variable from its three-dot menu. See [Attributes](https://docs.arcweave.com/project-items/attributes) for full instructions. ## Find and debug board variables Context: Arcweave docs > Project Items > Variables > Board variables > Find and debug board variables Project [Search](https://docs.arcweave.com/project-tools/search) can find a board variable by its label or custom ID and open the **Board attributes dialog** for its owning board. In Play Mode, the Debugger groups board variables under the board's name and custom ID and shows their current values. See [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview) > [Debugger](https://docs.arcweave.com/project-tools/play-mode/debugger) for full instructions. # Component variables Source: https://docs.arcweave.com/project-items/variables/component Section: Project Items > Variables Description: How to create, manage, and use component-scoped variables in Arcweave Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. Component variables are **String Field**, **Boolean**, **Integer**, or **Float** [attributes](https://docs.arcweave.com/project-items/attributes) added to a component. These types appear in the **Variables** group of the **Add attribute** menu because Arcscript treats them as variables scoped to that component. Use a component variable from anywhere in the project by joining the component's **custom ID** and the variable's **custom ID** with a dot: ```arcscript hero.health -= 10 ``` Unqualified names resolve global variables only. For example, `health` and `hero.health` can coexist and store different values. ## Create component variables Context: Arcweave docs > Project Items > Variables > Component variables > Create component variables 1. Find the component in the **Components** section of the sidebar. 2. Click the component to open the component editor. 3. Click **Add attribute** and select **String Field**, **Boolean**, **Number > Integer**, or **Number > Float** from the **Variables** group. 4. Enter the variable's label and initial value. The component already has a custom ID generated when the component was created. Arcweave generates the variable's custom ID from its label. Their Arcscript reference appears as `component_custom_id.variable_custom_id`. Component folders cannot contain attributes or variables. ## Use component variables Context: Arcweave docs > Project Items > Variables > Component variables > Use component variables Component variables can be read and changed from anywhere in the project. Their component custom ID is a namespace, not an access restriction. A component variable belongs to the component itself. Attaching the component to multiple elements does not create separate copies of the variable or its value. See [Common use cases](https://docs.arcweave.com/project-items/variables/overview#common-use-cases) for assignment, branch, and dynamic-text examples. ## Edit component and variable custom IDs Context: Arcweave docs > Project Items > Variables > Component variables > Edit component and variable custom IDs The component's custom ID appears beneath its name in the component editor. Select it to edit the scope used by all variables on that component. To edit a variable's custom ID, open its three-dot menu and select **Edit Custom ID**. The variable label is for people reading the project; its custom ID is the member name used in Arcscript. Renaming either the component or attribute custom ID updates existing Arcscript references automatically. Custom IDs cannot be empty and must follow the [variable naming rules](https://docs.arcweave.com/project-items/variables/overview#variable-names-and-custom-ids). ## Manage component variables Context: Arcweave docs > Project Items > Variables > Component variables > Manage component variables Open the component editor from the **Components** section or from an element where the component is attached. From there, you can: - Drag variables to reorder them. - Rename a variable or edit its custom ID from its three-dot menu. - Delete a variable from its three-dot menu. See [Attributes](https://docs.arcweave.com/project-items/attributes) for full instructions. ## Find and debug component variables Context: Arcweave docs > Project Items > Variables > Component variables > Find and debug component variables Project [Search](https://docs.arcweave.com/project-tools/search) can find a component variable by its label or custom ID and open the owning component. In Play Mode, the Debugger groups component variables under the component's name and custom ID and shows their current values. See [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview) > [Debugger](https://docs.arcweave.com/project-tools/play-mode/debugger) for full instructions. # Comments Source: https://docs.arcweave.com/project-items/comments Section: Project Items Description: Create, reply to, resolve, and filter comment threads on boards, with user mentions and comment notifications [Workspace members](https://docs.arcweave.com/workspaces/roles#workspace-members) and [guests](https://docs.arcweave.com/workspaces/roles#workspace-guests) can use **comments** to communicate directly on [projects](https://docs.arcweave.com/workspaces/projects). Users with the above roles can add and reply to comments, as well as [mention](https://docs.arcweave.com/project-items/comments#user-mentions) each other. Moreover, they get [email notifications](https://docs.arcweave.com/project-items/comments#email-notification-settings), when new comments and replies are posted. ![Arcweave's project environment, with orange arrows pointing at the Comments icon (opening the comments sidebar) and the "create new comment" icon at the bottom menu. An orange rectangle shows two comment pins in the current board, one resolved and one unresolved. A comment pin looks like the speech bubble icon. A resolved comment pin (when visible) is of a darker color than the unresolved one.](https://docs.arcweave.com/assets/comments-general.Dlfmw-tR.png) You can find your project's comments in both: - The board they have been created, as **comment pins**. - The **[comments sidebar](https://docs.arcweave.com/project-items/comments#comments-sidebar)**, as a list. Use the [comments sidebar](https://docs.arcweave.com/project-items/comments#comments-sidebar) to do the following: - See all your comments in the **comments list**. - Set your **email notifications** preferences. - Filter the comments you want to see. - Mark all comments as read. > ⚠️ [Project visitors](https://docs.arcweave.com/workspaces/roles#project-visitors) cannot view or create comments. ## Comments sidebar Context: Arcweave docs > Project Items > Comments > Comments sidebar Click the **Comments** icon in the top-right menu to open the **comments sidebar**. This panel shows all project comments in a **comments list** and allows you to set comment display preferences. ## Create comments Context: Arcweave docs > Project Items > Comments > Create comments To create a comment: 1. Do either of the following: - **Right-click** an empty area of the current board and select **Create > Comment** from the menu. - **Drag and drop** the **New comment** icon (located at the bottom menu) onto an empty area of the board. ![Arcweave's project environment. An orange arrow shows how to drag a new comment using the "new comment" icon, at the bottom menu.](https://docs.arcweave.com/assets/comments-drag.Cmgj1YXP.png) 2. Type your comment. 3. Click **Post** or press **Ctrl/Cmd + Enter**. Creating a comment also places a **comment pin** on the board, marking the location of the comment thread. The comment pin has the form of a speech bubble icon. ## Open comments Context: Arcweave docs > Project Items > Comments > Open comments To open a comment and its thread (to reply, edit, or resolve the comment), do either of the following: - Click the comment pin in its board. - Click the comment in the comments list. ![Arcweave's project environment. Two orange arrows point at a comment pin in the board and at the comment in the sidebar. Clicking on either opens the comment.](https://docs.arcweave.com/assets/comments-open.CKSZB69L.png) > ✅ Clicking a comment in the comments list scrolls the board to its corresponding pin and opens the comment thread. ## Reply to comments Context: Arcweave docs > Project Items > Comments > Reply to comments To reply to a comment: 1. [Open the comment](https://docs.arcweave.com/project-items/comments#open-comments). 2. Click the **Reply text field**, next to your [account photo](https://docs.arcweave.com/account/overview#account-photo) and type your comment. 3. Click the **Reply button**. ## Select comments Context: Arcweave docs > Project Items > Comments > Select comments Comment pins behave like other board entities: they can be selected and moved freely. Clicking a comment pin selects the comment and also expands the full thread of replies. To select multiple comment pins or combine them with other items, see [Select board items](https://docs.arcweave.com/project-tools/interface/mouse-actions#select-board-items). ## Move comments Context: Arcweave docs > Project Items > Comments > Move comments To move a comment do either of the following: - Drag the comment pin with your mouse. - [Select](https://docs.arcweave.com/project-items/comments#select-comments), cut, and paste the comment elsewhere, using the shortcuts **Ctrl/Cmd + X** and **Ctrl/Cmd + V**. ## Resolve comments Context: Arcweave docs > Project Items > Comments > Resolve comments To mark a comment thread as resolved: 1. [Open the comment](https://docs.arcweave.com/project-items/comments#open-comments). 2. Click the **✔** (checkmark icon) at the top right of the comment. By default, pins of resolved threads are hidden. You can [show or hide them using the settings](https://docs.arcweave.com/project-items/comments#show-resolved-comments) in the comments sidebar. ## Delete comments Context: Arcweave docs > Project Items > Comments > Delete comments To delete a comment, you must delete its pin. Do either of the following: - [Select the comment pin](https://docs.arcweave.com/project-items/comments#select-comments) and press **Delete** or **Backspace**. - Right-click the pin and select **Delete selection** from the context menu. > ⚠️ Deleted comments cannot be restored with undo or [History](https://docs.arcweave.com/project-tools/history). > ✅ If a comment is no longer relevant, consider [resolving](https://docs.arcweave.com/project-items/comments#resolve-comments) it instead of deleting it. Resolved comments remain in the project and can be reopened at any time. ## User mentions Context: Arcweave docs > Project Items > Comments > User mentions Users collaborating in a project can **mention each other in comments**. ![Animated GIF demonstrating the user mentions in comments.](https://docs.arcweave.com/assets/user-mentions.CS8t46iI.gif) To mention a user that already has access to a project: 1. Create a comment or comment reply. 2. Type the `@` character and continue typing the desired username. 3. Select the username from the available list. Mentioned users get an email notification. Email notifications can be configured in the [email notification settings](https://docs.arcweave.com/project-items/comments#email-notification-settings). ## Comment notifications Context: Arcweave docs > Project Items > Comments > Comment notifications When a comment is added to a project: - **Board**: The comment's pin displays an **unread comment badge** (a dot indicating it hasn't been viewed). - **Comments list**: An **unread comment badge** also appears next to the comment. - **Email**: Workspace and project owners, editors, and commenters receive an **email notification**. Notifications include new comments, replies, mentions, and comment resolution updates. To adjust comment notification settings, click the **comment notifications** icon at the top-left of the comment sidebar. ### Email notification settings Context: Arcweave docs > Project Items > Comments > Comment notifications > Email notification settings By default, users receive email notifications for **all comments**. They can limit email notifications to **mentions and replies only**. To change your email notification preferences: 1. Click the **Comments** icon in the top-right menu to open the comment sidebar. 2. Click the **Comment notifications** icon at the top-left of the sidebar. 3. Choose one of the following options: - **All comments** - **Mentions and replies only** - **None** > ℹ️ Users who have not yet visited the project will only receive notifications for comments in which they are mentioned. ### Mark comments as read Context: Arcweave docs > Project Items > Comments > Comment notifications > Mark comments as read To mark all comments as read and remove **unread comment badges**: 1. Click the **Comments** icon in the top-right menu to open the comment sidebar. 2. Click the **Comment notifications** icon at the top-left of the sidebar. 3. Click **Mark all comments as read**. ## Filters Context: Arcweave docs > Project Items > Comments > Filters To filter comments, click the **Filters** icon at the top-right of the comments sidebar and enable any of the following options. ### Show resolved comments Context: Arcweave docs > Project Items > Comments > Filters > Show resolved comments Enable this option to display resolved comments and their pins, both on the board and in the sidebar. This option is disabled by default. ### Show only comments I am involved in Context: Arcweave docs > Project Items > Comments > Filters > Show only comments I am involved in Enable this option to display only comments you are involved in, both on the board and in the comments list: - Comments [created](https://docs.arcweave.com/project-items/comments#create-comments) by you - Comments with [replies](https://docs.arcweave.com/project-items/comments#reply-to-comments) by you - Comments that [mention](https://docs.arcweave.com/project-items/comments#user-mentions) you ### Show only current board comments Context: Arcweave docs > Project Items > Comments > Filters > Show only current board comments Enable this option to display only comments that exist on the current board. # Project tools Source: https://docs.arcweave.com/project-tools/overview Section: Project Tools Description: Overview of Arcweave's project tools, including the interface, settings, Play Mode, search, history, localization, AI tools, sharing, and export As already mentioned, a [project](https://docs.arcweave.com/workspaces/projects) holds the structure and content of your interactive story. This section includes a complete guide of the [project interface](https://docs.arcweave.com/project-tools/interface/overview) and covers the tools Arcweave provides for the design, testing, and integration of your projects: - [Keyboard shortcuts](https://docs.arcweave.com/project-tools/interface/keyboard-shortcuts): Quick access to common actions throughout the interface. - [Project settings](https://docs.arcweave.com/project-tools/settings): Configure the grid, spell checking, input device, board renderer, and AI settings, and view project properties such as the project hash and item count. - [Icon library](https://docs.arcweave.com/project-tools/icon-library): A built-in set of icons to use as element and component covers. - [Rich text](https://docs.arcweave.com/project-tools/rich-text): Format text in elements, labels, notes, and rich text field attributes. - [Mentions](https://docs.arcweave.com/project-tools/mentions): Link to components and boards from element, note, label, and rich text attribute text. - [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview): Preview your project's flow in an interactive player. - [Search](https://docs.arcweave.com/project-tools/search): Quickly locate boards, elements, notes, and more. - [History](https://docs.arcweave.com/project-tools/history): View and restore previous versions of your project. - [Localization](https://docs.arcweave.com/project-tools/localization): Translate your project into multiple languages. - [AI tools](https://docs.arcweave.com/project-tools/ai-features/overview): Generate or refine content using built-in AI assistance. - [Share](https://docs.arcweave.com/project-tools/share): Invite collaborators and set access permissions. - [Export](https://docs.arcweave.com/project-tools/export): Output your project data for use in game engines or for documentation. - [Troubleshooting](https://docs.arcweave.com/project-tools/troubleshooting): Diagnose common editor issues, such as slow board performance. # Project interface Source: https://docs.arcweave.com/project-tools/interface/overview Section: Project Tools Description: Overview of the Arcweave project interface, including the top menu, bottom menu, left sidebar, and layout on small screens This section is a reference guide to Arcweave's project interface. It catalogs all UI areas and menus of the project environment, explaining what each one does and how it supports your workflow. You can look up what you're searching for by browsing the following interface areas: ## Top menu Context: Arcweave docs > Project Tools > Project interface > Top menu ![The Arcweave project environment with an orange rectangle highlighting the top menu.](https://docs.arcweave.com/assets/castle-top-menu.DQtyWvSz.png) The [top menu](https://docs.arcweave.com/project-tools/interface/top-menu) provides access to key project actions, settings, and tools. ## Bottom menu Context: Arcweave docs > Project Tools > Project interface > Bottom menu ![The Arcweave project environment with an orange rectangle highlighting the bottom menu.](https://docs.arcweave.com/assets/castle-bottom-menu.Cjn8g9lw.png) The [bottom menu](https://docs.arcweave.com/project-tools/interface/bottom-menu) allows you to create project items and switch between Pan and Select mode (on the left), and to adjust your board view with zooming and access help resources (on the right). ## Left sidebar Context: Arcweave docs > Project Tools > Project interface > Left sidebar ![The Arcweave project environment with an orange rectangle highlighting the left sidebar.](https://docs.arcweave.com/assets/castle-sidebar.DNtBNczK.png) The [sidebar on the left side](https://docs.arcweave.com/project-tools/interface/left-sidebar) of your window provides access to important items of your project: components, assets, boards, and variables. ## Responsive interface Context: Arcweave docs > Project Tools > Project interface > Responsive interface On narrow screens, Arcweave rearranges these areas to leave more room for the board: - The top menu splits into two dropdown menus, positioned on the left and right. The **Workspace** button and **Play Mode** stay visible on the left, and your profile stays visible on the far right. - The left sidebar starts collapsed and can be opened with the chevron tab at the left edge. - The item-creation tools open from a **+** button at the bottom left. - The help and board-view tools expand vertically from the chevron button at the bottom right. The same permission and plan restrictions apply in both the desktop and responsive layouts. Some desktop controls, such as the Pan/Select icon, History, and the item count, are not shown in the responsive layout. # Project top menu Source: https://docs.arcweave.com/project-tools/interface/top-menu Section: Project Tools > Interface Description: The project top menu with Play Mode, settings, export, sharing, collaborators, Design Assistant, history, localization, comments, and search ![The Arcweave project environment with an orange rectangle highlighting the top menu.](https://docs.arcweave.com/assets/castle-top-menu.DQtyWvSz.png) The top menu, from left to right has the following items: ## Workspace button Context: Arcweave docs > Project Tools > Interface > Project top menu > Workspace button Click the **Workspace** button to exit the project and return to your [workspace](https://docs.arcweave.com/workspaces/overview). ## Project & board names Context: Arcweave docs > Project Tools > Interface > Project top menu > Project & board names Click the name of your project or the name of the currently open [board](https://docs.arcweave.com/project-items/boards) to rename either. Renaming requires the **Edit projects** permission. > ℹ️ You can also [rename a project from its thumbnail](https://docs.arcweave.com/workspaces/projects#rename-projects), in the Projects section and rename a board from the [Boards section](https://docs.arcweave.com/project-items/boards) in the project's left sidebar. ## Play Mode button Context: Arcweave docs > Project Tools > Interface > Project top menu > Play Mode button Click the **Play icon** to open the project's [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview) in a new browser tab, starting from the element set with **Play Mode > Set Play Mode start** in the element's context menu. If you are viewing a translation, Play Mode opens in the same language. ## Project Settings Context: Arcweave docs > Project Tools > Interface > Project top menu > Project Settings Click the **cog icon** to open the [Project Settings](https://docs.arcweave.com/project-tools/settings) menu. This control requires the **Edit projects** permission. ## Export project Context: Arcweave docs > Project Tools > Interface > Project top menu > Export project Click the **Export icon** to open the [Export](https://docs.arcweave.com/project-tools/export) modal. This control requires the **Export projects** permission. ## Share project Context: Arcweave docs > Project Tools > Interface > Project top menu > Share project Click the **Share button** to open the [Share](https://docs.arcweave.com/project-tools/share) modal. ## Collaborators Context: Arcweave docs > Project Tools > Interface > Project top menu > Collaborators The collaborator avatars show other users currently working in the project. Click an avatar to move to that collaborator's current board position when their cursor location is available. ## Item count Context: Arcweave docs > Project Tools > Interface > Project top menu > Item count In Basic workspaces, projects show how many [counted items](https://docs.arcweave.com/workspaces/billing-plans#additional-information) have been used from the 200-item limit. Click the item count to open **Project item limit**, which shows how many items are used and how many are left. Users with the **Manage billing** permission can click **Unlock unlimited items** or **See plans** to [upgrade the workspace](https://docs.arcweave.com/workspaces/billing-plans#upgrade-workspace-plan); other users are asked to contact a workspace admin. ## Design Assistant Context: Arcweave docs > Project Tools > Interface > Project top menu > Design Assistant Click the **stars icon** to open the [Design Assistant](https://docs.arcweave.com/project-tools/ai-features/design-assistant). > ℹ️ This control is shown to logged-in users who can edit the project when AI is enabled and supported for the workspace. ## History Context: Arcweave docs > Project Tools > Interface > Project top menu > History Click the **clock icon** to open [History](https://docs.arcweave.com/project-tools/history). > ℹ️ History is available on Team workspaces; on other plans, the control opens an upgrade prompt. The control is shown to logged-in users with project editing permission. ## Localization Context: Arcweave docs > Project Tools > Interface > Project top menu > Localization Click the **languages icon** to choose a locale or manage [Localization](https://docs.arcweave.com/project-tools/localization). > ℹ️ Team workspaces can manage locales and translations; on other plans, the control opens an upgrade prompt. > ℹ️ Importing localization data requires project editing permission. ## Comments Context: Arcweave docs > Project Tools > Interface > Project top menu > Comments Click the **dialogue icon** to open the project's [Comments](https://docs.arcweave.com/project-items/comments). This control requires permission to comment on the project. ## Search Context: Arcweave docs > Project Tools > Interface > Project top menu > Search Click the **magnifying glass icon** to open the project's [Search](https://docs.arcweave.com/project-tools/search). ## User icon Context: Arcweave docs > Project Tools > Interface > Project top menu > User icon Click on the **user icon** (the user avatar) to open a menu with your email address, **My Account** (your [Account](https://docs.arcweave.com/account/overview) settings), and **Logout**. This icon is accessible from the [workspace interface](https://docs.arcweave.com/workspaces/overview) as well. ## Top menu on small screens Context: Arcweave docs > Project Tools > Interface > Project top menu > Top menu on small screens On narrow screens, Arcweave condenses the top menu into two dropdowns while keeping the **Workspace** button, **Play Mode**, and the profile menu visible: - The **menu icon** on the left contains the project and board names, Project Settings, Export, and Share. The items shown still depend on your permissions. - The **double-chevron icon** on the right contains collaborators, Design Assistant, Localization, Comments, and Search. History and the item count are part of the desktop top menu and are not currently included in the condensed mobile dropdowns. # Project bottom menu Source: https://docs.arcweave.com/project-tools/interface/bottom-menu Section: Project Tools > Interface Description: The project bottom menu for adding elements, jumpers, branches, notes, and comments, plus pan, select, and zoom controls ![The Arcweave project environment with an orange rectangle highlighting the bottom menu.](https://docs.arcweave.com/assets/castle-bottom-menu.Cjn8g9lw.png) The [bottom menu](https://docs.arcweave.com/project-tools/interface/bottom-menu) allows you to create project items and switch between Pan and Select mode (on the left), and to adjust your board view with zooming and access help resources (on the right). The item icons require the **Edit projects** permission, except the comment icon, which requires permission to comment on the project. ## Element icon Context: Arcweave docs > Project Tools > Interface > Project bottom menu > Element icon Drag into empty board space to create a new [element](https://docs.arcweave.com/project-items/elements). ## Jumper icon Context: Arcweave docs > Project Tools > Interface > Project bottom menu > Jumper icon Drag into empty board space to create a new [jumper](https://docs.arcweave.com/project-items/jumpers). ## Branch icon Context: Arcweave docs > Project Tools > Interface > Project bottom menu > Branch icon Drag into empty board space to create a new [branch](https://docs.arcweave.com/project-items/branches). ## Note icon Context: Arcweave docs > Project Tools > Interface > Project bottom menu > Note icon Drag into empty board space to create a new [note](https://docs.arcweave.com/project-items/notes). ## Comment icon Context: Arcweave docs > Project Tools > Interface > Project bottom menu > Comment icon Drag into empty board space to create a new [comment](https://docs.arcweave.com/project-items/comments). ## Pan/Select icon Context: Arcweave docs > Project Tools > Interface > Project bottom menu > Pan/Select icon Click the **hand icon** to toggle between the following modes. This control is available to users with the **Edit projects** permission: - **Pan mode**: Click and drag to move around the board. - **Select mode**: Click to select items, or click and drag from empty board space to draw a [selection rectangle](https://docs.arcweave.com/project-tools/interface/mouse-actions#select-board-items). ## Zoom option icons Context: Arcweave docs > Project Tools > Interface > Project bottom menu > Zoom option icons - **Fit to screen**: Adjusts the zoom so that the selected items, or the whole board if nothing is selected, fit the window. - **Enter full screen**: Expands the board to fill your entire screen for less distractions. - **Zoom in**: Increases magnification for closer inspection of board details. - **Zoom out**: Decreases magnification for a broader overview. - **Current zoom**: Displays the current zoom percentage. Click to reset zoom to 100%. ## Info button Context: Arcweave docs > Project Tools > Interface > Project bottom menu > Info button Click the **Info button** (the icon with a question mark) to open a helpful menu with quick access to support and learning resources: - **What's new**: Opens Arcweave's latest product updates. - **Shortcuts / Help**: Opens a dialog that lists keyboard shortcuts. See [Keyboard shortcuts](https://docs.arcweave.com/project-tools/interface/keyboard-shortcuts) for the complete list. - **Documentation**: Takes you to Arcweave's official documentation site for in-depth guides and references. - **Video tutorials**: Opens the [Arcweave YouTube playlist](https://www.youtube.com/playlist?list=PLP2s5PcDiBdbJUFiw8gu8gK1IyFboWxFH) featuring step-by-step video tutorials. - **Ask us on Discord**: Join the [Arcweave Discord server](https://discord.com/invite/atVXxAK) to ask questions, get support, or connect with the community. ## Bottom tools on small screens Context: Arcweave docs > Project Tools > Interface > Project bottom menu > Bottom tools on small screens On narrow screens, the two groups are collapsed and the Pan/Select icon is not shown: - Tap the **+** button at the bottom left to open the item-creation tray. Drag an item icon from the tray onto the board. Tap the tray handle or swipe it down to close it. - Tap the **chevron** button at the bottom right to show or hide Help, Fit to screen, Full screen, Zoom in, Zoom out, and the current zoom percentage. # Project left sidebar Source: https://docs.arcweave.com/project-tools/interface/left-sidebar Section: Project Tools > Interface Description: The project left sidebar with the Components and Assets tabs, the Boards section with board outlines, and global variables ![The Arcweave project environment with an orange rectangle highlighting the left sidebar.](https://docs.arcweave.com/assets/castle-sidebar.DNtBNczK.png) The [sidebar on the left side](https://docs.arcweave.com/project-tools/interface/left-sidebar) of your Arcweave workspace gives you quick access to essential project items. It is divided into two main sections: the top part for reusable items and the bottom part for structural navigation and data. ## Sidebar top Context: Arcweave docs > Project Tools > Interface > Project left sidebar > Sidebar top The upper half of the left sidebar contains two tabs: ### Components Context: Arcweave docs > Project Tools > Interface > Project left sidebar > Sidebar top > Components The **Components** tab displays a list of all [components](https://docs.arcweave.com/project-items/components) in your project, organized in folders. Right-click a component and select **Copy link** to share a link to its dialog. See [Copy a component link](https://docs.arcweave.com/project-items/components#copy-a-component-link). ### Assets Context: Arcweave docs > Project Tools > Interface > Project left sidebar > Sidebar top > Assets The **Assets** tab lists all imported media files, such as images, audio, and videos. Use this area to upload, generate, replace, organize in folders, preview, and manage references for your [assets](https://docs.arcweave.com/project-items/assets/overview) before attaching them to elements or components. ## Sidebar bottom Context: Arcweave docs > Project Tools > Interface > Project left sidebar > Sidebar bottom The lower half of the sidebar helps you navigate and organize your project's boards and global variables: ### Boards Context: Arcweave docs > Project Tools > Interface > Project left sidebar > Sidebar bottom > Boards This section shows all the [boards](https://docs.arcweave.com/project-items/boards) in your project organized in folders. Expand a board to see an outline of its contents. Right-click a board or an element listed beneath it and select **Copy link** to share that destination. Board folders do not have this action. See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position) for link behavior and access requirements. #### Board contents Context: Arcweave docs > Project Tools > Interface > Project left sidebar > Sidebar bottom > Boards > Board contents Under each board, items are listed in this order: 1. [Elements](https://docs.arcweave.com/project-items/elements), in the board's element order. You can still drag elements to reorder them. Under each element are its outgoing [connections](https://docs.arcweave.com/project-items/connections), in output order: the order its choices appear in Play Mode. 2. [Branches](https://docs.arcweave.com/project-items/branches). Under each branch are the connections leaving its conditions, tagged `if`, `elseif`, or `else`. Conditions without an output connection are not listed. 3. [Jumpers](https://docs.arcweave.com/project-items/jumpers). 4. [Notes](https://docs.arcweave.com/project-items/notes). Rows are named as follows: - **Connections** show their [label](https://docs.arcweave.com/project-items/labels). An unlabelled connection shows the name of its target, in grey. - **Branches** show their `if` condition, or **Empty condition**. - **Jumpers** show the name of the element they point to, or **Empty jumper**. - **Notes** show their first line of text, or **Empty note**. - **Elements** show their title, or the start of their content if they have no title, or **Empty element**. Click a row, or focus it and press **Enter** or **Space**, to zoom the board to that item. A connection row zooms to the connection's label. Elements and branches with connections have a chevron for showing or hiding their connections. They start collapsed. As with boards and folders, collapse state is saved for each user, so expanding an item doesn't change what your collaborators see. When you work in a language other than the main one, elements and labelled connections show their [translation status](https://docs.arcweave.com/project-tools/localization#translation-status). Right-click a labelled connection to [set its status](https://docs.arcweave.com/project-tools/localization#set-label-status). ### Global variables Context: Arcweave docs > Project Tools > Interface > Project left sidebar > Sidebar bottom > Global variables At the very bottom of the sidebar, you'll find the **Global variables** button. Clicking it opens the [**Global variable dialog**](https://docs.arcweave.com/project-items/variables/global). ## Sidebar on small screens Context: Arcweave docs > Project Tools > Interface > Project left sidebar > Sidebar on small screens At viewport widths of 768 pixels or less, the sidebar starts collapsed over the board. Use the chevron tab on the left edge to open or close it. Its **Components**, **Assets**, **Boards**, and **Global variables** sections work the same as in the desktop layout. # Mouse actions Source: https://docs.arcweave.com/project-tools/interface/mouse-actions Section: Project Tools > Interface Description: Mouse actions for creating, editing, selecting, panning, and zooming board items in Arcweave projects Arcweave is designed for mouse-driven interaction. Aside from text entry, all actions in a project can be performed with the mouse. > ✅ For efficiency, Arcweave also provides [keyboard shortcuts](https://docs.arcweave.com/project-tools/interface/keyboard-shortcuts); especially useful to avoid unnecessary back-and-forth between keyboard and mouse. The following desktop mouse actions let you create and edit items or move around the board. See [Select board items](https://docs.arcweave.com/project-tools/interface/mouse-actions#select-board-items) for selection controls. On touch devices, dragging empty board space pans the board. | Mouse action | Result | | :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | | Double-click in empty board area | Create element | | Double-click element / branch / note | Edit | | Drop end of new connection in empty board area | Open a menu to create a connected [element, jumper, or branch](https://docs.arcweave.com/project-items/connections#with-drag-and-drop) there | | Double-click connection or its label | Add or edit the connection's [label](https://docs.arcweave.com/project-items/labels) | | Drag the board in Pan mode | Pan the board | | Middle-button drag | Pan the board from either cursor mode | | Hold Space + left-button drag | Pan the board from either cursor mode | | Mouse wheel | Zoom when [Input device](https://docs.arcweave.com/project-tools/settings#input-device) is set to Mouse; pan when it is set to Trackpad | | Ctrl/Cmd + mouse wheel | Zoom | | Click component | Open component for editing | | Right-click item | Open item's context menu | | Drag a connection's path handle | [Reshape the connection](https://docs.arcweave.com/project-items/connections#edit-connection-paths) | | Double-click a connection's path handle | Restore the connection's automatic path | | Right-click empty board area | Open the board menu: **Create** items, **Paste** or **Paste as jumper** at that point, or open **Board Properties** | Creating and editing board items, except comments, requires the **Edit projects** permission. Users without it pan the board by dragging it, in either cursor mode. Item context menus include **Copy**, which copies the selected items like **Ctrl/Cmd + C**. To paste them where you right-clicked, choose **Paste** in the empty board area's menu. To share an element, connection, branch, jumper, or note, select that item alone, right-click it, and choose **Copy link**. See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position) for all supported menu locations and access requirements. ## Select board items Context: Arcweave docs > Project Tools > Interface > Mouse actions > Select board items The same selection controls apply to [elements](https://docs.arcweave.com/project-items/elements), [connections](https://docs.arcweave.com/project-items/connections), [branches](https://docs.arcweave.com/project-items/branches), [jumpers](https://docs.arcweave.com/project-items/jumpers), [notes](https://docs.arcweave.com/project-items/notes), and [comment pins](https://docs.arcweave.com/project-items/comments#select-comments). You can include different item types in the same selection. Click an item to replace the current selection with that item. To select multiple items one at a time, hold **Shift** or **Ctrl/Cmd** while clicking each one. Clicking an already selected item with one of these keys removes it from the selection. To select items with a rectangle, switch to [Select mode](https://docs.arcweave.com/project-tools/interface/bottom-menu#pan-select-icon), then click and drag from empty board space. The rectangle selects every item it touches, even partially: | Mouse action | Result | | :------------------------- | :--------------------------------------------------------------- | | Drag without modifier keys | Replace the selection with items touched by the rectangle | | Shift + drag | Add items touched by the rectangle to the current selection | | Ctrl / Cmd + drag | Remove items touched by the rectangle from the current selection | # Keyboard shortcuts Source: https://docs.arcweave.com/project-tools/interface/keyboard-shortcuts Section: Project Tools > Interface Description: Keyboard shortcuts for navigation, selection, element creation, connections, text editing, and Play Mode in Arcweave projects Arcweave is primarily designed for [mouse-driven interaction](https://docs.arcweave.com/project-tools/interface/mouse-actions), but keyboard shortcuts help streamline common actions and reduce context switching between mouse and keyboard. The tables below list the available keyboard shortcuts, what each one does, and which permission is needed to use them. Board shortcuts do not work while a dialog or menu is open. ## Global controls Context: Arcweave docs > Project Tools > Interface > Keyboard shortcuts > Global controls | Shortcut | Action | Required permission | | :------------------- | :----------------------------------------------------------------------------------------- | :-------------------- | | Ctrl/Cmd + Z | Undo | ✏️ Edit projects | | Ctrl/Cmd + Shift + Z | Redo | ✏️ Edit projects | | Ctrl/Cmd + F | [Search](https://docs.arcweave.com/project-tools/search) | 👀 View projects list | | Ctrl/Cmd + A | Select all board items | ✏️ Edit projects | | Ctrl/Cmd + C | Copy selected item(s) | ✏️ Edit projects | | Ctrl/Cmd + X | Cut selected item(s) | ✏️ Edit projects | | Ctrl/Cmd + V | Paste copied item(s) | ✏️ Edit projects | | Ctrl/Cmd + Shift + V | Paste single copied [element](https://docs.arcweave.com/project-items/elements) as [jumper](https://docs.arcweave.com/project-items/jumpers) | ✏️ Edit projects | | Ctrl/Cmd + Shift + F | Fit to screen | 👀 View projects list | ## Navigation & view Context: Arcweave docs > Project Tools > Interface > Keyboard shortcuts > Navigation & view | Shortcut | Action | Required permission | | :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- | :-------------------- | | + | Zoom in | 👀 View projects list | | - | Zoom out | 👀 View projects list | | Space + drag with mouse | Pan board | 👀 View projects list | | Tab (no selection) | Select the item nearest to the screen center and move the view to it | ✏️ Edit projects | | Tab (while editing element) | Switch between [editing element](https://docs.arcweave.com/project-items/elements#edit-elements) title and content | ✏️ Edit projects | | Ctrl/Cmd + Arrow key | With one board item selected, select the nearest item in that direction; otherwise, select the item nearest to the screen center | ✏️ Edit projects | | Esc (while editing a board item) | Exit editing mode | ✏️ Edit projects | | Esc (no editing in progress) | Clear the selection | ✏️ Edit projects | ## Selection & movement Context: Arcweave docs > Project Tools > Interface > Keyboard shortcuts > Selection & movement | Shortcut | Action | Required permission | | :------------------------------------------------- | :---------------------------------------------------------------------------------- | :-------------------- | | Shift/Ctrl/Cmd + click board item | Add or subtract item from selection | ✏️ Edit projects | | Shift + drag empty board space (in Select mode) | Add items to selection | ✏️ Edit projects | | Ctrl/Cmd + drag empty board space (in Select mode) | Subtract items from selection | ✏️ Edit projects | | Arrow key (no selection) | Pan board to arrow direction | 👀 View projects list | | Arrow key (with selection) | Nudge selection to arrow direction | ✏️ Edit projects | | Shift + Arrow key (with selection) | Nudge selection in larger steps (20 pixels instead of 1, unless Snap to grid is on) | ✏️ Edit projects | | Delete/Backspace (while items are selected) | Delete selected items | ✏️ Edit projects | ## Element creation & connection Context: Arcweave docs > Project Tools > Interface > Keyboard shortcuts > Element creation & connection | Shortcut | Action | Required permission | | :-------------------------------------------------------- | :------------------------------------------------------------------------- | :------------------ | | Ctrl + Alt/Option/Cmd + Arrow key (with element selected) | Create a [connected](https://docs.arcweave.com/project-items/connections) element in that direction | ✏️ Edit projects | ## Text editing Context: Arcweave docs > Project Tools > Interface > Keyboard shortcuts > Text editing | Shortcut | Action | Required permission | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :------------------ | | @... (while typing in rich text) | [Mention component or board](https://docs.arcweave.com/project-tools/mentions) | ✏️ Edit projects | | @... (while typing in [Arcscript](https://docs.arcweave.com/project-items/arcscript)) | Mention element as argument of [`visits` function](https://docs.arcweave.com/project-items/arcscript#visits) | ✏️ Edit projects | | Ctrl/Cmd + B (while editing rich text) | Bold | ✏️ Edit projects | | Ctrl/Cmd + I (while editing rich text) | Italic | ✏️ Edit projects | | Ctrl/Cmd + U (while editing rich text) | Underline | ✏️ Edit projects | | Ctrl/Cmd + Shift + S (while editing rich text) | Strikethrough | ✏️ Edit projects | | Ctrl/Cmd + Shift + B (while editing [element](https://docs.arcweave.com/project-items/elements) content or a [rich text field attribute](https://docs.arcweave.com/project-items/attributes#rich-text-field)) | Toggle blockquote | ✏️ Edit projects | | Ctrl/Cmd + Shift + C (while editing [element](https://docs.arcweave.com/project-items/elements) content or a [label](https://docs.arcweave.com/project-items/labels)) | Toggle [Arcscript segment](https://docs.arcweave.com/project-items/arcscript#arcscript-segments) | ✏️ Edit projects | | Enter (with one [element](https://docs.arcweave.com/project-items/elements), [branch](https://docs.arcweave.com/project-items/branches), [note](https://docs.arcweave.com/project-items/notes), or [connection](https://docs.arcweave.com/project-items/connections) selected) | Open selected item for editing (for a connection, edit its [label](https://docs.arcweave.com/project-items/labels)) | ✏️ Edit projects | | Enter (while editing a [branch](https://docs.arcweave.com/project-items/branches) condition) | Add `else` condition to the branch | ✏️ Edit projects | | Ctrl/Cmd + Enter (while editing a [branch](https://docs.arcweave.com/project-items/branches) condition) | Add `elseif` condition to the branch | ✏️ Edit projects | | Tab / Shift + Tab (while editing a [branch](https://docs.arcweave.com/project-items/branches) condition) | Move to the next / previous condition | ✏️ Edit projects | ## Play Mode Context: Arcweave docs > Project Tools > Interface > Keyboard shortcuts > Play Mode | Shortcut | Action | Required permission | | :------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :------------------ | | Tab (while editing in the [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor)) | Insert 2 spaces at the cursor, or indent all selected lines by 2 spaces | ✏️ Edit projects | | Shift + Tab (while editing in the Style Editor) | Remove 2 leading spaces from the current line or from all selected lines | ✏️ Edit projects | | Esc (while [editing content in Play Mode](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#edit-content-in-play-mode)) | Save edits and exit edit mode | ✏️ Edit projects | | Tab (while editing element content in Play Mode edit mode) | Move focus to the first option label | ✏️ Edit projects | | Shift + Tab (while editing element content in Play Mode edit mode) | Move focus to the last option label | ✏️ Edit projects | | Tab (while editing an option label in Play Mode edit mode) | Move focus to the next option label, or back to element content from the last option | ✏️ Edit projects | | Shift + Tab (while editing an option label in Play Mode edit mode) | Move focus to the previous option label, or to element content from the first option | ✏️ Edit projects | # Project Settings Source: https://docs.arcweave.com/project-tools/settings Section: Project Tools Description: Project settings for grid, spell checking, input device, board renderer, and AI, plus project properties like hash and word count To access your project's **settings**, click the **cog icon** (**Project Settings**) on the left side of the top menu. The cog icon is available to users who can edit the project (owners and editors). ![Arcweave's project environment, with an orange arrow pointing at the cog icon, in the top menu.](https://docs.arcweave.com/assets/settings_cog.CmlNUThz.png) The **Project Settings** menu provides the following two sections: - [Configurable settings](https://docs.arcweave.com/project-tools/settings#configurable-settings): - Show grid - Snap to grid - Spell checking - Input device - Board renderer - AI settings - [Properties](https://docs.arcweave.com/project-tools/settings#properties) ## Configurable settings Context: Arcweave docs > Project Tools > Project Settings > Configurable settings Configure these settings to affect how you work inside the editor. ### Show grid Context: Arcweave docs > Project Tools > Project Settings > Configurable settings > Show grid Toggles a background grid of dots on the board to help visually align elements. The dots fade as you zoom out below 100% and disappear at 25% zoom. ### Snap to grid Context: Arcweave docs > Project Tools > Project Settings > Configurable settings > Snap to grid Toggles board item snapping to the nearest grid point, for precise placement and alignment. > ✅ **Snap to grid** functions independently from **Show grid**: snapping can remain active even if the grid itself is hidden. ### Spell checking Context: Arcweave docs > Project Tools > Project Settings > Configurable settings > Spell checking Activates your browser's built-in spell checker within Arcweave, helping you identify and correct typos as you type. > ℹ️ To use this feature, ensure spell checking is also enabled in your browser's settings. ### Input device Context: Arcweave docs > Project Tools > Project Settings > Configurable settings > Input device Select your input device: - **Auto**: Automatically detects mouse-only and trackpad-only gestures, adjusting the functionality accordingly. The menu shows the currently detected device. - **Mouse**: Optimizes for mouse input. - **Trackpad**: Optimizes for trackpad gestures. > ✅ If you need to scroll within a tall element, switch to **Trackpad** mode and scroll using your mouse wheel or trackpad gesture. ### Board renderer Context: Arcweave docs > Project Tools > Project Settings > Configurable settings > Board renderer Choose which renderer Arcweave uses for boards: - **WebGL**: Best compatibility for most browsers and devices. - **WebGPU**: Preferred on modern browsers with WebGPU support. - **Canvas (Compatibility)**: May be slower; use it when GPU rendering is unavailable. If board panning, zooming, selection, or connection editing feels slow on your current browser or device, try switching to the other GPU renderer. If the selected renderer can't run, Arcweave falls back to the other GPU renderer, then to Canvas. See [Board performance](https://docs.arcweave.com/project-tools/troubleshooting#board-performance). > ℹ️ Refresh the page after changing the board renderer, so the new setting can take effect. > ℹ️ Arcweave stores this preference in your current browser. > ℹ️ For Chrome-specific performance checks, see [Troubleshooting](https://docs.arcweave.com/project-tools/troubleshooting#board-performance). ### AI settings Context: Arcweave docs > Project Tools > Project Settings > Configurable settings > AI settings Use **AI Settings...** to define the visual direction for all [AI-generated images](https://docs.arcweave.com/project-tools/ai-features/image-generator) in the project. This option appears when the workspace's plan includes AI features and AI is enabled for the workspace. The **AI Settings** panel includes two optional ways to guide generated images: - **Image Generation Guidelines**: Enter up to 1,000 characters of instructions describing the desired style, tone, medium, or visual characteristics you want Arcweave to apply to generated images across the project. - **Attached Style References**: Drag image assets from the **Assets** sidebar into this list to use them as visual references. Arcweave uses them to guide palette, mood, lighting, texture, and rendering style. > ℹ️ Attached style references act as style guides by default. They are not reproduced literally unless your prompt explicitly asks for the details shown in them. > ℹ️ If you add attached style references, you can mention one by name in your prompt to guide the result more precisely. ## Properties Context: Arcweave docs > Project Tools > Project Settings > Properties Select **Properties** to open the **Project properties** dialog. It gives access to the following key project information used for integration, sharing, and project management. ### Project hash Context: Arcweave docs > Project Tools > Project Settings > Properties > Project hash ![Arcweave's project environment, with the Project properties panel open and an orange rectangle emphasizing the project hash.](https://docs.arcweave.com/assets/project-hash.BcnLdJ7_.png) #### What is the project hash? Context: Arcweave docs > Project Tools > Project Settings > Properties > Project hash > What is the project hash? The project hash is the unique identifier of a project. You need a project's hash in the following cases: - When [integrating](https://docs.arcweave.com/integrations/overview) with another platform through Arcweave's REST API. - When [embedding](https://docs.arcweave.com/project-tools/share) the project's Play Mode in a webpage. #### Copy the project hash Context: Arcweave docs > Project Tools > Project Settings > Properties > Project hash > Copy the project hash To access and copy the project hash: 1. Click the **Settings icon** (the cog) on the left side of the top menu. 2. Select **Properties**. 3. Locate the **Project hash** and click the **clipboard icon**. Your project's hash is now copied to your system's clipboard. ### Project item count Context: Arcweave docs > Project Tools > Project Settings > Properties > Project item count Shows the total number of each item type within your project: - Boards - Jumpers - Notes - Assets - Elements - Branches - Components - Comments ### Total words Context: Arcweave docs > Project Tools > Project Settings > Properties > Total words Calculates the total number of words across all boards, using element titles, element content, and connection labels. Arcscript blocks are not counted. In localized projects, this count uses the current language. ### Total characters Context: Arcweave docs > Project Tools > Project Settings > Properties > Total characters Calculates the total number of characters across all boards, using element titles, element content, and connection labels. Arcscript blocks are not counted. In localized projects, this count uses the current language. ### Project storage limit Context: Arcweave docs > Project Tools > Project Settings > Properties > Project storage limit Displays the total storage capacity available for your project and the current usage. # Arcweave's icon library Source: https://docs.arcweave.com/project-tools/icon-library Section: Project Tools Description: Use Arcweave's built-in library of over 4,000 game icons as element and component covers Arcweave includes a built-in library of **4,000+ game icons** sourced from [game-icons.net](https://game-icons.net). You can freely use these icons as cover images for your elements and components. ![An Arcweave component with its cover modal open to the Icon Library tab, showing a collection of "knight" icons.](https://docs.arcweave.com/assets/component-icons.DHM2jeqw.png) ## Element covers Context: Arcweave docs > Project Tools > Arcweave's icon library > Element covers To set an icon as an element cover: 1. Right-click the element and select **Cover > Set cover**. 2. In the cover picker that opens, go to the **Icon Library** tab. 3. Browse by category or use the search bar to find the icon you want. ## Component covers Context: Arcweave docs > Project Tools > Arcweave's icon library > Component covers To set an icon as a component cover: 1. In the **Components** section of the sidebar, click a component to open it. 2. Hover over the current cover image and click **Change cover** in the top-right corner. 3. In the cover picker that opens, go to the **Icon Library** tab. 4. Browse or search to select an icon. # Rich text Source: https://docs.arcweave.com/project-tools/rich-text Section: Project Tools Description: Rich text formatting in Arcweave elements, labels, notes, and rich text attributes [Elements](https://docs.arcweave.com/project-items/elements), [labels](https://docs.arcweave.com/project-items/labels), [notes](https://docs.arcweave.com/project-items/notes), and [rich text field attributes](https://docs.arcweave.com/project-items/attributes#rich-text-field) support **rich text formatting**. The available formatting depends on the field. ## Supported formatting Context: Arcweave docs > Project Tools > Rich text > Supported formatting | Field | Bold, italic, underline, strikethrough | Links | Blockquotes | Arcscript segments | | ------------------------- | -------------------------------------- | ----- | ----------- | ------------------ | | Element title | Yes | Yes | No | No | | Element content | Yes | Yes | Yes | Yes | | Connection label | Yes | Yes | No | Yes | | Note content | Yes | Yes | No | No | | Rich text field attribute | Yes | Yes | Yes | No | [Arcscript segments](https://docs.arcweave.com/project-items/arcscript#arcscript-segments) are code blocks used for story logic. Inline code formatting is not supported in any of these fields. Plain **String Field** attributes contain unformatted text and do not support the formatting above. For integrations, see [Rich text in the REST API](https://docs.arcweave.com/rest-api/rich-text). ## Formatting menu Context: Arcweave docs > Project Tools > Rich text > Formatting menu The formatting menu appears above or below the rich text field and displays **context-dependent formatting buttons**. The picture below shows the formatting menu appearing when editing the content of an **element**: ![Arcweave's project environment, while editing an element. An orange arrow and an orange rectangle emphasize the position of the formatting bar above the element content's rich text field.](https://docs.arcweave.com/assets/rich-text-formatting-menu.s-yo582I.png) And this is the formatting menu appearing when editing an **element's title**: ![Arcweave's project environment, while editing an element's title. An orange rectangle emphasizes the position of the formatting bar above the element title's rich text field.](https://docs.arcweave.com/assets/rich-text-formatting-menu-elementtitle.DGWnNKS3.png) Same, when editing a **label**: ![Arcweave's project environment, while editing a label. An orange rectangle emphasizes the position of the formatting bar above the label's rich text field.](https://docs.arcweave.com/assets/rich-text-formatting-menu-label.DhuEyB3y.png) When editing a **note**: ![Arcweave's project environment, while editing a note. An orange rectangle emphasizes the position of the formatting bar above the note's rich text field.](https://docs.arcweave.com/assets/rich-text-formatting-menu-note.CkAZNSTW.png) Finally, this is the formatting menu appearing when editing a **rich text field attribute**: ![Arcweave's project environment, while editing a rich text field attribute. An orange rectangle emphasizes the position of the formatting bar above the rich text field.](https://docs.arcweave.com/assets/rich-text-formatting-menu-attribute.Dcdz3LtH.png) ### Bold, italic, underline, and strikethrough Context: Arcweave docs > Project Tools > Rich text > Formatting menu > Bold, italic, underline, and strikethrough Available in: **element title**, **element content**, **label**, **note**, **rich text field attribute** After selecting your text, click the **Bold**, **Italic**, **Underline**, or **Strikethrough** button in the formatting menu to apply the desired style. ![An element in edit mode. An orange rectangle emphasizes the Bold, Italic, Underline, and Strikethrough buttons in the rich text formatting menu.](https://docs.arcweave.com/assets/element-edit-biu.B1fj9LA5.png) ### Blockquote Context: Arcweave docs > Project Tools > Rich text > Formatting menu > Blockquote Available in: **element content**, **rich text field attribute** Place your cursor in a paragraph and click the **Blockquote** button in the formatting menu to format the paragraph as a blockquote. This helps the text stand out as a quote or callout. ![An element in edit mode. An orange rectangle emphasizes the Blockquote button in the rich text formatting menu. A similar rectangle emphasizes a paragraph formatted as blockquote inside the element's text content.](https://docs.arcweave.com/assets/element-edit-blockquote.DK81b-zG.png) ### Link Context: Arcweave docs > Project Tools > Rich text > Formatting menu > Link Available in: **element title**, **element content**, **label**, **note**, **rich text field attribute** Select text and click the **Link** button in the formatting menu, then type or paste a URL and press **Enter** to turn the text into a link. The button is disabled when no text is selected or inside Arcscript segments. ![An element in edit mode. An orange rectangle emphasizes the Link button in the rich text formatting menu. A second rectangle emphasizes a group of words formatted as a link inside the element's text content.](https://docs.arcweave.com/assets/element-edit-link.DZG9BnWG.png) ### Arcscript Context: Arcweave docs > Project Tools > Rich text > Formatting menu > Arcscript Available in: **element content**, **label** Place the cursor in a paragraph and click the **Arcscript** button in the formatting menu to convert the paragraph into an Arcscript segment. ![An element in edit mode. An orange rectangle emphasizes the Arcscript button in the rich text formatting menu. A similar rectangle emphasizes a paragraph formatted as Arcscript code segment inside the element's text content.](https://docs.arcweave.com/assets/element-edit-arcscript.tIg7kegi.png) ### Translatable Context: Arcweave docs > Project Tools > Rich text > Formatting menu > Translatable Available in: **element content**, **label** When [localization](https://docs.arcweave.com/project-tools/localization#translate-arcscript-segments) is available (Team workspaces), it toggles whether the current Arcscript segment is translatable. The button is enabled only while the cursor is in an Arcscript segment and the project's default language is selected. ![An element in edit mode. An orange rectangle emphasizes the Translatable button in the rich text formatting menu.](https://docs.arcweave.com/assets/element-edit-translatable.DA_jFjzT.png) ## Format rich text Context: Arcweave docs > Project Tools > Rich text > Format rich text To format rich text: 1. Edit an element, note, label, or rich text field attribute. 2. Select some text. 3. Click one of the [formatting menu](https://docs.arcweave.com/project-tools/rich-text#formatting-menu) buttons (or use Arcweave's [keyboard shortcuts](https://docs.arcweave.com/project-tools/interface/keyboard-shortcuts)). ## Markdown formatting Context: Arcweave docs > Project Tools > Rich text > Markdown formatting Arcweave's rich text content supports limited Markdown syntax: - **Italic**: Wrap text in \*_single asterisks_\* or \__single underscores_\_ and it will automatically transform to italic text. - **Bold**: Wrap text in \*\***double asterisks**\*\* or \_\_**double underscores**\_\_ and it will transform to bold text. - **Strikethrough**: Wrap text in \~\~~~double tildes~~\~\~ and it will transform to struck-through text. - **Blockquote**: In fields that support blockquotes, type `>` followed by a space at the start of a paragraph. - **Arcscript segment**: In fields that support Arcscript segments, type ` ``` ` or `~~~` followed by a space at the start of a paragraph. ![Animated demonstration of Markdown syntax transforming into formatted rich text in Arcweave.](https://docs.arcweave.com/assets/rich-text-markdown-syntax.B6xQi0Ws.gif) > ✅ By the way, [Pro and Team](https://docs.arcweave.com/workspaces/billing-plans) workspaces support [exporting your project in Markdown](https://docs.arcweave.com/project-tools/export#export-as-markdown). # Mentions Source: https://docs.arcweave.com/project-tools/mentions Section: Project Tools Description: Mention components and boards in rich text to link them, and create new components directly from a mention Mentions are **links to components and boards** within your Arcweave project. ![Example of mentioning a component by typing the @ character followed by a few letters of the component's name. A list opens, from which the user can choose an existing component or create a new one.](https://docs.arcweave.com/assets/mentions-overview.BgVMv8af.jpg) You can insert mentions while typing in the following fields: - Title or content of [elements](https://docs.arcweave.com/project-items/elements) - [Notes](https://docs.arcweave.com/project-items/notes) - [Rich text attributes](https://docs.arcweave.com/project-items/attributes) - [Connection labels](https://docs.arcweave.com/project-items/labels) In the board, component mentions appear as **orange text** and board mentions as **gold text**. > ℹ️ Inside [Arcscript segments](https://docs.arcweave.com/project-items/arcscript#arcscript-segments) and [branch](https://docs.arcweave.com/project-items/branches) conditions, typing `@` lists **elements** instead, so you can use them as arguments of the [`visits` function](https://docs.arcweave.com/project-items/arcscript#visits). > ℹ️ Mentions are not visually styled in Play Mode; they appear as regular text. > ⚠️ Not to be confused with [user mentions in comments](https://docs.arcweave.com/project-items/comments#user-mentions). ## Benefits of mentions Context: Arcweave docs > Project Tools > Mentions > Benefits of mentions Mentions offer several advantages that improve project navigation and consistency: - **Quick navigation**: Clicking on a mention instantly opens the referenced component or board. - **Auto-updating**: If the referenced item is renamed, all related mentions are automatically updated. - **Distraction-free writing**: You can [create and reference new components](https://docs.arcweave.com/project-tools/mentions#create-new-components) on the fly without breaking your writing flow. ## Create a mention Context: Arcweave docs > Project Tools > Mentions > Create a mention To mention an existing component or board: 1. While typing, type the **`@`** character. 2. Start typing the name of the component or board. 3. Click the correct item in the dropdown list, or move to it with the arrow keys and press **Enter**. > ℹ️ The `@` character opens the list only at the start of a paragraph or after a space or an opening parenthesis `(`. > ⚠️ The **Create "..."** option is highlighted first in the list. Pressing **Enter** without moving to another item creates a new component, even if an existing component matches your text. ![Animated GIF demonstrating how to mention an existing component.](https://docs.arcweave.com/assets/mention.DQykf4Hg.gif) ## Create new components Context: Arcweave docs > Project Tools > Mentions > Create new components Mentions also allow you to create new components as you write. To create one, type `@` followed by the desired name and press **Enter**. Arcweave will automatically create and mention the new component without interrupting your writing flow. > ⚠️ This method creates only components; not boards. > ℹ️ To include spaces in the name, use underscores (`_`). For example, typing `@bronze_key` will create a component named **bronze key**. # Play Mode Source: https://docs.arcweave.com/project-tools/play-mode/overview Section: Project Tools Description: Emulate the player's experience in Arcweave's built-in Play Mode Play Mode runs your Arcweave project as a choose-your-path game, emulating the player's experience. It loads one element per turn and the story progresses choice-by-choice. This process enables structured testing, debugging, and refinement of the narrative flow. > ✅ Story edits update Play Mode. For CSS saved through the REST API or MCP, reload an existing Play Mode tab or open a new one from the editor; see [Save and verify styles](https://docs.arcweave.com/project-tools/play-mode/styling-reference#save-and-verify-styles). ## Breakdown Context: Arcweave docs > Project Tools > Play Mode > Breakdown The following steps describe how Play Mode functions: 1. The game begins at the defined [starting element](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#set-play-mode-start). 2. At each turn, Arcweave renders the content of the current [element](https://docs.arcweave.com/project-items/elements). 3. The current element's [cover](https://docs.arcweave.com/project-items/elements#element-covers) is displayed at the top of the Play Mode window. 4. The [covers](https://docs.arcweave.com/project-items/components#cover) of the current element's components are shown below the element cover. 5. The textual content of the current element appears beneath the components. 6. Arcweave evaluates [branch conditions](https://docs.arcweave.com/project-items/branches) and [label Arcscript](https://docs.arcweave.com/project-items/labels#arcscript-in-labels) to determine the available options. Each option uses the last label on its path that produces text, while the Arcscript of every label on the path is evaluated. See [Labels across branches](https://docs.arcweave.com/project-items/labels#labels-across-branches). 7. Available options appear as clickable **option buttons**. If an option has no label text, the button uses the target element's title, or the beginning of its content if it has no title. 8. If **only one option is available** and its labels produce **no text**, a **blinking arrow** appears instead of an option button. This is checked after branch and label evaluation, so an element with several outgoing connections can also show the arrow. 9. The player progresses the story by clicking an option button or clicking anywhere within the content area, in the case of the blinking arrow. ![A split-screen view of an Arcweave project and its Play Mode, with both sides focusing on the starting element. Orange rectangles and arrows highlight how the element's cover becomes the featured image in Play Mode, and how the connection's label appears as an option button.](https://docs.arcweave.com/assets/play-split-arrows.Bffgc1CY.png) > ℹ️ To let people who are not project collaborators play your project, [make the project or its Play Mode public](https://docs.arcweave.com/project-tools/share#make-a-project-public). ## Play Mode access Context: Arcweave docs > Project Tools > Play Mode > Play Mode access Depending on their role, users fall into two primary role-based categories with respect to Play Mode access and functionality: - Commenters & Visitors - Owners & Editors ### Commenters & Visitors Context: Arcweave docs > Project Tools > Play Mode > Play Mode access > Commenters & Visitors Workspace commenters, project commenters, and project visitors have limited access to Play Mode. They can do the following: - Play through the story - Restart the session - Adjust audio settings - Choose story language (if [translations](https://docs.arcweave.com/project-tools/localization) are available) For each of these features, see [Using Play Mode](https://docs.arcweave.com/project-tools/play-mode/using-play-mode) (next page). > ✅ For a quick overview of roles, see [workspace and project roles](https://docs.arcweave.com/workspaces/roles). ### Owners & Editors Context: Arcweave docs > Project Tools > Play Mode > Play Mode access > Owners & Editors Workspace and project owners and editors enjoy the following Play Mode features: - [Debugger](https://docs.arcweave.com/project-tools/play-mode/debugger): Ability to inspect variable changes and force assign values for testing. - [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor): Ability to change the CSS of the story's Play Mode. - [Edit content in Play Mode](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#edit-content-in-play-mode): Ability to edit the current element's text and its option labels while playtesting, without leaving Play Mode. - [Reorder option buttons](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#reorder-options): Ability to reorder the option buttons of any element. - [Quickstart Play Mode from any element](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#quickstart-play-mode-from-here): Directly playtest any part of the story. ## Style Play Mode Context: Arcweave docs > Project Tools > Play Mode > Style Play Mode Use the [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor) to preview and save custom CSS, or update it through the [REST API](https://docs.arcweave.com/rest-api/css) or [MCP tools](https://docs.arcweave.com/integrations/mcp#style-play-mode). The [Play Mode styling reference](https://docs.arcweave.com/project-tools/play-mode/styling-reference) describes the shared DOM, selectors, defaults, and verification workflow. # Using Play Mode Source: https://docs.arcweave.com/project-tools/play-mode/using-play-mode Section: Project Tools > Play Mode Description: Play your story in Play Mode, set the starting element, choose options, edit content, restart, and change audio and language This page explains how to use **Play Mode**. Access to Play Mode and its features depends on a user's role within the project. For a quick overview of roles, see [Workspace and project roles](https://docs.arcweave.com/workspaces/roles). Unless otherwise noted, all instructions apply to project or workspace owners and editors, who have full access to the project. ## Set Play Mode start Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Set Play Mode start Before running your project in Play Mode, you must define a starting element. To set a starting element: 1. Right-click the desired element. 2. Select **Play Mode > Set Play Mode start**. You can change the starting element at any time by repeating the same action on a different element. > ⚠️ A project can have only one starting element. > ℹ️ There is no option to unset the starting element; setting another element as the Play Mode start replaces it. If you delete the starting element, the project has no starting element until you set a new one. ## Enter Play Mode Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Enter Play Mode To enter Play Mode, click the **Play Mode** button on the top-left of the menu bar. Play Mode opens in a new browser tab. ![An orange arrow pointing at the Play Mode button in the top menu of an Arcweave project.](https://docs.arcweave.com/assets/play-button.Cx3qNU9M.png) If you are working in a [translation](https://docs.arcweave.com/project-tools/localization), Play Mode starts in that language. > ⚠️ Project visitors without access to the board can only enter Play Mode via a **public link**. This occurs when a project has been shared publicly for Play Mode access only. See [Share your project](https://docs.arcweave.com/project-tools/share). ## Quickstart Play Mode from here Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Quickstart Play Mode from here Workspace and project owners and editors can also start Play Mode from any element in the project, ignoring the starting element. To do this: 1. Right-click an element. 2. Select **Play Mode > Quickstart Play Mode from here**. Play Mode opens in a new browser tab, starting from that element. > ⚠️ Quick-starting from an element skips all variable changes and element visits that would normally occur when reaching that element through standard play. ## Continue to the next element Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Continue to the next element Select an option button to continue the story. Arcweave determines the available options by evaluating [branch conditions](https://docs.arcweave.com/project-items/branches) and [label Arcscript](https://docs.arcweave.com/project-items/labels#arcscript-in-labels). If **only one option is available** and its labels produce **no text**, a blinking arrow appears instead of a button. Click the element's content area to continue. This can happen even with several outgoing connections if branch conditions leave only one option. To show a button for a single option, give its path a label that produces text, such as **Continue**. Variable assignments alone do not produce option text. For paths through branches, Arcweave uses the [last label that produces text](https://docs.arcweave.com/project-items/labels#labels-across-branches). ## Reorder options Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Reorder options Workspace and project owners and editors can **reorder an element's clickable options** in Play Mode while [Edit content](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#edit-content-in-play-mode) mode is enabled. To reorder an element's options: 1. Right-click the element on the board. 2. Select **Play Mode > Quickstart Play Mode from here**. 3. Once in Play Mode, press **Edit content** (the **pencil** icon in the top menu). 4. Drag an option by the grip handle on its left, or by its border, to reorder it. Changes are saved automatically. ## Play Mode menu Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Play Mode menu ### Open Play Mode menu Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Play Mode menu > Open Play Mode menu **On desktop**: To open the Play Mode menu, hover your cursor near the top of your browser window. The menu hides a few seconds after your cursor leaves it. To keep it visible, select **Lock Toolbar** from the menu icon (☰) at its left. **On mobile**: In browser windows narrower than 768 pixels, the Play Mode menu is always visible. On other touch screens, tap the top of the screen to show it. ### Functionality Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Play Mode menu > Functionality The Play Mode menu provides access to the following tools and options: - [Restart story](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#restart-story): Resets everything and restarts the story. - **Full screen**: Enters or exits full-screen view. - [Share](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#share-project): Lets you share your project and control its public access. - [Audio](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#control-audio-volume): Controls the playback volume of your project's audio. - [Localization](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#choose-language): Select the story's language (if [Localization](https://docs.arcweave.com/project-tools/localization) is available). - [Edit content](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#edit-content-in-play-mode): Lets you edit the current element's text and option labels while playtesting. - [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor): Lets you style Play Mode's appearance through direct CSS editing. - [Debug](https://docs.arcweave.com/project-tools/play-mode/debugger): Opens the Debugger, where you can inspect the current board, current element, and variable changes. - **Menu** (☰): **Lock Toolbar** keeps the Play Mode menu visible, and **Go to Editor** opens the project's boards in the same tab. **Edit content**, **Style Editor**, and **Debug** are available only to owners and editors. On desktop, the menu icon (☰) and **Share** are hidden from [project visitors](https://docs.arcweave.com/workspaces/roles#project-visitors). On narrow screens, the menu icon (☰) is available to everyone and contains **Restart**; **Edit content**, **Share**, and **Open in Editor** appear according to your permissions. ## Edit content in Play Mode Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Edit content in Play Mode Workspace and project owners and editors can edit story content directly in Play Mode, without switching back to the board. This is useful when playtesting reveals wording you want to fix on the spot. ![Play Mode with Edit content enabled: the pencil button in the top menu, the Editing indicator, and editable element text and option labels.](https://docs.arcweave.com/assets/play-mode-edit-content.CPnglMqz.gif) While editing, the top menu shows an **Editing** indicator next to the project name. Story navigation is paused: option buttons are not clickable, and the single-path advance arrow does not progress the story until you finish editing. ### Enter edit mode Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Edit content in Play Mode > Enter edit mode To start editing the current element: 1. Click the **Edit content** button (pencil icon) in Play Mode's top menu, or 2. Double-click the element's text content. The button is disabled when no element is loaded. On smaller screens, use the mobile menu to access **Edit content**. ### What you can edit Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Edit content in Play Mode > What you can edit In edit mode you can change: - The current element's [rich text](https://docs.arcweave.com/project-tools/rich-text) content. - The [labels](https://docs.arcweave.com/project-items/labels) of the element's outgoing connections (the option buttons shown in Play Mode). - The order of option buttons, by dragging the handle on the left of each option (same behavior as [reorder options](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#reorder-options)). Edits use the same [rich text](https://docs.arcweave.com/project-tools/rich-text) toolbar as on the board, including formatting and [@mentions](https://docs.arcweave.com/project-tools/mentions). If the project uses [localization](https://docs.arcweave.com/project-tools/localization), changes apply to the language currently selected in Play Mode. When an option has no label text, Play Mode shows the target element's title as option text, or the beginning of its content if it has no title. ### Move between fields Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Edit content in Play Mode > Move between fields Use **Tab** and **Shift + Tab** to move focus between the element content and option labels. From the last option, **Tab** returns to the element content; from the element content, **Shift + Tab** moves to the last option. ### Save and exit edit mode Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Edit content in Play Mode > Save and exit edit mode To save your changes and return to normal playtesting: - Press **Esc**, or - Click outside the content and option areas, or - Click the **Edit content** button again. **Restart** and [**Undo last choice**](https://docs.arcweave.com/project-tools/play-mode/debugger#undo-last-choice) save your edits and exit edit mode before they run. > ℹ️ Changes are saved to the project immediately and are visible on the board and in future Play Mode sessions. ## Restart story Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Restart story To restart the story, click the **Restart** button on the left side of the Play Mode top menu. The button is disabled while the story is at the element it restarts from. ![Arcweave Play Mode with an orange arrow pointing at the Restart button in the top menu.](https://docs.arcweave.com/assets/play-mode-restart.CQ4BTfFQ.png) This resets all [variables](https://docs.arcweave.com/project-items/variables/overview) and element [visits](https://docs.arcweave.com/project-items/arcscript#visits), and restarts the story from the project's [starting element](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#set-play-mode-start). > ℹ️ If you entered Play Mode using [Quickstart Play Mode from here](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#quickstart-play-mode-from-here), restarting will restart the story from that element, not the project's starting element. ## Control audio volume Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Control audio volume If you attach [audio assets](https://docs.arcweave.com/project-items/elements#audio-attachments) to elements, these files will automatically play during transitions between elements in Play Mode. Play Mode follows each attachment's [audio reference settings](https://docs.arcweave.com/project-items/assets/audio#audio-reference-settings), including its behavior, volume, **Delay**, **Fade in**, **Fade out**, and **Auto-stop on element exit**. The Play Mode interface includes audio controls on the top menu: 1. Click the **audio icon** to access volume controls. ![Arcweave's Play Mode environment, with an orange arrow pointing at the volume control button on the top menu.](https://docs.arcweave.com/assets/playmode-audio-open.BKkPJmnl.png) 2. Adjust the volume slider to set your preferred audio level. 3. Click the **mute icon** to toggle audio on or off. ## Choose language Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Choose language The Play Mode interface includes a menu that lets you select the story's language. This option is useful when a project uses Arcweave's [localization](https://docs.arcweave.com/project-tools/localization) feature and includes multiple languages. ![Arcweave Play Mode's interface with an orange arrow pointing at the Localization button.](https://docs.arcweave.com/assets/play-mode-localization.BQ17viup.png) To change the story's language: 1. Click the **Localization icon** to open the list of available story languages. 2. Choose the desired language. ## Share project Context: Arcweave docs > Project Tools > Play Mode > Using Play Mode > Share project For all users except [project visitors](https://docs.arcweave.com/workspaces/roles#project-visitors), the **Play Mode** interface includes a **Share** button, located on the left side of the top menu. ![Arcweave's Play Mode environment, with an orange arrow pointing at the Share button on the top menu.](https://docs.arcweave.com/assets/playmode-share-closed.aVUfWXJ7.png) This button functions identically to the project's main [Share](https://docs.arcweave.com/project-tools/share) button: it opens the **Share panel**, where you can manage project collaborator and visitor access. The available sharing options and permissions depend on the user's assigned role within the project. ![Arcweave's Play Mode environment, with an orange arrow pointing at the Share button on the top menu. The Share panel is open and identical to the project's Share panel, providing the option to invite project collaborators and change the project's public access.](https://docs.arcweave.com/assets/playmode-share-open.TdloxnU2.png) For a detailed description of the Share panel, see [Share your project](https://docs.arcweave.com/project-tools/share). # Debugger Source: https://docs.arcweave.com/project-tools/play-mode/debugger Section: Project Tools > Play Mode Description: Playtest your project using Play Mode's debugging features Project owners and editors can use the Debugger to track variables and playtest the project. ![Arcweave's Play Mode environment with the Debugger open and the current board's identifiers displayed.](https://docs.arcweave.com/assets/play-mode-debugger.CaTP6wLt.png) > ⚠️ Debug info is visible only to owners and editors; see [Roles](https://docs.arcweave.com/workspaces/roles) in the Workspaces section of this documentation. ## Access the Debugger Context: Arcweave docs > Project Tools > Play Mode > Debugger > Access the Debugger To open the Debugger: 1. [Open the Play Mode menu](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#open-play-mode-menu) at the top of the window. 2. Click the **Debug** icon (bug icon). The icon is disabled if the project has no [starting element](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#set-play-mode-start) and you did not [quickstart](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#quickstart-play-mode-from-here) from an element. To resize the Debugger, drag its left edge. To close it, click its **X** button or the **Debug** icon again. ## Undo last choice Context: Arcweave docs > Project Tools > Play Mode > Debugger > Undo last choice After you make a choice in Play Mode, **Undo last choice** appears beside the **Debugger** heading. Click it to return to the previous element. Undo restores the variable values, element visit counts, and rendered content saved before that choice. It also restores the Debugger's Previous and Current values. The previous element's Arcscript does not run again. You can undo repeatedly until you reach the start of the current playthrough. The button disappears when there are no choices left to undo. Restarting the story clears this choice history. ## Identifiers display Context: Arcweave docs > Project Tools > Play Mode > Debugger > Identifiers display The top part of the Debugger displays information on the current board and element: - Current board: - [Board name](https://docs.arcweave.com/project-items/boards#rename-boards-folders) - [Board UUID](https://docs.arcweave.com/project-items/boards#board-id) - [Board custom ID](https://docs.arcweave.com/project-items/boards#custom-id) - Current element: - [Element title](https://docs.arcweave.com/project-items/elements#edit-elements) - [Element UUID](https://docs.arcweave.com/project-items/elements#element-id) Click the **ID** button next to the current board or element to display its identifiers. Use the copy button next to an identifier to copy it to your clipboard. > ℹ️ Uses of board and element UUIDs include accessing the items in the project's [JSON](https://docs.arcweave.com/integrations/json), as well as targeting the element for CSS styling in the [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor); see the [CSS basics guide](https://docs.arcweave.com/tutorials/style-editor/css-basics#style-specific-elements). ## Track variables Context: Arcweave docs > Project Tools > Play Mode > Debugger > Track variables The area beneath the identifiers panel displays a list of the project's [variables](https://docs.arcweave.com/project-items/variables/overview), providing real-time tracking and debugging during playthrough. Use **Search variables and values** to filter the list by variable name, Previous value, or Current value. Variables appear in collapsible groups: one for global variables and one for each board or component that owns scoped variables. Each group heading shows its number of variables. Board and component groups also display the item's name and custom ID. Each row in the list includes: - **Name**: The global variable name or the custom ID of a board/component variable attribute. Scoped variables are grouped under their owning board or component and its custom ID. Hover over a name to see the variable's type. - **Previous value** (editable): The variable's value _before_ loading the current element. - **Current value**: The variable's value _after_ loading the current element. > ℹ️ When Arcweave loads an element that contains [Arcscript segments](https://docs.arcweave.com/project-items/arcscript), those segments execute sequentially in their defined order. If any segment assigns a new value to a variable, the update appears in the **Current value** column. The Previous value field's type depends on the variable's type, as defined in the **Global variable dialog** or the owning board or component's attributes. Editing a variable's **Previous value** allows you to test the logic of the current element. Updating this field immediately recalculates: - The variable's **Current value** - The values of any other variables updated by code within the current element - Text content that depends on the variable (e.g., via `if` expressions) - Available options that depend on the variable (e.g., via branch logic) ### Color indicators Context: Arcweave docs > Project Tools > Play Mode > Debugger > Track variables > Color indicators The Debugger uses **orange color** to flag variable values that either: - Are manually edited by you during the playthrough. - Have different Previous and Current values. An orange dot in a group heading indicates that the group contains at least one variable whose Previous and Current values differ. # Style Editor Source: https://docs.arcweave.com/project-tools/play-mode/style-editor Section: Project Tools > Play Mode Description: Customize Play Mode's appearance using custom CSS Arcweave allows you to customize the appearance of the Play Mode interface using custom CSS via the **Style Editor**. ![Arcweave's Play Mode screen, with the Style Editor sidebar open on the right, showing a block of CSS code affecting the playthrough's appearance on the left: the option buttons are semi-transparent and the cover image is full screen.](https://docs.arcweave.com/assets/play-style-editor.cx55xf1r.png) > ✅ The **Tutorials** section includes two tutorials on CSS: [Arcweave CSS basics](https://docs.arcweave.com/tutorials/style-editor/css-basics) and [Visual novel CSS](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel). ## Access the Style Editor Context: Arcweave docs > Project Tools > Play Mode > Style Editor > Access the Style Editor To access the Style Editor: 1. Enter Play Mode by clicking the **Play Mode** button in the project's top menu. 2. Click the **Style Editor icon** (palette icon) in Play Mode's top bar. The Style Editor is available to project owners and editors. To close it, click its **X** button or the palette icon again. ## Use the Style Editor Context: Arcweave docs > Project Tools > Play Mode > Style Editor > Use the Style Editor The Style Editor panel provides a dedicated environment for writing and managing your custom CSS: 1. **Interface:** The editor features CSS syntax highlighting and line numbers for easier code readability and navigation. The panel itself is resizable; you can drag its left edge to adjust the width. 2. **Writing CSS:** Enter your custom CSS rules in the editor. 3. **Real-time Validation:** As you type, the editor automatically validates your CSS. - If errors are detected, an alert icon and the error count (for example, **2 errors - view details**) appear at the bottom of the panel. - Clicking the error count displays each error with its line number (e.g., "Line 5: ..."). - The **Save changes** button will be disabled until all validation errors are resolved. 4. **Live Preview:** Valid CSS rules are reflected in the Play Mode window in real-time, allowing you to see the effects of your changes instantly. The preview applies only to your current browser tab; unsaved changes are lost when you reload or leave Play Mode. 5. **Saving:** Once you are satisfied and there are no validation errors, click the **Save changes** button to persist your custom styles. Your styles will be applied whenever you or others run this project in Play Mode. ## Keyboard Shortcuts Context: Arcweave docs > Project Tools > Play Mode > Style Editor > Keyboard Shortcuts The following keyboard shortcuts are available within the Style Editor: | Shortcut | Action | | :---------- | :---------------------------------------------------------------------- | | Tab | Insert 2 spaces at the cursor, or indent the selected lines by 2 spaces | | Shift + Tab | Remove 2 spaces from the start of the current or selected lines | ## Available CSS Selectors Context: Arcweave docs > Project Tools > Play Mode > Style Editor > Available CSS Selectors See the [Play Mode styling reference](https://docs.arcweave.com/project-tools/play-mode/styling-reference) for the DOM structure, selectors, layout defaults, CSS variables, media variants, and edit-mode behavior. It includes working examples for both manual editing and AI agents using the REST API or MCP. For story text, start with `.prototype__text .editor .editor-content`. For choices, use `.prototype__option`; these are clickable `div` elements. Scope rules to the story to avoid changing other application UI. ## Example Context: Arcweave docs > Project Tools > Play Mode > Style Editor > Example Here's the built-in preset from the Style Editor. To load it, click **apply a preset** at the top of the Style Editor panel. This replaces the CSS in the editor; click **Save changes** to keep it. You can use this as a starting point for your own customizations: ```css @import url('https://fonts.googleapis.com/css2?family=Lora:ital,wght@0,400..700;1,400..700&display=swap'); .prototype__wrapper { padding-top: 0px; } .prototype__content { display: flex; flex: 1; flex-flow: row-reverse; max-width: 100%; padding: 0; } .prototype__header { display: flex; flex-basis: 50%; } .prototype__body { flex: 1; padding: 2rem; font-family: 'Lora', serif; } .prototype__text .editor .editor-content { font-size: 22px; } .prototype__media { flex-flow: column; flex: 1; } .prototype__media img { object-fit: cover; width: 100%; height: 100%; } .prototype__components { grid-gap: 0; height: 100%; } .prototype__components--pushed { display: none; } .prototype__components.single > .comp { background: #1d1f1f; } .prototype__option { --prototype-option-background: transparent; --prototype-option-background-hover: transparent; border-radius: 0; border: 1px solid #292d2d; background: none; } @media (max-width: 767px) { .prototype__wrapper { padding-top: 40px; } .prototype__content { flex-flow: column; } .prototype__body .editor .editor-content { padding: 0 0 40px; } .prototype__header { flex-basis: 0; } } ``` ## Target elements Context: Arcweave docs > Project Tools > Play Mode > Style Editor > Target elements Each displayed element's root has the DOM ID `el-` followed by its element UUID. Copy the UUID from **Properties → Details → Element ID**, or use the element ID returned by the REST API or MCP. See [Target one element](https://docs.arcweave.com/project-tools/play-mode/styling-reference#target-one-element) for the mapping and its limits. ```css /* Replace this UUID with the element's UUID. */ #el-38375689-9e4d-430e-954c-65205eb622fe .prototype__text .editor .editor-content { font-family: 'Courier New', monospace; font-size: 18px; } #el-38375689-9e4d-430e-954c-65205eb622fe .prototype__option { --prototype-option-background: darkred; --prototype-option-background-hover: #b22222; } ``` Browser developer tools can help investigate a rule that does not behave as expected. You do not need browser inspection to construct an element selector from its UUID. ## Update styles through the API or MCP Context: Arcweave docs > Project Tools > Play Mode > Style Editor > Update styles through the API or MCP The [CSS REST API](https://docs.arcweave.com/rest-api/css) and [MCP CSS tools](https://docs.arcweave.com/integrations/mcp#style-play-mode) edit the same custom stylesheet. They replace its complete contents. Reload an already-open Play Mode tab to fetch externally saved changes, or click Play in the editor to open a new tab with fresh settings. Restarting the story does not refresh the stylesheet. The latest save wins; an old Style Editor tab can overwrite externally saved CSS. Retain unsaved local edits before reloading, then reapply them to the fresh stylesheet before saving. Follow [Save and verify styles](https://docs.arcweave.com/project-tools/play-mode/styling-reference#save-and-verify-styles) to preserve existing rules, keep a rollback copy, and check the result. A successful API/MCP response does not perform the Style Editor's CSS validation or visual verification. # Play Mode styling reference Source: https://docs.arcweave.com/project-tools/play-mode/styling-reference Section: Project Tools > Play Mode Description: Play Mode DOM structure, CSS selectors, layout defaults, and working examples for the Style Editor, REST API, and MCP This reference describes Play Mode's HTML structure, CSS selectors, and default styles. The [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor), [REST API](https://docs.arcweave.com/rest-api/css), and [MCP server](https://docs.arcweave.com/integrations/mcp#style-play-mode) all use the same project stylesheet. Reading that stylesheet returns only your custom rules, not Arcweave's built-in CSS. The structure and examples below let you author styles without browser inspection. Use a browser to verify the rendered result, especially after changing layout or targeting a particular playback state. ## Start with a small theme Context: Arcweave docs > Project Tools > Play Mode > Play Mode styling reference > Start with a small theme This example changes the background, story text, and choices while keeping the default layout: ```css .prototype { background: #060c13; } .prototype__content { background: #111e28; } .prototype__text .editor .editor-content { color: #d4dedc; font-family: Georgia, serif; font-size: 22px; line-height: 1.6; } .prototype__option { --prototype-option-background: #1b2d37; --prototype-option-background-hover: #293b42; color: #e1bc79; border: 1px solid #415962; } ``` Preserve any existing custom CSS when applying a new theme. A REST or MCP update replaces the complete custom stylesheet; see [Save and verify styles](https://docs.arcweave.com/project-tools/play-mode/styling-reference#save-and-verify-styles). ## Page structure Context: Arcweave docs > Project Tools > Play Mode > Play Mode styling reference > Page structure This browser capture shows the default styling on a Castle demo scene with two attached components. Cyan callouts identify the regions listed below; they are annotations, not built-in borders. ![Default Play Mode with numbered callouts: 1 image cover, 2 attached icon and image components, 3 story text, and 4 three choices.](https://docs.arcweave.com/assets/play-mode-styling-structure.DB_7GpVZ.png) | Callout | Region | Selectors | | ------- | ------ | --------- | | 1 | Element image cover | `.prototype__media img.single` | | 2 | Attached components | `.prototype__components`; individual covers use `.comp--icon` or `.comp--image`. | | 3 | Story text | `.prototype__text`; style its text with `.prototype__text .editor .editor-content`. | | 4 | Choices | `.prototype__options` contains the individual `.prototype__option` choices. | The following is a simplified example of normal playback with an image cover and two choices. Utility classes and rich-text wrappers are omitted where marked. Navigation, the debugger, and the Style Editor sit outside the story root. ```html The story text. Enter the castle Return to camp ``` Use descendant selectors such as `.prototype__root .prototype__wrapper`. Do not assume the wrapper is a direct child of the root: the scrollbar library adds wrappers at runtime. Treat library and utility classes as implementation details; prefer the named story classes below. ### Main selectors Context: Arcweave docs > Project Tools > Play Mode > Play Mode styling reference > Page structure > Main selectors | Selector | Target | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `.prototype` | Outer Play Mode page, including surrounding controls. Useful for the page background. | | `.prototype__main` | Player area. | | `.prototype__root` | Scrollbar host for the current story element; also carries `id="el-"`. | | `.prototype__wrapper` | Centers the story and supplies top spacing. | | `.prototype__content` | Story panel containing the header and body. | | `.prototype__header` | Element cover and attached component covers. | | `.prototype__body` | Story text and choices. | | `.prototype__text` | Text region; may also have `has-cover`, `showArrow`, or `play-mode-editing`. | | `.prototype__text .editor .editor-content` | Text box with explicit color, font size, line height, and padding. | | `.prototype__text .editor .ProseMirror` | Rich-text content, containing paragraphs, headings, links, and formatting tags. | | `.prototype__options` | Available choices. Hidden when there are no displayed choices. | | `.prototype__option` | A clickable **`div`**, not a native `button`. Normal playback puts label HTML directly inside it. | | `.prototype__option.visited` | A choice leading to an element already visited in the current playthrough. | | `.prototype__option.gold` | A choice with the corresponding connection color theme; see [all theme classes](https://docs.arcweave.com/tutorials/style-editor/css-basics#style-connections-of-specific-color). | Use `.prototype__option` to style choice text, or `.prototype__option p` for its paragraphs. There is no separate label class in normal playback. ### Media and components Context: Arcweave docs > Project Tools > Play Mode > Play Mode styling reference > Page structure > Media and components The element cover appears inside `.prototype__media` in one of these forms: | Cover | Rendered target | Styling notes | | -------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Image | `img.single` | `.prototype__media img.single` selects only the element cover. | | Uploaded video | `video.video-cover-player` | The class is on the video itself; `.video-cover-player video` matches nothing. | | YouTube | `.embeded-youtube` containing an `iframe` | Keep the spelling `embeded-youtube`. Size the wrapper and iframe as needed. | | Icon | `.prototype__media > .svg-icon-container` containing an `svg` | Use the direct child selector to exclude component icons inside `.prototype__media` when there is no element cover. | Attached component covers use `.prototype__components` grids. Their placement depends on the element cover: - **No element cover:** the visible grid is inside `.prototype__media`. A single component adds `.single` to this grid. - **Image cover:** the visible grid is a sibling after `.prototype__media`, with `.prototype__components--pushed`. - **Icon or YouTube cover:** the sibling grid has `.prototype__icon-pushed`. - **Video cover:** the sibling grid has `.prototype__components` without either modifier. An unused grid can remain in the DOM with inline `display: none`. Do not force hidden grids to display with `!important`. Image components render as ``. Icon components render as `` containing an SVG icon. A component without an assigned image uses its icon or the default icon. The grid after a cover also has a `.flex-fix` filler; it is not a component. Select `.comp` rather than every grid child. For example, fit an existing element cover inside a shorter frame: ```css .prototype__media img.single { width: 100%; height: 40vh; object-fit: contain; } ``` To show full component image silhouettes instead of cropping them into squares: ```css .prototype__components > .comp--image { object-fit: contain; background: transparent; } ``` ### Edit content mode Context: Arcweave docs > Project Tools > Play Mode > Play Mode styling reference > Page structure > Edit content mode While [Edit content](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#edit-content-in-play-mode) is enabled, the text region gets `.play-mode-editing`, and its editor wrapper gets `.prototype-content-editor.is-content-editable`. Editable choices introduce a row wrapper and a rich-text editor. When reordering is available, the row also gets `.is-option-edit-mode` and a drag handle. ![Detail of the same Play Mode scene with Edit content enabled: 1 editable story text, 2 the first choice row including its handle, 3 an editable choice, and 4 a drag handle. Native edit outlines are blue; numbered annotations are cyan.](https://docs.arcweave.com/assets/play-mode-styling-edit-content.D0iRGJQI.png) This cropped view shows the same scene with **Edit content** enabled. The blue edit outlines belong to the app; the cyan callouts are annotations. | Callout | Region | Selectors | | ------- | ------ | --------- | | 1 | Editable story text | `.prototype__text.play-mode-editing` contains `.prototype-content-editor.is-content-editable`. | | 2 | First choice row, including its handle | `.prototype-option-row.is-option-edit-mode` | | 3 | Editable choice | `.prototype__option.play-mode-editing` | | 4 | Drag handle | `.prototype-option-handle` | The simplified markup for an editable choice is: ```html ``` The actual editable markup has additional wrappers, and a hidden read-only copy of the rich text may remain. In the active text editor, `.ProseMirror` and `.editor-content` are classes on the **same node**. Continue to use descendant selectors from `.editor`, without assuming `.editor-content > .ProseMirror`. Styling `.prototype__text .editor .editor-content` works in both states and keeps story typography separate from the choice label editors. Editable choices also capture their current background in an inline `background` declaration. If you change choice backgrounds in the Style Editor while editing content, leave and re-enter Edit content mode to see the updated background. The app suppresses motion and hover effects on editable regions and pauses story navigation. Test the finished appearance with editing off, then confirm editing and drag handles are still usable. For positional choice selectors that handle both structures, see [Style specific options](https://docs.arcweave.com/tutorials/style-editor/css-basics#style-specific-options). ### Conditional content and the advance arrow Context: Arcweave docs > Project Tools > Play Mode > Play Mode styling reference > Page structure > Conditional content and the advance arrow Choices reflect the current branch conditions and label evaluation, so their number and order can change. If exactly one available path has no label text, Play Mode uses a blinking advance arrow instead of a choice button. This also happens when branch conditions reduce several outgoing connections to one available path. See [Continue to the next element](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#continue-to-the-next-element). The arrow is a border triangle on the **last rich-text child**, not a pseudo-element of the outer text region: ```css .prototype__text.showArrow .editor .ProseMirror > :last-child::after { border-top-color: #e1bc79; animation: none; } ``` Video settings can delay the text and choices until the video ends. A missing text region or hidden choices container can therefore reflect playback state rather than a CSS error. CSS does not create choices, change their destinations, or change the condition that displays the arrow. Missing translations can display fallback text and choice labels at reduced opacity, with a fallback notice before the text editor. Arcscript errors can add diagnostic boxes inside `.prototype__text` for element content, or after `.prototype__options` for labels. These are playback states, not necessarily color or layout problems; scope formatting rules such as `em` to `.prototype__text .editor .editor-content` to avoid restyling the notice. ## Layout defaults Context: Arcweave docs > Project Tools > Play Mode > Play Mode styling reference > Layout defaults These are built-in values before custom CSS. More specific rules, rich-text formatting, and inline styles can affect the final result. | Target | Default behavior | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `.prototype` | Relative positioning, full available height, black background, hidden overflow. | | `.prototype__main` | Horizontal flex container, full height, hidden overflow. | | `.prototype__root` | Flex column with `flex: 1`, `max-height: 100%`, and vertical scrolling managed by OverlayScrollbars. | | `.prototype__wrapper` | Flex container, centered horizontally, `min-height: 100%`, `padding-top: 40px`. | | `.prototype__content` | `width: 100%`, `max-width: 860px`, `min-height: 100%`, `padding: 20px`, `font-size: 20px`, `overflow-x: hidden`. | | `.prototype__body` | `white-space: pre-wrap`. | | `.prototype__body .editor .editor-content` | `color: #bcbcbc`, `font-size: 20px`, `line-height: 1.5`, `padding: 20px 0 40px`. | | Rich-text wrappers | `.editor-content` and the read-only editor also have overflow rules; paragraphs have their own spacing. Account for these when building a separately scrolling dialogue box. | | `.prototype__media` | Wrapping flex container. Image covers preserve their aspect ratio within maximum width/height constraints. | | `.prototype__components` | Grid with `width: 100%`, `margin-top: 3%`, and a `3%` column gap. Column count is set inline. | | `.prototype__components > .comp` | Full cell width/height, `object-fit: cover`, dark background, `4px` corners. Image aspect ratio is set inline. | | `.prototype__option` | `color: #db841e`, `padding: 15px 20px`, `margin-bottom: 20px`, `border-radius: 8px`, `line-height: 1.5`, `white-space: pre-wrap`, and a background transition. | The component grid has one column per attached component when there is no element cover. With a cover it uses at least five columns (`max(component count, 5)`). A lone image component without an element cover uses its natural aspect ratio; otherwise image components use a square aspect ratio. Both `grid-template-columns` on the grid and `aspect-ratio` on component images are **inline styles**. If you need to replace those properties, use a narrowly targeted override: ```css .prototype__components { grid-template-columns: repeat(2, minmax(0, 1fr)) !important; } .prototype__components > .comp--image { aspect-ratio: auto !important; height: 180px; object-fit: contain; } ``` Switching the grid to `display: flex` is another layout choice: its inline grid column definition then has no effect. Avoid blanket `!important` rules, especially on visibility or edit-mode behavior. ### Choice background variables Context: Arcweave docs > Project Tools > Play Mode > Play Mode styling reference > Layout defaults > Choice background variables The built-in stylesheet defines these on **each `.prototype__option`**: | Variable | Default | | ------------------------------------- | --------- | | `--prototype-option-background` | `#171818` | | `--prototype-option-background-hover` | `#292d2d` | Override them on `.prototype__option`, as in the starter theme. Setting them only on a parent does not replace the declarations on each choice. A custom `background` without a matching hover rule can still be replaced by the built-in `:hover` background. ### Player scrollbars Context: Arcweave docs > Project Tools > Play Mode > Play Mode styling reference > Layout defaults > Player scrollbars The root's current scrollbar library creates a `[data-overlayscrollbars-viewport]` descendant and separate `.os-scrollbar` controls. Styling `.prototype__root::-webkit-scrollbar` does not style those controls. Change their thumb colors with the library's variables: ```css .prototype__root .os-scrollbar { --os-handle-bg: #64748b; --os-handle-bg-hover: #94a3b8; --os-handle-bg-active: #cbd5e1; } ``` The built-in values are `#242829` for the normal thumb and `#424a4c` for hover/active. A separately scrolling region that you add with `overflow: auto`, such as the visual-novel dialogue box, uses native scrollbars instead; style that region with `scrollbar-color` and `scrollbar-width`. ## CSS scope and precedence Context: Arcweave docs > Project Tools > Play Mode > Play Mode styling reference > CSS scope and precedence Custom CSS is inserted into a document-level stylesheet while Play Mode is mounted. Arcweave does **not** automatically scope your selectors to the story. Bare `body`, `button`, `.editor`, `.ProseMirror`, or `svg` rules can also affect surrounding application UI. Use the story selectors above, or an element ID, to limit their reach. Define your own theme variables on a story container rather than global `:root`. Custom CSS appears after the built-in styles, but normal CSS specificity, inheritance, inline styles, and `!important` still apply. For example, changing `color` or `font-size` on `.prototype__content` does not override the explicit values on its descendant `.editor-content`. Target `.prototype__text .editor .editor-content` for those properties. Rich-text headings, links, or formatted spans may need a further targeted rule. Default `overflow-x: hidden` on the story panel and scrolling wrappers matter for absolute positioning. Establish a containing block deliberately, remove conflicting size/padding constraints, and bound separately scrolling dialogue and choice regions. Check short screens as well as narrow ones; the [visual novel tutorial](https://docs.arcweave.com/tutorials/style-editor/css-visual-novel) demonstrates this layout. ## Target one element Context: Arcweave docs > Project Tools > Play Mode > Play Mode styling reference > Target one element Use the element's **UUID** from the API/MCP element record or **Properties → Details → Element ID**. The player maps it directly to `id="el-"`; no browser lookup is needed. For UUID `38375689-9e4d-430e-954c-65205eb622fe`, the selector is: ```css #el-38375689-9e4d-430e-954c-65205eb622fe .prototype__text .editor .editor-content { color: #e2e8f0; font-family: 'Courier New', monospace; font-size: 18px; } ``` Elements have no custom ID. The UUID is also distinct from the element's title and the project's URL hash (`projectId` in MCP). Prefix a raw UUID with `el-` once; a DOM ID copied from the browser already contains that prefix. Component and connection UUIDs are **not** exposed as corresponding DOM IDs or data attributes. Do not invent `#component-`, `#connection-`, or `[data-id="..."]` selectors. You can scope to the current element and then target component types, choice themes, visited state, or visible choice positions. Positions are not stable identifiers across branch evaluation or reordering. ## Asset URLs Context: Arcweave docs > Project Tools > Play Mode > Play Mode styling reference > Asset URLs Prefer attaching an asset as an [element cover](https://docs.arcweave.com/project-items/elements#element-covers) or [component cover](https://docs.arcweave.com/project-items/components#cover), then styling its rendered image. Arcweave supplies the image URL and updates it as the current element changes. Asset metadata reads through REST/MCP return a stored `file` name, not a persistent public URL for CSS. The MCP file-download tool returns a temporary transfer URL. An agent using those tools should use managed covers, or a persistent public URL supplied by the user or hosted under their control. Do not construct a URL from `file`. If you already have a persistent Arcweave media delivery URL, use it unchanged and verify that the intended players can access it. See [Asset delivery URLs](https://docs.arcweave.com/rest-api/assets#download-asset-file). The authenticated REST file-download endpoint requires an API-key header, which CSS requests cannot supply. MCP upload/download transfer URLs expire and must not be saved in a stylesheet. Never embed an API key in CSS or a URL. Verify external fonts and images in the public player as well as your editing session. ## Save and verify styles Context: Arcweave docs > Project Tools > Play Mode > Play Mode styling reference > Save and verify styles For the [REST API](https://docs.arcweave.com/rest-api/css) and [MCP tools](https://docs.arcweave.com/integrations/mcp#style-play-mode): 1. Read the current custom CSS and retain a copy for rollback. 2. Modify it while preserving unrelated rules. Re-read the saved CSS immediately before updating; if it changed, apply your edits to that latest value. Send the **complete updated stylesheet**; updates do not append rules. 3. Read it back to confirm what was stored. Passing `""` clears all custom styling. 4. **Reload an already-open Play Mode tab**, or click Play in the editor to open a new tab, which loads fresh settings. Restarting the story or returning to Play Mode through same-tab navigation does not fetch fresh settings. External CSS updates are not broadcast to existing players. 5. Verify the appearance and story navigation. A successful save confirms storage, not CSS syntax, matching selectors, or usable layout. The Style Editor's validation and live preview are separate from REST/MCP string validation. Saves replace the entire stylesheet without conflict detection: the latest save wins. An old Style Editor tab can overwrite an agent's changes, and an agent can overwrite a newer manual save. Coordinate edits; re-reading before a write reduces this risk but does not lock the stylesheet. After an external update, retain any unsaved local edits, reload the Style Editor tab, and reapply them to the fresh CSS before saving there. CSS API/MCP writes do not create project command-history entries. Restore your saved original by sending it as the complete stylesheet again, then reload. Check a typical scene and the cases affected by your change: long dialogue, many long choices, a single unlabelled path, visited/themed choices, each cover type you use, components with and without a cover, and edit mode. Test desktop, a narrow mobile viewport, and a short landscape viewport. Confirm that text and the last choice remain reachable by scrolling and that navigation controls remain usable. If a browser is unavailable, you can verify the saved stylesheet and check selectors against this reference. Report that visual verification is still outstanding rather than treating a successful tool response as proof of appearance. # Search Source: https://docs.arcweave.com/project-tools/search Section: Project Tools Description: Search boards, elements, jumpers, branches, labels, notes, components, and assets across an Arcweave project by ID or content Arcweave provides a project-wide **search** function to help you quickly find content across key parts of your project. ![Arcweave's project screen, with the search field open and showing results for the term "crusader" in the Interactive Fiction Example project.](https://docs.arcweave.com/assets/search._53j8hnX.png) ## Search context Context: Arcweave docs > Project Tools > Search > Search context The search scans the following [project items](https://docs.arcweave.com/project-items/overview) and properties: | Item | Properties scanned | | :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | | [Board](https://docs.arcweave.com/project-items/boards) | board ID, board name | | [Element](https://docs.arcweave.com/project-items/elements) | element ID, element title, element content | | [Jumper](https://docs.arcweave.com/project-items/jumpers) | jumper ID, target element title | | [Branch](https://docs.arcweave.com/project-items/branches) | branch ID, condition content | | [Label](https://docs.arcweave.com/project-items/labels) | connection ID, label content | | [Note](https://docs.arcweave.com/project-items/notes) | note ID, note content | | [Component](https://docs.arcweave.com/project-items/components) | component ID, name, [attribute](https://docs.arcweave.com/project-items/attributes) names, String Field and Rich Text Field attribute values | | [Asset](https://docs.arcweave.com/project-items/assets/overview) | asset ID, asset name (including its file extension) | | [Variable](https://docs.arcweave.com/project-items/variables/overview) | variable ID, global variable name, scoped variable label or custom ID | Item ID matching starts only when your search term contains at least **eight characters**, excluding leading and trailing spaces. Shorter terms still search names and content. For component attributes, search matches names of all attribute types, but only searches values of **String Field** and **Rich Text Field** attributes. Numeric, Boolean, and list values are not searched. Board, component, and asset folders are not included in the results. ## Perform a search Context: Arcweave docs > Project Tools > Search > Perform a search To perform a search: 1. Press either of the following: - The **magnifying glass icon** on the right side of the top menu - **Ctrl/Cmd+F** 2. Begin typing your search term. The results update automatically as you type. 3. Expand or collapse result groups as needed. 4. Click **Show all results** if the search has more matches than the initial list shows. The initial list shows up to 20 results in total. 5. Click a result to view it. ## View search results Context: Arcweave docs > Project Tools > Search > View search results Arcweave behaves differently depending on the type of search result: - **Board**: Opens the board at the position of your last visit. - **Element, jumper, branch, or note**: Opens the board that contains the item and centers it on the item. - **Label** (listed under **Connection Labels**): Opens the board that contains the connection and centers it on the connection. - **Component**: Opens the component editor for viewing or editing. - **Asset**: Opens the asset preview. - **Variable**: Opens the **Global variables** dialog for a global variable, the board's attributes dialog for a board variable, or the component editor for a component variable. Variable results display their type and scope. ## Exit search Context: Arcweave docs > Project Tools > Search > Exit search To close the search, press any of the following: - **Ctrl/Cmd+F** - **Esc** - The **magnifying glass icon** in the top menu # History Source: https://docs.arcweave.com/project-tools/history Section: Project Tools Description: Safely view and restore previous versions of your project Arcweave's **History** feature allows you to view and restore previous versions of your project. Its **timeline** shows the currently loaded versions. You can [load older versions](https://docs.arcweave.com/project-tools/history#load-older-versions) when more history is available. > ✅ [Edits in Play Mode](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#edit-content-in-play-mode) are also tracked by History. > ℹ️ The History feature is available only in [Team workspaces](https://docs.arcweave.com/workspaces/billing-plans#workspace-comparison), to users who can edit the project (owners and editors). ## Open history Context: Arcweave docs > Project Tools > History > Open history To open History, click the **History** button (tooltip: **Open History**) located on the right side of the top menu. The button is disabled while the project has no saved history. ![Arcweave's project screen, with an orange arrow pointing at the History button.](https://docs.arcweave.com/assets/history-menu.XhwUakBN.png) When you open History, your project switches to a **read-only** state, allowing you to navigate and read its contents, change boards, open components, etc.—but not edit anything. Moreover, the History **timeline** and **control buttons** will be displayed. ![Arcweave's project screen, with the History timeline and control buttons open and emphasized by an orange rectangle.](https://docs.arcweave.com/assets/history-timeline.DMLk0Dnf.png) ## Close history Context: Arcweave docs > Project Tools > History > Close history To close History without restoring a version, you can: - Click **Close History** (the **X** button) in the History control buttons. - Click the **History** button in the top menu again. > ℹ️ When you [restore a version](https://docs.arcweave.com/project-tools/history#restore-project-versions), History closes automatically and your project returns to its normal **read/write** mode, i.e. you can again edit. ## View project versions Context: Arcweave docs > Project Tools > History > View project versions To browse through your project's versions: - Drag the timeline's **view slider** left (older versions) or right (newer versions). - Hover over the timeline and click the desired version. - Use the **Move one step back** or **Move one step forward** buttons. As you move through the timeline, your project temporarily reflects the selected version. Changes are only permanent after you [restore a version](https://docs.arcweave.com/project-tools/history#restore-project-versions). ## Version ranges Context: Arcweave docs > Project Tools > History > Version ranges The **version-range dropdown** on the left of the timeline lists the loaded history in ranges of up to 100 versions. Each entry shows the first and last version numbers in that range, or a single number if it contains only one version. Select a range to view its versions on the timeline. The **Move one step back** and **Move one step forward** buttons also move between loaded ranges when you reach the end of the current range. The back button is disabled at the oldest loaded version, and the forward button is disabled at the newest version. The oldest loaded version may not be the oldest saved version; use **Load More** to retrieve earlier history when available. ### Load older versions Context: Arcweave docs > Project Tools > History > Version ranges > Load older versions To load older versions: 1. Open the **version-range dropdown** on the left of the timeline. 2. Click **Load More**. The entry changes to **Loading...** while Arcweave retrieves the next batch of up to 100 older versions. The version you are viewing stays selected. 3. Once loading finishes, select an older range and browse its versions on the timeline. 4. Repeat **Load More** to go further back. While loading, the timeline's navigation controls are disabled. **Load More** is disabled while loading, when the project has no older history stored on the server, or once the full history has been loaded. ## Version information Context: Arcweave docs > Project Tools > History > Version information Hovering over a version in the timeline displays its **information panel**. ![Arcweave's environment with the History timeline open. The information panel of a version on the timeline is visible.](https://docs.arcweave.com/assets/history-hover-info.CcIw2OUZ.png) From top to bottom, the information panel displays: - The user who created the version, or the API key name for changes made through the [REST API](https://docs.arcweave.com/rest-api/overview) or [MCP](https://docs.arcweave.com/integrations/mcp) - The date and time of creation - The recorded actions - The version number The panel also includes a **Restore this version** button (history icon) to restore the project to that version. ## Restore project versions Context: Arcweave docs > Project Tools > History > Restore project versions To restore a project version: 1. Select the desired version on the timeline. 2. In the version's information panel, click **Restore this version**. ![Arcweave's environment with the History timeline open. The information panel of a version on the timeline is visible and an orange arrow points at the "Restore this version" button.](https://docs.arcweave.com/assets/history-restore-button.B-2iOkVK.png) ## Notes on history Context: Arcweave docs > Project Tools > History > Notes on history ### Non-destructive versioning Context: Arcweave docs > Project Tools > History > Notes on history > Non-destructive versioning Restoring a previous version does not delete any subsequent progress. Arcweave creates a new version that duplicates the selected version, ensuring no versions are lost. ### History vs. undo/redo Context: Arcweave docs > Project Tools > History > Notes on history > History vs. undo/redo History is different from undoing (**Ctrl/Cmd + Z**) or redoing (**Ctrl/Cmd + Shift + Z**) actions in the following ways: - **Persistence:** History records are stored on Arcweave's server and are not session-bound, unlike Undo/Redo, which operates locally on the user's client. - **User scope:** History can revert to versions created by any user, while Undo only reverts actions performed by the current user. # Localization Source: https://docs.arcweave.com/project-tools/localization Section: Project Tools Description: Translate projects into multiple languages, manage languages and translation status, and import or export translation spreadsheets Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. Arcweave includes built-in localization tools to manage translations of your project into multiple languages. It allows you to: - Translate your project collaboratively and efficiently. - Work safely: adding/removing [project items](https://docs.arcweave.com/project-items/overview) is disabled while translating. - Set [Arcscript segments as translatable](https://docs.arcweave.com/project-tools/localization#translate-arcscript-segments) or non-translatable. - Let players choose their preferred language in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#choose-language). - Select which languages to include when you [export](https://docs.arcweave.com/project-tools/export) the project. > ℹ️ Localization is available only in [Team workspaces](https://docs.arcweave.com/workspaces/billing-plans#workspace-comparison). > ⚠️ A user must have [project editing](https://docs.arcweave.com/workspaces/roles) permissions to translate. ## Main language & translations Context: Arcweave docs > Project Tools > Localization > Main language & translations By default, an Arcweave project has only one language, referred to as the project's **Main** language. By default, this is _English,_ but you can [change it to any language](https://docs.arcweave.com/project-tools/localization#set-main-language). > ⚠️ When working in any language other than its main, the project enters **Translation Mode**. Once in Translation Mode, you cannot add or delete [project items](https://docs.arcweave.com/project-items/overview); you can only translate existing ones. > ℹ️ To return to Arcweave's default editing mode, you need to [switch back to the project's main language](https://docs.arcweave.com/project-tools/localization#switch-language). ## Open localization Context: Arcweave docs > Project Tools > Localization > Open localization To open the localization menu, click the **Localization** icon on the right side of the top menu. ![Arcweave's project environment, with an orange arrow pointing at the Localization icon.](https://docs.arcweave.com/assets/localization-icon.CXcYZQcB.png) ![Arcweave's project environment, with an orange rectangle emphasizing the Localization menu](https://docs.arcweave.com/assets/localization-menu.BAXfGIk9.png) The drop-down menu shows: - A list of all languages added to the project - The project's main language (marked with an orange **Main** tag) - The currently displayed language (marked with an orange tick) - The [translation status](https://docs.arcweave.com/project-tools/localization#translation-status) of each translation (marked with the relevant icon) - The translation progress percentage for each translation - An option to **Import XLSX** (owners and editors); see [Import localized spreadsheets](https://docs.arcweave.com/project-tools/localization#import-localized-spreadsheets) - An option to **Manage languages...** ## Manage languages Context: Arcweave docs > Project Tools > Localization > Manage languages To add, edit, and remove languages: 1. Open the **Localization** drop-down menu. 2. Select **Manage languages...** 3. Perform any of the following actions. ![Arcweave's project environment, with the modal for managing languages open.](https://docs.arcweave.com/assets/localization-manage.TnLU4PWQ.png) ### Set main language Context: Arcweave docs > Project Tools > Localization > Manage languages > Set main language By default, the project language is English. To set another language as the default: 1. Open the **Localization** drop-down menu. 2. Select **Manage languages...** 3. Find the **Main** language; it is the first in the list. 4. Click the **three-dot (•••)** icon on the right and select **Edit**. 5. Update the main language's information: - **Language**: e.g. `Spanish` - **ISO code**: e.g. `es` 6. Click **Save**. Editing the main language changes its name and ISO code; the project's existing main-language content stays in the main language. You cannot turn an existing translation into the main language. ### Add language Context: Arcweave docs > Project Tools > Localization > Manage languages > Add language To add a new language: 1. Open the **Localization** drop-down. 2. Select **Manage languages...** 3. Click **Add Language**. 4. Enter the new language's information: - **Language**: e.g. `Italian` - **ISO code**: e.g. `it` 5. Select a source language for the new language's translation in **Translates from**. It defaults to the main language. 6. Click **Save**. Language names (up to 50 characters) and ISO codes must be unique within the project. ISO codes are 2 to 10 characters long, can contain letters, numbers, hyphens, and underscores, and must start and end with a letter or number. A language cannot translate from a language that, directly or indirectly, translates from it. > ✅ While translating to a language, the source content is displayed on the side, in the language set in **Translates from**. ### Edit language Context: Arcweave docs > Project Tools > Localization > Manage languages > Edit language To edit an existing language: 1. Open the **Localization** drop-down. 2. Select **Manage languages...** 3. Find the language in the list. 4. Click the **three-dot (•••)** icon on the right and select **Edit**. > ℹ️ You can update the **Language** name, **ISO code**, and **Translates from** fields. ### Delete language Context: Arcweave docs > Project Tools > Localization > Manage languages > Delete language To delete a language: 1. Open the **Localization** drop-down. 2. Select **Manage languages...** 3. Find the language in the list. 4. Click the **three-dot (•••)** icon on the right and select **Delete**. 5. Confirm with **Yes, Delete**. This action cannot be undone. > ⚠️ You cannot delete the [main language](https://docs.arcweave.com/project-tools/localization#set-main-language). ## Switch language Context: Arcweave docs > Project Tools > Localization > Switch language To switch the working language: 1. Open the **Localization** drop-down menu. 2. Select the desired language. The editor will now display content in the selected language. ### Copy a link in the current language Context: Arcweave docs > Project Tools > Localization > Switch language > Copy a link in the current language After switching languages, use an item's **Copy link** action to share that item in the selected language. Opening the link selects that language, entering **Translation Mode** for a translation. See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position) for supported items and access requirements. In Translation Mode, you can select branches and jumpers and right-click them to copy their links. Moving or deleting them, editing branch logic, and changing jumper targets remain disabled. ## Translation status Context: Arcweave docs > Project Tools > Localization > Translation status When working in translation mode, each [board](https://docs.arcweave.com/project-items/boards), [element](https://docs.arcweave.com/project-items/elements), [label](https://docs.arcweave.com/project-items/labels), and [component](https://docs.arcweave.com/project-items/components) has a **translation status** to indicate its progress. This makes it easier to track and manage the state of translations across the project. The available statuses are: - **Untranslated** (red) - **In progress** (yellow) - **For review** (blue) - **Final** (green) > ℹ️ Translation status for elements, labels, and components must be set manually. Translation status for boards is generated automatically, according to the status of the containing elements and labels. > ℹ️ Only connections with a label in the main language have a translation status. Unlabelled connections don't count toward the status of boards and folders or toward a language's [completion percentage](https://docs.arcweave.com/project-tools/localization#translation-percentage). > ✅ Translation status is exported as part of [Arcweave's JSON](https://docs.arcweave.com/integrations/json). ### Set element status Context: Arcweave docs > Project Tools > Localization > Translation status > Set element status To set the translation status of an element: 1\. Locate the element in the current board. ![Arcweave's project environment, with the context menu of an element in the board being open and displaying the translation status.](https://docs.arcweave.com/assets/localization-set-status-element-1.ewYUaqA-.png) Alternatively, locate the element in the **Boards** section of the sidebar, as a child of the board it belongs to. ![Arcweave's project environment, with the context menu of an element in the Boards section being open and displaying the translation status.](https://docs.arcweave.com/assets/localization-set-status-element-2.DxtjLv5R.png) 2\. Right-click the element and select **Set status**. ### Set label status Context: Arcweave docs > Project Tools > Localization > Translation status > Set label status To set the translation status of a label, right-click the label in the current board and select **Set status**. Alternatively, in the **Boards** section of the sidebar, expand the board, then expand the element or branch that the connection leaves from. Right-click the labelled connection and select **Set status**. See [Board contents](https://docs.arcweave.com/project-tools/interface/left-sidebar#board-contents). > ℹ️ Unlabelled connections, branches, jumpers, and notes have no translation status, so they have no **Set status** option. ### Set component status Context: Arcweave docs > Project Tools > Localization > Translation status > Set component status ![Arcweave's project environment, with the context menu of a component in the Components section being open and displaying the translation status.](https://docs.arcweave.com/assets/localization-set-status-component-1.DN3jtd8m.png) To set the translation status of a component, right-click the component in the **Components** section of the left sidebar and select **Set status**. ### Translation percentage Context: Arcweave docs > Project Tools > Localization > Translation status > Translation percentage Items marked as **Final** count toward the language's completion percentage, shown next to it in the **Localization** menu. ## Translate elements Context: Arcweave docs > Project Tools > Localization > Translate elements To translate an element: 1. Open the **Localization** drop-down and switch to the desired language. 2. [Set the translation status](https://docs.arcweave.com/project-tools/localization#set-element-status) of the element you want to translate from _Untranslated_ to _In progress._ ![Arcweave's project environment, with the context menu of an element in the board being open and displaying the translation status.](https://docs.arcweave.com/assets/localization-translate-element-1.B2qf0G35.png) 3. Double-click the element you want to translate to start editing. The element's source text, in the language specified in the [Translates from](https://docs.arcweave.com/project-tools/localization#add-language) field, will appear as a reference. ![Arcweave's project environment during element translation.](https://docs.arcweave.com/assets/localization-translate-element-2.r-pT4qiV.png) > ℹ️ Use the **clipboard icon** in the source text reference to copy and paste the source text into the element you are translating. ![Arcweave's project environment during element translation, with an orange rectangle emphasizing the clipboard icon.](https://docs.arcweave.com/assets/localization-translate-element-3.CImcav0e.png) 4. After translating, press ESC or click outside the element, to exit editing. 5. Once done, set the translation status of the element to _For review_ or _Final,_ depending on your workflow. ![Arcweave's project environment, with the context menu of an element in the board being open and displaying the translation status.](https://docs.arcweave.com/assets/localization-translate-element-4.BNll9H96.png) ## Translate label Context: Arcweave docs > Project Tools > Localization > Translate label To translate a label: 1\. Open the **Localization** drop-down and switch to the desired language. 2\. [Set the translation status](https://docs.arcweave.com/project-tools/localization#set-label-status) of the label you want to translate from _Untranslated_ to _In progress._ 3\. Double-click the label you want to translate to start editing. The label's source text, in the language specified in the [Translates from](https://docs.arcweave.com/project-tools/localization#add-language) field, will appear as a reference. 4\. After translating, press ESC or click outside the label, to exit editing. 5\. Once done, set the translation status of the label to _For review_ or _Final,_ depending on your workflow. ## Translate component Context: Arcweave docs > Project Tools > Localization > Translate component To translate a component: 1\. Open the **Localization** drop-down and switch to the desired language. 2\. In the left sidebar's **Components** section, set the translation status of the component you want to translate from _Untranslated_ to _In progress._ 3\. Click the component you want to translate to open it, then edit its name. 4\. After translating, press ESC or click outside the name field, to exit editing. 5\. If you're done, set the translation status of the component to _For review_ or _Final,_ depending on your workflow. > ⚠️ You can only translate the name of a component, not its attributes or their values. ## Translate Arcscript segments Context: Arcweave docs > Project Tools > Localization > Translate Arcscript segments By default, [Arcscript segments](https://docs.arcweave.com/project-items/arcscript#arcscript-segments) in [element](https://docs.arcweave.com/project-items/elements#add-arcscript) and [label content](https://docs.arcweave.com/project-items/labels#arcscript-in-labels) are **non-translatable**. This means that, when translating, Arcscript expressions cannot be modified. ### Why translate Arcscript? Context: Arcweave docs > Project Tools > Localization > Translate Arcscript segments > Why translate Arcscript? A common reason for making Arcscript segments translatable is to let string assignments properly follow the current language. For example, the following code assigns a string value to the variable `flower` and then uses that value in a sentence. It makes sense that the value must follow the language of the translation. ```arcweave-html flower = "the rose" You take show(flower) and give it to the guard. ``` This will render as "You take the rose and give it to the guard." ```arcweave-html flower = "الوردة" تأخذ show(flower) .ثم أعطها للحارس ``` And this will render properly in the Arabic language: ".تأخذ الوردة ثم أعطها للحارس" > ⚠️ You cannot set branch conditions as translatable; only Arcscript in elements and labels. ### Toggle translatable Arcscript Context: Arcweave docs > Project Tools > Localization > Translate Arcscript segments > Toggle translatable Arcscript You can mark individual Arcscript segments as **translatable** or **non-translatable**. This setting determines whether a segment can be edited independently per language or only in the main language. To toggle an Arcscript segment: 1. Switch to your project's [main language](https://docs.arcweave.com/project-tools/localization#main-language-translations), if needed: - Open the **Localization** drop-down menu and select the main language. 2. Edit the content containing the Arcscript segment: - **In a label**: double-click the label's connection and place the cursor inside the Arcscript segment. - **In an element**: double-click the element's content and place the cursor inside the Arcscript segment. 3. In the formatting bar, click **Translatable** (the globe icon) to toggle the setting. - **Translatable ON**: the Arcscript segment can be edited separately in each language. - **Translatable OFF** (default): the Arcscript segment is editable only in the main language and is locked in all translations. > ⚠️ You can only toggle translatability while editing the project in its **main language**. ## Localization in Play Mode Context: Arcweave docs > Project Tools > Localization > Localization in Play Mode ### Set Play Mode language Context: Arcweave docs > Project Tools > Localization > Localization in Play Mode > Set Play Mode language To set the story's language in Play Mode use the **Localization** icon in the [Play Mode menu](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#play-mode-menu). This is accessible to anyone who views the project's Play Mode. ![Arcweave Play Mode's interface with an orange arrow pointing at the Localization button.](https://docs.arcweave.com/assets/play-mode-localization.BQ17viup.png) To change the story's language: 1. Click the Localization icon to open the list of available story languages. 2. Choose the desired language. ### Edit language in Play Mode Context: Arcweave docs > Project Tools > Localization > Localization in Play Mode > Edit language in Play Mode [Edits made in Play Mode](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#edit-content-in-play-mode) apply to the language currently selected and are saved automatically to the corresponding translation. ## Export translations Context: Arcweave docs > Project Tools > Localization > Export translations Arcweave allows you to control which languages & translations you include in the export. See [Export](https://docs.arcweave.com/project-tools/export) for instructions. XLSX exports include [Open in Arcweave links](https://docs.arcweave.com/project-tools/export#open-items-from-an-xlsx-export) for viewing items in context. A single-language export's links select that language in Arcweave, entering **Translation Mode** for a translation. An **All languages** export's links leave language selection to the person opening them. ## Import localized spreadsheets Context: Arcweave docs > Project Tools > Localization > Import localized spreadsheets Arcweave allows importing **XLSX spreadsheet files** for translating purposes. This facilitates translators who are familiar with and prefer working on spreadsheets. > ⚠️ Valid spreadsheet files are the [XLSX spreadsheets exported from Arcweave](https://docs.arcweave.com/project-tools/export#export-as-spreadsheet) with the option **All languages** selected. These include the **Languages** sheet and translators must preserve this format. ### Workflow synopsis Context: Arcweave docs > Project Tools > Localization > Import localized spreadsheets > Workflow synopsis To establish such a workflow, follow these steps: 1. **Project owner/editor** Export spreadsheet and send to the translator. 2. **Translator** Translate on the spreadsheet and send back. 3. **Project owner / editor** Import the translated spreadsheet. > ⚠️ Edits in the main language are also reimported. Below you'll find instructions for each of the above steps. ### Export spreadsheet Context: Arcweave docs > Project Tools > Localization > Import localized spreadsheets > Export spreadsheet To export a spreadsheet for your translator: 1. Add the new language to the project. 2. In **Languages to export**, select **All languages**. 3. Export the project as an `.xlsx` spreadsheet file. Then, forward the exported spreadsheet file to the translator, who will work as described in the following step. ### Translate spreadsheet Context: Arcweave docs > Project Tools > Localization > Import localized spreadsheets > Translate spreadsheet Once the translator receives the `.xlsx` spreadsheet file, they can open and edit it in their spreadsheet editor. > The translator should focus on specific sheets and columns, as described below. Keep each row's `Id` unchanged. Import updates only items whose IDs still exist in the project; rows with missing or unknown IDs, including deleted items, are ignored. Adding rows does not create project items. Keep the **Languages** sheet and the column headers unchanged. Arcweave matches languages by ISO code. If the **Languages** sheet lists a language that the project doesn't have, or a different name or **Base Language** for an existing one, the import adds or updates that language. Blank translation and status cells are skipped during import, leaving the corresponding existing values unchanged. To remove existing translated text, use the [editor steps below](https://docs.arcweave.com/project-tools/localization#clear-translated-text-in-the-editor). After translating, they must save the spreadsheet file as `.xls` or `.xlsx` and forward the translated spreadsheet file to the Arcweave project owner / editor, who will then reimport it. (See [Import spreadsheet](https://docs.arcweave.com/project-tools/localization#import-spreadsheet) below.) #### View an item in Arcweave Context: Arcweave docs > Project Tools > Localization > Import localized spreadsheets > Translate spreadsheet > View an item in Arcweave To check the story context while translating, click **Open in Arcweave** in the row's **Arcweave Link** column. The translator needs [access to the project's boards](https://docs.arcweave.com/project-tools/share#access) to use these links. This import workflow uses **All languages** exports, so their links do not select a translation. After opening a link, use the [Localization menu](https://docs.arcweave.com/project-tools/localization#switch-language) to choose the language you are translating. A freshly opened project starts in its main language; navigating within an already open project keeps its current language. Keep the **Arcweave Link** column as provided and continue entering translations in the columns listed below. The links are for navigation; spreadsheet translations are applied through the import process. #### Translator access to sheets and columns Context: Arcweave docs > Project Tools > Localization > Import localized spreadsheets > Translate spreadsheet > Translator access to sheets and columns The file includes [sheets for all kinds](https://docs.arcweave.com/project-tools/export#xlsx) of project items, but the translator should focus only on the following sheets and columns. Note that `{languageIsoCode}` stands for the ISO code of a language, e.g. `en` for English. 1. **Elements** sheet: - Source `{languageIsoCode}` columns: ⚠️ The translator _should only read from these:_ - `Title - {languageIsoCode}` - `Content - {languageIsoCode}` - Translation `{languageIsoCode}` columns: ✅ The translator uses these columns to type the translation and set its status: - `Title - {languageIsoCode}` - `Content - {languageIsoCode}` - `Status - {languageIsoCode}` (see [acceptable status values](https://docs.arcweave.com/project-tools/localization#translation-status-acceptable-values) below) 1. **Connections** sheet: - Source `{languageIsoCode}` column: ⚠️ The translator _should only read from this:_ - `Label - {languageIsoCode}` - Translation `{languageIsoCode}` columns: ✅ The translator uses these columns to type the translation and set its status: - `Label - {languageIsoCode}` - `Status - {languageIsoCode}` 1. **Components**: - Source `{languageIsoCode}` column: ⚠️ The translator _should only read from this:_ - `Name - {languageIsoCode}` - Translation `{languageIsoCode}` columns: ✅ The translator uses these columns to type the translation and set its status: - `Name - {languageIsoCode}` - `Status - {languageIsoCode}` #### Translation status acceptable values Context: Arcweave docs > Project Tools > Localization > Import localized spreadsheets > Translate spreadsheet > Translation status acceptable values The translator can mark their progress by setting the Status column with any of the following values: - `untranslated`: Untranslated - `progress`: In progress - `review`: For review - `final`: Final Enter these values exactly as shown, in lowercase. Any other value makes the import fail. #### Clear translated text in the editor Context: Arcweave docs > Project Tools > Localization > Import localized spreadsheets > Translate spreadsheet > Clear translated text in the editor [Switch to the translation language](https://docs.arcweave.com/project-tools/localization#switch-language), then clear the text in Arcweave: - **Element titles, element content, and connection labels:** double-click the field, remove the translated text, and click outside the field to save. - **Component names:** right-click the component in the sidebar's **Components** section, select **Rename**, clear the name, and press **Enter**. After clearing a translation, the editor may display source text as a placeholder. [Set the translation status](https://docs.arcweave.com/project-tools/localization#translation-status) separately if needed; clearing text does not reset it. ### Import spreadsheet Context: Arcweave docs > Project Tools > Localization > Import localized spreadsheets > Import spreadsheet The project owner / editor imports the translated spreadsheet as follows: 1. Open the **Localization** drop-down menu. 2. Select **Import XLSX**. ![Arcweave's project environment. The Localization menu is open and an orange rectangle is emphasizing the Import XLSX option.](https://docs.arcweave.com/assets/localization-import-xlsx.Bl6z-PYd.png) 3. Click **Import from Excel** ![Arcweave's project environment. The Import from Excel modal is open and an orange rectangle is emphasizing the Import from Excel button.](https://docs.arcweave.com/assets/localization-import-2-xlsx.3jSbpgWg.png) 4. Select and upload an `.xls` or `.xlsx` file from your drive. 5. In **Confirm Import**, review the changes, grouped by language and item type, and select the ones you want to import. Only values that differ from the project are listed. ![Arcweave's project environment. The Confirm Import modal is open, where the user can select and confirm the imported content, by checking on checkboxes.](https://docs.arcweave.com/assets/localization-import-xlsx-3-confirm.Cg8ipbkm.png) 6. Click **Import**. The project will add the translation in its localization system. If the file cannot be imported, Arcweave shows **Import Failed** with a list of errors, for example a missing **Languages** sheet, a column whose ISO code is not in the **Languages** sheet, or an invalid status value. Fix the file and select it again. > ⚠️ Edits in the main language are also reimported. # Arcweave's AI tools Source: https://docs.arcweave.com/project-tools/ai-features/overview Section: Project Tools Description: Arcweave's AI tools, with access requirements, monthly AI credits and costs, prompt limits, and how to turn AI features off Arcweave's AI tools are designed to assist and enhance your creative workflow. They automate routine tasks, help refine your content, and offer intelligent suggestions to support your design process. They are built to complement your creativity, so you can focus more on what matters most in your project. All workspace plans include Arcweave's AI tools and each plan has a different monthly AI credit allowance. ## Access requirements Context: Arcweave docs > Project Tools > Arcweave's AI tools > Access requirements To use any AI tool, including the Design Assistant, you need [permission to edit the project](https://docs.arcweave.com/workspaces/roles). AI must also be [enabled for the workspace](https://docs.arcweave.com/project-tools/ai-features/overview#toggle-ai-features), and the workspace must have enough credits for the action. ## Monthly AI credits Context: Arcweave docs > Project Tools > Arcweave's AI tools > Monthly AI credits Credits are shared across the workspace and reset at **00:00 UTC on the first day of each calendar month**, independently of your subscription's billing date. | Workspace plan | Monthly AI credits | | -------------- | ----------------------------------------------- | | **Basic** | 25 per workspace | | **Pro** | 100 per [seat](https://docs.arcweave.com/workspaces/billing-plans#seats) | | **Team** | 300 per [seat](https://docs.arcweave.com/workspaces/billing-plans#seats) | ## AI credit costs Context: Arcweave docs > Project Tools > Arcweave's AI tools > AI credit costs Each AI action consumes credits from the workspace's monthly allowance: - **Design Assistant**: 1 AI credit per message, however many steps the assistant takes - **Element Generator**: 1 AI credit per generation - **Element Enhancer**: 1 AI credit per enhancement - **Image Generator**: 5 AI credits per image Arcweave shows each action's credit cost in the interface. If your workspace does not have enough credits left for an action, Arcweave blocks it and shows the reset date. If an action fails, for example because the AI service returns an error, its credits are not consumed. A Design Assistant message is charged once its first edit succeeds or its answer completes, so a message that fails or is stopped after making edits, or while an edit is being applied, still uses its credit. See [Design Assistant AI credits](https://docs.arcweave.com/project-tools/ai-features/design-assistant#ai-credits). ![Arcweave's project environment, showing the AI tooltip for the Auto-generate cover action, which displays the action's AI credit cost.](https://docs.arcweave.com/assets/ai-credits-tooltip.BT3BdsFQ.png) Users with **Manage billing** or **Manage workspace** permission, such as workspace Owners, can track current usage from the [Billing](https://docs.arcweave.com/workspaces/billing#ai-usage) section. ## Prompt limits Context: Arcweave docs > Project Tools > Arcweave's AI tools > Prompt limits The prompt fields in the editor have the following limits: | AI tool | Maximum prompt length | | ----------------------------------------------------------------- | ---------------------------- | | [Design Assistant](https://docs.arcweave.com/project-tools/ai-features/design-assistant) | 2,000 characters per message | | [Element Generator](https://docs.arcweave.com/project-tools/ai-features/element-generator) | 200 characters | | [Element Enhancer](https://docs.arcweave.com/project-tools/ai-features/element-enhancer) | 200 characters | | [Image Generator](https://docs.arcweave.com/project-tools/ai-features/image-generator) | 3,000 characters | ## Vision for the future Context: Arcweave docs > Project Tools > Arcweave's AI tools > Vision for the future Arcweave is committed to staying informed about the ethical, social, and technological implications of generative AI. We strive to provide powerful tools while respecting user data, privacy, and creative integrity. For more, visit our [AI approach page](https://arcweave.com/ai). ## Toggle AI features Context: Arcweave docs > Project Tools > Arcweave's AI tools > Toggle AI features The **Workspace AI functionality** toggle allows you to enable or disable all AI-powered tools within your workspace. Turning it off disables the entire suite, including the Design Assistant, Element Generator, Element Enhancer, and Image Generator. AI functionality is enabled by default for new workspaces. Changing it requires the **Manage workspace** permission. To toggle the AI functionality: 1. Open your **Workspace** and go to **Settings**. 2. Locate the **Workspace AI functionality** toggle. 3. Switch it on / off. 4. Click **Save** in the unsaved changes bar at the bottom of the window. # Design Assistant Source: https://docs.arcweave.com/project-tools/ai-features/design-assistant Section: Project Tools > AI tools Description: How to use the AI assistant in your Arcweave projects The **Design Assistant** helps you explore, brainstorm, and edit your project. Ask it about your story or about Arcweave, or ask it to make changes, such as creating elements, connecting them, or reorganizing boards. The Design Assistant reads your project's live data whenever it needs it, so its answers reflect the project's current state. It also uses the open board and up to 50 selected items as context. A badge above the input shows the board's name and how many items are selected, for example _Main · 2 selected_. ## Video tutorial Context: Arcweave docs > Project Tools > AI tools > Design Assistant > Video tutorial Video: https://www.youtube.com/watch?v=N9CS0Ihs1F8 ## Access the Design Assistant Context: Arcweave docs > Project Tools > AI tools > Design Assistant > Access the Design Assistant The Design Assistant follows the shared [AI access requirements](https://docs.arcweave.com/project-tools/ai-features/overview#access-requirements). To access the Design Assistant: 1. Click on the **Design Assistant** button (sparkles icon) on the right of the top menu. 2. Type a question or a request of up to **2,000 characters** in the chat interface. A character counter appears as you approach the limit. 3. Press **Enter** or click the **send** button (arrow icon). To add a new line without sending, press **Shift+Enter**. Press **Esc** while typing to close the Design Assistant. > ℹ️ Each Design Assistant message costs **1 AI credit** from your workspace's monthly allowance. See [AI credits](https://docs.arcweave.com/project-tools/ai-features/design-assistant#ai-credits) below. ### Suggested prompts Context: Arcweave docs > Project Tools > AI tools > Design Assistant > Access the Design Assistant > Suggested prompts When the conversation is empty, the Design Assistant suggests a few prompts. The suggestions depend on whether your project is blank: - **Blank project** (no elements, components, or variables yet): _Draft a short interactive story_, _Create a character_, _Set up an example quest_, and _How do variables and branches work?_ - **Project with content**: _Summarize this project_, _Check my story for issues_, _Summarize this board_, and _Suggest a better board structure_. Clicking a suggestion fills the input with a more detailed prompt, without sending it. Edit the prompt if you want to, then send it. ## Make edits Context: Arcweave docs > Project Tools > AI tools > Design Assistant > Make edits When you ask for a change, the Design Assistant applies it directly to your project. As the note below the input says, **edits apply immediately**: there is no preview or approval step. The Design Assistant is designed to change the project only when you clearly ask it to, not when you ask a question or for suggestions. The Design Assistant can create, edit, and delete: - [Boards](https://docs.arcweave.com/project-items/boards) and board folders - [Elements](https://docs.arcweave.com/project-items/elements), including their [covers](https://docs.arcweave.com/project-items/elements#element-covers), [attributes](https://docs.arcweave.com/project-items/attributes), attached [components](https://docs.arcweave.com/project-items/components), and [audio](https://docs.arcweave.com/project-items/assets/audio) - [Connections](https://docs.arcweave.com/project-items/connections) and their [labels](https://docs.arcweave.com/project-items/labels) - [Branches](https://docs.arcweave.com/project-items/branches) and their conditions, and [jumpers](https://docs.arcweave.com/project-items/jumpers) - [Notes](https://docs.arcweave.com/project-items/notes) - [Variables](https://docs.arcweave.com/project-items/variables/overview) - [Components](https://docs.arcweave.com/project-items/components), their attributes and covers, and component folders It can also move boards and components between folders, and reorder boards, components, elements, an element's choices, variables, attributes, attached components and audio, and else-if conditions. It can set the [starting element](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#set-play-mode-start), edit the [Play Mode custom CSS](https://docs.arcweave.com/project-tools/play-mode/styling-reference), and rename, move, or delete existing [assets](https://docs.arcweave.com/project-items/assets/overview) and create asset folders. The Design Assistant works under your own project permissions, and only in the open project. It can read [comments](https://docs.arcweave.com/project-items/comments) but not write them. It cannot upload or download files, export, or delete the project. To use a new image or audio file, upload it to the asset library first, then ask the Design Assistant to use it. Edits go through the same validation as edits you make yourself, and collaborators see them as they happen. The Design Assistant checks Arcscript before saving it in element content, labels, and branch conditions; an invalid script fails without changing the project. Content edits are recorded in [History](https://docs.arcweave.com/project-tools/history), which is available in Team workspaces. Play Mode CSS is saved in the project settings instead, without a History entry; fully reload Play Mode to see the new styles. > ⚠️ Make your request specific, and check the result in your project. The Design Assistant can misread a request. To undo its edits, change the items back yourself or, if your workspace includes [History](https://docs.arcweave.com/project-tools/history), restore an earlier version. A single request can involve a limited number of steps. For a large request, such as copying a whole board, the Design Assistant may stop before finishing. Its edits so far are kept; ask it to continue. ## Activity list Context: Arcweave docs > Project Tools > AI tools > Design Assistant > Activity list While it works, the Design Assistant lists each step above its answer, for example _Reading element_ or _Creating connection_. For elements, boards, components, and variables, a step that changes the item also shows its name. - Once the request finishes, completed lookups, such as reading project data or searching the documentation, are grouped under **Looked up N sources**. Click it to expand the list. - Click a step that changed an item to show it in the project (tooltip: **Show in project**). Arcweave zooms to board items and opens the dialog of a component or variable. Steps for folders, assets, and Play Mode CSS don't link anywhere. A step can also show one of these labels: - **Failed**: the step didn't apply. Click the label to see the error details. - **Recovered**: the step failed, but a later step in the same request retried it successfully. Click the label to see the original error. - **Unconfirmed**: the request ended before this step reported back, for example because you stopped it. Check the project to see whether the change was applied. - **Deleted**: the item that this step changed no longer exists in the project, so the step no longer links to it. ## Interrupt the generation Context: Arcweave docs > Project Tools > AI tools > Design Assistant > Interrupt the generation If you want to stop the Design Assistant while it is working, click the **stop** button (circle icon). Stopping keeps everything the Design Assistant has done so far: edits that were already applied stay in your project, and the conversation shows **Stopped**, with any partial answer. A step that was still running is marked **Unconfirmed**. Requests are never retried automatically, so check the project before you send the request again. > ℹ️ The Assistant can make mistakes, so be sure to verify important information in advance. ## Copy and clear the conversation Context: Arcweave docs > Project Tools > AI tools > Design Assistant > Copy and clear the conversation Hover over a message, or move the keyboard focus to it, to show its **copy** button: - **Copy message** copies your question exactly as you typed it. - **Copy answer** copies a finished answer as plain text. To start over, click **Clear conversation** (eraser icon) at the top of the panel, then confirm with **Clear**. Clearing removes the conversation from the panel only: edits the Design Assistant already made stay in your project. You cannot clear the conversation while the Design Assistant is working. The conversation is also cleared when you switch to another project. > ℹ️ Each request includes your new message and up to four previous exchanges. For a follow-up on something older, repeat the details in your request. ## AI credits Context: Arcweave docs > Project Tools > AI tools > Design Assistant > AI credits Each message you send costs **1 AI credit**, however many steps the Design Assistant takes to handle it. The credit is charged when the first edit succeeds or when the answer completes. If the request fails or you stop it before either happens, no credit is used, unless an edit was still being applied: that edit may have been saved, so the credit is kept. Check the project before you try again. See [AI credit costs](https://docs.arcweave.com/project-tools/ai-features/overview#ai-credit-costs) for the other AI tools. ## Knowledge base Context: Arcweave docs > Project Tools > AI tools > Design Assistant > Knowledge base Ask the Design Assistant questions about the following topics, or ask it to make changes to your project: - Your project and story - Arcscript - Arcweave functionality - Arcweave documentation ## Prompt examples Context: Arcweave docs > Project Tools > AI tools > Design Assistant > Prompt examples ### Project-related Context: Arcweave docs > Project Tools > AI tools > Design Assistant > Prompt examples > Project-related With _The Castle_ (the built-in example project) in mind, here are some examples of questions you could ask the Design Assistant: - _How can the player find the Crusader's name?_ - _Where does the player defeat the Crusader, and how?_ - _Where is the element called "Battle?"_ - _What is the usage of the health variable, and what is its initial value?_ - _Do you have any recommendations on how I can continue the story?_ - _Do you find any plot holes?_ ### Edits Context: Arcweave docs > Project Tools > AI tools > Design Assistant > Prompt examples > Edits Ask for changes in plain language. You can refer to the open board or to the items you have selected: - _Add a choice to the selected element that leads to a new element where the player hides._ - _Create a `gold` variable starting at 0, and add 10 gold in the element called "Treasure."_ - _Rename the "Intro" board to "Prologue" and move it into a folder called "Act 1."_ - _Create a component called "Innkeeper" with attributes for appearance and personality._ - _Set the element called "Gate" as the starting element._ ### Arcweave-related Context: Arcweave docs > Project Tools > AI tools > Design Assistant > Prompt examples > Arcweave-related Please use Arcweave terminology where applicable. - _How can I [export my project to Unity](https://docs.arcweave.com/integrations/unity)?_ - _How does the [`visits`](https://docs.arcweave.com/project-items/arcscript#visits) function work?_ - _Give me a list of all the [elements](https://docs.arcweave.com/project-items/elements) in the Main [Board](https://docs.arcweave.com/project-items/boards)._ - _How do I attach an [audio asset](https://docs.arcweave.com/project-items/assets/audio)?_ - _How do these AI tools work?_ # Element Enhancer Source: https://docs.arcweave.com/project-tools/ai-features/element-enhancer Section: Project Tools > AI tools Description: How to enhance and edit your elements using Arcweave's AI tools The Element Enhancer refines and improves existing elements based on your guidance. ## Data collection Context: Arcweave docs > Project Tools > AI tools > Element Enhancer > Data collection The Element Enhancer gathers context from the following sources: - Your prompt text (up to 200 characters) - The current element's title and content. - The elements immediately preceding the current in the flow. - Components [mentioned](https://docs.arcweave.com/project-tools/mentions) in your prompt, and their [attributes](https://docs.arcweave.com/project-items/attributes). - All of the above elements' components and their attributes. These components can be: - Attached to any of the elements. - Mentioned in any of the element's title or content. This context is used as input for the AI, ensuring the generated result aligns with your project's structure and tone. ## Use the Element Enhancer Context: Arcweave docs > Project Tools > AI tools > Element Enhancer > Use the Element Enhancer The Element Enhancer follows the shared [AI access requirements](https://docs.arcweave.com/project-tools/ai-features/overview#access-requirements). To enhance an element using the Element Enhancer, follow the next steps: 1. Right-click on the element and choose **AI > "Enhance element"** from the menu. 2. Type your prompt in the input field, to guide the enhancement process. You can do any of the following: - Use the prompt box to guide the story in your desired direction. - @-[mentioning](https://docs.arcweave.com/project-tools/mentions) components to include their attributes in the context. 3. Click **Enhance**. The element's title and content will be rewritten according to the context you provided. The element's attached components are replaced with the components the AI selects from that context. > ℹ️ If you are not satisfied with the outcome, you can **undo** (Ctrl/Cmd+Z) to revert to your original content. > ℹ️ Each enhancement costs **1 AI credit** from your workspace's monthly allowance. See [monthly AI credits by workspace plan](https://docs.arcweave.com/project-tools/ai-features/overview#monthly-ai-credits). # Element Generator Source: https://docs.arcweave.com/project-tools/ai-features/element-generator Section: Project Tools > AI tools Description: How to generate elements using Arcweave's AI tools The Element Generator creates a new element based on the context you provide in your prompt, in a way similar to the [Element Enhancer](https://docs.arcweave.com/project-tools/ai-features/element-enhancer). The difference is that it creates a new element, complete with a suggested title, content, and component mentions tailored to your project's needs. Video: https://www.youtube.com/watch?v=x86KqQZuKJI ## Data collection Context: Arcweave docs > Project Tools > AI tools > Element Generator > Data collection The Element Generator gathers context from the following sources: - Your prompt text (up to 200 characters) - The current element's title and content. - The elements immediately preceding the current in the flow. - Components [mentioned](https://docs.arcweave.com/project-tools/mentions) in your prompt, and their [attributes](https://docs.arcweave.com/project-items/attributes). - All of the above elements' components and their attributes. These components can be: - Attached to any of the elements. - Mentioned in any of the element's title or content. This context is used as input for the AI, ensuring the generated result aligns with your project's structure and tone. ## Use the Element Generator Context: Arcweave docs > Project Tools > AI tools > Element Generator > Use the Element Generator The Element Generator follows the shared [AI access requirements](https://docs.arcweave.com/project-tools/ai-features/overview#access-requirements). To generate an element using the Element Generator, follow the next steps: 1. Right-click on an element and choose **AI > "Generate element"** from the menu. 2. Type your prompt in the input field, to guide the generation process. You can do any of the following: - Use the prompt box to guide the story in your desired direction. - @-[mentioning](https://docs.arcweave.com/project-tools/mentions) components to include their attributes in the context. 3. Click **Generate**. A new element will be generated, with its title and content written according to the context you provided. It will be automatically connected with the element you have selected. > ℹ️ Each generated element costs **1 AI credit** from your workspace's monthly allowance. See [monthly AI credits by workspace plan](https://docs.arcweave.com/project-tools/ai-features/overview#monthly-ai-credits). # Image Generator Source: https://docs.arcweave.com/project-tools/ai-features/image-generator Section: Project Tools > AI tools Description: How to generate image assets using Arcweave's AI tools The Image Generator lets you create images for your prototypes using generative AI. You can access it from several places in the app: - The **Assets** section (left sidebar) - When setting an element cover - When setting a component cover The Image Generator follows the shared [AI access requirements](https://docs.arcweave.com/project-tools/ai-features/overview#access-requirements). Prompts entered in the Image Generator can contain up to **3,000 characters**. > ℹ️ Each image generation costs **5 AI credits** from your workspace's monthly allowance. See [monthly AI credits by workspace plan](https://docs.arcweave.com/project-tools/ai-features/overview#monthly-ai-credits). ![Arcweave's project environment, showing the AI tooltip for the Auto-generate cover action, which displays the Image Generator credit cost.](https://docs.arcweave.com/assets/ai-credits-tooltip.BT3BdsFQ.png) Video: https://www.youtube.com/watch?v=mBlagOinKCU ## AI settings Context: Arcweave docs > Project Tools > AI tools > Image Generator > AI settings In your [project settings](https://docs.arcweave.com/project-tools/settings) (accessible from the top menu), you'll find an option for accessing the **AI Settings**. 1. Click the **Settings** cog and select **AI Settings...** from the dropdown. 2. Optionally add project-wide guidance for image generation: - Fill in the **Image Generation Guidelines** to define the art style rules for the images you generate. You can specify guidelines, preferred styles, or any other instructions you want applied to all image creations across the app. - Drag image assets from the **Assets** sidebar into **Attached Style References** to use them as visual guides for palette, mood, lighting, texture, and rendering style. > ℹ️ Attached style references are treated as style guides by default. They do not cause Arcweave to copy the specific characters, props, places, or compositions shown in those images unless you explicitly ask for that in your prompt. > ℹ️ If you add attached style references, you can mention them by name in your prompt to steer the generated result more precisely. ## Use from the Assets section Context: Arcweave docs > Project Tools > AI tools > Image Generator > Use from the Assets section ![Arcweave's project environment, showing the context menu in the assets section (revealed by right-clicking an asset). An orange rectangle emphasizes the option to generate an image asset.](https://docs.arcweave.com/assets/assets-generate-image.wS1dcQGR.png) 1. Open the **Assets** tab in the left sidebar. 2. Click the **Create asset** button (image icon with a plus) in the top-right corner of the Assets panel, or right-click inside the Assets panel. 3. Select **Generate asset...** 4. Choose the image size: - **Square**: 1024 x 1024 - **Vertical**: 1024 x 1536 - **Horizontal**: 1536 x 1024 - **Custom**: Enter a width and height. Each side must be a multiple of 16 pixels and at most 3,840 pixels, the image must contain between 655,360 and 8,294,400 pixels, and the longest side can be at most 3 times the shortest. 5. Optionally, check **Transparent background (PNG)**. 6. Enter a prompt describing what you want to generate. 7. Click **Generate**. 8. After the image is generated, click **Import in Asset List** to add it to the project's Assets section. > ℹ️ To generate an image directly into an asset folder, right-click the folder (or click the **+** that appears when you hover over it) and select **Generate asset...** ## Use from elements Context: Arcweave docs > Project Tools > AI tools > Image Generator > Use from elements ### Set covers Context: Arcweave docs > Project Tools > AI tools > Image Generator > Use from elements > Set covers 1. Right-click an element and choose **Cover > Set cover**. ![Element context menu with the Cover > Set cover option highlighted.](https://docs.arcweave.com/assets/element-set-cover-menu.CCl43IkV.png) 2. Switch to the **Generate** tab. ![Set cover modal with the Generate tab selected.](https://docs.arcweave.com/assets/element-set-cover-modal-generate.8bMrfeKi.png) 3. Choose the image size, then enter a detailed prompt. 4. Click **Generate**. 5. Leave **Use as cover** enabled and click **Import in Asset List** to import the image and assign it as the element cover. ### Auto-generate covers Context: Arcweave docs > Project Tools > AI tools > Image Generator > Use from elements > Auto-generate covers 1. Right-click an element. 2. Select **AI > Auto-generate cover**. ![Element context menu with the AI > Auto-generate cover option highlighted.](https://docs.arcweave.com/assets/element-set-cover-menu-autogenerate.D4c_9tEn.png) 3. Your image will be created automatically in the horizontal size (1536 x 1024), imported into the Assets section, and set as the element cover. > ℹ️ The context used when auto-generating element covers is defined by the element's title and content, along with the [AI Settings](https://docs.arcweave.com/project-tools/settings#ai-settings), including both your text guidelines and any attached style references. ## Use from components Context: Arcweave docs > Project Tools > AI tools > Image Generator > Use from components ### Set covers Context: Arcweave docs > Project Tools > AI tools > Image Generator > Use from components > Set covers 1. Open the component. 2. Hover over the cover area and click **Change cover** in its top-right corner. 3. Switch to the **Generate** tab (the last tab). 4. Choose the image size, then enter a detailed prompt. 5. Click **Generate**. 6. Leave **Use as cover** enabled and click **Import in Asset List** to import the image and assign it as the component cover. > ℹ️ The context used when generating images for assets, elements, and components is defined by your prompt and the [AI Settings](https://docs.arcweave.com/project-tools/settings#ai-settings), including both your text guidelines and any attached style references. # Share your project Source: https://docs.arcweave.com/project-tools/share Section: Project Tools Description: Give members, guests, and visitors access to a project, share links to items, make projects public, and embed Play Mode There are three ways to access an Arcweave project: - [Workspace members](https://docs.arcweave.com/workspaces/roles#workspace-members) have access to all projects in the workspace. - [Workspace guests](https://docs.arcweave.com/workspaces/roles#workspace-guests) can access the specific projects they are invited to. - [Project visitors](https://docs.arcweave.com/workspaces/roles#project-visitors) can access a public project via its link—see [Make a project public](https://docs.arcweave.com/project-tools/share#make-a-project-public). ## Access Context: Arcweave docs > Project Tools > Share your project > Access For more information on these roles, see the [Roles](https://docs.arcweave.com/workspaces/roles) page in the **Workspaces** section of this documentation. ### Workspace member Context: Arcweave docs > Project Tools > Share your project > Access > Workspace member Workspace members automatically have access to all projects in the workspace, based on their assigned **roles** and **permissions**. See [Workspace members](https://docs.arcweave.com/workspaces/roles#workspace-members). ### Workspace guest Context: Arcweave docs > Project Tools > Share your project > Access > Workspace guest Users with the **Manage memberships** permission (by default, workspace owners) can share a project with people outside the workspace by assigning them the role of **project commenter** or **project editor**—see [Workspace guests](https://docs.arcweave.com/workspaces/roles#workspace-guests) > [Invite guests](https://docs.arcweave.com/workspaces/roles#invite-guests). ### Project visitor Context: Arcweave docs > Project Tools > Share your project > Access > Project visitor A project or just its Play Mode can be made **public**, allowing anyone with the link to access it—see [Project visitors](https://docs.arcweave.com/workspaces/roles#project-visitors). ## Share an item or board position Context: Arcweave docs > Project Tools > Share your project > Share an item or board position Use **Copy link** to send someone directly to a board or item in the project's current language. Recipients need access to the project's boards through one of the [roles described above](https://docs.arcweave.com/project-tools/share#access). Copying a link does not change project access; **Can play only** access does not allow someone to open items in the editor. ### Copy an item link Context: Arcweave docs > Project Tools > Share your project > Share an item or board position > Copy an item link 1. Open the item's menu using one of the locations below. 2. Select **Copy link**. Arcweave displays **Link copied** when the URL is on your clipboard. 3. Paste the link into your message or document. | Item | Where to find Copy link | | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Board](https://docs.arcweave.com/project-items/boards#copy-a-board-link) | Right-click the board in the sidebar's **Boards** section. | | [Element](https://docs.arcweave.com/project-items/elements#copy-an-element-link) | Right-click the element on the board or in the sidebar's **Boards** section. | | [Jumper](https://docs.arcweave.com/project-items/jumpers#copy-a-jumper-link), [note](https://docs.arcweave.com/project-items/notes#copy-a-note-link), or [branch](https://docs.arcweave.com/project-items/branches#copy-a-branch-link) | Right-click the item on the board. | | [Connection](https://docs.arcweave.com/project-items/connections#copy-a-connection-link) | Right-click the connection or its label on the board. | | [Component](https://docs.arcweave.com/project-items/components#copy-a-component-link) | Right-click the component in the sidebar's **Components** section, open the component's **three-dot (•••)** header menu, or right-click a component reference attached to an element or included in a **Component List** attribute. | On the board, **Copy link** is available when exactly one supported item is selected. If several items are selected, clear the selection first. Folders, unsaved drafts, comments, attributes, and variables do not have a **Copy link** action. People with read-only access to the project's boards can also copy links. Editing actions still require the appropriate permissions. ### Open a copied link Context: Arcweave docs > Project Tools > Share your project > Share an item or board position > Open a copied link - An element, jumper, note, or branch link opens its board and centers the item. A jumper link takes you to the jumper itself. - A connection link opens the connection's area on its board. - A board link opens that board and restores its saved position and zoom. - A component link opens the component's dialog, including when copied from an attached reference. The link selects the language that was active when it was copied, entering [Translation Mode](https://docs.arcweave.com/project-tools/localization#main-language-translations) for a translation. If that language is no longer available, or the workspace does not support that translation, the link opens without changing the current language. If the item has been deleted, Arcweave reports that the linked item could not be found. ### Share a board position Context: Arcweave docs > Project Tools > Share your project > Share an item or board position > Share a board position After a board item link opens, the browser URL contains the board's position and zoom. Copy that URL to share the current view, or refresh to return to the same view. To share the item and current language again, use its **Copy link** action. A board's **Copy link** action identifies the board; use the browser URL to share a particular position and zoom. ### Share a link from a spreadsheet Context: Arcweave docs > Project Tools > Share your project > Share an item or board position > Share a link from a spreadsheet You can also copy an **Open in Arcweave** hyperlink from an [XLSX export](https://docs.arcweave.com/project-tools/export#open-items-from-an-xlsx-export) to send someone to an item or its relevant dialog. Links from single-language exports select the exported language. To preserve that destination and language when sharing, copy the original hyperlink from the spreadsheet. ## Make a project public Context: Arcweave docs > Project Tools > Share your project > Make a project public To enable public link access to your project: 1. Open the project. 2. Click **Share** in the top menu. 3. In the Share modal, use the dropdown next to **Anyone with the link** to control public access. Select one of the following options: - **Can view & play**: Grants access to both the project's boards and Play Mode. - **Can play only**: Grants access only to the project's Play Mode. - **Has no access**: Prevents any public access to the project. 4. Click **copy link**, under **Anyone with the link**, to copy the project's URL to your clipboard for sharing. With **Can play only**, the copied URL opens Play Mode. Only owners and editors can change the public access option. ![Arcweave's project screen showing the Share modal](https://docs.arcweave.com/assets/share-public.-msafp79.png) > ✅ Users accessing a project through a public link are called [project visitors](https://docs.arcweave.com/workspaces/roles#project-visitors). They do _not_ need an Arcweave account to view or play the project. ## Embed Play Mode in HTML Context: Arcweave docs > Project Tools > Share your project > Embed Play Mode in HTML Projects with public Play Mode provide an **HTML embed code snippet**, enabling the project to be played in its own **iframe window** on any webpage. ### Embed example Context: Arcweave docs > Project Tools > Share your project > Embed Play Mode in HTML > Embed example The following is a public project created by the Arcweave team: Embedded content: https://arcweave.com/embed/MWEZebKl2g/play The code for the above embed is the following: ```html ``` > ℹ️ This code has been customized. See [Customize embed code](https://docs.arcweave.com/project-tools/share#customize-embed-code), below. ### Copy embed code Context: Arcweave docs > Project Tools > Share your project > Embed Play Mode in HTML > Copy embed code To copy a project's embed code: 1. Open the project and click **Share** in the top menu. 2. Make the project or its Play Mode [public](https://docs.arcweave.com/project-tools/share#make-a-project-public). 3. Click **Get embed code** at the bottom of the Share modal. 4. In the embed dialog, click **Copy code**. 5. Paste the code from your clipboard into the body of your webpage. > ℹ️ Only the Play Mode of a project can be embedded; the Arcweave project interface cannot. > ⚠️ The embed window has a reduced [Play Mode menu](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#play-mode-menu) with **Restart**, full screen, audio, and language controls; the language menu appears only if the project has more than one language. Other Play Mode features, such as the [Debugger](https://docs.arcweave.com/project-tools/play-mode/debugger), the [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor), **Edit content**, and **Share**, are not available in the embed window. The embed uses the project's saved custom CSS. ### Arcweave watermark Context: Arcweave docs > Project Tools > Share your project > Embed Play Mode in HTML > Arcweave watermark The embed dialog includes a **Show Arcweave watermark** checkbox. - In [Basic](https://docs.arcweave.com/workspaces/billing-plans) workspaces, the watermark is always shown. - In [Pro and Team](https://docs.arcweave.com/workspaces/billing-plans) workspaces, you can uncheck this option to hide the watermark from embedded Play Mode. This option is saved with the project and applies to all of its embeds; the embed code does not change. ### Customize embed code Context: Arcweave docs > Project Tools > Share your project > Embed Play Mode in HTML > Customize embed code The following is the default embed code of a project: ```html ``` Replace `MWEZebKl2g` with the project's [hash](https://docs.arcweave.com/project-tools/settings#project-hash), which you can copy from **Project Settings > Properties > Project hash**. After pasting the code into your webpage's body, you can customize it as needed: - Adjust the embed window's dimensions by changing the `width` and `height` values. - Use the `style` attribute for advanced CSS control. See the previous [embed example](https://docs.arcweave.com/project-tools/share#embed-example) for such customization. > ℹ️ The `height: 100%;` property-value pair works best on host pages that include a **parent container** with defined dimensions for the embed window, such as Itch.io. > ✅ If your page includes a parent container for the embed window, adjust the parent's width and height and the window will expand automatically. ### Export as HTML for Itch.io Context: Arcweave docs > Project Tools > Share your project > Embed Play Mode in HTML > Export as HTML for Itch.io Some platforms, such as [Itch.io](https://itch.io/), require an HTML file that embeds your game directly in the browser. Follow the steps below to create a file optimized for embedding Arcweave's Play Mode. #### Step 1: Prepare the HTML file Context: Arcweave docs > Project Tools > Share your project > Embed Play Mode in HTML > Export as HTML for Itch.io > Step 1: Prepare the HTML file Open any plain-text editor and create a new file. Paste the template below into the file. (You will replace `{HASH}` with your actual project hash in the next step.) ```html ``` #### Step 2: Insert your project hash Context: Arcweave docs > Project Tools > Share your project > Embed Play Mode in HTML > Export as HTML for Itch.io > Step 2: Insert your project hash You can find your [project hash](https://docs.arcweave.com/project-tools/settings#project-hash) in the **Settings** panel. ![Arcweave's project environment, with an orange arrow pointing at the cog icon, in the top menu.](https://docs.arcweave.com/assets/settings_cog.CmlNUThz.png) 1. Click the **cog icon** on the left side of the top menu. 2. Open the **Properties** section. 3. Locate **Project hash** and click the **clipboard** icon to copy it. Insert your hash in place of `{HASH}` within the HTML page created in the previous step. #### Step 3: Save as HTML Context: Arcweave docs > Project Tools > Share your project > Embed Play Mode in HTML > Export as HTML for Itch.io > Step 3: Save as HTML Save the file with the `.html` extension. #### Step 4: Upload to Itch.io Context: Arcweave docs > Project Tools > Share your project > Embed Play Mode in HTML > Export as HTML for Itch.io > Step 4: Upload to Itch.io Upload the HTML file to your Itch.io project page. Your Arcweave game will then load and play directly within the page. # Export your project Source: https://docs.arcweave.com/project-tools/export Section: Project Tools Description: Export Arcweave projects as JSON, spreadsheets, images, Markdown, PDF, game engine files, or backups, and automate exports Arcweave supports exporting your project data to the following formats: - [JSON](https://docs.arcweave.com/project-tools/export#export-as-json) - [Spreadsheet](https://docs.arcweave.com/project-tools/export#export-as-spreadsheet) - [Image](https://docs.arcweave.com/project-tools/export#export-as-image-file) - [Game engine JSON](https://docs.arcweave.com/project-tools/export#export-for-game-engines) - [Markdown](https://docs.arcweave.com/project-tools/export#export-as-markdown) - [PDF](https://docs.arcweave.com/project-tools/export#export-as-pdf) - [Backup](https://docs.arcweave.com/project-tools/export#export-project-backup) > ✅ The [JSON](https://docs.arcweave.com/project-tools/export#export-as-json) and [Game engine JSON](https://docs.arcweave.com/project-tools/export#export-for-game-engines) exports provide the option to also export the project's **assets**. This option is selected by default. See each format below for details. > ✅ If your project has multiple languages (see [Localization](https://docs.arcweave.com/project-tools/localization)), you have the option to select which translations are to be included in the export. See each export format below for details. Language options appear only in workspaces that support Localization ([Team](https://docs.arcweave.com/workspaces/billing-plans)); other workspaces export the main language. ## Export project Context: Arcweave docs > Project Tools > Export your project > Export project To export your Arcweave project: 1. Open the project. 2. Click the **Export project** button in the project's top menu. 3. Select the tab that is relevant to the desired format (see following sections). 4. Click **Export**. Exporting requires the **Export projects** permission, which owners and editors have by default. Exporting a [project backup](https://docs.arcweave.com/project-tools/export#export-project-backup) also requires the **Export projects backup** permission; see [Roles](https://docs.arcweave.com/workspaces/roles). Arcweave remembers each project's export options for the next export. ## Export as JSON Context: Arcweave docs > Project Tools > Export your project > Export as JSON Exporting as **JSON** produces a `.json` file containing all the project's story data. > ✅ Arcweave JSON files can be imported into a workspace (Basic, Pro, and Team). See [Import projects](https://docs.arcweave.com/workspaces/projects#import-projects). You can study the schema of Arcweave's JSON under the [Integrations](https://docs.arcweave.com/integrations/json) section. > ℹ️ In the JSON format, text content is exported in **html encoding**. ### Export specific boards Context: Arcweave docs > Project Tools > Export your project > Export as JSON > Export specific boards By default, Arcweave exports all boards of your project. To export specific boards: 1. Go to the section titled **Boards to export**. 2. Choose **Select boards** instead of **All boards**. 3. Select the boards you want to be included in the JSON file. Board selection filters boards and their board items. Components, attributes, assets, and global variables are still exported for the whole project, including attributes belonging to excluded boards or items. Review these collections before sharing a partial export. ### Export languages Context: Arcweave docs > Project Tools > Export your project > Export as JSON > Export languages If your project has multiple languages (see [Localization](https://docs.arcweave.com/project-tools/localization)), you can select which translations are to be included in the export: 1. Go to the section titled **Languages to export**. 2. Switch among the following: - **Current language**: The JSON includes story data only in the current language. - **All languages**: The JSON includes story data in all languages. - **Select language**: Choose the language to be included in the JSON from the dropdown. ### Include assets Context: Arcweave docs > Project Tools > Export your project > Export as JSON > Include assets To download the project's assets along with its story data (JSON file), select **Include assets** (selected by default). This produces a .zip file containing: - The story data **.json file** (`project_settings.json`) - An **assets folder** containing the project's [assets](https://docs.arcweave.com/project-items/assets/overview), with their subfolder structure matching that of the project - A **cover folder** containing the [project's cover](https://docs.arcweave.com/workspaces/projects#project-cover) (if any) The archive includes the entire project's assets, even when you select specific boards. Assets are included whether or not the selected boards use them. ### Include coordinates Context: Arcweave docs > Project Tools > Export your project > Export as JSON > Include coordinates To export the spatial layout of your boards, select **Include coordinates**. This option stores the following extra properties: - `x` and `y` position coordinates of all board items (elements, notes, jumpers, and branches). - `width`, `height`, and `autoHeight` of resizable board items (elements and notes). - `waypoints` or `controlPoints` of connections with [customized paths](https://docs.arcweave.com/project-items/connections#edit-connection-paths). With **Include coordinates** enabled, [importing the JSON file](https://docs.arcweave.com/workspaces/projects#import-projects) restores items to their original positions on each board. Without it, importing generates a new layout and uses default element/note dimensions. The [REST JSON export](https://docs.arcweave.com/rest-api/exports#json-export) always omits this layout data and has no **Include coordinates** option. > ℹ️ The `autoHeight` property is a boolean indicating whether the [element](https://docs.arcweave.com/project-items/elements#resize-elements) or [note automatically adjusts its height](https://docs.arcweave.com/project-items/notes#resize-notes) to the size of its content. ## Export as spreadsheet Context: Arcweave docs > Project Tools > Export your project > Export as spreadsheet Arcweave offers the option to export your project as a spreadsheet, in **CSV** or **XLSX** (Excel format). > ✅ XLSX spreadsheets can be imported for translating purposes into any project of a Team workspace, using the [Localization](https://docs.arcweave.com/project-tools/localization#import-localized-spreadsheets) menu. The column tables below show the single-language layout used by **Current language** and **Select language**, without language suffixes or translation-status columns. For **All languages**, see [All-languages columns](https://docs.arcweave.com/project-tools/export#all-languages-columns). ### CSV Context: Arcweave docs > Project Tools > Export your project > Export as spreadsheet > CSV Exporting in **Comma Separated Values (CSV)** produces a `.zip` file containing the following files: | Filename | Columns | | ----------------- | ----------------------------------------------------------------------------------------------- | | `Attributes.csv` | `Id`, `Custom Id`, `Component Id`, `Board Id`, `Name`, `Data`, `Type`, `RichText`, `Element Id` | | `Boards.csv` | `Id`, `Custom Id`, `Parent Id`, `Has Children`, `Name` | | `Branches.csv` | `Id`, `Board Id`, `Theme`, `Conditions` | | `Components.csv` | `Id`, `Custom Id`, `Parent Id`, `Has Children`, `Name`, `Attributes` | | `Conditions.csv` | `Id`, `Branch Id`, `Script`, `Output`, `Type` | | `Connections.csv` | `Id`, `Board Id`, `Source Id`, `Source Type`, `Target Id`, `Target Type`, `Label` | | `Elements.csv` | `Id`, `Board Id`, `Title`, `Content`, `Theme`, `Components`, `Outputs`, `Attributes` | | `Jumpers.csv` | `Id`, `Board Id`, `Element Id` | | `Notes.csv` | `Id`, `Board Id`, `Content`, `Theme` | | `Variables.csv` | `Id`, `Name`, `Type`, `Value` | > ℹ️ In the CSV export format, text content is exported in **html encoding**. > ℹ️ `Variables.csv` contains global variables. Board and component variables appear in `Attributes.csv`: `Custom Id` provides the variable name, while `Board Id` or `Component Id` links it to its owner. The owner's `Custom Id` in `Boards.csv` or `Components.csv` provides the Arcscript scope. ### XLSX Context: Arcweave docs > Project Tools > Export your project > Export as spreadsheet > XLSX [Pro and Team](https://docs.arcweave.com/workspaces/billing-plans) workspaces allow exporting your project data for Excel, producing a `.xlsx` file that contains a separate sheet for each item: | Sheet | Columns | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `Attributes` | `Id`, `Custom Id`, `Component Id`, `Board Id`, `Name`, `Data`, `Type`, `RichText`, `Element Id`, `Arcweave Link` | | `Boards` | `Id`, `Custom Id`, `Parent Id`, `Has Children`, `Name` | | `Branches` | `Id`, `Board Id`, `Theme`, `Conditions`, `Arcweave Link` | | `Components` | `Id`, `Custom Id`, `Parent Id`, `Has Children`, `Name`, `Attributes`, `Arcweave Link` | | `Conditions` | `Id`, `Branch Id`, `Script`, `Output`, `Type`, `Arcweave Link` | | `Connections` | `Id`, `Board Id`, `Source Id`, `Source Type`, `Target Id`, `Target Type`, `Label`, `Arcweave Link` | | `Elements` | `Id`, `Board Id`, `Title`, `Content`, `Theme`, `Components`, `Outputs`, `Attributes`, `Arcweave Link` | | `Jumpers` | `Id`, `Board Id`, `Element Id`, `Arcweave Link` | | `Notes` | `Id`, `Board Id`, `Content`, `Theme`, `Arcweave Link` | | `Variables` | `Id`, `Name`, `Type`, `Value`, `Arcweave Link` | | `Languages` (All languages only) | `Name`, `ISO`, `Base Language` | > ℹ️ In the XLSX export format, text content gets exported in **html encoding**. > ℹ️ The `Variables` sheet contains global variables. Board and component variables appear in the `Attributes` sheet: `Custom Id` provides the variable name, while `Board Id` or `Component Id` links it to its owner. The owner's `Custom Id` in the `Boards` or `Components` sheet provides the Arcscript scope. > ✅ XLSX spreadsheets can be imported for translating purposes into any project of a Team workspace, using the [Localization](https://docs.arcweave.com/project-tools/localization#import-localized-spreadsheets) menu. > ℹ️ The `Languages` sheet is included when you export **All languages**. This is the format required when preparing an XLSX file for [localized spreadsheet import](https://docs.arcweave.com/project-tools/localization#import-localized-spreadsheets). ### All-languages columns Context: Arcweave docs > Project Tools > Export your project > Export as spreadsheet > All-languages columns With **All languages**, the following sheets and their CSV counterparts use these columns instead. `{languageIsoCode}` is the language's ISO code, such as `en` or `fr`. Text columns include every language; `Status` columns include only translations, never the main language. | Sheet / CSV file | First columns, in order | Following language columns, in order | | --------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Components` / `Components.csv` | `Id`, `Custom Id`, `Parent Id`, `Has Children`, `Attributes` | For each language: `Name - {languageIsoCode}`, followed by `Status - {languageIsoCode}` if it is a translation. | | `Connections` / `Connections.csv` | `Id`, `Board Id`, `Source Id`, `Source Type`, `Target Id`, `Target Type` | For each language: `Label - {languageIsoCode}`, followed by `Status - {languageIsoCode}` if it is a translation. | | `Elements` / `Elements.csv` | `Id`, `Board Id`, `Theme`, `Components`, `Outputs`, `Attributes` | All `Title - {languageIsoCode}` columns, then all `Content - {languageIsoCode}` columns, then all `Status - {languageIsoCode}` columns for translations. | Languages follow the project's language order within each group. XLSX appends one `Arcweave Link` column after these language columns and includes the `Languages` sheet. CSV includes neither `Arcweave Link` columns nor a `Languages.csv` file. Other sheets and files keep the columns listed above. ### Open items from an XLSX export Context: Arcweave docs > Project Tools > Export your project > Export as spreadsheet > Open items from an XLSX export Click **Open in Arcweave** in a row's **Arcweave Link** column to open that item in its original project. The recipient needs [access to the project's boards](https://docs.arcweave.com/project-tools/share#access). | Sheet | Where the link opens | | ------------------------------------------ | --------------------------------------------------------------- | | `Elements`, `Jumpers`, `Branches`, `Notes` | The item on its board | | `Connections` | The connection's area on its board | | `Conditions` | The branch containing the condition | | `Components` | The component's dialog | | `Attributes` | The owning element, component dialog, or board variables dialog | | `Variables` | The global variables dialog | Component folder rows have no link. Each eligible sheet has one **Arcweave Link** column, regardless of the number of exported languages. The language selected when exporting determines how the link opens: - **Current language** or **Select language**: the link selects the exported language. A translation opens in [Translation Mode](https://docs.arcweave.com/project-tools/localization#main-language-translations); the main language opens outside Translation Mode. - **All languages**: the link does not select a language. Choose the language in Arcweave's [Localization menu](https://docs.arcweave.com/project-tools/localization#switch-language). A project opened fresh starts in its main language; navigation within an already open project keeps the current language. If the linked translation is no longer available, or the workspace does not support localization, the link opens the item without changing the current language. Board item links move directly to the target. Arcweave saves the resulting position and zoom, so refreshing or reopening the board returns to that view. You can also use **Copy link** in the editor for supported items. See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position) for menu locations and the difference between an item link and the resulting browser URL. ### Exported boards Context: Arcweave docs > Project Tools > Export your project > Export as spreadsheet > Exported boards Spreadsheet exports include all boards in the project. ### Export languages Context: Arcweave docs > Project Tools > Export your project > Export as spreadsheet > Export languages If your project has multiple languages (see [Localization](https://docs.arcweave.com/project-tools/localization)), you can select which translations are to be included in the export: 1. Go to the section titled **Languages to export**. 2. Switch among the following: - **Current language**: The spreadsheet includes story data only in the current language. - **All languages**: The spreadsheet includes story data in all languages. - **Select language**: Choose the language to be included in the spreadsheet from the dropdown. ## Export as image file Context: Arcweave docs > Project Tools > Export your project > Export as image file You can export the current board as an image. This supports the following specifications: ### JPG Context: Arcweave docs > Project Tools > Export your project > Export as image file > JPG The `.jpg` format uses lossy compression and is best for lightweight exports and sharing, where smaller file size is preferred over maximum image fidelity. ### PNG Context: Arcweave docs > Project Tools > Export your project > Export as image file > PNG The `.png` format is a lossless bitmap image and is best for high-quality exports, preserving sharp text and UI details. The board background is included, so the image is not transparent. ### Image size Context: Arcweave docs > Project Tools > Export your project > Export as image file > Image size The available options for exported image size are: - Small: 1600 x 900 - Medium: 3200 x 1800 - Large: 6400 x 3600 (Pro and Team workspaces only) ### Print-friendly Context: Arcweave docs > Project Tools > Export your project > Export as image file > Print-friendly Checking the **Print-friendly** checkbox converts the picture to a light mode style, making it more suitable for printing. ### Export specific boards Context: Arcweave docs > Project Tools > Export your project > Export as image file > Export specific boards Currently, you can **only export the current board** as an image. ### Export languages Context: Arcweave docs > Project Tools > Export your project > Export as image file > Export languages If your project has multiple languages (see [Localization](https://docs.arcweave.com/project-tools/localization)), you can select which language is to be included in the export: 1. Go to the section titled **Language to export**. 2. Switch among the following: - **Current language**: The image includes story data only in the current language. - **Select language**: Choose the language to be included in the image from the dropdown. ## Export for game engines Context: Arcweave docs > Project Tools > Export your project > Export for game engines You can export your project data for direct import in other platforms; see the [Integrations](https://docs.arcweave.com/integrations/overview) section of this documentation. ### Export language Context: Arcweave docs > Project Tools > Export your project > Export for game engines > Export language If your project has multiple languages (see [Localization](https://docs.arcweave.com/project-tools/localization)), you can select which language is to be included in the export for the game engine: 1. Go to the section titled **Language to export**. 2. Select a language from the dropdown. ### Include assets Context: Arcweave docs > Project Tools > Export your project > Export for game engines > Include assets Game engine exports are `.zip` files named after the chosen engine. The archive contains the story data as `project.json`. To also include the project's assets, select **Include assets** (selected by default): the archive then adds an **assets folder** and a **cover folder**, as in the [JSON export](https://docs.arcweave.com/project-tools/export#include-assets). See [Integrations](https://docs.arcweave.com/integrations/overview) for how to import the archive. ## Export as Markdown Context: Arcweave docs > Project Tools > Export your project > Export as Markdown In [Pro and Team](https://docs.arcweave.com/workspaces/billing-plans) workspaces, you can export your story data as a [Markdown](https://www.markdownguide.org/) document. This facilitates proofreading, sharing dialogue with voice actors, etc. ### Export specific boards Context: Arcweave docs > Project Tools > Export your project > Export as Markdown > Export specific boards By default, Arcweave exports all boards and elements of your project. To export only specific boards and their elements: 1. Go to the section titled **Boards to export**. 2. Choose **Select boards** instead of **All boards**. 3. Select the boards you want to be included in the Markdown document. Board selection filters boards and their elements. The **Components** and **Variables** sections still list the whole project's components and global variables. The Markdown document uses the project's main language; this export has no language option. ### Preferences Context: Arcweave docs > Project Tools > Export your project > Export as Markdown > Preferences Boards and elements form the core content of the Markdown document and are included under the `## Boards & Elements` heading. Board attributes, including board variables, are listed with their boards. In addition, you can enable the following optional sections and features in the **Include** section. All of them are enabled by default: - **Table of contents** Adds a `## Table of Contents` section at the beginning of the document, listing all boards and elements, along with any enabled optional sections. - **Overview** Adds an `## Overview` section that displays the starting element's title and project statistics before the document's main content. - **Components** Adds a `## Components` section listing all components and their attributes, including component variables. - **Variables** Adds a `## Variables` section listing all global variables, their types, and initial values. - **Option text** Includes the text of each element's outgoing options and branch logic, so the story flow is easy to follow. When combined with **Links** (see below), the option text becomes clickable, enabling playable navigation when the document is opened in a Markdown viewer. - **Links** Creates links for in-project references (boards, elements, components) and URLs. When combined with **Option text** (see above), links enable clickable option text for playable navigation. - **Dividers** Inserts horizontal rules between sections for improved readability and printing. - **Item prefixes** Prefixes boards, elements, and components with generated IDs (B1, E1, C1, etc.) and reuses them in links for quick cross-referencing. ### Markdown example Context: Arcweave docs > Project Tools > Export your project > Export as Markdown > Markdown example The following is the Markdown document of the Interactive Fiction Example _(The Castle_—see [Project templates](https://docs.arcweave.com/workspaces/projects#project-templates)). All of the above preferences have been included during exporting. **Arcweave Markdown example** ````markdown # The Castle ## Table of Contents - [Overview](#overview) - [Boards & Elements](#boards--elements) - [B1: Main Board](#b1-main-board) - [E1: Outside Castle Monsignor](#e1-outside-castle-monsignor) - [E2: Castle Courtyard](#e2-castle-courtyard) - [E3: The small house - Overview](#e3-the-small-house---overview) - [E4: Examine the painting](#e4-examine-the-painting) - [E5: The stone passage](#e5-the-stone-passage) - [E6: The Crusader](#e6-the-crusader) - Dialogues - [B2: Crusader Dialogue](#b2-crusader-dialogue) - [E7: Dialogue start](#e7-dialogue-start) - [E8: Trying to run past](#e8-trying-to-run-past) - [E9: The Question](#e9-the-question) - [E10: Correct answer](#e10-correct-answer) - [E11: Game over](#e11-game-over) - [E12: Wrong answer](#e12-wrong-answer) - [E13: Success](#e13-success) - [B3: Credits](#b3-credits) - [Components](#components) - Characters - [C1: Crusader](#c1-crusader) - Locations - [C2: Castle Courtyard](#c2-castle-courtyard) - [C3: Castle Monsignor](#c3-castle-monsignor) - [Variables](#variables) - `score` --- ## Overview - **Starting Element:** [E1: Outside Castle Monsignor](#e1-outside-castle-monsignor) - **Elements:** 13 - **Boards:** 3 - **Components:** 3 - **Variables:** 1 --- ## Boards & Elements ### B1: Main Board #### E1: Outside Castle Monsignor **⭐ Starting Element** You have just arrived at [C3: Castle Monsignor](#c3-castle-monsignor), your uncle's home for the past 20 years. The tone of his letter was desperate, urgently asking for your help. Worried, you quickly packed your suitcase and took the first plane. Faint bird sounds break the eerie silence and a pale mist engulfs the castle hill. **To the north you can see the castle entrance.** - [Enter the castle](#e2-castle-courtyard) --- #### E2: Castle Courtyard You stand inside a small courtyard. Everything is unusually silent here. **The path leads further to the north. An abandoned house lies to your left.** - [Follow the path north](#e5-the-stone-passage) - [Enter the house](#e3-the-small-house---overview) - [Exit Castle Monsignor](#e1-outside-castle-monsignor) --- #### E3: The small house - Overview The interior looks more like an artist's studio than a house. A few abstract paintings lie scattered around. One of the paintings depicts a strange figure: a knight dressed in white, with a red cross on his chest. - [Examine the painting `if visits(examine_the_painting)` one more time `endif`](#e4-examine-the-painting) - [Back to Castle Courtyard](#e2-castle-courtyard) --- #### E4: Examine the painting The knight is guarding a mysterious gate. You see a name written above his head: > "Conrad IV, Count of Exeter" ``` if visits(the_crusader) ``` He looks just like the crusader you saw guarding the door! ``` endif ``` ``` if visits() == 1 ``` You make a mental note of the knight's name. ``` score += 2 ``` \(Your score just went up 2 points. You now have a score of ``` show(score, ".)") ``` ``` endif ``` - [Step back from the painting](#e3-the-small-house---overview) --- #### E5: The stone passage A stone passage. The sound of dripping water is echoing in the distance. You feel uneasy. - [Walk further down the path](#e6-the-crusader) - [Back to Castle Courtyard](#e2-castle-courtyard) --- #### E6: The Crusader [C1: Crusader](#c1-crusader) You reach a wooden door. In front of you stands a strange man dressed as a medieval crusader. - [Talk to the man](#e7-dialogue-start) - [Back to the stone passage](#e5-the-stone-passage) --- ### B3: Credits ### B2: Crusader Dialogue #### E7: Dialogue start The man looks at you suspiciously and tightens his sword grip. He speaks in a deep voice: _"What do you want stranger?"_ - [_"Can I pass?"_](#e9-the-question) - [_"I'll come back later."_](#e5-the-stone-passage) --- #### E8: Trying to run past As you try to run past him, he swiftly grabs you by the neck. You fight for freedom but his grip is inhumanly strong. You drift into unconsciousness... - [E11: Game over](#e11-game-over) --- #### E9: The Question _"Only he who knows my name shall pass,"_ he hisses. - (Conditional Branch) - **IF** `visits(examine_the_painting)` → [_"Conrad IV, Count of Exeter?"_](#e10-correct-answer) - **ELSE** → [_"Uh... Crusader?"_](#e12-wrong-answer) - [Try to run past him](#e8-trying-to-run-past) - [_"I'll come back later."_](#e5-the-stone-passage) --- #### E10: Correct answer At once, you utter the name you remember from the painting. In the blink of an eye, the [C1: Crusader](#c1-crusader) disappears... Almost as if he were never there. Weird. ``` score += 3 ``` \(Your score just went up 3 points. You now have a score of ``` show(score, ".)") ``` - [Open the door](#e13-success) --- #### E11: Game over Alas, you did not manage to find what lies behind the ominous door... --- #### E12: Wrong answer *"Wrong!"*he shouts. Before you can utter another word he strikes you with the back of his sword hilt. Everything fades to black... - [E11: Game over](#e11-game-over) --- #### E13: Success Congrats, you finished the example project! 🎉 Now try and make your own interactive experience. If you need help, check the [docs](https://docs.arcweave.com), our [YouTube tutorials](https://youtu.be/Dfm6dKQH3I0), or ping us on [Discord](https://discord.gg/atVXxAK)! Happy creations! 😊 --- ## Components ### C1: Crusader **Cover:** `crusader.jpeg` **Attributes:** | Attribute | Value | Type | | ------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------- | | `Real name` | Conrad IV, Count of Exeter | rich-text | | `Defeated by` | Telling him his real name, which can be found on a painting inside the small house | rich-text | | `Description` | The Crusader exists as an early obstacle to the player, introducing an atmosphere of danger and anachronism throughout the game | rich-text | --- ### C2: Castle Courtyard **Cover:** `castle` **Attributes:** | Attribute | Value | Type | | ------------- | --------------------------------- | --------- | | `Description` | The courtyard of Castle Monsignor | rich-text | --- ### C3: Castle Monsignor **Cover:** `monsignor.jpeg` **Attributes:** | Attribute | Value | Type | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | `Info` | Castle Monsignor is where the game plot and narrative take place. It was built in 1562 near Devonshire, England. The Castle is home to Lord Monsignor, the player's uncle, who has been living there for the past 20 years. The castle has recently become a time traveling portal, allowing people from the 16th century to travel to the present. | rich-text | | `Characters living here` | [C1: Crusader](#c1-crusader) | component-list | --- ## Variables | Variable | Initial Value | Type | | -------- | ------------- | ------- | | `score` | `0` | integer | ```` ## Export as PDF Context: Arcweave docs > Project Tools > Export your project > Export as PDF In [Pro and Team](https://docs.arcweave.com/workspaces/billing-plans) workspaces, you can export the current board in the Adobe Portable Document Format (PDF). This supports the following specifications: - Lossless **vector** format. - All text retains its **selectability**. ### Export specific boards Context: Arcweave docs > Project Tools > Export your project > Export as PDF > Export specific boards Currently, you can **only export the current board** as a PDF. ### Export language Context: Arcweave docs > Project Tools > Export your project > Export as PDF > Export language If your project has multiple languages (see [Localization](https://docs.arcweave.com/project-tools/localization)), you can select which language is to be included in the PDF export: 1. Go to the section titled **Language to export**. 2. Switch among the following: - **Current language**: The PDF includes story data only in the current language. - **Select language**: Choose the language to be included in the PDF from the dropdown. ### Print-friendly Context: Arcweave docs > Project Tools > Export your project > Export as PDF > Print-friendly Checking the **Print-friendly** checkbox converts the picture to a light mode style, making it more suitable for printing. ## Export project backup Context: Arcweave docs > Project Tools > Export your project > Export project backup Pro and Team workspaces allow exporting the data of their projects to an encrypted **Arcweave file** format (`.arcw`). When exporting a project as an Arcweave file: - All project data including notes, comments, assets, and [languages](https://docs.arcweave.com/project-tools/localization) are included in the exported file. - Editors and commenters are not included in the exported file. - Exported `.arcw` files can be imported into [Pro and Team](https://docs.arcweave.com/workspaces/billing-plans) workspaces. See [Import projects](https://docs.arcweave.com/workspaces/projects#import-projects) on the Projects page under Workspaces, in this documentation. ## Automate exports Context: Arcweave docs > Project Tools > Export your project > Automate exports In [Team workspaces](https://docs.arcweave.com/workspaces/billing-plans), you can export your projects using the [Export endpoints of Arcweave's REST API](https://docs.arcweave.com/rest-api/exports). # Troubleshooting Source: https://docs.arcweave.com/project-tools/troubleshooting Section: Project Tools Description: Troubleshoot slow board performance by switching the board renderer, checking Chrome extensions, and other editor checks Use this page to diagnose common issues in Arcweave's editor. ## Board performance Context: Arcweave docs > Project Tools > Troubleshooting > Board performance Arcweave boards use a GPU-accelerated renderer to draw parts of the board, such as connections. If a board feels slow to pan, zoom, select, or edit, use the checks below. ### Switch board renderer Context: Arcweave docs > Project Tools > Troubleshooting > Board performance > Switch board renderer Arcweave lets you choose between three board renderers in [Project Settings](https://docs.arcweave.com/project-tools/settings#board-renderer): - **WebGL** - **WebGPU** - **Canvas (Compatibility)** If one GPU renderer performs poorly on your current browser or hardware, the other one may work better. **WebGL** is the default. After changing the renderer, refresh the page to apply it. The setting is saved in your current browser, so it applies to every project you open there. > ℹ️ If your browser cannot run the selected renderer, Arcweave automatically tries the other GPU renderer, then **Canvas**. If neither GPU renderer is available, Arcweave shows a warning that it is using a slower compatibility renderer. Enable hardware acceleration in your browser's settings, then refresh the page for better performance. ### Which renderer should I try? Context: Arcweave docs > Project Tools > Troubleshooting > Board performance > Which renderer should I try? - **WebGL**: The most compatible option and a good default if you want predictable behavior across browsers and devices. - **WebGPU**: May offer better board performance on some systems, but results depend more on your browser, GPU, and drivers. - **Canvas (Compatibility)**: Doesn't use the GPU, so it may be slower. Use it when neither GPU renderer works on your browser or device. If one GPU renderer feels slow or unstable, switch to the other one and refresh the page. ### Check Chrome extensions Context: Arcweave docs > Project Tools > Troubleshooting > Board performance > Check Chrome extensions Some Chrome extensions can interfere with Arcweave's board rendering and input performance. If Arcweave feels slow in Chrome: - Temporarily disable extensions for Arcweave and refresh the page. - Or test the same project in an incognito window or a clean browser profile. So far we have identified two extensions that negatively impact performance in Chrome: - [Dark Reader](https://darkreader.org/) - [AdGuard](https://adguard.com/) If you need these extensions enabled in Chrome, try disabling them only for Arcweave. ### Additional checks Context: Arcweave docs > Project Tools > Troubleshooting > Board performance > Additional checks - Make sure your browser is up to date. - Close other tabs or apps that heavily use GPU acceleration. - If dragging or scrolling feels wrong rather than slow, review the [Input device](https://docs.arcweave.com/project-tools/settings#input-device) setting. # Integrations Source: https://docs.arcweave.com/integrations/overview Section: Integrations Description: Arcweave integrations, including the MCP server for AI assistants, Unity, Unreal, and Godot plugins, Arcscript interpreters, and the REST API Connect an AI assistant to your projects with the [Arcweave MCP server](https://docs.arcweave.com/integrations/mcp). The setup guide covers Claude, Codex, Cursor, GitHub Copilot, OpenCode, Antigravity, Muse Code, and other popular clients, including API keys, permissions, and troubleshooting. Arcweave also provides integrations that let you bring your project's narrative data into various platforms and game engines: - [Unity](https://docs.arcweave.com/integrations/unity) - [Unreal Engine](https://docs.arcweave.com/integrations/unreal) - [Godot Engine](https://docs.arcweave.com/integrations/godot) - [Arcscript interpreters](https://docs.arcweave.com/integrations/arcscript-interpreters) The game engine plugins read project data as [Arcweave JSON](https://docs.arcweave.com/integrations/json). You can either export it via the [Export project](https://docs.arcweave.com/project-tools/export) options within Arcweave or fetch it using the [REST API](https://docs.arcweave.com/rest-api/overview) (Team workspaces only). The Arcscript interpreters evaluate the Arcscript in that data, and you can use them to build your own integration. For custom integrations, visit the dedicated [REST API](https://docs.arcweave.com/rest-api/overview) section. It covers authentication, permissions, request and response formats, rate limits, and the complete endpoint reference for **read and write access** to projects in Team workspaces. > ✅ Fetching your project's JSON via the REST API enables **runtime story updates** and easy story testing. Detailed instructions for each option are provided on the respective integration pages. # Arcweave MCP server Source: https://docs.arcweave.com/integrations/mcp Section: Integrations Description: Connect Arcweave to Claude, Codex, Cursor, Copilot, OpenCode, Antigravity, Muse Code, and other AI assistants with the Arcweave MCP server The Arcweave **Model Context Protocol (MCP)** server lets an AI assistant work with your Arcweave projects. You can ask it to summarize a story, inspect branching logic, create elements and connections, manage components and assets, or export a project for your game engine. Arcweave hosts the server. To connect, create a workspace API key and add the server to your AI app using the instructions below. ## Before you connect Context: Arcweave docs > Integrations > Arcweave MCP server > Before you connect You need a **Team workspace**, the **Create API key** workspace permission, and an MCP client that supports **Streamable HTTP** with an `Authorization` header. Your AI app may also require its own subscription or administrator approval for custom MCP servers. 1. Open your Arcweave workspace's **API** section. 2. Click **Create new key** and give it a recognizable name, such as `Claude — story review`. 3. Select **Read projects** to let the assistant inspect project data. Also select **Write projects** if you want it to create, edit, or delete content, including entire projects. Write permission alone does not include read access. 4. Click **Create**, then copy the key using the clipboard icon in the **Key** column. The key acts as the member who created it, within that workspace. It cannot access projects or perform actions that member cannot access. See [Workspace API](https://docs.arcweave.com/workspaces/api) for key management and [REST API permissions](https://docs.arcweave.com/rest-api/overview#permissions) for the underlying access rules. **Tip: Start with read access** A key with **Read projects** is enough to connect and try the first example. Enable **Write projects** when you are ready to let the assistant change your project. Keep the client's tool approval prompts enabled so you can review proposed changes. ### Connection details Context: Arcweave docs > Integrations > Arcweave MCP server > Before you connect > Connection details | Setting | Value | | -------------- | -------------------------------------------- | | Server name | `arcweave` | | Server URL | `https://arcweave.com/mcp` | | Transport | **Streamable HTTP** (often labeled **HTTP**) | | Authentication | Workspace API key sent as a bearer token | | Header name | `Authorization` | | Header value | `Bearer YOUR_API_KEY` | Replace `YOUR_API_KEY` with the key you copied. Include the word `Bearer` followed by one space when setting the header. A dedicated bearer-token field expects only the key. Arcweave's MCP server currently uses API keys, not OAuth. You do not need an OAuth client ID, client secret, or browser sign-in. Use the `/mcp` URL exactly; `/api/v1` is the REST API, and `/sse` is not the MCP endpoint. Keep keys in your client's private settings or environment. Do not paste them into chat messages, screenshots, or files committed to source control. When adding a JSON example to an existing configuration, merge the `arcweave` entry into the existing server object instead of replacing your other settings. ### Environment variables for local clients Context: Arcweave docs > Integrations > Arcweave MCP server > Before you connect > Environment variables for local clients Some examples reference an `ARCWEAVE_API_KEY` environment variable. Set it before launching the client from that terminal: ```bash title="Bash" read -rsp 'Arcweave API key: ' ARCWEAVE_API_KEY printf '\n' export ARCWEAVE_API_KEY ``` ```powershell title="PowerShell 7.1+" $env:ARCWEAVE_API_KEY = Read-Host 'Arcweave API key' -MaskInput ``` These commands set the key for the current terminal session. Set it again in a new terminal. Desktop apps opened from a dock or Start menu may not inherit it: fully quit the app and launch it from the configured terminal, or use its private credential settings. For SSH, containers, or remote development, set the variable in the environment where the MCP client runs. ## Choose your client Context: Arcweave docs > Integrations > Arcweave MCP server > Choose your client | Client | Setup | | ----------------------------------------- | -------------------------------------------------------- | | Claude Code | [Claude Code](https://docs.arcweave.com/integrations/mcp#claude-code) | | Codex CLI, desktop app, and IDE extension | [Codex](https://docs.arcweave.com/integrations/mcp#codex) | | Cursor | [Cursor](https://docs.arcweave.com/integrations/mcp#cursor) | | Visual Studio Code with GitHub Copilot | [VS Code](https://docs.arcweave.com/integrations/mcp#vs-code-with-github-copilot) | | GitHub Copilot CLI | [Copilot CLI](https://docs.arcweave.com/integrations/mcp#github-copilot-cli) | | OpenCode | [OpenCode](https://docs.arcweave.com/integrations/mcp#opencode) | | Google Antigravity | [Antigravity](https://docs.arcweave.com/integrations/mcp#google-antigravity) | | Muse Code | [Muse Code](https://docs.arcweave.com/integrations/mcp#muse-code) | | Gemini CLI | [Gemini CLI](https://docs.arcweave.com/integrations/mcp#gemini-cli) | | Claude web and Desktop | [Claude](https://docs.arcweave.com/integrations/mcp#claude-web-and-desktop) | | Windsurf / Devin Desktop (Cascade) | [Windsurf](https://docs.arcweave.com/integrations/mcp#windsurf-cascade) | | Cline | [Cline](https://docs.arcweave.com/integrations/mcp#cline) | | ChatGPT | [ChatGPT compatibility](https://docs.arcweave.com/integrations/mcp#chatgpt) | | Zed, Kiro, and other clients | [Other MCP clients](https://docs.arcweave.com/integrations/mcp#other-mcp-clients) | | Clients that only support local servers | [Local bridge](https://docs.arcweave.com/integrations/mcp#clients-that-only-support-local-servers) | ## Claude Code Context: Arcweave docs > Integrations > Arcweave MCP server > Claude Code After [setting the environment variable](https://docs.arcweave.com/integrations/mcp#environment-variables-for-local-clients), run this in Bash: ```bash claude mcp add --transport http --scope user \ arcweave https://arcweave.com/mcp \ --header 'Authorization: Bearer ${ARCWEAVE_API_KEY}' claude ``` The single quotes preserve `${ARCWEAVE_API_KEY}` in the saved configuration; Claude Code expands it when connecting. User scope makes the server available across your projects. In PowerShell, use the command on one line and keep the single quotes. For a project-specific setup, add this to `.mcp.json` at the project root instead: ```json { "mcpServers": { "arcweave": { "type": "http", "url": "https://arcweave.com/mcp", "headers": { "Authorization": "Bearer ${ARCWEAVE_API_KEY}" } } } } ``` Start Claude Code, approve the project MCP configuration if prompted, and use `/mcp` to check that `arcweave` connects. You can also run `claude mcp list` from your terminal. No OAuth login is required. See the [official Claude Code MCP guide](https://code.claude.com/docs/en/mcp). ## Codex Context: Arcweave docs > Integrations > Arcweave MCP server > Codex After [setting the environment variable](https://docs.arcweave.com/integrations/mcp#environment-variables-for-local-clients), run: ```bash codex mcp add arcweave \ --url https://arcweave.com/mcp \ --bearer-token-env-var ARCWEAVE_API_KEY codex ``` In PowerShell, run the `codex mcp add` command on one line without the backslashes. Alternatively, add this to `~/.codex/config.toml`: ```toml [mcp_servers.arcweave] url = "https://arcweave.com/mcp" bearer_token_env_var = "ARCWEAVE_API_KEY" ``` The CLI, desktop app, and IDE extension share MCP configuration on the same Codex host. Restart the client after changing it, and make sure that client can read `ARCWEAVE_API_KEY`. In an app's MCP settings, the equivalent setup is a Streamable HTTP server with the URL above and the bearer token or `Authorization` header. Run `codex mcp list` to check the saved configuration, then use `/mcp` in a Codex session to check the connection. Do not run `codex mcp login arcweave`; that command is for OAuth servers. See the [official Codex MCP guide](https://developers.openai.com/codex/mcp/). ## Cursor Context: Arcweave docs > Integrations > Arcweave MCP server > Cursor Add this to your user configuration at `~/.cursor/mcp.json`, or to `.cursor/mcp.json` for a single project: ```json { "mcpServers": { "arcweave": { "url": "https://arcweave.com/mcp", "headers": { "Authorization": "Bearer ${env:ARCWEAVE_API_KEY}" } } } } ``` Make sure Cursor inherits the [environment variable](https://docs.arcweave.com/integrations/mcp#environment-variables-for-local-clients), then restart it. Check that Arcweave is enabled in Cursor's MCP settings and use **Agent** to try a tool call. See the [official Cursor MCP guide](https://cursor.com/docs/mcp). ## VS Code with GitHub Copilot Context: Arcweave docs > Integrations > Arcweave MCP server > VS Code with GitHub Copilot 1. Open the Command Palette and run **MCP: Add Server**. 2. Choose **HTTP**, enter `https://arcweave.com/mcp`, and name the server `arcweave`. 3. Choose **Copilot Global** to save the configuration for your user. Open the resulting `~/.copilot/mcp-config.json` file, or the equivalent under your configured `COPILOT_HOME`. 4. Add the authentication header so the entry looks like this: ```json { "mcpServers": { "arcweave": { "type": "http", "url": "https://arcweave.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" }, "tools": ["*"] } } } ``` Replace `YOUR_API_KEY` in this private user file. Save it, restart the server from **MCP: List Servers**, and enable Arcweave in the chat tool picker. Use an agent session to try the [connection check](https://docs.arcweave.com/integrations/mcp#check-your-connection). This portable configuration also works with Copilot CLI. ### VS Code user-profile configuration Context: Arcweave docs > Integrations > Arcweave MCP server > VS Code with GitHub Copilot > VS Code user-profile configuration If your VS Code version does not offer **Copilot Global**, run **MCP: Open User Configuration** and use this format instead. VS Code asks for the key through a password input and stores it securely: ```json { "inputs": [ { "type": "promptString", "id": "arcweave-api-key", "description": "Arcweave workspace API key", "password": true } ], "servers": { "arcweave": { "type": "http", "url": "https://arcweave.com/mcp", "headers": { "Authorization": "Bearer ${input:arcweave-api-key}" } } } } ``` This format uses `servers`, not `mcpServers`. It is intended for VS Code's local extension-host sessions: servers that require interactive input are not forwarded to Agent Host sessions. Use the portable configuration above for those sessions. See the [VS Code MCP guide](https://code.visualstudio.com/docs/agent-customization/mcp-servers) and [configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration). ## GitHub Copilot CLI Context: Arcweave docs > Integrations > Arcweave MCP server > GitHub Copilot CLI You can use the portable configuration in the [VS Code instructions](https://docs.arcweave.com/integrations/mcp#vs-code-with-github-copilot), or configure the server interactively: 1. Start `copilot` and enter `/mcp add`. 2. Set **Server Name** to `arcweave` and **Server Type** to **HTTP**. 3. Set **URL** to `https://arcweave.com/mcp`. 4. In **HTTP Headers**, enter `{"Authorization":"Bearer YOUR_API_KEY"}`, replacing the placeholder with your key. 5. Leave **Tools** as `*` to make the server's tools available, then press **Ctrl+S** to save. The server is available immediately. Use `/mcp` to inspect it, then try the [connection check](https://docs.arcweave.com/integrations/mcp#check-your-connection). The key is saved in your private Copilot user configuration; do not copy that file into a repository. See the [official Copilot CLI MCP guide](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers). ## OpenCode Context: Arcweave docs > Integrations > Arcweave MCP server > OpenCode After [setting the environment variable](https://docs.arcweave.com/integrations/mcp#environment-variables-for-local-clients), add this to your project's `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "arcweave": { "type": "remote", "url": "https://arcweave.com/mcp", "enabled": true, "oauth": false, "headers": { "Authorization": "Bearer {env:ARCWEAVE_API_KEY}" } } } } ``` OpenCode uses `mcp`, `type: "remote"`, and `{env:VARIABLE}` syntax. Setting `oauth` to `false` prevents it from attempting an OAuth flow for this API-key server. Run `opencode mcp list` to check the connection, then launch `opencode` from the same terminal. See the [official OpenCode MCP guide](https://opencode.ai/docs/mcp-servers/). ## Google Antigravity Context: Arcweave docs > Integrations > Arcweave MCP server > Google Antigravity In the IDE's agent side panel, open **… → MCP Servers → Manage MCP Servers → View raw config**. Add this to the global `mcp_config.json` shown by the app, replacing `YOUR_API_KEY`: ```json { "mcpServers": { "arcweave": { "serverUrl": "https://arcweave.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` Antigravity requires **`serverUrl`** for a remote server. Save the configuration and refresh the MCP server list, then try the [connection check](https://docs.arcweave.com/integrations/mcp#check-your-connection). In Antigravity CLI, the global file is `~/.gemini/config/mcp_config.json`; use `/mcp` to reload it and inspect the connection. See the [official Antigravity MCP guide](https://antigravity.google/docs/mcp). ## Muse Code Context: Arcweave docs > Integrations > Arcweave MCP server > Muse Code After [setting the environment variable](https://docs.arcweave.com/integrations/mcp#environment-variables-for-local-clients), add this to your user settings at `~/.config/muse/settings.json`: ```json { "schema_version": 1, "mcp_servers": { "arcweave": { "transport": "streamable_http", "url": "https://arcweave.com/mcp", "headers": { "Authorization": "Bearer ${ARCWEAVE_API_KEY}" }, "mode": "optional" } } } ``` The settings file must contain `"schema_version": 1`; if the file already exists, add only the `arcweave` entry to its `mcp_servers` block. Muse Code expands `${ARCWEAVE_API_KEY}` when connecting, so the key stays out of the file. With `mode` set to `optional`, Muse Code starts with a warning if Arcweave is unreachable; the default, `required`, stops the run instead. Launch `muse` from the same terminal and run `/mcp` to check that `arcweave` connects and lists its tools. Do not run `muse mcp login arcweave`; that command is for OAuth servers. See the [official Muse Code extension guide](https://dev.meta.ai/docs/muse-code/extending) and [settings reference](https://dev.meta.ai/docs/muse-code/configuration#settings-file). ## Gemini CLI Context: Arcweave docs > Integrations > Arcweave MCP server > Gemini CLI Add this to your private user settings at `~/.gemini/settings.json`: ```json { "mcpServers": { "arcweave": { "httpUrl": "https://arcweave.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` Replace `YOUR_API_KEY` in that private file. Gemini CLI uses **`httpUrl`** for Streamable HTTP; `url` selects the legacy SSE transport. Restart Gemini CLI, then use `/mcp` to inspect the connection and tools. You can also run `gemini mcp list` from the terminal. Leave tool confirmations enabled. See the [official Gemini CLI MCP guide](https://geminicli.com/docs/tools/mcp-server/). ## Claude web and Desktop Context: Arcweave docs > Integrations > Arcweave MCP server > Claude web and Desktop Use a **custom connector** with a request header. Claude connects to Arcweave from Anthropic's servers, so a custom connector works in Claude on the web as well as in Desktop. Availability depends on your Claude plan; Team and Enterprise connectors may need to be added by an organization owner. 1. Open **Customize → Connectors**. For an organization-wide connector, the owner uses **Organization settings → Connectors**. 2. Select **Add → Add custom connector**. 3. Name it `Arcweave` and enter `https://arcweave.com/mcp` as the remote MCP server URL. 4. Continue to the authentication settings. Choose **No sign in**, since Arcweave uses a fixed API key rather than OAuth. 5. Under **Request headers**, add `Authorization` with the value `Bearer YOUR_API_KEY`, replacing the placeholder with your key. 6. Save the connector. In a conversation, open **+ → Connectors**, enable Arcweave, and try the [first connection check](https://docs.arcweave.com/integrations/mcp#check-your-connection). **No sign in** only disables the OAuth flow; the request header still authenticates every request to Arcweave. For a Team or Enterprise connector, everyone using that connector accesses Arcweave through the same configured key. Choose a key whose access is appropriate for those members. If your Desktop version does not offer custom request headers, use the [local bridge](https://docs.arcweave.com/integrations/mcp#clients-that-only-support-local-servers) below. It runs on your computer and is not a workaround for Claude web or mobile. See Claude's [custom connector instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). ## Windsurf / Devin Desktop (Cascade) Context: Arcweave docs > Integrations > Arcweave MCP server > Windsurf / Devin Desktop (Cascade) Open Cascade's MCP configuration from its MCP settings or **… → Open MCP config file**. Add this entry to `mcp_config.json`: ```json { "mcpServers": { "arcweave": { "serverUrl": "https://arcweave.com/mcp", "headers": { "Authorization": "Bearer ${env:ARCWEAVE_API_KEY}" } } } } ``` Make sure the app inherits the [environment variable](https://docs.arcweave.com/integrations/mcp#environment-variables-for-local-clients), then reload the MCP configuration or restart the app. Enable the Arcweave tools you want to use. If the client reaches its enabled-tool limit, select a smaller set of Arcweave tools and disable unused tools from other servers. Windsurf's documentation now redirects to **Devin Desktop**, which uses the same Cascade configuration with the `serverUrl` and `headers` fields. Open the configuration through the app to find the correct file for your installed version. See the [Cascade MCP guide](https://docs.devin.ai/desktop/cascade/mcp). ## Cline Context: Arcweave docs > Integrations > Arcweave MCP server > Cline In the Cline extension, open **MCP Servers → Configure → Configure MCP Servers**. For Cline CLI, edit `~/.cline/mcp.json` or use the `cline mcp` wizard. Add the following to the client's private MCP settings, replacing `YOUR_API_KEY`: ```json { "mcpServers": { "arcweave": { "type": "streamableHttp", "url": "https://arcweave.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" }, "disabled": false, "autoApprove": [] } } } ``` Save the file and check the Arcweave server's connection and tools in Cline's MCP panel. Cline's transport spelling is **`streamableHttp`**; omitting it can select legacy SSE. The empty `autoApprove` list keeps tool approvals under your control. See the [official Cline MCP guide](https://docs.cline.bot/mcp/mcp-overview). ## ChatGPT Context: Arcweave docs > Integrations > Arcweave MCP server > ChatGPT **ChatGPT web's developer-mode apps do not currently offer the fixed bearer-token authentication this server requires.** They support OAuth, no authentication, or a mix of both, and cannot send a custom API key. Adding the Arcweave URL with **No Authentication** will not connect, because Arcweave requires a workspace API key even for tool discovery. Use one of the clients above for direct access. If you use the ChatGPT desktop app's local Codex-host MCP support, follow the [Codex configuration](https://docs.arcweave.com/integrations/mcp#codex): its local MCP configuration supports bearer tokens. A local configuration does not automatically make the server available in ChatGPT web or mobile. See OpenAI's [ChatGPT authentication documentation](https://developers.openai.com/plugins/build/auth) and [local MCP configuration](https://developers.openai.com/codex/mcp/). ## Other MCP clients Context: Arcweave docs > Integrations > Arcweave MCP server > Other MCP clients If your client supports remote servers with custom headers, add a server using the [connection details](https://docs.arcweave.com/integrations/mcp#connection-details). Select **Streamable HTTP**, enter the server URL, and configure the `Authorization` header. Many clients accept this shape in their private user configuration: ```json { "mcpServers": { "arcweave": { "url": "https://arcweave.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` Field names differ between clients, so check each client's own configuration format. For example: | Client | Where to configure | Differences | | ------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Zed | **Settings → AI → MCP Servers → Add Remote Server**, or **zed: open settings file** | Use `context_servers` instead of `mcpServers`. Check for a green **Server is active** indicator. | | Kiro | **Kiro: Open user MCP config (JSON)**, which opens `~/.kiro/settings/mcp.json` | Uses the shape above. Enable MCP support in Kiro's settings if it is disabled; saving the file reconnects. | See the [Zed MCP guide](https://zed.dev/docs/ai/mcp) and [Kiro MCP configuration guide](https://kiro.dev/docs/mcp/configuration/). Web apps that connect to MCP servers from their own servers, such as [Claude's custom connectors](https://docs.arcweave.com/integrations/mcp#claude-web-and-desktop), work like desktop clients as long as they can send the `Authorization` header. Clients that call the server directly from a browser tab are rejected unless Arcweave allows their origin; see [Troubleshooting](https://docs.arcweave.com/integrations/mcp#troubleshooting). ### Clients that only support local servers Context: Arcweave docs > Integrations > Arcweave MCP server > Other MCP clients > Clients that only support local servers A local client that supports **stdio** can use the third-party [`mcp-remote`](https://github.com/geelen/mcp-remote) bridge. The bridge runs on your computer and forwards requests to Arcweave's hosted server. Install a current Node.js LTS release with npm first. For Claude Desktop, open **Settings → Developer → Edit Config** and add the following to `claude_desktop_config.json`. For another stdio client, add the equivalent command, arguments, and environment in its local server settings: ```json { "mcpServers": { "arcweave": { "command": "npx", "args": [ "-y", "mcp-remote", "https://arcweave.com/mcp", "--transport", "http-only", "--header", "Authorization:${ARCWEAVE_AUTH_HEADER}" ], "env": { "ARCWEAVE_AUTH_HEADER": "Bearer YOUR_API_KEY" } } } } ``` Replace `YOUR_API_KEY` in this private configuration. Keep the header argument exactly as shown: the bridge expands `ARCWEAVE_AUTH_HEADER`, and putting the space inside its value avoids argument-quoting problems on Windows. Fully quit and reopen the client. If Windows cannot launch `npx`, set `command` to `cmd` and prepend `"/c", "npx"` to `args`. If Node.js was just installed, restart the app so it picks up the updated `PATH`. This bridge requires a client that can run local processes. It cannot be added to a web app that only accepts a remote URL. ## Check your connection Context: Arcweave docs > Integrations > Arcweave MCP server > Check your connection After connecting, start a conversation and ask: > Use Arcweave to list the projects I can access. Show their names and project IDs without changing anything. The assistant should call `arcweave_list_projects` and return projects from your key's workspace. A successful server connection or tool list alone does not confirm that the key has permission to read project data. Then choose a project: > In the project with ID PROJECT_HASH, list its boards and summarize the opening scene. Do not make changes. Replace `PROJECT_HASH` with the returned `projectId`. It is the project's [URL hash](https://docs.arcweave.com/project-tools/settings#project-hash), not a numeric database ID. You can copy it from Project settings if your role allows access to a specific project but not the workspace project list. If you enabled **Read projects** and **Write projects**, try an edit in a test project: > In my test project PROJECT_HASH, find the board named “MCP test” and create one element titled “Hello from MCP” with the content “This element was created by my assistant.” Ask before making the change. Create or choose that test board first, then review the tool call. Open the same project in Arcweave and check the new element and project history. Further tasks can build connected scenes, inspect conditions, organize components, or prepare exports. Asset uploads and export downloads return temporary transfer URLs. The assistant also needs an HTTP or file-transfer capability to upload or save the actual files. A tool result containing a URL does not mean the file has already transferred. ## Style Play Mode Context: Arcweave docs > Integrations > Arcweave MCP server > Style Play Mode The MCP CSS tools edit the same custom stylesheet as Arcweave's [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor). Use the [Play Mode styling reference](https://docs.arcweave.com/project-tools/play-mode/styling-reference) for DOM structure, selectors, default styles, and element UUID targeting. You do not need to inspect the browser to construct these selectors. Reading requires **Read projects** and project read access. Updating or clearing requires **Write projects** and project edit access. For an editing workflow, enable both permissions. 1. Call `arcweave_get_project_css` with: ```json { "projectId": "PROJECT_HASH" } ``` The response is `{"css":"..."}`, or `{"css":""}` when no custom CSS exists. It does not include Arcweave's built-in styles. Retain the original string for rollback. 2. Modify that string, preserving rules unrelated to the requested change. Re-read the saved CSS just before updating; if it changed, reapply your edits to the latest value. Call `arcweave_update_project_css` with the **complete resulting stylesheet**. For a project with no existing custom CSS, a text-color change could use: ```json { "projectId": "PROJECT_HASH", "css": ".prototype__text .editor .editor-content { color: #e2e8f0; }" } ``` This replaces all custom CSS; it does not append a rule. The tool returns the saved stylesheet. To clear custom styling, use `{"projectId":"PROJECT_HASH","css":""}`. The `css` field is required; `null` does not clear it. 3. Call `arcweave_get_project_css` again and compare the saved value with your intended stylesheet. Surrounding whitespace may be trimmed. 4. **Reload an already-open Play Mode tab**, or click Play in the editor to open a new tab with fresh settings. Then check the appearance. Restarting the story or returning through same-tab navigation does not fetch fresh settings. External CSS updates are not broadcast to already-open players. A successful tool response confirms storage, not valid CSS syntax, matching selectors, or a usable layout. Follow the reference's [verification steps](https://docs.arcweave.com/project-tools/play-mode/styling-reference#save-and-verify-styles). If the assistant cannot use a browser, it should state that visual verification is outstanding. Saves have no conflict detection: the latest save replaces the stylesheet. Coordinate with anyone editing CSS manually. Retain unsaved local edits before reloading an old Style Editor tab, then reapply them to the fresh CSS before saving there. See [Save and verify styles](https://docs.arcweave.com/project-tools/play-mode/styling-reference#save-and-verify-styles). CSS writes do not create project command-history entries. To roll back, send the original stylesheet through `arcweave_update_project_css`, then reload the player. For example, ask: > In project PROJECT_HASH, read the existing Play Mode CSS and retain a rollback copy. Use the Play Mode styling reference to change the story text color to light gray while preserving other rules. Save the complete stylesheet, read it back, and fully reload Play Mode to check the result if browser access is available. Report what you verified. For images, prefer styling the project's existing element or component covers. Upload and download transfer URLs expire; do not save them in CSS. See [Asset URLs](https://docs.arcweave.com/project-tools/play-mode/styling-reference#asset-urls) for presentation URLs and authenticated download limitations. ## Troubleshooting Context: Arcweave docs > Integrations > Arcweave MCP server > Troubleshooting | Problem | What to check | | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401 Unauthorized` | Check that the key is current and the header is `Authorization: Bearer YOUR_API_KEY`. Remove accidental whitespace. For environment-based setups, fully restart the client from the terminal containing the variable. | | `403 Forbidden` when connecting | The key's workspace must have API access, which requires a Team workspace. A browser-based client also needs Arcweave to allow its origin; contact support with the client name and origin. Do not send your API key. | | Connection works, but a tool returns `403 Forbidden` | Check the key's **Read projects** / **Write projects** permissions and the creator's workspace and project permissions. Listing projects requires the creator to have the workspace-level **View projects list** permission. | | `404 Not Found` at the MCP endpoint | Check the exact URL `https://arcweave.com/mcp`. The endpoint must be enabled for the release; if the correct URL still returns `404` during setup, contact Arcweave support. | | OAuth or “sign in” error | Use the API-key header, not OAuth. In OpenCode, set `oauth` to `false`. In Claude's custom connector, use **No sign in** with the request header. | | SSE or transport error | Choose Streamable HTTP and the field spelling shown for your client. Do not change the endpoint to `/sse`. | | Tools do not appear, or only some appear | Reconnect or restart the client to refresh its tool catalog. Check server enablement, tool selection, client tool limits, and organization policies. Use an agent mode that can call tools. | | `429 Too Many Requests` | Wait for the server's `Retry-After` period. MCP shares the workspace's [REST API quotas](https://docs.arcweave.com/rest-api/overview#rate-limits); imports and exports have a smaller shared quota, and MCP also has an IP request limit. | | An upload or download URL fails | Ask the assistant to request a fresh URL. Transfer URLs expire after 10 minutes, and upload URLs are single-use. If an upload's response was lost, check the asset library before retrying. | Opening the endpoint in an ordinary browser tab is not a connection test: the address bar does not send your API-key header or an MCP request. Use your client's server status and the read-only project-list prompt above. To disconnect, disable or remove `arcweave` in the client. To revoke access, [remove the API key](https://docs.arcweave.com/workspaces/api#remove-api-keys) in Arcweave. Changing a key's permissions takes effect immediately; if you replace a key, update every client that used it. # Arcweave JSON Source: https://docs.arcweave.com/integrations/json Section: Integrations Description: Structure of Arcweave JSON exports, with single- and multi-language formats, rich text, Arcscript, every object type, and an example The Arcweave JSON is shallow and fairly easy to understand. When you [export an Arcweave project as JSON](https://docs.arcweave.com/project-tools/export#export-as-json), the resulting file contains a complete representation of your project's structure and content. > ✅ You can use the Arcweave JSON when integrating with game engines or import it back into an Arcweave workspace. > ℹ️ You can [import Arcweave JSON](https://docs.arcweave.com/workspaces/projects#import-a-project) (`.json`) into a Basic, Pro, or Team workspace if you have the **Import projects** permission and the import fits the workspace's project and item limits. Team workspaces can also use the [Import project endpoint of the REST API](https://docs.arcweave.com/rest-api/projects#import-project). Importing [native backup files](https://docs.arcweave.com/workspaces/projects#arcweave-file) (`.arcw`) requires a Pro or Team workspace. > ⚠️ An import creates a new project without media. Assets, element and component covers, element audio, and Asset List attribute values are not imported; upload and attach them again in the new project. Every item ID (object key) in an imported JSON file must be a UUID (version 4). When an imported file includes [`exportVersion`](https://docs.arcweave.com/integrations/json#project-level), it must be the number `1`; any other value, including the string `"1"`, makes the import fail. Files without `exportVersion`, such as older exports, are imported as before. The [REST API JSON export](https://docs.arcweave.com/rest-api/exports#json-export) returns the same format: [single-language JSON](https://docs.arcweave.com/integrations/json#single-language-json) by default, or [multi-language JSON](https://docs.arcweave.com/integrations/json#multi-language-json) with `allLocales=true`. It never includes coordinates. ## Two JSON formats Context: Arcweave docs > Integrations > Arcweave JSON > Two JSON formats Arcweave JSON comes in **two possible versions**, depending on whether the export includes **multiple languages** or not (see [Localization](https://docs.arcweave.com/project-tools/localization)). Specifically: ### Single-language JSON Context: Arcweave docs > Integrations > Arcweave JSON > Two JSON formats > Single-language JSON The exported JSON file is of the **single-language JSON** format when _either_ of the following is true: - The [workspace](https://docs.arcweave.com/workspaces/overview) doesn't have **Localization** features. The export contains the project's main language. - The workspace has **Localization** features, but **Current language** or **Select language** is chosen [during JSON export](https://docs.arcweave.com/project-tools/export#export-languages). In the single-language JSON: - **Element title** and **element content** data are nested in the `elements` object at the following paths: - `/elements/{elementId}/title` - `/elements/{elementId}/content` - **Label content** data are nested in the `connections` object at `/connections/{connectionId}/label` - **Component name** data are nested in the `components` object at `/components/{componentId}/name`. The root of the components folder tree is named `Root`. - The [`contents`](https://docs.arcweave.com/integrations/json#contents) object and the [`locales`](https://docs.arcweave.com/integrations/json#locales) array are omitted. - Text that has no translation in the exported language is `null`. **Extract of single-language JSON example** ```json { "elements": { "188e6385-85e2-496b-82ac-a81696e7bcab": { "content": "You reach a wooden door. In front of you stands a strange man dressed as a medieval crusader.<\/p>", "title": " The Crusader<\/span><\/p>" } } } ``` ### Multi-language JSON Context: Arcweave docs > Integrations > Arcweave JSON > Two JSON formats > Multi-language JSON The exported JSON file is of the **multi-language JSON** format when _both_ of the following are true: - The [workspace](https://docs.arcweave.com/workspaces/overview) has **Localization** features. - **All languages** is chosen [during JSON export](https://docs.arcweave.com/project-tools/export#export-languages). > ℹ️ Selecting **All languages** during export will produce a multi-language JSON file, even if the project has no more than one language. In the multi-language JSON, a `contents` object is included, nesting the contents of all translatable items in all languages. Specifically: - **Element title** and **element content** data are nested in the `contents` object, at the following paths: - `/contents/{itemId}/title/{languageIsoCode}/text` - `/contents/{itemId}/content/{languageIsoCode}/text` - **Label content** data are nested in the `contents` object at `/contents/{itemId}/label/{languageIsoCode}/text` - **Component name** data are nested in the `contents` object at `/contents/{itemId}/name/{languageIsoCode}/text` - Items in the `elements`, `connections`, and `components` objects don't include their title, content, label, or name. To find an item's text, look up the item's ID in `contents`. - A [`locales`](https://docs.arcweave.com/integrations/json#locales) array lists the project's languages. ## Rich text and Arcscript Context: Arcweave docs > Integrations > Arcweave JSON > Rich text and Arcscript Element titles and content, connection labels, note content, and Rich Text Field attribute values are HTML strings: - [Mentions](https://docs.arcweave.com/project-tools/mentions) appear as `` tags with the `mention` class. Their `data-id` and `data-type` attributes identify the mentioned item. - [Arcscript segments](https://docs.arcweave.com/project-items/arcscript#arcscript-segments) in element content and labels appear as ` …` blocks. The [Arcscript interpreters](https://docs.arcweave.com/integrations/arcscript-interpreters) accept this HTML as input. - Branch [conditions](https://docs.arcweave.com/integrations/json#conditions) store their Arcscript expression without the `` wrapper. In single-language JSON, element content and connection labels are simplified: Arcweave removes `style` attributes (such as indentation) from paragraphs, block quotes, and code blocks, and the `data-id`, `spellcheck`, and `class` attributes from code blocks. Element titles and the texts in the multi-language `contents` object keep these attributes, as in the [complete example](https://docs.arcweave.com/integrations/json#complete-example) below. ## JSON structure reference Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference This section explains how each major part and its properties are organized within the JSON file. All JSON extracts used from here on are of the **multi-language format**. Properties marked as optional below are omitted when they don't apply to an item. ### Project-level Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference > Project-level At the root level, the JSON includes several top-level properties: - `exportVersion`: The version of the Arcweave JSON format, currently `1`. [Game engine exports](https://docs.arcweave.com/project-tools/export#export-for-game-engines) don't include it. - `name`: The project's title - `startingElement`: The ID of [the element where your story begins](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#set-play-mode-start); `null` if none - `cover`: An object containing the [project's cover](https://docs.arcweave.com/workspaces/projects#project-cover) info; `null` if the project has no cover - `file`: The cover image's file name, including its extension. For an uploaded cover, Arcweave generates this name. When you export with [Include assets](https://docs.arcweave.com/project-tools/export#include-assets), the `.zip` file's `cover` folder contains the image under this name. - `type`: `cover-image` for a cover you uploaded, or `template-image` for a cover provided by a [project template](https://docs.arcweave.com/workspaces/projects#project-templates) **Extract of JSON example** ```json { "exportVersion": 1, "name": "Game Engine Example", "startingElement": null, "cover": { "file": "game-engine-cover.png", "type": "template-image" } } ``` ### Boards Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference > Boards The `boards` object contains references to all [boards](https://docs.arcweave.com/project-items/boards) and [board folders](https://docs.arcweave.com/project-items/boards#board-folders) of the project by their ID and it includes the following properties: - A **folder** (including the Root): Identified by having a `children` array that references other board and folder IDs. The Root folder is distinguished by a `root: true` property and is named `Root`. - A **board**: Has a custom ID and arrays referencing the IDs of items owned by or placed on that board: - `customId`: The stable, editable ID used as an Arcscript variable scope - `attributes`: Array of [attribute](https://docs.arcweave.com/integrations/json#attributes) IDs owned by the board (optional) - `notes`: Array of [note](https://docs.arcweave.com/project-items/notes) IDs - `elements`: Array of [element](https://docs.arcweave.com/project-items/elements) IDs - `branches`: Array of [branch](https://docs.arcweave.com/project-items/branches) IDs - `jumpers`: Array of [jumper](https://docs.arcweave.com/project-items/jumpers) IDs - `connections`: Array of [connection](https://docs.arcweave.com/project-items/connections) IDs All boards and folders have a `name` property identifying them. **Extract of JSON example** ```json "boards": { "733b1cc4-6d51-4ad6-9fba-444b4f2d98f3": { "name": "Dialogues", "children": ["ef8116b9-c38d-473d-9c0a-600bc37a010d"] }, "2ad15ff6-f2ba-4f1d-9d9d-68938c683d7e": { "name": "Root", "root": true, "children": ["733b1cc4-6d51-4ad6-9fba-444b4f2d98f3"] }, "ef8116b9-c38d-473d-9c0a-600bc37a010d": { "name": "Wanda Dialogue", "customId": "wanda_dialogue", "attributes": ["6b00c0d0-2e3e-4c70-8629-825faac22be3"], "notes": ["d974242a-a65d-4bd6-8670-24c6b02a487f"], "jumpers": ["28e3009a-e164-4679-92c3-977615b1eb4b"], "branches": ["0d845415-33d5-4486-9514-32b88e17e6b2"], "elements": ["5265ceac-f13f-47fc-a02c-6eda7eea6b90"], "connections": [ "8a89cabd-7542-48db-b501-3c0019145989", "a2e45faf-cfea-44c1-b64c-fa8b99bf2bfd" ] } }, ``` ### Notes Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference > Notes The `notes` object contains references to all [notes](https://docs.arcweave.com/project-items/notes) of the project by their ID and it includes the following properties: - `theme`: The note's [color theme](https://docs.arcweave.com/project-items/notes#change-color-theme) (e.g., `cyan`, `moss`; see [Color themes](https://docs.arcweave.com/rest-api/overview#color-themes) for all values) - `content`: HTML-formatted text content - `x` and `y`: The board coordinates of the note (present only when [Include coordinates](https://docs.arcweave.com/project-tools/export#include-coordinates) is selected during export) - `width` and `height`: The dimensions of the note (present only when [Include coordinates](https://docs.arcweave.com/project-tools/export#include-coordinates) is selected during export) - `autoHeight`: Boolean indicating whether the note [automatically adjusts its height](https://docs.arcweave.com/project-items/notes#resize-notes) to the size of its content (present only when [Include coordinates](https://docs.arcweave.com/project-tools/export#include-coordinates) is selected during export) **Extract of JSON example** ```json "notes": { "d974242a-a65d-4bd6-8670-24c6b02a487f": { "theme": "cyan", "content": "We've given dialogue starting elements a custom element attribute.<\/p>" } }, ``` ### Elements Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference > Elements The `elements` object stores references to all [elements](https://docs.arcweave.com/project-items/elements) of the project by their ID and it includes the following properties: - `theme`: The element's [color theme](https://docs.arcweave.com/project-items/elements#change-element-theme) (e.g., `cyan`, `moss`) - `outputs`: Array of [connection](https://docs.arcweave.com/project-items/connections) IDs originating from this element - `attributes`: Array of custom [attribute](https://docs.arcweave.com/project-items/attributes) IDs attached to this element (optional) - `components`: Array of [component](https://docs.arcweave.com/project-items/components) IDs attached to this element - `assets`: The element's [cover](https://docs.arcweave.com/project-items/elements#element-covers) and [audio attachments](https://docs.arcweave.com/project-items/elements#audio-attachments) (optional): - `cover`: An object whose `type` is one of the following: - `image` or `template-image`: An image asset, referenced by its `id` - `video` or `template-video`: A video asset, referenced by its `id`, with optional playback settings `mode` (`once`, `loop`, or `stop`), `autoplay`, `showOptions`, and `showControls` - `icon`: An icon from the [icon library](https://docs.arcweave.com/project-tools/icon-library), identified by `file` - `youtube`: A YouTube embed, with its `url` and optional `autoplay` and `showControls` settings - `audio`: Array of attached [audio references](https://docs.arcweave.com/project-items/assets/audio#audio-reference-settings). Each entry has its own `id`, the audio asset's ID in `asset`, the playback `mode` (`once`, `loop`, or `stop`), and a `delay` in milliseconds. Optional `volume` (`0` to `1`), `fadeIn`, and `fadeOut` (milliseconds) override the asset's values; when omitted, the asset's values apply. `autoStopOnExit` is `true` when the audio stops as Play Mode leaves the element. - `linkedBoard`: The ID of a board linked to this element (optional) - `x` and `y`: The board coordinates of the element (present only when [Include coordinates](https://docs.arcweave.com/project-tools/export#include-coordinates) is selected during export) - `width` and `height`: The dimensions of the element (present only when [Include coordinates](https://docs.arcweave.com/project-tools/export#include-coordinates) is selected during export) - `autoHeight`: Boolean indicating whether the element [automatically adjusts its height](https://docs.arcweave.com/project-items/elements#resize-elements) to the size of its content (present only when [Include coordinates](https://docs.arcweave.com/project-tools/export#include-coordinates) is selected during export) The `components` and `outputs` properties are optional. When there are no attached components or outgoing connections, the corresponding property can be an empty array (`[]`) or absent. Treat either as an empty list. > ⚠️ The properties `x`, `y`, `width`, `height`, and `autoHeight` are included in the JSON only if [Include coordinates](https://docs.arcweave.com/project-tools/export#include-coordinates) is selected during JSON export. Regarding **element title** and **element content** data, they are stored in the following ways: - In [single-language JSON](https://docs.arcweave.com/integrations/json#single-language-json) files, they are nested in the `elements` object. - In [multi-language JSON](https://docs.arcweave.com/integrations/json#multi-language-json) files, they are nested in the [`contents` object](https://docs.arcweave.com/integrations/json#contents), under the element's ID. **Extract of multi-language JSON example** ```json "elements": { "5265ceac-f13f-47fc-a02c-6eda7eea6b90": { "theme": "cyan", "outputs": ["8a89cabd-7542-48db-b501-3c0019145989"], "attributes": ["11006864-6f66-4c2c-a3b7-d3fae8febc42"], "components": ["647349ca-9ebb-4d5f-b81e-500761ec1c5a"] } }, ``` ### Jumpers Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference > Jumpers The `jumpers` object contains references to all [jumpers](https://docs.arcweave.com/project-items/jumpers) of the project by their ID and it includes the following properties: - `elementId`: The ID of the target element this jumper points to - `x` and `y`: The board coordinates of the jumper (present only when [Include coordinates](https://docs.arcweave.com/project-tools/export#include-coordinates) is selected during export) **Extract of JSON example** ```json "jumpers": { "28e3009a-e164-4679-92c3-977615b1eb4b": { "elementId": "5265ceac-f13f-47fc-a02c-6eda7eea6b90" } }, ``` ### Connections Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference > Connections The `connections` object contains references to all [connections](https://docs.arcweave.com/project-items/connections) of the project by their ID and it includes the following properties: - `type`: The visual style of the connection: `Straight`, `Bezier`, or `Flowchart` - `theme`: Color theme - `sourceid`: ID of the originating item - `targetid`: ID of the destination item - `sourceType`: Type of source item: `elements` or `conditions` - `targetType`: Type of target item: `elements`, `branches`, or `jumpers` - `sourceFace` and `targetFace`: The side of the source or target item that the connection attaches to: `left`, `right`, `top`, or `bottom` (optional) - `labelLocation`: The label's relative position along the connection, from `0` to `1` (optional) - `labelWidth`: The label's width (optional) - `waypoints`: For a `Flowchart` connection with a [customized path](https://docs.arcweave.com/project-items/connections#edit-connection-paths), an ordered array of `x` and `y` points in board coordinates (optional; present only when [Include coordinates](https://docs.arcweave.com/project-tools/export#include-coordinates) is selected during export) - `controlPoints`: For a customized `Bezier` connection, an object with `source` and `target` points, each an `x` and `y` offset from the point where the connection attaches to that item (optional; present only when [Include coordinates](https://docs.arcweave.com/project-tools/export#include-coordinates) is selected during export) Regarding **label content** data, they are stored in the following way: - In [single-language JSON](https://docs.arcweave.com/integrations/json#single-language-json) files, they are nested in the `connections` object. - In [multi-language JSON](https://docs.arcweave.com/integrations/json#multi-language-json) files, they are nested in the [`contents` object](https://docs.arcweave.com/integrations/json#contents), under the connection's ID. **Extract of multi-language JSON example** ```json "connections": { "8a89cabd-7542-48db-b501-3c0019145989": { "type": "Straight", "theme": "moss", "sourceid": "5265ceac-f13f-47fc-a02c-6eda7eea6b90", "targetid": "0d845415-33d5-4486-9514-32b88e17e6b2", "sourceType": "elements", "targetFace": "left", "targetType": "branches" }, "a2e45faf-cfea-44c1-b64c-fa8b99bf2bfd": { "targetType": "jumpers", "type": "Straight", "targetid": "28e3009a-e164-4679-92c3-977615b1eb4b", "sourceid": "f8e12e95-43b7-4d42-9844-5402665b24ef", "theme": "moss", "sourceType": "conditions" } }, ``` ### Branches Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference > Branches The `branches` object contains references to all [branches](https://docs.arcweave.com/project-items/branches) of the project by their ID and it includes the following properties: - `theme`: Color theme - `conditions`: An object defining conditional expressions: - `ifCondition`: The ID of the branch's `if` condition - `elseIfConditions`: An array of the branch's `elseif` condition IDs, in order (optional) - `elseCondition`: The ID of the branch's `else` condition (optional) - `x` and `y`: The board coordinates of the branch (present only when [Include coordinates](https://docs.arcweave.com/project-tools/export#include-coordinates) is selected during export) **Extract of JSON example** ```json "branches": { "0d845415-33d5-4486-9514-32b88e17e6b2": { "theme": "moss", "conditions": { "ifCondition": "f8e12e95-43b7-4d42-9844-5402665b24ef", "elseIfConditions": ["e3234e1e-74f9-45d5-be30-994bf5b3bc7c"], "elseCondition": "0d91c8a3-7704-423e-b3f6-046973eb15a7" } } }, ``` ### Conditions Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference > Conditions The `conditions` object contains references to all branch conditions of the project (see [Branches](https://docs.arcweave.com/project-items/branches)) by their ID and it includes the following properties: - `output`: The ID of the condition's output [connection](https://docs.arcweave.com/project-items/connections) - `script`: The Arcscript [expression](https://docs.arcweave.com/project-items/arcscript#expressions) being evaluated to determine if the condition is met (`null` for `else` conditions). The script isn't wrapped in ` ` tags, and [mentions](https://docs.arcweave.com/project-tools/mentions), such as an element passed to `visits()`, appear as HTML `` tags. To evaluate a script with an [Arcscript interpreter](https://docs.arcweave.com/integrations/arcscript-interpreters), wrap it in `` and `` first. **Extract of JSON example** ```json "conditions": { "f8e12e95-43b7-4d42-9844-5402665b24ef": { "output": "a2e45faf-cfea-44c1-b64c-fa8b99bf2bfd", "script": "have_potion" } }, ``` ### Contents Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference > Contents The `contents` object is central to Arcweave's [localization](https://docs.arcweave.com/project-tools/localization) system. It contains the content of all translatable project items: - [Elements](https://docs.arcweave.com/project-items/elements): Title and content, referenced by the element ID - [Components](https://docs.arcweave.com/project-items/components) and component folders: Name, referenced by the component or folder ID. The Root of the components folder tree has no entry. - [Labels](https://docs.arcweave.com/project-items/labels): Content (property `label`), referenced by the label's [connection](https://docs.arcweave.com/project-items/connections) ID. > ⚠️ The single-language JSON format _does not_ include the `contents` object. See [Two JSON formats](https://docs.arcweave.com/integrations/json#two-json-formats) above, for the distinction between single-language and multi-language JSON. Each entry of the `contents` object can include the following properties: - `title`: For element title only, organized by locale (e.g., `en`, `es`) - `content`: For element content only, organized by locale - `name`: For component name only, organized by locale - `label`: For connection label content only, organized by locale - `_status`: [Translation status](https://docs.arcweave.com/project-tools/localization#translation-status) for each translated locale: `untranslated`, `progress` (**In progress**), `review` (**For review**), or `final`. The main language has no status. Component folders have no `_status`. Each localized field contains a `text` property with the actual content. A missing locale or a `null` text means the item has no text in that language. **Extract of JSON example** ```json "contents": { "5265ceac-f13f-47fc-a02c-6eda7eea6b90": { "title": { "en": { "text": "Starting loop<\/p>" } }, "content": { "en": { "text": " Help me, Stranger.... I am wounded...<\/p>" }, "es": { "text": " \u00a1Ay\u00fadame, por favor! \u00a1Estoy herido!<\/p>" } }, "_status": { "es": "review", "elf": "untranslated" } }, "036db898-0cb9-4a29-b19d-3e8f3288d9a2": { "name": { "en": { "text": "Characters" } } }, "647349ca-9ebb-4d5f-b81e-500761ec1c5a": { "name": { "en": { "text": "Wanda Elandor" } }, "_status": { "es": "review", "elf": "untranslated" } }, "8a89cabd-7542-48db-b501-3c0019145989": { "label": { "en": { "text": " Give potion<\/p>" }, "es": { "text": " Dar poci\u00f3n<\/p>" } }, "_status": { "es": "final", "elf": "untranslated" } } }, ``` ### Components Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference > Components The `components` object contains references to all [components](https://docs.arcweave.com/project-items/components) and [component folders](https://docs.arcweave.com/project-items/components#component-folders) of the project by their ID and it includes the following properties: - `root`: Boolean indicating if this is the root of the components folder tree - `children`: Array of child component and folder IDs (applies to component folders only) - `customId`: Stable, editable ID used as an Arcscript variable scope (applies to components only) - `assets`: The component's [cover](https://docs.arcweave.com/project-items/components#cover) (optional). Its `cover` object references an image asset by `id` (with an optional `type` of `image` or `template-image`), or an icon from the [icon library](https://docs.arcweave.com/project-tools/icon-library) by `file` (with `type` set to `icon`). - `attributes`: Array of custom attribute IDs (applies to components only) Regarding **component name** data, they are stored in the following way: - In [single-language JSON](https://docs.arcweave.com/integrations/json#single-language-json) files, they are nested in the `components` object. - In [multi-language JSON](https://docs.arcweave.com/integrations/json#multi-language-json) files, they are nested in the [`contents` object](https://docs.arcweave.com/integrations/json#contents), under the component's ID. **Extract of JSON example** ```json "components": { "036db898-0cb9-4a29-b19d-3e8f3288d9a2": { "children": [ "3846c37c-07a1-4c04-98e2-26cd026295d1", "647349ca-9ebb-4d5f-b81e-500761ec1c5a" ] }, "3846c37c-07a1-4c04-98e2-26cd026295d1": { "customId": "drake_miles", "assets": { "cover": { "id": "190e9e72-32e9-4c51-adbb-dbad343134fc" } }, "attributes": ["22780ff3-64a2-40e8-a2e4-e753809c020a"] }, "65005bda-15d0-41c5-867f-68c118829f08": { "root": true, "children": ["036db898-0cb9-4a29-b19d-3e8f3288d9a2"] } }, ``` ### Attributes Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference > Attributes The `attributes` object contains references to all [attributes](https://docs.arcweave.com/project-items/attributes) of the project by their ID and it includes the following properties: - `cId`: The ID of the parent [board](https://docs.arcweave.com/project-items/boards), [component](https://docs.arcweave.com/project-items/components), or [element](https://docs.arcweave.com/project-items/elements) - `name`: The attribute's name - `customId`: The Arcscript variable name for eligible board/component attributes (optional) - `cType`: The type of parent (`boards`, `components`, or `elements`) - `value`: An object containing: - `type`: The attribute's data type: - `string`: A String Field or Rich Text Field - `boolean`, `integer`, or `float`: A Boolean, Integer, or Float attribute (boards and components only) - `component-list`: A Component List - `asset-list`: An Asset List - `data`: The actual value. String Field values are plain text and Rich Text Field values are HTML; an empty string attribute is `null`. Component and Asset Lists contain arrays of component or asset IDs. - `plain`: For `string` values, `true` for a String Field. Rich Text Field values have `plain` set to `false` or omitted. String attributes with `plain: true`, as well as Boolean, Integer, and Float attributes, become scoped variables only when both the attribute and its owning board/component have a `customId`. The attribute object's key remains its stable internal ID. **Extract of JSON example** ```json "attributes": { "6b00c0d0-2e3e-4c70-8629-825faac22be3": { "cId": "ef8116b9-c38d-473d-9c0a-600bc37a010d", "cType": "boards", "name": "Message", "customId": "message", "value": { "data": "Welcome", "type": "string", "plain": true } }, "11006864-6f66-4c2c-a3b7-d3fae8febc42": { "cId": "5265ceac-f13f-47fc-a02c-6eda7eea6b90", "name": "tag", "cType": "elements", "value": { "data": "dialogue_start", "type": "string", "plain": true } }, "22780ff3-64a2-40e8-a2e4-e753809c020a": { "cId": "3846c37c-07a1-4c04-98e2-26cd026295d1", "name": "obj_id", "customId": "obj_id", "cType": "components", "value": { "data": "DRAKE", "type": "string", "plain": true } } }, ``` ### Assets Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference > Assets The `assets` object contains references to all [assets](https://docs.arcweave.com/project-items/assets/overview) and [asset folders](https://docs.arcweave.com/project-items/assets/overview#asset-folders) of the project by their ID and it includes the following properties: - `name`: The asset's name followed by its file extension, such as `player.png`; for asset folders, the folder name. The Root folder has no name. - `type`: The asset type; one of the following: - `image`: [Image asset](https://docs.arcweave.com/project-items/assets/images) uploaded by the user - `audio`: [Audio asset](https://docs.arcweave.com/project-items/assets/audio) uploaded by the user - `video`: [Video asset](https://docs.arcweave.com/project-items/assets/video) uploaded by the user - `template-image`: Image asset instantiated during [project template](https://docs.arcweave.com/workspaces/projects#project-templates) recreation - `template-audio`: Audio asset instantiated during project template recreation - `template-video`: Video asset instantiated during project template recreation - `volume`: For audio and video assets, the playback volume from `0` to `1` (optional) - `fadeIn` and `fadeOut`: For audio assets, the default fade durations in milliseconds, used by audio references that don't override them (optional) - `root`: Boolean indicating if this is the root of the assets folder tree - `children`: Array of asset and folder IDs (applies to asset folders only) > ℹ️ The JSON references assets by ID and name only; it doesn't include the files. To download the files, export with [Include assets](https://docs.arcweave.com/project-tools/export#include-assets). In the `.zip` file, the `assets` folder recreates the project's folder structure and names each file after its asset `name`. **Extract of JSON example** ```json "assets": { "190e9e72-32e9-4c51-adbb-dbad343134fc": { "name": "player.png", "type": "template-image" }, "647d0495-341f-42b2-8788-b47dace22bf8": { "root": true, "children": [ "4de16200-4175-4aff-b753-3d40ff849289", "190e9e72-32e9-4c51-adbb-dbad343134fc", "fd70f4a4-578f-442f-9e5c-78872289818f" ] } }, ``` ### Variables Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference > Variables The `variables` object contains project-level [global variables](https://docs.arcweave.com/project-items/variables/global) by their ID. Board and component variables are stored in the [`attributes`](https://docs.arcweave.com/integrations/json#attributes) object instead, using String values with `plain: true`, or Boolean, Integer, or Float values. - `name`: The variable name - `type`: The variable data type: `string`, `integer`, `float`, or `boolean` - `value`: The variable's initial value - `cType`: `global` for a global variable - `root`: `true` for the root entry, which lists the global variables instead of defining one - `children`: Array of the global variable IDs (applies to the root entry only) **Extract of JSON example** ```json "variables": { "6e25dd6b-e976-4a80-afc5-5ce2cbcc8228": { "name": "have_potion", "type": "boolean", "value": false, "cType": "global" }, "747d0495-341f-42b2-8788-b47dace22bf8": { "root": true, "children": [ "990d6321-43cb-430b-84bd-6b48c574c489", "6e25dd6b-e976-4a80-afc5-5ce2cbcc8228" ] }, "990d6321-43cb-430b-84bd-6b48c574c489": { "name": "healer_health", "type": "integer", "value": 50, "cType": "global" } }, ``` ### Locales Context: Arcweave docs > Integrations > Arcweave JSON > JSON structure reference > Locales The `locales` array defines available languages used by Arcweave's [localization](https://docs.arcweave.com/project-tools/localization) features. It is included only in [multi-language JSON](https://docs.arcweave.com/integrations/json#multi-language-json). The included properties are: - `name`: The language name - `iso`: The ISO language code (e.g., `en`, `es`) - `base`: The language set as the one used to **translate from** (`null` for the [main language](https://docs.arcweave.com/project-tools/localization#set-main-language)) Translation content is distributed throughout the `contents` object, where each localizable item contains nested objects for each locale, along with a `_status` object tracking translation progress. **Extract of JSON example** ```json "locales": [ { "name": "English", "iso": "en", "base": null }, { "name": "Spanish", "iso": "es", "base": "en" } ] ``` ## Complete example Context: Arcweave docs > Integrations > Arcweave JSON > Complete example To illustrate the structure of Arcweave's JSON format, the following is a complete `.json` file exported from a simplified version of the [Game Engine Example](https://docs.arcweave.com/workspaces/projects#project-templates) project template, with **All languages** and **Include coordinates** selected. **Example JSON** ```json { "exportVersion": 1, "startingElement": "ddc209cc-7832-4ff6-ae1f-4eea592d07d4", "boards": { "1c11fa2a-f76c-4be7-aac4-6bf92a63240f": { "name": "Dialogue", "customId": "dialogue", "notes": ["034133c4-42d2-45af-9db6-351eadfd5a1e"], "jumpers": ["49be178c-30a9-4160-b065-1a72e3626a65"], "branches": ["bce80b17-0165-41a2-a29d-e814f6e9f110"], "elements": [ "540d5fc7-aa78-4b1a-8c11-bc2d4dc24ba9", "ddc209cc-7832-4ff6-ae1f-4eea592d07d4", "d852a577-bd1f-44cf-8187-77a86f97baef", "3eb1ee28-19fe-4e1f-b71b-07ec622e8fbc" ], "connections": [ "57572c19-ca11-4223-bdb7-718971ef7951", "90872a7c-0f63-472b-8330-a6b14d824aeb", "9b1224a4-5546-4f81-96c7-a1865c618291", "0879ddb5-e1a2-4b95-a28c-d4df8df845e9", "0828bb7f-3a2b-4121-bff6-affe5c77d55d", "4a9530d7-9b4e-48c8-b9a7-4682db61647a" ] }, "2ad15ff6-f2ba-4f1d-9d9d-68938c683d7e": { "name": "Root", "root": true, "children": ["1c11fa2a-f76c-4be7-aac4-6bf92a63240f"] } }, "notes": { "034133c4-42d2-45af-9db6-351eadfd5a1e": { "x": 10180, "y": 10540, "theme": "cyan", "width": 301, "height": 106, "content": " We've given dialogue starting elements a custom element attribute:<\/p> tag: dialogue_start<\/strong><\/p>", "autoHeight": true } }, "elements": { "3eb1ee28-19fe-4e1f-b71b-07ec622e8fbc": { "width": 301, "y": 10744, "x": 11128, "components": ["3846c37c-07a1-4c04-98e2-26cd026295d1"], "height": 185, "autoHeight": true, "theme": "moss", "outputs": ["4a9530d7-9b4e-48c8-b9a7-4682db61647a"] }, "ddc209cc-7832-4ff6-ae1f-4eea592d07d4": { "x": 10055, "y": 10727, "theme": "cyan", "width": 294, "height": 121, "outputs": ["0879ddb5-e1a2-4b95-a28c-d4df8df845e9"], "attributes": ["955b9b0d-372a-45d9-a68f-33ddfebf2bf6"], "autoHeight": true, "components": [] }, "540d5fc7-aa78-4b1a-8c11-bc2d4dc24ba9": { "x": 11120, "y": 10340, "theme": "moss", "width": 301, "height": 185, "outputs": ["90872a7c-0f63-472b-8330-a6b14d824aeb"], "autoHeight": true, "components": ["3846c37c-07a1-4c04-98e2-26cd026295d1"] }, "d852a577-bd1f-44cf-8187-77a86f97baef": { "x": 11607, "y": 10318, "theme": "moss", "width": 301, "height": 253, "outputs": ["9b1224a4-5546-4f81-96c7-a1865c618291"], "attributes": ["45a15656-47e5-463a-a3ed-c508965e6010"], "autoHeight": true, "components": ["82820a96-708d-4a05-b2aa-21e8d582d5de"] } }, "jumpers": { "49be178c-30a9-4160-b065-1a72e3626a65": { "x": 12340, "y": 10820, "elementId": "ddc209cc-7832-4ff6-ae1f-4eea592d07d4" } }, "connections": { "4a9530d7-9b4e-48c8-b9a7-4682db61647a": { "targetType": "jumpers", "type": "Bezier", "targetid": "49be178c-30a9-4160-b065-1a72e3626a65", "sourceType": "elements", "sourceid": "3eb1ee28-19fe-4e1f-b71b-07ec622e8fbc", "theme": "default" }, "0828bb7f-3a2b-4121-bff6-affe5c77d55d": { "targetType": "elements", "type": "Bezier", "targetid": "3eb1ee28-19fe-4e1f-b71b-07ec622e8fbc", "sourceType": "conditions", "sourceid": "d24a6cbe-85fb-4059-8867-fa8ba0af6aa0", "theme": "default", "labelLocation": 0.5 }, "0879ddb5-e1a2-4b95-a28c-d4df8df845e9": { "type": "Straight", "theme": "default", "sourceid": "ddc209cc-7832-4ff6-ae1f-4eea592d07d4", "targetid": "bce80b17-0165-41a2-a29d-e814f6e9f110", "sourceType": "elements", "targetType": "branches" }, "9b1224a4-5546-4f81-96c7-a1865c618291": { "type": "Straight", "theme": "moss", "sourceid": "d852a577-bd1f-44cf-8187-77a86f97baef", "targetid": "49be178c-30a9-4160-b065-1a72e3626a65", "sourceType": "elements", "targetType": "jumpers" }, "90872a7c-0f63-472b-8330-a6b14d824aeb": { "type": "Straight", "theme": "moss", "sourceid": "540d5fc7-aa78-4b1a-8c11-bc2d4dc24ba9", "targetid": "d852a577-bd1f-44cf-8187-77a86f97baef", "sourceType": "elements", "targetFace": "left", "targetType": "elements" }, "57572c19-ca11-4223-bdb7-718971ef7951": { "type": "Straight", "theme": "moss", "sourceid": "66acc3a7-454a-43db-a923-1b0d3cb17805", "targetid": "540d5fc7-aa78-4b1a-8c11-bc2d4dc24ba9", "sourceType": "conditions", "targetFace": "left", "targetType": "elements" } }, "branches": { "bce80b17-0165-41a2-a29d-e814f6e9f110": { "x": 10580, "y": 10740, "theme": "default", "conditions": { "ifCondition": "66acc3a7-454a-43db-a923-1b0d3cb17805", "elseCondition": "d24a6cbe-85fb-4059-8867-fa8ba0af6aa0" } } }, "contents": { "82820a96-708d-4a05-b2aa-21e8d582d5de": { "name": { "en": { "text": "Healer" }, "it": { "text": "Guaritore" } }, "_status": { "it": "final" } }, "540d5fc7-aa78-4b1a-8c11-bc2d4dc24ba9": { "title": { "en": { "text": " Ask for help (successfully)<\/p>" }, "it": { "text": " Chiedere aiuto (con successo)<\/p>" } }, "content": { "en": { "text": " Someone's hurt! Can you help?<\/p>" }, "it": { "text": " Qualcuno \u00e8 ferito! Puoi aiutare?<\/p>" } }, "_status": { "it": "final" } }, "036db898-0cb9-4a29-b19d-3e8f3288d9a2": { "name": { "en": { "text": "Characters" } } }, "3eb1ee28-19fe-4e1f-b71b-07ec622e8fbc": { "content": { "en": { "text": " Oops, wrong turn. Bye!<\/p>" }, "it": { "text": " Ops, svolta sbagliata. Ciao!<\/p>" } }, "title": { "en": { "text": " Bye now<\/p>" }, "it": { "text": " Ciao<\/p>" } }, "_status": { "it": "final" } }, "9b1224a4-5546-4f81-96c7-a1865c618291": { "label": { "en": { "text": " [Back]<\/p>" }, "it": { "text": " [Indietro]<\/p>" } }, "_status": { "it": "final" } }, "3846c37c-07a1-4c04-98e2-26cd026295d1": { "name": { "en": { "text": "Drake Miles" }, "it": { "text": "Drake Miles" } }, "_status": { "it": "final" } }, "57572c19-ca11-4223-bdb7-718971ef7951": { "label": { "en": { "text": " Ask for help<\/p>" }, "it": { "text": " Chiedi aiuto<\/p>" } }, "_status": { "it": "final" } }, "ddc209cc-7832-4ff6-ae1f-4eea592d07d4": { "title": { "en": { "text": " Start<\/p>" }, "it": { "text": " Inizio<\/p>" } }, "content": { "en": { "text": " An old man is standing by a stone cottage.<\/p>" }, "it": { "text": " Un vecchio \u00e8 in piedi accanto a una casetta di pietra.<\/p>" } }, "_status": { "it": "final" } }, "d852a577-bd1f-44cf-8187-77a86f97baef": { "title": { "en": { "text": " Get potion<\/p>" }, "it": { "text": " Prendi la pozione<\/p>" } }, "content": { "en": { "text": " have_potion = true<\/code><\/pre>Oh my! But of course! Here, take this healing potion<\/strong>.<\/p>" }, "it": { "text": " have_potion = true<\/code><\/pre>Oh mio Dio! Ma ovviamente! Ecco, prendi questa pozione curativa.<\/p>" } }, "_status": { "it": "final" } } }, "components": { "036db898-0cb9-4a29-b19d-3e8f3288d9a2": { "children": [ "3846c37c-07a1-4c04-98e2-26cd026295d1", "82820a96-708d-4a05-b2aa-21e8d582d5de" ] }, "3846c37c-07a1-4c04-98e2-26cd026295d1": { "customId": "drake_miles", "assets": { "cover": { "id": "190e9e72-32e9-4c51-adbb-dbad343134fc" } }, "attributes": [ "9d863621-49d6-4f34-a893-20dd24645345", "5f504b6a-8dfd-4a32-b1b2-e45cb1772e8a", "22780ff3-64a2-40e8-a2e4-e753809c020a" ] }, "82820a96-708d-4a05-b2aa-21e8d582d5de": { "customId": "healer", "assets": { "cover": { "id": "4de16200-4175-4aff-b753-3d40ff849289" } }, "attributes": [ "b36b6cc2-7dab-4582-b420-7e470ceb90d4", "96cefbf8-2c24-424c-9538-3533e52d38c6", "5efdbbc2-5a4d-4fb9-bb9b-994e1b4bb35c" ] }, "65005bda-15d0-41c5-867f-68c118829f08": { "root": true, "children": ["036db898-0cb9-4a29-b19d-3e8f3288d9a2"] } }, "attributes": { "5f504b6a-8dfd-4a32-b1b2-e45cb1772e8a": { "cId": "3846c37c-07a1-4c04-98e2-26cd026295d1", "name": "Race", "customId": "race", "cType": "components", "value": { "data": "Human", "type": "string", "plain": true } }, "b36b6cc2-7dab-4582-b420-7e470ceb90d4": { "cId": "82820a96-708d-4a05-b2aa-21e8d582d5de", "name": "Color", "customId": "color", "cType": "components", "value": { "data": "Red", "type": "string", "plain": true } }, "22780ff3-64a2-40e8-a2e4-e753809c020a": { "cId": "3846c37c-07a1-4c04-98e2-26cd026295d1", "name": "obj_id", "customId": "obj_id", "cType": "components", "value": { "data": "DRAKE", "type": "string", "plain": true } }, "96cefbf8-2c24-424c-9538-3533e52d38c6": { "cId": "82820a96-708d-4a05-b2aa-21e8d582d5de", "name": "Race", "customId": "race", "cType": "components", "value": { "data": "Human", "type": "string", "plain": true } }, "45a15656-47e5-463a-a3ed-c508965e6010": { "cId": "d852a577-bd1f-44cf-8187-77a86f97baef", "name": "tag", "cType": "elements", "value": { "data": "dialogue_end", "type": "string", "plain": true } }, "9d863621-49d6-4f34-a893-20dd24645345": { "cId": "3846c37c-07a1-4c04-98e2-26cd026295d1", "name": "Color", "customId": "color", "cType": "components", "value": { "data": "Brown", "type": "string", "plain": true } }, "5efdbbc2-5a4d-4fb9-bb9b-994e1b4bb35c": { "cId": "82820a96-708d-4a05-b2aa-21e8d582d5de", "name": "obj_id", "customId": "obj_id", "cType": "components", "value": { "data": "HEALER", "type": "string", "plain": true } }, "955b9b0d-372a-45d9-a68f-33ddfebf2bf6": { "cId": "ddc209cc-7832-4ff6-ae1f-4eea592d07d4", "name": "tag", "cType": "elements", "value": { "data": "dialogue_start", "type": "string", "plain": true } } }, "assets": { "190e9e72-32e9-4c51-adbb-dbad343134fc": { "name": "player.png", "type": "template-image" }, "4de16200-4175-4aff-b753-3d40ff849289": { "name": "healer.png", "type": "template-image" }, "647d0495-341f-42b2-8788-b47dace22bf8": { "root": true, "children": [ "4de16200-4175-4aff-b753-3d40ff849289", "190e9e72-32e9-4c51-adbb-dbad343134fc", "fd70f4a4-578f-442f-9e5c-78872289818f" ] }, "fd70f4a4-578f-442f-9e5c-78872289818f": { "name": "wanda.png", "type": "template-image" } }, "variables": { "6e25dd6b-e976-4a80-afc5-5ce2cbcc8228": { "name": "have_potion", "type": "boolean", "cType": "global", "value": false }, "747d0495-341f-42b2-8788-b47dace22bf8": { "root": true, "children": ["6e25dd6b-e976-4a80-afc5-5ce2cbcc8228"] } }, "conditions": { "d24a6cbe-85fb-4059-8867-fa8ba0af6aa0": { "output": "0828bb7f-3a2b-4121-bff6-affe5c77d55d", "script": null }, "66acc3a7-454a-43db-a923-1b0d3cb17805": { "output": "57572c19-ca11-4223-bdb7-718971ef7951", "script": "not have_potion" } }, "locales": [ { "iso": "en", "base": null, "name": "English" }, { "iso": "it", "name": "Italiano", "base": "en" } ], "name": "Game Engine Simplified", "cover": { "file": "game-engine-cover.png", "type": "template-image" } } ``` # Unity integration Source: https://docs.arcweave.com/integrations/unity Section: Integrations Description: Install the Arcweave plugin for Unity, import data into an ArcweaveProjectAsset, run the demo scene, and use the plugin reference Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: ` ` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. Arcweave provides a free plugin for importing your Arcweave projects into [Unity](https://unity.com/). This plugin supports data that is either: - Exported from Arcweave [via Export for Unity](https://docs.arcweave.com/integrations/unity#via-export-for-unity) (available to all workspace tiers) or - Fetched [via Arcweave's REST API](https://docs.arcweave.com/integrations/unity#via-web-api) (available to Team workspaces only). ## Tutorials Context: Arcweave docs > Integrations > Unity integration > Tutorials For a step-by-step walkthrough and videos on this integration, see the [Unity integration tutorial](https://docs.arcweave.com/tutorials/unity/overview). ## Plugin repository Context: Arcweave docs > Integrations > Unity integration > Plugin repository You can download the Arcweave plugin for Unity using [its GitHub link](https://github.com/arcweave/arcweave-unity-plugin). ## Example Project Context: Arcweave docs > Integrations > Unity integration > Example Project Explore our [Unity example project](https://github.com/arcweave/arcweave-unity-example) to see Arcweave's implementation with Unity in action. ![Screenshot from the Unity example.](https://docs.arcweave.com/assets/unity-example.C-xtGpTC.png) 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](https://docs.arcweave.com/workspaces/projects). 2. Click the **+ New project** button. 3. Select a template from the menu. ## Install the plugin Context: Arcweave docs > Integrations > Unity integration > 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 Context: Arcweave docs > Integrations > Unity integration > Install the plugin > 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](https://github.com/arcweave/arcweave-unity-plugin). 2. Extract the ZIP file. 3. Copy the `/Assets/Arcweave` folder into your Unity project's `Assets` folder. ### From Unity Asset Store Context: Arcweave docs > Integrations > Unity integration > Install the plugin > 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](https://assetstore.unity.com/packages/tools/integration/arcweave-for-unity-148326). 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 Context: Arcweave docs > Integrations > Unity integration > Get Arcweave data ### Via Export for Unity Context: Arcweave docs > Integrations > Unity integration > 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 Context: Arcweave docs > Integrations > Unity integration > Get Arcweave data > Via REST API Use of Arcweave REST API is available to [Team workspaces](https://docs.arcweave.com/workspaces/billing-plans) only. You will need: - Your Team workspace [API key](https://docs.arcweave.com/workspaces/api) with **Read projects** enabled (found in your workspace's **API section**). - Your [project hash](https://docs.arcweave.com/project-tools/settings#project-hash) (found in your project's **Settings > Properties**). ## Create ArcweaveProjectAsset Context: Arcweave docs > Integrations > Unity integration > 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 Context: Arcweave docs > Integrations > Unity integration > Create ArcweaveProjectAsset > 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 Context: Arcweave docs > Integrations > Unity integration > Demo scene The plugin includes a `Demo` folder with a complete example scene. ### Run the demo Context: Arcweave docs > Integrations > Unity integration > Demo 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 Context: Arcweave docs > Integrations > Unity integration > Demo scene > 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 Context: Arcweave docs > Integrations > Unity integration > Demo scene > 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 Context: Arcweave docs > Integrations > Unity integration > Demo scene > 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()`, using the filename without its extension. ## Plugin reference guide Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide ### Project Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Project The root container for an imported Arcweave project. Access via `ArcweaveProjectAsset.Project`. #### Properties Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Project > Properties | Property | Type | Description | | --------------------------- | ----------------- | ------------------------------------ | | `name` | string | Project name | | `Boards` | List\ | All boards in the project | | `components` / `Components` | List\ | All components (characters/entities) | | `Variables` | List\ | All global variables | | `StartingElement` | Element | Entry point for the narrative | #### Methods Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Project > 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(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 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 Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > 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: ```arcscript 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. ```csharp 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 Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Board Container for narrative nodes. #### Properties Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Board > Properties | Property | Type | Description | | ------------ | ----------------- | ------------------------------------------- | | `Id` | string | Unique identifier | | `CustomId` | string | Arcweave custom ID used as a variable scope | | `Name` | string | Board name | | `Nodes` | List\ | All nodes (Elements, Branches, Jumpers) | | `Notes` | List\ | Annotation notes | | `Attributes` | List\ | Board attributes | | `Variables` | List\ | Variables scoped to this board | #### Methods Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Board > Methods | Method | Description | | ---------------------------------- | ----------------------- | | `T NodeWithID(string id)` | Get node by ID and type | | `Element ElementWithID(string id)` | Get element by ID | ### Element Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Element A narrative node containing dialogue content. #### Properties Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Element > 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\ | Attached characters/entities | | `Attributes` | List\ | Custom metadata | | `Outputs` | List\ | Outgoing connections | | `cover` | Cover | Cover image reference | | `AudioAssets` | AudioAsset[] | Audio assets attached to this element | #### Methods Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > 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 Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Element > Code Example ```csharp // 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 Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Connection Link between nodes with optional label. #### Properties Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Connection > 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 Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Connection > Methods | Method | Description | | ----------------------- | ----------------------------------------- | | `void RunLabelScript()` | Evaluate Arcscript → updates RuntimeLabel | ### Branch Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Branch Conditional branching node with if/elseif/else logic. #### Properties Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Branch > Properties | Property | Type | Description | | ------------ | ----------------- | ------------------------------------ | | `Id` | string | Unique identifier | | `Conditions` | List\ | Ordered conditions (first true wins) | | `colorTheme` | string | Visual theme color | ### Condition Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Condition Single condition in a branch. #### Properties Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Condition > Properties | Property | Type | Description | | -------- | ---------- | ------------------------------ | | `Id` | string | Unique identifier | | `Script` | string | Arcscript condition expression | | `Output` | Connection | Output connection if true | #### Methods Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Condition > Methods | Method | Description | | ----------------- | ---------------------------------------------- | | `bool Evaluate()` | Evaluate condition (empty scripts return true) | ### Jumper Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Jumper Navigation shortcut to another element. #### Properties Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Jumper > Properties | Property | Type | Description | | -------- | ------- | ------------------------- | | `Id` | string | Unique identifier | | `Target` | Element | Target element to jump to | ### Component Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Component Character or entity definition. **Not a Unity MonoBehaviour.** #### Properties Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Component > Properties | Property | Type | Description | | ------------ | ----------------- | ------------------------------------------- | | `Id` | string | Unique identifier | | `CustomId` | string | Arcweave custom ID used as a variable scope | | `Name` | string | Component name | | `Attributes` | List\ | Custom attributes | | `Variables` | List\ | Variables scoped to this component | | `cover` | Cover | Cover image reference | #### Methods Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Component > Methods | Method | Description | | --------------------------- | ------------------------------- | | `Texture2D GetCoverImage()` | Load cover image from Resources | ### Attribute Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Attribute Custom metadata on elements, components, or boards. #### Properties Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Attribute > 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 Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Variable Global, board-scoped, or component-scoped state variable. Supports: `int`, `double`, `bool`, `string`. #### Properties Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Variable > 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 Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Variable > Methods | Method | Description | | ---------------------------- | ---------------------- | | `void ResetToDefaultValue()` | Reset to default value | ### Cover Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Cover Image or video reference. #### Properties Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Cover > Properties | Property | Type | Description | | ---------- | ---------- | ---------------------------- | | `type` | Cover.Type | Image, Youtube, or Undefined | | `filePath` | string | Asset filename | #### Methods Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Cover > Methods | Method | Description | | -------------------------- | -------------------------------- | | `Texture2D ResolveImage()` | Load image from Resources folder | ### Options Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Options Available paths from an element. Created by `Element.GetOptions()`. #### Properties Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Options > Properties | Property | Type | Description | | ------------ | ------------ | ---------------------------------------- | | `Element` | Element | Source element | | `Paths` | List\ | Valid paths to next elements | | `hasPaths` | bool | True if any paths exist | | `hasOptions` | bool | True if multiple paths OR path has label | ### Path Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Path Resolved path to a target element. #### Properties Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Path > Properties | Property | Type | Description | | --------------- | ------- | ------------------------------- | | `label` | string | Connection label (if any) | | `text` | string | Label or target element's title | | `TargetElement` | Element | Destination element | #### Methods Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > Path > Methods | Method | Description | | ---------------------------------------- | ------------------------------------------------- | | `void ExecuteAppendedConnectionLabels()` | Run Arcscript in all connection labels along path | ### ArcweavePlayer Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > ArcweavePlayer Event-driven narrative player (demo helper class). #### Inspector Fields Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > ArcweavePlayer > Inspector Fields | Field | Type | Description | | ----------- | -------------------- | ------------------------ | | `aw` | ArcweaveProjectAsset | The project to play | | `autoStart` | bool | Auto-start on scene load | #### Events Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > ArcweavePlayer > Events | Event | Signature | Description | | ------------------ | ------------------------ | --------------------------------- | | `onProjectStart` | `(Project)` | Narrative started | | `onProjectFinish` | `(Project)` | Narrative ended | | `onElementEnter` | `(Element)` | Entered new element | | `onElementOptions` | `(Options, Action)` | Multiple choices available | | `onWaitInputNext` | `(Action)` | Single path, waiting for continue | #### Methods Context: Arcweave docs > Integrations > Unity integration > Plugin reference guide > ArcweavePlayer > 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 Context: Arcweave docs > Integrations > Unity integration > 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](https://docs.arcweave.com/integrations/unity#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 Context: Arcweave docs > Integrations > Unity integration > 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` ```csharp element.RunContentScript(); ``` ❌ **Getting `NullReferenceException` when accessing variables** Variables are null or throw errors. ✅ Call `Initialize` once before using the project: ```csharp 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 Context: Arcweave docs > Integrations > Unity integration > License See the [LICENSE file](https://github.com/arcweave/arcweave-unity-plugin/blob/main/LICENSE) on GitHub for details. # 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 Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. 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. # Godot Engine integration Source: https://docs.arcweave.com/integrations/godot Section: Integrations Description: Install the Arcweave Godot plugin, import project data, and use its Story and Project classes from C# or GDScript Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. Arcweave provides a free plugin for importing your Arcweave projects into the .NET edition of [Godot Engine](https://godotengine.org/) (version 4.4 or later). The plugin can import data from Arcweave's [JSON](https://docs.arcweave.com/integrations/json) (available to all workspaces) or fetch it using Arcweave's [REST API](https://docs.arcweave.com/rest-api/overview) (Team workspaces only). ## Tutorials Context: Arcweave docs > Integrations > Godot Engine integration > Tutorials For a step-by-step walkthrough and videos on this integration, see the [Godot Engine integration tutorial](https://docs.arcweave.com/tutorials/godot/overview). ## Plugin repository Context: Arcweave docs > Integrations > Godot Engine integration > Plugin repository You can download the Arcweave plugin for Godot Engine using [its GitHub link](https://github.com/arcweave/arcweave-godot-plugin). ## Example project Context: Arcweave docs > Integrations > Godot Engine integration > Example project ![Animated GIF image showing a segment of the Godot example project's gameplay: it is a simple 3D third-person RPG setup, where the player approaches an NPC called Healer and starts dialogue with him. After the dialogue, a healing potion appears in the player's inventory.](https://github.com/arcweave/arcweave-godot-example/raw/main/readme-images/demo.gif) Explore our [Godot example project](https://github.com/arcweave/arcweave-godot-example) to see Arcweave's implementation with Godot 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. ## Requirements Context: Arcweave docs > Integrations > Godot Engine integration > Requirements - **Godot Engine**: You must use the [.NET version](https://godotengine.org/) of Godot. - **Arcweave plugin**: Available on the [Godot Asset Library](https://godotengine.org/asset-library/asset/1912) or from the [GitHub repository](https://github.com/arcweave/arcweave-godot-plugin). ## Install & activate Context: Arcweave docs > Integrations > Godot Engine integration > Install & activate ### Install Context: Arcweave docs > Integrations > Godot Engine integration > Install & activate > Install Complete the following steps to install the Arcweave plugin for Godot Engine: 1. Download the plugin from its [GitHub repository](https://github.com/arcweave/arcweave-godot-plugin). 2. Add the plugin's `addons/arcweave` folder to your Godot project's `addons` directory. 3. Reload the project. > ℹ️ If you download via "Download ZIP", you will only get the `addons` folder. To get the test project as well, clone the repo or download the full release ZIP file. ### Create C# solution Context: Arcweave docs > Integrations > Godot Engine integration > Install & activate > Create C# solution If you haven't already, go to `Project > Tools > C# > Create C# Solution`. This will create `.csproj` and `.sln` files in your root directory. Then, open the `.csproj` file in a text editor and add the following after the `PropertyGroup` section's closing tag: ```xml ``` The file will now look similar to this: ```xml net8.0 true ``` This installs the Antlr4 library required for parsing Arcscript. ### Build Context: Arcweave docs > Integrations > Godot Engine integration > Install & activate > Build Now, build your Godot project: click **Build** (the hammer icon at the top right of the editor, next to the Play buttons). Or press **Alt+B**. ### Activate the plugin Context: Arcweave docs > Integrations > Godot Engine integration > Install & activate > Activate the plugin In Godot Engine, reload your project. Then, go to `Project > Project Settings > Plugins`, find **Arcweave**, and enable it. ## Importing Arcweave project data Context: Arcweave docs > Integrations > Godot Engine integration > Importing Arcweave project data You can import your Arcweave project data into Godot using one of two methods: ### Folder import Context: Arcweave docs > Integrations > Godot Engine integration > Importing Arcweave project data > Folder import 1. In Arcweave, click **Export project**. 2. Go to the **Engine** tab and select **Export for Godot**. 3. Optionally, clear **Include assets** if you only need the project data. 4. Click **Export**. Arcweave downloads a `.zip` file. 5. Extract the `project.json` file from the `.zip` file. ### API import (Team workspaces only) Context: Arcweave docs > Integrations > Godot Engine integration > Importing Arcweave project data > API import (Team workspaces only) 1. In Arcweave, obtain 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). 2. In Godot, provide this information in the plugin's interface. ## ArcweaveAsset Context: Arcweave docs > Integrations > Godot Engine integration > ArcweaveAsset To import your data into Godot, you must first create and initialize an **ArcweaveAsset** resource, in your Godot project. Follow the next steps: 1. In the FileSystem tab, right-click and select **New Resource**. 2. Choose **ArcweaveAsset** and give it a name. 3. In the Inspector, choose your data source: - **Importing from JSON**: Set **Receive Method** to **File**. Under **File Settings**, set **Project File** to the extracted `project.json` file. - **Importing from API**: Set **Receive Method** to **WebAPI**. Under **API Settings**, fill the **API Key** and **Project Hash** values. 4. Click **Initialize Arcweave Asset** to load the data onto the resource. ## Using Arcweave data Context: Arcweave docs > Integrations > Godot Engine integration > Using Arcweave data You can use the plugin with either a custom node or the provided `ArcweaveNode`. ### Using `ArcweaveNode` Context: Arcweave docs > Integrations > Godot Engine integration > Using Arcweave data > Using `ArcweaveNode` This plugin creates a new **ArcweaveNode** class (inheriting from Godot's Node), that you can use in your scenes to integrate your Arcweave Project in your game. ArcweaveNode exposes and manages the following: - `ArcweaveAsset`: The resource you already created and initialized. - `Story`: The class that handles the Arcweave project and its flow. It stores all the info regarding your project and it is the way we are interacting with it. - `APIRequest`: A child node created by ArcweaveNode that handles the connection to the Arcweave API for requesting and retrieving the updated Arcweave project. Add an ArcweaveNode as a child node in your scene and use the Inspector tab to connect it to your `ArcweaveAsset` resource that you created earlier, as follows: 1. Add an `ArcweaveNode` as a child in your scene. 2. In the Inspector, connect it to your `ArcweaveAsset`. To reload the project data while the game runs, call the node's `UpdateStory()` method. It refreshes the ArcweaveAsset using its **Receive Method** (set it to **WebAPI** to fetch the latest data from the API), then updates the `Story` and emits the node's `ProjectUpdated` signal. ### Using a custom node Context: Arcweave docs > Integrations > Godot Engine integration > Using Arcweave data > Using a custom node Using the plugin's `ArcweaveNode` is not mandatory. You can also create your own nodes and interact with the `ArcweaveAsset`. In order to update during runtime though, you will have to add the `APIRequest` script (`addons/arcweave/Editor/APIRequestScript.gd`) to your scene and initialize the `Story` class directly in GDScript or C#. Examples are available on the plugin's GitHub repo: - [GDScript: Example scene with ArcweaveNode](https://github.com/arcweave/arcweave-godot-plugin/blob/main/scripts/gd_script_scene.gd) - [GDScript: Example scene without ArcweaveNode](https://github.com/arcweave/arcweave-godot-plugin/blob/main/scripts/gd_script_scene_no_arcweave_node.gd) - [C#: Example scene with ArcweaveNode](https://github.com/arcweave/arcweave-godot-plugin/blob/main/scripts/CSharpScene.cs) - [C#: ArcweaveNode script](https://github.com/arcweave/arcweave-godot-plugin/blob/main/addons/arcweave/Editor/ArcweaveNode.cs) ## Our implementation Context: Arcweave docs > Integrations > Godot Engine integration > Our implementation Most of our implementation, except ArcweaveAsset and some editor GDScript classes, is written in C#. This means that not all of the API is available in GDScript, because of type compatibility issues. The interpreter we are using for **Arcscript** is written in C# and uses built-in types. ## Using the plugin Context: Arcweave docs > Integrations > Godot Engine integration > Using the plugin Using Godot's functionality for [cross-language scripting](https://docs.godotengine.org/en/stable/tutorials/scripting/cross_language_scripting.html) you can use the plugin both from GDScript and C# Godot projects. The only limitation is that you must use the _.NET_ version of Godot Engine. The [plugin's repo](https://github.com/arcweave/arcweave-godot-plugin) provides a simple demo of both implementations. ### Scoped variables Context: Arcweave docs > Integrations > Godot Engine integration > Using the plugin > 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, while the board or component custom ID is its scope: ```arcscript health = 100 castle.health = 10 hero.health = 20 ``` Unqualified names resolve global variables only. In C#, use the [Project class](https://docs.arcweave.com/integrations/godot#project-class) methods `GetScopedVariable(name, scope)` and `SetScopedVariable(name, scope, value)` for scoped values; get the project from `Story.GetProject()`. The existing `GetVariable(name)` and `SetVariable(name, value)` APIs remain global-only. `GetAllVariables()` enumerates every scope, while `SetVariableById(id, value)` applies a change using the stable Arcweave variable or attribute ID. Variable saves and `Story.GetVariableChanges()` use stable IDs as keys so the same member name can exist in multiple scopes. If your JSON file was exported before legacy board variables were migrated to attributes, export the project again. ### C# example Context: Arcweave docs > Integrations > Godot Engine integration > Using the plugin > C# example **How to use the plugin in a C# Godot Project** The main class that the user should use is the [**Story**](https://docs.arcweave.com/integrations/godot#story-class) class of the plugin. This has most of the functionality needed to traverse through a Project. Story is stored as a property inside our ArcweaveNode so our examples are based on that. To start a Project's Story you have to initialize a Story instance with its project settings, as well as an instance of APIRequest to be able to update your project on runtime. ArcweaveNode handles that in its `_Ready` function, so if you are using this Node Type, you don't have to do it. ```csharp public override void _Ready() { Dictionary projectSettings = (Dictionary)ArcweaveAsset.Get("project_settings"); Story = new Story(projectSettings); var requestScript = GD.Load("res://addons/arcweave/Editor/APIRequestScript.gd"); ApiRequest = (Node)requestScript.New(ArcweaveAsset); AddChild(ApiRequest); } ``` During the initialization, the data is loaded, the starting_element is set and the Element Options are generated. If you have a text container you can use the `Story.GetCurrentRuntimeContent()` function to get the text of the current element and set it. In our Demo project, we have a function called `Repaint()` that updates our TextContainer with the new content. ```csharp private void Repaint() { TextContainer.Text = ArcweaveNode.Story.GetCurrentRuntimeContent(); } ``` You can also use `Story.GenerateCurrentOptions()` function to get the options of the current element: ```csharp private void Repaint() { TextContainer.Text = ArcweaveNode.Story.GetCurrentRuntimeContent(); AddOptions(); } private void AddOptions() { // Empty the previous options foreach (var b in OptionContainer.GetChildren()) { OptionContainer.RemoveChild(b); } // Retrieve the current options Options options = ArcweaveNode.Story.GenerateCurrentOptions(); if (options.Paths != null) { foreach (var path in options.Paths) { if (path.IsValid) { Button button = CreateButton(path); OptionContainer.AddChild(button); } } } } ``` To select a certain option and continue the story path, we add a signal handler for the button in `CreateButton` that we used earlier, where we select the Path that we provided using `Story.SelectPath()`. When the new path is selected, we call the repaint function to recreate our UI. ```csharp private Button CreateButton(IPath path) { Button button = new Button(); button.Text = path.label; button.Pressed += () => OptionButtonPressed(path); return button; } private void OptionButtonPressed(IPath path) { ArcweaveNode.Story.SelectPath(path as Path); Repaint(); } ``` ### GDScript example Context: Arcweave docs > Integrations > Godot Engine integration > Using the plugin > GDScript example **How to use the plugin in a GDScript Godot Project** The GDScript example below shows the custom-node setup: load the C# `Story` class, create an `APIRequest`, connect the `project_updated` signal, and initialize `story` from your ArcweaveAsset's project settings. If you use the provided `ArcweaveNode` instead, it handles this setup and exposes `arcweave_node.Story` directly. ```gdscript # Your ArcweaveAsset resource file var arcweave_asset: ArcweaveAsset = preload("res://resources/ArcweaveAsset.tres") var api_request: APIRequest var Story = load("res://addons/arcweave/Story.cs") var story func _ready(): api_request = APIRequest.new(arcweave_asset) arcweave_asset.project_updated.connect(_on_project_updated) add_child(api_request) story = Story.new(arcweave_asset.project_settings) func _on_project_updated(project_settings): story.UpdateStory(project_settings) repaint() ``` During the initialization, the data is loaded, the starting_element is set and the Element Options are generated. If you have a text container (here, a RichTextLabel node saved as `text_window`) you can use the `story.GetCurrentRuntimeContent()` function to get the text of the current element and set it. In our Demo project, we have a function called `repaint()` that updates our TextContainer with the new content. ```gdscript func repaint(): text_window.text = story.GetCurrentRuntimeContent() ``` You can also use `story.GenerateCurrentOptions()` function to get the options of the current element: ```gdscript func repaint(): text_window.text = story.GetCurrentRuntimeContent() add_options() func add_options(): for option in options_container.get_children(): options_container.remove_child(option) option.queue_free() var options = story.GenerateCurrentOptions() var paths = options.Paths if paths != null: for path in paths: if path.IsValid: var button : Button = create_button(path) options_container.add_child(button) ``` To select a certain option and continue the story path, we add a signal handler for the button in `create_button` that we used earlier, where we select the Path that we provided using `story.SelectPath()`. When the new path is selected, we call the repaint function to recreate our UI. ```gdscript func create_button(path): var button : Button = Button.new() button.text = path.label button.pressed.connect(option_button_pressed.bind(path)) return button func option_button_pressed(path): story.SelectPath(path) repaint() ``` ## Story class Context: Arcweave docs > Integrations > Godot Engine integration > Story class ### Properties Context: Arcweave docs > Integrations > Godot Engine integration > Story class > Properties | Property | Description | | :-------------------------------- | :------------------------------------------------------ | | `VariableChanges VariableChanges` | Tracks variable changes caused by the latest selection. | ### Methods Context: Arcweave docs > Integrations > Godot Engine integration > Story class > Methods | Method Name | Description | | :--------------------------------------------------------------------- | :------------------------------------------------------------ | | `Story(Dictionary projectData)` | Initializes a Story with the project data. | | `Story UpdateStory(Dictionary projectData)` | Updates the story with new project data. | | `void ResetStory()` | Resets variables, visits, and the current element. | | `void SetCurrentElementById(string id)` | Sets the current element by element ID. | | `void SetCurrentElement(Element element)` | Sets the current element. | | `Options GenerateCurrentOptions()` | Returns the current element's options. | | `void SelectPath(Path path)` | Selects a path/option. | | `Project GetProject()` | Returns the project instance. | | `Element GetCurrentElement()` | Returns the current element. | | `string GetCurrentRuntimeContent()` | Returns the current element's runtime content. | | `Dictionary> GetVariableChanges()` | Returns old and new values for variables changed by the path. | | `Dictionary GetSave()` | Returns the current story state as a save dictionary. | | `void LoadSave(Dictionary save)` | Loads a save dictionary created by `GetSave()`. | ## Project class Context: Arcweave docs > Integrations > Godot Engine integration > Project class ### Properties Context: Arcweave docs > Integrations > Godot Engine integration > Project class > Properties | Property | Description | | :----------------------------------------- | :----------------------------------- | | `string Name` | The Project's name. | | `Dictionary Boards` | The Boards of the Project. | | `Dictionary Components` | The Components of the Project. | | `Array Variables` | The global variables of the Project. | | `Dictionary Elements` | The Elements of the Project. | | `Dictionary Assets` | The Assets of the Project. | | `Element StartingElement` | The starting element of the Project. | ### Methods Context: Arcweave docs > Integrations > Godot Engine integration > Project class > Methods | Method Name | Description | | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------- | | `Element ElementWithId(string id)` | Returns an element by ID, or null if it does not exist. | | `void ResetVariables()` | Resets project variables to their default values. | | `void ResetVisits()` | Resets all element visit counts to 0. | | `Variable GetVariable(string name)` | Returns a global variable by name, or null. | | `Variable GetScopedVariable(string name, string scope)` | Returns a board/component variable by name and owner custom ID. | | `Variable GetVariableById(string id)` | Returns any variable by its stable Arcweave ID. | | `IEnumerable GetAllVariables()` | Enumerates global, board, and component variables. | | `void Set(Element startingElement, Dictionary boards, Dictionary components, Array variables, Dictionary elements, Dictionary assets)` | Sets the project's main data collections. | | `Project Merge(Project project)` | Merges a new project into the current runtime state. | | `Dictionary GetBoards()` | Returns the project's boards. | | `bool SetVariable(string name, object value)` | Sets a global variable value. | | `bool SetScopedVariable(string name, string scope, object value)` | Sets a board/component variable value. | | `bool SetVariableById(string id, object value)` | Sets any variable by its stable Arcweave ID. | | `Dictionary SaveVariables()` | Saves all scopes using stable IDs as keys. | | `void LoadVariables(Dictionary save)` | Loads global and scoped values from a save dictionary. | # Arcscript interpreters Source: https://docs.arcweave.com/integrations/arcscript-interpreters Section: Integrations Description: Implementing custom Arcweave solutions with the Arcscript interpreters for C++, C#, and TypeScript Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `` for text, ` ` for an empty line, and each Arcscript segment in its own `` block, with `<` written as `<`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID. The [arcscript-interpreters](https://github.com/arcweave/arcscript-interpreters) repository contains the supported interpreters for **[Arcscript](https://docs.arcweave.com/project-items/arcscript)**, the scripting language of [Arcweave](https://arcweave.com). They evaluate conditions, update variables, and render Arcscript output in your own applications and game engines. | Implementation | Runtime | Used by | | ------------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------- | | [TypeScript](https://github.com/arcweave/arcscript-interpreters/tree/main/TypeScript) | ES2022 with browser DOM APIs | The Arcweave app and JavaScript or TypeScript applications | | [C#](https://github.com/arcweave/arcscript-interpreters/tree/main/CSharp) | .NET 6 | The [Unity](https://docs.arcweave.com/integrations/unity) and [Godot Engine](https://docs.arcweave.com/integrations/godot) plugins | | [C++](https://github.com/arcweave/arcscript-interpreters/tree/main/Cpp) | C++17 and CMake 3.10 or newer | The [Unreal Engine](https://docs.arcweave.com/integrations/unreal) plugin and other native applications | Each implementation's folder contains a guide with setup instructions, API examples, and tests. The interpreters are built using [ANTLR 4](https://github.com/antlr/antlr4), a parser generator for reading, processing, executing, or translating structured text or binary files. ## Why a parser generator? Context: Arcweave docs > Integrations > Arcscript interpreters > Why a parser generator? In order to support updating game data from Arcweave that uses Arcscript during runtime in game engines, we had to find a way to interpret it without having to rebuild the game. This led us to use a parser generator. ANTLR 4 is a great option for that, since it can create parsers for multiple languages from the same grammar, including C++ (which we use for Unreal), C# (for Unity and Godot), and TypeScript (for our frontend). ## Our implementation Context: Arcweave docs > Integrations > Arcscript interpreters > Our implementation In the [`grammar`](https://github.com/arcweave/arcscript-interpreters/tree/main/grammar) folder, you can find the files [`ArcscriptLexer.g4`](https://github.com/arcweave/arcscript-interpreters/blob/main/grammar/ArcscriptLexer.g4) and [`ArcscriptParser.g4`](https://github.com/arcweave/arcscript-interpreters/blob/main/grammar/ArcscriptParser.g4), the grammar files for the lexer and the parser, respectively. ## Script input Context: Arcweave docs > Integrations > Arcscript interpreters > Script input The interpreters read Arcscript as HTML, the way Arcweave stores it. Each Arcscript segment is a `…` block, as in element content and connection labels in the [Arcweave JSON](https://docs.arcweave.com/integrations/json#rich-text-and-arcscript): ```html health -= 10 show(health) ``` Branch [condition scripts](https://docs.arcweave.com/integrations/json#conditions) are stored without this wrapper. Wrap a condition's `script` in `` and `` before you run it; the interpreter then returns the condition's boolean result. ## Generate parsers Context: Arcweave docs > Integrations > Arcscript interpreters > Generate parsers Parser generation regenerates the TypeScript, C#, and C++ ANTLR sources from the shared grammar. It is separate from building and testing each interpreter. Prerequisites: - Java 11 or newer, to run the ANTLR tool - Python 3 - `curl` on Linux and macOS, if `antlr4.jar` isn't in the repository root yet - PowerShell on Windows From the repository root, run [`generate.sh`](https://github.com/arcweave/arcscript-interpreters/blob/main/generate.sh) on Linux or macOS: ```bash sh generate.sh ``` On Windows, run [`generate.ps1`](https://github.com/arcweave/arcscript-interpreters/blob/main/generate.ps1): ```powershell .\generate.ps1 ``` The script: 1. Downloads the `antlr4.jar` file, if it isn't already present. 2. Generates the parsers for each language. To build and test an interpreter, follow the guide in its folder. ## Variable scopes and runtime state Context: Arcweave docs > Integrations > Arcscript interpreters > Variable scopes and runtime state All three interpreters support global variables and variables backed by String Field, Boolean, Integer, or Float board/component attributes: ```arcscript health = 100 castle.health = 10 hero.health = 20 ``` Unqualified names resolve global variables only. A qualified name uses the owning board or component custom ID as its scope and the attribute custom ID as its member name. Runtime integrations keep the mutable current value separate from the project-authored default. This allows `reset` and `resetAll` to restore the original value after any number of interpreter calls. Stable Arcweave variable or attribute IDs identify changes and reset exclusions even when different scopes use the same member name. When updating an interpreter integration: - C# project models (`IProject` implementations) must provide a component collection. `GetAllVariables()` enumerates the global, board, and component variables. - C++ consumers must use the current `UVariable` header, marshal both current and default values, and rebuild their native libraries because the scoped-variable update changes the ABI. - Null or missing runtime values are rejected instead of being treated as valid variable state. ## TypeScript Context: Arcweave docs > Integrations > Arcscript interpreters > TypeScript We are using the TypeScript interpreter to interpret Arcscript in our Arcweave app. It is also available as the [`@arcweave/arcscript`](https://www.npmjs.com/package/@arcweave/arcscript) package, built from the generated files in the [TypeScript](https://github.com/arcweave/arcscript-interpreters/tree/main/TypeScript) folder, along with a custom ANTLR visitor that interprets the parse tree. ```sh npm install @arcweave/arcscript ``` The package uses browser DOM APIs, including `document` and `DOMParser`. In Node.js, provide a compatible DOM implementation. ```ts import { Interpreter } from '@arcweave/arcscript'; const interpreter = new Interpreter({ state: { health: { id: 'health', name: 'health', type: 'integer', defaultValue: 100, }, }, }); const { changes, output } = interpreter.runScript( 'health -= 10 show(health)' ); // changes: { health: 90 } // output: '90' ``` The `state` object is keyed by variable ID, and `changes` reports new values by variable ID. Add a `scope` to a variable for board and component variables. For persisting values between runs, conditions, and error handling, see the [TypeScript guide](https://github.com/arcweave/arcscript-interpreters/tree/main/TypeScript). ## C# & C++ Context: Arcweave docs > Integrations > Arcscript interpreters > C# & C++ The C# interpreter's entry point is `AwInterpreter`, which runs scripts against an Arcweave project model. The C++ interpreter provides the `Arcweave::ArcscriptTranspiler` class for C++ applications, and `runScriptExport()` for integrations that load the shared library. Both return rendered output and variable changes keyed by stable variable ID. For setup and examples, see the [C# guide](https://github.com/arcweave/arcscript-interpreters/tree/main/CSharp) and the [C++ guide](https://github.com/arcweave/arcscript-interpreters/tree/main/Cpp). ## Links & references Context: Arcweave docs > Integrations > Arcscript interpreters > Links & references - [Arcweave](https://arcweave.com/) - [arcscript-interpreters on GitHub](https://github.com/arcweave/arcscript-interpreters) - [ANTLR](https://www.antlr.org/) # REST API Source: https://docs.arcweave.com/rest-api/overview Section: REST API Description: Authenticate with Arcweave's REST API for read and write access to your projects Arcweave's REST API provides read and write access to projects in a Team workspace. You can retrieve exports, create and edit project content, import projects, synchronize assets and components, or build custom integrations. > ⚠️ The REST API is available to Team workspaces only. Access depends on both the API key's project permissions and the permissions of the member who created it. ## Base path and version Context: Arcweave docs > REST API > Base path and version Use the versioned base path for all new integrations: ```text /api/v1 ``` The unversioned `/api` routes currently remain as aliases, but integrations should use `/api/v1` so their contract is explicit. Most project endpoints include the project's hash: ```text /api/v1/{hash}/... ``` You can find the hash in [Project settings](https://docs.arcweave.com/project-tools/settings#project-hash). ## API tokens Context: Arcweave docs > REST API > API tokens Arcweave displays API tokens as **API keys** in the workspace interface. ### Create an API key Context: Arcweave docs > REST API > API tokens > Create an API key 1. Open the workspace **API** section. 2. Click **Create new key** and enter a descriptive name. 3. Under **Project permissions**, select **Read projects**, **Write projects**, or both. **Read projects** is selected by default; at least one permission is required. 4. Click **Create**, then copy the key from the **Key** column and store it securely. See [Workspace API](https://docs.arcweave.com/workspaces/api) for key management instructions. > ⚠️ API keys grant access to workspace project data. Never expose a key in browser code, a public repository, or an application distributed to end users. ## Authentication and headers Context: Arcweave docs > REST API > Authentication and headers Send the API key as a bearer token and include `Accept: application/json` on every request, including `GET` requests. Requests with a JSON body should also send `Content-Type: application/json`: ```http Authorization: Bearer YOUR_API_KEY Accept: application/json Content-Type: application/json ``` The `Accept` header ensures that missing or invalid credentials return a JSON `401 Unauthorized` response. Without it, an unauthenticated request can return `302 Found` with a redirect to `/login`; clients that follow the redirect receive an HTML login page. See [Error responses](https://docs.arcweave.com/rest-api/overview#error-responses) for the authentication error body. For example: ```http title="HTTP" GET /api/v1/{hash}/board Authorization: Bearer YOUR_API_KEY Accept: application/json ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/board" ``` File uploads use `multipart/form-data` instead of `application/json`. [Creating a media asset](https://docs.arcweave.com/rest-api/assets#create-asset-or-folder) uploads the file and registers the asset in one request. Let your HTTP client set the multipart header and boundary. In curl tabs for JSON mutations, `--data @payload.json` refers to the JSON request body shown below the tabs. Save that body as `payload.json`, or replace the argument with equivalent inline JSON. ## Permissions Context: Arcweave docs > REST API > Permissions ### API key permissions Context: Arcweave docs > REST API > Permissions > API key permissions Each API key has one or both of these permissions: | Workspace label | Token permission | Allowed requests | | ------------------ | ---------------- | --------------------------------------------------------------------------------------------- | | **Read projects** | `project:read` | `GET` and `HEAD`: list, view, and export projects and their content. | | **Write projects** | `project:write` | `POST`, `PATCH`, and `DELETE`: create, import, update, and delete projects and their content. | The permissions are independent. A key with **Write projects** alone cannot read or export data. Select both for an integration that needs read and write access. A request without its required token permission returns `403 Forbidden`. New keys created in the workspace interface start with **Read projects** selected. Keys that existed before project permissions were introduced were assigned both **Read projects** and **Write projects**. Review their permissions in the workspace's API section and use **Edit key** to change them. Permission changes apply immediately. ### Workspace and project permissions Context: Arcweave docs > REST API > Permissions > Workspace and project permissions A key acts as the member who created it, within the key's workspace. Token permissions do not grant that member additional workspace or project access. The following access requirements also apply: | Operations | Access requirement | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Retrieve project resources, CSS, and asset files | **View projects list** permission for the target project. | | Create, update, move, reorder, or delete resources | **Edit projects** permission for the target project. | | List workspace projects | **View projects list** permission for the workspace. Without it, this endpoint returns `403 Forbidden`, even if the key owner has access to individual projects. | | Create a project | **Create projects** permission for the workspace, plus available project capacity. | | Import a project | **Import projects** permission for the workspace, plus available project and item capacity. | | Rename a project | **Edit projects** permission for the target project. | | Delete a project | **Delete projects** permission for the target project. | | Retrieve JSON, Unity, Unreal Engine, or Godot exports | The corresponding export feature must be enabled for the workspace, and the project must belong to the token's workspace. | ## Make your first write Context: Arcweave docs > REST API > Make your first write Create a key with both **Read projects** and **Write projects**, then choose a project you can edit in that key's workspace. Replace `YOUR_API_KEY` and `PROJECT_HASH` below with your key and [project hash](https://docs.arcweave.com/project-tools/settings#project-hash). Create a board: ```bash curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{"name":"API example"}' \ "https://arcweave.com/api/v1/PROJECT_HASH/board" ``` The response is `201 Created` and includes the new board's `id`. Replace `BOARD_ID` with that value to read the board back: ```bash curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/board/BOARD_ID" ``` The response is `200 OK` with the board data. See [Boards](https://docs.arcweave.com/rest-api/boards) for updating, moving, and deleting boards. ## Rate limits Context: Arcweave docs > REST API > Rate limits API quotas are shared by all users and API keys in the workspace associated with the key. Each workspace has independent quotas. Versioned `/api/v1` routes and their unversioned `/api` aliases share the same quotas. Requests through the [Arcweave MCP server](https://docs.arcweave.com/integrations/mcp) also count toward these workspace quotas. | Quota | Requests per minute | | ------------------------------------- | -------------------- | | All REST API requests | 60 × workspace seats | | Project imports and exports, combined | 3 × workspace seats | Seats are purchased subscription seats, including unused seats and the combined monthly and yearly subscription quantities. A trial workspace with no purchased seats receives a one-seat allowance. Existing plan and API key permissions still apply. For example, a workspace with five seats can make **300 API requests per minute, including up to 15 project imports and exports combined**. Import and export requests consume both quotas. Exhausting the import/export quota still allows other API requests while the overall quota has capacity. The import/export quota applies to these endpoints and their unversioned aliases: - `POST /api/v1/workspace/projects/import` - `GET` and `HEAD /api/v1/{hash}/json` - `GET` and `HEAD /api/v1/{hash}/godot` - `GET` and `HEAD /api/v1/{hash}/unity` - `GET` and `HEAD /api/v1/{hash}/unreal` Each quota uses a 60-second window beginning with its first counted request. Requests admitted by the limiter count even if subsequent validation or authorization fails. Requests rejected by the limiter do not consume allowance. Responses passing through the limiter include `X-RateLimit-Limit` and `X-RateLimit-Remaining`, which report the request allowance and remaining requests. When both quotas apply, these headers describe the quota with fewer remaining requests. An exhausted quota returns `429 Too Many Requests` with `Retry-After` as an integer number of seconds and `X-RateLimit-Reset` as a Unix timestamp. If multiple applicable quotas are exhausted, these headers describe the longest wait. ### Retrying requests Context: Arcweave docs > REST API > Rate limits > Retrying requests A request rejected by the API rate limiter with `429` has not been applied. Wait at least the number of seconds in `Retry-After` before retrying, and coordinate requests across all users, API keys, and workers using the same workspace. Concurrent requests can consume renewed capacity. A timeout, lost connection, or `5xx` response does not tell you whether a write succeeded. The API does not support the `Idempotency-Key` header: repeating a create or import request can create a second resource or project, and repeating a media upload can create another asset and store another file. Do not automatically retry these requests after an ambiguous failure. First inspect the current project state to determine whether the operation completed; for uploads, check [Get assets](https://docs.arcweave.com/rest-api/assets#get-assets). If you cannot establish the result, resolve it before resubmitting. A media upload rejected with `410 Gone` expired before file storage began and can be retried with a fresh upload request. Read requests can be retried after transient failures. Before retrying an update, move, or delete, read the affected resources and check whether the intended change already happened or whether another editor changed the state. These readback checks require **Read projects** permission. ## Response conventions Context: Arcweave docs > REST API > Response conventions Create operations normally return `201 Created` with the generated resource ID: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` Successful update, move, and delete operations normally return `200 OK`: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` `version` is the project version before the request, `newVersion` is the version after the request is successfully applied, and `versionTime` is the update timestamp returned by the project service. If an operation makes no change, `newVersion` can equal `version` and `versionTime` can be `null`. ### Concurrent edits Context: Arcweave docs > REST API > Response conventions > Concurrent edits The returned version fields describe a completed operation. The API does not accept an expected project version or support `If-Match` conditional writes, so these fields do not prevent an update from overwriting another editor's changes. Send only the fields you intend to change. When a write depends on existing data, read that data first and coordinate writes from your integration. Reading before writing still leaves a window for another editor to make a change. Separate requests are not a single transaction; if a later request fails, earlier successful requests remain applied. On `409 Conflict`, inspect the error and read the affected resources again. Correct the request for the current project state before retrying. A `409` reports a detected state or relationship conflict; it does not mean every concurrent edit is detected. ### Error responses Context: Arcweave docs > REST API > Response conventions > Error responses With `Accept: application/json`, a missing or invalid API key returns `401 Unauthorized` with an `application/json` body: ```json { "error": "Unauthenticated." } ``` Use the HTTP response status to identify the failure; this authentication error body contains only the `error` field. Validation and permission errors use a JSON object with a human-readable `title`, HTTP `status`, and optional field errors. These responses have the `application/problem+json` content type: ```json { "title": "Bad Request - element.create payload", "status": 400, "detail": null, "errors": { "x": "The x field is required." }, "errorCode": 0 } ``` Concurrent or relationship conflicts return `409 Conflict` and may include `type`, `conflictType`, and `context`: ```json { "title": "Integrity error: Cannot create element on missing board: b1", "status": 409, "detail": "The target board does not exist.", "errors": [], "errorCode": 0, "type": "integrity_conflict", "conflictType": "missing_parent", "context": { "boardId": "b1", "parentType": "board" } } ``` The following table lists the HTTP status codes the API may return: | Status | Meaning | | ------ | ----------------------------------------------------------------------------- | | `200` | Request completed successfully. | | `201` | Resource created successfully. | | `400` | Invalid payload or unsupported operation. | | `401` | Missing or invalid API key. | | `403` | API feature, token permission, workspace access, or member permission denied. | | `404` | Project or resource not found. | | `405` | HTTP method not supported for the requested path, including POST to the removed `/asset/upload` route. | | `409` | The project state conflicts with the requested command. | | `410` | Media upload reservation expired before file storage began. Retry the upload. | | `429` | Request rate limit exceeded. | | `500` | Unexpected export or server error. | ## General request rules Context: Arcweave docs > REST API > General request rules - Resource IDs created through the API are server-generated UUIDs. Do not send an `id` when creating a resource unless an endpoint explicitly documents it as a reference. - Unexpected JSON properties are rejected instead of ignored. - `PATCH` requests must contain at least one supported field. - Reorder endpoints end in `/index` and use a zero-based, non-negative `index` request field. - In create, move, and reorder requests, an `index` at or past the end of the target list appends the item. - Elements, notes, jumpers, and branches must fit entirely inside the `40000` by `40000` board canvas. Their `x` and `y` coordinates must be non-negative and cannot exceed the canvas dimensions minus the item's width and height. - Root containers cannot be moved or deleted. - Moving a folder into itself or one of its descendants is rejected. - Arcscript sent in a request is parsed before it is saved: code blocks in element content and connection labels, and branch condition scripts. Scripts must be valid and reference existing variables, attributes, and mentioned elements. Invalid scripts return `400 Bad Request` with the title `Bad Request - invalid Arcscript` and an `errors` entry for each affected field. Requests without script fields don't revalidate existing scripts. - If the project changes while submitted Arcscript is being validated, the request returns `409 Conflict` with `conflictType: "arcscript_context_changed"` and isn't applied. Read the current state and retry. For element titles/content, connection labels, and component names, see [Localized content](https://docs.arcweave.com/rest-api/localization) for language setup, default-language writes, partial translation updates, and locale errors. Rich-text fields also follow the [field-specific formatting rules](https://docs.arcweave.com/rest-api/rich-text#supported-html). ### Color themes Context: Arcweave docs > REST API > General request rules > Color themes The `theme` field on elements, notes, branches, and connections accepts only these case-sensitive values: `default`, `orange`, `brown`, `gold`, `moss`, `green`, `cyan`, `lightBlue`, `blue`, `purple`, `pink`, `red`. Creation defaults to `default`. On update, omitting `theme` keeps the current value. Custom color strings and other names are rejected with `400 Bad Request`. ## API reference Context: Arcweave docs > REST API > API reference Choose a resource to find its endpoints, request examples, and response formats: | Resource | Description | | --- | --- | | [Projects](https://docs.arcweave.com/rest-api/projects#list-workspace-projects) | List, create, import, rename, and delete workspace projects. | | [Exports](https://docs.arcweave.com/rest-api/exports) | Export projects as [JSON](https://docs.arcweave.com/rest-api/exports#json-export) or for [Unity](https://docs.arcweave.com/rest-api/exports#export-for-unity), [Unreal Engine](https://docs.arcweave.com/rest-api/exports#export-for-unreal-engine), and [Godot](https://docs.arcweave.com/rest-api/exports#export-for-godot). | | [Boards](https://docs.arcweave.com/rest-api/boards) | Manage boards and folders, and retrieve their contents. | | [Elements](https://docs.arcweave.com/rest-api/elements) | Manage elements, their attachments, and the project's starting element. | | [Connections](https://docs.arcweave.com/rest-api/connections) | Create and edit connections between board items. | | [Notes](https://docs.arcweave.com/rest-api/notes) | Create and edit notes on boards. | | [Comments](https://docs.arcweave.com/rest-api/comments) | Read project comment threads and replies. | | [Jumpers](https://docs.arcweave.com/rest-api/jumpers) | Manage jumpers that point to project elements. | | [Branches and conditions](https://docs.arcweave.com/rest-api/branches) | Manage branches and their if, else-if, and else conditions. | | [Variables](https://docs.arcweave.com/rest-api/variables) | Manage global project variables and their values. | | [Assets](https://docs.arcweave.com/rest-api/assets) | Upload and download files, and organize assets into folders. | | [Components](https://docs.arcweave.com/rest-api/components) | Manage reusable components, folders, and covers. | | [Attributes](https://docs.arcweave.com/rest-api/attributes) | Manage attributes on elements, boards, and components. | | [CSS](https://docs.arcweave.com/rest-api/css) | Retrieve and update the project's custom styles. | # Rich text Source: https://docs.arcweave.com/rest-api/rich-text Section: REST API Description: Supported HTML and validation rules for rich-text REST API fields Rich-text fields in REST API requests accept HTML and use the same [field-specific formatting](https://docs.arcweave.com/project-tools/rich-text#supported-formatting) as the editor. ## Supported HTML Context: Arcweave docs > REST API > Rich text > Supported HTML Use `` for paragraphs, ` ` for line breaks, `` or `` for bold, `` or `` for italic, `` for underline, `` for strikethrough, and `` for links. `` and `` are also accepted and stored as ``. Fields without strikethrough reject ``, ``, and ``, as they reject ``. Use ` … ` only in element content or rich-text attributes. To add an Arcscript segment to element content or a connection label, use a complete `… ` block. An inline `…` tag is rejected; code blocks are also rejected in titles, notes, and rich-text attributes. ## Example Context: Arcweave docs > REST API > Rich text > Example Send this body to [Update element](https://docs.arcweave.com/rest-api/elements#update-element) to update its title and content: ```json { "title": "A quiet room", "content": "You enter the room. Welcome. show(\"Hello\")" } ``` ## Validation Context: Arcweave docs > REST API > Rich text > Validation Unsupported markup returns `400 Bad Request`. The API normalizes accepted HTML when saving it. See [Localized content](https://docs.arcweave.com/rest-api/localization) for choosing which language these values update. Arcscript inside code blocks is also validated before saving. Invalid scripts or references return `400 Bad Request` with the title `Bad Request - invalid Arcscript`. See [General request rules](https://docs.arcweave.com/rest-api/overview#general-request-rules). # Localized content Source: https://docs.arcweave.com/rest-api/localization Section: REST API Description: Locale setup, request formats, and merge behavior for localized REST API writes The following REST API fields accept localized content: | Resource | Fields | Content format | | ------------------------------------ | ------------------ | ---------------------------------------------------------------- | | [Elements](https://docs.arcweave.com/rest-api/elements) | `title`, `content` | [Rich text HTML](https://docs.arcweave.com/rest-api/rich-text#supported-html) | | [Connections](https://docs.arcweave.com/rest-api/connections) | `label` | [Rich text HTML](https://docs.arcweave.com/rest-api/rich-text#supported-html) | | [Components](https://docs.arcweave.com/rest-api/components) | `name` | Text | Create endpoints accept strings, `null`, and locale maps. Update endpoints also accept path-style fields. The examples below assume the project has `en` as its main language and already includes `fr` and `de`. ## Set up project languages Context: Arcweave docs > REST API > Localized content > Set up project languages Add the languages to the project before writing translations. In the editor, open **Localization > Manage languages** and [add each language](https://docs.arcweave.com/project-tools/localization#add-language). Use the exact ISO codes configured there, including their letter case: `en` and `EN` are different codes. The REST API has no endpoint for adding, renaming, or removing project locales. Sending a locale key in a content request does not create that locale. The project's **default locale** is its **Main** language. Passing a field as a string or `null` writes to that language, regardless of which language someone currently has selected in the editor. ## Write the main language Context: Arcweave docs > REST API > Localized content > Write the main language A string value updates only the main language. A `null` value clears only that field's main-language text. Other translations remain unchanged. For example, send this body to `PATCH /api/v1/{hash}/element/{elementID}`: ```json { "title": null, "content": "You enter the room." } ``` With `en` as the main language, this clears the English title and replaces the English content. It leaves the French and German title and content unchanged. On update, omitting a field leaves all of that field's translations unchanged. The same rule applies when you pass a connection `label` or component `name` as a string or `null`. To clear text, send JSON `null`; do not use the string `"null"`. For element titles and content and connection labels, an empty string `""` is treated the same as `null`, including in locale maps and path-style fields. Blank component names follow the [component naming rules](https://docs.arcweave.com/rest-api/components#create-component-or-folder). ## Write specific languages Context: Arcweave docs > REST API > Localized content > Write specific languages A locale map updates only its supplied languages. It does not replace the whole translation map or remove languages that are omitted. For example, send this body to `PATCH /api/v1/{hash}/element/{elementID}`: ```json { "content": { "fr": { "text": "Vous entrez dans la pièce." }, "de": { "text": null } } } ``` This replaces the French content, clears the German content, and keeps the English content and all titles unchanged. Clearing text does not remove the language from the project. Play Mode may display fallback content when a translation is empty. Each map value may be a string, `null`, or an object containing only `text` with a string or `null` value. For example, `"fr": "Bonjour. "` is shorthand for `"fr": { "text": "Bonjour." }`. Use the same map structure for labels and component names. For example, this body updates only the French name through `PATCH /api/v1/{hash}/component/{componentID}`: ```json { "name": { "fr": { "text": "Garde" } } } ``` ## Update one translated field Context: Arcweave docs > REST API > Localized content > Update one translated field Update endpoints also accept a flat JSON key naming the field and locale, separated by `/` or `.`. An optional final `text` segment is supported. The value must be a string or `null`. For example, send this body to `PATCH /api/v1/{hash}/element/{elementID}`: ```json { "content/fr/text": "Vous entrez dans la pièce.", "title.de": null } ``` This changes only the French content and German title. `content/fr`, `content.fr`, and `content.fr.text` also address the French content. For connections, use keys such as `label/fr/text`; for component names, use `name/fr/text`. ## Unknown locale errors Context: Arcweave docs > REST API > Localized content > Unknown locale errors Writing a locale that is not defined in the project returns `409 Conflict` with `type: "integrity_conflict"` and `conflictType: "unknown_locale"`. The request is rejected without applying its content changes. For example, if `it` has not been added, a request containing `"title": { "it": "Ingresso" }` returns: ```json { "title": "Integrity error: Unknown locale in API payload", "status": 409, "detail": "The payload contains localized content for a locale that is not defined in this project.", "errors": { "title.it": "Locale it is not defined in this project." }, "errorCode": 0, "type": "integrity_conflict", "conflictType": "unknown_locale" } ``` Check the code against the project's configured languages. Correct the request or add the language in the editor before retrying. Malformed locale maps or unsupported rich-text markup instead return `400 Bad Request`. # Projects Source: https://docs.arcweave.com/rest-api/projects Section: REST API Description: REST API endpoints for listing and managing workspace projects These endpoints list, create, import, rename, and delete projects in the current workspace. ## Endpoints Context: Arcweave docs > REST API > Projects > Endpoints ### List workspace projects Context: Arcweave docs > REST API > Projects > Endpoints > List workspace projects `GET /api/v1/workspace/projects` The key needs **Read projects** (`project:read`), and its owner needs **View projects list** for the key's workspace. Without workspace **View projects list**, this endpoint returns `403 Forbidden`, including when the owner participates in individual projects as an external member. **Request** ```http title="HTTP" GET /api/v1/workspace/projects ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/workspace/projects" ``` **Response** Returns `200 OK`. The response lists every active project in the key's workspace, without pagination. Projects are ordered by their latest data update. Each entry contains the public project hash, name, timestamps, and status: ```json [ { "hash": "ra6XRNxl3G", "name": "The Castle", "updatedAt": "2026-07-12T10:15:30.000000Z", "createdAt": "2026-01-05T13:43:32.000000Z", "status": "active" } ] ``` ### List user workspace projects Context: Arcweave docs > REST API > Projects > Endpoints > List user workspace projects `GET /api/v1/user/projects` **Warning: Deprecated endpoint** `GET /api/v1/user/projects` is an alias of `GET /api/v1/workspace/projects`. It is deprecated and will be removed soon. New integrations should use `GET /api/v1/workspace/projects`, and existing integrations should migrate to it. **Request** ```http title="HTTP" GET /api/v1/user/projects ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/user/projects" ``` **Response** Returns `200 OK`. Projects are ordered by their latest data update. The response has the same shape as the workspace projects endpoint: ```json [ { "hash": "ra6XRNxl3G", "name": "The Castle", "updatedAt": "2026-07-12T10:15:30.000000Z", "createdAt": "2026-01-05T13:43:32.000000Z", "status": "active" } ] ``` ### Create project Context: Arcweave docs > REST API > Projects > Endpoints > Create project `POST /api/v1/workspace/projects` **Request** ```http title="HTTP" POST /api/v1/workspace/projects ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/workspace/projects" ``` ```json { "template": "empty" } ``` Request fields: | Property | Required | Type | Description | | ---------- | -------- | ------ | -------------------------------------------- | | `template` | Yes | String | Template used to initialize the new project. | Supported templates: | Value | Template | | -------------------------- | --------------------------- | | `empty` | Blank Project | | `sample` | Interactive Fiction Example | | `video-sample` | Interactive Movie Example | | `game-engine-sample` | Game Engine Example | | `tabletop-campaign-sample` | Tabletop Campaign Example | | `visual-novel` | Visual Novel Example | | `cyber-security-sample` | Serious Games Example | The token owner must have permission to create projects, and the workspace must have capacity for another project. Unknown root fields are rejected. The new project uses the template's default name, such as `Untitled project` for `empty`. To change it, [rename the project](https://docs.arcweave.com/rest-api/projects#rename-project). **Response** Returns `201 Created` with the new project's numeric ID and public hash: ```json { "message": "Successful project creation", "projectId": 1234, "hash": "ra6XRNxl3G" } ``` ### Import project Context: Arcweave docs > REST API > Projects > Endpoints > Import project `POST /api/v1/workspace/projects/import` **Info: Rate limits** Project imports and exports share a workspace quota of **3 requests per minute per purchased seat**. Import requests also count toward the overall API quota of **60 requests per minute per purchased seat**. See [Rate limits](https://docs.arcweave.com/rest-api/overview#rate-limits) for seat allowances, shared quotas, and retry guidance. **Request** ```http title="HTTP" POST /api/v1/workspace/projects/import ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/workspace/projects/import" ``` ```json { "name": "Generated game", "project": { "startingElement": "65139ea3-331f-4b25-88b4-ea7a65ff106c", "boards": { "e723bdc8-f5f3-4cbc-875d-f559ca40b511": { "name": "Generated Board", "elements": ["65139ea3-331f-4b25-88b4-ea7a65ff106c"], "notes": [], "jumpers": [], "branches": [], "connections": [] } }, "elements": { "65139ea3-331f-4b25-88b4-ea7a65ff106c": { "title": "Opening", "content": "Hello world", "outputs": [] } } } } ``` Request fields: | Property | Required | Type | Description | | --------- | -------- | ------ | --------------------------------------------------------------------------------------------- | | `name` | Yes | String | New project name, up to 255 characters. Used as supplied without an `Imported -` prefix. | | `project` | Yes | Object | Project data to import. Accepts an Arcweave JSON export or collection maps as in the example. | Import creates a new project in the key's workspace. It does not replace or merge into an existing project. The key needs `project:write`, and its owner needs permission to import projects. Workspace project and item limits still apply. Collections can be maps keyed by resource UUIDs or objects containing a `byId` map. Use valid UUID v4 IDs and consistent references; the server validates project integrity and rich-text content. Missing collection roots and default fields are generated. Existing board variables in imported data are migrated to board attributes. A [JSON export](https://docs.arcweave.com/rest-api/exports#json-export) can be supplied directly as `project`. This imports project content and structure; asset files are not restored. The asset collection is reset to an empty root, element/component asset references are removed, and asset-list attribute values are cleared. Upload and attach media separately using the [asset endpoints](https://docs.arcweave.com/rest-api/assets). REST JSON exports also omit board-item positions and element/note dimensions and automatic-height settings. Importing one generates new positions and uses default dimensions, so the original layout is not preserved. To preserve layout, supply JSON exported from the editor with [Include coordinates](https://docs.arcweave.com/project-tools/export#include-coordinates) enabled. **Response** Returns `201 Created` with the new project's identifiers and name: ```json { "hash": "ra6XRNxl3G", "projectId": 1234, "name": "Generated game" } ``` If the payload includes [`exportVersion`](https://docs.arcweave.com/integrations/json#project-level), it must be the number `1`. Omit it for data that isn't an Arcweave JSON export. Invalid payloads, an unsupported `exportVersion`, inconsistent references, invalid rich text, invalid Arcscript, or exceeded project/item limits return `400 Bad Request`. Import integrity errors use the title `Project integrity exception during import.`; each entry in `errors` has a `type`, such as `ItemLimitExceeded`, and a `text` description. Invalid Arcscript uses the title `Bad Request - invalid Arcscript`. ### Rename project Context: Arcweave docs > REST API > Projects > Endpoints > Rename project `PATCH /api/v1/{hash}` **Request** ```http title="HTTP" PATCH /api/v1/{hash} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH" ``` ```json { "name": "The Castle: Remastered" } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | ------ | -------------------------------------------- | | `name` | Yes | String | New project name. Maximum length: 255 chars. | `name` must not be empty. Unknown root fields are rejected. The token owner must have permission to edit the project. **Response** Returns `200 OK`: ```json { "message": "Project name was successfully updated" } ``` ### Delete project Context: Arcweave docs > REST API > Projects > Endpoints > Delete project `DELETE /api/v1/{hash}` **Request** ```http title="HTTP" DELETE /api/v1/{hash} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH" ``` The token owner must have permission to delete the project. **Response** Returns `200 OK`: ```json { "message": "Successful project deletion" } ``` ## Common errors Context: Arcweave docs > REST API > Projects > Common errors | Status | Meaning | | ------ | --------------------------------------------------------------------- | | `400` | Invalid create, import, or rename payload, or import limit exceeded. | | `403` | API access, project permission, or workspace project capacity denied. | | `404` | Project not found. | # Exports Source: https://docs.arcweave.com/rest-api/exports Section: REST API Description: REST API endpoints for JSON and engine exports Export endpoints retrieve project data in Arcweave JSON or an engine-specific format. The Unity, Unreal Engine, and Godot endpoints return JSON with the exported data inside a `project` property. The JSON endpoint returns the project data directly. [Engine downloads from the editor](https://docs.arcweave.com/project-tools/export#export-for-game-engines) are ZIP archives containing `project.json` and, when requested, assets. **Info: Rate limits** Project imports and exports share a workspace quota of **3 requests per minute per purchased seat**. Export requests, including `HEAD` requests, also count toward the overall API quota of **60 requests per minute per purchased seat**. See [Rate limits](https://docs.arcweave.com/rest-api/overview#rate-limits) for seat allowances, shared quotas, and retry guidance. For all export endpoints, send `locale` as a single language-code string and boolean query parameters as `true` or `false`. Only lowercase `allLocales=true` enables all languages; `allLocales=1` does not. An array for `locale` or an unrecognized `allLocales` value returns `400 Bad Request` with the title `Bad Request - project export parameters`; each field in `errors` lists its messages in an array. Engine exports also reject invalid `fallbackContents` values with the same response. The API doesn't check `locale` against the project's languages. An unknown code, or a code with different letter case, returns `null` for the localized fields instead of an error. ## Endpoints Context: Arcweave docs > REST API > Exports > Endpoints ### JSON export Context: Arcweave docs > REST API > Exports > Endpoints > JSON export `GET /api/v1/{hash}/json` **Request** ```http title="HTTP" GET /api/v1/{hash}/json ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/json" ``` **Response** Returns `200 OK`. The response uses the [Arcweave JSON export format](https://docs.arcweave.com/integrations/json). The body is JSON, but the response's `Content-Type` header is `text/html; charset=UTF-8`. Parse the body as JSON regardless of this header. This endpoint always omits board-item positions and the dimensions and automatic-height settings of elements and notes. [Importing this response](https://docs.arcweave.com/rest-api/projects#import-project) generates a new layout. To preserve layout, export JSON from the editor with [Include coordinates](https://docs.arcweave.com/project-tools/export#include-coordinates) enabled; the REST endpoint has no equivalent parameter. **Query parameters** All JSON export query parameters are optional: | Parameter | Value | Behavior | When omitted | | ------------ | ----------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | `boardIds[]` | Board ID | Selects boards and their board items. Repeat the parameter for multiple boards. | The export includes all project boards. | | `locale` | Language ISO code | Exports localized content for the specified language, for example `es`. | The export uses the project's default language. | | `allLocales` | Boolean | When `true`, exports all available languages. This overrides `locale` when both parameters are supplied. | Defaults to `false`; the `locale` behavior applies. | Selecting a board folder includes all boards inside it. Unknown board IDs are ignored. Board selection keeps components, attributes, assets, and global variables from the whole project, including attributes belonging to excluded boards or items. Review these collections before sharing a partial export. Retrieve the full project in its default language: ```http title="HTTP" GET /api/v1/{hash}/json ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/json" ``` Retrieve the full project in Spanish: ```http title="HTTP" GET /api/v1/{hash}/json?locale=es ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/json?locale=es" ``` Retrieve two boards in Spanish: ```http title="HTTP" GET /api/v1/{hash}/json?boardIds[]=board_1&boardIds[]=board_2&locale=es ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/json?boardIds%5B%5D=board_1&boardIds%5B%5D=board_2&locale=es" ``` `boardIds` must be an array of board ID strings. A non-array value or a nested array entry returns `400 Bad Request`. Retrieve the full project in all available languages: ```http title="HTTP" GET /api/v1/{hash}/json?allLocales=true ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/json?allLocales=true" ``` **Warning: Deprecated asset filename header** `AW-No-Filter-Asset-Names` is deprecated and will be removed soon. New integrations should use the dedicated asset endpoints, and existing integrations should migrate to them. The header exposes stored asset filenames in JSON and Godot exports: ```http AW-No-Filter-Asset-Names: true ``` Use the dedicated [asset endpoints](https://docs.arcweave.com/rest-api/assets) instead: 1. Read the asset IDs from the export's `assets` object. 2. Retrieve an asset's metadata and stored filename with [`GET /asset/{assetID}`](https://docs.arcweave.com/rest-api/assets#get-asset). 3. Retrieve its binary file with [`GET /asset/{assetID}/file`](https://docs.arcweave.com/rest-api/assets#download-asset-file). ### Export for Unity Context: Arcweave docs > REST API > Exports > Endpoints > Export for Unity `GET /api/v1/{hash}/unity` **Request** ```http title="HTTP" GET /api/v1/{hash}/unity ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/unity" ``` **Response** Returns `200 OK`. Returns the project format used by the Arcweave Unity integration inside the `project` property. Abbreviated response: ```json { "project": { "name": "The Castle" } } ``` | Query parameter | Type | Description | | ------------------ | ----------------- | ------------------------------------------------------------------------------------------ | | `locale` | Language ISO code | Export content for one language. | | `allLocales` | Boolean | Export all languages and override `locale`. | | `fallbackContents` | Boolean | When `true`, empty values use the **Translates from** language chain. Defaults to `false`. | ### Export for Unreal Engine Context: Arcweave docs > REST API > Exports > Endpoints > Export for Unreal Engine `GET /api/v1/{hash}/unreal` **Request** ```http title="HTTP" GET /api/v1/{hash}/unreal ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/unreal" ``` **Response** Returns `200 OK`. Returns the project format used by the Arcweave Unreal Engine integration inside the `project` property. Abbreviated response: ```json { "project": { "name": "The Castle" } } ``` | Query parameter | Type | Description | | ------------------ | ----------------- | ------------------------------------------------------------------------------------------ | | `locale` | Language ISO code | Export content for one language. | | `allLocales` | Boolean | Export all languages and override `locale`. | | `fallbackContents` | Boolean | When `true`, empty values use the **Translates from** language chain. Defaults to `false`. | ### Export for Godot Context: Arcweave docs > REST API > Exports > Endpoints > Export for Godot `GET /api/v1/{hash}/godot` **Request** ```http title="HTTP" GET /api/v1/{hash}/godot ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/godot" ``` **Response** Returns `200 OK`. Returns the project format used by the Arcweave Godot integration inside the `project` property. Abbreviated response: ```json { "project": { "name": "The Castle" } } ``` | Query parameter | Type | Description | | ------------------ | ----------------- | ------------------------------------------------------------------------------------------ | | `locale` | Language ISO code | Export content for one language. | | `allLocales` | Boolean | Export all languages and override `locale`. | | `fallbackContents` | Boolean | When `true`, empty values use the **Translates from** language chain. Defaults to `false`. | **Warning: Deprecated asset filename header** `AW-No-Filter-Asset-Names` is deprecated and will be removed soon. New integrations should use the dedicated [asset endpoints](https://docs.arcweave.com/rest-api/assets), and existing integrations should migrate to them. ## Common errors Context: Arcweave docs > REST API > Exports > Common errors | Status | Meaning | | ------ | ----------------------------------------------------- | | `400` | Invalid export query. | | `403` | Export feature, project access, or permission denied. | | `404` | Project not found. | | `500` | Export failed unexpectedly. | # Boards Source: https://docs.arcweave.com/rest-api/boards Section: REST API Description: REST API endpoints for listing and managing boards and board folders Board endpoints let you retrieve the project board tree and a board's items, inspect a board, and create or modify boards and board folders. ## Endpoints Context: Arcweave docs > REST API > Boards > Endpoints ### Get boards Context: Arcweave docs > REST API > Boards > Endpoints > Get boards `GET /api/v1/{hash}/board` **Request** ```http title="HTTP" GET /api/v1/{hash}/board ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/board" ``` **Response** Returns `200 OK`. The response includes the root board so clients can reconstruct the complete board and folder hierarchy. The root is an internal folder container with `parentId: null`; it is not a playable board and cannot be moved or deleted. ```json [ { "id": "b0", "name": "Root", "type": "folder", "parentId": null, "children": ["folder_1"], "elementCount": 0, "noteCount": 0, "connectionCount": 0, "branchCount": 0, "jumperCount": 0 }, { "id": "b1", "name": "Main Board", "type": "board", "parentId": "folder_1", "children": [], "elementCount": 5, "noteCount": 3, "connectionCount": 10, "branchCount": 3, "jumperCount": 1 }, { "id": "folder_1", "name": "Chapter One", "type": "folder", "parentId": "b0", "children": ["b1"], "elementCount": 0, "noteCount": 0, "connectionCount": 0, "branchCount": 0, "jumperCount": 0 } ] ``` Entries are sorted by ID, not by their position in the board tree. Use each folder's `children` array for the order of its boards and folders. **Summary fields** | Field | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------- | | `id` | Board or folder ID. | | `name` | Board or folder name. | | `type` | `board` for a regular board or `folder` for the root and board folders. Use this field to determine the resource type. | | `parentId` | ID of the direct parent folder. The root returns `null`. | | `children` | IDs of the folder's direct child boards and folders. Regular boards cannot have children and return an empty array. | | `elementCount` | Number of elements directly contained by a regular board. | | `noteCount` | Number of notes directly contained by a regular board. | | `connectionCount` | Number of connections directly contained by a regular board. | | `branchCount` | Number of branches directly contained by a regular board. | | `jumperCount` | Number of jumpers directly contained by a regular board. | The response uses the same fields for every entry to provide a stable schema. Folder entries—including the root—cannot directly contain project items, so their item counts are `0`. Regular boards cannot contain child boards or folders, so their `children` value is `[]`. ### Get board elements Context: Arcweave docs > REST API > Boards > Endpoints > Get board elements `GET /api/v1/{hash}/board/{boardID}/elements` **Request** ```http title="HTTP" GET /api/v1/{hash}/board/{boardID}/elements ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}/elements" ``` **Response** Returns `200 OK`. ```json [ { "id": "e2", "title": "String title", "x": 10205, "y": 10769, "width": 138, "height": 100, "theme": "red", "hasContent": true, "componentCount": 0, "attributeCount": 2, "outputCount": 4 } ] ``` `title` contains the element title in the project's main language, or the first available translation when the main language has no title. `hasContent` is `true` when the element has content in any language. ### Get board notes Context: Arcweave docs > REST API > Boards > Endpoints > Get board notes `GET /api/v1/{hash}/board/{boardID}/notes` **Request** ```http title="HTTP" GET /api/v1/{hash}/board/{boardID}/notes ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}/notes" ``` **Response** Returns `200 OK` with compact note objects in board order: ```json [ { "id": "n1", "content": "Testing note", "x": 3100, "y": 2200, "width": 50, "height": 100, "theme": "cyan", "autoHeight": true } ] ``` ### Get board jumpers Context: Arcweave docs > REST API > Boards > Endpoints > Get board jumpers `GET /api/v1/{hash}/board/{boardID}/jumpers` **Request** ```http title="HTTP" GET /api/v1/{hash}/board/{boardID}/jumpers ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}/jumpers" ``` **Response** Returns `200 OK` with compact jumper objects in board order: ```json [ { "id": "jump1", "x": 900, "y": 15000, "width": 185, "height": 86, "elementId": "e1" } ] ``` ### Get board branches Context: Arcweave docs > REST API > Boards > Endpoints > Get board branches `GET /api/v1/{hash}/board/{boardID}/branches` **Request** ```http title="HTTP" GET /api/v1/{hash}/board/{boardID}/branches ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}/branches" ``` **Response** Returns `200 OK` with compact branch objects in board order. Condition values are IDs, not expanded condition objects. ```json [ { "id": "br2", "x": 500, "y": 500, "theme": "default", "conditions": { "ifCondition": "cond3", "elseIfConditions": ["cond4", "cond5", "cond6"], "elseCondition": "cond7" } } ] ``` ### Get board connections Context: Arcweave docs > REST API > Boards > Endpoints > Get board connections `GET /api/v1/{hash}/board/{boardID}/connections` **Request** ```http title="HTTP" GET /api/v1/{hash}/board/{boardID}/connections ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}/connections" ``` **Response** Returns `200 OK` with compact connection objects in board order: ```json [ { "id": "con2", "sourceid": "e2", "sourceType": "elements", "targetid": "e1", "targetType": "elements", "sourceFace": "right", "targetFace": "left", "label": "Continue", "labelLocation": 0.5, "labelWidth": 100, "theme": "default", "type": "Bezier" } ] ``` `label` contains the label HTML in the project's main language, or the first available translation when the main language has no label. Use [Get connection](https://docs.arcweave.com/rest-api/connections#get-connection) to retrieve every translation. The five board-item collection endpoints return `404 Not Found` when the board does not exist and `400 Bad Request` when `{boardID}` identifies a folder, because folders cannot contain board items. ### Get board Context: Arcweave docs > REST API > Boards > Endpoints > Get board `GET /api/v1/{hash}/board/{boardID}` **Request** ```http title="HTTP" GET /api/v1/{hash}/board/{boardID} ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}" ``` **Response** Returns `200 OK` with the stored board object: ```json { "id": "b1", "name": "Board 1", "customId": "custom_b1", "elements": ["e1", "e2"], "notes": ["n1"], "jumpers": ["jump1"], "branches": ["br1"], "connections": ["con1", "con2"], "comments": ["comment1"], "attributes": ["board_attribute_9"] } ``` Regular boards include their item and attribute ID collections. Folder boards contain `children` instead of board-item collections. Use the [attribute endpoints](https://docs.arcweave.com/rest-api/attributes#get-board-attributes) to read and modify board attributes. The `comments` collection contains thread IDs. Use [List project comments](https://docs.arcweave.com/rest-api/comments#list-project-comments) to retrieve thread content and replies, and match each thread's `position.id` to the board ID. ### Create board or folder Context: Arcweave docs > REST API > Boards > Endpoints > Create board or folder `POST /api/v1/{hash}/board` **Request** ```http title="HTTP" POST /api/v1/{hash}/board ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/board" ``` Create a regular board: ```json { "name": "API Board", "customId": "apiBoard", "parentId": "folder_1", "index": 0 } ``` Create a folder: ```json { "type": "folder", "name": "API Folder" } ``` | Property | Required | Type | Description | | ---------- | -------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `type` | No | String | `board` or `folder`. Defaults to `board`. | | `name` | No | String | Defaults to `Untitled board` for boards or `New Folder` for folders. | | `customId` | No | String | Arcscript ID for a regular board. A unique ID is generated from the name when omitted. Not accepted for folders. | | `parentId` | No | String or `null` | Parent folder ID. Defaults to the root board container. | | `index` | No | Non-negative integer or `"-"` | Position in the parent folder. Defaults to `"-"`, which appends the item. | The parent, when supplied, must exist and must be a folder. A board `customId` must match `^[A-Za-z$][0-9A-Za-z_]*$`: start with a letter or `$`, followed by letters, numbers, or underscores. It cannot be an Arcscript reserved identifier such as `if`, `true`, or `random`, or duplicate any existing board or component custom ID in the project. **Response** Returns `201 Created` with the generated resource ID and project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Update board Context: Arcweave docs > REST API > Boards > Endpoints > Update board `PATCH /api/v1/{hash}/board/{boardID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/board/{boardID} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}" ``` ```json { "name": "Updated Board Name" } ``` Request fields: | Property | Required | Type | Description | | ---------- | -------- | ------ | ------------------------------------------------------- | | `name` | No | String | Updated board or folder name. | | `customId` | No | String | Set a regular board custom ID only when one is missing. | Supply at least one of `name` or `customId`. The custom ID must satisfy the [creation rules](https://docs.arcweave.com/rest-api/boards#create-board-or-folder). You may set a missing ID or resend the current one, but changing an existing non-empty custom ID is not supported. Folders do not accept `customId`. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Move or reorder board Context: Arcweave docs > REST API > Boards > Endpoints > Move or reorder board `PATCH /api/v1/{hash}/board/{boardID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/board/{boardID}/index ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}/index" ``` ```json { "parentId": "folder_1", "index": 0 } ``` Request fields: | Property | Required | Type | Description | | ---------- | -------- | -------------------- | ------------------------------------------------------------------------ | | `parentId` | No | String or `null` | Target folder. Omit to keep the current parent; use `null` for the root. | | `index` | Yes | Non-negative integer | New position within the target folder. | - `index` is required. An index past the end of the target folder places the item last. - Omit `parentId` to reorder within the current folder. - Use `"parentId": null` to move the item to the root. - The target parent must be a folder. - The root board cannot be moved. - A folder cannot be moved into itself or one of its descendants. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete board Context: Arcweave docs > REST API > Boards > Endpoints > Delete board `DELETE /api/v1/{hash}/board/{boardID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/board/{boardID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}" ``` Deleting a board deletes its contents. Deleting a folder deletes its entire subtree, including the boards and their contents. If the deleted board or folder subtree contains the project's starting element, Arcweave automatically clears the starting element to `null`. You do not need to clear it before deleting the board, and no replacement starting element is selected automatically. Use [Set the starting element](https://docs.arcweave.com/rest-api/elements#set-the-starting-element) to select an element on a remaining board. At least one playable board must remain. Deleting the last playable board, or a folder containing all remaining playable boards, returns `409 Conflict` without applying the deletion. This error has `type: "integrity_conflict"` and `conflictType: "invalid_target"`. A playable board is a regular board (`type: "board"`), even if it is empty; folders and the internal root do not count. Create another board before retrying the deletion if necessary. The internal root cannot be deleted; attempting to delete it returns `400 Bad Request`. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ## Common errors Context: Arcweave docs > REST API > Boards > Common errors | Status | Meaning | | ------ | --------------------------------------------------------------------------------------------------- | | `400` | Invalid payload, folder used as an item board, root mutation, non-folder parent, or recursive move. | | `403` | Project permission denied. | | `404` | Project, board, or requested parent not found. | | `409` | Deletion would leave no playable boards, or the board tree changed before the command was applied. | # Elements Source: https://docs.arcweave.com/rest-api/elements Section: REST API Description: REST API endpoints for elements and their components, attributes, audio, and covers Element endpoints manage element content and ordering, attached components, attributes, audio, covers, outputs, and the project's starting element. ## Element endpoints Context: Arcweave docs > REST API > Elements > Element endpoints ### Create element Context: Arcweave docs > REST API > Elements > Element endpoints > Create element `POST /api/v1/{hash}/element` **Request** ```http title="HTTP" POST /api/v1/{hash}/element ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/element" ``` ```json { "boardId": "b1", "x": 200, "y": 300, "width": 320, "height": 180, "title": "Opening", "content": "The story begins." } ``` | Property | Required | Type | Description | | ------------ | -------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `boardId` | Yes | String | Board that will contain the element. | | `x` | Yes | Number | Horizontal board coordinate. | | `y` | Yes | Number | Vertical board coordinate. | | `width` | No | Number | Element width. Defaults to `301`. | | `height` | No | Number | Element height. Defaults to `121`. | | `theme` | No | String | One of the [color themes](https://docs.arcweave.com/rest-api/overview#color-themes). Defaults to `default`. | | `autoHeight` | No | Boolean | Automatic-height setting. Defaults to `true`. | | `title` | No | String, `null`, or [localized map](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | Element title. Defaults to `null`. | | `content` | No | String, `null`, or [localized map](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | Element content. Defaults to `null`. | | `index` | No | Non-negative integer or `"-"` | Position in the board. Defaults to `"-"`, which appends the element. | The element must fit inside the `40000` by `40000` board canvas. `width` and `height` must each be between `0` and `40000`; `x` must be between `0` and `40000 - width`, and `y` must be between `0` and `40000 - height`. The server generates the element ID. Relationship-managed fields such as components, attributes, outputs, and covers are handled by their dedicated endpoints. New elements start with `components: null` and `outputs: null`, matching elements created in the editor. MCP element creation uses the same defaults. The server sets these fields; do not include them in create or update requests. Provide `title` and `content` as [valid rich text HTML](https://docs.arcweave.com/rest-api/rich-text#supported-html). Element content supports blockquotes and Arcscript code blocks; titles support neither. Inline code is not supported. Arcweave validates Arcscript code blocks in `content`, including whether the variables, attributes, and elements they reference exist. Invalid Arcscript returns `400 Bad Request` with the title `Bad Request - invalid Arcscript`, and the request is not applied. A string or `null` updates only the project's main language. Locale maps update only the supplied, already configured languages; see [Localized content](https://docs.arcweave.com/rest-api/localization) for examples and error handling. If `boardId` does not exist, the request returns `409 Conflict` with `conflictType: "missing_parent"`. A board folder returns `400 Bad Request`. **Response** Returns `201 Created` with the generated resource ID and project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Get element Context: Arcweave docs > REST API > Elements > Element endpoints > Get element `GET /api/v1/{hash}/element/{elementID}` **Request** ```http title="HTTP" GET /api/v1/{hash}/element/{elementID} ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}" ``` **Response** Returns `200 OK` with the stored element: ```json { "id": "e1", "boardId": "b1", "x": 10205, "y": 10469, "width": 138, "height": 100, "theme": "cyan", "title": { "en": { "text": "Test element 1" } }, "content": { "en": { "text": "Test element 1 content custom_b1.board_var_9 = 42" } }, "components": [ { "id": "ref1", "component": "c1" } ], "outputs": ["con1"] } ``` The response contains the stored element object and its `boardId`. Relationship fields can be absent or `null` when empty, including in existing or imported elements. Treat `null`, an empty array, or a missing field as empty: - `components`: component attachments. Each `id` is the attachment ID used by the [component attachment endpoints](https://docs.arcweave.com/rest-api/elements#components). - `attributes`: IDs of the element's [attributes](https://docs.arcweave.com/rest-api/attributes). - `assets.audio`: audio attachments with `id`, `asset`, `mode`, and `delay`, plus `volume`, `fadeIn`, `fadeOut`, and `autoStopOnExit` when set. Each `id` is the attachment ID used by the [audio endpoints](https://docs.arcweave.com/rest-api/elements#audio). - `assets.cover`: the element's [cover](https://docs.arcweave.com/rest-api/elements#covers). - `outputs`: IDs of the element's outgoing connections. ### Update element Context: Arcweave docs > REST API > Elements > Element endpoints > Update element `PATCH /api/v1/{hash}/element/{elementID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}" ``` ```json { "x": 240, "theme": "cyan", "title": { "en": { "text": "Updated element title" } }, "content": { "en": { "text": "Updated element content." } } } ``` Request fields: | Property | Required | Type | Description | | ------------ | -------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `theme` | No | String | One of the [color themes](https://docs.arcweave.com/rest-api/overview#color-themes). Omit to keep the current theme. | | `autoHeight` | No | Boolean | Updated automatic-height setting. If omitted, the current value is retained. | | `x` | No | Number | Updated horizontal coordinate. If omitted, the current value is retained. | | `y` | No | Number | Updated vertical coordinate. If omitted, the current value is retained. | | `width` | No | Number | Updated width. If omitted, the current value is retained. | | `height` | No | Number | Updated height. If omitted, the current value is retained. | | `title` | No | String, `null`, or [localized map](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | Updated title. Path-style localized properties are supported. | | `content` | No | String, `null`, or [localized map](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | Updated content. Path-style localized properties are supported. | Supported update fields are `theme`, `autoHeight`, `x`, `y`, `width`, `height`, `title`, and `content`. Path-style [localized updates](https://docs.arcweave.com/rest-api/localization#update-one-translated-field) such as `title/en/text` are also supported. The `id` and relationship fields are immutable through this endpoint. Geometry updates must keep the complete element inside the `40000` by `40000` board canvas. The server uses the element's current geometry for fields omitted from the request. Provide `title` and `content` as [valid rich text HTML](https://docs.arcweave.com/rest-api/rich-text#supported-html). Element content supports blockquotes and Arcscript code blocks; titles support neither. Inline code is not supported. Arcscript in `content` is validated as described in [Create element](https://docs.arcweave.com/rest-api/elements#create-element). A string or `null` updates only the project's main language. Locale maps update only the supplied, already configured languages; see [Localized content](https://docs.arcweave.com/rest-api/localization) for examples and error handling. If the element does not exist, the request returns `409 Conflict` with `conflictType: "missing_target"`. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Reorder element Context: Arcweave docs > REST API > Elements > Element endpoints > Reorder element `PATCH /api/v1/{hash}/element/{elementID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID}/index ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/index" ``` ```json { "index": 0 } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | -------------------- | -------------------------------------- | | `index` | Yes | Non-negative integer | New position within the current board. | **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete element Context: Arcweave docs > REST API > Elements > Element endpoints > Delete element `DELETE /api/v1/{hash}/element/{elementID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/element/{elementID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}" ``` Deleting an element also deletes its incoming and outgoing connections and all [attributes](https://docs.arcweave.com/rest-api/attributes) owned by that element. [Jumpers](https://docs.arcweave.com/rest-api/jumpers) that target the element remain, with their `elementId` cleared to `null`. Mentions of the element elsewhere in the project are converted to plain text. If it is the project's starting element, Arcweave also clears the starting element to `null`. No replacement is selected automatically. If the element does not exist, the request returns `409 Conflict` with `conflictType: "missing_target"`. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ## Outputs Context: Arcweave docs > REST API > Elements > Outputs ### Reorder output Context: Arcweave docs > REST API > Elements > Outputs > Reorder output `PATCH /api/v1/{hash}/element/{elementID}/output/{connectionID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID}/output/{connectionID}/index ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/output/{connectionID}/index" ``` ```json { "index": 0 } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | -------------------- | -------------------------------------------- | | `index` | Yes | Non-negative integer | New position within the element output list. | `connectionID` identifies one of the outgoing connections in the element's `outputs` list. Outputs can only be reordered within the same element. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ## Starting element Context: Arcweave docs > REST API > Elements > Starting element The [starting element](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#set-play-mode-start) is the element where the project begins when entering Play Mode. ### Get the starting element Context: Arcweave docs > REST API > Elements > Starting element > Get the starting element `GET /api/v1/{hash}/starting-element` Retrieve the project's current starting element without exporting the project or knowing the element ID first. The key needs **Read projects** (`project:read`), and its owner needs **View projects list** permission for the target project in the key's Team workspace. See [Permissions](https://docs.arcweave.com/rest-api/overview#permissions). **Request** ```http title="HTTP" GET /api/v1/{hash}/starting-element ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/starting-element" ``` The unversioned `/api/{hash}/starting-element` route is an alias. Use `/api/v1` for new integrations. This request counts toward the [overall workspace API quota](https://docs.arcweave.com/rest-api/overview#rate-limits), but does not consume the import/export quota or require an export feature. **Response** Returns `200 OK` with the starting element's ID and full stored element. The `element` object has the same shape as [Get element](https://docs.arcweave.com/rest-api/elements#get-element), including `boardId`, localized text, and attachment references: ```json { "elementId": "e1", "element": { "id": "e1", "boardId": "b1", "x": 10205, "y": 10469, "width": 138, "height": 100, "theme": "cyan", "title": { "en": { "text": "Test element 1" } }, "content": { "en": { "text": "Test element 1 content custom_b1.board_var_9 = 42" } }, "components": [ { "id": "ref1", "component": "c1" } ], "outputs": ["con1"] } } ``` When no starting element is configured, the endpoint still returns `200 OK`, with both fields set to `null`: ```json { "elementId": null, "element": null } ``` The response reflects the current selection across all boards, including recent changes made through [Set the starting element](https://docs.arcweave.com/rest-api/elements#set-the-starting-element). Reading it does not change the selection or add a project command-history entry. ### Set the starting element Context: Arcweave docs > REST API > Elements > Starting element > Set the starting element `PATCH /api/v1/{hash}/starting-element` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/starting-element ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/starting-element" ``` ```json { "id": "e2" } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | ---------------- | ---------------------------------------------------- | | `id` | Yes | String or `null` | Element ID, or `null` to clear the starting element. | Set `id` to `null` to clear the starting element. The `id` key must always be present. Use [Get the starting element](https://docs.arcweave.com/rest-api/elements#get-the-starting-element) to read the current selection or verify an update. Arcweave also clears the starting element automatically when that element is deleted, including when its board or a containing folder is deleted. No replacement is selected automatically. [Board deletion](https://docs.arcweave.com/rest-api/boards#delete-board) still requires at least one playable board to remain; clearing the starting element does not remove that requirement. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ## Components Context: Arcweave docs > REST API > Elements > Components ### Attach component Context: Arcweave docs > REST API > Elements > Components > Attach component `POST /api/v1/{hash}/element/{elementID}/component` **Request** ```http title="HTTP" POST /api/v1/{hash}/element/{elementID}/component ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/component" ``` ```json { "componentId": "c1", "index": 0 } ``` Request fields: | Property | Required | Type | Description | | ------------- | -------- | --------------------------- | ------------------------------------------------------------------------- | | `componentId` | Yes | String | Regular component to attach. Folders and root containers are not allowed. | | `index` | No | Non-negative integer or `-` | Position in the attachment list. Defaults to `-`, which appends it. | `componentId` must identify a regular component. Component folders and root containers return `400 Bad Request`; regular components located inside folders can be attached. `index` is optional. **Response** Returns `201 Created` with project version data. The `id` is the new attachment ID, used as `{componentAttachmentID}` in the endpoints below: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Move attached component Context: Arcweave docs > REST API > Elements > Components > Move attached component `PATCH /api/v1/{hash}/element/{elementID}/component/{componentAttachmentID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID}/component/{componentAttachmentID}/index ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/component/{componentAttachmentID}/index" ``` ```json { "targetElementId": "e2", "index": 0 } ``` Request fields: | Property | Required | Type | Description | | ----------------- | -------- | -------------------- | ------------------------------------------------- | | `targetElementId` | No | String | Target element. Omit to keep the current element. | | `index` | Yes | Non-negative integer | New position within the target element. | Omit `targetElementId` to reorder within the current element. `{componentAttachmentID}` is the attachment entry ID, not the component ID. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Remove attached component Context: Arcweave docs > REST API > Elements > Components > Remove attached component `DELETE /api/v1/{hash}/element/{elementID}/component/{componentAttachmentID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/element/{elementID}/component/{componentAttachmentID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/component/{componentAttachmentID}" ``` **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ## Attributes Context: Arcweave docs > REST API > Elements > Attributes Elements can own attributes. See [Attributes](https://docs.arcweave.com/rest-api/attributes) for the shared board, element, and component attribute API. ## Audio Context: Arcweave docs > REST API > Elements > Audio ### Attach audio Context: Arcweave docs > REST API > Elements > Audio > Attach audio `POST /api/v1/{hash}/element/{elementID}/audio` **Request** ```http title="HTTP" POST /api/v1/{hash}/element/{elementID}/audio ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/audio" ``` ```json { "assetId": "audio2", "mode": "loop", "delay": 50, "volume": 0.6, "fadeIn": 500, "fadeOut": 1000, "autoStopOnExit": true, "index": 0 } ``` Request fields: | Property | Required | Type | Description | | ---------------- | -------- | --------------------------- | ----------------------------------------------------------------------------------- | | `assetId` | Yes | String | Audio asset to attach. | | `mode` | No | String | Playback mode: `once`, `loop`, or `stop`. Defaults to `once`. | | `delay` | No | Number | Playback delay in milliseconds. Defaults to `0`. | | `volume` | No | Number | Volume override from `0` to `1`. Omit to use the asset's volume. | | `fadeIn` | No | Number | Fade-in override in milliseconds. Omit to use the asset's value. | | `fadeOut` | No | Number | Fade-out override in milliseconds. Omit to use the asset's value. | | `autoStopOnExit` | No | Boolean | When `true`, stops the clip when Play Mode leaves the element. Defaults to `false`. | | `index` | No | Non-negative integer or `-` | Position in the audio list. Defaults to `-`, which appends it. | `assetId` is required and must identify an audio asset. All other fields are optional. `delay`, `fadeIn`, and `fadeOut` must be zero or more. In Play Mode, `once` plays the clip once, `loop` repeats it, and `stop` stops all playing instances of the clip, fading them out over the `stop` reference's fade-out duration. See [Audio reference settings](https://docs.arcweave.com/project-items/assets/audio#audio-reference-settings). **Response** Returns `201 Created` with project version data. The `id` is the new audio attachment ID, used as `{audioAttachmentID}` in the endpoints below: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Update audio attachment Context: Arcweave docs > REST API > Elements > Audio > Update audio attachment `PATCH /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/audio/{audioAttachmentID}" ``` ```json { "mode": "once", "delay": 0, "fadeOut": null } ``` Request fields: | Property | Required | Type | Description | | ---------------- | -------- | ---------------- | --------------------------------------------------------------------------------------------- | | `assetId` | No | String | Replacement audio asset. If omitted, the current asset is retained. | | `mode` | No | String | Playback mode: `once`, `loop`, or `stop`. Omit to retain. | | `delay` | No | Number | Playback delay in milliseconds. Omit to retain. | | `volume` | No | Number or `null` | Volume override from `0` to `1`. Use `null` to use the asset's volume again; omit to retain. | | `fadeIn` | No | Number or `null` | Fade-in override in milliseconds. Use `null` to use the asset's value again; omit to retain. | | `fadeOut` | No | Number or `null` | Fade-out override in milliseconds. Use `null` to use the asset's value again; omit to retain. | | `autoStopOnExit` | No | Boolean | Whether to stop the clip when Play Mode leaves the element. Omit to retain. | Send at least one of these fields. `{audioAttachmentID}` is the attachment entry ID from the element's `assets.audio` list, not the asset ID. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Move audio attachment Context: Arcweave docs > REST API > Elements > Audio > Move audio attachment `PATCH /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID}/index ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/audio/{audioAttachmentID}/index" ``` ```json { "targetElementId": "e2", "index": 0 } ``` Request fields: | Property | Required | Type | Description | | ----------------- | -------- | -------------------- | ------------------------------------------------- | | `targetElementId` | No | String | Target element. Omit to keep the current element. | | `index` | Yes | Non-negative integer | New position within the target element. | Omit `targetElementId` to reorder within the current element. `{audioAttachmentID}` is the attachment entry ID, not the asset ID. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Remove audio attachment Context: Arcweave docs > REST API > Elements > Audio > Remove audio attachment `DELETE /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/audio/{audioAttachmentID}" ``` **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ## Covers Context: Arcweave docs > REST API > Elements > Covers ### Set element cover Context: Arcweave docs > REST API > Elements > Covers > Set element cover `PATCH /api/v1/{hash}/element/{elementID}/cover` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID}/cover ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/cover" ``` ```json { "cover": { "id": "image_asset_id" } } ``` Request fields: | Property | Required | Type | Description | | -------------------- | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `cover` | Yes | Object | Cover definition. Unknown fields are rejected. | | `cover.type` | No | String | `image`, `template-image`, `icon`, `video`, `template-video`, or `youtube`. | | `cover.id` | Conditional | String | Project asset ID. Required when `type` is omitted or uses an image/video project asset. | | `cover.file` | Conditional | String | [Icon library](https://docs.arcweave.com/project-tools/icon-library) path in `artist/icon-name` form, such as `Arcweave/star`. Required when `type` is `icon`. | | `cover.url` | Conditional | String | YouTube URL. Required when `type` is `youtube`. | | `cover.mode` | No | String | Video playback mode: `once`, `loop`, or `stop`. | | `cover.autoplay` | No | Boolean | Whether video playback starts automatically. | | `cover.showControls` | No | Boolean | Whether video playback controls are visible. | | `cover.showOptions` | No | Boolean | Whether video playback options are visible. | Set a video cover: ```json { "cover": { "id": "video_asset_id", "type": "video", "mode": "loop", "autoplay": true, "showControls": false, "showOptions": true } } ``` The referenced asset must exist and have a supported cover type. Fields are restricted by the selected cover type: | Cover type | Required fields | Optional fields | | ------------------------- | --------------- | --------------------------------------------------------- | | `image`, `template-image` | `id` | `type` | | `video`, `template-video` | `id` | `type`, `mode`, `autoplay`, `showControls`, `showOptions` | | `icon` | `type`, `file` | None | | `youtube` | `type`, `url` | `autoplay`, `showControls` | When `id` is supplied, Arcweave applies the allowed fields of the referenced asset's type and stores that type, replacing any `type` in the request. Image and template-image assets keep their type; video and template-video assets are stored as `video`. If you also send `type`, the fields must be valid for that type as well. Image covers reject video playback fields, and YouTube covers reject `mode` and `showOptions`. Mixed or unsupported fields return `400 Bad Request`. The new cover replaces the element's existing cover, including any playback options you omit. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete element cover Context: Arcweave docs > REST API > Elements > Covers > Delete element cover `DELETE /api/v1/{hash}/element/{elementID}/cover` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/element/{elementID}/cover ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/cover" ``` **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ## Common errors Context: Arcweave docs > REST API > Elements > Common errors | Status | Meaning | | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Invalid fields, malformed localized content, invalid Arcscript, board folder target, unsupported asset type, component folder/root attachment, or missing required payload data. | | `403` | Project permission denied. | | `404` | Project, element, target element, component, asset, component or audio attachment, or output not found. | | `409` | An [unknown locale](https://docs.arcweave.com/rest-api/localization#unknown-locale-errors) was supplied, the board to create in or the element to update or delete does not exist, or the board or target resource changed before the command was applied. | # Connections Source: https://docs.arcweave.com/rest-api/connections Section: REST API Description: REST API endpoints for project connections Connection endpoints create, retrieve, update, and delete connections between board items. ## Connection paths Context: Arcweave docs > REST API > Connections > Connection paths The `type` field sets a connection's style: `Straight`, `Bezier`, or `Flowchart`. Without path geometry, Arcweave routes `Bezier` and `Flowchart` connections automatically. To store a [customized path](https://docs.arcweave.com/project-items/connections#edit-connection-paths), send the geometry field that matches the type: | Field | Type | Description | | --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `waypoints` | Array | `Flowchart` only. Ordered array of at most 1,000 `{ "x": …, "y": … }` points, in absolute board coordinates. | | `controlPoints` | Object | `Bezier` only. Object with exactly `source` and `target`, each `{ "x": …, "y": … }`. Each point is an offset, in board units, from the point where the connection attaches to its source or target. | Each object must contain only numeric `x` and `y`. Every coordinate must be a JSON number between `-40000` and `40000`, inclusive; numeric strings are rejected. ```json { "type": "Flowchart", "waypoints": [ { "x": 480, "y": 180 }, { "x": 480, "y": 420 } ] } ``` Geometry that doesn't match the effective type is dropped: `Straight` stores neither field, `Flowchart` stores only `waypoints`, and `Bezier` stores only `controlPoints`. Changing a connection to a different type clears its previous path and restores automatic routing, unless the same request supplies geometry for the new type. An empty `waypoints` array also uses automatic routing. ## Endpoints Context: Arcweave docs > REST API > Connections > Endpoints ### Create connection Context: Arcweave docs > REST API > Connections > Endpoints > Create connection `POST /api/v1/{hash}/connection` **Request** ```http title="HTTP" POST /api/v1/{hash}/connection ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/connection" ``` ```json { "boardId": "b1", "sourceid": "e2", "sourceType": "elements", "targetid": "e1", "targetType": "elements", "label": "Continue", "labelLocation": 0.25, "labelWidth": 180, "theme": "default", "type": "Bezier" } ``` Request fields: | Property | Required | Type | Description | | --------------- | -------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `boardId` | Yes | String | Board containing the connection. | | `sourceid` | Yes | String | Source item ID. | | `sourceType` | Yes | String | `elements` or `conditions`. | | `targetid` | Yes | String | Target item ID. | | `targetType` | Yes | String | `elements`, `branches`, or `jumpers`. | | `label` | No | String, `null`, or [localized map](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | Connection label. Defaults to no label. | | `labelLocation` | No | Number | Relative label position from `0` to `1`. Defaults to `0.5`. | | `labelWidth` | No | Number | Positive label width. | | `sourceFace` | No | String or `null` | `left`, `right`, `top`, or `bottom`. Omit or use `null` to leave the face unset. | | `targetFace` | No | String or `null` | `left`, `right`, `top`, or `bottom`. Omit or use `null` to leave the face unset. | | `theme` | No | String | One of the [color themes](https://docs.arcweave.com/rest-api/overview#color-themes). Defaults to `default`. | | `type` | No | String | `Straight`, `Bezier`, or `Flowchart` (case-sensitive). Defaults to `Bezier`. | | `waypoints` | No | Array | Customized `Flowchart` path. See [Connection paths](https://docs.arcweave.com/rest-api/connections#connection-paths). | | `controlPoints` | No | Object | Customized `Bezier` path. See [Connection paths](https://docs.arcweave.com/rest-api/connections#connection-paths). | Omit `waypoints` and `controlPoints` to use automatic routing; `null` is not accepted when creating a connection. `boardId` must identify a regular board, not a folder. The source and target must exist on that board; a condition belongs to the board that contains its branch. A condition has a single output connection: if it already has one, delete that connection or update its target instead of creating another connection from the condition. Provide `label` as [valid rich text HTML](https://docs.arcweave.com/rest-api/rich-text#supported-html). Labels support Arcscript code blocks, but not blockquotes or inline code. Code blocks must contain valid Arcscript, and the variables, variable attributes, and elements they reference must exist. Otherwise, the request returns `400 Bad Request` with the title `Bad Request - invalid Arcscript` and an error for each invalid label path. A string or `null` updates only the project's main language. Locale maps update only the supplied, already configured languages; see [Localized content](https://docs.arcweave.com/rest-api/localization) for examples and error handling. **Response** Returns `201 Created` with the generated resource ID and project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Get connection Context: Arcweave docs > REST API > Connections > Endpoints > Get connection `GET /api/v1/{hash}/connection/{connectionID}` **Request** ```http title="HTTP" GET /api/v1/{hash}/connection/{connectionID} ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/connection/{connectionID}" ``` **Response** Returns `200 OK`. ```json { "id": "con2", "boardId": "b1", "sourceid": "e2", "targetid": "e1", "sourceType": "elements", "targetType": "elements", "theme": "default", "type": "Bezier", "label": { "en": { "text": "Test label custom_b1.board_var_9 == 0" } } } ``` `boardId` is derived from the board that contains the connection. A connection with a [customized path](https://docs.arcweave.com/rest-api/connections#connection-paths) also includes `waypoints` or `controlPoints`. ### Update connection Context: Arcweave docs > REST API > Connections > Endpoints > Update connection `PATCH /api/v1/{hash}/connection/{connectionID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/connection/{connectionID} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/connection/{connectionID}" ``` ```json { "label": { "en": { "text": "Updated label" } }, "labelLocation": 0.75, "labelWidth": 180, "theme": "blue", "type": "Straight", "targetid": "e3", "targetType": "elements", "sourceFace": "left", "targetFace": "right" } ``` Request fields: | Property | Required | Type | Description | | --------------- | -------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `label` | No | String, `null`, or [localized map](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | Updated label. If omitted, the current value is retained. | | `labelLocation` | No | Number | Relative label position from `0` to `1`. Omit to keep the current value. | | `labelWidth` | No | Number or `null` | Positive label width. Use `null` to remove the stored width. | | `theme` | No | String | One of the [color themes](https://docs.arcweave.com/rest-api/overview#color-themes). Omit to keep the current theme. | | `type` | No | String | `Straight`, `Bezier`, or `Flowchart` (case-sensitive). Omit to keep the current type. | | `waypoints` | No | Array or `null` | Customized `Flowchart` path. Use `null` to restore automatic routing; omit to retain. | | `controlPoints` | No | Object or `null` | Customized `Bezier` path. Use `null` to restore automatic routing; omit to retain. | | `sourceid` | No | String | New source item ID. Must be sent together with `sourceType`. | | `sourceType` | No | String | New source type: `elements` or `conditions`. | | `targetid` | No | String | New target item ID. Must be sent together with `targetType`. | | `targetType` | No | String | New target type: `elements`, `branches`, or `jumpers`. | | `sourceFace` | No | String or `null` | `left`, `right`, `top`, or `bottom`. Use `null` to clear; omit to retain. | | `targetFace` | No | String or `null` | `left`, `right`, `top`, or `bottom`. Use `null` to clear; omit to retain. | Path geometry follows the rules in [Connection paths](https://docs.arcweave.com/rest-api/connections#connection-paths). If `type` is omitted, the geometry must match the connection's current type; otherwise, it is dropped. When changing an endpoint, send its ID and type as a pair. The new source and target must exist on the connection's board and form a valid connection. A condition cannot become the source when it already owns another output connection. The update must include at least one supported field. The [label formatting rules](https://docs.arcweave.com/rest-api/rich-text#supported-html) and Arcscript validation also apply to updates. A string or `null` updates only the project's main language; locale maps update only the supplied, already configured languages. Path-style fields such as `label/fr/text` are also supported. See [Localized content](https://docs.arcweave.com/rest-api/localization) for examples and error handling. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete connection Context: Arcweave docs > REST API > Connections > Endpoints > Delete connection `DELETE /api/v1/{hash}/connection/{connectionID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/connection/{connectionID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/connection/{connectionID}" ``` **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ## Common errors Context: Arcweave docs > REST API > Connections > Common errors | Status | Meaning | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `400` | Invalid fields, enum, numeric value, label content or Arcscript, incomplete endpoint pair, or a folder `boardId`. | | `403` | Project permission denied. | | `404` | Project or connection not found. | | `409` | An [unknown locale](https://docs.arcweave.com/rest-api/localization#unknown-locale-errors) was supplied; the board, source, target, or connection is missing, or an endpoint is on another board; an update would give a condition a second output; or the project changed during Arcscript validation. | # Notes Source: https://docs.arcweave.com/rest-api/notes Section: REST API Description: REST API endpoints for notes Note endpoints create, retrieve, update, and delete notes placed on project boards. ## Endpoints Context: Arcweave docs > REST API > Notes > Endpoints ### Create note Context: Arcweave docs > REST API > Notes > Endpoints > Create note `POST /api/v1/{hash}/note` **Request** ```http title="HTTP" POST /api/v1/{hash}/note ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/note" ``` ```json { "boardId": "b1", "x": 200, "y": 300, "content": "Remember to revisit this scene." } ``` Request fields: | Property | Required | Type | Description | | ------------ | -------- | ----------------------------- | ---------------------------------------------------------------------------------- | | `boardId` | Yes | String | Board that will contain the note. | | `x` | Yes | Number | Horizontal board coordinate. | | `y` | Yes | Number | Vertical board coordinate. | | `content` | No | String or `null` | Note content. Defaults to `null`. | | `theme` | No | String | One of the [color themes](https://docs.arcweave.com/rest-api/overview#color-themes). Defaults to `default`. | | `autoHeight` | No | Boolean | Automatic-height setting. Defaults to `true`. | | `width` | No | Number | Note width. Defaults to `301`. | | `height` | No | Number | Note height. Defaults to `101`. | | `index` | No | Non-negative integer or `"-"` | Position within the board's note list. Defaults to `"-"`, which appends the note. | `boardId` must identify a regular board, not a folder. The note must fit inside the `40000` by `40000` board canvas. `width` and `height` must each be between `0` and `40000`; `x` must be between `0` and `40000 - width`, and `y` must be between `0` and `40000 - height`. `content` accepts a string or `null`. Note content is not localized, so locale maps are rejected. Provide it as [valid rich text HTML](https://docs.arcweave.com/rest-api/rich-text#supported-html); notes do not support blockquotes or code blocks. The server generates the note ID. **Response** Returns `201 Created` with the generated resource ID and project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Get note Context: Arcweave docs > REST API > Notes > Endpoints > Get note `GET /api/v1/{hash}/note/{noteID}` **Request** ```http title="HTTP" GET /api/v1/{hash}/note/{noteID} ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/note/{noteID}" ``` **Response** Returns `200 OK`. ```json { "id": "n1", "boardId": "b1", "x": 3100, "y": 2200, "width": 50, "height": 100, "theme": "cyan", "content": "Testing note" } ``` ### Update note Context: Arcweave docs > REST API > Notes > Endpoints > Update note `PATCH /api/v1/{hash}/note/{noteID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/note/{noteID} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/note/{noteID}" ``` ```json { "x": 240, "content": "Updated note content" } ``` Request fields: | Property | Required | Type | Description | | ------------ | -------- | ---------------- | ------------------------------------------------------------------------------------------- | | `content` | No | String or `null` | Updated HTML content. If omitted, the current value is retained. | | `theme` | No | String | One of the [color themes](https://docs.arcweave.com/rest-api/overview#color-themes). Omit to keep the current theme. | | `autoHeight` | No | Boolean | Updated automatic-height setting. If omitted, the current value is retained. | | `x` | No | Number | Updated horizontal coordinate. If omitted, the current value is retained. | | `y` | No | Number | Updated vertical coordinate. If omitted, the current value is retained. | | `width` | No | Number | Updated width. If omitted, the current value is retained. | | `height` | No | Number | Updated height. If omitted, the current value is retained. | Supported fields are `content`, `theme`, `autoHeight`, `x`, `y`, `width`, and `height`. Geometry updates must keep the complete note inside the `40000` by `40000` board canvas. The server uses the note's current geometry for fields omitted from the request. The [content rules](https://docs.arcweave.com/rest-api/notes#create-note) for creating notes also apply to updates. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete note Context: Arcweave docs > REST API > Notes > Endpoints > Delete note `DELETE /api/v1/{hash}/note/{noteID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/note/{noteID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/note/{noteID}" ``` **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ## Common errors Context: Arcweave docs > REST API > Notes > Common errors | Status | Meaning | | ------ | ------------------------------------------------------------------------------------------------------- | | `400` | Invalid payload, unsupported field, malformed content, invalid theme, or `boardId` identifies a folder. | | `403` | Project permission denied. | | `404` | Project or note not found when retrieving a note. | | `409` | The board or note does not exist when the command is applied. | # Comments Source: https://docs.arcweave.com/rest-api/comments Section: REST API Description: REST API endpoint for reading project comment threads and replies Retrieve project discussions, including resolved threads and their replies. The REST API currently supports reading comments only. ## Endpoints Context: Arcweave docs > REST API > Comments > Endpoints ### List project comments Context: Arcweave docs > REST API > Comments > Endpoints > List project comments `GET /api/v1/{hash}/comments` The key needs **Read projects** (`project:read`), and its owner needs **View projects list** permission for the target project in the key's Team workspace. See [Permissions](https://docs.arcweave.com/rest-api/overview#permissions). **Request** ```http title="HTTP" GET /api/v1/{hash}/comments ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/comments" ``` The unversioned `/api/{hash}/comments` route is an alias. Use `/api/v1` for new integrations. There are no filtering or pagination parameters. The response includes threads from every board, including resolved threads, regardless of the token owner's personal comment filters. Reading comments does not mark them as read or change personal comment settings. This request counts toward the [overall workspace API quota](https://docs.arcweave.com/rest-api/overview#rate-limits) of 60 requests per minute per purchased seat. **Response** Returns `200 OK` with an array of threads. Threads and their nested replies retain their stored order. An empty project discussion returns `[]`. ```json [ { "id": "thread-1", "author": { "id": 42, "fullName": "Alex Morgan" }, "content": "Can we clarify this character's motivation?", "createdAt": "2026-09-16T09:00:00.000Z", "updatedAt": null, "resolved": false, "position": { "id": "board-1", "type": "boards", "x": 120, "y": 240 }, "replies": [ { "id": "reply-1", "author": { "id": 57, "fullName": null }, "content": "I'll add some context to the opening scene.", "createdAt": "2026-09-16T09:15:00.000Z", "updatedAt": null } ] } ] ``` Fields shared by threads and replies: | Field | Type | Description | | ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | String | Comment ID. | | `author.id` | Number | Author's user ID, retained even when their name is unavailable. | | `author.fullName` | String or null | Current name for a workspace member or a guest of this project. `null` when the author no longer participates or their user record is unavailable. | | `content` | String | Comment content as HTML. | | `createdAt` | String or null | Creation timestamp, when available. | | `updatedAt` | String or null | Last edit timestamp, or `null` when no edit timestamp is stored. | Additional thread fields: | Field | Type | Description | | ---------- | ------- | ------------------------------------------------------------------------------------------------- | | `resolved` | Boolean | Whether the thread is resolved. | | `position` | Object | Board location: `id` is the board ID, `type` is `boards`, and `x` and `y` are canvas coordinates. | | `replies` | Array | Replies in their stored order, or `[]` when there are none. | The response reflects the current project comments, including recent edits. It does not include personal read/unread state or project version metadata. ## Common errors Context: Arcweave docs > REST API > Comments > Common errors | Status | Meaning | | ------ | ----------------------------------------------------------------------------- | | `401` | Missing or invalid API key. | | `403` | API access, token permission, workspace access, or project permission denied. | | `404` | Project not found. | | `429` | Workspace API quota exhausted. | # Jumpers Source: https://docs.arcweave.com/rest-api/jumpers Section: REST API Description: REST API endpoints for jumpers Jumper endpoints create, retrieve, update, and delete jumpers that point to project elements. ## Endpoints Context: Arcweave docs > REST API > Jumpers > Endpoints ### Create jumper Context: Arcweave docs > REST API > Jumpers > Endpoints > Create jumper `POST /api/v1/{hash}/jumper` **Request** ```http title="HTTP" POST /api/v1/{hash}/jumper ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/jumper" ``` ```json { "boardId": "b1", "x": 450, "y": 650.5, "elementId": "e1" } ``` | Property | Required | Type | Description | | ----------- | -------- | ---------------- | ------------------------------------------------------------------------------- | | `boardId` | Yes | String | Board that will contain the jumper. | | `x` | Yes | Number | Horizontal board coordinate. | | `y` | Yes | Number | Vertical board coordinate. | | `width` | No | Number | Jumper width. Defaults to `185`. | | `height` | No | Number | Jumper height. Defaults to `86`. | | `elementId` | No | String or `null` | Target element. Defaults to `null`; a string must identify an existing element. | The jumper must fit inside the `40000` by `40000` board canvas. `width` and `height` must each be between `0` and `40000`; `x` must be between `0` and `40000 - width`, and `y` must be between `0` and `40000 - height`. `boardId` must identify a regular board, not a folder. The target element can be on any board. If the target element is deleted, the jumper remains and its `elementId` becomes `null`. The server generates the jumper ID. **Response** Returns `201 Created` with the generated resource ID and project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Get jumper Context: Arcweave docs > REST API > Jumpers > Endpoints > Get jumper `GET /api/v1/{hash}/jumper/{jumperID}` **Request** ```http title="HTTP" GET /api/v1/{hash}/jumper/{jumperID} ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/jumper/{jumperID}" ``` **Response** Returns `200 OK`. ```json { "id": "jump1", "boardId": "b1", "x": 900, "y": 15000, "elementId": "e1" } ``` ### Update jumper Context: Arcweave docs > REST API > Jumpers > Endpoints > Update jumper `PATCH /api/v1/{hash}/jumper/{jumperID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/jumper/{jumperID} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/jumper/{jumperID}" ``` ```json { "x": 500.25, "elementId": "e4" } ``` | Property | Required | Type | Description | | ----------- | -------- | ---------------- | ------------------------------------------------------- | | `x` | No | Number | Updated horizontal coordinate. | | `y` | No | Number | Updated vertical coordinate. | | `width` | No | Number | Updated width. | | `height` | No | Number | Updated height. | | `elementId` | No | String or `null` | Updated target element. Use `null` to clear the target. | Geometry updates must keep the complete jumper inside the `40000` by `40000` board canvas. The server uses the jumper's current geometry for fields omitted from the request. The request must contain at least one supported field. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete jumper Context: Arcweave docs > REST API > Jumpers > Endpoints > Delete jumper `DELETE /api/v1/{hash}/jumper/{jumperID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/jumper/{jumperID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/jumper/{jumperID}" ``` Deleting a jumper also deletes connections that target it. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ## Common errors Context: Arcweave docs > REST API > Jumpers > Common errors | Status | Meaning | | ------ | -------------------------------------------------------------------------------------------- | | `400` | Invalid payload, unsupported field, invalid numeric value, or `boardId` identifies a folder. | | `403` | Project permission denied. | | `404` | Project or jumper not found when retrieving a jumper. | | `409` | The board, jumper, or target element does not exist when the command is applied. | # Branches and conditions Source: https://docs.arcweave.com/rest-api/branches Section: REST API Description: REST API endpoints for branches and branch conditions Branch endpoints manage branch nodes and their `if`, `else if`, and `else` conditions. ## Condition scripts Context: Arcweave docs > REST API > Branches and conditions > Condition scripts A condition `script` is an Arcscript expression, such as `score > 3`, without the `` wrapper used in element content. To reference an element, for example in `visits()`, use the element mention markup shown in the [Get branch](https://docs.arcweave.com/rest-api/branches#get-branch) response. Empty strings are normalized to `null`. Non-empty scripts must be valid Arcscript, and the variables, variable attributes, and elements they reference must exist. Otherwise, the request returns `400 Bad Request` with the title `Bad Request - invalid Arcscript` and an error for each invalid `conditions.{conditionId}.script` path. These rules apply to every endpoint on this page that accepts a `script`. The `else` condition is followed when no `if` or `else if` condition is true. Play Mode does not evaluate its script, and the editor does not display one, so omit `script` or use `null` for `else` conditions. ## Endpoints Context: Arcweave docs > REST API > Branches and conditions > Endpoints ### Branch Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Branch ### Create branch Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Create branch `POST /api/v1/{hash}/branch` **Request** ```http title="HTTP" POST /api/v1/{hash}/branch ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/branch" ``` ```json { "boardId": "b1", "x": 650, "y": 700, "theme": "blue", "conditions": { "ifCondition": { "script": "score > 3" }, "elseIfConditions": [ { "script": "lives > 0" } ], "elseCondition": { "script": null } } } ``` | Property | Required | Type | Description | | ------------ | -------- | ----------------------------- | ------------------------------------------------------------------------------------- | | `boardId` | Yes | String | Board that will contain the branch. | | `x` | Yes | Number | Horizontal board coordinate. | | `y` | Yes | Number | Vertical board coordinate. | | `theme` | No | String | One of the [color themes](https://docs.arcweave.com/rest-api/overview#color-themes). Defaults to `default`. | | `conditions` | No | Object | Initial condition definitions. Defaults to an `if` condition with a `null` script. | | `index` | No | Non-negative integer or `"-"` | Position within the board's branch list. Defaults to `"-"`, which appends the branch. | `boardId` must identify a regular board, not a folder. Branches use a fixed `288` by `53` footprint and must fit inside the `40000` by `40000` board canvas. `x` must be between `0` and `39712`, and `y` must be between `0` and `39947`. Every branch receives an `if` condition, even when `conditions.ifCondition` is omitted. On create, condition objects may contain only `script`; condition IDs and outputs are server-managed. Scripts follow the [condition script rules](https://docs.arcweave.com/rest-api/branches#condition-scripts). **Response** Returns `201 Created` with the generated resource ID and project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Get branch Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Get branch `GET /api/v1/{hash}/branch/{branchID}` **Request** ```http title="HTTP" GET /api/v1/{hash}/branch/{branchID} ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}" ``` **Response** Returns `200 OK`. The response expands condition IDs into embedded objects: ```json { "id": "br2", "boardId": "b1", "x": 500, "y": 500, "theme": "default", "conditions": { "ifCondition": { "id": "cond3", "output": "condCon3", "script": "variable_1 > 10" }, "elseIfConditions": [ { "id": "cond4", "output": "condCon4", "script": null }, { "id": "cond5", "output": "condCon5", "script": null }, { "id": "cond6", "output": null, "script": "visits(mentioned_element_title)" } ], "elseCondition": { "id": "cond7", "output": null, "script": null } } } ``` Each condition's `output` is the ID of its outgoing connection, or `null` when it has none. `elseIfConditions` and `elseCondition` can be omitted when the branch has no such conditions. ### Update branch and its condition set Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Update branch and its condition set `PATCH /api/v1/{hash}/branch/{branchID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/branch/{branchID} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}" ``` ```json { "x": 725, "theme": "red", "conditions": { "ifCondition": { "script": "score > 5" }, "elseIfConditions": [ { "id": "cond5", "script": "lives > 1" }, { "script": "lives == 1" }, { "id": "cond4" } ], "elseCondition": null } } ``` Request fields: | Property | Required | Type | Description | | ------------ | -------- | ------ | ------------------------------------------------------------------------------------------- | | `theme` | No | String | One of the [color themes](https://docs.arcweave.com/rest-api/overview#color-themes). Omit to keep the current theme. | | `x` | No | Number | Updated horizontal coordinate. If omitted, the current value is retained. | | `y` | No | Number | Updated vertical coordinate. If omitted, the current value is retained. | | `conditions` | No | Object | Desired final condition set. If omitted, conditions remain unchanged. | Supported root fields are `theme`, `x`, `y`, and `conditions`. Coordinate updates must keep the complete fixed-size branch inside the `40000` by `40000` board canvas. The condition payload represents the desired final state. Omitted keys leave those conditions unchanged: - `ifCondition` updates the existing `if` condition. If its ID is included, it must match the branch's `if` condition. - An `elseCondition` object creates or updates the `else` condition. `null` deletes it. If its ID is included, it must match the branch's existing `else` condition. - `elseIfConditions` is the final ordered list. - Existing `else if` conditions are referenced by ID; each ID must belong to this branch and appear only once. - Entries without an ID create new conditions. - Existing `else if` conditions omitted from the array are deleted. - Deleting an `else` or `else if` condition through this update also deletes any outgoing connections from that condition. - `output` is internal and cannot be supplied. Scripts follow the [condition script rules](https://docs.arcweave.com/rest-api/branches#condition-scripts). **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete branch Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Delete branch `DELETE /api/v1/{hash}/branch/{branchID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/branch/{branchID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}" ``` Deleting a branch also deletes its owned conditions, connections targeting the branch, and outgoing connections from its conditions. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### If condition Context: Arcweave docs > REST API > Branches and conditions > Endpoints > If condition ### Update the if condition Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Update the if condition `PATCH /api/v1/{hash}/branch/{branchID}/if-condition` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/branch/{branchID}/if-condition ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}/if-condition" ``` ```json { "script": "score >= 10" } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | ---------------- | ----------------------------------------------------------------- | | `script` | Yes | String or `null` | Updated condition script. Empty strings are normalized to `null`. | The script follows the [condition script rules](https://docs.arcweave.com/rest-api/branches#condition-scripts). **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Else-if conditions Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Else-if conditions ### Create else-if condition Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Create else-if condition `POST /api/v1/{hash}/branch/{branchID}/else-if-condition` **Request** ```http title="HTTP" POST /api/v1/{hash}/branch/{branchID}/else-if-condition ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}/else-if-condition" ``` ```json { "script": "lives > 0" } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | ---------------- | ---------------------------------------------------------------- | | `script` | No | String or `null` | Condition script. Defaults to `null`; the condition is appended. | `script` is optional and may be `null`. The new condition is appended; use the reorder endpoint afterward to move it. **Response** Returns `201 Created` with the generated resource ID and project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Update else-if condition Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Update else-if condition `PATCH /api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}/else-if-condition/{conditionID}" ``` ```json { "script": "lives > 1" } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | ---------------- | ----------------------------------------------------------------- | | `script` | Yes | String or `null` | Updated condition script. Empty strings are normalized to `null`. | **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Reorder else-if condition Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Reorder else-if condition `PATCH /api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID}/index ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}/else-if-condition/{conditionID}/index" ``` ```json { "index": 0 } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | -------------------- | ------------------------------------------------------------------------------------------------- | | `index` | Yes | Non-negative integer | New position among the branch's `else if` conditions, where `0` is the first `else if` condition. | An index past the end of the list moves the condition to the last position. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete else-if condition Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Delete else-if condition `DELETE /api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}/else-if-condition/{conditionID}" ``` Deleting an `else if` condition also deletes any outgoing connections from it. Condition endpoints enforce ownership: a condition can only be changed through the branch that owns it. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Else condition Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Else condition ### Create the else condition Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Create the else condition `POST /api/v1/{hash}/branch/{branchID}/else-condition` **Request** ```http title="HTTP" POST /api/v1/{hash}/branch/{branchID}/else-condition ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}/else-condition" ``` ```json {} ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | ---------------- | ------------------------------------- | | `script` | No | String or `null` | Condition script. Defaults to `null`. | Only one `else` condition can exist. Creating another returns `409 Conflict`. Play Mode does not evaluate an `else` script; see [Condition scripts](https://docs.arcweave.com/rest-api/branches#condition-scripts). **Response** Returns `201 Created` with the generated resource ID and project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Update the else condition Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Update the else condition `PATCH /api/v1/{hash}/branch/{branchID}/else-condition` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/branch/{branchID}/else-condition ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}/else-condition" ``` ```json { "script": null } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | ---------------- | ----------------------------------------------------------------- | | `script` | Yes | String or `null` | Updated condition script. Empty strings are normalized to `null`. | **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete the else condition Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Delete the else condition `DELETE /api/v1/{hash}/branch/{branchID}/else-condition` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/branch/{branchID}/else-condition ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}/else-condition" ``` Deleting the `else` condition also deletes any outgoing connections from it. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ## Common errors Context: Arcweave docs > REST API > Branches and conditions > Common errors | Status | Meaning | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Invalid payload, internal condition field supplied, condition ID that does not belong to the branch, empty update, invalid index, invalid Arcscript, or `boardId` identifies a folder. | | `403` | Project permission denied. | | `404` | Project, branch, or branch-owned condition not found. | | `409` | Missing board/branch, duplicate `else`, stale condition ownership/order snapshot, or the project changed while scripts were validated. | # Variables Source: https://docs.arcweave.com/rest-api/variables Section: REST API Description: REST API endpoints for global variables Variable endpoints manage global variables. Use [board and component variable attributes](https://docs.arcweave.com/rest-api/attributes#variable-attributes) for values scoped to those owners. The REST API has no endpoint that lists variables. To find variable IDs, use the [JSON export](https://docs.arcweave.com/rest-api/exports#json-export), whose `variables` object is keyed by variable ID. ## Endpoints Context: Arcweave docs > REST API > Variables > Endpoints ### Get variable Context: Arcweave docs > REST API > Variables > Endpoints > Get variable `GET /api/v1/{hash}/variable/{variableID}` **Request** ```http title="HTTP" GET /api/v1/{hash}/variable/{variableID} ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/variable/{variableID}" ``` **Response** Returns `200 OK`. Global variable: ```json { "id": "v2", "name": "variable_2", "type": "string", "value": "test value", "cType": "global" } ``` Global variables use `"cType": "global"`. Board-scoped values are stored as attributes and use the [board attribute endpoints](https://docs.arcweave.com/rest-api/attributes#get-board-attributes). The internal root variable container is not exposed and returns `404 Not Found`. ### Create variable Context: Arcweave docs > REST API > Variables > Endpoints > Create variable `POST /api/v1/{hash}/variable` **Request** ```http title="HTTP" POST /api/v1/{hash}/variable ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/variable" ``` ```json { "name": "door_open", "type": "boolean", "value": true, "index": 0 } ``` | Property | Required | Type | Description | | -------- | -------- | ----------------------------- | ------------------------------------------------------------------------------------------------ | | `name` | Yes | String | Starts with a letter, `$`, or `_`; remaining characters may be letters, numbers, or underscores. | | `type` | No | String | `string`, `integer`, `float`, or `boolean`. Defaults to `string`. | | `value` | No | Depends on `type` | Must match the resolved type. Defaults to that type's value listed below. | | `index` | No | Non-negative integer or `"-"` | Position within the global variable list. Defaults to `"-"`, which appends the variable. | **Default values by type** When `value` is omitted, Arcweave uses the default for the resolved variable type: | Type | Default value | | --------- | ------------- | | `string` | `""` | | `integer` | `0` | | `float` | `0.0` | | `boolean` | `false` | **Accepted values by type** | Type | Accepted `value` | | --------- | --------------------------------------------------------------------------------- | | `string` | A JSON string. | | `integer` | An integer, or a string containing an integer such as `"42"`. Stored as a number. | | `float` | A number, or a numeric string such as `"0.5"`. Stored as a number. | | `boolean` | `true` or `false`. Strings such as `"true"` are rejected. | Variable names must be unique among global variables and cannot be Arcscript reserved identifiers such as `if`, `true`, or `random`. The `boardId` field is not accepted; create a [board variable attribute](https://docs.arcweave.com/rest-api/attributes#create-board-attribute) instead. **Response** Returns `201 Created` with the generated resource ID and project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Update variable Context: Arcweave docs > REST API > Variables > Endpoints > Update variable `PATCH /api/v1/{hash}/variable/{variableID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/variable/{variableID} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/variable/{variableID}" ``` ```json { "type": "integer", "value": "42" } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | -------------- | ------------------------------------------------------------------------------------- | | `type` | No | String | `string`, `integer`, `float`, or `boolean`. If omitted, the current type is retained. | | `value` | No | Type-dependent | Updated value. If omitted, the current value is normalized for any new type. | Only `type` and `value` can be updated. Renaming a variable is not supported. The final value must be an [accepted value](https://docs.arcweave.com/rest-api/variables#create-variable) for the final type. If only `type` is supplied, Arcweave reuses and normalizes the current value when it is compatible with the new type; for example, `5` can become a `float`, and `"42"` can become an `integer`. Otherwise, the request returns `400 Bad Request`; send a `value` for the new type in the same request. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Reorder variable Context: Arcweave docs > REST API > Variables > Endpoints > Reorder variable `PATCH /api/v1/{hash}/variable/{variableID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/variable/{variableID}/index ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/variable/{variableID}/index" ``` ```json { "index": 0 } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | -------------------- | --------------------------------------------- | | `index` | Yes | Non-negative integer | New position within the global variable list. | This reorders a global variable. An index past the end of the list moves the variable to the last position. Reorder board and component variable attributes through their respective [attribute endpoints](https://docs.arcweave.com/rest-api/attributes). **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete variable Context: Arcweave docs > REST API > Variables > Endpoints > Delete variable `DELETE /api/v1/{hash}/variable/{variableID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/variable/{variableID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/variable/{variableID}" ``` Deleting a variable does not update Arcscript that references it. Review element content, connection labels, and branch conditions that use the variable. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ## Common errors Context: Arcweave docs > REST API > Variables > Common errors | Status | Meaning | | ------ | ------------------------------------------------------------------------------------------------------- | | `400` | Invalid name, duplicate name, unsupported type, incompatible value, attempted rename, or invalid index. | | `403` | Project permission denied. | | `404` | Project or variable not found, or an internal root ID was requested. | | `409` | Missing variable or invalid container metadata. | # Assets Source: https://docs.arcweave.com/rest-api/assets Section: REST API Description: REST API endpoints for asset folders, asset records, and files Asset endpoints manage the asset tree and upload or download asset files. Upload a media file and create its asset record in one multipart `POST /asset` request. The returned asset ID is ready to use for attachments, metadata requests, and downloads. Folders use a JSON request on the same endpoint. **Warning: Breaking change: asset uploads** The standalone `POST /asset/upload` route has been removed from both `/api/v1` and `/api`; requests to it return `405 Method Not Allowed`. Replace the old upload-then-register flow with [one multipart creation request](https://docs.arcweave.com/rest-api/assets#create-asset-or-folder) containing `name`, `type`, and the binary `file`. JSON media creation with a stored filename, media creation without a file, and creation requests containing `size` return `400 Bad Request`. Creation returns `201 Created` with an asset `id` and project version data. To retrieve the stored filename and size, use [Get asset](https://docs.arcweave.com/rest-api/assets#get-asset) with that ID. Existing file replacement clients also need to follow the [replacement workflow](https://docs.arcweave.com/rest-api/assets#replace-an-asset-file). ## Endpoints Context: Arcweave docs > REST API > Assets > Endpoints ### Get assets Context: Arcweave docs > REST API > Assets > Endpoints > Get assets `GET /api/v1/{hash}/asset` **Request** ```http title="HTTP" GET /api/v1/{hash}/asset ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/asset" ``` **Response** Returns `200 OK` with a compact representation of the complete asset tree: ```json [ { "id": "root_asset", "name": "Root", "type": "folder", "parentId": null, "children": ["image_1", "audio_folder"] }, { "id": "image_1", "name": "Castle.png", "type": "image", "parentId": "root_asset", "children": [] }, { "id": "audio_folder", "name": "Audio", "type": "folder", "parentId": "root_asset", "children": [] } ] ``` Every entry contains `id`, `name`, `type`, `parentId`, and `children`. Folder entries, including the internal root, use `type: "folder"`. File assets use their stored asset type. File asset names include the stored file extension when one is available. ### Get asset Context: Arcweave docs > REST API > Assets > Endpoints > Get asset `GET /api/v1/{hash}/asset/{assetID}` **Request** ```http title="HTTP" GET /api/v1/{hash}/asset/{assetID} ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/asset/{assetID}" ``` **Response** Returns `200 OK`. File-bearing assets include `type` and `file`: ```json { "id": "a01", "name": "asset 1", "type": "image", "file": "asset_1.jpg", "size": "12.06 KB" } ``` Folders include `children` and do not include file-bearing properties. ### Create asset or folder Context: Arcweave docs > REST API > Assets > Endpoints > Create asset or folder `POST /api/v1/{hash}/asset` **Request** For media assets, send `multipart/form-data` containing the metadata and one binary file. The request requires **Write projects** API key permission, permission to edit the project, and a workspace plan that supports asset uploads. ```http title="HTTP" POST /api/v1/{hash}/asset Content-Type: multipart/form-data ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --form-string "name=Castle" \ --form-string "type=image" \ --form "file=@path/to/file.png" \ "https://arcweave.com/api/v1/PROJECT_HASH/asset" ``` Let your HTTP client set the multipart `Content-Type` header and boundary. With curl, `--form` does this automatically. Request fields: | Property | Required | Type | Description | | ---------- | --------- | ----------------------------- | ----------------------------------------------------------------------------- | | `name` | Yes | String | Nonempty asset or folder name. | | `type` | For media | String | `image`, `audio`, or `video`. Omit to create a folder. | | `file` | For media | File | Binary upload. Omit for folders. | | `volume` | No | Number | Initial volume metadata for a media asset, from `0` to `1`. Omit for folders. | | `fadeIn` | No | Number | Default fade-in duration for an audio asset, in milliseconds (zero or more). | | `fadeOut` | No | Number | Default fade-out duration for an audio asset, in milliseconds (zero or more). | | `parentId` | No | String or `null` | Existing target folder in this project. Omit or use `null` for the root. | | `index` | No | Non-negative integer or `"-"` | Position in the target folder. Defaults to `"-"`, which appends the item. | Multipart numeric strings are accepted for `volume`, `fadeIn`, `fadeOut`, and `index`. Audio references attached to elements use the asset's `volume`, `fadeIn`, and `fadeOut` unless they [override them](https://docs.arcweave.com/rest-api/elements#attach-audio). Arcweave generates the asset ID and stored filename and calculates the size from the uploaded file. Do not send `size`, `id`, or other fields outside this table. The target parent must exist and be a folder. Template asset trees are read-only. **Supported formats and limits** The uploaded file must match the selected `type`: | `type` | Accepted formats | | ------- | -------------------------------------- | | `image` | JPEG (`.jpeg`, `.jpg`), PNG, GIF, WebP | | `audio` | MPEG/MP3, Ogg, WAV, WebM | | `video` | MP4, WebM, Ogg | Arcweave checks the file's content to determine its MIME type. Renaming a file's extension does not make an unsupported format valid. - Images have separate width and height limits, each defaulting to **8192 pixels**. These limits are configurable on the server; a validation error reports the applicable limit. - The workspace plan sets the maximum size of one file and the total asset size per project. Standard Team limits are **400 MB per file** and **10 GB per project**; see [asset upload limits](https://docs.arcweave.com/project-items/assets/overview#asset-upload-limits). - The total-size check uses exact stored byte sizes and includes existing assets, in-progress uploads, and the incoming file. Concurrent uploads to the same project share the remaining allowance. Unsupported file content, exceeded image dimensions, a plan without asset uploads, and exceeded plan limits return `400 Bad Request` with details in `errors.file`. Request-size limits on the server can reject an oversized upload before API validation runs. **Create a folder** Send JSON with `name` and, optionally, `parentId` and `index`. Omit `type`, `file`, `volume`, `fadeIn`, and `fadeOut`; do not send `type: "folder"`. ```http title="HTTP" POST /api/v1/{hash}/asset Content-Type: application/json ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/asset" ``` ```json { "name": "Locations" } ``` Folder creation requires REST API access and edit permissions, but does not require the plan's asset-upload feature or consume asset storage. **Response** Returns `201 Created` with the generated resource ID and project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` For media assets, a successful response means the file is stored and the asset is registered. Use the returned `id` with [Get asset](https://docs.arcweave.com/rest-api/assets#get-asset) to read its `file` and `size`, or [Download asset file](https://docs.arcweave.com/rest-api/assets#download-asset-file) to retrieve the original binary. These read requests require **Read projects** API key permission. **Upload failures and retries** An upload reservation that expires before file storage begins returns `410 Gone`. Retry it with a fresh upload request. Failed uploads can continue to occupy reserved storage until cleanup succeeds. A timeout, lost connection, or `500` response can occur after the asset has been created. Check [Get assets](https://docs.arcweave.com/rest-api/assets#get-assets) before retrying: another POST creates another asset. See [Retrying requests](https://docs.arcweave.com/rest-api/overview#retrying-requests) for general retry guidance. ### Update asset Context: Arcweave docs > REST API > Assets > Endpoints > Update asset `PATCH /api/v1/{hash}/asset/{assetID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/asset/{assetID} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/asset/{assetID}" ``` ```json { "name": "Updated Castle" } ``` Request fields: | Property | Required | Type | Description | | --------- | -------- | ------ | ------------------------------------------------------------------------------------- | | `name` | No | String | Updated name. If omitted, the current value is retained. | | `type` | No | String | `image`, `audio`, or `video`. If omitted, the current value is retained. | | `file` | No | String | Existing stored filename in this project for the selected media type. Omit to retain. | | `size` | No | String | Accepted, but replaced with the actual stored file size. Omit this field. | | `volume` | No | Number | Updated volume metadata, from `0` to `1`. | | `fadeIn` | No | Number | Updated default fade-in duration for an audio asset, in milliseconds. | | `fadeOut` | No | Number | Updated default fade-out duration for an audio asset, in milliseconds. | The effective `file` must exist in this project under the selected media type. Omitted `type` and `file` use the asset's current values. Every media update checks this reference, including name-only, volume-only, and fade-only updates, and refreshes `size` from the stored file. A missing filename or a file that does not exist for this project and type returns `400 Bad Request` with `errors.file`. This endpoint accepts JSON metadata. To supply a new binary file while keeping the original asset's ID and references, follow [Replace an asset file](https://docs.arcweave.com/rest-api/assets#replace-an-asset-file). - Folders may be renamed but cannot receive file-asset properties. - Template assets cannot be modified. - The internal `root_asset` container cannot be modified. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Move or reorder asset Context: Arcweave docs > REST API > Assets > Endpoints > Move or reorder asset `PATCH /api/v1/{hash}/asset/{assetID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/asset/{assetID}/index ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/asset/{assetID}/index" ``` ```json { "parentId": "folder_1", "index": 0 } ``` Request fields: | Property | Required | Type | Description | | ---------- | -------- | -------------------- | ------------------------------------------------------------------------ | | `parentId` | No | String or `null` | Target folder. Omit to keep the current parent; use `null` for the root. | | `index` | Yes | Non-negative integer | New position within the target folder. | - `index` is required. - Omit `parentId` to reorder within the current folder. - Use `"parentId": null` to move to the root asset container. - The target must be a folder. - An asset folder cannot be moved into itself or one of its descendants. - The root and template asset trees cannot be moved. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete asset Context: Arcweave docs > REST API > Assets > Endpoints > Delete asset `DELETE /api/v1/{hash}/asset/{assetID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/asset/{assetID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/asset/{assetID}" ``` Deleting a folder deletes its subtree. The root and template asset trees cannot be deleted. Deleting an asset also removes its uses throughout the project: element and component covers, audio attachments, and entries in attribute asset lists. Deleting a folder applies this removal to every asset in its subtree. To replace a file while retaining these references, [update the existing asset](https://docs.arcweave.com/rest-api/assets#update-asset). **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Download asset file Context: Arcweave docs > REST API > Assets > Endpoints > Download asset file `GET /api/v1/{hash}/asset/{assetID}/file` **Request** ```http title="HTTP" GET /api/v1/{hash}/asset/{assetID}/file ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --output OUTPUT_FILE \ "https://arcweave.com/api/v1/PROJECT_HASH/asset/{assetID}/file" ``` **Response** Returns `200 OK` with the stored binary file. The `Content-Type` header is the file's MIME type, such as `image/png`. Both project-uploaded and referenced template asset files can be returned. Requesting a folder returns `400 Bad Request`; a missing stored file returns `404 Not Found`. **Info: Asset delivery URLs** Arcweave can serve media files through `/media/` URLs on its own domain. If you already have a media link, use it as it is; existing public Google storage URLs remain accessible. API clients can continue to download file bytes through this authenticated endpoint. ## Replace an asset file Context: Arcweave docs > REST API > Assets > Replace an asset file To upload a replacement while preserving the original asset's ID and all references to it: 1. [Create a media asset](https://docs.arcweave.com/rest-api/assets#create-asset-or-folder) in the same project with the replacement binary and the original asset's `type`. This creates an additional asset; the upload needs enough remaining project storage for the new file. 2. [Get the new asset](https://docs.arcweave.com/rest-api/assets#get-asset) using the creation response's `id`, and read its `file` value. 3. [Update the original asset](https://docs.arcweave.com/rest-api/assets#update-asset) with a JSON body containing that stored filename, for example `{"file":"STORED_FILENAME_FROM_GET"}`. Use the original asset's ID in the PATCH URL. 4. After the update succeeds, [delete the additional asset record](https://docs.arcweave.com/rest-api/assets#delete-asset) if it is no longer needed. Use the new asset's ID for this DELETE. The original asset keeps its references and can still use the replacement file. Both asset records count toward project storage while they reference the file. Removing the additional record avoids counting the replacement twice. This workflow requires both **Read projects** and **Write projects** API key permissions. ## Common errors Context: Arcweave docs > REST API > Assets > Common errors | Status | Meaning | | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Invalid metadata/upload or PATCH file reference, folder file mutation or download, root/template mutation, non-folder parent, recursive move, or plan limit exceeded. | | `403` | Project permission denied. | | `404` | Project, asset, or parent not found, or the stored file is missing when downloading. | | `405` | POST sent to the removed `/asset/upload` route. | | `409` | Asset or parent changed before the command was applied. | | `410` | Upload reservation expired before file storage began. Retry with a fresh upload request. | # Components Source: https://docs.arcweave.com/rest-api/components Section: REST API Description: REST API endpoints for components, component folders, and covers Component endpoints manage the component tree and component covers. Component attributes use the dedicated [attribute endpoints](https://docs.arcweave.com/rest-api/attributes). ## Endpoints Context: Arcweave docs > REST API > Components > Endpoints ### Get components Context: Arcweave docs > REST API > Components > Endpoints > Get components `GET /api/v1/{hash}/component` **Request** ```http title="HTTP" GET /api/v1/{hash}/component ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/component" ``` **Response** Returns `200 OK` with a compact representation of the complete component tree: ```json [ { "id": "c0", "name": "Root", "type": "folder", "parentId": null, "children": ["component_1", "characters_folder"] }, { "id": "component_1", "name": "Guard", "type": "component", "parentId": "c0", "children": [] }, { "id": "characters_folder", "name": "Characters", "type": "folder", "parentId": "c0", "children": [] } ] ``` Every entry contains `id`, `name`, `type`, `parentId`, and `children`. Folder entries, including the internal root, use `type: "folder"`; regular components use `type: "component"`. Names are returned as strings using the project's default locale and available locale fallbacks, or `null` when no name text is available. Entries are not listed in tree order. A folder's `children` lists its direct child components and folders in display order; regular components return `[]`. Use `parentId` and `children` to rebuild the hierarchy. ### Get component Context: Arcweave docs > REST API > Components > Endpoints > Get component `GET /api/v1/{hash}/component/{componentID}` **Request** ```http title="HTTP" GET /api/v1/{hash}/component/{componentID} ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}" ``` **Response** Returns `200 OK` with the stored component or folder: ```json { "id": "c2", "customId": "component2", "parentId": "c0", "name": { "en": { "text": "Component 2" } }, "attributes": null } ``` The response includes `parentId` unless the requested item is the internal root. Regular components include `name`, `customId`, `attributes` (attribute IDs or `null`), and `assets.cover` when a cover is set. Folders include `children` (child IDs) and `name`. The internal root has `root: true` and no stored name. ### Create component or folder Context: Arcweave docs > REST API > Components > Endpoints > Create component or folder `POST /api/v1/{hash}/component` **Request** ```http title="HTTP" POST /api/v1/{hash}/component ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/component" ``` Create a component: ```json { "name": "Guard", "parentId": "characters_folder", "index": 1 } ``` Create a folder: ```json { "type": "folder", "name": "Characters", "index": 0 } ``` | Property | Required | Type | Description | | ---------- | -------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `type` | No | String | `component` or `folder`. Defaults to `component`. | | `name` | No | String, `null`, or [localized map](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | Defaults to `Untitled component` for components or `New folder` for folders. | | `parentId` | No | String or `null` | Parent component folder. Defaults to the root component container. | | `index` | No | Non-negative integer or `"-"` | Position in the parent folder. Defaults to `"-"`, which appends the item. | The target parent must exist and must be a folder. Regular components cannot contain child components. Passing `name` as a string or `null` targets the project's main language. Locale maps target only the supplied, already configured languages. See [Localized content](https://docs.arcweave.com/rest-api/localization) for the request formats and locale prerequisites. A blank or whitespace-only main-language name is saved as `Untitled component`; blank names in other languages are saved as `null`. For regular components, Arcweave generates a unique `customId` from the main-language name, avoiding existing board and component custom IDs and reserved identifiers. This ID supports [component variable attributes](https://docs.arcweave.com/rest-api/attributes#variable-attributes). Folders do not get a `customId`. The create and rename endpoints do not accept a custom `customId`, and renaming does not change it. **Response** Returns `201 Created` with the generated resource ID and project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Rename component Context: Arcweave docs > REST API > Components > Endpoints > Rename component `PATCH /api/v1/{hash}/component/{componentID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/component/{componentID} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}" ``` ```json { "name/en/text": "Updated Guard" } ``` Request fields: | Property | Required | Type | Description | | -------- | ------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | `name` | Yes, unless a path-style name field is sent | String, `null`, or [localized map](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | Updated name. Path-style localized name properties are also supported. | The endpoint supports `name` and [path-style localized name fields](https://docs.arcweave.com/rest-api/localization#update-one-translated-field), such as `name/fr/text`. Other component properties are managed through dedicated endpoints. Renaming also updates component mention labels. Passing `name` as a string or `null` changes only the main language. A locale map updates only its supplied languages and preserves the others. All locale codes must already exist in the project; see [Localized content](https://docs.arcweave.com/rest-api/localization). Blank `name` values follow the same rules as in [Create component or folder](https://docs.arcweave.com/rest-api/components#create-component-or-folder). **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Move or reorder component Context: Arcweave docs > REST API > Components > Endpoints > Move or reorder component `PATCH /api/v1/{hash}/component/{componentID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/component/{componentID}/index ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}/index" ``` ```json { "parentId": "characters_folder", "index": 0 } ``` Request fields: | Property | Required | Type | Description | | ---------- | -------- | -------------------- | ------------------------------------------------------------------------ | | `parentId` | No | String or `null` | Target folder. Omit to keep the current parent; use `null` for the root. | | `index` | Yes | Non-negative integer | New position within the target folder. | - `index` is required. - Omit `parentId` to reorder within the current folder. - Use `"parentId": null` to move to the root component container. - The target must be a component folder. - A folder cannot be moved into itself or one of its descendants. - The root component container cannot be moved. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete component Context: Arcweave docs > REST API > Components > Endpoints > Delete component `DELETE /api/v1/{hash}/component/{componentID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/component/{componentID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}" ``` Deleting a component automatically deletes all [attributes](https://docs.arcweave.com/rest-api/attributes) owned by that component. Deleting a folder deletes its full subtree and the attributes owned by every component in that subtree. Arcweave also removes the deleted components from element component attachments and `component-list` attribute values, and converts their mentions to plain text. The root component container cannot be deleted. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Set component cover Context: Arcweave docs > REST API > Components > Endpoints > Set component cover `PATCH /api/v1/{hash}/component/{componentID}/cover` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/component/{componentID}/cover ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}/cover" ``` ```json { "cover": { "id": "image_asset_id" } } ``` Request fields: | Property | Required | Type | Description | | ------------ | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `cover` | Yes | Object | Cover definition. Unknown fields are rejected. | | `cover.type` | No | String | `image`, `template-image`, or `icon`. | | `cover.id` | Conditional | String | Project image asset ID. Required when `type` is omitted, `image`, or `template-image`. | | `cover.file` | Conditional | String | [Icon library](https://docs.arcweave.com/project-tools/icon-library) path in `artist/icon-name` form, such as `Arcweave/star`. Required when `type` is `icon`. | Set an icon cover: ```json { "cover": { "type": "icon", "file": "Arcweave/star" } } ``` Folders cannot have covers. Project asset covers must identify image assets. The accepted cover fields depend on its type: `image` and `template-image` accept only `id` and `type`; `icon` accepts only `type` and `file`. When `id` is supplied, Arcweave stores the referenced asset's type (`image` or `template-image`), replacing any `type` in the request. Mixing fields from different cover types returns `400 Bad Request`. The new cover replaces the component's existing cover. **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete component cover Context: Arcweave docs > REST API > Components > Endpoints > Delete component cover `DELETE /api/v1/{hash}/component/{componentID}/cover` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/component/{componentID}/cover ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}/cover" ``` **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ## Common errors Context: Arcweave docs > REST API > Components > Common errors | Status | Meaning | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Invalid component data, malformed localized name, folder cover mutation, non-image cover asset, root mutation, non-folder parent, or recursive move. | | `403` | Project permission denied. | | `404` | Project, component, parent, or cover asset not found. | | `409` | An [unknown locale](https://docs.arcweave.com/rest-api/localization#unknown-locale-errors) was supplied, or the component tree or target changed before the command was applied. | # Attributes Source: https://docs.arcweave.com/rest-api/attributes Section: REST API Description: REST API endpoints for board, element, and component attributes Attributes belong to a board, element, or component. Use the endpoint matching the attribute's owner when listing, creating, updating, reordering, or deleting them. Board and component folders cannot host attributes. Boards and components have attribute list endpoints; elements do not. To read an element's attributes, get the `attributes` ID list from [Get element](https://docs.arcweave.com/rest-api/elements#get-element), then retrieve each attribute with [Get attribute](https://docs.arcweave.com/rest-api/attributes#get-attribute). ## Attribute values Context: Arcweave docs > REST API > Attributes > Attribute values Element attributes support `string`, `rich-text`, `component-list`, and `asset-list` values. Board and component attributes also support `boolean`, `integer`, and `float` values. | Value type | `value.data` | Default when omitted on creation or a type change | | ---------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | `string` | String or `null`. `plain: true` means plain text; `plain: false` means HTML. | `null` | | `rich-text` | [Rich text HTML](https://docs.arcweave.com/rest-api/rich-text#supported-html) or `null`. Stored as `string` with `plain: false`. | `null` | | `component-list` | Array of `{ "id": "reference_id", "component": "component_id" }` objects, or `null`. | `null` | | `asset-list` | Array of `{ "id": "reference_id", "asset": "asset_id" }` objects, or `null`. | `null` | | `boolean` | JSON `true` or `false`. | `false` | | `integer` | JSON integer. | `0` | | `float` | Finite JSON number. | `0.0` | `value.plain` is accepted only when the same request sets `value.type` to `string` or `rich-text`. `rich-text` requires `plain: false`; `type: "string"` defaults to `plain: true`, including on update. To retain the existing text format while updating only data, omit both `value.type` and `value.plain`. Reference lists contain objects, not bare IDs. Each reference must have exactly `id` and its target field, both strings. Reference IDs must be unique within the list; each target must exist in the same project and cannot be a folder. Empty reference lists and empty text are normalized to `null`. ### Variable attributes Context: Arcweave docs > REST API > Attributes > Attribute values > Variable attributes On boards and components, plain `string` values (`plain: true`), booleans, integers, and floats are variable attributes usable in Arcscript. They require a `customId` unique within their owner, and the owner must already have its own `customId`. Attribute custom IDs must match `^[A-Za-z$_][0-9A-Za-z_]*$` and cannot be Arcscript reserved identifiers such as `if`, `true`, or `random`. `customId` is not accepted for rich text, reference lists, or element attributes. Creating a board/component attribute with `type: "string"` defaults to plain text, so it requires `customId`. Use `rich-text` for formatted descriptive content. When updating a variable attribute, its existing `customId` cannot be changed. Converting an existing variable attribute with a custom ID to rich text or a reference list is also unsupported. You can convert a non-variable attribute to a variable type by supplying a valid `customId`. ## Endpoints Context: Arcweave docs > REST API > Attributes > Endpoints ### Get attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Get attribute `GET /api/v1/{hash}/attribute/{attributeID}` **Request** ```http title="HTTP" GET /api/v1/{hash}/attribute/{attributeID} ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/attribute/{attributeID}" ``` **Response** Returns `200 OK` with the stored attribute: ```json { "id": "a1", "name": "Description", "size": "full", "value": { "type": "string", "data": "Attribute content", "plain": false }, "cId": "c1", "cType": "components" } ``` `cId` identifies the owner. `cType` is `boards`, `elements`, or `components`. Variable attributes also include their `customId`. ### Get board attributes Context: Arcweave docs > REST API > Attributes > Endpoints > Get board attributes `GET /api/v1/{hash}/board/{boardID}/attributes` **Request** ```http title="HTTP" GET /api/v1/{hash}/board/{boardID}/attributes ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}/attributes" ``` **Response** Returns `200 OK` with the board's stored attributes in their display order. An owner with no attributes returns `[]`. ```json [ { "id": "a1", "name": "Health", "customId": "health", "size": "full", "value": { "type": "integer", "data": 100 }, "cId": "b1", "cType": "boards" } ] ``` Board folders return `400 Bad Request`. A missing owner returns `404 Not Found`. ### Get board attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Get board attribute `GET /api/v1/{hash}/board/{boardID}/attribute/{attributeID}` **Request** ```http title="HTTP" GET /api/v1/{hash}/board/{boardID}/attribute/{attributeID} ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}/attribute/{attributeID}" ``` **Response** Returns `200 OK` with the stored attribute. The attribute must belong to the board identified in the route. ```json { "id": "a1", "name": "Health", "customId": "health", "size": "full", "value": { "type": "integer", "data": 100 }, "cId": "b1", "cType": "boards" } ``` Board folders return `400 Bad Request`. A missing owner or attribute returns `404 Not Found`. ### Get component attributes Context: Arcweave docs > REST API > Attributes > Endpoints > Get component attributes `GET /api/v1/{hash}/component/{componentID}/attributes` **Request** ```http title="HTTP" GET /api/v1/{hash}/component/{componentID}/attributes ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}/attributes" ``` **Response** Returns `200 OK` with the component's stored attributes in their display order. An owner with no attributes returns `[]`. ```json [ { "id": "a1", "name": "Health", "customId": "health", "size": "full", "value": { "type": "integer", "data": 100 }, "cId": "c1", "cType": "components" } ] ``` Component folders return `400 Bad Request`. A missing owner returns `404 Not Found`. ### Get component attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Get component attribute `GET /api/v1/{hash}/component/{componentID}/attribute/{attributeID}` **Request** ```http title="HTTP" GET /api/v1/{hash}/component/{componentID}/attribute/{attributeID} ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}/attribute/{attributeID}" ``` **Response** Returns `200 OK` with the stored attribute. The attribute must belong to the component identified in the route. ```json { "id": "a1", "name": "Health", "customId": "health", "size": "full", "value": { "type": "integer", "data": 100 }, "cId": "c1", "cType": "components" } ``` Component folders return `400 Bad Request`. A missing owner or attribute returns `404 Not Found`. ### Create element attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Create element attribute `POST /api/v1/{hash}/element/{elementID}/attribute` **Request** ```http title="HTTP" POST /api/v1/{hash}/element/{elementID}/attribute ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/attribute" ``` ```json { "name": "Description", "size": "half", "value": { "type": "rich-text", "data": "Attribute content" }, "index": 0 } ``` Request fields: | Property | Required | Type | Description | | ------------- | -------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `name` | No | String or `null` | Attribute label. Defaults to `null`. | | `size` | No | String | Attribute width: `full` or `half`. Defaults to `full`. | | `value` | Yes | Object | Attribute value object. | | `value.type` | Yes | String | `string`, `rich-text`, `component-list`, or `asset-list`. | | `value.data` | No | String, array, or `null` | Text or reference objects as described in [Attribute values](https://docs.arcweave.com/rest-api/attributes#attribute-values). Defaults to `null`. | | `value.plain` | No | Boolean | Indicates whether a text value contains plain text. Defaults to `true` for `string` and `false` for `rich-text`. | | `index` | No | Non-negative integer or the string `-` | Position within the owner's attribute list. Defaults to `-`, which appends the attribute. | For `rich-text` attributes, provide `value.data` using the [rich-text attribute formatting rules](https://docs.arcweave.com/rest-api/rich-text#supported-html). Blockquotes are supported; code blocks and inline code are not. Plain `string` attributes with `plain: true` should contain unwrapped text. Rich-text input is normalized to Arcweave's internal string representation with `plain: false`, and empty string data is normalized to `null`. **Response** Returns `201 Created` with the new attribute ID and project version: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Create board attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Create board attribute `POST /api/v1/{hash}/board/{boardID}/attribute` **Request** ```http title="HTTP" POST /api/v1/{hash}/board/{boardID}/attribute ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}/attribute" ``` ```json { "name": "Description", "size": "half", "value": { "type": "rich-text", "data": "Attribute content" }, "index": 0 } ``` Request fields: | Property | Required | Type | Description | | ------------- | ----------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `name` | No | String or `null` | Attribute label. Defaults to `null`. | | `customId` | For variable attributes | String | Required for plain text, boolean, integer, and float values. See [Variable attributes](https://docs.arcweave.com/rest-api/attributes#variable-attributes). | | `size` | No | String | Attribute width: `full` or `half`. Defaults to `full`. | | `value` | Yes | Object | Attribute value object. | | `value.type` | Yes | String | `string`, `rich-text`, `component-list`, `asset-list`, `boolean`, `integer`, or `float`. | | `value.data` | No | Type-dependent | Data and defaults depend on the type; see [Attribute values](https://docs.arcweave.com/rest-api/attributes#attribute-values). | | `value.plain` | No | Boolean | Indicates whether a text value contains plain text. Defaults to `true` for `string` and `false` for `rich-text`. | | `index` | No | Non-negative integer or the string `-` | Position within the board's attribute list. Defaults to `-`, which appends the attribute. | For `rich-text` attributes, provide `value.data` using the [rich-text attribute formatting rules](https://docs.arcweave.com/rest-api/rich-text#supported-html). Blockquotes are supported; code blocks and inline code are not. Plain `string` attributes with `plain: true` should contain unwrapped text. Rich-text input is normalized to Arcweave's internal string representation with `plain: false`, and empty string data is normalized to `null`. Board folders cannot host attributes. For example, create a board variable attribute with: ```json { "name": "Health", "customId": "health", "value": { "type": "integer", "data": 100 } } ``` **Response** Returns `201 Created` with the new attribute ID and project version: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Create component attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Create component attribute `POST /api/v1/{hash}/component/{componentID}/attribute` **Request** ```http title="HTTP" POST /api/v1/{hash}/component/{componentID}/attribute ``` ```bash title="curl" curl --request POST \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}/attribute" ``` ```json { "name": "Description", "size": "half", "value": { "type": "rich-text", "data": "Attribute content" }, "index": 0 } ``` Request fields: | Property | Required | Type | Description | | ------------- | ----------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `name` | No | String or `null` | Attribute label. Defaults to `null`. | | `customId` | For variable attributes | String | Required for plain text, boolean, integer, and float values. See [Variable attributes](https://docs.arcweave.com/rest-api/attributes#variable-attributes). | | `size` | No | String | Attribute width: `full` or `half`. Defaults to `full`. | | `value` | Yes | Object | Attribute value object. | | `value.type` | Yes | String | `string`, `rich-text`, `component-list`, `asset-list`, `boolean`, `integer`, or `float`. | | `value.data` | No | Type-dependent | Data and defaults depend on the type; see [Attribute values](https://docs.arcweave.com/rest-api/attributes#attribute-values). | | `value.plain` | No | Boolean | Indicates whether a text value contains plain text. Defaults to `true` for `string` and `false` for `rich-text`. | | `index` | No | Non-negative integer or the string `-` | Position within the component's attribute list. Defaults to `-`, which appends the attribute. | For `rich-text` attributes, provide `value.data` using the [rich-text attribute formatting rules](https://docs.arcweave.com/rest-api/rich-text#supported-html). Blockquotes are supported; code blocks and inline code are not. Plain `string` attributes with `plain: true` should contain unwrapped text. Rich-text input is normalized to Arcweave's internal string representation with `plain: false`, and empty string data is normalized to `null`. Component folders cannot host attributes. For example, create a component variable attribute with: ```json { "name": "Health", "customId": "health", "value": { "type": "integer", "data": 100 } } ``` **Response** Returns `201 Created` with the new attribute ID and project version: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"], "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c" } ``` ### Update element attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Update element attribute `PATCH /api/v1/{hash}/element/{elementID}/attribute/{attributeID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID}/attribute/{attributeID} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/attribute/{attributeID}" ``` ```json { "name": "Updated description", "size": "half", "value": { "type": "string", "data": "Updated value", "plain": true } } ``` Request fields: | Property | Required | Type | Description | | ------------- | -------- | ------------------------ | ------------------------------------------------------------------------------------------------------- | | `name` | No | String or `null` | Updated attribute label. If omitted, the current value is retained. | | `size` | No | String | Updated width: `full` or `half`. If omitted, the current value is retained. | | `value` | No | Object | Updated value properties. If omitted, the current value is retained. | | `value.type` | No | String | `string`, `rich-text`, `component-list`, or `asset-list`. If omitted, the current type is retained. | | `value.data` | No | String, array, or `null` | Updated data compatible with the selected type. If omitted during a type change, it defaults to `null`. | | `value.plain` | No | Boolean | Text only. Omit together with `value.type` to retain the current text format. | At least one of `name`, `size`, or `value` is required. If the value type changes and `value.data` is omitted, stale data from the old type is cleared. When updating a `rich-text` attribute, provide `value.data` using the [rich-text attribute formatting rules](https://docs.arcweave.com/rest-api/rich-text#supported-html). Blockquotes are supported; code blocks and inline code are not. Do not add HTML tags to plain `string` attributes with `plain: true`. An attribute can only be updated through the element that owns it. **Response** Returns `200 OK` with the updated project version: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Update board attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Update board attribute `PATCH /api/v1/{hash}/board/{boardID}/attribute/{attributeID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/board/{boardID}/attribute/{attributeID} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}/attribute/{attributeID}" ``` ```json { "name": "Updated description", "size": "half", "value": { "type": "rich-text", "data": "Updated value" } } ``` Request fields: | Property | Required | Type | Description | | ------------- | ---------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `name` | No | String or `null` | Updated attribute label. If omitted, the current value is retained. | | `customId` | For a conversion to a variable attribute | String | Supply when converting to a variable type. An existing custom ID cannot be changed. | | `size` | No | String | Updated width: `full` or `half`. If omitted, the current value is retained. | | `value` | No | Object | Updated value properties. If omitted, the current value is retained. | | `value.type` | No | String | `string`, `rich-text`, `component-list`, `asset-list`, `boolean`, `integer`, or `float`. If omitted, the current type is retained. | | `value.data` | No | Type-dependent | Updated data compatible with the selected type. If omitted during a type change, the new type default is used. | | `value.plain` | No | Boolean | Text only. Omit together with `value.type` to retain the current text format. | At least one of `name`, `customId`, `size`, or `value` is required. If the value type changes and `value.data` is omitted, stale data from the old type is cleared. When updating a `rich-text` attribute, provide `value.data` using the [rich-text attribute formatting rules](https://docs.arcweave.com/rest-api/rich-text#supported-html). Blockquotes are supported; code blocks and inline code are not. Do not add HTML tags to plain `string` attributes with `plain: true`. An attribute can only be updated through the board that owns it. [Variable attribute restrictions](https://docs.arcweave.com/rest-api/attributes#variable-attributes) apply to type and custom ID changes. **Response** Returns `200 OK` with the updated project version: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Update component attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Update component attribute `PATCH /api/v1/{hash}/component/{componentID}/attribute/{attributeID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/component/{componentID}/attribute/{attributeID} ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}/attribute/{attributeID}" ``` ```json { "name": "Updated description", "size": "half", "value": { "type": "rich-text", "data": "Updated value" } } ``` Request fields: | Property | Required | Type | Description | | ------------- | ---------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `name` | No | String or `null` | Updated attribute label. If omitted, the current value is retained. | | `customId` | For a conversion to a variable attribute | String | Supply when converting to a variable type. An existing custom ID cannot be changed. | | `size` | No | String | Updated width: `full` or `half`. If omitted, the current value is retained. | | `value` | No | Object | Updated value properties. If omitted, the current value is retained. | | `value.type` | No | String | `string`, `rich-text`, `component-list`, `asset-list`, `boolean`, `integer`, or `float`. If omitted, the current type is retained. | | `value.data` | No | Type-dependent | Updated data compatible with the selected type. If omitted during a type change, the new type default is used. | | `value.plain` | No | Boolean | Text only. Omit together with `value.type` to retain the current text format. | At least one of `name`, `customId`, `size`, or `value` is required. If the value type changes and `value.data` is omitted, stale data from the old type is cleared. When updating a `rich-text` attribute, provide `value.data` using the [rich-text attribute formatting rules](https://docs.arcweave.com/rest-api/rich-text#supported-html). Blockquotes are supported; code blocks and inline code are not. Do not add HTML tags to plain `string` attributes with `plain: true`. An attribute can only be updated through the component that owns it. [Variable attribute restrictions](https://docs.arcweave.com/rest-api/attributes#variable-attributes) apply to type and custom ID changes. **Response** Returns `200 OK` with the updated project version: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Reorder element attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Reorder element attribute `PATCH /api/v1/{hash}/element/{elementID}/attribute/{attributeID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID}/attribute/{attributeID}/index ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/attribute/{attributeID}/index" ``` ```json { "index": 0 } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | -------------------- | ------------------------------------------------- | | `index` | Yes | Non-negative integer | New position within the element's attribute list. | Attributes can only be reordered within their current element. **Response** Returns `200 OK` with the updated project version: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Reorder board attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Reorder board attribute `PATCH /api/v1/{hash}/board/{boardID}/attribute/{attributeID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/board/{boardID}/attribute/{attributeID}/index ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}/attribute/{attributeID}/index" ``` ```json { "index": 0 } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | -------------------- | ----------------------------------------------- | | `index` | Yes | Non-negative integer | New position within the board's attribute list. | Attributes can only be reordered within their current board. **Response** Returns `200 OK` with the updated project version: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Reorder component attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Reorder component attribute `PATCH /api/v1/{hash}/component/{componentID}/attribute/{attributeID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/component/{componentID}/attribute/{attributeID}/index ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}/attribute/{attributeID}/index" ``` ```json { "index": 0 } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | -------------------- | --------------------------------------------------- | | `index` | Yes | Non-negative integer | New position within the component's attribute list. | Attributes can only be reordered within their current component. **Response** Returns `200 OK` with the updated project version: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete element attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Delete element attribute `DELETE /api/v1/{hash}/element/{elementID}/attribute/{attributeID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/element/{elementID}/attribute/{attributeID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/attribute/{attributeID}" ``` **Response** Returns `200 OK` with the updated project version: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete board attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Delete board attribute `DELETE /api/v1/{hash}/board/{boardID}/attribute/{attributeID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/board/{boardID}/attribute/{attributeID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}/attribute/{attributeID}" ``` **Response** Returns `200 OK` with the updated project version: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete component attribute Context: Arcweave docs > REST API > Attributes > Endpoints > Delete component attribute `DELETE /api/v1/{hash}/component/{componentID}/attribute/{attributeID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/component/{componentID}/attribute/{attributeID} ``` ```bash title="curl" curl --request DELETE \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}/attribute/{attributeID}" ``` **Response** Returns `200 OK` with the updated project version: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ## Attribute lifecycle Context: Arcweave docs > REST API > Attributes > Attribute lifecycle Attributes cannot exist independently from their owner: - Deleting a [board](https://docs.arcweave.com/rest-api/boards#delete-board), including a folder subtree, deletes its owned attributes. - Deleting an [element](https://docs.arcweave.com/rest-api/elements#delete-element) automatically deletes all attributes owned by that element. - Deleting a [component](https://docs.arcweave.com/rest-api/components#delete-component) automatically deletes all attributes owned by that component. - Deleting a component folder also deletes the attributes owned by every component in the deleted subtree. ## Common errors Context: Arcweave docs > REST API > Attributes > Common errors | Status | Meaning | | ------ | -------------------------------------------------------------------------------------------------------------- | | `400` | Invalid value, reference, custom ID, type conversion, size, index, empty update, or an owner that is a folder. | | `403` | Project permission denied. | | `404` | Project, owner, or attribute not found, or the attribute does not belong to the owner in the route. | # CSS Source: https://docs.arcweave.com/rest-api/css Section: REST API Description: REST API endpoints for project custom CSS CSS endpoints retrieve or replace a project's custom Play Mode stylesheet. Use the [Play Mode styling reference](https://docs.arcweave.com/project-tools/play-mode/styling-reference) for DOM structure, selectors, layout defaults, and working CSS examples. The [Style Editor](https://docs.arcweave.com/project-tools/play-mode/style-editor) and [MCP CSS tools](https://docs.arcweave.com/integrations/mcp#style-play-mode) use the same project stylesheet. ## Endpoints Context: Arcweave docs > REST API > CSS > Endpoints ### Get custom CSS Context: Arcweave docs > REST API > CSS > Endpoints > Get custom CSS `GET /api/v1/{hash}/css` **Request** ```http title="HTTP" GET /api/v1/{hash}/css ``` ```bash title="curl" curl --request GET \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ "https://arcweave.com/api/v1/PROJECT_HASH/css" ``` **Response** Returns `200 OK`. This endpoint returns only the custom CSS saved for the project. It does not include Arcweave's built-in Play Mode stylesheet. If no custom CSS has been set, `css` is an empty string: ```json { "css": "" } ``` ### Update custom CSS Context: Arcweave docs > REST API > CSS > Endpoints > Update custom CSS `PATCH /api/v1/{hash}/css` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/css ``` ```bash title="curl" curl --request PATCH \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data @payload.json \ "https://arcweave.com/api/v1/PROJECT_HASH/css" ``` This endpoint replaces the project's complete custom CSS string. It does not parse the stylesheet or add, modify, or remove individual CSS rules. To change a single rule, first retrieve the current stylesheet with `GET /api/v1/{hash}/css`, modify it in your integration, and send the full updated stylesheet in the `PATCH` request. ```json { "css": ".prototype__text .editor .editor-content { color: #e2e8f0; }" } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | ------ | ----------------------------------------------------------------- | | `css` | Yes | String | Complete replacement stylesheet. Use an empty string to clear it. | `css` must be present and must be a string. An empty string is valid and clears the custom CSS. Unknown root fields are rejected. This validates the payload shape, not CSS syntax or selectors. Surrounding whitespace may be trimmed. The text-color example above is a complete stylesheet for a project with no other custom rules; preserve existing rules when updating an already styled project. **Response** Returns `200 OK` with the complete saved custom stylesheet: ```json { "css": ".prototype__text .editor .editor-content { color: #e2e8f0; }" } ``` ## Read, update, and verify Context: Arcweave docs > REST API > CSS > Read, update, and verify 1. `GET /api/v1/{hash}/css` and keep the original `css` string for rollback. 2. Modify that string, then re-read the saved CSS just before updating. If it changed, reapply your edits to the latest value. `PATCH /api/v1/{hash}/css` with the complete updated value. The update replaces all custom rules. 3. `GET /api/v1/{hash}/css` again to confirm the stored value. 4. **Reload an already-open Play Mode tab**, or click Play in the editor to open a new tab with fresh settings. Restarting the story or returning through same-tab navigation does not fetch fresh settings. These writes do not broadcast live CSS changes. 5. Follow [Save and verify styles](https://docs.arcweave.com/project-tools/play-mode/styling-reference#save-and-verify-styles) to check layout and navigation. Read-back verifies persistence; it does not prove the CSS renders correctly. Saves have no conflict detection: the latest save replaces the stylesheet. Coordinate simultaneous API and manual edits. Retain unsaved local edits before reloading an old Style Editor tab, then reapply them to the fresh CSS before saving there. CSS writes do not create project command-history entries. To restore the previous styling, send the retained original string in another `PATCH`, then reload. Sending `{"css":""}` restores built-in styling by clearing all custom CSS. ## Common errors Context: Arcweave docs > REST API > CSS > Common errors | Status | Meaning | | ------ | ------------------------------------------------------------ | | `400` | Invalid payload shape or field type, not a CSS syntax check. | | `403` | Project access or permission denied. | | `404` | Project not found. | # Workspaces Source: https://docs.arcweave.com/workspaces/overview Section: Workspaces Description: What Arcweave workspaces are and their sections for projects, people, roles, settings, and billing Up to this point, this documentation has covered the structure of a project and the tools used to build and manage it. This section introduces the broader framework through which teams organize their work and collaborate on shared projects: the workspace. ## What workspaces are Context: Arcweave docs > Workspaces > What workspaces are A workspace serves as a collaborative environment where users can create, manage, and share [projects](https://docs.arcweave.com/workspaces/projects) with their team. Users can create multiple workspaces, invite members, and assign them specific [roles](https://docs.arcweave.com/workspaces/roles). These roles determine the level of access and permissions members have within the workspace, including control over its projects and configuration. Each workspace operates independently and maintains its own set of projects, members, settings, billing information, and API keys. > ℹ️ For a thorough exploration of billing, changing plans, and workspace comparison, see [Workspace plans](https://docs.arcweave.com/workspaces/billing-plans) (next page). ## Workspace sections Context: Arcweave docs > Workspaces > Workspace sections Each workspace includes the following sections: - [Projects](https://docs.arcweave.com/workspaces/projects): View and manage all projects within the workspace. - [People](https://docs.arcweave.com/workspaces/people): Manage members, guests, and invitations to join the workspace. - [Roles](https://docs.arcweave.com/workspaces/roles): See available roles and their permissions. - [Settings](https://docs.arcweave.com/workspaces/settings): Configure workspace settings and change billing plan. - [Billing](https://docs.arcweave.com/workspaces/billing): Set up invoicing, review billing history, and monitor detailed usage. - [API](https://docs.arcweave.com/workspaces/api): Access and manage the workspace's [API keys](https://docs.arcweave.com/rest-api/overview) for external integrations. In addition, the [workspace list](https://docs.arcweave.com/workspaces/list) (located at the top left of the workspace window) lets you switch between your workspaces or create new ones. > ℹ️ Each section appears only to users whose [role](https://docs.arcweave.com/workspaces/roles#list-of-permissions) includes the required permission: **View memberships** or **Manage memberships** for People, **Manage roles** for Roles, **Manage workspace** for Settings, **Manage billing** or **Manage workspace** for Billing, and **View API keys** for API. The default **Owner** role includes all of them. # Workspace plans Source: https://docs.arcweave.com/workspaces/billing-plans Section: Workspaces Description: Compare Basic, Pro, and Team plans and upgrade, downgrade, or change seats, with proration and worked billing examples Arcweave [accounts](https://docs.arcweave.com/account/overview) are free. An Arcweave account can be associated with any number and combination of workspaces. ## Workspace comparison Context: Arcweave docs > Workspaces > Workspace plans > Workspace comparison A workspace can be one of the following types: - **Basic**: Free workspace with content and feature limitations. - **Pro**: Removes most limitations and increases the [upload size limit](https://docs.arcweave.com/project-items/assets/overview#asset-upload-limits). - **Team**: Unlocks all features and further increases the upload size limit. ### Feature comparison table Context: Arcweave docs > Workspaces > Workspace plans > Workspace comparison > Feature comparison table The 3 workspace types have important differences in project limits, item capacity, and billing behavior, as shown in the table below. | Feature | Basic | Pro | Team | | ------------------------------------------------ | ------------------- | ---------------- | ------------ | | **Number of members**: | ✅ Unlimited | ✅ Unlimited | ✅ Unlimited | | **Project limits**: | ⚠️ Up to 3 projects | ✅ Unlimited | ✅ Unlimited | | **Item limits** (per project): | ⚠️ Up to 200 items | ✅ Unlimited | ✅ Unlimited | | **Assets upload limit** (per file): | 5 MB | 100 MB | 400 MB | | **Assets upload limit** (per project): | 50 MB | 1 GB | 10 GB | | **[History](https://docs.arcweave.com/project-tools/history) access**: | ❌ Not available | ❌ Not available | ✅ Available | | **[Localization](https://docs.arcweave.com/project-tools/localization)**: | ❌ Not available | ❌ Not available | ✅ Available | | **[REST API](https://docs.arcweave.com/workspaces/api)**: | ❌ Not available | ❌ Not available | ✅ Available | | **[Custom roles](https://docs.arcweave.com/workspaces/roles)**: | ❌ Not available | ❌ Not available | ✅ Available | | **Duplicate projects**: | ❌ Not available | ✅ Available | ✅ Available | | **Hide watermark in embeds**: | ❌ Not available | ✅ Available | ✅ Available | | **AI credits** (per month): | 25 / workspace | 100 / seat | 300 / seat | These differences are designed to help individuals and teams scale their use of Arcweave, from lightweight solo work to complex multi-member collaboration, without sacrificing flexibility or continuity. ### Additional information Context: Arcweave docs > Workspaces > Workspace plans > Workspace comparison > Additional information Along with the table above, consider the following information: - **Unlimited members**: In Basic workspaces, members and guests can be added at no cost. In Pro and Team workspaces, adding or removing members and guests affects billing. - **Project limits**: If a Pro or Team workspace is downgraded to Basic, it keeps all existing [projects](https://docs.arcweave.com/workspaces/projects), but cannot add new ones if the limit is exceeded. - **Item limits**: - The 200-item per project limit in **Basic** workspaces applies only to [elements](https://docs.arcweave.com/project-items/elements), [jumpers](https://docs.arcweave.com/project-items/jumpers), [branches](https://docs.arcweave.com/project-items/branches), [components](https://docs.arcweave.com/project-items/components) (not component folders), and [comment](https://docs.arcweave.com/project-items/comments) threads (not replies). - Your projects can include an unlimited number of [connections](https://docs.arcweave.com/project-items/connections), [notes](https://docs.arcweave.com/project-items/notes), [assets](https://docs.arcweave.com/project-items/assets/overview), and [variables](https://docs.arcweave.com/project-items/variables/overview). - When downgrading to Basic, existing projects keep all their items, but cannot grow beyond 200 counted items. - **Export limits**: - Basic workspaces can export JSON, CSV, game engine JSON, and small or medium JPG/PNG images. - Pro workspaces also unlock XLSX, PDF, Markdown, large image exports, backup export, and project import from backups. - Team workspaces include all Pro exports. - **Embed watermark**: Pro and Team workspaces can disable the Arcweave watermark in embedded Play Mode. Basic workspaces always show it. - **AI tools**: All workspace plans include AI tools, but the monthly AI credit allowance depends on the workspace plan. - **AI credits**: - **Basic** workspaces receive 25 credits per month for the whole workspace. - **Pro** workspaces receive 100 credits per [seat](https://docs.arcweave.com/workspaces/billing-plans#seats) per month. - **Team** workspaces receive 300 credits per [seat](https://docs.arcweave.com/workspaces/billing-plans#seats) per month. - Credits reset every month. You can track usage from the [Billing](https://docs.arcweave.com/workspaces/billing) section. - If you change plan during the current month, Arcweave recalculates the workspace's effective monthly AI limit immediately. Credits already used still count, so the remaining credits become the new limit minus the credits already used. - **Example**: A 3-seat **Pro** workspace has 300 monthly AI credits. If it has already used 40 credits and then upgrades to 3-seat **Team**, its effective monthly limit becomes 900 credits, so 860 credits remain for the rest of that month. > ℹ️ For a complete feature comparison, visit the [Pricing page](https://arcweave.com/pricing) on Arcweave's website. ## Seats Context: Arcweave docs > Workspaces > Workspace plans > Seats In **Basic** workspaces, you can add any number of members or guests for free. In **Pro** and **Team** workspaces, workspace members and guest editors are billable. Each billable user occupies a **seat**. Seats are slots that billable users occupy and they determine your subscription cost. Adding a billable user occupies an available paid seat or adds a new one; removing a user frees a seat. > ✅ A freed seat remains active until its billing period ends. > ℹ️ For details on adding and removing seats and how this affects your billing, see [Change number of seats](https://docs.arcweave.com/workspaces/billing-plans#change-number-of-seats), below. ## Billing calculation Context: Arcweave docs > Workspaces > Workspace plans > Billing calculation Each Pro or Team workspace is billed **independently**, based on: - Selected plan (Pro / Team) - Billing cycle (monthly / yearly) - Number of billable seats (members + guest editors) This page includes detailed instructions and billing [examples](https://docs.arcweave.com/workspaces/billing-plans#examples) on plan upgrades, downgrades, [prorated charges](https://docs.arcweave.com/workspaces/billing-plans#proration), and seat management, to help you understand how your subscription costs are calculated. ## Upgrade workspace plan Context: Arcweave docs > Workspaces > Workspace plans > Upgrade workspace plan > ℹ️ Selecting a plan in the upgrade modal requires the **Manage billing** permission, which the default **Owner** role includes. See [Workspace roles](https://docs.arcweave.com/workspaces/roles#list-of-permissions). ### Upgrade Basic Context: Arcweave docs > Workspaces > Workspace plans > Upgrade workspace plan > Upgrade Basic A Basic workspace suits early exploration and limited projects. As the size and complexity of your work increases, upgrading to Pro or Team removes content limitations and unlocks additional workflow features. To upgrade your Basic workspace to Pro or Team, follow the steps below: #### 1. Review existing seats Context: Arcweave docs > Workspaces > Workspace plans > Upgrade workspace plan > Upgrade Basic > 1. Review existing seats Before upgrading, review your current [members](https://docs.arcweave.com/workspaces/roles#workspace-members) and [guest editors](https://docs.arcweave.com/workspaces/roles#workspace-guests). - Remove users who should not remain on the workspace. - Decide whether additional collaborators must be invited before upgrading. ⚠️ **You will be billed for all billable roles** (members + guest editors) immediately after upgrading, regardless of how active those users are. > ℹ️ If you choose a **yearly** plan, seats included at checkout are billed yearly. After the upgrade, removing a billable user leaves their paid seat open until its renewal date, so another billable user can occupy it without adding a seat. When inviting a member who needs an additional paid seat, eligible users can [choose monthly or yearly billing](https://docs.arcweave.com/workspaces/people#choose-billing-for-an-additional-seat). See [Yearly-billed workspaces](https://docs.arcweave.com/workspaces/billing-plans#yearly-billed-workspaces) for details. To make seat changes before upgrading, close the **Upgrade** modal and follow the [instructions to invite](https://docs.arcweave.com/workspaces/billing-plans#add-seats) or [remove](https://docs.arcweave.com/workspaces/billing-plans#remove-seats) users: #### 2. Open the upgrade modal Context: Arcweave docs > Workspaces > Workspace plans > Upgrade workspace plan > Upgrade Basic > 2. Open the upgrade modal You can upgrade a Basic workspace from two locations: **a. From the upgrade prompt**: Located at the bottom left corner of your workspace environment. (Exit any open project first.) ![The Projects section of a Basic workspace in Arcweave, with an orange arrow pointing at the workspace's upgrade prompt at the bottom left corner of the window.](https://docs.arcweave.com/assets/free-upgrade.Bv-Gz32q.png) Click **Upgrade** to open the upgrade modal. ![The "Upgrade workspace" modal with the options to switch to Pro or Team.](https://docs.arcweave.com/assets/upgrade-modal.DBHZLAWn.png) **b. From the Settings section**: Go to your workspace **Settings > Change plan** and press [Change](https://docs.arcweave.com/workspaces/settings#change-workspace-plan), to open the upgrade modal. ![Workspace settings section showing the Change plan button.](https://docs.arcweave.com/assets/settings-change-plan.DBFTWQPm.png) #### 3. Choose Pro or Team Context: Arcweave docs > Workspaces > Workspace plans > Upgrade workspace plan > Upgrade Basic > 3. Choose Pro or Team Select **Upgrade to Pro** or **Upgrade to Team** based on feature needs and team size. > ✅ Need help selecting a plan? [Contact us](https://arcweave.com/contact). #### 4. Choose billing cycle Context: Arcweave docs > Workspaces > Workspace plans > Upgrade workspace plan > Upgrade Basic > 4. Choose billing cycle Choose **Monthly** or **Yearly** as the workspace's billing cycle. - Existing billable seats follow the workspace billing cycle. - Seats added later are [prorated](https://docs.arcweave.com/workspaces/billing-plans#proration) until the next renewal of their monthly or yearly billing cycle. #### 5. Enter payment details Context: Arcweave docs > Workspaces > Workspace plans > Upgrade workspace plan > Upgrade Basic > 5. Enter payment details Provide payment information, a **Company Name or Full Name**, and your country for invoicing. Address and VAT ID are optional. #### 6. Confirm upgrade Context: Arcweave docs > Workspaces > Workspace plans > Upgrade workspace plan > Upgrade Basic > 6. Confirm upgrade Press **Upgrade workspace** to complete the upgrade. #### After upgrading Context: Arcweave docs > Workspaces > Workspace plans > Upgrade workspace plan > Upgrade Basic > After upgrading The new plan takes effect immediately. Your card is charged and your workspace upgrades to **Pro** or **Team**. ### Upgrade Pro to Team Context: Arcweave docs > Workspaces > Workspace plans > Upgrade workspace plan > Upgrade Pro to Team To upgrade a Pro workspace to Team: 1. Open the [upgrade modal](https://docs.arcweave.com/workspaces/billing-plans#_2-open-the-upgrade-modal). 2. Select **Upgrade to Team**. 3. Choose **Pay Monthly** or **Pay Yearly** under **Billing cycle**. The **Order summary** displays the [prorated cost](https://docs.arcweave.com/workspaces/billing-plans#proration) for the remainder of the billing cycle. 4. Click **Change plan**. Your card is charged instantly and access to Team-only features begins immediately. ## Change number of seats Context: Arcweave docs > Workspaces > Workspace plans > Change number of seats [Seats](https://docs.arcweave.com/workspaces/billing-plans#seats) determine how many users hold billable roles at the same time. ### Add seats Context: Arcweave docs > Workspaces > Workspace plans > Change number of seats > Add seats A new seat is added to a workspace when you do one of the following: - **Add a workspace member** in the workspace's **People** section. See: [People](https://docs.arcweave.com/workspaces/people) > [Add members](https://docs.arcweave.com/workspaces/people#add-members) - **Add a project editor** to a project. See: [Roles](https://docs.arcweave.com/workspaces/roles) > [Invite guests](https://docs.arcweave.com/workspaces/roles#invite-guests) > ✅ [Project commenters](https://docs.arcweave.com/workspaces/roles#project-commenter) can be added for free and do not occupy seats. #### Monthly-billed workspaces Context: Arcweave docs > Workspaces > Workspace plans > Change number of seats > Add seats > Monthly-billed workspaces When adding new seats in monthly-billed workspaces, consider the following: - New seats are [prorated](https://docs.arcweave.com/workspaces/billing-plans#proration) for the remainder of the current billing cycle. - From the next billing date onward, the seat appears in the regular monthly invoice, aligned with the workspace's billing cycle. > ✅ See an [example of adding a seat to a monthly-billed workspace](https://docs.arcweave.com/workspaces/billing-plans#add-seats-monthly-plan) under **Examples**, below. #### Yearly-billed workspaces Context: Arcweave docs > Workspaces > Workspace plans > Change number of seats > Add seats > Yearly-billed workspaces When adding new seats in yearly-billed workspaces, consider the following: - If a paid seat is open because its previous user was removed before its renewal date, the new billable user occupies it without adding a seat. - When inviting a workspace member and no unused paid seats remain, users with **Manage memberships** and either **Manage billing** or **Manage workspace** permission can [choose **Pay Yearly** or **Pay Monthly**](https://docs.arcweave.com/workspaces/people#choose-billing-for-an-additional-seat). **Pay Yearly** is selected initially. - The invitation dialog shows pricing, applicable discounts, renewal details, and the estimated charge for the selected cycle. The choice is saved with the invitation and applied when it is accepted, if an additional seat is still needed. - **Pay Yearly** adds the seat to the yearly subscription at the yearly seat rate. Its first charge is [prorated](https://docs.arcweave.com/workspaces/billing-plans#proration) until the next yearly renewal, then it is included in the regular yearly invoice. - **Pay Monthly** adds the seat at the monthly seat rate. Its first charge is [prorated](https://docs.arcweave.com/workspaces/billing-plans#proration) until the next monthly renewal, then it is included in the regular monthly invoice. Existing yearly seats keep their yearly billing cycle. - Invitations without a billing-cycle selection, including guest-editor invitations, add a monthly seat when a new seat is required. - Users with **Manage billing** permission can later [convert one or more monthly seats to yearly billing](https://docs.arcweave.com/workspaces/billing#switch-monthly-seats-to-yearly). > ✅ See an [example of adding a seat to a yearly-billed workspace](https://docs.arcweave.com/workspaces/billing-plans#add-seats-yearly-plan) under **Examples**, below. ### Remove seats Context: Arcweave docs > Workspaces > Workspace plans > Change number of seats > Remove seats Seats are **billable slots** that workspace members or billable guests occupy. - To remove a seat, you must remove the user occupying it (a workspace member or a project editor). - Removing a user frees their seat, but **the seat itself remains active until its billing period ends**. - During this time, you may invite another user to occupy the same seat. - If left unfilled, a seat expires at the next renewal date. To remove users: - **Remove workspace members**: See [People](https://docs.arcweave.com/workspaces/people) > [Remove members](https://docs.arcweave.com/workspaces/people#remove-members) - **Remove project editors**: See [Roles](https://docs.arcweave.com/workspaces/roles) > [Remove guests](https://docs.arcweave.com/workspaces/roles#remove-guests) > ✅ See examples of [removing a seat from a monthly](https://docs.arcweave.com/workspaces/billing-plans#remove-seats-monthly-plan) and [a yearly plan](https://docs.arcweave.com/workspaces/billing-plans#remove-seats-yearly-plan) under **Examples**, below. ## Downgrade workspace plan Context: Arcweave docs > Workspaces > Workspace plans > Downgrade workspace plan ### Downgrade Team to Pro Context: Arcweave docs > Workspaces > Workspace plans > Downgrade workspace plan > Downgrade Team to Pro To downgrade a Team workspace to Pro: 1. Go to **Settings > Change plan** and press **Change**. 2. Select **Go to Pro**. 3. Select a monthly or yearly billing cycle. Review the **Order summary**, including [prorated charges and credits](https://docs.arcweave.com/workspaces/billing-plans#proration) and any amount due today. 4. Click **Change plan**. The new plan takes effect immediately, and any amount due is charged when you confirm. If your billing cycle and seats stay unchanged, unused Team time is credited against the remaining Pro time. Changing billing cycles can produce an immediate charge: for example, switching from **Team Monthly** to **Pro Yearly** starts a yearly subscription, with the unused Team time credited against its cost. > ℹ️ Any credit remaining after the change is saved in your workspace's billing balance and applied to future invoices. > ✅ See examples of [downgrading Team to Pro](https://docs.arcweave.com/workspaces/billing-plans#downgrade-team-to-pro-1) under **Examples**, below. ### Downgrade to Basic Context: Arcweave docs > Workspaces > Workspace plans > Downgrade workspace plan > Downgrade to Basic To cancel a workspace's Pro or Team subscription, you need to **downgrade it to Basic**. To downgrade a Pro or Team workspace to Basic: 1. Go to **Settings > Change plan** and click **Change**. 2. On the **Basic** plan, click **Downgrade**. 3. In the **Cancel Plan** dialog, review what changes when the plan ends, then click **Cancel plan**. 4. Select at least one reason for leaving and click **Downgrade**. Your paid plan remains active and you continue enjoying its benefits until the end of the current billing period. Until then, **Settings > Change plan** shows the date your plan ends and a **Resume subscription** button that keeps your current plan instead. > ⚠️ If you have a yearly plan, the subscription remains active until the end of the yearly cycle. _During this time, you continue getting billed on any associated monthly seat subscriptions._ ## Proration Context: Arcweave docs > Workspaces > Workspace plans > Proration Proration is the way Arcweave adjusts charges when: - You **add seats** to a Pro or Team plan. - You **upgrade or downgrade** between Pro and Team plans. For such cases, Arcweave calculates a partial cost or credit based on the exact number of days left in the current billing period. This ensures you pay only for the portion of the service you actually use. For example, if you add a new seat halfway through a monthly cycle, you're billed for just half of that seat's price for the current month. Similarly, upgrading or downgrading between Pro and Team credits the unused time on your current plan against the cost of the new plan. If you also change billing cycles, the new billing period can make an amount payable immediately, even when downgrading to Pro. Review the **Order summary** before confirming. In yearly workspaces, an additional seat's first charge is prorated until the next renewal of its selected monthly or yearly cycle. The charge occurs when the invitation is accepted, so the amount may differ from the estimate shown when sending the invitation. See [Yearly-billed workspaces](https://docs.arcweave.com/workspaces/billing-plans#yearly-billed-workspaces). ## Examples Context: Arcweave docs > Workspaces > Workspace plans > Examples ### Upgrade Basic to Pro Context: Arcweave docs > Workspaces > Workspace plans > Examples > Upgrade Basic to Pro Let's say you have a **Basic** workspace with the following seats: - **1 member** - **1 guest editor** - **several guest commenters** (who are non-billable) > ℹ️ Members and guest editors count as one seat each. #### Pro Monthly Context: Arcweave docs > Workspaces > Workspace plans > Examples > Upgrade Basic to Pro > Pro Monthly A Pro workspace seat costs $18.00 / month when charged monthly. This is how billing will be calculated for a Pro Monthly plan: | Workspace Seats | Amount | | ------------------ | ---------: | | 2 @ $18.00 / month | $36.00 | | Months: | x 1 | | **Invoice Total**: | **$36.00** | Therefore, on the day of the upgrade, and on the same day of every month after that, you will be charged and invoiced for **$36.00**. #### Pro Yearly Context: Arcweave docs > Workspaces > Workspace plans > Examples > Upgrade Basic to Pro > Pro Yearly A Pro workspace seat costs $15.00 / month when charged yearly. This is how billing will be calculated for a Pro Yearly plan: | Workspace Seats | Amount | | ------------------ | ----------: | | 2 @ $15.00 / month | $30.00 | | Months: | x 12 | | **Invoice Total**: | **$360.00** | On the day of purchase, you will be charged and invoiced for **$360.00**. ### Upgrade Basic to Team Context: Arcweave docs > Workspaces > Workspace plans > Examples > Upgrade Basic to Team Let's now say you have a **Basic** workspace with the same number of seats as in the previous example: - **1 member** - **1 guest editor** - **several guest commenters** (who are non-billable) #### Team Monthly Context: Arcweave docs > Workspaces > Workspace plans > Examples > Upgrade Basic to Team > Team Monthly A Team workspace seat costs $30.00 / month when charged monthly. This is how billing will be calculated for a Team Monthly plan: | Workspace Seats | Amount | | ------------------ | ---------: | | 2 @ $30.00 / month | $60.00 | | Months: | x 1 | | **Invoice Total**: | **$60.00** | On the day of purchase, and on the same day of every month after that, you will be charged and invoiced for **$60.00**. #### Team Yearly Context: Arcweave docs > Workspaces > Workspace plans > Examples > Upgrade Basic to Team > Team Yearly A Team workspace seat costs $25.00 / month when charged yearly. This is how billing will be calculated for a Team Yearly plan: | Workspace Seats | Amount | | ------------------ | ----------: | | 2 @ $25.00 | $50.00 | | Months: | x 12 | | **Invoice Total**: | **$600.00** | On the day of purchase, you will be charged and invoiced for **$600.00**. ### Upgrade Pro to Team Context: Arcweave docs > Workspaces > Workspace plans > Examples > Upgrade Pro to Team Similarly to the previous examples, let's say you have a Pro workspace with 2 billable seats. When upgrading it to Team, Arcweave will [prorate](https://docs.arcweave.com/workspaces/billing-plans#proration) the cost of your invoice as described below. #### Upgrade Pro Monthly to Team Monthly Context: Arcweave docs > Workspaces > Workspace plans > Examples > Upgrade Pro to Team > Upgrade Pro Monthly to Team Monthly Five days after your subscription's start, you decide that you need REST API access to read and write project data, plus custom workspace roles, so you switch to **Team**. First, you need to calculate the cost of both Pro Monthly and Team Monthly, for your workspace's number of seats. As seen in the previous examples, for 2 seats, you pay **$36.00** for Pro Monthly, while the Team Monthly costs **$60.00**. You have already consumed _5 days of your Pro subscription._ Immediately after the upgrade and until the end of your monthly subscription, you will enjoy _25 days of Team subscription._ Therefore, on the day of your plan switch, you will be charged the cost of 25 days of Team Monthly (which will immediately be available to use) minus the 25 days of Pro Monthly (which you will not be using): | Workspace Seats | Amount | | ------------------------------------ | ---------: | | 25 days x Team Monthly ($60.00) / 30 | $50.00 | | - 25 x Pro Monthly ($36.00) / 30 | - $30.00 | | **Invoice Total**: | **$20.00** | After the current month, on the day of your subscription's renewal, your Team Monthly subscription will renew normally, with a charge of $60.00. #### Upgrade Pro Yearly to Team Yearly Context: Arcweave docs > Workspaces > Workspace plans > Examples > Upgrade Pro to Team > Upgrade Pro Yearly to Team Yearly Five months after your subscription's start, you decide that you need REST API access to read and write project data, plus custom workspace roles, so you switch to **Team**. First, you need to calculate the cost of both Pro Yearly and Team Yearly, for your workspace's number of seats. As seen in the previous examples, for 2 seats, you pay **$360.00** for Pro Yearly, while the Team Yearly costs **$600.00**. You have already consumed _5 months of your Pro subscription._ Immediately after the upgrade and until the end of your Yearly subscription, you will enjoy _7 months of Team subscription._ Therefore, on the day of your plan switch, you will be charged the cost of 7 months of Team Yearly (which will immediately be available to use) minus the 7 months of Pro Yearly (which you will not be using): | Workspace Seats | Amount | | -------------------------------------- | ----------: | | 7 months x Team Yearly ($600.00) / 12 | $350.00 | | - 7 months x Pro Yearly ($360.00) / 12 | - $210.00 | | **Invoice Total**: | **$140.00** | After the 7 months, on the day of your subscription's renewal, your Team Yearly subscription will renew normally, with a charge of $600.00. ### Add seats (Monthly plan) Context: Arcweave docs > Workspaces > Workspace plans > Examples > Add seats (Monthly plan) Let's now say you have a **Pro Monthly** workspace with **2 seats** and some days after your subscription's last invoice date, you decide to add 1 more workspace editor, so you invite them to your workspace. > ℹ️ Members and guest editors count as one seat each, while guest commenters are non-billable. When the new user accepts the invite (let's say this happens 11 days after the workspace's regular billing date), a new invoice gets issued, with the new seat prorated as follows: - **Proration period: 19 days** Out of the 30 days of the monthly subscription, 11 days have passed as usual and 19 days will pass including the new seat. - **Proration amount per seat: $11.40** We get the daily cost of the $18-per-month-seat and multiply it by 19 days: 19 \* 18 / 30 = 11.40 When your Pro Monthly subscription gets renewed on its regular day, the extra seat will be incorporated into your regular invoice. You will then be paying: | Workspace Seats | Amount | | ------------------ | --------------: | | 3 @ $18.00 / month | **$54** / month | ### Add seats (Yearly plan) Context: Arcweave docs > Workspaces > Workspace plans > Examples > Add seats (Yearly plan) Let's say you have a **Pro Yearly** workspace with **2 occupied seats** renewing on January 5th. On July 14, you decide to add 1 more workspace editor, so you invite them to your workspace. > ℹ️ Members and guest editors count as one seat each, while guest commenters are non-billable. Because both paid seats are occupied, a user with the required permissions can choose the new member's billing cycle in the invitation dialog: | Choice | First charge when the invitation is accepted | Regular renewals at standard Pro rates | | --------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | | **Pay Yearly** | The new seat is prorated for the remaining time until January 5th. | Three yearly seats at $180 each: **$540 per year**. | | **Pay Monthly** | The new seat is prorated until the next monthly renewal date. | The original two seats remain **$360 per year**, plus **$18 per month** for the new seat. | Review the **Order summary** before sending the invitation for applicable discounts, the renewal date, and the estimated initial charge. Sending the invitation does not charge the workspace; the amount is calculated when the user accepts and a new seat is added. If you choose monthly billing, you can later use **Billing > Monthly Seats > Switch to yearly** with **Manage billing** permission. The conversion dialog shows the prorated amount due today and the resulting monthly and yearly renewal totals before you confirm. ### Remove seats (Monthly plan) Context: Arcweave docs > Workspaces > Workspace plans > Examples > Remove seats (Monthly plan) A workspace renews on the 5th of every month. The owner removes an editor on the 18th. The empty seat remains available until the 5th of the next month. Inviting another member or guest editor before that date, will fill the existing seat. > ⚠️ Available seats that do not get occupied by new members get removed at the end of their billing cycle (the 5th of the next month, in this example). ### Remove seats (Yearly plan) Context: Arcweave docs > Workspaces > Workspace plans > Examples > Remove seats (Yearly plan) When seats are removed from a Yearly plan: - **If the seat is billed monthly**: The seat gets removed first, before the yearly seats. These are typically seats added after the subscription's initial date that have not been converted to yearly billing. When empty, they remain available until the end of their monthly cycle. - **If the seat is billed yearly**: The seat remains available until the end of the workspace's Yearly billing cycle. ### Downgrade Team to Pro Context: Arcweave docs > Workspaces > Workspace plans > Examples > Downgrade Team to Pro Suppose you have **2 seats** on **Team Monthly** at **$60 per month** and change plans halfway through a 30-day billing cycle. The unused Team time is worth **$30**. At standard prices, before taxes or discounts: - **Team Monthly to Pro Monthly**: The remaining half-month of Pro costs **$18**. After applying the $30 credit, **$12 remains as credit** toward future invoices. - **Team Monthly to Pro Yearly**: A year of Pro for two seats costs **$360**. After applying the $30 credit, **$330 is due immediately**. Your actual charge or credit depends on the change date, billing cycle, seats, discounts, taxes, and existing billing balance. Review the **Order summary** before clicking **Change plan**. # Workspace list Source: https://docs.arcweave.com/workspaces/list Section: Workspaces Description: Open the workspace list to create and switch workspaces; rename or delete them in workspace Settings Your **workspace list** lets you switch between your workspaces and create new ones, helping you manage different projects and teams with ease. ## Open workspace list Context: Arcweave docs > Workspaces > Workspace list > Open workspace list To open the workspace list: 1. Go to your workspace environment; exit any open project if necessary. 2. Click the current workspace's name in the top-left corner of the window. ![Animated GIF demonstrating how to open the workspace list clicking at the top left corner of the Arcweave window.](https://docs.arcweave.com/assets/workspace-list.k6CigeFl.gif) The list includes: - Workspaces where you are a member. - Workspaces where you are a [guest](https://docs.arcweave.com/workspaces/roles#workspace-guests) in at least one project, marked with a **Guest** badge. - Pending invitations, with **Reject** and **Accept invite** buttons. ## Create new workspaces Context: Arcweave docs > Workspaces > Workspace list > Create new workspaces To create a new workspace: 1. Open the workspace list. 2. Click **+ Create new workspace** at the bottom. 3. Enter a name for your new workspace. 4. Click **Create**. A new, empty workspace will be added to your account, and Arcweave opens its **Projects** section. ## Switch workspace Context: Arcweave docs > Workspaces > Workspace list > Switch workspace To switch to a different workspace: 1. Open the workspace list. 2. Click the name of the workspace you want to switch to. ## Rename or delete workspaces Context: Arcweave docs > Workspaces > Workspace list > Rename or delete workspaces You cannot rename or delete workspaces directly from the workspace list. To make changes, go to the workspace's [Settings](https://docs.arcweave.com/workspaces/settings) section. # Workspace projects Source: https://docs.arcweave.com/workspaces/projects Section: Workspaces Description: Create, import, duplicate, rename, and delete workspace projects, use project templates, and manage project covers An Arcweave **project** is a self-contained unit that holds the structure, content, and assets of an interactive story. It allows you to design, test, share, and export your work. Projects include [project items](https://docs.arcweave.com/project-items/overview) such as boards, elements, and components, and support both collaboration and external integration. The **Projects** section displays the workspace's projects. ![The Projects section of a workspace with multiple project thumbnails.](https://docs.arcweave.com/assets/projects.BM3m9Naf.png) > ℹ️ Guests only see the projects they have been invited to. ## Project thumbnails Context: Arcweave docs > Workspaces > Workspace projects > Project thumbnails All the workspace projects are shown as **thumbnails** in a grid. You can access project-specific options through the [menu](https://docs.arcweave.com/workspaces/projects#project-menu) on each thumbnail. ## Search Context: Arcweave docs > Workspaces > Workspace projects > Search Use the **search** field to quickly filter projects by title. ## Create projects Context: Arcweave docs > Workspaces > Workspace projects > Create projects To create a new project: 1. Go to the **Projects** section of your workspace. 2. Click the **+ New Project** button. 3. Select **Blank Project** among the available project templates. ![Arcweave workspace screenshot, with the "New Project" button highlighted.](https://docs.arcweave.com/assets/workspaces-new-project.DPv-Ss89.png) A new project will be created and automatically opened. > ℹ️ Basic workspaces can have up to 3 projects. > ✅ You can also [import a project](https://docs.arcweave.com/workspaces/projects#import-projects) into your workspace. Use the search field or the **All templates**, **Examples**, and **Game Engines** tabs to filter the available templates. ## Project templates Context: Arcweave docs > Workspaces > Workspace projects > Project templates Arcweave includes built-in project templates that you can recreate to expand and learn from. To create a project from one of the templates: 1. Go to the workspace's **Projects** section. 2. Click the **+ New Project** button. 3. Select a template from the menu. ![The Projects section of an Arcweave workspace, with the "Create project" modal open, showing the available project templates.](https://docs.arcweave.com/assets/project-templates.cASA2VSk.png) Current built-in templates include: - **Blank Project**: an empty project for starting from scratch. - **Interactive Fiction Example**: a simple example of Arcweave's basic flowchart and story features. - **Interactive Movie Example**: an example of an interactive short film using video assets. - **Game Engine Example**: the project used in the game engine integration tutorials. - **Tabletop Campaign Example**: a simple campaign structure with dice rolling. - **Visual Novel Example**: a tutorial-style visual novel with characters, backgrounds, and audio. - **Serious Games Example**: simulated email-based security training with custom Play Mode CSS. > ✅ Try the _Game Engine Example_ to see how Arcweave [integrates with popular game engines](https://docs.arcweave.com/integrations/overview). Watch the video tutorials on the [Unreal](https://docs.arcweave.com/tutorials/unreal/overview) and [Godot](https://docs.arcweave.com/tutorials/godot/overview) plugins to get a glimpse of such integrations. ## Import projects Context: Arcweave docs > Workspaces > Workspace projects > Import projects The [Import projects permission](https://docs.arcweave.com/workspaces/roles#list-of-permissions) allows users to import projects into a workspace. - Arcweave JSON files can be imported into any workspace, as long as the import stays within the workspace's project and item limits. - Native Arcweave backup files (`.arcw`) can also be imported into [Pro and Team](https://docs.arcweave.com/workspaces/billing-plans) workspaces. - In Team workspaces, projects can also be imported using Arcweave's [REST API](https://docs.arcweave.com/rest-api/overview). ### Arcweave JSON Context: Arcweave docs > Workspaces > Workspace projects > Import projects > Arcweave JSON You can also import a project from an **Arcweave JSON** file (`.json`) that was either previously [exported from Arcweave](https://docs.arcweave.com/project-tools/export#export-as-json) or otherwise generated, as long as it follows the [Arcweave JSON format](https://docs.arcweave.com/integrations/json). > ⚠️ JSON import does not restore assets, element and component covers, element audio, or Asset List attribute values, and every item ID must be a UUIDv4. See [Arcweave JSON](https://docs.arcweave.com/integrations/json) for details. > ✅ If the JSON includes board item coordinates (e.g. it were [exported](https://docs.arcweave.com/project-tools/export#include-coordinates) with **Include coordinates** enabled), board items will be restored to their original positions and sizes upon import. ### Arcweave file Context: Arcweave docs > Workspaces > Workspace projects > Import projects > Arcweave file An **Arcweave file** (`.arcw`) is the native backup format used by Arcweave. It contains the complete project data, including notes, comments, and assets, as well as positions of all board items. To generate an Arcweave file, [export a project as a backup](https://docs.arcweave.com/project-tools/export#export-project-backup). > ⚠️ Importing `.arcw` backup files is available in [Pro and Team](https://docs.arcweave.com/workspaces/billing-plans) workspaces. ### REST API Context: Arcweave docs > Workspaces > Workspace projects > Import projects > REST API In Team workspaces, you can also import projects using the [Import project endpoint](https://docs.arcweave.com/rest-api/projects#import-project) of Arcweave's **REST API**. ### Import a project Context: Arcweave docs > Workspaces > Workspace projects > Import projects > Import a project To import a project into your workspace: 1. Go to the **Projects** section of your workspace. 2. Click the **Import** button at the top right. 3. Choose the file format you want to import. 4. Select the file from your device and upload it. ![The Projects section of an Arcweave workspace, with an orange arrow pointing at the "Import" button at the top right of the screen.](https://docs.arcweave.com/assets/import-project.CzEYalxL.png) Once the import is complete, the project will appear in your workspace's Projects list. > ℹ️ Imported projects are named `Imported - ` followed by the original project name. Because project names are limited to 255 characters, the original name can be up to 244 characters. ## Invite people Context: Arcweave docs > Workspaces > Workspace projects > Invite people Click the **invite** button (person icon with a plus) at the top right to invite team [members](https://docs.arcweave.com/workspaces/people#add-members) to your workspace. This button requires the **Manage memberships** permission. ## Project menu Context: Arcweave docs > Workspaces > Workspace projects > Project menu From the **Projects** section, you can open the menu for any project to perform the following actions: - Delete - Duplicate (Pro and Team workspaces only) - Rename - Upload/Change cover - Remove cover (if any) - Move to workspace The actions shown depend on your permissions. **Duplicate** requires **Duplicate projects**, **Delete** requires **Delete projects**, and **Move to workspace** requires **Move project**. Renaming and cover actions require **Edit projects**. As the [project owner](https://docs.arcweave.com/workspaces/roles#project-owner), you can also duplicate or delete projects you created. ### Open project menu Context: Arcweave docs > Workspaces > Workspace projects > Project menu > Open project menu Once in the **Projects** section, open the menu for a project as follows: 1. Hover over the project's thumbnail. 2. Click the **•••** icon that appears at its top-right corner. 3. Select the action you want to perform from the menu. Or: 1. Right-click the thumbnail. 2. Select the action you want to perform from the menu. ## Delete projects Context: Arcweave docs > Workspaces > Workspace projects > Delete projects To delete a project: 1. Go to the workspace's **Projects** section. 2. Open the project's menu using the **•••** icon or by right-clicking the thumbnail. 3. Select **Delete**. 4. Click **Delete** to confirm. > ⚠️ Deleting a project is permanent and _cannot be undone._ ## Duplicate projects Context: Arcweave docs > Workspaces > Workspace projects > Duplicate projects Pro and Team workspaces include the feature of project duplication. To duplicate a project: 1. Go to the workspace's **Projects** section. 2. Open the project's menu using the **•••** icon or by right-clicking the thumbnail. 3. Select **Duplicate**. ## Rename projects Context: Arcweave docs > Workspaces > Workspace projects > Rename projects To rename a project: **While the project is open**: Click the project's name at the top left of the window. **From within the workspace**: 1. Go to the workspace's **Projects** section. 2. Open the project's menu using the **•••** icon or by right-clicking the thumbnail. 3. Select **Rename**. 4. Type a new name for the project and press **Enter**. Project names can be up to 255 characters long. ## Project cover Context: Arcweave docs > Workspaces > Workspace projects > Project cover You can add, change, or remove a project's **cover image** from the **Projects** section. ### Add project covers Context: Arcweave docs > Workspaces > Workspace projects > Project cover > Add project covers 1. Go to the workspace's **Projects** section. 2. Open the project menu via **•••** or right-click. 3. Select **Upload cover** and choose an image. Project cover images can be `.jpg`, `.jpeg`, or `.png` files, up to **3 MB** and at least 128 x 128 pixels. ### Change project covers Context: Arcweave docs > Workspaces > Workspace projects > Project cover > Change project covers 1. Go to the workspace's **Projects** section. 2. Open the project menu. 3. Select **Change cover** and choose a new image. ### Remove project covers Context: Arcweave docs > Workspaces > Workspace projects > Project cover > Remove project covers 1. Go to the workspace's **Projects** section. 2. Open the project menu. 3. Select **Remove cover**. ## Move projects Context: Arcweave docs > Workspaces > Workspace projects > Move projects To move a project from one workspace to another: 1. Go to the workspace's **Projects** section. 2. Open the project menu. 3. Select **Move to workspace**. 4. Select the target workspace from the dropdown menu and press **Move**. > ℹ️ Moving projects requires **Move project** permission in the source workspace and **Create projects** permission in the target workspace. The target workspace must also have room for the project under its project and item limits. ## Open projects Context: Arcweave docs > Workspaces > Workspace projects > Open projects From the **Projects** section, click a project's thumbnail to open the project. ## Exit projects Context: Arcweave docs > Workspaces > Workspace projects > Exit projects From within a project, click the **Workspace** icon at the top left of the window (next to the project name) to return to the workspace. # Workspace people Source: https://docs.arcweave.com/workspaces/people Section: Workspaces Description: Invite and manage workspace members and guests, handle pending invitations and seats, and change member roles The **People** section of your workspace is where you manage all users associated with it. Access is permission-based: - **View memberships** allows a role to see the **Members** and **Guests** tabs. The default Commenter, Editor, and Owner roles all include it. - **Manage memberships** allows a role to invite members, change member roles, and manage guest access and pending invitations. - **Delete memberships** shows the **Remove** action for members and guests. Removing them from the **People** section also requires **Manage memberships**. Owners have all three permissions. Team workspaces can also grant them through [custom roles](https://docs.arcweave.com/workspaces/roles#add-new-roles). Depending on your permissions, the section contains up to three tabs: **Members**, **Guests**, and **Invitations**. ## Members tab Context: Arcweave docs > Workspaces > Workspace people > Members tab The **Members** tab displays a table of all current workspace members, sorted by their join date. ![The People section of an Arcweave workspace, showing the Members tab.](https://docs.arcweave.com/assets/people-members.CMM_gLcx.png) The Members tab has the following columns: - **User**: Displays each member's name and email address. - **Last active**: Displays when the member last opened a project, or **Never**. - **Role**: Displays their current role in the workspace. Users with **Manage memberships** can change it from this column when the membership is eligible for a role change. At the right side of each eligible row, a **three-dot (•••)** menu allows a user with **Delete memberships** to [remove a member](https://docs.arcweave.com/workspaces/people#remove-members). On your own row, the action is **Leave** instead of **Remove**, regardless of your role and permissions. At the top right, the **Add Member** button allows users with **Manage memberships** to [invite new people](https://docs.arcweave.com/workspaces/people#add-members) and assign them available roles. ## Guests tab Context: Arcweave docs > Workspaces > Workspace people > Guests tab The **Guests** tab lists all [guests](https://docs.arcweave.com/workspaces/roles#workspace-guests) who have been invited to specific projects within the workspace. ![The People section of an Arcweave workspace, showing the Guests tab.](https://docs.arcweave.com/assets/people-guests.e-v37mc2.png) > ✅ **Reminder:** Guests are users with access limited to specific projects. They are not workspace members. This tab has the following columns: - **User**: Displays each guest's name and email address. - **Last active**: Displays when the guest last opened a project, or **Never**. - **Access**: Displays how many projects the guest can access. Click it to see those projects. - **Billable**: Indicates whether the guest counts toward your workspace billing. Guest **editors** are billable; **commenters** are not. At the right side of each row, the available actions depend on your membership permissions. Users with **Manage memberships** or **Delete memberships**, respectively, can: - See and edit a guest's access to the workspace projects. - Remove the guest from the workspace. > ℹ️ **Note:** To add guests, a user with **Manage memberships** must invite them from within the project they should have access to. ## Invitations tab Context: Arcweave docs > Workspaces > Workspace people > Invitations tab ![The People section of an Arcweave workspace, showing the Invitations tab.](https://docs.arcweave.com/assets/people-invitations.C6Og3ZAS.png) The **Invitations** tab is available to users with **Manage memberships** and shows pending invitations to join the workspace as members. Accepted invitations move to **Members**; declined or cancelled invitations are not listed here. - The **User** column shows the invitee's email address. - The **Status** column shows **Pending**, or **Expired** when a pending invitation has passed its expiry date. - The **Role** column shows the role the invitee has been assigned. - The final column provides options to **Resend** or **Cancel** the invitation. This tab also includes an **Add Member** button for sending new invitations with predefined roles. ## Add members Context: Arcweave docs > Workspaces > Workspace people > Add members To add a user to a workspace, you must invite them and they must accept the invitation. ### Send invitations Context: Arcweave docs > Workspaces > Workspace people > Add members > Send invitations To send an invitation: 1. Go to the workspace's **People** section. 2. Click **Add Member**. 3. Enter the user's email address. 4. Select a role from the dropdown menu. 5. Review the seat and billing information shown in the dialog: - If a paid seat is already available, Arcweave shows how many seats remain. - If a new seat is required in a yearly workspace, eligible users can choose **Pay Yearly** or **Pay Monthly** under **Billing cycle**. See [Choose billing for an additional seat](https://docs.arcweave.com/workspaces/people#choose-billing-for-an-additional-seat). - Users with **Manage billing** or **Manage workspace** permission can review the next renewal date and amount, applicable discounts, and the estimated **Due today** amount for the selected cycle. 6. Click **Invite**. Until it gets accepted, the invitation will appear in the **Invitations** tab of the workspace's **People** section. > ℹ️ Sending an invitation does not create a charge. If an additional paid seat is needed when the invitation is accepted, Arcweave applies a **prorated charge** for the remainder of its billing period. The **Due today** estimate can change depending on the acceptance date. > ✅ **Basic** workspaces can have an unlimited number of members and guests for free, but they remain subject to Basic project, item, export, and asset limits. ### Choose billing for an additional seat Context: Arcweave docs > Workspaces > Workspace people > Add members > Choose billing for an additional seat When inviting a member to a yearly **Pro** or **Team** workspace, you can choose **Pay Yearly** or **Pay Monthly** for the additional seat. **Pay Yearly** is selected initially. The choice appears only when no unused paid seats remain and you have **Manage billing** or **Manage workspace** permission, in addition to **Manage memberships** permission to send the invitation. The options show the price per month per editor. The **Order summary** updates to show the selected cycle's next renewal, applicable discounts, and estimated **Due today** amount. Yearly seats are billed yearly even though the option displays their equivalent monthly price. The selected cycle is saved with the invitation and applied when it is accepted, if a new paid seat is still needed. Existing seats keep their billing cycles, so monthly and yearly seats can coexist in the same workspace. If an unused paid seat is available, the new member uses it without adding a seat or choosing a billing cycle. Invitations sent without a billing-cycle selection, including [guest-editor invitations](https://docs.arcweave.com/workspaces/roles#invite-guests), add a monthly seat when a new seat is needed. See [yearly workspace billing](https://docs.arcweave.com/workspaces/billing-plans#yearly-billed-workspaces) for renewal details and examples. ### Pending invitations Context: Arcweave docs > Workspaces > Workspace people > Add members > Pending invitations To manage pending invitations: 1. Open the **Invitations** tab under **People**. 2. Click the **•••** menu next to the invite. 3. Choose **Resend invite** or **Cancel invite**. > ℹ️ To change a pending invitee's role, cancel the invitation and send a new one with the desired role. ## Change member Roles Context: Arcweave docs > Workspaces > Workspace people > Change member Roles To change a member's role, follow the next steps: 1. Go to the **People** section of your workspace. 2. Use the **Role** dropdown next to the member's name. 3. Select the new role. > ℹ️ A workspace must always have at least one **Owner**. If you are the only Owner, you must assign another before changing your own role. You need **Manage memberships** permission to change another member's role. ## Remove members Context: Arcweave docs > Workspaces > Workspace people > Remove members To remove a member: 1. Go to the **People** section. 2. Go to the **Members** tab. 3. Click the **three-dot (•••)** menu next to their name and select **Remove**. 4. Click **Remove** to confirm. The user will be removed from the workspace. Their seat remains available for another member to be added, until the end of its billing cycle. Projects that the removed member [owns](https://docs.arcweave.com/workspaces/roles#project-owner) and the API keys they created are transferred to the workspace's longest-standing remaining **Owner**. You need **Delete memberships** and **Manage memberships** permissions to remove another member. ## Leave a workspace Context: Arcweave docs > Workspaces > Workspace people > Leave a workspace To leave a workspace yourself: 1. Go to **People > Members**. 2. Open the **three-dot (•••)** menu on your own row. 3. Select **Leave** and confirm. You immediately lose access to the workspace. If you are the workspace's only **Owner**, you must assign another Owner before leaving. ## Add guests Context: Arcweave docs > Workspaces > Workspace people > Add guests Workspace guests are users invited to specific projects and their access is limited to those. They are not workspace members, so they cannot be invited from the **People** section of a workspace. To add guests, a user with **Manage memberships** must [invite them](https://docs.arcweave.com/workspaces/roles#invite-guests) from within a specific project. ## Remove guests Context: Arcweave docs > Workspaces > Workspace people > Remove guests To remove a guest from the workspace: 1. Go to the **People** section. 2. Go to the **Guests** tab. 3. Click the **three-dot (•••)** menu next to their name and select **Remove**. 4. Click **Remove** to confirm. This removes the guest from all of the workspace's projects. The user will be removed from the workspace. Their seat remains available for another member or guest to be added, until the end of its billing cycle. You need **Delete memberships** and **Manage memberships** permissions to remove another guest from the **People** section. Guests can remove themselves from an individual project by selecting **Leave** for their own entry in that project's **Share** dialog. ## Edit guest access Context: Arcweave docs > Workspaces > Workspace people > Edit guest access To edit a guest's access to the workspace projects: 1. Go to the **People** section. 2. Go to the **Guests** tab. 3. Click the **three-dot (•••)** menu next to their name and select **See access**. 4. Edit the user's access to any project. # Workspace roles Source: https://docs.arcweave.com/workspaces/roles Section: Workspaces Description: Workspace and project roles and permissions for members, guests, and visitors, including custom roles In Arcweave, roles define what users can see and do at both the **workspace** and **project** level, according to their set of **permissions**. Arcweave users can belong to one of the following categories: - [**Workspace members**](https://docs.arcweave.com/workspaces/roles#workspace-members) Users who share access to all projects in the workspace. - [**Workspace guests**](https://docs.arcweave.com/workspaces/roles#workspace-guests) Users invited to collaborate in specific projects only. - [**Project visitors**](https://docs.arcweave.com/workspaces/roles#project-visitors) Users who can view and play a public project via a link. ## Workspace members Context: Arcweave docs > Workspaces > Workspace roles > Workspace members A workspace member has access to all projects in a workspace, with permissions that vary based on the member's role. The workspace includes three default roles: - **Commenter** - **Editor** - **Owner** These roles come with predefined permission sets that **cannot be modified**. In Team workspaces, owners can create additional custom roles instead. ### Commenter Context: Arcweave docs > Workspaces > Workspace roles > Workspace members > Commenter - Can view the workspace's **Projects** list. - Can open and comment on all workspace projects. - Can view the workspace's **People** list, including members and guests. ### Editor Context: Arcweave docs > Workspaces > Workspace roles > Workspace members > Editor - Includes all commenter permissions. - Can edit all projects in the workspace. - Can create new projects. - Can export any project, including `.arcw` backups. - Can duplicate, import, and manage project settings. - Can view and create API keys when the workspace plan includes REST API access. - Can delete only the projects they created, as their [project owner](https://docs.arcweave.com/workspaces/roles#project-owner). Deleting other projects requires a custom role with the **Delete projects** permission. ### Owner Context: Arcweave docs > Workspaces > Workspace roles > Workspace members > Owner - Includes all editor permissions. - Can invite or remove members and assign their roles. - Can manage **Settings**, **Billing**, **Roles**, and all workspace-level configurations. - Can delete any project and move projects to other workspaces. > ℹ️ A permission does not override plan availability. For example, the Editor role includes API-key permissions, but REST API access is available only on Team workspaces. > ✅ Multiple users can hold the same role. > ℹ️ A workspace's initial owner is the user who created it, but additional owners can be assigned later. ## Roles section Context: Arcweave docs > Workspaces > Workspace roles > Roles section The **Roles** section of the workspace allows you to manage user roles and their associated permissions. It is visible only to users with the **Manage roles** permission, which the default **Owner** role includes. ![The Roles section of an Arcweave Team workspace, demonstrating a custom role called Silent Beholder, who only has viewing permissions.](https://docs.arcweave.com/assets/roles.CHDaiTBv.png) Each role is presented in its own tab, containing its name, description, and a list of permissions. > ✅ **Team** workspaces allow owners to define **custom roles** with granular permissions. ## Add new roles Context: Arcweave docs > Workspaces > Workspace roles > Add new roles Below the default roles, **Team workspaces** have access to a button for adding custom roles. This feature allows you to tailor roles to match your team's workflow. In other workspaces, the button opens an upgrade prompt. To create a custom role (Team workspaces only): 1. Go to the **Roles** section of your workspace. 2. Click **+ New workspace role**. 3. Name and describe the role, then click **Save**. 4. Toggle the desired permissions on or off. A new role starts with no permissions. 5. Click **Save** in the unsaved changes bar at the bottom of the window. ## Delete custom roles Context: Arcweave docs > Workspaces > Workspace roles > Delete custom roles Before deleting a custom role, [change the role of every member assigned to it](https://docs.arcweave.com/workspaces/people#change-member-roles) in the workspace's **People** section. A role cannot be deleted while any workspace members still have it. To delete a custom role (Team workspaces only), do the following: 1. Go to the **Roles** section of your workspace. 2. Select the role to delete. 3. Scroll down and click **Delete**. 4. Press **Delete** in the **Delete Role** dialog to confirm the deletion. ## List of permissions Context: Arcweave docs > Workspaces > Workspace roles > List of permissions Within each role tab, beneath the name and description, you'll find a list of available permissions. **Default roles** have fixed permissions. **Custom roles** (Team workspaces only) allow toggling permissions on or off to suit specific responsibilities. Custom roles can be configured using the following permissions: | Permission | Description | | -------------------------- | -------------------------------------------------------------------------------------------------------------- | | **Manage workspace** | Edit workspace settings and delete workspace. | | **View memberships** | See the list of members and Guests. | | **Manage memberships** | Invite and edit member roles (requires view permissions). | | **Delete memberships** | Remove members (requires view permissions). | | **View projects list** | Access project list and open all projects and Play Modes. | | **Comment project** | Add and reply to comments (requires view permissions). | | **Edit projects** | Modify project content (requires view permissions). | | **Duplicate projects** | Duplicate any project (requires view permissions). | | **Manage projects** | Change project-level settings (requires view permissions). | | **Delete projects** | Delete any project (requires view permissions). | | **Create projects** | Start new projects in the workspace (requires view permissions). | | **Export projects** | Export projects to external formats (requires view permissions). | | **Export projects backup** | Export `.arcw` backup files (requires view permissions). | | **Import projects** | Import projects from `.json` files, `.arcw` backup files, or through the REST API (requires view permissions). | | **Manage roles** | Create, modify, and delete custom roles. | | **View API keys** | See workspace API keys. | | **Create API key** | Generate new API keys (requires view permission). | | **Manage API** | Edit API key names and project permissions, or delete keys (requires view permission). | | **Manage billing** | Modify billing settings and view invoices. | | **Move project** | Move projects to another workspace. | ## Project roles Context: Arcweave docs > Workspaces > Workspace roles > Project roles In addition to workspace roles, users can be granted **project-specific roles**, which control access and permissions within individual projects: ### Project commenter Context: Arcweave docs > Workspaces > Workspace roles > Project roles > Project commenter - Can view the project and its Play Mode. - Can add comments and replies. ### Project editor Context: Arcweave docs > Workspaces > Workspace roles > Project roles > Project editor - Includes all project commenter permissions. - Can edit the project. - Can access the project's debugger. - Can export the project. - Can change the project's [public access](https://docs.arcweave.com/project-tools/share#make-a-project-public). ### Project owner Context: Arcweave docs > Workspaces > Workspace roles > Project roles > Project owner - Includes all project editor permissions. - Can export a project backup. - Can duplicate or delete the project. The project owner is the workspace member who created, duplicated, or imported the project; this role cannot be assigned to guests. If the project owner is removed from the workspace, ownership passes to the workspace's longest-standing remaining **Owner**. Project ownership does not by itself grant workspace membership-management permissions. Inviting guests, changing another guest's role, or removing another guest requires **Manage memberships** or **Delete memberships**, as appropriate. Project ownership cannot currently be transferred from the Share dialog. > ℹ️ A project role adds project-specific permissions to any permissions the user already has from their workspace role. For example, a workspace commenter may also be a project editor on a specific project. ## Workspace guests Context: Arcweave docs > Workspaces > Workspace roles > Workspace guests Guests are users invited to collaborate on specific projects without being workspace members. Guests: - Are assigned either **project commenter** or **project editor** roles. - Can only access the specific projects they are invited to. - Can enter the workspace's **Projects** list, where they see only those assigned projects. - Cannot create workspace projects or delete projects through the Projects list. > ℹ️ Guests are **not a workspace role**, but an implicit status based on access. If a guest loses all project roles, they are removed from the workspace. > ⚠️ Guest editors count toward billing (1 seat each). Guest commenters do not. See more on [adding](https://docs.arcweave.com/workspaces/billing-plans#add-seats) and [removing seats](https://docs.arcweave.com/workspaces/billing-plans#remove-seats) on the **Workspace plans** page. ### Invite guests Context: Arcweave docs > Workspaces > Workspace roles > Workspace guests > Invite guests ![The Arcweave window showing an open project and its "Share" modal. The modal allows the user to invite more collaborators to the project and to configure the project's private or public state.](https://docs.arcweave.com/assets/share.Dygv2dx1.png) To invite a user to a project: 1. Open the project. 2. Click **Share** in the top menu. 3. Enter their email under **Email address**. 4. Choose a role: **Commenter** or **Editor**. 5. Click **Invite**. You need **Manage memberships** permission to send a guest invitation or manage a pending one. > ⚠️ Guest editors count toward billing (1 seat each). See more on [adding](https://docs.arcweave.com/workspaces/billing-plans#add-seats) and [removing seats](https://docs.arcweave.com/workspaces/billing-plans#remove-seats) on the **Workspace plans** page. ### Remove guests Context: Arcweave docs > Workspaces > Workspace roles > Workspace guests > Remove guests You can remove workspace guests from either the project's **Share** modal or the workspace's **People** section: - Within the project: 1. Open the project. 2. Click **Share** in the top menu. 3. Under **People with access**, locate the user's name 4. Click the dropdown that displays their role. 5. Select **Remove**. - From the workspace's **People** section: See [People](https://docs.arcweave.com/workspaces/people) > [Remove guests](https://docs.arcweave.com/workspaces/people#remove-guests). Removing another guest requires **Delete memberships** permission. A guest can remove themselves by choosing **Leave** for their own entry in the Share dialog. ### Change guest roles Context: Arcweave docs > Workspaces > Workspace roles > Workspace guests > Change guest roles You can change the roles of workspace guests from either the project's **Share** modal or the workspace's **People** section: - Within the project: 1. Open the project. 2. Click **Share** in the top menu. 3. Under **People with access**, locate the user's name 4. Click the dropdown that displays their role. 5. Select a new role for the user. - From the workspace's **People** section: See [People](https://docs.arcweave.com/workspaces/people) > [Edit guest access](https://docs.arcweave.com/workspaces/people#edit-guest-access). Changing another guest's role requires **Manage memberships** permission. A guest editor can downgrade their own role to Commenter but cannot upgrade themselves. > ⚠️ Guest editors count toward billing (1 seat each). See more on [adding](https://docs.arcweave.com/workspaces/billing-plans#add-seats) and [removing seats](https://docs.arcweave.com/workspaces/billing-plans#remove-seats) on the **Workspace plans** page. ## Project visitors Context: Arcweave docs > Workspaces > Workspace roles > Project visitors Project visitors is the implicit role taken by users who view a public project or its Play Mode via a link. They: - Do not require an Arcweave account. - Cannot comment or interact with the project. - Are not workspace members or guests and have no assignable role. > ℹ️ The number of project visitors is not tracked and cannot be viewed in the workspace or project. # Workspace settings Source: https://docs.arcweave.com/workspaces/settings Section: Workspaces Description: Workspace settings for the icon, name, ID, and AI functionality, plus changing the plan or deleting the workspace The workspace **Settings** section provides access to important workspace properties. ![The Settings section of an Arcweave workspace.](https://docs.arcweave.com/assets/settings.6ZtNdUKJ.png) On this page, you can access and configure the following settings: - [Workspace icon](https://docs.arcweave.com/workspaces/settings#workspace-icon) - [Workspace ID](https://docs.arcweave.com/workspaces/settings#workspace-id) - [AI functionality](https://docs.arcweave.com/workspaces/settings#ai-functionality) - [Workspace name](https://docs.arcweave.com/workspaces/settings#workspace-name) - Option to [change the workspace plan](https://docs.arcweave.com/workspaces/settings#change-workspace-plan) - Option to [delete the workspace](https://docs.arcweave.com/workspaces/settings#delete-workspace) > ℹ️ To change a workspace's billing plan, see [Change billing plan](https://docs.arcweave.com/workspaces/billing-plans) (next page). > ℹ️ To change the email address that receives invoices, edit the **Billing email** under [Billing > Invoice details](https://docs.arcweave.com/workspaces/billing#invoice-details). ## Workspace icon Context: Arcweave docs > Workspaces > Workspace settings > Workspace icon You can set an icon for your workspace to help it visually stand out in your [workspace list](https://docs.arcweave.com/workspaces/list). ### Add workspace icon Context: Arcweave docs > Workspaces > Workspace settings > Workspace icon > Add workspace icon To add an icon to your workspace: 1. Go to **Settings > Workspace icon**. 2. Click the icon field. 3. In the **Upload Image** modal, drag an image or click to upload one from your device. 4. Adjust the crop boundaries as needed. 5. Click **Save**. ### Change workspace icon Context: Arcweave docs > Workspaces > Workspace settings > Workspace icon > Change workspace icon To change the workspace icon, click the existing icon (not the red 'X') and repeat the steps above for [adding a workspace icon](https://docs.arcweave.com/workspaces/settings#add-workspace-icon). ### Delete workspace icon Context: Arcweave docs > Workspaces > Workspace settings > Workspace icon > Delete workspace icon To remove the workspace icon, click the red **X** at the top right corner of the icon. ## Workspace ID Context: Arcweave docs > Workspaces > Workspace settings > Workspace ID This section displays your workspace's unique ID. To copy it to your clipboard, click the **clipboard** icon. > ℹ️ The workspace ID is also visible in the URL, right after `arcweave.com/app/workspace/`. ## AI functionality Context: Arcweave docs > Workspaces > Workspace settings > AI functionality To enable or disable AI features in your workspace: 1. Go to **Settings > Workspace AI functionality**. 2. Toggle the switch **on** or **off**. 3. Click **Save** in the unsaved changes bar at the bottom of the window. ## Workspace name Context: Arcweave docs > Workspaces > Workspace settings > Workspace name To rename your workspace: 1. Go to **Settings > Workspace name**. 2. Edit the current name. 3. Click **Save** in the unsaved changes bar at the bottom of the window. ## Change workspace plan Context: Arcweave docs > Workspaces > Workspace settings > Change workspace plan To upgrade or downgrade your workspace: 1. Go to **Settings > Change plan**. 2. Click **Change**. 3. In the pricing modal, select a different plan. > ⚠️ For detailed information on billing & changing plans, see [Workspace plans](https://docs.arcweave.com/workspaces/billing-plans). > ℹ️ To [add](https://docs.arcweave.com/workspaces/people#add-members) or [remove members](https://docs.arcweave.com/workspaces/people#remove-members), go to the **People** section of your workspace. ## Delete workspace Context: Arcweave docs > Workspaces > Workspace settings > Delete workspace To permanently delete a workspace: 1. Go to the workspace's **Settings** section. 2. Scroll to the **Delete workspace** field. 3. Click **Delete**. 4. Type the workspace's name to confirm, then click **Continue**. > ⚠️ Deleting a workspace is an action that _cannot be undone!_ > ℹ️ You cannot delete your only workspace. # Workspace billing Source: https://docs.arcweave.com/workspaces/billing Section: Workspaces Description: Workspace billing details, including seat cards, AI usage, payment method, invoice details, failed payments, and billing history The **Billing** section contains an overview of your subscription and seats, AI usage, payment and invoice details, and billing history. Access is permission-based: - **Manage billing** or **Manage workspace** permission opens the **Billing** section, including the overview, AI usage, payment method, invoice details, and billing history. Users with **Manage workspace** can also edit the billing email. - Only **Manage billing** allows a role to change the plan, payment method, and invoice details, and to convert monthly seats to yearly billing. - Of the default roles, only **Owner** includes these permissions. Team workspaces can also grant them through [custom roles](https://docs.arcweave.com/workspaces/roles#add-new-roles). ![The top part of an Arcweave workspace's Billing section.](https://docs.arcweave.com/assets/billing-top.BzzSuLKt.png) From top to bottom, you can find: - **Current Plan**: The active plan. Click **Change** to choose another plan. - **Total Seats**: The number of billable users and subscribed seats. In Pro and Team workspaces, click **Manage** to see the users occupying those seats. - **Next Invoice**: The amount and date of the next monthly invoice, when one is scheduled. - **Yearly Seats** and **Monthly Seats**: Seat usage, renewal dates, and the amounts of the next invoices for each billing cycle. - **AI usage**: Your workspace's monthly AI credit usage, remaining credits, and reset date. - **Discount**: Any coupon discounts applied to the next monthly invoice, when present. - **Payment method**: Your selected card or other method of payment. - **Invoice details**: Your billing email, company name, VAT number, and address that appear on your invoices. - **Billing history**: A list of all your invoices and receipts. ## Seat cards Context: Arcweave docs > Workspaces > Workspace billing > Seat cards Pro and Team subscriptions display one or both of the following cards below the billing overview: - **Yearly Seats** shows occupied yearly seats out of the total purchased, their renewal date, and the next yearly invoice amount. - **Monthly Seats** shows occupied monthly seats out of the total purchased, their renewal date, and the next monthly invoice amount. A yearly workspace can have both kinds of seats. Seats purchased with the initial yearly subscription are yearly seats. If a user is removed before a paid seat's renewal date, that seat remains open for another billable user until it expires. When inviting a member who needs an additional paid seat, users with the required permissions can [choose monthly or yearly billing](https://docs.arcweave.com/workspaces/people#choose-billing-for-an-additional-seat). The choice applies when the invitation is accepted. Invitations without a billing-cycle selection, including guest-editor invitations, add a monthly seat when needed. A user with **Manage billing** permission can [convert monthly seats to yearly billing](https://docs.arcweave.com/workspaces/billing#switch-monthly-seats-to-yearly) from this section. ### Switch monthly seats to yearly Context: Arcweave docs > Workspaces > Workspace billing > Seat cards > Switch monthly seats to yearly When at least one monthly seat is occupied, the **Monthly Seats** card provides a **Switch to yearly** action to users with **Manage billing** permission. 1. Go to the workspace's **Billing** section. 2. On the **Monthly Seats** card, click **Switch to yearly**. 3. Choose the number of monthly seats to convert. 4. Review the next monthly and yearly renewal totals, estimated savings, and the amount due today. 5. Click **Switch to yearly** to confirm. The converted seats move to the yearly seat total. Any monthly seats you do not convert keep their monthly billing cycle. ## AI usage Context: Arcweave docs > Workspaces > Workspace billing > AI usage The **AI usage** section shows how many AI credits your workspace has used during the current month, how many remain, and when the allowance resets. ![The Billing section of an Arcweave workspace, showing the AI usage section highlighted.](https://docs.arcweave.com/assets/ai-credits-billing.BubVvs9N.png) Users with permission to manage billing, or permission to manage the workspace, can see this summary. This section includes: - The number of **credits used** out of the workspace's **effective monthly limit** - The number of **credits left** - The monthly **reset date** - A usage state: **Credits available**, **Approaching limit**, **Monthly limit reached**, or **AI disabled** If the workspace is on **Basic** or **Pro**, users with **Manage billing** permission also see an **Upgrade plan** link so they can move to a higher plan for a larger monthly AI allowance. ## Payment method Context: Arcweave docs > Workspaces > Workspace billing > Payment method To change your payment method, click **Change** next to your current payment method. ![Billing section showing the option to edit the workspace payment method.](https://docs.arcweave.com/assets/billing-edit-payment-method.BMzU4HOV.png) ## Invoice details Context: Arcweave docs > Workspaces > Workspace billing > Invoice details This section lets you see and edit the billing information used on your invoices. It includes: - Company name - Billing email - Address: - Street address - City - State - Zip/Postal code - Country - VAT ID ### Edit invoice details Context: Arcweave docs > Workspaces > Workspace billing > Invoice details > Edit invoice details ![Billing section showing editable invoice details for a workspace.](https://docs.arcweave.com/assets/billing-edit-invoice-details.UT9Vig87.png) To update your invoice details or billing email: 1. Click **Edit invoice details**. If only a billing email is present, click **Edit billing email**. 2. Fill in the updated information. Invoice details require a company name (or your full name) and a country; the other address fields and VAT ID are optional. 3. Submit the form to save your changes. ## Overdue invoices Context: Arcweave docs > Workspaces > Workspace billing > Overdue invoices ### Payment retry Context: Arcweave docs > Workspaces > Workspace billing > Overdue invoices > Payment retry When an invoice becomes overdue, Arcweave will make up to 3 attempts to charge you via your selected payment method. If the charge fails due to an issue with your payment method, you can update it [as described above](https://docs.arcweave.com/workspaces/billing#payment-method). > ℹ️ Updating your payment method will also trigger an immediate retry of an overdue invoice payment. ### Payment failure Context: Arcweave docs > Workspaces > Workspace billing > Overdue invoices > Payment failure If all retry attempts fail and the invoice remains unpaid, the following actions apply, depending on your plan: #### Overdue monthly invoice on a monthly plan Context: Arcweave docs > Workspaces > Workspace billing > Overdue invoices > Payment failure > Overdue monthly invoice on a monthly plan Your subscription will be cancelled and your workspace will automatically downgrade to **Basic**. #### Overdue yearly invoice on a yearly plan Context: Arcweave docs > Workspaces > Workspace billing > Overdue invoices > Payment failure > Overdue yearly invoice on a yearly plan The same as above: your subscription will be cancelled and your workspace will automatically downgrade to **Basic**. #### Overdue monthly invoice on a yearly plan: Context: Arcweave docs > Workspaces > Workspace billing > Overdue invoices > Payment failure > Overdue monthly invoice on a yearly plan: > ℹ️ This case applies to yearly workspaces with additional seats on monthly billing. See [Add seats to a yearly plan](https://docs.arcweave.com/workspaces/billing-plans#yearly-billed-workspaces). If the monthly invoice remains unpaid, _your yearly subscription will not be cancelled._ The monthly seats are removed. If the number of billable users exceeds the remaining yearly seats, Arcweave removes enough users to fit that capacity, in this order: 1. Members who are not Owners and guest editors, starting with those added most recently. 2. Owners, starting with those added most recently, if further removals are needed. The last Owner is always retained. The remaining yearly seats are shared capacity; they are not permanently assigned to particular users. If all billable users already fit within that capacity, no users are removed. Once this adjustment is complete, your yearly subscription will continue normally on its annual billing cycle. ## Billing history Context: Arcweave docs > Workspaces > Workspace billing > Billing history The final section displays your workspace's billing and invoice history. ![The billing history table in the Billing section of an Arcweave workspace, showing a list of downloadable invoices.](https://docs.arcweave.com/assets/billing-invoices.D155uJ-i.png) To download an invoice: 1. Find the invoice using its **date**, **description**, and **amount**. 2. Click the download icon at the end of the row. 3. Save the file to your device. # Workspace API Source: https://docs.arcweave.com/workspaces/api Section: Workspaces Description: Manage API keys and permissions for Arcweave's REST API The **API** section lists your workspace's API keys for the [REST API](https://docs.arcweave.com/rest-api/overview) and [MCP server](https://docs.arcweave.com/integrations/mcp). API access is available to **Team workspaces only** and supports read and write access to project data. The section is visible to users with the **View API keys** permission. The key list shows each key's **Name**, **Key**, **Permissions**, **Created** date, and **Last used** date. ![The API section of a Team workspace in Arcweave, showing API keys and their Read and Write permissions.](https://docs.arcweave.com/assets/api-section.C882MQUI.png) ## Create API keys Context: Arcweave docs > Workspaces > Workspace API > Create API keys To create a new API key, you need the **Create API key** permission: 1. Click **Create new key**. 2. Give your key a descriptive name to help you remember its purpose. 3. Under **Project permissions**, select **Read projects**, **Write projects**, or both. You must select at least one permission. 4. Click **Create**. The new key will appear in your API key list. Its **Permissions** column shows **Read** and/or **Write** badges. ### Project permissions Context: Arcweave docs > Workspaces > Workspace API > Create API keys > Project permissions **Read projects** is selected by default when you create a key. It allows listing, viewing, and exporting projects and their content. This is the permission needed by the Unity, Unreal Engine, and Godot integrations to import project data. **Write projects** allows creating, importing, updating, and deleting projects and their content. It does not include read access: select both permissions when your integration needs to read and write data. These key permissions work together with the workspace and project permissions of the member who created the key. A key cannot grant access beyond that member's permissions. If that member is removed from the workspace, the key is transferred to the workspace's longest-standing remaining **Owner** and uses that Owner's permissions from then on. See [REST API permissions](https://docs.arcweave.com/rest-api/overview#permissions) for the requirements for each operation. Keys that existed before project permissions were introduced were assigned both **Read projects** and **Write projects**. Review their permissions and edit any key that should only read project data. ## Remove API keys Context: Arcweave docs > Workspaces > Workspace API > Remove API keys To delete an existing API key: 1. Find the key in the list. 2. Click the **settings** icon (three dots) at the end of the row. 3. Select **Remove**. 4. Confirm the deletion by clicking **Delete** in the modal. ## Edit API keys Context: Arcweave docs > Workspaces > Workspace API > Edit API keys To rename an existing API key or change its permissions: 1. Locate the key in the list. 2. Click the **settings** icon (three dots) at the end of the row. 3. Select **Edit key**. 4. Update the name and/or **Project permissions**, then click **Save**. Permission changes apply immediately to the same key. Removing a permission causes requests that require it to return `403 Forbidden`. You can edit or remove your own keys with **Create API key** permission. **Manage API** permission lets you edit or remove any key in the workspace. ## Copy API keys Context: Arcweave docs > Workspaces > Workspace API > Copy API keys To copy an API key to your clipboard: 1. Find the key in the list. 2. In the **Key** column, click the **clipboard** icon. The key will now be copied to your device's clipboard. Store it securely and keep it out of public repositories and applications distributed to end users. > ⚠️ Keys remain copyable from this list after creation. Every user with **View API keys** permission can copy any key in the workspace, including keys created by other members. # Your Arcweave account Source: https://docs.arcweave.com/account/overview Section: Account Description: Create your Arcweave account, find your default workspace, and manage your profile and notifications on the My Account page Your free Arcweave account lets you create and manage your [projects](https://docs.arcweave.com/workspaces/projects) across unlimited [workspaces](https://docs.arcweave.com/workspaces/overview), each billed independently. You can update your personal preferences anytime from your [account settings](https://docs.arcweave.com/account/overview#my-account-page). ## Creating an account Context: Arcweave docs > Account > Your Arcweave account > Creating an account To create an Arcweave account: 1. Sign up with your email address and a secure password. 2. Check your inbox for a verification email. 3. Click the link in the email to verify your account. Arcweave signs you in and opens your workspace. You can also select **Continue with Google** on the sign-up page to create your account with Google. Google sign-up does not require the email verification step. > ✅ Creating an Arcweave account is—and will always be—free! > ℹ️ Can't find the link? Check your spam folder. If it's still missing, contact us through our [Discord](https://discord.gg/atVXxAK) channel. ## Default workspace Context: Arcweave docs > Account > Your Arcweave account > Default workspace ![The Projects section of the Basic workspace containing only the Interactive Fiction Example project named "The Castle."](https://docs.arcweave.com/assets/projects-page-free.D570iK2y.png) New accounts start with a default [Basic workspace](https://docs.arcweave.com/workspaces/billing-plans#workspace-comparison), automatically named after the user. This workspace includes a sample project called _The Castle,_ which you can recreate anytime using the **Interactive Fiction Example** [project template](https://docs.arcweave.com/workspaces/projects#project-templates). To add more workspaces, see the [workspace list](https://docs.arcweave.com/workspaces/list) page. ## My Account page Context: Arcweave docs > Account > Your Arcweave account > My Account page You can manage or delete your account from **My Account**. To open your account settings: 1. From any workspace or project window, click your **user icon** in the top-right corner. 2. Select **My Account** from the menu. The **My Account** page includes two tabs: **Profile** and **Notifications**, where you can manage your account settings. ![Arcweave's My Account page, Profile tab, showing the fields and settings described in this documentation page.](https://docs.arcweave.com/assets/account-profile.Bp8WhF-I.png) ### Account photo Context: Arcweave docs > Account > Your Arcweave account > My Account page > Account photo To add a profile photo: 1. Go to **My Account > Profile > Photo**. 2. Click the **+** icon or **Edit**, then upload an image from your device. To remove your photo, click **Delete**. ### Account color Context: Arcweave docs > Account > Your Arcweave account > My Account page > Account color To change your profile color: 1. Go to **My Account > Profile > Color**. 2. Choose one of the available colors. > ℹ️ This color appears in your avatar during collaborative work. ### Account name Context: Arcweave docs > Account > Your Arcweave account > My Account page > Account name To change your name: 1. Go to **My Account > Profile > Name**. 2. Click **Edit**, update your first and last name, then click **Change name**. ### Account email Context: Arcweave docs > Account > Your Arcweave account > My Account page > Account email To update your email address: 1. Go to **My Account > Profile > Email**. 2. Click **Edit**, enter your new email address twice, then click **Update email**. ### Account password Context: Arcweave docs > Account > Your Arcweave account > My Account page > Account password To change your password: 1. Go to **My Account > Profile > Password**. 2. Click **Edit**, enter your current password and your new password (twice), then click **Change password**. If you signed up with Google and have not set a password, the **Password** row shows **Set a password** instead. You must set a password before you can change your email address. ### Delete your account Context: Arcweave docs > Account > Your Arcweave account > My Account page > Delete your account Before deleting your account, each workspace where you are the only **Owner** and still have other members or guests needs one of these changes: - [Change another member's role](https://docs.arcweave.com/workspaces/people#change-member-roles) to **Owner** so they can continue managing the workspace. - [Remove the other members](https://docs.arcweave.com/workspaces/people#remove-members) and [all guests](https://docs.arcweave.com/workspaces/people#remove-guests) if you no longer need to share the workspace. If this requirement is not met, the deletion dialog lists the affected workspaces. Resolve each one before trying again. A workspace where you are the only member and there are no guests does not block account deletion. To permanently delete your account: 1. Go to **My Account > Profile > Delete your Arcweave account**. 2. Click **Delete account**. 3. Read the warning and check both confirmation boxes. 4. Click **Yes, delete my account**. ## Notifications Context: Arcweave docs > Account > Your Arcweave account > Notifications ![Arcweave's My Account page, Notifications tab, showing the fields and settings described in this documentation page.](https://docs.arcweave.com/assets/account-notifications.D8jnxUaa.png) To manage your notification preferences: 1. Go to **My Account > Notifications > Send me emails about**. 2. Check or uncheck **New features and updates**.

Color	Selector
██████████	`.prototype__option.pink`
██████████	`.prototype__option.red`
██████████	`.prototype__option.purple`
██████████	`.prototype__option.lightBlue`
██████████	`.prototype__option.cyan`
██████████	`.prototype__option.moss`
██████████	`.prototype__option.green`
██████████	`.prototype__option.gold`
██████████	`.prototype__option.brown`
██████████	`.prototype__option.default`
██████████	`.prototype__option.orange`
██████████	`.prototype__option.blue`