Behavior Tree Editor Nodes

This is a reference of all Behavior Tree nodes available in the BT editor

Leaf action nodes

Nodes with no children

Ship movement

Ship_Drift

Keep the ship moving at current velocity (and allow it to be affected by external influences)

InputTypeRequiredDefaultDescription
LookEntityId, PositionnoDirection for ship to point in

Outputs: none


Ship_FlyFlourishSpline

Fly a nav spline as a flourish. That is - copy the spline directly in front of the ship and fly that

InputTypeRequiredDefaultDescription
SplineEntityIdyes-The spline to fly
SpeedOverrideFloatno-1.00Speed to fly the spline at. This is read every frame while the spline is being flown. The default of -1 causes the spline to be flown at the usual speed
DisableAvoidanceBooleannofalseWhile flying this spline switch off collision avoidance

Outputs: none


Ship_FlySpline

Fly a nav spline

InputTypeRequiredDefaultDescription
SplineEntityIdyes-The spline to fly
StartAtNearestBooleannofalseWhether to start at the nearest point on the spline
AttackTargetsBooleannotrueIf true (default), fire on targets that are specified by the spline
AttackUsualTargetBooleannofalseIf true, face and fire at the target selected by the usual target selector while flying the spline. If spline targets are specified and AttackTargets is true, this option will be overridden while going past those specific points
SpeedOverrideFloatno-1.00Speed to fly the spline at. This is read every frame while the spline is being flown. The default of -1 causes the spline to be flown at the usual speed
ErrorLimitFloatno-1.00Maximum distance the entity may be away from the spline. If this distance is exceeded then the entity’s position is overridden. Negative for no limit (default), otherwise must be >= 1m
TeleportToStartBooleannofalseInstead of flying to the start of the spline, immediately teleport the ship there
AvoidanceModeStringHashno“Normal”While flying this spline what type of collision avoidance to do (Options: Off, Normal, Limited)
FailOnJoinFallbackBooleannofalseWhether to fail this node if joining falls back to use spline based method. This should normally be set to true when splines are picked systemically, to avoid collisions when the path to a systemically picked spline collides with something

Outputs: none


Ship_GetSplinePoint

Get a point from a spline

InputTypeRequiredDefaultDescription
SplineEntityIdyes-The spline to look up from
SplineIndexIntegeryes-Which point to look up
OutputTypeRequiredDescription
PointPosPositionyesPosition of spline point

Ship_Goto

Go straight to a destination. Destination is re-evaluated each update

InputTypeRequiredDefaultDescription
DestinationEntityId, Positionyes-Where to go to
AbsoluteSpeedFloatno0.00The speed to move at in m/s, RelativeSpeed is used if this is set to 0
RelativeSpeedFloatno1.00The proportion of maximum speed to move at (0.0 - 1.0)
EndDistanceFloatno0.00The minimum distance from the end point to complete at
AbsoluteSpeedAtDestinationFloatno0.00The absolute speed to be moving at when reaching target position in m/s. Defaults to using RelativeSpeedAtDestination. When going to an entity, this is ignored, instead the entity’s current speed is used
RelativeSpeedAtDestinationFloatno0.00The relative speed to be moving at when reaching target position (0.0 - 1.0). Defaults to stop. When going to an entity, this is ignored, instead the entity’s current speed is used
LookAtDestinationBooleannofalseWhether to set the look direction to be looking at the destination
LookTargetEntityId, PositionnoExplicit look target (optional)

Outputs: none


Ship_MaintainVel

Keep the ship moving at current velocity

InputTypeRequiredDefaultDescription
VelocityVelocityyes-The velocity for the ship to move at (read every frame)
LookEntityId, PositionnoDirection for ship to point in

Outputs: none


Ship_PathTo

Path to a destination. Destination is re-evaluated each update

InputTypeRequiredDefaultDescription
DestinationEntityId, Positionyes-Where to go to/path to follow
AbsoluteSpeedFloatno0.00The speed to move at in m/s, RelativeSpeed is used if this is set to 0
RelativeSpeedFloatno1.00The proportion of maximum speed to move at (0.0 - 1.0)
EndDistanceFloatno0.00The minimum distance from the end point to complete at
AbsoluteSpeedAtDestinationFloatno0.00The absolute speed to be moving at when reaching target position in m/s. Defaults to using RelativeSpeedAtDestination. When going to an entity, this is ignored, instead the entity’s current speed is used
RelativeSpeedAtDestinationFloatno0.00The relative speed to be moving at when reaching target position (0.0 - 1.0). Defaults to stop. When going to an entity, this is ignored, instead the entity’s current speed is used
LookTargetEntityId, PositionnoExplicit look target (optional)

Outputs: none


Ship_Roll

Roll the ship, normally executed in parallel with another movement node. Never completes

InputTypeRequiredDefaultDescription
RollRateFloatyes-Rotation rate in rad/sec

Outputs: none


Ship_Stop

Bring the entity to a complete stop

Inputs: none

Outputs: none


Ship_Track

Attempt to reach and maintain a given distance from a target entity. Target is only evaluated on entry

InputTypeRequiredDefaultDescription
TargetEntityId, Positionyes-The entity or position to track
MinAbsoluteSpeedFloatno0.00The minimum speed to move at while tracking in m/s, MinRelativeSpeed is used if this is set to 0
MinRelativeSpeedFloatno0.00The minimum proportion of top speed to move at while tracking (0.0 - 1.0)
MaxAbsoluteSpeedFloatno0.00The maximum speed to move at while tracking in m/s, MaxRelativeSpeed is used if this is set to 0
MaxRelativeSpeedFloatno1.00The maximum proportion of top speed to move at while tracking (0.0 - 1.0)
DistanceFloatyes-Distance to attempt to stay away from the target
LookAtDestinationBooleannofalseWhether to set the look direction to be looking at the destination

Outputs: none


Ship_TurnToTarget

Turn the ship to face a target. Reads target every frame until completes

InputTypeRequiredDefaultDescription
TargetEntityId, Positionyes-Either a target entity or a position for the ship to point at
MaintainDirectionBooleannofalseIf true, keeps a constant velocity and rotates to point at target. If false, keeps a constant speed but changes direction of velocity to point at target
ToleranceFloatno1.00Tolerance (in degrees) in the direction that must be reached before the node completes

Outputs: none


Character movement

Character_ExactGoto

Move to the given position and direction

InputTypeRequiredDefaultDescription
DestinationPositionyes-Where the character should go to
DirectionVectoryes-What direction the character should face in at the destination position
SpeedFloat, StringHashyes-The speed for the character to move at

Outputs: none


Character_Goto

Path find and goto destination

InputTypeRequiredDefaultDescription
DestinationEntityId, Positionyes-Where to go to
SpeedFloat, StringHashyes-The speed for the character to move at
EndDistanceFloatno0.00The distance from the end of the path to complete

Outputs: none


Character_GotoDirectness

Approach the given waypoint at a given directness

InputTypeRequiredDefaultDescription
DestinationEntityId, Positionyes-Position to approach
SpeedFloat, StringHashyes-The speed for the character to move at
EndDistanceFloatno1.00Distance from destination to complete
DirectnessFloatno1.00Directness of approach

Outputs: none


Character_GotoWaypoint

Pathfind to a given input. When nearly complete, redirect to a new waypoint if one has been given

InputTypeRequiredDefaultDescription
WaypointEntityId, Positionyes-The next waypoint to go to
SpeedFloat, StringHashyes-The speed for the character to move at
EndToleranceFloatno1.00At what distance from the current waypoint to read in the next waypoint
OutputTypeRequiredDescription
DistanceToWaypointFloatyesDistance to the current waypoint

Character_IsPointReachableNow

Succeed if there is a valid path from the start point/entity to the end point/entity, fail if not

InputTypeRequiredDefaultDescription
StartEntityId, PositionnoPosition/entity to start test from. Default is current AI position
EndEntityId, Positionyes-Position/entity to test to
ClampRadiusXYFloatno2.00The radius to clamp to on start and end points in XY plane
ClampRadiusZFloatno2.00The radius to clamp to on start and end points on Z axis
MaxPathLengthFloatnoThe maximum path length to test. Will default to 2x the distance from start to end positions

Outputs: none


Character_PathDistance

Get the length of the current path. Fails if there is no current path

Inputs: none

OutputTypeRequiredDescription
DistanceFloatyesThe distance from the end of the path to complete

Character_SteeringGoto

Let steering handle motion for this entity (from other input)

InputTypeRequiredDefaultDescription
SpeedFloat, StringHashyes-The speed for the character to move at

Outputs: none


Character_TurnToFace

Makes a character turn to face a direction or position

InputTypeRequiredDefaultDescription
GoalVector, EntityId, Positionyes-The position or direction or entity for the character to face
DirToleranceFloatno5.00The tolerance (in degrees) of the target direction
TurnRateFloatno0.00Optionally override the character turn rate, in degrees per second. Ignored if zero (or less)

Outputs: none


Character control

SetStance

Set the stance of a character

InputTypeRequiredDefaultDescription
StanceStringHashno“Stand”The stance to switch to
StrafingBooleannofalseWhether to allow strafing or not

Outputs: none


Conditional

CompareNow

Test a Lua script conditional expression. Can access entity, profile and behavior blackboards

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
ConditionStringHashyes-The expression to be evaluated. Must evaluate as a boolean (e.g. it could have multiple expressions with ands and ors, for example)

Outputs: none


EqualsNow

Test whether two inputs are equal (Lhs == Rhs)

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
LhsAnyyes-Left hand value to test
RhsAnyyes-Right hand value to test

Outputs: none


GreaterThanEqualsNow

Test whether one input is greater or equal to another (Lhs >= Rhs)

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
LhsInteger, Floatyes-Left hand value to test
RhsInteger, Floatyes-Right hand value to test

Outputs: none


GreaterThanNow

Test whether one input is greater than another (Lhs > Rhs)

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
LhsInteger, Floatyes-Left hand value to test
RhsInteger, Floatyes-Right hand value to test

Outputs: none


HasTagNow

Checks whether an entity has a particular tag

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
TagTagyes-The tag to test
EntityIdEntityIdyes-The id of the entity to test on

Outputs: none


HasVariableNow

Checks whether the named variable exists

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
NameStringHashyes-The variable name (or path) to check for

Outputs: none


IsInFrontNow

True if the given entity or position has a dot product with our current direction greater than the minimum specified

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
TargetEntityId, Positionyes-entity or position to test
MinDotProductFloatno0.00Minimum dot product for target to be considered ‘in front’

Outputs: none


IsInGroupNow

Checks whether an entity has membership of a particular group

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
EntityIdEntityIdyes-The id of the entity to test on
GroupIdEntityIdyes-The id of the entity to test on

Outputs: none


IsInRangeNow

True if the distance between two positions is within the given range

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
StartEntityId, Positionyes-Entity or position to test from
EndEntityId, Positionyes-Entity or position to check distance to
MinRangeFloatno0.00Minimum distance for check to pass (optional)
MaxRangeFloatnoMaximum distance for check to pass (optional)

Outputs: none


IsValidIDNow

True if the given entity ID is not empty and the entity exists

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
EntityIdEntityIdyes-Entity ID

Outputs: none


LessThanEqualsNow

Test whether one input is less or equal to another (Lhs <= Rhs)

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
LhsInteger, Floatyes-Left hand value to test
RhsInteger, Floatyes-Right hand value to test

Outputs: none


LessThanNow

Test whether one input is less than another (Lhs < Rhs)

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
LhsInteger, Floatyes-Left hand value to test
RhsInteger, Floatyes-Right hand value to test

Outputs: none


RandomChanceNow

True with a given probability

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
ProbabilityFloatyes-Probability of success (range 0-1)

Outputs: none


SignalHasParameterNow

True if the given signal contains a parameter with the given name

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
SignalBlackboardyes-The signal to query
ParameterNameStringyes-Name of the parameter to look for, this may be a path if the signal contains sub-blackboards

Outputs: none


TimeGreaterThanNow

Test whether more than a certain interval of time has passed since a timestamp. False if the timestamp isn’t set

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
TimestampTimestampyes-The timestamp of an event
IntervalFloatyes-Minimum time since the event

Outputs: none


TimeLessThanNow

Test whether less than a certain interval of time has passed since a timestamp. False if the timestamp isn’t set

InputTypeRequiredDefaultDescription
InvertBooleannofalseCheck for the opposite of the condition
TimestampTimestampyes-The timestamp of an event
IntervalFloatyes-Maximum time since the event

Outputs: none


Math

Add

Add two inputs together. The inputs must be of types that make sense to be added (int, float, vector)

InputTypeRequiredDefaultDescription
InputAInteger, Float, Vector, Position, Velocityyes-First input of any type
InputBInteger, Float, Vector, Position, Velocityyes-Second input of the same type as InputA
OutputTypeRequiredDescription
ResultAnyyesInputA + InputB

Divide

Divide one input by another. The numerator input must be a divisible type (int, float, vector). Denominator must a number (int, float)

InputTypeRequiredDefaultDescription
InputAInteger, Float, Vectoryes-InputA - Numerator input
InputBInteger, Floatyes-InputB - Denominator input
OutputTypeRequiredDescription
ResultAnyyesInputA/InputB

Dot

Calculate the dot product of two vectors

InputTypeRequiredDefaultDescription
InputAVectoryes-First vector
InputBVectoryes-Second vector
OutputTypeRequiredDescription
ResultFloatyesInputA . InputB

Length

Get the length of a vector or velocity

InputTypeRequiredDefaultDescription
VectorVector, Velocityyes-A vector or velocity
OutputTypeRequiredDescription
ResultFloatyesLength of the vector

Multiply

Multiply two inputs together. The inputs must of types that make sense to be multiplied (int, float, vector)

InputTypeRequiredDefaultDescription
InputAInteger, Float, Vector, Position, Velocityyes-First input number
InputBInteger, Float, Vector, Position, Velocityyes-Second input number
OutputTypeRequiredDescription
ResultAnyyesInputA * InputB

Normalize

Normalize a vector. Return (0,0,0) if the vector has no length

InputTypeRequiredDefaultDescription
VectorVectoryes-A vector
OutputTypeRequiredDescription
ResultVectoryesA unit length vector in the same direction as Vector

Subtract

Subtract one input from another. The inputs must be of types that make sense to be subtracted (int, float, vector)

InputTypeRequiredDefaultDescription
InputAInteger, Float, Vector, Position, Velocityyes-First input of any type
InputBInteger, Float, Vector, Position, Velocityyes-Second input of the same type as InputA
OutputTypeRequiredDescription
ResultAnyyesInputA - InputB

Character_PredictPosition

Predict where an entity will be in x secs assuming they continue to move at constant velocity on the navmesh

InputTypeRequiredDefaultDescription
EntityEntityIdyes-The entity to predict
TimeFloatyes-How far ahead to predict the position
OutputTypeRequiredDescription
PositionPositionyesPredicted position

Character_RandomPointInRange

Find a random point within a given navigation distance of the agent (or an arbitrary position)

InputTypeRequiredDefaultDescription
RangeFloatyes-Maximum path distance to returned point (approximate)
MinDistanceFloatno0.00Minimum straight line distance to returned point (approximate)
AngleFloatno0.00Angle of segment to limit search direction in degrees. Ignored if zero (or less) and clamped if greater than 180
DirectionVectornoLimit search direction to segment about this vector
CenterEntityId, PositionnoCenter the search on this position rather than the agent’s current position
OutputTypeRequiredDescription
PointPositionyesThe generated point
DistanceFloatnoApproximate non-string pulled path distance to the point

Character_RandomPointWithDirectness

Find a random point closest to a given direction

InputTypeRequiredDefaultDescription
DestinationEntityId, Positionyes-Target position or entity to calculate directness to
DirectnessFloatyes-The target directness to generate point for
RangeFloatyes-Maximum path distance to returned point (approximate)
MinDistanceFloatno0.00Minimum straight line distance to returned point (approximate). Default = 0.0f
DirectionBiasVectornoDirection to bias when scoring points
OutputTypeRequiredDescription
PointPositionyesThe generated point

CountEntitiesWithTags

Search all entities and find the ones that match the specified tags. Returns an array of matching entities. If no entities match then node fails

InputTypeRequiredDefaultDescription
TagTagyes-Tag to search on
ExtraTagTagno""Optional extra tag, if specified this must also be present
ExcludeIdEntityIdnoOptional entity to exclude
RangeFloatno0.00Max distance from entity’s current position to search within
OutputTypeRequiredDescription
CountIntegeryesThe number of entities found

FindEntitiesWithTags

Search all entities and find the ones that match the specified tags. Returns an array of matching entities. If no entities match then node fails

InputTypeRequiredDefaultDescription
TagsStringHash, BlackboardArrayyes-Tag or array of tags to search for
ExcludeIdEntityIdnoOptional entity to exclude
RangeFloatno0.00Max distance from entity’s current position to search within
OutputTypeRequiredDescription
ResultsBlackboardArrayyesThe id of the selected entity

FindNearestEntityWithTags

Search all entities within Range and find the ones that match the specified tags. Returns the closest entity from the set. If no entities match then node fails

InputTypeRequiredDefaultDescription
TagTagyes-Tag to search on
ExtraTagTagno""Optional extra tags to also search on
ExcludeIdEntityIdnoOptional entity to exclude
RangeFloatno0.00Max distance from entity’s current position to search within
OutputTypeRequiredDescription
EntityIdEntityIdyesThe id of the nearest entity
DistanceFloatnoThe distance to the nearest entity

FindRandomEntityWithTags

Search all entities and find the ones that match the specified tags. Returns a randomly select entity from the set. If no entities match then node fails

InputTypeRequiredDefaultDescription
TagTagyes-Tag to search on
ExtraTagTagno""Optional extra tags to also search on
ExcludeIdEntityIdnoOptional entity to exclude
RangeFloatno0.00Max distance from entity’s current position to search within. A value of zero means there is no distance limit
OutputTypeRequiredDescription
EntityIdEntityIdyesThe id of the selected entity

GetNextNavPoint

Finds the id of the next point on a nav route. Fails if there is no next point

InputTypeRequiredDefaultDescription
CurrentPointEntityIdyes-The id of the current point
OutputTypeRequiredDescription
NextPointEntityIdyesThe id of the next point

Ship_RandomPointInRange

Find a random point in the octree within a given navigation distance of the agent (or an arbitrary position)

InputTypeRequiredDefaultDescription
RangeFloatyes-Maximum path distance to returned point (approximate)
MinDistanceFloatno0.00Minimum straight line distance to returned point (approximate)
CenterEntityId, PositionnoCenter the search on this position rather than the agent’s current position
ClampStartPointBooleannofalseClamp the origin search to navigable octree
OutputTypeRequiredDescription
PointPositionyesThe generated point

Utility

AddTag

Add a tag to an entity

InputTypeRequiredDefaultDescription
TagTagyes-The tag to add
EntityIdEntityIdyes-The id of the entity to add the tag to

Outputs: none


ArrayBreak

Breaks out of currently iterating array loop, See also BTIterateOverArray

InputTypeRequiredDefaultDescription
BreakResultStringHashyes-Deems if this breakpoint should be considered successful or a failure

Outputs: none


Character_AdjustSpeedToTargetDist

Calculate speed based on distance from target

InputTypeRequiredDefaultDescription
StartEntityId, PositionnoOptional position or id to calculate distance from, defaults to self
EndEntityId, Positionyes-The position or id to calculate distance to
FarSpeedFloat, StringHashnoOptional name of the speed or a speed value in m/s to use up to far distance, defaults to current speed
FarDistanceFloatyes-Distance at which to start interpolating speed towards CloseSpeed
CloseSpeedFloat, StringHashnoOptional name of the speed or a speed value in m/s to use within close distance, defaults to current speed
CloseDistanceFloatyes-Distance at which to finish interpolating speed towards CloseSpeed
OutputTypeRequiredDescription
ResultFloatyesThe calculated speed value

Character_Speed

Translate a named speed (e.g. ‘Walk’, ‘Run’) into its numerical value for this entity, applying an optional percentage modifier

InputTypeRequiredDefaultDescription
SpeedFloat, StringHashnoOptional name of the speed or a speed value in m/s, defaults to current speed
StanceStringHashnoOptional stance to map against, defaults to current stance
MultiplierFloatno1.00Optional multiplier to apply to speed (to simplify calculating e.g. 10% faster than walking speed)
OutputTypeRequiredDescription
ResultFloatyesThe calculated speed value

ClaimEntity

Claim ownership an entity and remove its ‘Available’ tag

InputTypeRequiredDefaultDescription
EntityIdEntityIdyes-The id of the entity to claim
ObjectSlotStringHashyes-Where on the entity ownership blackboard to store the object id. Only one object can be stored in each

Outputs: none


ClearTimestampVariable

Clear the value of a timestamp so that any greater or less than comparisons will always return false

InputTypeRequiredDefaultDescription
NameStringHashyes-Name of the timestamp variable to clear

Outputs: none


Compute

Evaluate a Lua script conditional expression. Can access Entity, Profile and Behavior blackboards

InputTypeRequiredDefaultDescription
ExpressionStringHashyes-The expression to be evaluated
OutputTypeRequiredDescription
ResultAnyyesThe result of the expression

Copy

Copies a value (constant or variable) to a variable

InputTypeRequiredDefaultDescription
InputAnyyes-The value
OutputTypeRequiredDescription
OutputAnyyesA copy of the value

DistanceBetweenPoints

Get distance between two points, either of which can be specified as a KytPos or an entity ID

InputTypeRequiredDefaultDescription
Point1EntityId, Positionyes-The first position or id
Point2EntityId, Positionyes-The second position or id
OutputTypeRequiredDescription
DistanceFloatyesDistance between points

DistanceToBoundsEdge

Get distance of an entity to the nearest edge of a bounds object, negative if outside of bounds

InputTypeRequiredDefaultDescription
BoundsIdEntityIdyes-The id of the bounds object
OutputTypeRequiredDescription
DistanceFloatyesDistance to bounds edge, negative if outside of bounds

EraseTag

Remove a tag from an entity

InputTypeRequiredDefaultDescription
TagTagyes-The tag to erase
EntityIdEntityIdyes-The id of the entity to erase the tag from
IncludeChildrenBooleannofalseWhether to also erase children of this tag

Outputs: none


EraseVariable

Erases a specified variable

InputTypeRequiredDefaultDescription
NameStringHashyes-Name of the variable to erase

Outputs: none


Execute

Execute a Lua script expression. Can access Entity, Profile and Behavior blackboards

InputTypeRequiredDefaultDescription
ExpressionStringHashyes-The expression to be executed

Outputs: none


Fail

Do nothing; return fail on first update

Inputs: none

Outputs: none


GenerateRandom2dDirection

Generate a random 2d direction in the x-y plane within +/- degrees of the forward direction

InputTypeRequiredDefaultDescription
ForwardVectoryes-The forward direction about which to generate
AngleFloatno180.00The maximum allow angle (in degrees) either side of the forward direction (allowed range 0 - 180)
OutputTypeRequiredDescription
DirectionVectoryesThe random direction that is generated

GenerateRandomDirectionOnPlane

Generate a random direction on a plane given a normal to the plane

InputTypeRequiredDefaultDescription
NormalVectoryes-The plane normal
OutputTypeRequiredDescription
DirectionVectoryesThe random direction that is generated

GenerateRandomFloat

Generate a random float value from Min to Max, optionally scaled

InputTypeRequiredDefaultDescription
MinFloatyes-The minimum (inclusive) value to be generated
MaxFloatyes-The maximum (inclusive) value to be generated
ScaleFloatno1.00Value to scale the randomly generated integer by, e.g. MinVal = 1.0, MaxVal = 4.0, Scale = 2.0: return value is a number from from 2.0 to 8.0
OutputTypeRequiredDescription
ResultFloatyesThe random number that is generated

GenerateRandomInt

Generate a random integer value from Min to Max, optionally scaled

InputTypeRequiredDefaultDescription
MinIntegeryes-The minimum (inclusive) value to be generated
MaxIntegeryes-The maximum (inclusive) value to be generated
ScaleIntegerno1Value to scale the randomly generated integer by, e.g. MinVal = 1, MaxVal = 4, Scale = 2: return value is a number from from 2 to 8
OutputTypeRequiredDescription
ResultIntegeryesThe random number that is generated

GenerateRandomPosition

Generate a random position offsetting from reference pos, within the Min and Max constraints on each axis

InputTypeRequiredDefaultDescription
MinXFloatno0.00The minimum (inclusive) value to be generated on the X axis
MaxXFloatno0.00The maximum (inclusive) value to be generated on the X axis
MinYFloatno0.00The minimum (inclusive) value to be generated on the Y axis
MaxYFloatno0.00The maximum (inclusive) value to be generated on the Y axis
MinZFloatno0.00The minimum (inclusive) value to be generated on the Z axis
MaxZFloatno0.00The maximum (inclusive) value to be generated on the Z axis
ReferencePosPositionyes-The position to generate the random offset from
OutputTypeRequiredDescription
ResultPositionyesThe random position that is generated

GetArraySize

Get an Entity’s sate tree and gain access to it’s blackboards. [WARNING] Do not attempt to change values of a blackboard recieved by this node

InputTypeRequiredDefaultDescription
ArrayBlackboardArrayyes-Array to return size of
OutputTypeRequiredDescription
ArraySizeIntegeryesSize of the given array

GetDirection

Get a normalized direction vector between two points, either of which can be specified as a KytPos or an entity ID

InputTypeRequiredDefaultDescription
StartEntityId, Positionyes-The first position or id
EndEntityId, Positionyes-The second position or id
OutputTypeRequiredDescription
ResultVectoryesA unit length vector

GetEntityDirection

Get direction in world space of entity’s specified local axis

InputTypeRequiredDefaultDescription
EntityIdEntityIdyes-The id of the entity
DirectionStringHashyes-The name of the desired local direction
OutputTypeRequiredDescription
WorldDirectionVectoryesUnit vector in the relevant direction in world space

GetEntityPos

Get position of an entity

InputTypeRequiredDefaultDescription
EntityIdEntityIdyes-The id of the entity
OutputTypeRequiredDescription
PositionPositionyesThe position of the entity

GetEntityStateTree

Get an Entity’s sate tree and gain access to it’s blackboards. [WARNING] Do not attempt to change values of a blackboard recieved by this node

InputTypeRequiredDefaultDescription
EntityIdEntityIdyes-The ID of the Entity
OutputTypeRequiredDescription
StateTreeBlackboardyesReturns the Entity State Tree giving access to it’s blackboards

GetEntityTargetBlackboard

Returns a pointer to entity’s target blackboard. Fails if no blackboard exists

InputTypeRequiredDefaultDescription
EntityIdEntityIdyes-Id of entity to get blackboard from
OutputTypeRequiredDescription
TargetBBBlackboardyesTarget blackboard to the input entity

GetSignalParameter

Get the value of a signal parameter

InputTypeRequiredDefaultDescription
SignalBlackboardyes-The signal to query
ParameterNameStringHashyes-Name of the parameter to retrieve from the signal, this may be a path if the signal contains sub-blackboards
OutputTypeRequiredDescription
ValueAnyyesValue contained by the parameter

InitializeVariable

Create a behavior variable initialized to the default value

InputTypeRequiredDefaultDescription
NameStringHashyes-The variable name to create
TypeStringHashyes-The type for the behavior variable

Outputs: none


Log

Write a message to a log

InputTypeRequiredDefaultDescription
MessageStringyes-The message to write to the log
LevelStringHashno“Normal”The severity of the message

Outputs: none


Noop

Do nothing until interrupted

Inputs: none

Outputs: none


OverrideEntityPhysics

Override the physics aspect of an entity for a given frame

InputTypeRequiredDefaultDescription
EntityIdEntityIdyes-Entity to override
PositionPositionnoOverride the entity’s position (Optional)
VelocityVector, VelocitynoOverride the entity’s velocity (Optional)

Outputs: none


PersonalLog

Write a message to an entity’s personal log

InputTypeRequiredDefaultDescription
MessageStringyes-The message to write to the personal log

Outputs: none


PopArrayValue

Pops last value from the end of an array

InputTypeRequiredDefaultDescription
ArrayBlackboardArrayyes-The array to pop a value from
MethodStringHashno“Last”Which value to pop from the array
OutputTypeRequiredDescription
ValueAnyyesThe value popped from the array

PushArrayValue

Pops last value from the end of an array

InputTypeRequiredDefaultDescription
ArrayStringHashyes-The array push value to
ValueAnyyes-The value to push into array

Outputs: none


Raycast

Perform a raycast, succeeds if nothing is hit

InputTypeRequiredDefaultDescription
FromEntityId, Positionyes-Entity or position to raycast from
ToEntityId, Positionyes-Entity or position to raycast to
OutputTypeRequiredDescription
HitPosPositionnoHit position (only valid if node fails)

ReleaseEntity

Release ownership of an object and add ‘Available’ tag

InputTypeRequiredDefaultDescription
ObjectSlotStringHashyes-Where on the entity ownership blackboard the object is stored

Outputs: none


ReplaceTag

Replace one tag with another on an entity

InputTypeRequiredDefaultDescription
OldTagTagyes-The tag to remove
NewTagTagyes-The tag to add
EntityIdEntityIdyes-The id of the entity on which to change the tags

Outputs: none


SendResponseSignal

Send a response to a signal handled by the Behavior Tree

InputTypeRequiredDefaultDescription
SignalBlackboardyes-The signal to respond to
ResultStringHashyes-The result to return, e.g. Success or Failed

Outputs: none


SendSignal

Send a signal

InputTypeRequiredDefaultDescription
NameStringHashyes-The name of the signal to send
TargetEntityIdnoThe ID of the entity to send the signal to (defaults to self)
Key1StringHashno""Optional key for first data parameter on the signal
Value1AnynoOptional value for first data parameter
Key2StringHashno""Optional key for second data parameter on the signal
Value2AnynoOptional value for second data parameter

Outputs: none


SendSignalToGroup

Send a signal to all entities in a group

InputTypeRequiredDefaultDescription
NameStringHashyes-The name of the signal to send
CategoryStringHashyes-The category of the group to send the signal to
Key1StringHashno""Optional key for first data parameter on the signal
Value1AnynoOptional value for first data parameter
Key2StringHashno""Optional key for second data parameter on the signal
Value2AnynoOptional value for second data parameter

Outputs: none


SetBranchTag

Remove all tags within a given branch and add new tag instead

InputTypeRequiredDefaultDescription
BranchTagTagyes-The branch tag to prune
TagTagyes-The tag to add
EntityIdEntityIdyes-The id of the entity to alter tags

Outputs: none


SetTimestampVariable

Set the value of a timestamp to now, create if it doesn’t already exist

InputTypeRequiredDefaultDescription
NameStringHashyes-Name of the timestamp variable to set to now

Outputs: none


SetVariable

Sets a variable to a particular value

InputTypeRequiredDefaultDescription
NameStringHashyes-The variable name (or path) to write the value to
ValueAnyyes-Value to assign to the variable

Outputs: none


Ship_NavRaycast

Test if there is a straight navigable line between two positions

InputTypeRequiredDefaultDescription
FromEntityId, Positionyes-Entity or position to raycast from
ToEntityId, Positionyes-Entity or position to raycast to
OutputTypeRequiredDescription
HitPosPositionyesHit position (only valid if node fails)

SmoothSpeedToTargetDist

Calculate speed based on distance from target, smoothing over frames for less abrupt changes

InputTypeRequiredDefaultDescription
StartEntityId, PositionnoOptional position or id to calculate distance from, defaults to self
EndEntityId, Positionyes-The position or id to calculate distance to
FarSpeedFloat, StringHashnoOptional name of the speed or a speed value in m/s to use up to far distance, defaults to current speed
FarDistanceFloatyes-Distance at which to start interpolating speed towards CloseSpeed
CloseSpeedFloat, StringHashnoOptional name of the speed or a speed value in m/s to use within close distance, defaults to current speed
CloseDistanceFloatyes-Distance at which to finish interpolating speed towards CloseSpeed
LowSpeedClampFloat, StringHashno0.00Optional name of the speed or a speed value in m/s below which not to go
SmoothingDecayRateFloatno0.10Smoothing decay, higher value is more smoothing, e.g. 0.1 is 90% towards target value in 1 second
LastResultFloatyes-Speed calculated in last run, or initial speed value
LastUpdateTimestampyes-Timestamp that node was last run, or use now for first run
OutputTypeRequiredDescription
SmoothedSpeedFloatyesThe calculated speed value
UpdateTimestampTimestampyesThe timestamp for this update (to pass back in next time)

Success

Do nothing; return success on first update

Inputs: none

Outputs: none


Wait

Wait and do nothing for specified time

InputTypeRequiredDefaultDescription
WaitTimeFloatno0.00Seconds to wait, zero seconds waits forever

Outputs: none


WaitForSignal

Listen for a signal of a specified name and then keep copy of the signal

InputTypeRequiredDefaultDescription
NameStringHashyes-The name of the type of signals to listen for
FilterKey1StringHashno""Optional filter to listen for only signals that contain this key
FilterValue1AnynoOptional filter to listen for only signals that have this value in the FilterKey field
FilterKey2StringHashno""Optional filter to listen for only signals that contain this key
FilterValue2AnynoOptional filter to listen for only signals that have this value in the FilterKey field
OutputTypeRequiredDescription
SignalBlackboardnoA copy of the signal received

WaitRandom

Wait and do nothing for random time length between min and max specified values

InputTypeRequiredDefaultDescription
MinWaitTimeFloatyes-Min seconds to wait
MaxWaitTimeFloatyes-Max seconds to wait

Outputs: none


Groups

AddEntityToGroup

Add an entity to a group

InputTypeRequiredDefaultDescription
GroupIdEntityIdyes-Id of the group to add entity to
EntityIdEntityIdyes-Id of the entity to add
IsLeaderBooleannofalseIs this node designated as leader of the group. If this entity dies then the group will be disbanded
OutputTypeRequiredDescription
CountIntegeryesNumber of entities in the group after the entity is added

CreateGroup

Create a new group entity

InputTypeRequiredDefaultDescription
TypeStringHashyes-Type of the group
OutputTypeRequiredDescription
GroupIdEntityIdyesThe id of the group entity that has been created

EraseGroup

Erase an existing group entity

InputTypeRequiredDefaultDescription
EntityIdEntityIdyes-Id of the entity to erase

Outputs: none


GetEntityInGroup

Get the nth Entity in a Group

InputTypeRequiredDefaultDescription
GroupIdEntityIdyes-The id of the group that the entity belongs to
IndexIntegeryes-0 based index of entity to get from group
OutputTypeRequiredDescription
EntityIdEntityIdyesThe id of the entity

GetGroupCount

Get the count of entities in a group

InputTypeRequiredDefaultDescription
GroupIdEntityIdyes-Id of the group to add entity to
OutputTypeRequiredDescription
CountIntegeryesNumber of entities in the group after the entity is added

GetGroupFromEntity

Get the group that an entity belongs to

InputTypeRequiredDefaultDescription
EntityIdEntityIdyes-The id of the entity to get the group for
TypeStringHashyes-Type of the group to check membership of
OutputTypeRequiredDescription
GroupIdEntityIdyesThe id of the group that the entity belongs to

RemoveEntityFromGroup

Remove an entity from a group

InputTypeRequiredDefaultDescription
GroupIdEntityIdyes-Id of the group to add entity to
EntityIdEntityIdyes-Id of the entity to add
OutputTypeRequiredDescription
CountIntegeryesNumber of entities in the group after the entity is removed

Exception handling

ThrowException

Throw an exception

InputTypeRequiredDefaultDescription
TypeStringHashyes-Type of exception to throw

Outputs: none


Debug

DD_DrawLine

Draw a line between two points

InputTypeRequiredDefaultDescription
Point1EntityId, Positionyes-The first position or id
Point2EntityId, Positionyes-The second position or id
ColorStringHashno“White”The color of the line

Outputs: none


DD_DrawSphere

Draw a sphere at point with radius

InputTypeRequiredDefaultDescription
CenterEntityId, Positionyes-Position of center
RadiusFloatyes-Radius of sphere
ColorStringHashno“White”The color of the line

Outputs: none


HDV2D_DrawRandomPoints

Generate and render random points on the navmesh

InputTypeRequiredDefaultDescription
NumPointsIntegeryes-The number of points to generate (maximum 10000)
MinRadiusFloatyes-The minimum distance points are allowed to be to the centre
MaxRadiusFloatyes-The maximum distance points are allowed to be to the centre

Outputs: none


SQS

SpatialQuerySimple

Run a SQS query with simplest setup

InputTypeRequiredDefaultDescription
QueryStringHashyes-Name of SQS query to process
OriginEntityId, Positionyes-Entity or position for the query origin
ReferenceEntityId, PositionnoEntity or position for the query reference
OutputTypeRequiredDescription
SQSPointPositionyesPosition of top point of query
SQSPointIdEntityIdnoID of top point of query
SQSResultBlackboardnoBlackboard containing more data about result

State Machine

SendTransitionSignal

Send a signal to this entity to cause a state transition in a parent State Machine. This node throws an error if the state machine does not transition away from the current state after this node has sent the signal

InputTypeRequiredDefaultDescription
NameStringHashyes-The name of the transition signal

Outputs: none


Composite Nodes

Nodes with one or more children

Basic

IfThenElse

Test a Lua condition on entry and if true executes its first child, if false executes second child, if present, otherwise fails

InputTypeRequiredDefaultDescription
ConditionStringHashyes-The Lua expression to be evaluated, must evaluate as a boolean (e.g. it could have multiple tests with ands and ors, for example)

Outputs: none


ParallelUntilAllComplete

Runs all children at the same time all are complete. Returns fail if any failed

Inputs: none

Outputs: none


ParallelUntilAnyComplete

Runs all children at the same time until one completes

Inputs: none

Outputs: none


ParallelUntilFailure

Runs all children at the same time until one fails

Inputs: none

Outputs: none


Selector

Runs children one after another until one succeeds or they all fail

Inputs: none

Outputs: none


Sequence

Sequence of nodes that is run in succession. Stops and fails as soon as any child fails

Inputs: none

Outputs: none


State Machine

StateMachine

A state machine with transitions controlled by signals. This node completes if a child state runs to completion

Inputs: none

Outputs: none


Priority

Priority

Controls an ordered set of children each with a boolean condition as to whether to execute. Will continuously evaluate and execute first child with a true condition

Inputs: none

Outputs: none


Decorator Nodes

Nodes with exactly one child

Flow control

RepeatUntilFails

Keeps repeating the child node until it fails

InputTypeRequiredDefaultDescription
IterationsIntegerno0Number of iterations to run (default infinite)

Outputs: none


RepeatUntilSucceeds

Keeps repeating the child node until it succeeds

InputTypeRequiredDefaultDescription
IterationsIntegerno0Number of iterations to run (default infinite)

Outputs: none


Repeater

Keeps repeating the child node regardless of the outcome

InputTypeRequiredDefaultDescription
IterationsIntegerno0Number of iterations to run (default infinite)

Outputs: none


Timer

Runs child node for up to the specified amount of time

InputTypeRequiredDefaultDescription
RunTimeFloatyes-Seconds to run
FailOnTimeoutBooleannofalseWhether the node should fail if the timer expires before the child node completes

Outputs: none


Return code manipulation

Failer

Always fails

Inputs: none

Outputs: none


Inverter

Reverse the return value of the child node

Inputs: none

Outputs: none


Succeeder

Always succeeds, unless there is an exception

Inputs: none

Outputs: none


Exception handling

HandleException

Handle an exception by interrupting the tree and then failing or succeeding

InputTypeRequiredDefaultDescription
ResultStringHashno“Succeed”What should the node return when it receives an exception
TypeStringHashno""Type of exception to handle, or unspecified to handle all exceptions

Outputs: none


ThrowOnFail

Throw an exception if the child node fails

InputTypeRequiredDefaultDescription
TypeStringHashyes-Type of exception to throw

Outputs: none


Utility

CallSubtree

Call a registered pluggable BT subtree

InputTypeRequiredDefaultDescription
LabelStringHashyes-The name of the subtree to be called

Outputs: none


ClearTimestampVariableOnExit

Clear the value of a timestamp on exit so that any greater or less than comparisons will always return false

InputTypeRequiredDefaultDescription
NameStringHashyes-Name of the timestamp variable to clear

Outputs: none


EraseVariableOnExit

Erase a variable when the child node finishes

InputTypeRequiredDefaultDescription
NameStringHashyes-Variable name (or path) to erase

Outputs: none


HandleRequestSignal

Manages the sending of signal responses when handling request signals such as task switches or scripted commands

InputTypeRequiredDefaultDescription
SignalBlackboardyes-The signal being responded to
ResponseOnSuccessStringHashno“Success”The response to return when subtree succeeds
ResponseOnFailStringHashno“Failed”The response to return when subtree fails
ResponseOnEnterStringHashnoThe optional response to return when entering the subtree

Outputs: none


IterateOverArray

Iterates over elements in an array, See also BTArrayBreak

InputTypeRequiredDefaultDescription
ArrayBlackboardArrayyes-Array to iterator over
OnCompleteStringHashno“Succeed”Return value to propogate on reaching end of array
OutputTypeRequiredDescription
ElementAnyyesArray element currently iterating

ReleaseEntityOnExit

Release ownership of a claimed entity on exit

InputTypeRequiredDefaultDescription
ObjectSlotStringHashyes-Where on the entity ownership blackboard is the object id stored

Outputs: none


SetControlledEntity

Specifies which entity the behavior tree is being applied to. Still keeps the same behavior blackboard

InputTypeRequiredDefaultDescription
EntityIdEntityIdnoThe id of the entity to control (Optional, default current entity)

Outputs: none


SetTimestampVariableOnExit

Set a timestamp variable to a current time on exit

InputTypeRequiredDefaultDescription
NameStringHashyes-Name of the timestamp variable to set

Outputs: none


SetVariableOnExit

Set a variable to a particular value when the child node finishes

InputTypeRequiredDefaultDescription
NameStringHashyes-Variable name (or path) to set
ValueAnyyes-Value to assign to the variable

Outputs: none


Character movement

Character_DisableAvoidanceForEntity

Switch of avoidance against a particular entity. Usually used for your target. Avoidance is re enabled when this node terminates

InputTypeRequiredDefaultDescription
EntityEntityIdyes-The entity to no longer avoid

Outputs: none


OverrideObstacleScale

Temporarily changes the scale of the avoidance obstacle until the subtree finishes

InputTypeRequiredDefaultDescription
ScaleFloatyes-The new scale to use

Outputs: none


Ship_DisableAvoidanceForEntity

Switch off avoidance against a particular entity. Usually used for your target. Avoidance is re enabled when this node terminates

InputTypeRequiredDefaultDescription
EntityEntityIdyes-The entity to no longer avoid

Outputs: none


Ship_ToggleAvoidance

Switch on or off avoidance. Avoidance is reset when this node terminates

InputTypeRequiredDefaultDescription
Avoidance EnabledBooleanyes-Is avoidance enabled or disabled?

Outputs: none



Copyright © 2022 Open 3D Engine Contributors

Documentation Distributed under CC BY 4.0.
For our trademark, privacy and antitrust policies, code of conduct, and terms of use, please click the applicable link below or see https://www.lfprojects.org.


The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Policy page.