> ## Content Index > Fetch the complete content index at: https://blog.arcweave.com/llms.txt > Use this file to discover other available public pages before exploring further. # Arcweave scoped variables: game-engine migration guide - URL: https://blog.arcweave.com/scoped-variables-in-arcweave-migration-guide/ - Published: 2026-09-03T08:31:34.000Z - Updated: 2026-09-18T06:59:39.000Z - Description: Learn how Arcweave’s scoped variables affect Unity, Unreal Engine, Godot, exported JSON, and custom integrations—and how to migrate safely. - Author: Manos Kalaitzoglou - Tags: news, features ## Board and component variables are now first-class Arcweave data Arcweave 5.11.0, 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. ## Key takeaways - Arcweave 5.11.0 moves board-scoped variables into the attributes data model and adds component-scoped variables, affecting custom JSON integrations. - Update loaders to read global variables from variables and scoped variables from attributes, preserving stable IDs, ownership, names, types, and values. - Use compatible engine plugins, generate a fresh export, and verify conditions, assignments, display expressions, and resets before relying on the updated integration. **Updated documentation:** [Variables overview](https://docs.arcweave.com/project-items/variables/overview?ref=blog.arcweave.com), [board variables](https://docs.arcweave.com/project-items/variables/board?ref=blog.arcweave.com), [component variables](https://docs.arcweave.com/project-items/variables/component?ref=blog.arcweave.com), [attributes](https://docs.arcweave.com/project-items/attributes?ref=blog.arcweave.com), and the [current JSON export structure](https://docs.arcweave.com/integrations/json?ref=blog.arcweave.com#attributes). **Engine and runtime guides:** [Unity](https://docs.arcweave.com/integrations/unity?ref=blog.arcweave.com#scoped-variables), [Unreal Engine](https://docs.arcweave.com/integrations/unreal?ref=blog.arcweave.com#scoped-variables), [Godot](https://docs.arcweave.com/integrations/godot?ref=blog.arcweave.com#scoped-variables), and [custom Arcscript interpreters](https://docs.arcweave.com/integrations/arcscript-interpreters?ref=blog.arcweave.com#variable-scopes-and-runtime-state). ## 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. ## Summary of the change Before 5.11.0, 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; 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.0 ``` { "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.0 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 | Before 5.11.0 | From 5.11.0 | Notes | | --------------------- | --------------------------------------------------- | ----------------------------------------------- | | board.variables | board.attributes | The array still contains stable IDs. | | variables\[id\].name | attributes\[id\].name and attributes\[id\].customId | customId is used as the Arcscript member name. | | variables\[id\].type | attributes\[id\].value.type | Supported variable types are unchanged. | | variables\[id\].value | attributes\[id\].value.data | Plain empty strings may be represented as null. | | variables\[id\].cType | attributes\[id\].cType | boards or components for scoped values. | | variables\[id\].cId | attributes\[id\].cId | The owning board or component UUID. | ## 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.0 exports, board variables. Skip root and folder records. 2. The `attributes` object, which contains eligible scoped variables in 5.11.0 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.0 and generate a fresh export after updating it. | Integration | Compatible release | Required action | | ---------------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------- | | [Unity](https://github.com/Arcweave/arcweave-unity-plugin?ref=blog.arcweave.com) | 3.0.0 or later | Recreate imported project assets and test existing runtime variable saves. | | [Godot](https://github.com/Arcweave/arcweave-godot-plugin?ref=blog.arcweave.com) | 3.0.0 or later | Replace the complete plugin directory, rebuild the C# project, and reinitialize the Arcweave asset. | | [Unreal](https://github.com/Arcweave/arcweave-unreal-plugin?ref=blog.arcweave.com) | 2.0.0 or later | Update the plugin, headers, and bundled native libraries together. | 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 - 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](https://discord.gg/atVXxAK?ref=blog.arcweave.com) or send us a [Support request ](https://arcweave.com/contact?ref=blog.arcweave.com)email. Provide: - the Arcweave project hash; - a last-known-good JSON export (if available); - 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. ## Going forward Export formats are production APIs. Future breaking JSON changes will ship with advance notice, a compatibility period, and migration documentation published before the change becomes the default. For additional reference, see the following: - [Arcweave variables documentation](https://docs.arcweave.com/project-items/variables/overview?ref=blog.arcweave.com) - [Attributes documentation](https://docs.arcweave.com/project-items/attributes?ref=blog.arcweave.com) - Integration guides for [Unity](https://docs.arcweave.com/integrations/unity?ref=blog.arcweave.com), [Unreal Engine](https://docs.arcweave.com/integrations/unreal?ref=blog.arcweave.com), and [Godot](https://docs.arcweave.com/integrations/godot?ref=blog.arcweave.com)