Conversion
The exact set of type conversions a binding accepts, and what happens to everything outside it.
On this page
Bind compatible values directly to node parameters without adding a conversion node. The editor shows which direction works before you press Play.
The problem
Section titled “The problem”Dungeon Heist’s guard holds its alarm as an enum, but the graph needs its numeric tier and the HUD needs its name. Copying those values by hand would leave the guard looking calm while the alarm is Wary.
The binding resolves the declared types while you author. A pair outside the accepted catalog fails graph build with a named reason instead of losing part of a value.
When to reach for it
Section titled “When to reach for it”- Dungeon Heist’s Guard_2 reads
Alarms.Levelas aninttier and writes its enum name to astringcaption. - The guard reads an
AlarmLevelProfileinto afloatspeed multiplier through a project-registered converter. - A
Vector2value can feed aVector3parameter with Z set to zero, while aVector3cannot feed aVector2parameter without dropping Z.
See it
Section titled “See it”


The accepted set
Section titled “The accepted set”| Conversion | Example | Two-way eligibility |
|---|---|---|
| Identical declared types | float into float |
Yes; no conversion marker |
| Implicit numeric widening | int into float |
No; the reverse narrows |
| Enum and its exact underlying integral type | AlarmLevel into its underlying int, or back |
Yes, when both ends are that exact pair |
| Reference assignment to a base class or implemented interface | Rigidbody into Component; an ordinary argument’s List<IGuardActor> into IEnumerable<IGuardActor> |
No, unless the pair is identical; collection element types are not converted |
| List to matching array where the parameter admits it | List<Vector2> into Vector2[] |
No; into the member only |
Vector2 into Vector3 |
X and Y retained, Z set to zero | No |
Quaternion into Vector3 |
Euler angles from the rotation | No, even though the reverse resolves |
Vector3 into Quaternion |
Quaternion.Euler on the angle vector |
No, even though the reverse resolves |
GameObject into an attached Component |
Find the component of the declared type | No, except the Transform pair below |
Component into its GameObject or Transform |
The owning object or transform | No, except the Transform pair below |
GameObject and its Transform |
Each identifies exactly the other | Yes, in either direction |
GameObject or Component into an implemented interface |
Find a matching attached component | No |
GameObject or Component into Vector3 or Quaternion |
World position or world rotation | No |
Boolean, integral, char, float, double, or enum into string |
AlarmLevel.Wary into Wary |
No; formatting is one-way |
| Project-registered converter | AlarmLevelProfile into float |
Only an explicit RegisterTwoWay pair |
Widening follows C# exactly: sbyte to short, int, long, float, double; byte to short, ushort, int, uint, long, ulong, float, double; short to int, long, float, double; ushort to int, uint, long, ulong, float, double; int to long, float, double; uint to long, ulong, float, double; long and ulong to float, double; char to ushort, int, uint, long, ulong, float, double; float to double.
String formatting uses culture-invariant text for every admitted scalar or enum. An unchanged value reuses its formatted string; a changed value materializes one new string. For a custom pair, implement IBehaviorMemberConverterProvider and register public static converter methods with BehaviorMemberConverterRegistry.RegisterOneWay or RegisterTwoWay. The guard’s sample chapter shows the one-way profile example.
What is refused
Section titled “What is refused”- Numeric narrowing, including
floattointandlongtoint. Vector3intoVector2: dropping Z is lossy. NodeCanvas lists that cast; this editor rejects it at build time and names the binding and both types.- One enum for another, and an enum to an integral type other than its own underlying type.
- Downcasts and user-defined conversion operators;
Convertcoercions and unregistered pairs. - Boxing or unboxing; nullable wrapping.
UnityEngine.Vector3intoUnity.Mathematics.float3. The built-in geometry pairs above use specific declared UnityEngine types; similar struct layouts do not create a general conversion.- Per-element collection conversions, changed dictionary key/value identities, and list-to-array conversion outside the explicit matching-collection parameter case. A CLR-safe ordinary reference upcast passes the existing object and is not an element conversion.
- Conversion on an index argument of an indexed property; supply its exact type.

Direction and indicator
Section titled “Direction and indicator”A variable into a member needs its declared type to reach the member’s declared type. A member into a variable needs the reverse direction. two-way requires an explicitly lossless pair in both directions. That can be identical types, an enum paired with its exact underlying integral type, a GameObject paired with its own Transform, or a project pair registered with RegisterTwoWay. Two independent one-way registrations do not make a pair two-way.
The collection reference-upcast rule applies to ordinary by-value argument reads only. ref and in collection inputs, collection outputs/write-back, and two-way collection bindings keep their exact declared types. An index or dictionary key retains its own exact contract. A readable interface does not make a different collection type a valid write destination.
In Member bindings and the selected node’s binding rail, a converted row says converts when its pair can also be bound two-way, one-way when only the authored direction qualifies, or both ways when a converted pair is actually bound two-way. The row names both types; a registered converter also shows project and names the method in its tooltip. Direction still shows two-way for an identical-type binding, but that binding has no conversion indicator.
-
Open
Assets/_Project/Behavior/Guard2.bqbehaviorin Window > Behavior & State > Behavior Tree Editor. Keep the toolbar on Static and select graph home with no node selected. -
In Blackboard > Member bindings, expand
alarm_tier. TheAlarms.Levelread says converts fromAlarmLeveltoint: that enum can also convert back from its own underlying type. -
Expand the second
alarm_caption_sourcerow, the writer toGuardBehaviorActor.AlarmCaption. It says one-way fromAlarmLeveltostring. Then expandalarm_speed_multiplierto see one-way,AlarmLevelProfiletofloat, and the project chip. -
Expand
alarmTierOverride. It binds theintvariablealarmTierOverridetwo-way to Guard_2’sAlarmLevelmemberGuardBehaviorActor.AlarmTierOverride, so it says both ways ·intandAlarmLevel. ExpandpatrolSpeed: it shows TWO-WAY direction but no conversion marker because both ends arefloat. Press Play and select Guard_2: set Alarm Tier Override toLockdownin the Inspector and the LivealarmTierOverriderow reads2; type1into that row’s Current value and the Inspector showsWary. When the alarm becomes Wary, the graph’s tier and the HUD caption change together.
How it decides
Section titled “How it decides”- Conversion is selected from both ends’ declared types during validation and bake. An unsupported or ambiguous pair names the binding and both types, and the graph does not build.
- Constants are converted and range-checked during bake:
bool, signed and unsigned integrals includingchar, finitefloatanddouble, an enum by member name or its exact underlying literal, andnullfor a reference. - Generated call sites dispatch the selected conversion through generated code and compiled runtime helpers; the project converter is a direct static call. No runtime converter-table lookup or reflection is added per tick. String formatting is revision-gated so an unchanged value is not formatted again.
- The entity path accepts only its carried value kinds. Geometry and extraction use types that path does not carry, as does the new string family; registered custom converters can run there when both declared kinds are entity-supported and the converter is valid for that backend.
When it goes wrong
Section titled “When it goes wrong”When it goes wrong
| Symptom | Check | Fix |
|---|---|---|
| The variable you want is missing from a Blackboard source list. | Compare its declared type with the parameter type. | Declare the type the member uses, or add an overload that takes what you have. |
| Two-way is refused on a pair that works one way. | Check whether the pair is explicitly reversible, rather than checking only whether both directions resolve. | Use an identical type, the exact enum-underlying or GameObject-Transform pair, or RegisterTwoWay for a genuinely reversible project converter. Otherwise use one-way bindings. |
| A float3 member refuses a Vector3 variable. | These are two different declared CLR struct types. | Declare the exact type the member uses, or register a safe converter in your project. |
| An enum variable will not bind to a differently sized integer. | Only the enum and its own underlying type convert. | Declare the underlying type of that enum, or expose the member with the enum type. |
| Your implicit operator is ignored. | User-defined operators are outside the built-in catalog. | Register a deterministic converter, or expose a member using the type you already have. |
| An indexer index is refused even though it would widen. | Index arguments take no conversion at all. | Supply the exact index type. |
- Property and field: choose the direction and see how a two-way binding updates.
- Dungeon Heist: inspect the guard’s enum and string rows, then its project conversion.
- Arguments and results: where converted values enter and leave a node.
- Entity variables: which kinds the entity path carries.
- Member nodes and bindings: where these conversions are applied, card by card.