Updating and Migration

Export

Use this guide to update an existing Behavior Designer Pro project or adopt Behavior Designer Pro alongside the original Behavior Designer. The safest path is a staged migration with a recoverable baseline, a clean core-package checkpoint, and separate verification passes for graphs, custom Tasks, builds, add-ons, and integrations.

Behavior Designer and Behavior Designer Pro can coexist in the same Unity project. They use separate GUIDs, namespaces, editor data, and runtime data, so an existing project can leave stable Behavior Designer trees in place while new or performance-sensitive behavior moves to Behavior Designer Pro.

Behavior trees are not automatically converted between the products. Their serialized graphs and runtime implementations differ. Treat adopting Pro as a deliberate graph migration, not as an in-place package replacement.

Choose the migration you are performing

Starting point Recommended route
An earlier Behavior Designer Pro 3 release Update the core package on a recoverable branch, verify it alone, then update samples, add-ons, and integrations.
Original Behavior Designer in a mature project Install Pro alongside the original package and migrate one tree at a time. Keep the original component and graph until the Pro replacement passes the same tests.
Original Behavior Designer in a small or early project Rebuild the graphs in Pro, then port project-owned Tasks and validate the complete replacement before removing the original package.
A project moving to a newer Unity editor at the same time Separate the changes when possible. First establish a working product baseline, then change either Unity or Behavior Designer Pro so a failure has one likely cause.

The Version Comparison covers architecture, platform, and feature differences. Custom Task Migration maps the original Task API to the Pro API.

Record a recoverable baseline

  1. Commit or back up the complete Unity project, including Packages, ProjectSettings, graph assets, prefabs, scenes, project-owned Tasks, and any imported integration or add-on files.
  2. Record the Unity editor version and the installed versions of Behavior Designer, Behavior Designer Pro, Graph Designer, Opsive Shared, add-ons, integrations, and the Entities packages.
  3. Open the project before changing packages. Confirm that scripts compile, representative trees run, and a development build succeeds.
  4. Save screenshots or notes for critical Shared Variable assignments, Subtree overrides, component references, and expected runtime branches.
  5. Perform the migration in a project copy or source-control branch. Do not use the only copy of a production graph as the test asset.

This baseline is the rollback point and the comparison target. A backup created after a partial import is not a clean baseline.

Update Behavior Designer Pro 3

  1. Confirm that the Unity version is supported. Behavior Designer Pro requires Unity 2022.3.11 or newer. For Unity 6.3, use 6.3.5 or newer; Unity 6.3.0 through 6.3.4 cannot load the editor assembly correctly.
  2. Resolve existing compiler errors before importing or changing the package. The GRAPH_DESIGNER scripting symbol is added automatically only when the editor can compile.
  3. Update the Behavior Designer Pro core package and its required Opsive dependencies without importing optional add-ons, integrations, or samples in the same step.
  4. Let Unity finish compiling. Open Tools > Opsive > Behavior Designer > Editor, create a disposable tree, and reopen one existing tree.
  5. If the product exposes Tools > Opsive > Behavior Designer > Upgrade Project Serialization, commit or back up first, run it once, then review and save the resulting asset changes before continuing.
  6. Open Tools > Opsive > Behavior Designer > Samples. Use Update Samples when the project contains sample content from an older Pro version; do not use an old sample folder as production content.
  7. Update add-ons and integrations to releases intended for the installed Pro version. Add them one at a time and compile after each import.
  8. Run the editor, Play Mode, and build checkpoints below before merging the update.

If the core package does not pass step 4, stop before adding optional content. Use Import Errors to resolve the compiler or Unity-version boundary first.

Adopt Pro alongside the original Behavior Designer

The two products are intentionally separate. Installing Pro does not rewrite original Behavior Designer components, trees, variables, preferences, or runtime state.

For an incremental migration:

  1. Keep the original Behavior Designer package and the existing tree on its current component.
  2. Install Behavior Designer Pro and create a new Pro Behavior Tree on a disposable or duplicated agent.
  3. Rebuild one representative graph. Recreate its Shared Variables, Subtrees, conditional-abort behavior, and event flow instead of copying serialized graph data.
  4. Port only the custom Tasks that graph requires. Follow Custom Task Migration for namespaces, attributes, generic Shared Variables, and lifecycle method changes.
  5. Run the old and new implementations against the same scenario and compare their observable decisions, transitions, and side effects.
  6. Move the Pro implementation onto the production agent only after it passes. Keep the original graph available for rollback until the complete feature is accepted.
  7. Repeat by feature or agent. Remove the original package only when no scene, prefab, script, add-on, integration, or build target depends on it.

This route avoids an all-at-once graph rewrite. It also makes performance comparisons meaningful because each migrated behavior has an original baseline.

Review serialized references after an update

Unity can preserve a serialized reference only while the receiving field remains compatible. When a release changes a Task field from a specific component type to a GameObject, or otherwise changes its serialized type, inspect that Task and reassign the intended object. Do not assume a graph that compiles retained every Inspector reference.

Review at least:

  • Task fields that reference components, GameObjects, assets, or project-owned types;
  • Shared Variable names, value types, scope, Internal state, and task assignments;
  • Subtree assets and their parent-tree overrides;
  • Start connections, conditional aborts, event branches, disabled Tasks, and Task delegates;
  • custom Task scripts and Control Types; and
  • add-on and integration Tasks that came from a separately downloaded package.

Open the Error Window after the serialization review. A graph with no compiler errors can still contain an unknown Task, a missing field assignment, or an invalid connection.

Verify the migration

Editor checkpoint

  1. Restart Unity so the test includes a fresh domain reload.
  2. Open a new graph, an existing graph, and a Subtree used by more than one agent.
  3. Create, rename, reorder, assign, and delete a disposable Shared Variable. Save, close, and reopen the project and confirm that its name, type, scope, and task assignment persist.
  4. Open the Error Window and resolve every new graph error.
  5. Save the project and review the source-control diff. Expect intentional package and serialization changes; investigate unrelated prefab, scene, or graph churn.

Play Mode checkpoint

  1. Run a small tree and one production-sized tree.
  2. Confirm that the expected branch runs, conditional aborts reevaluate, events arrive once, and Subtree overrides use the intended values.
  3. Test at least two agents that share the same Subtree asset. Graph-scoped runtime values should remain local to each Behavior Tree component.
  4. Exercise stop, disable, re-enable, scene change, pooling, and save/load flows used by the project.
  5. Profile the representative scenario before and after the migration instead of assuming a package update changed performance in one direction.

Build checkpoint

  1. Make a development build for every supported backend or platform affected by Burst, Entities, managed stripping, or platform-specific integrations.
  2. Start the build outside the editor and run the same representative behavior.
  3. Treat a successful editor Play Mode run and a successful player build as separate requirements.

Behavior Designer Pro does not support WebGL because of its Burst-based runtime. Keep an original Behavior Designer implementation or choose another supported runtime when WebGL remains a project requirement.

Troubleshooting

Symptom Check Fix
Add-on scripts cannot find Behavior Tree types and GRAPH_DESIGNER is missing The project had compiler errors when the core package or add-on was imported Remove or isolate the optional add-on, fix the first compiler error, and let the core package add the symbol. Add the symbol manually only after confirming that the core packages are present.
Opening or interacting with the graph throws an EventModifiers TypeLoadException Unity is 6.3.0 through 6.3.4 Update Unity 6.3 to 6.3.5 or newer. See Import Errors.
Existing graphs open but some Task references are empty A serialized field type changed or an optional Task package is missing Restore the matching add-on or integration, then reassign fields whose new type is not serialization-compatible with the old field.
The editor works until samples, an add-on, or an integration is imported Optional content targets a different product release or has an unmet dependency Return to the clean core checkpoint and import a matching release only after its dependencies compile.
An original Behavior Designer graph does not appear in Pro The products use different graph formats and do not auto-convert Keep the original package while rebuilding the graph in Pro. Port project-owned Tasks separately.
Shared Variable names or assignments do not survive reopening Confirm the installed Pro version, whether a Subtree is assigned, and whether the asset remains reproducibly affected after restart Update to the current release, preserve the affected graph or Subtree in version control, and send the smallest reproducible asset to support rather than rebuilding the only copy.
Two agents appear to share a Graph variable through a Subtree Runtime ownership and pooling setup Assign the same Subtree asset directly to separate Behavior Tree components. If using the pooling API, give every concurrently running component its own deserialized pooled instance. See Scope and Subtrees.
A player build fails although the editor runs Build-only assembly, stripping, Burst, Entities, or platform restrictions Diagnose the first build error, verify the target platform is supported, and retest with optional integrations removed from the checkpoint.
  • Import Errors covers the scripting-symbol and Unity 6.3 assembly failures.
  • Custom Task Migration ports original Behavior Designer Tasks to Pro.
  • Version Comparison compares requirements, architecture, platforms, and features.
  • Scope explains runtime ownership and the Graph, GameObject, Scene, Project, Internal, and Dynamic choices.
  • Subtrees covers direct asset reuse, variable overrides, reevaluation, and pooling.
  • Debugging traces graph validation and runtime execution problems.