Skip to content
Bit Quirky Behavior Trees and
State Machines

Search documentation

All topics and APIs

Close returns focus to Search.

What are you looking for?

Try a common topic or enter a complete API identifier.

Browse the reference instead

Esc closes · Tab reaches results · Enter opens the focused link

v0.11.0
Menu

Conversion

The exact set of type conversions a binding accepts, and what happens to everything outside it.

Bind compatible values directly to node parameters without adding a conversion node. The editor shows which direction works before you press Play.

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.

  • Dungeon Heist’s Guard_2 reads Alarms.Level as an int tier and writes its enum name to a string caption.
  • The guard reads an AlarmLevelProfile into a float speed multiplier through a project-registered converter.
  • A Vector2 value can feed a Vector3 parameter with Z set to zero, while a Vector3 cannot feed a Vector2 parameter without dropping Z.
Guard_2’s alarm tier row says converts from AlarmLevel to int.
Figure 1. The Member bindings row names the converted types before Play Mode.
The guard’s caption source and writer are distinct rows; the writer says one-way from AlarmLevel to string.
Figure 2. The caption can go into the HUD, but a string cannot turn back into the alarm enum.
The profile-to-float row says one-way and carries a project chip.
Figure 3. The profile converter comes from the Dungeon Heist project, not the built-in catalog.
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.

  • Numeric narrowing, including float to int and long to int.
  • Vector3 into Vector2: 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; Convert coercions and unregistered pairs.
  • Boxing or unboxing; nullable wrapping.
  • UnityEngine.Vector3 into Unity.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.
The member picker lists methods and notes that members breaking the binding contract are set aside at the end of the list.
Figure 4. The picker explains where to find members ruled out by the binding contract; this view does not show the unavailable entries themselves.

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.

  1. Open Assets/_Project/Behavior/Guard2.bqbehavior in Window > Behavior & State > Behavior Tree Editor. Keep the toolbar on Static and select graph home with no node selected.

  2. In Blackboard > Member bindings, expand alarm_tier. The Alarms.Level read says converts from AlarmLevel to int: that enum can also convert back from its own underlying type.

  3. Expand the second alarm_caption_source row, the writer to GuardBehaviorActor.AlarmCaption. It says one-way from AlarmLevel to string. Then expand alarm_speed_multiplier to see one-way, AlarmLevelProfile to float, and the project chip.

  4. Expand alarmTierOverride. It binds the int variable alarmTierOverride two-way to Guard_2’s AlarmLevel member GuardBehaviorActor.AlarmTierOverride, so it says both ways · int and AlarmLevel. Expand patrolSpeed: it shows TWO-WAY direction but no conversion marker because both ends are float. Press Play and select Guard_2: set Alarm Tier Override to Lockdown in the Inspector and the Live alarmTierOverride row reads 2; type 1 into that row’s Current value and the Inspector shows Wary. When the alarm becomes Wary, the graph’s tier and the HUD caption change together.

  • 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 including char, finite float and double, an enum by member name or its exact underlying literal, and null for 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

SymptomCheckFix
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.
Full-size image