> For the complete documentation index, see [llms.txt](https://postica.gitbook.io/binding-system-3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://postica.gitbook.io/binding-system-3/getting-started/upgrading.md).

# Upgrading from Binding System 2

What changes, what does not, and what to check after the update.

## The short version

Your bindings survive. `Bind<T>` and its variants, the bind data format, converters, modifiers and custom extensions all carry over. The upgrade is mostly about the editor: new tools, a redesigned settings page, and a few defaults worth reviewing.

{% hint style="warning" %}
**Back up, or commit, before updating.** The upgrade runs migration hooks that move files on disk. It is well behaved, but a clean point to return to costs nothing.
{% endhint %}

## Before you start

1. **Unity 6000.0 or newer is required.** There is no path around this. If the project cannot move editor version yet, stay on 2.x.
2. Make sure asset serialization is set to **Force Text** (**Project Settings ▸ Editor ▸ Asset Serialization**). Several of the new project-wide tools read YAML directly.
3. Note down your current 2.x settings. The settings page is reorganised and a few options are gone.

## What happens on the first launch

The upgrade runs automatically, once, driven by the version stored in `Library/`.

<table><thead><tr><th width="290">Step</th><th>What happens</th></tr></thead><tbody><tr><td>Migration hooks run</td><td>Any method marked <code>[OnBindSystemUpgrade]</code> is called with the version you came from. The package uses these to move its own data, for example relocating a <code>Assets/Bindings</code> folder left over from 2.2.4 or earlier into the package.</td></tr><tr><td>Converters and modifiers re-register</td><td>Your custom converters and modifiers are rescanned and re-registered.</td></tr><tr><td>The welcome screen opens</td><td>In its <strong>What's New</strong> state, with the two default questions described in <a href="/binding-system-3/getting-started/welcome-screen.md">The Welcome Screen</a>.</td></tr></tbody></table>

Expect the first compilation and the first import after the update to take longer than usual. The databases behind the dependency and refactoring tools are being built.

## What is new

Nothing here is required. Every item is optional, and a project that ignores all of it behaves like 2.x on a newer editor.

<table><thead><tr><th width="270">Feature</th><th>What it does</th></tr></thead><tbody><tr><td><a href="/binding-system-3/overview/ui-toolkit.md">Bindings for UI Toolkit</a></td><td>Bind the properties, inline styles and USS classes of UXML elements from UI Builder. The binding is stored on the scene or in the asset.</td></tr><tr><td><a href="/binding-system-3/overview/paths.md#methods-in-the-bind-path-menu">Method binding</a></td><td>A path can call a method or an indexer, not only read a field or a property. Every argument can itself be a binding.</td></tr><tr><td><a href="/binding-system-3/overview/sources.md">Source modes</a></td><td>A source can be named by variable, name or path, tag, pattern, context, scene search or static type, instead of only by direct reference.</td></tr><tr><td><a href="/binding-system-3/overview/bind-variables.md">Bind variables</a></td><td>Named values in a scene component or a project asset, usable as the source of any binding.</td></tr><tr><td><a href="/binding-system-3/project-tools/diagnostics.md">Better project-wide diagnostics</a></td><td>The <a href="/binding-system-3/project-tools/diagnostics/bindings-monitor.md">Bindings Monitor</a> and the dependency window were already in 2.x. Added here: the <a href="/binding-system-3/project-tools/diagnostics/dependency-graph.md">dependency graph</a>, the <a href="/binding-system-3/project-tools/diagnostics/validator.md">validator</a>, and a read of the serialized data rather than of loaded objects, so the whole project is covered without opening it.</td></tr><tr><td><a href="/binding-system-3/project-tools/performance/optimized-accessors.md">Generated accessors</a></td><td>At build time, the paths your project binds are turned into generated direct-access code.</td></tr><tr><td><a href="/binding-system-3/overview/micro-ui.md">Micro UI</a></td><td>A bound field can keep its own control, showing the value the binding produces, with only the hexagon beside it. Its centre lights green or red for the value shown, and the whole binding opens in a popup.</td></tr><tr><td><a href="/binding-system-3/overview/binding.md#editing-several-bindings-at-once">Bulk editing of binding lists</a></td><td>Edit one binding in a list, or on one of several selected objects, and have the change repeated on the others that match.</td></tr><tr><td><a href="/binding-system-3/overview/binding.md#the-bind-path-menu">Async search and member loading</a></td><td>The bind path menu fills its groups and runs its search in the background, so it opens immediately even on types with very large member trees.</td></tr></tbody></table>

## What changed

### The Inspector UI

In 2.x, the UI Toolkit drawer was an option called **Minimal UI**. In 3.x it is simply the drawer. The old IMGUI path still exists as a fallback for inspectors that are not built on UI Toolkit, but it is not something you choose any more, and the setting is gone.

Two settings that used to say "requires Minimal UI" now just work: [Source Replacement](/binding-system-3/reference/settings.md#visualization) and [Realtime Debug](/binding-system-3/project-tools/diagnostics/live-debug.md#realtime-debug).

### The settings page

Rebuilt, and reorganised into five sections: **Language**, **Visualization**, **Optimization**, **Configuration** and **Tools**. Everything that makes the system *show* something extra now lives in one place, the [Visualization panel](/binding-system-3/reference/settings.md#visualization), instead of being scattered across the sections that own each feature.

<table><thead><tr><th width="300">2.x setting</th><th>3.x</th></tr></thead><tbody><tr><td>Minimal UI</td><td>Gone. The UI Toolkit drawer is the default.</td></tr><tr><td>Show Implicit Converters</td><td>Gone. Implicit conversions are resolved without being listed.</td></tr><tr><td>Show Incompatible Modifiers</td><td>Gone. Incompatible modifiers are not offered.</td></tr><tr><td>Show Target Replacement</td><td>Now <strong>Visualization ▸ Source Replacement</strong>.</td></tr><tr><td>Optimization + Auto Apply Optimization</td><td>Replaced by <a href="/binding-system-3/project-tools/performance/optimized-accessors.md">Build-Time Optimized Accessors</a>, which is scoped, inspectable and off by default.</td></tr><tr><td>Build All AOT Code</td><td>Gone. Not needed on Unity 6000.</td></tr><tr><td>Auto Conversion</td><td>The <a href="/binding-system-3/project-tools/diagnostics/reserializer.md">Reserializer</a> is still in the package but is off by default and its toggle is hidden. See that page for how to enable it.</td></tr></tbody></table>

### The splash screen

Replaced by the [welcome screen](/binding-system-3/getting-started/welcome-screen.md). The two questions the old splash asked on every 2.x upgrade are now asked once and recorded.

## After the upgrade: a short checklist

1. **Open a scene with bindings and look at a few.** They should draw normally, with no red fields. If something is red, [Error Visualization](/binding-system-3/project-tools/diagnostics/errors.md) says what it is missing.
2. **Run the** [**Bindings Dependencies**](/binding-system-3/project-tools/diagnostics/dependencies.md) **window.** It lists every serialized bind in the project. Anything reported as unresolved is worth looking at before you ship.
3. **Answer the two welcome questions** rather than dismissing them. [Phased bindings](/binding-system-3/project-tools/performance/phased-bindings.md) in particular are worth having on.
4. **Decide about** [**optimized accessors**](/binding-system-3/project-tools/performance/optimized-accessors.md)**.** Off by default. If your project has many deep paths in built scenes, turning it on collapses each one into a single generated call.
5. **Review the** [**Visualization panel**](/binding-system-3/reference/settings.md#visualization) if inspectors feel heavier than they used to. Also see [Performance Mode](/binding-system-3/project-tools/performance/performance-mode.md).

## Code compatibility

Public API from 2.x continues to work. The additions you may want to adopt:

```csharp
// New source modes and behaviour switches are expressed through BindFlags.
var data = new BindData(someTransform, "position.x", null, -1);
data.TryEnableFlag(BindFlags.AutoUpdate, true);

// Any object can now control its own bindings, if Universal Bind Control is on.
this.PauseAllBinds();
this.UpdateBind(nameof(speed));
this.ResumeAllBinds();
```

See [Binding from Code](/binding-system-3/overview/code.md) and [Controlling Bindings at Runtime](/binding-system-3/overview/runtime-control.md).

{% hint style="info" %}
Custom converters, modifiers, accessor providers and value providers written against 2.x need no changes. The interfaces are unchanged.
{% endhint %}