BGE Logic Nodes Add-on.

V 0.2.8

Reference.

Overview

The add-on allows the user to build logic statements connecting nodes.

All the nodes added to the tree are transformed into cells of a network. This network of cells is then pulsed one time per frame during the execution of the game. The net result of this pulse is that the network is evaluated as a set of statements: the parameters that need to be filled with values are filled, the conditions that needs to be checked are checked, the actions that need to be executed are executed. All this happens once per frame. In this execution model, saying that “when the condition A is TRUE, the action B will be executed” means that if the condition is TRUE, the action will be executed one time every frame.

There are three kind of nodes: parameters (green), conditions (yellow), actions (orange).

A parameter is an unconditioned value: it always has a value. A parameter may need to be linked to other cells to have a valid value but nonetheless it will have one.

A condition is a node that emits a TRUE or FALSE value. Some conditions operate by themselves, like the Always condition in the previous image, some may need other conditions, like a And condition:

The value emitted by a Condition can be used to form other conditions or to activate Actions or as a parameter – if the boolean alternative TRUE / FALSE makes sense as a parameter in some logic setup.

Actions are conditioned tasks. When the input condition of an action is TRUE, the action is executed. As said before, that means that for each frame in which the condition is TRUE, the action will be executed once. If the action says “move the object 1 unit in some direction” and the actions is  TRUE on every frame, then the object will move 1 unit every frame.

For its output to be executed in the game, a logic tree must be applied to some object.

Each object gets its own copy of the logic tree.

The consequence of that is that both objects will execute the same logic process but some of the parameters in the tree may have different values. For example, named A and B to objects that shares the same logic tree in the blender interface, the parameter “Owner Game Object” will be A, when the A's instance of the tree is executed, and B when the B's instance of the tree is executed.

List of the available nodes.

Parameters

Action Status

The Action Status parameter returns the current status of a blender animation (which is called action, presumably because animations are just a kind of action).

The parameter requires a Game Object. If no game object is supplied or if the game object is invalid – because it has been removed from the game – the parameter values will be FALSE, FALSE, NONE, 0.0

The input Game Object is the object that is – or may be – playing an action.

The Layer integer value can be specified directly in the node or supplied with an input. The Layer is the index of the animation channels available to the game object that will be queried.

The output Is Playing is TRUE if the game object is playing some action in the Layer channel, FALSE otherwise.

The output Not Playing is TRUE if the game object is not playing an action in the Layer channel, FALSE otherwise.

The output Action Name is some string if the game object is playing an action in the given Layer, None otherwise. If it is not None, the string is equal to the name of the played action, as seen in the blender interface.

The output Action Frame is the index of the frame currently played by the action in the given layer of the game object, if an action is playing in that layer, otherwise is 0.0

Active Camera

The Active Camera parameter returns the active camera (a game object, likely to be of type bge.types.KX_Camera) of the input scene.

The output value is a camera object if the input scene is not None and not invalid, otherwise it will be None.

The input scene is a KX_Scene instance (commonly the output of a Current Scene parameter or of a Find Scene action)

Arithmetic Op

The Arithmetic Op takes two values and return the result of an operation on both.

The input values A and B can be anything that supports the addition, subtraction, multiplication or division operator. For example, “+” is available for strings, so A and B can be strings, but divide is not, so A and B cannot be string if the operator is the division. Matrices can be multiplied, Game Objects cannot. A Vector can be multiplied by a scalar but not added to a scalar or vice versa.

Current Scene

The Current Scene parameter has a single output that has always the value of the current scene. The current scene is a bge.types.KX_Scene instance and it refers to the scene in which the logic network – which is a plain python module controller in logic brick terms – is executed.

Usually this is the scene you're working on when building the tree – but that really depends on your workflow.

Game Object's Parent

Access to the parent of a game object.

The Child Game Object input is the Game Object whose parent will be returned.

The Parent Game Object is the parent of the input child object.

Get Game Object Member

This parameter takes an object, usually a Game Object, and returns the value of one of its members. The member is a python attribute of the given object. In the common case, this parameter is used to get values like the position, the color, the orientation or the name of a game object.

The output value depends on the chosen member. It can be a vector, a matrix, a string…

The output will be None if the game object is missing or if it is invalid.

Get Game Object Property

This parameter returns the value of a game object property. Each game object in the blender game engine has an associated and initially empty set of key-value pairs. This parameter is used to access the values in that set.

The input Object is the game object from where to get the values. If it is None or Invalid, the output of the parameter will be Default value.

The input Name is the string key associated with the requested value. If it missing or empty, the output of the parameter will be the Default value.

The Default value is the value returned if, for any reason, it is not possible to get the requested value from the object (there is no such value, the key is not valid, there is no object).

It is important to remember that the Default value is never set: if the object has not the value with the requested name, the parameter will return the default value but the object will still have no value associated with the given key.

To store the value one has to either use the Set Game Object Property action or use the blender game logic panel.

Get Global Value

The Get Global Value parameter returns a value shared among all trees.

The system allows the creation of multiple named dictionaries of values. Each one of these dictionaries is identified by a unique name, chosen by the user.

The ID input is a string denoting the unique name of the shared key-value set the user wants to access. Typing something like “My Game Data” means that the key and the value will be retrieved from a shared dictionary that all trees can access via the ID “My Game Data”.

The Key input is a string that defines the unique name of the requested value.

The Default value is the value that the parameter will return if there is no value with the requested Key in the global values set with the given ID.

Global value accessed with this parameter can be persistent – meaning that they might have been written to a file, in bgelogic/storage subdirectory of the main game file.

To store a value in a global dictionary one can use the Set Global Value action. That action also handles the optional persistence of the values.

Value

The Value parameter is a constant value. The value can be chosen to be None, a scalar, a string, a boolean, a vector or the result of a constant expression.

Mouse Data

The parameter Mouse Data gives access to the position of the mouse cursor, in normalized screen space coordinates – that is from 0.0 to 1.0, with 0.5 being the center.

X is the position along the X axis

Y is the position along the Y axis

DX is the translation of the mouse position along the X axis since the last game frame.

DY is the translation of the mouse position along the Y axis since the last game frame.

DWHEEL is the scroll direction of the mouse wheel (-1, 0 or 1)

(X,Y,0) is a Vector whose first two components are the X and Y positions.

(DY, DY, 0) is a Vector whose first two components are the DX and DY translations.

Orientation

The Orientation parameter is 3x3 rotation Matrix. The X,Y and Z inputs are angle in radians. The Orientation input is another 3x3 Matrix. If there is no Orientation input, the value of the Matrix is the value of the euler angle set (X,Y,Z).

If there is an Orientation input, the rotation component along the X, Y or Z axis is replaced by the corresponding X, Y, Z input angle. To avoid this replacement, the X, Y or Z angle must be set to None.

The Orientation output is a 3x3 Matrix obtained with the aforementioned substitution process.

The XYZ Rad Euler output is the euler angle set (X,Y,Z), obtained from the output matrix.

The X Rad is the X component of that euler angle set – the rotation along the X axis.

The Y Rad is the Y component of that euler angle set – the rotation along the Y axis.

The Z Rad is the Z component of that euler angle set – the rotation along the Z axis.

Owner Game Object

The Owner Game Object is the game object to which this logic tree is applied. When a tree is applied to multiple objects, because each object will get an instance of the tree, the Owner Game Object parameter will return, for each tree instance, a different game object. That allows the tree to be applied to different things without one interfering with the others.

The output is never None and never invalid. Unless there is a bug.

Python Module Function

The Python Module Function is a parameter whose ouput is a set of four value, resulting from the application of a function defined in a python module to a set of four inputs.

The Module input is a string, whose value corresponds to the name of the python module that contains the invoked function.

The Member input is a string, whose value corresponds to the name of the python function (or callable member) that will be invoked.

If the Module or the Member inputs are None or empty, the parameter node will print the input values on the console – as a debug utility.

The four inputs are the values of anything that gets linked to it.

The four outputs are the values that the called function wants to expose to other cells.

The called function must take one argument. That argument is a cell object – the cell that represents the parameter node at runtime.

The cell has a list of inputs and a list of outputs.

Both lists have four slots.

The input list is called… inputs, the output list is called outputs.

For example, a function could be:

def do_something(cell):

In the body, to access the value of the input IN0, one could write:

some_value_0 = cell.inputs[0]

and

some_value_1 = cell.inputs[1]

some_value_2 = cell.inputs[2]

some_value_3 = cell.inputs[3]

The function does its work on the needed value then, if it wants to spit out some result, it can do so by filling the outputs slots:

cell.outputs[0] = some value

cell.outputs[1] = some other value

cell.outputs[2] = whatever

cell.outputs[3] = a thing

Non connected input slots have the default value None.

Time

The Time parameter returns two time relate values.

Time Per Frame is the time elapsed since the last game frame. This time value can be used to compute displacements that are the result of a velocity.

Timeline is the time elapsed since the start of the underlying network. If some action must happen after ten minutes are passed since the start of the game, one can use this value – provided that the tree It belongs to has also been started when the game did.

Value Switch

Value Switch takes two inputs A and B and returns either A or B, according to evaluation of a third input value, “True A, False B”. The default output is None. A and B can be anything, the input value for the “condition” can be any boolean value or any value that can be evaluated for truth – in the python sense of “if X then return A else return B”

Vector

The Vector parameter returns a Vector and each one of its components. The default value is the zero Vector and zero is also the default value of the outputs X, Y, Z.

If provided, the input Vector is used to set the components of the output Vector.

The input components X, Y and Z replaces the corresponding components of the input Vector, if they are not None.

The Normalized Vec output is the normalized output vector.

Vector 4

The Vector 4 parameter assembles and returns a vector and its components.

If the node has an input vector (with 3 or 4 components) AND some component inputs (any combination of X,Y,Z,W) the resulting vector is (a copy of) the same as the input one with the individual components replaced by the inputs that are not None.

Sound

The Sound parameter represents a sound object, for the purpose of… playing sound. The resulting Sound value is an instance obtained from the given sound file. It is possible, through other nodes, to start, stop or loop a single Sound. If one needs to play two instances of the same Sound at once, there must be two different Sound parameters, both using the same file path.

The File input is a string, denoting the relative or absolute path of a sound File. It looks like a sound in blender can be played as a 3D sound only if it is mono. A path is relative if it starts with a double forward slash (//). Internally, the relative path is transformed into an absolute path by calling bge.logic.expandPath (which should result in a path relative to the path of the main blender file of the game).

The Sound output is the node representation of the sound file. The Sound socket is blue, so it should be clear who can use a sound.

The Is Playing output signals if the sound is playing (TRUE) or not (FALSE).

The Current Frame output is the position (in seconds) of the playing sound. It can be used in conjunction with other nodes to do stuff like executing some action when a sound track has reached or past a certain threshold point.

Formatted String

The Formatted String parameter takes some input values and returns a string. The intended purpose is to show on the user interface information strings like how much life the player has, how many bullets are available or the name of an enemy… things like that.

The Format String input is the string one would pass to the “format” function of a python string (like “something”.format(the_format_string)). What can go in that format string is defined by that format function. Basically, {} is A, B, C or D, {0} is A, {1} is B, {2} is C, {3} is D. One can use {0:.2f} to format a decimal value with two digits after the dot, and so forth.

The four inputs A, B, C and D are the values that can be used in the format string. There are four of them for an arbitrary decision on my part.

Distance

The distance parameter returns the distance between two values.

The A and B inputs can be game objects, vectors or sequences of 3 decimal values, in any combination.

Armature Bone Status

The Armature Bone Status parameter gives access to the position, orientation and scale value of an armature's bone.

The Armature Object input is a game object that points to a game armature. In the game engine, armatures are translated into KX_GameObject instances so it possible to access an armature using one of the lookup nodes that seeks Game Object instances.

The Bone Name input is the name of the bone we want to access, as seen in the blender interface.

The XYZ Pos, XYZ Rot and XYZ Scale outputs returns the position, rotation and scale of the bone, as vectors. The rotation is always expressed in XYZ euler form.

Screen Position

The Screen Position parameter converts the world position (of a Game Object or as a Vector 3) into a normalized screen location (-1.0 to 1.0, where 0.5 is the center of the screen)

The Game Object /Vector input is the world position (of the Game Object or packed into a Vector3) to translate

The Camera input is the Camera relative to which the world position is transformed

The Screen X output is the resulting x value (horizontal axis) in the normalized screen coordinate system

The Screen Y output is the resulting y value (vertical axis) in the normalized screen coordinate system

World Position

The World Position parameter translates a screen position (in normalized screen coordinates) into a world position (vector 3)

The Camera input is the camera object relative to which the translation occurs.

The Screen X input is the normalized (-1.0 to 1.0, where 0.5 is the center of the screen) value along the horizontal axis

The Screen Y input is the normalized value along the vertical axis

The Depth value is a scalar (float, double, integer…) that represents the distance from the camera plane in world coordinates of the resulting 3d point.

Conditions

Always

The Always condition returns TRUE for the first network pulse and FALSE all other times. If Repeat is ON, the condition returns TRUE all the time. With Repeat OFF, the condition can be used to execute actions just once, the first time the network is executed. With Repeat ON, it can be used to activate actions once every frame.

And

The And condition output is TRUE if both A and B input values are TRUE, it is FALSE if any of A or B is FALSE. The purpose is to do something when two conditions are both TRUE (like keeping the mouse button and the shift key pressed to activate some action)

And List

The And List condition returns TRUE if all the linked input values are TRUE. It is not necessary to fill all the input sockets, the condition works with up to six input values.

Collision

The Collision condition is used to detect collisions between game objects. The “When Colliding” output is TRUE fo as long as the input Game Object is in collision with another object.

The Game Object input is the object whose collision with other objects are monitored. If the input Game Object is None or invalid, the Collision returns FALSE, None, None, None.

The Game Object output is the object with whom the monitored object is in collision.

The Point output is a Vector denoting the contact point of the collision.

The Normal output is a Vector denoting the normal at the contact point. More or less.

Key Pressed

The Key Pressed condition is used detect the state of a keyboard's key.

If Pulse is OFF, the output of the condition is TRUE the first time the key is pressed and FALSE from then on until the key is released. After the release, the condition will by TRUE again when the key is pressed and so no.

If Pulse is ON, the condition remaing TRUE until the key is released.

The monitored key can be chosen by pressing the Press & Choose button and then pressing the requested key or by using an input value. The input value is a string that corresponds to the name of one of the blender constants for a keyboard key.

Key Released

The KeyPressed condition works the same as the Key Released condition, but for release events.

Mouse Pressed

The Mouse Pressed condition is the analog of Key Pressed for mouse buttons. The button input takes a string equal to the fully qualified name of one of the bge constants that identifies a mouse button (for example bge.events.LEFTMOUSE)

Mouse Released

Mouse Released does the same as Mouse Pressed but for button release events.

Logic Operations

The Logic Operations condition remains TRUE for as long as the result of the selected logic operation, applied to the two input values, is also TRUE

Check Distance

The Check Distance condition checks the distance between two values and returns True or False according to the result of a logic operation between that distance and a threshold

The Check input is the logic operation performed between the computed distance and the Dist value

The A input is a Vector, a Game Object or a sequence of 3 decimal values

The B input is a Vector, a Game Object or a sequence of 3 decimal values

The Dist input is the value to check the computed distance against

The Hyst input is the hysteresis value to apply when the check operation is a greater than or less that or greater than/equal to or less that/equal to value. When the input is specified, it acts as a threshold on subsequent activations of the condition, like a small pause an object will take before to start following again a target.

The Out output returns TRUE for as long as the condition check is satisfied.

Logic Network Status

The Logic Network Status condition monitors the status of a logic network – that is the runtime version of a Logic Tree – and returns if it is running or not.

The Game Object input is a game object that may or may not have a tree installed.

The Tree Name input is the name of the logic tree as seen in the blender interface.

If the game object is None or invalid, the condition returns FALSE for both outputs.

If the game object has the given network installed and running, the If Running output will be TRUE. If the network is not running, it will return FALSE. If Stopped works the contrary.

Mouse Targeting

The Mouse Targeting condition monitors an object for Mouse Enter, Mouse Over and Mouse Exit events. When the mouse cursor enters the projected surface of the object, the output On Mouse Enter will be TRUE, once, until the mouse exists the surface and then enters a second time…

The On Mouse Over output is TRUE for as long as the mouse cursor stays inside the projected surface of the object.

The On Mouse Exit output is TRUE when the mouse cursor exits the surface, then it will be FALSE until the cursor enters and then exits again.

The Point and Normal output are the Point and the Normal to the surface of the object where the mouse cursor is.

If the input Game Object is None or invalid, the output is FALSE, FALSE, FALSE, None, None.

Not

The Not condition returns TRUE if the input Condition is FALSE and FALSE if the input Condition if TRUE. When Pulse is OFF (input value FALSE), the condition will return the negated input Condition once, then it will return FALSE until the input Condition changes its value. When Pulse is ON (input value TRUE), the condition will constantly return the negated value of the input Condition.

Not None

The Not None condition returns TRUE if the input Value is not None, FALSE, if it is None.

None

The None condition returns TRUE if the input Value is None, FALSE if it is not None

Once

The Once condition return TRUE if the input Condition is TRUE, for one network pulse/loop/cycle whatever, then it will always return FALSE

Or

The Or condition returns TRUE if either A or B is TRUE, if returns FALSE if both input A and B are FALSE

Or List

The Or List condition returns TRUE if any of the linked values is also TRUE. It is not necessary to fill all the sockets, the condition works with up to six inputs.

Time Elapsed

The Time Elapsed condition outputs TRUE after a certain amount of seconds have passed since the start of the underlying logic network. If Repeat is checked (or the linked input evaluates to TRUE), the output will be TRUE once every given seconds. The Seconds input takes a floating point value.

Value Changed

The Value Changed condition monitors a Value and becomes TRUE when the value changes. The condition will then return FALSE until the value changes again.

The Old Value output returns the old value, the New Value output returns the new value.

The Value input can be any value.

If Initialize is ON, the condition takes the first value as the initial one and signals when the input value changes from that.

If Initialize is OFF, the first comparison in done against None.

Value Changed To

The Value Changed To condition monitors a value and signals when it changes into some other specific value. The output value becomes TRUE the first time the change is detected and then stays FALSE until the change is detected again.

Mouse Pressed On

The Mouse Pressed On condition is a short cut for the common task of doing something when the user clicks on a game object.

The button input controls which button must activate the check

The Game Object input represents the Game Object that must be under the mouse cursor when the mouse button is pressed to activate the condition.

The When Pressed On output is TRUE if the user pressed the mouse button when the Game Object is under the cursor (then it becomes false waiting for another “click”), it is FALSE if the user didn't press the mouse button, the cursor was not pointing at Game Object or the condition triggered and the mouse button has not been released and pressed again.

Mouse Wheel Moved

The Mouse Wheel Moved condition detects the movement of the mouse wheel.

The scroll input controls which direction of the wheel should be monitored. Scroll Up (integer value 1) detects the mouse scrolling toward positive values, Scroll Down (input integer 2) detects the mouse scrolling toward negative values, Scroll Up or Down (input integer 3) detects the mouse wheel scrolling in any “direction”.

The output condition is TRUE whenever the requested scroll happens.

Actions

Add Object

The Add Object actions adds a game object to a scene every time the input Condition is True. The added object is returned from the Added Object output.

The Name input is a string equal to the name of an object contained in an inactive layer of the given Scene.

The Life input measures for how many logic ticks the object will remain in the scene, before to be automatically removed. If zero, the object won't be removed – unless one does so by other means.

Align Axis to Vector

The Align Axis to Vector action aligns the local axis of a game object to a world direction – expressed as a x,y, z vector.

The Condition input determines when the action is executed – as long as the input is TRUE.

The Game Object input is the Game Object whose axis will be aligned (so the object rotates).

The Vector input is a x,y,z vector that represent the target world direction of the alignment. The vector can be specified in the field as a sequence of decimal numbers separated by any non numeric character sequence (like 1 1 1 or 1,1,1 or 1, 1, 1 and so on)

The axis input is the local axis of the game object that will be aligned.

The Factor input is a 0.0 – 1.0 value that represent how close the local axis will be aligned (0.0 not even a bit, 1.0 parallel).

Follow Path

This action moves a Game Object along a path. The path is defined as a sequence of points derived from the children of a game object. It means that you have to create an object – ideally an empty one that will be passed to the Path input. The world positions of all the children of that object will be the points of the path. The order is established by the name of each children. If the parent object is “Empty” and it has three children “A”, “C”, “B”, the path resulting from using “Empty” as the game object linked to the Path input will be A.worldPosition, B.worldPosition, C.worldPosition. While it might look a bit complicate, creating a path is actually quite simple: create an empty object, duplicate it the make the duplicate a child of the empty. That will be the first point of the path. To add the second point, select the child, shift-d and move it, to add a third point, shift-d and move it. And so on, Altering the position of the children will also alter the path points.

The Condition input activates the action. The condition must be continuously true for the action to operate.

The Moving Object input is the Game Object that will be translated along the path.

The Rotating Object input is the Game Object that will be rotated to look at the next point in the path. This can be the same as Moving Object or another object – usually a child of the moving object, like a turret.

The Path input is the aforementioned parent of a set of children-points

The Loop input is a boolean (TRUE/FALSE) that controls whether the action should loop the object along the path or not (a patrolling character will loop along the path until something happens that stops the follow path action)

The Optional Navmesh Object is a navmesh object. When the navmesh is present, the path will be defined using the information of the navmesh – instead of being a sequence of straight lines among the Path points.

The Move as Dynamic input is a boolean value (TRUE/FALSE) that controls whether the moving object should be translated varying its position of through its dynamic velocity components. Moving a dynamic object by settings its position (that is with “Move As Dynamic” to False) might cause the physic engine to warp it over obstacles – depending on how fast it moves, how thin the obstacle is, how big is the time step between updates of the physic engine. A static object cannot be moved via its velocity (so Move As Dynamic must be False)

The Lin Speed input is the value of the linear speed at which the object is moved.

The Reach Threshold value controls the minimum distance that the center of the moving object must reach from the current destination point in the path before to move to the next point. In general this value should be at least as big as the radius of a sphere surrounding the model, otherwise the object will never “reach” the current point.

The Look At input controls whether the Rotating Object (if defined) should be oriented toward the next point of the path.

The Rot Axis is the axis or rotation that will be changed to orientate the Rotating Object. For a walking character this is the Z axis. A turret placed on a wall might use the Y or X axis.

The Front input is the local front axis of the rotating object. If a character is set to walk forward when its Y value increases, the front axis is Y+.

The Rot Speed is the angular speed (radians per second) at which the rotating object rotates. If None, the rotating object is instantaneously oriented toward the current point of the path.

Move To

The Move To action moves an object toward a point. The output of the action signals when the destination has been reached.

The Move As Dynamic input works like the same input in Follow Path.

The Destination XYZ input is a vector (or a sequence of 3 decimals) representing the destination point. If this vector is the position of an object, Move To will behave like a Follow action.

The Stop At Distance input controls the minimum distance from the target that the moving object must reach to consider the destination reached. This should be no less than the radius of the moving object.

Replace Mesh

The Replace Mesh node replaces the mesh of a game object with another mesh.

The Condition controls when the action is executed (as long as it is TRUE).

The Target Game Object is the Game Object whose current mesh will be replaced.

The New Mesh Name input is the blender name of the mesh object that will be used as a replacement.

The Use Display input (TRUE/FALSE) controls whether the new mesh will replace the visible mesh of the game object.

The Use Physics input (TRUE/FALSE) controls whether the new mesh will replace the physics mesh of the game object.

Rotate To

This action rotates an object toward a position.

The target position is a vector or a sequence of 3 decimal values.

The rot axis is the axis along which the object will be rotated. The Z axis for a common character standing on ground.

The front input is the front axis of the object: the direction in which the object is considered moving forward.

The speed is the angular velocity of the rotation – radians per second.

Move To with Navmesh

This action behaves like a combination of Move To and Rotate To along the points that a navigation mesh returns as the path the object must follow to reach a certain position.

The Moving Object and Rotating Object can be the same game object or different ones if the part that must look at the moving direction is different than the moving body itself.

The Navmesh Object is a navigation mesh Game Object

The Destination input is a Vector or a sequence of three decimal values

The Move as Dynamic input is the same as the one in Follow Path

The Linear Speed and Reach Threshold controls the velocity of the object and the minimum distance the object must reach to stop the action – or move to the next point determined by the navigation mesh.

The Look At controls whether the Rotating Object must be oriented toward the next point, rotating around Rot Axis and facing Front axis at the given Rot Speed in radians per second.

The output condition is True when the object reaches the destination.

Add Scene

The Add Scene action adds a scene, identified by its name as seen in the blender interface, to the game as an overlay or a background, every time the input Condition is TRUE.

The Name input is a string.

Apply Motion/Rotation/Force/Torque

The Apply Value to Game Object actions applies a motion or rotational displacement, a force or a torque to a Game Object, every time the Condition is TRUE.

All applied inputs are 3 component Vectors (or list/tuple equivalents).

The rotation is in radians.

If the input Game Object is None or invalid, the action does nothing

Camera Pick

The Camera Pick action picks an object from a camera.

The pick aim can be a pair of floats, a vector or a game object. The aim is a pair of floats, the camera picks the first object located at the normalized screen position denoted by the pair. When the aim is a game object or a vector, the camera picks the first object in the direction that goes from the camera position to the aim position.

The Property input, when not empty or None, filters the pickable objects by possession of a property with that name.

The Distance input is the maximum distance at which an object can be picked.

The Has Result output is TRUE if the camera actually picks an object, it is FALSE if there is no target to pick.

The Picked Object output is the object that has been picked or None, if there is no result.

The Picked Point is the point on the surface of the target that has been picked.

The Picked Normal is the normal to the surface at thatn point.

Dynamic Object Controller

The Dynamic Object Controller moves and rotates two objects in a way compatible with a FPS or TPS navigator.

The Body Object must be a game object with physics set to Dynamic. The Head Object should be a KX_Camera – or a node whose child is a KX_Camera object but it can really be any game object.

When the Condition is True, the action evaluates the various “motion” conditions to rotate the body object along the Z axis and the camera along the X axis, to move the body object on the Y axis (forth-back) and the X axis (left-right), to apply a positive force value on the Z axis when it jumps.

The Head Rot Arc Size input determines the maximum and minimum orientation of the Head Object on the X axis, it is an angle in radians.

The Head Rot Speed is the speed of the rotation of the Head Object, in radians per second.

The Body Rot Speed is the speed of the rotation of the Body Object, same unit.

The Walk Speed and the Run Speed are the speeds at which the Body Object moves and runs, in unit per second.

The Jump Force is the measure of the force applied to the Z axis of the Body Object to make it jump.

The Body Object doesn't jump when jumping or flying (there's a check against the Z component of the velocity).

The inputs for the controls are condition results (TRUE/FALSE values), not keyboard keys or mouse buttons.

Find Game Object

The Find Game Object action finds and returns a game object.

If the condition is missing, the action will be executed once when the network starts and it will keep its value, if anything is found, until it becomes invalid.

If the condition is linked, the action will execute when the condition is TRUE until an object is found. When an object is found the action is not executed again, no matter what the condition state, until the found object becomes invalid. So this thing actually searches an object and the keeps it memorized.

The action can search for an object among all the objects in a given game scene or among the children (recursively) of some game object.

The From Scene input gives the action the scene to search in.

The From Parent input gives the action the parent object to search in.

The Query input is a string. The string is a query executed on the name of each scanned object. The query has the form:

[*]token[*]

The prefix and postfix asterisks are optional.

When there is no asterisk, the token is the exact name the action must look for.

The form *token means “the name must end with token”, the form “token*” means “the name must start with token”.

Find Scene

The Find Scene action searches and returns a Scene using a name query. The name query has the same form of the query in Find Game Object.

If the condition is missing, the action searches for a scene until one is found.

If the condition is linked, the action searched for a scene when the condition is TRUE.

The found value is kept until it becomes invalid.

Install Sub Tree

The Install Sub Tree action adds a logic tree (better, the logic network into which the tree is translated by the add-on) to an object, at runtime.

The Logic Tree will then act as a normal tree with the only difference that its execution will stop when the “parent” tree (the one executing Install Sub Tree) is removed from the game – which happens when the owner object is deleted.

The Target Object input is the game object into which install the tree.

The Tree Name input is the name of the logic tree to install, as seen in the blender's interface.

The Enabled input determines if the installed tree must also be immediately activated. An inactive tree is not executed – but can be activated with an action node when necessary.

Load Blender File

The Load Blender File action loads a blender file every time its input condition is TRUE.

The Path input is a string, its value is read as a path to a blender file. The path is relative – and resolved from the directory of the running game's blender file – if it starts with two forward slashes (//) otherwise it is considered absolute. And it won't work when you give your game to someone else.

Mouse Pick

The Mouse Pick action picks an object using the position of the mouse cursor on the screen.

Has Result it TRUE if some object has been picked.

Picked Object is the game object that has been picked or None if there's no object at the mouse cursor's position.

Picked Point is the point on the surface of the object where the pick occurred, or None if no object was found.

Picked Normal is the normal to the surface of the object at the pick point.

The Camera is the camera to use to generate the pick ray – and it is very likely to be the camera currently active.

The Property input is the name of a property that the object must have to be picked. If omitted or None, any object is good (if picked).

The Distance input measures how far an object can be from the camera to be a valid target for the picking process.

Play Game Object Action

 The Play Game Object action applies a blender animation (action) to a game object when the input Condition is True.

The Game Object input is the game object to which the animation is applied.

The Action Name input is the name of the animation to apply – as seen in the blender's interface.

The Start Frame input is the frame from where the animation should start playing.

The End Frame input is the frame at which the animation should stop playing.

The Layer input is the layer in which the animation should play. Only one animation can play on a given layer.

The Priority input controls the priority of this animation over any other playing animation.

The Play Mode input is the string value of the fully qualified name of the bge constant that denotes a mode of playing the animation (eg. bge.logic.KX_ACTION_MODE_PLAY for normal play)

The Layer Weight is the blending weight of this animation with respect of other playing animations.

The Speed input is the speed at which the animation should be played (1.0 normal 2.0 faster, 0.5 slower…)

The Bledin input is the float factor that scaled the influence of this animation with respect to other playing animations.

The Blend Mode is the string value of the fully qualified name of the bge constant denoting the blend mode (bge.logic.KX_ACTION_BLEND_ADD) and controls the kind of blending applied.

 Ray Pick

 The Ray Pick action picks an object in the scene using a ray, when the input Condition it TRUE.

The Origin inpu can be a vector or a game object and it's the location from where the pick ray originates.

The Destination input can be a vector or a game object and it's the location to where the pick ray is destined.

The Property input, if not empty and not None, tells the ray to report only objects that have a property with the given name.

The Distance input is the maximum distance at which an object can be, from the origin point, to be pickable.

The Has Result output is TRUE if the ray picked something, otherwise it is FALSE

The Picked Object output contains the picked object or None, if Has Result is FALSE

The Picked Point output contains the position on the surface of the object that has been picked. None if nothing has been picked.

The Picked Normal output contains the normal to the surface at the picked position. None if nothing has been picked.

The Ray Direction output contains the direction that the ray has been cast on. It can be useful if one wants to set something in motion along that direction (like a bullet).

 Remove Object

 The Remove Object action removes an object from the game, when the condition is TRUE. If the object has already been removed, or it is None, it does nothing.

 Remove Scene

 The Remove Scene action removes a Scene from the game, when the input Condition is TRUE. If the scene has already been removed, or it is None, it does nothing.

 Set Active Camera

 The Set Active Camera action sets the game object of the Camera input as the active camera for the input Scene whenever the input Condition is TRUE. If the input Camera or the input Scene are None or invalid, the action does nothing.

Set Object Visibility

This action changes the visibility status of a game object and, if requested via the boolean input “Include Children”, of all its children.

 Set Animation Frame

 The Set Animation Frame action sets the current frame of an animation when the input condition is TRUE. This (now) works like playing a single frame of an action.

The input Game Object is the object to which the modified animation is applied.

The Action Name input is the name of the action to use.

The Animation Layer input is the index of the layer in which the animation is playing.

The Animation Frame is the floating point value of the animation frame to set. If the input Game Object is None or invalid, the action does nothing.

 Set Game Object Member

 The Set Game Object Member action sets the value of a python attribute for the input Game Object whenever the Condition input is TRUE. The action provides some common attribute names to change the local position, world orientation the color and so forth. The requested value depends on the attribute to set. For orientations it has to be a matrix or eulers angles or a quaternion, for translations it has to be a vector… If the input Game Object is None or invalid, the action does nothing.

 Set Game Object Property

 The Set Game Object Property action sets the value of a game property for the input Game Object, whenever the condition is TRUE. The Name input is the string key of the property to set. The Value input is the value to use for the property. If the input Game Object is None or invalid, the action does nothing.

 Set Mouse Cursor Visibility

 The Set Mouse Cursor Visibility action hides or shows the mouse cursor when the input Condition is True. If the Visible input is TRUE or checked, the cursor is shown, if the input is FALSE or unchecked, the cursor is hidden.

 Start A Logic Network

 The Start Logic Network action changes the status of a network (the runtime counterpart of a Logic Tree) to active for the input Game Object. The network must be already installed, either via the Logic Tree user interface or with the Install Sub Network action. The Tree Name is a string, equal to the name of the Logic Tree, as seen in the blender's interface. If the input Game Object is None or invalid, the action does nothing. It also does nothing if the input Game Object doesn't have that particular tree installed.

 Stop a Logic Network

 The Stop Logic Network action works as Start Logic Network but does the opposite: it stops a running network.

 Stop Animation

 The Stop Animation action interrupts the animation that the input Game Object is playing in the layer denoted by the Animation Layer input, when the Condition is TRUE. If the input Game Object is None or invalid, the action does nothing. It also does nothing if no action is playing on the given layer's index.

 Unload Blender File

 The Unload Blender File action removes a blender file loaded with Load Blender File (or with a logic brick or a python call) when the condition is True. The output When Unloaded is TRUE when the file is removed. The Path is a string equal to the path of the blender file to remove. The path is considered relative to the played blender file if it starts with a double forward slash (//).

Edit Armature Bone

The Edit Armature Bone action controls the transform of an armature's bone.

The Condition input controls when the action is executed.

The Armature input is the armature game object that owns the controlled bone.

The Bone Name input is the string name of the controlled bone, as seen in the ui.

The Set XYZ Pos input is a Vector (3 numeric values can be used in the text field) used to locate the bone. If the position field is empty or the input value is None, the position of the bone is not changed. Note that the bone's position can be changed only if the bone is not connected. Or so the blender api says.

The Set XYZ Rot input is a Vector (same as above), denoting the rotation used for the bone, in euler radians. If the field is empty or the input value is None, the bone rotation is not changed.

The Set XYZ Scale input is a Vector (same as above), representing the scale to use for the bone. If the field is empty or the input value is None, the scale is not changed.

The Trans XYZ input is still a Vector, if not empty or None, it is applied as a translation – it is added to the current position of the bone.

The Rot XYZ input has the same form as the Set XYZ Rot input but it applies an angular displacement – the bone is rotated by the XYZ amount defined by that input.

The Scale XYZ input has the same form as the Set XYZ Scale input and it applies a scale differential – the bone scale is increased by the XYZ amount.

Edit Armature Constraint

The Edit Armature Constraint action is used to control a bone constraint.

The Condition determines when the action is executed.

The Constraint Name is a string that defines which constraint is controlled by the action. The name has the form [CONSTRAINT TYPE][:][BONE NAME] (without the brackes).

The Enforced Factor input is a float field that controls, when not empty or none, the “intensity” of the constraint.

The Primary Target input is the Game Object that acts as the primary target of the constraint – if the constraint needs a primary target.

The Secondary Target input is the Game Object that acts as the secondary target of the constraint – if required.

The Active input controls allows the action to activate or deactivate a constraint.

The IK Weight input is a float value that, when not empty or None, controls the influence of the constraint on the armature.

The ID distance input is a float value that, when not empty or None, sets the distance threshold used by the constraint – if needed.

The Distance Mode input controls the corresponding parameter of the constraint.

Start Sound

The Start Sound action starts playing a Sound value.

The Condition input controls when the action is executed. Note that if the controlled sound is already playing, the action will re-start the track. Every time the condition is TRUE, the action starts the sound.

The Sound input is the sound track started by the node – obtained from a Sound parameter.

The Loop Count input controls how many times the sound is repeated (0 for don't re-play, so it is played once, 1 for repeat once, so it's played two times and so on).

The XYZ Pos input is a vector (3 numeric values) that, when not empty or None, controls the absolute position of the sound in the 3D environment.

The Orientation input is an orientation (expressed as a XYZ euler radians vector in the text field, it can be a quaternion, a matrix or an euler angle set from the input) that controls, when not empty or None, the 3D orientation of the sound.

The XYZ Vel input is a vector that, when not empty or None, controls the velocity of the sound object in the 3D space.

The Pitch input is a float value that controls the pitch of the sound.

The Volume input is a float value that controls the volume of the single sound.

The Attenuation input is a float value that controls the attenuation of the sound (how much the intensity decays with distance).

The Distance Ref input is… I have no idea, but it is related to the attenuation factor.

The Distance Max input is the maximum distance passed wich the sound is no longer played. This is also the distance to which the attenuation factor is applied.

Note that versions < 0.2.8 the distance max value was the default one, that value is very high so the attenuation had an audible effect just at extreme distances as well.

Update Sound

The Update Sound action updates the status of a playing sound. The action is needed, for example, when the sound has to be “carried on” by some object, in which case one has to keep its position equal to the position of the moving object, or if the pitch of the sound has to be changed, for example according to the velocity of an object, to emulate the increasing note of a working engine.

The Condition input controls when the action is executed.

The XYZ Pos input is a Vector that, when not empty or None, controls the new position of the sound.

The Orientation input is a Vector (or an orientation in any form) that, when not empty or None, changes the orientation of the sound.

The XYZ Vel input controls the velocity of the sound (for doppler effects I think).

The Pitch input is the new float value to use for the pitch.

The Volume input controls the new volume of the sound.

The Attenuation input controls the new attenuation factor of the sound.

The Distance Ref is a value mapped to aud.handle.distance_reference. Don’t know what it does.

The Distance Max input controls the maximum distance passed which the sound is not audible any more.

Pause Sound

The Pause Sound action pauses a sound. If a Sound is paused, a Start Sound action will start playing it from the position it has when it was last paused.

The Condition input controls when the action is executed – and the sound paused.

The Sound input is the sound object to pause.

 Stop Sound

The Stop Sound action stops a sound. If a Sound is stopped, a Start Action will subsequently play it from the start position.

The Condition input controls when the action is executed.

The Sound input is the sound object to stop.

Random Values

The Random Values action generates random values to be used as parameters for other nodes.

The Condition input determines when the action generates the random values. Each time the condition is TRUE, the action will “roll the dices”. The action will then keep the last values until the condition becomes true again and the values are changed.

The Min input controls the minimum value (inclusive) of the random numbers.

The Max input controls the maximum value (inclusive) of the random numbers.

If both Min and Max are integer values, the generated values will be integers. Otherwise, the values will be decimals. If Min or Max are None, the minimum or maximum value of the type of the other value is used. If they are both None, the values are random decimals between 0 and 1.

Set Game Object Parent

The Set Game Object Parent action sets the parent of a Game Object. If an object is already parented to some other object, this action will replace that parent with the new one.

The Condition input controls when the action is executed.

The Child Game Object input is the game object whose parent will be changed.

The Parent Game Object input is the game object that will be used as the new parent for the Child Game Object.

The Compound boolean value controls whether the physical shape of the parent should become the enclosure of the previous one with the new child or not.

The Ghost boolean values controls whether the child object should become a physic ghost (not react to collision) while parented.

Detach Child From Parent

The Detach Child From Parent action detaches a child object from a parent one.

The Condition controls when the action is applied.

The Child Game Object input is the Game Object that will be detached from its parent.

Set Game Object Dynamics

The Set Game Object Dynamics action activates or deactivate the physics status of a Game Object set as a dynamic physics object.

The Condition input controls when the action is executed.

The Game Object input is the game object whose dynamic controls are changed. The action has an effect only if the game object has been set, in the blender interface, to have a dynamic physics controller.

The Ghost boolean input controls whether the object should react (FALSE) or not (TRUE) to incoming collisions.

The Suspend boolean input deactivates (TRUE) or activates (FALSE) the dynamic controller of the object. A falling object whose dynamic controller is suspended will stop falling, until controller is reactivated.

Set Global Value

The Set Global Value action sets the value associated with a global key for a shared dictionary, accessible by all trees in a game.

The Optional Condition input, if linked, controls the activation of the action. If the condition is not linked, the value is set once, when the tree is executed for the first time.

The ID input is a string value corresponding to the unique name of a global set of key-value pairs. That dictionary will be the one for which the value is set.

The Persistent input is a boolean value (TRUE or FALSE) that controls whether the value set for the global dictionary will be persistent or not. A persistent value is written to a file and can be read across game runs. Persistent values are meant to be used as a save/load mechanism.

The Key input is a string whose value corresponds to the key of the requested value in the global dictionary manipulated by the action.

The Value input is the value that will be associated with the given key.

Time Barrier

The Time Barrier action returns TRUE if the input condition stays TRUE for a certain amount of time. When that happens, the action output becomes TRUE for one cycle, then it waits the same amount of time before checking the input condition again. For example, if the player has to keep a button pressed for 5 seconds before something happens, we can use a button pressed condition followed by a time barrier set to 5 seconds.

The Delay Sec input is the amount of time the input condition has to remain TRUE for the action to emit a TRUE pulse.

The Repeat input controls if, after a TRUE result, the action should repeat its evaluation process.

Time Filter

The Time Filter action waits for the input condition to become TRUE, it emits a TRUE for one cycle then waits a certain amount of time before to check the input condition again. This action can be used, for example, to add object at a given time rate: if the input condition is some button pressed condition and the linked time filter has a delay of 1 tenth of a second, when the button is pressed the time filter will “emit” a TRUE signal ten times a second.

Change Current Scene

The Change Current Scene action swaps the current scene with another one.

The Condition input controls when the swap occurs (whenever the condition is TRUE)

The Scene Name input is the name (string) of the scene that will replace the currently active one.

Translate

The Translate action applies a translation to a Game Object.

The Condition controls the execution of the action (for as long as the input is the boolean value TRUE). The condition also determines the starting position of the translation (defined as the position that the object occupied when the condition changes from FALSE to TRUE).

The Moving Object input the the Game Object that will be moved.

The DX, DY and DZ inputs are the applied translation values. The object will move of that amount from the starting position.

The Local input controls whether the translation is applied to the local position or the world position of the object.

The Speed is the real time speed of the translation.

The When Done output becomes TRUE once the object has moved of the amount specified by the DX, DY and DZ axis.

Start Game, Restart Game, End Game

Yeah, I’m starting to pack stuff here.

The Start Game action starts a game defined in some blender file whenever the condition is true. The started game replaces the current one.

The Restart Game action re-starts the current game as if the blender file was reloaded and started anew.

The End Game actions terminates the current game and exists the application.