Arcweave scoped variables: game-engine migration guide

Updated documentation: Variables overview, board variables, component variables, attributes, and the current JSON export structure.

Engine and runtime guides: Unity, Unreal Engine, Godot, and custom Arcscript interpreters.

Board and component variables are now first-class Arcweave data

Arcweave 5.11, released on September 2, 2026, introduces component variables and unifies board- and component-scoped values under the attributes data model. This makes reusable, scoped state possible across boards and components, but it also changes the JSON representation consumed by custom integrations.

Who needs to take action?

You should review this guide if you:

• parse Arcweave JSON exports directly;
• retrieve JSON or game-engine data through the Arcweave API;
• maintain a custom Unity, Unreal, Godot, or other engine integration;
• inspect variable-change dictionaries or serialized variable state; or
• use an older version of an official Arcweave engine plugin.

If you only author and play projects inside Arcweave, no manual migration is required in most cases. Existing board variables are migrated automatically. One known exception is a migrated board string variable whose authored default was empty: it may be stored as null, which Arcscript does not accept as a variable value. If you used empty-string board defaults—or if an existing variable is missing or behaves differently—contact Arcweave support rather than recreating it manually.

Summary of the change

Before 5.11, global and board variables were stored together in the top-level variables object. A board referenced its variables through a variables array.

From 5.11 onward:

• global variables remain in the top-level variables object;
• board variables are attributes owned by a board;
• component variables are attributes owned by a component;
• boards and components reference these values through attributes arrays;
• the attribute's customId is its Arcscript member name;
• the board or component's customId is its Arcscript scope; and
• the stable UUID of an existing board variable is preserved during migration.

For example, castle.drawbridge_open still uses castle as its scope and drawbridge_open as its member name. Only its exported storage representation has changed.

JSON before and after

The following are simplified excerpts that show only the records relevant to this migration. Real exports also include root and folder records in variables; loaders should ignore entries with root or children.

Before Arcweave 5.11

{
  "boards": {
    "board-uuid": {
      "name": "Castle",
      "customId": "castle",
      "variables": ["variable-uuid"]
    }
  },
  "variables": {
    "variable-uuid": {
      "name": "drawbridge_open",
      "type": "boolean",
      "value": false,
      "cType": "boards",
      "cId": "board-uuid"
    }
  },
  "attributes": {}
}

Arcweave 5.11 and later

{
  "boards": {
    "board-uuid": {
      "name": "Castle",
      "customId": "castle",
      "attributes": ["variable-uuid"]
    }
  },
  "variables": {},
  "attributes": {
    "variable-uuid": {
      "name": "drawbridge_open",
      "customId": "drawbridge_open",
      "cType": "boards",
      "cId": "board-uuid",
      "value": {
        "type": "boolean",
        "data": false
      }
    }
  }
}

The object key variable-uuid is unchanged. Integrations should continue to treat that key as the stable identity of the value.

Field mapping

Which attributes are Arcscript variables?

An attribute is a scoped Arcscript variable when all of the following are true:

1. It belongs to a board or component.
2. Its owning board or component has a non-empty customId.
3. The attribute has a non-empty customId.
4. Its value is boolean, integer, float, or string with plain: true.

Rich-text strings, component lists, and asset lists remain regular attributes; they are not Arcscript variables.

{
  "customId": "display_name",
  "cType": "components",
  "cId": "hero-component-uuid",
  "value": {
    "type": "string",
    "data": "Ada",
    "plain": true
  }
}

If the component has customId: "hero", the corresponding Arcscript name is hero.display_name.

Updating a custom JSON integration

A compatible loader should inspect two top-level sources:

1. The variables object, which contains global variables and, in pre-5.11 exports, board variables. Skip root and folder records.
2. The attributes object, which contains eligible scoped variables in 5.11 and later.

For a transition period, we recommend accepting the old board-variable shape as well as the new attribute-backed shape. This lets a project load exports created on either side of the release.

In language-independent terms, the loader should:

variables = empty collection

for each (id, variable) in project.variables:
    skip it if it has a root or children field

    if variable.cType is global or missing:
        variables.add(id, variable.name, normalize(variable.type, variable.value))
        continue

    if variable.cType is boards:
        resolve the board through variable.cId
        skip it unless board.customId is present

        scriptName = board.customId + "." + variable.name
        variables.add(id, scriptName, normalize(variable.type, variable.value))

for each (id, attribute) in project.attributes:
    skip it unless its owner type is boards or components
    skip it unless it is boolean, integer, float, or a plain string
    resolve the owner through attribute.cType and attribute.cId
    skip it unless both owner.customId and attribute.customId are present

    scriptName = owner.customId + "." + attribute.customId
    defaultValue = normalize(attribute.value.type, attribute.value.data)
    variables.add(id, scriptName, defaultValue)

Normalize null plain strings to "". Do not use truthiness to decide whether a value exists: false and numeric zero are valid defaults.

If your models mirror the export structure, also retain:

• board.attributes;
• component.customId;
• attribute.customId; and
• the attribute's stable ID from its key in the attributes object.

Official engine plugins

Use a plugin version compatible with Arcweave 5.11 and generate a fresh export after updating it.

The updated plugins use stable IDs when reporting variable changes and saving runtime state. If game code reads these dictionaries directly or stores them externally, update and test that code before shipping. Back up existing saves first, and do not assume that every legacy scoped-variable save can be mapped by name without knowing its owning scope.

Recommended verification

Test migration on a copy of the project and keep a last-known-good export. Verify all of the following before updating a production build:

• Every previous board variable has a corresponding board attribute.
• Its stable object key, type, value, board ownership, and script-visible name are preserved.
• Global variables still load from variables.
• Conditions using scoped variables select the expected branches.
• Assignments and inline show(...) expressions update correctly.
• reset(...) and resetAll(...) restore the authored defaults.
• Boolean false and numeric zero are not treated as missing; for migrated empty-string board defaults, verify the known null issue described above.
• Existing save games load with the intended values.
• Runtime variable-change notifications use the keys expected by game code.

Rollback and deadline-sensitive projects

Arcweave is a hosted application and does not currently offer a per-project switch to an older editor version. Reverting an editor build alone is also not safe after project data has been migrated to the new representation.

If an upcoming milestone prevents an immediate integration update, contact the Arcweave team on our Discord server or send us a Support request email. Provide:

• the Arcweave project hash;
• a last-known-good export (if available);
• a current export;
• the integration repository or relevant parser code;
• the engine and runtime versions; and
• the complete error output or failing script example.

We can then verify the data migration and help produce a targeted integration guide. Avoid manually recreating variables before that comparison, because doing so can make stable ID and save-state recovery harder.

Going forward

Export formats are production APIs. Future breaking JSON changes will ship under an explicit schema or API version, with advance notice, example fixtures, a compatibility period, and migration documentation published before the change becomes the default.

For additional reference, see the Arcweave variables documentation, attributes documentation, and the integration guides for Unity, Unreal Engine, and Godot.