Chapter 27. Game LogicBricks

Table of Contents
27.1. Sensors
27.2. Controllers
27.3. Actuators

The game logic in Blenders game engine is assembled in the RealtimeButtons. Here you wire the different LogicBricks together. The following is a brief description of all the LogicBricks currently available.

27.1. Sensors

Sensors act like real senses; they can detect collisions, feel (Touch), smell (Near), view (Ray, Radar).

27.1.1. Always Sensor

The most basic Sensor is the Always Sensor. It is also a good example for the common buttons every sensor has.

Figure 27-1. Common elements for Sensors



The button labeled "X" deletes the Sensor from the game logic. This happens without a confirmation, so be careful. The MenuButton to the right of the delete button (here labeled "Always") allows you to choose the type of Sensor. Click and hold it with the left mouse button to get the pop up menu. Next is a TextButton, which holds the name of the Sensor. Blender assigns the name automatically on creation. Click the name with the left mouse button to change the name with the keyboard.

Note

Name your LogicBricks and Blender objects to keep track of your scenes. A graphical logic scheme can become very complex.

With the small arrow button you can hide the contents of the LogicBrick, so it only shows the top bar. This is very handy in complex scenes.

The next row of buttons is used to determine how and at which frequency a Sensor is "firing". This topic is a bit complex, so we will give examples in more than one part of this documentation.

General things on pulses

Pulses coming from Sensors trigger both Controllers and Actuators. A pulse can have two values, TRUE or FALSE.

Each Controller is always evaluated when it receives a pulse, it doesn't matter whether the pulse is TRUE or FALSE. The input "gate" of a Controller remembers the last pulse value. This is necessary for Controllers being linked by multiple Sensors, then it can still do a logical AND or OR operation on all inputs. When a Controller is triggered, and after the evaluation of all inputs, it can either decide to execute the internal script or to send a pulse to the Actuators.

An Actuator reacts to a pulse in a different way, with a TRUE pulse it switches itself ON (makes itself active), with a FALSE pulse it turns itself OFF.

Figure 27-2. Pulse Mode Buttons

The first button activates the positive pulse mode. Every time the Sensor fires a pulse it is a positive pulse. This can be used, for example to start a movement with an Motion Actuator. The button next to it activates the negative pulse mode, which can be used to stop a movement.

Note

If none of the pulse mode buttons are activated the Always Sensor fires exactly one time. This is very useful for initialising stuff at the start of a game.

The button labeled "f:" (set to 41 here), determines the delay between two pulses fired by the Sensor. The value of "f:" is given as frames.

The "Inv" button inverts the pulse, so a positive (TRUE) pulse will become negative (FALSE) and vice versa.

27.1.2. Keyboard Sensor

The Keyboard Sensor is one of the most often used Sensors because it provides the interface between Blender and the user.



The pulse mode buttons are common for every Sensor so they have the same functionality as described for the Always Sensor.

By activating the "All keys" Button, the Sensor will react to every key. In the "Hold" fields you can put in modifier keys, which need to be held while pressing the main key.

The Keyboardsensor can be used for simple text input. To do so, fill in the Property which should hold the typed text (you can use Backspace to delete chars) into the "Target:" field. The input will be active as long the Property in "LogToggle:" is "TRUE".

Python methods:

Import the Gamekeys module (see Section 28.3.3) to have symbolic names for the keys.

setKey( int key );

Sets the Key on which the Sensor reacts

int key getKey( );

Gets the key on which the Sensor reacts

setHold1( int key );

Sets the first modifier key

int key getHold1( );

Gets the first modifier key

setHold2( int key );

Sets the second modifier key

int key getHold2( );

Gets the second modifier key

list keys getPressedKeys( );

Gets the keys (including modifier)

list keys getCurrentlyPressedKeys( );

Gets the keys (including modifier) currently held

27.1.3. Mouse Sensor

Currently, the Sensor is able to watch for mouse clicks, mouse movement or a mouse over. To get the position of the mouse cursor as well you need to use a Python-script.

Use the MenuButton to choose between the Mouse Sensor types:

Mouse Sensor types

Left/Middle/Right Button



The sensor gives out a pulse when the correlate mouse button is pressed.

Python methods:

int xpos getXPosition( );

Gets the mouse's X-position

int ypos getYPosition( );

Gets the mouse's Y-position

Movement



The sensor gives out a pulse when the mouse is moved.

Python methods:

int xpos getXPosition( );

Gets the mouse x-position

int ypos getYPosition( );

Gets the mouse y-position

Mouse over



The sensor gives a pulse when the mouse cursor is over the object.

27.1.4. Touch Sensor

The Touch Sensor fires a pulse when the object it is assigned to, touches a material. If you enter a material name into the "MA:" text field it only reacts to this material otherwise it reacts to all touch.



Python methods:

The Touchsensor inherits from the Collision Sensor, so it provides the same Methods, hence the Methode names.

setProperty( (char* matname) );

Sets the Material the Touch Sensor should react to

char* matname getProperty( );

Gets the Material the Touch Sensor reacts to

gameObject obj getHitObject( );

Returns the touched Object

list objs getHitObjectList( );

Returns a list of touched objects

27.1.5. Collison Sensor

The Collision Sensor is a general Sensor used to detect contact between objects. Besides reacting to materials it is also capable of detecting Properties of an object. Therefore you can switch the input field from Material to Property by clicking on the "M/P" button.



Python methods:

setProperty( (char* name) );

Sets the Material or Property the Collision Sensor should react to

char* name getProperty( );

Gets the Material or Property the Collision Sensor reacts to

gameObject obj getHitObject( );

Returns the colliding Object

list objs getHitObjectList( );

Returns a list of objects that have collided

27.1.6. Near Sensor

The near sensor reacts to actors near the object with the sensor.



Tip

The near sensor only senses objects of the type "Actor" (a dynamic object is also an actor).

If the "Property:" field is empty, the near sensor reacts to all actors in its range. If filled with a property name, the sensor only reacts to actors carrying a property with that name.

The spherical range of the near sensor you set with the "Dist" NumberButton. The "Reset" value defines at what distance the near sensor is reset again.

Python methods:

setProperty( (char* propname) );

Sets the Property the Near Sensor should react to

char* propname getProperty( );

Gets the Property the Near Sensor reacts to

list gameObjects getHitObjectList( );

Returns a list of game objects detected by the Near Sensor.

gameObject obj getHitObject( );

Returns the object which triggered the Sensor

27.1.7. Radar Sensor

The Radar Sensor acts like a real radar. It looks for an object along the axis indicated with the axis buttons "X, Y, Z". If a property name is entered into the "Prop:" field, it only reacts to objects with this property.



In the "Ang:" field you can enter an opening angle for the radar. This equals the angle of view for a camera. The "Dist:" setting determines how far the Radar Sensor can see.

Objects can't block the line of sight for the Radar Sensor. This is different for the Ray Sensor (see Section 27.1.10). You can combine them for making a radar that is not able to look through walls.

Python methods:

setProperty( (char* name) );

Sets the Property that the Radar Sensor should react on

char* name getProperty( );

Gets the name of the Property

gameObject obj getHitObject( );

Returns the detected object that triggered the sensor

list objs getHitObjectList( );

Returns a list of detected objects

27.1.8. Property Sensor

The Property Sensor logically checks a Property attached to the same object.



The "Equal" type Property Sensor checks for equality of the property given in the "Prop:" field and the value in "Value:". If the condition is true, it fires pulses according to the pulse mode settings.

The "Not Equal" Property Sensor checks for inequality and then fires its pulses.



The "Interval" type property sensor fires its pulse if the value of property is inside the interval defined by "Min:" and "Max:". This sensor type is especially helpful for checking float values, which you can't depend on to reach a value exactly. This is most common with the "Timer" Property.

The "Changed" Property Sensor gives out pulses every time a Property is changed. This can, for example, happen through a Property Actuator, a Python script or an Expression.

Python methods:

setProperty( (char* propname) );

Sets the Property to check

char* propname getProperty( );

Gets the Property to check

setType( (int type) );

Sets the type of the Property Sensor.
  1. Equal

  2. Not Equal

  3. Interval

  4. Changed



char* propname getProperty( );

Gets the type of the Property Sensor

setValue( (char* expression) );

Sets the value to check (as expression)

char* expression getValue( );

Gets the value to check (as expression)

27.1.9. Random Sensor

The Random Sensor fires a pulse randomly according to the pulse settings (50/50 pick).



Tip

With a seed of zero the Random Sensor works like an Always Sensor, which means it fires a pulse every time.

Python methods:

setSeed( (int seed) );

Set the seed for the random generation

int seed getSeed( );

Gets the seed for the Random Sensor

int seed getLastDraw( );

Gets the last draw from the Random Sensor

27.1.10. Ray Sensor

The Ray Sensor casts a ray for the distance set into the NumberButton "Range". If the ray hits an object with the right Property or the right Material the Sensor fires its Pulse.

Important

Other objects block the ray, so that it can't see through walls.



Without a material or property name filled in, the Ray Sensor reacts to all objects.

Python methods:

list [x,y,z] getHitPosition( );

Returns the position where the ray hits the object.

list [x,y,z] getHitNormal( );

Returns the normal vector how the ray hits the object.

list [x,y,z] getRayDirection( );

Returns the vector of the Ray direction

gameObject obj getHitObject( );

Returns the hit Object

27.1.11. Message Sensor



The Message Sensor fires its pulse when a Message arrives for the object carrying the Sensor. The "Subject:" field can be used to filter messages matching the subject.

Python methods:

list bodies getBodies( );

Returns a list containing the message bodies arrived since last call

int messages getFrameMessageCount( );

Returns the number of messages received since the last frame

setSubjectFilterText( string subject );

Sets the subject for the Message Sensor