Game Creation Kit: Last modified 02/02/07 17:04:05 cw
Prev	Chapter 27. Game LogicBricks	Next

27.3. Actuators

Actuators are the executing LogicBricks. They can be compared with muscles or glands in a life form.

27.3.1. Action Actuator

Action play modes

Play: Plays the Action from "Sta" to "End" at every positive pulse the Actuator gets. Other pulses while playing are discarded.
Flipper: Plays the Action from "Sta" to "End" on activation. When the activation ends it plays backwards from the current position. When a new activation reaches the Actuator the Action will be played from the current position onwards.
Loop Stop: Plays the Action in a loop as long as the pulse is positive. It stops at the current position when the pulse turns negative.
Loop End: This plays the Action repeatedly as long as there is a positive pulse. When the pulse stops it continues to play the Action to the end and then stops.
Property: Plays the Action for exactly the frame indicated in the property entered in the field "Prop:".

27.3.2. Motion Actuator

The Motion Actuator is maybe the most important Actuator. It moves, rotates or applies a velocity to objects.

The simplest case of using a Motion Actuator is to move the object. This is done with the "dLoc" values in the third row. Every time the actuator is triggered by an impulse it moves the object by the amount given in the "dLoc" row. The three values here stand for X-, Y- and Z-axis. So when you enter a 1.0 in the first field the object is moved one unit per time unit of the game (the clock in the game engine ticks in frames, roughly 1/25 of a second, for exact timings use the Timer Property).

The buttons labeled "L" behind each row in the motion actuator, determine if the motion applied should be treated as global or local. If the button is pushed (dark green) the motion is applied based on the local axis of the object. If the button is not pressed the motion is applied based on the global (world) axis.

Force: Values in this row act as forces that apply to the object. This only works for dynamic objects.
Torque: Values in this row act as rotational forces (Torque) that apply to the object. This works only for dynamic objects. Positive values rotate counter-clock-wise.
dLoc: Offset the object as indicated in the value fields
dRot: Rotate the object for the given angle (36 is a full rotation). Positive values rotate clock-wise.
linV: Sets (overrides current velocity) the velocity of the object to the given values. When "add" is activated the velocity is added to the current velocity.
angV: Sets the angular velocity to the given values. Positive values rotate counter-clock-wise.

The Motion Actuator starts to move objects on a pulse (TRUE) and stops on a FALSE pulse. To get a movement over a certain distance, you need to send a FALSE pulse to the motion actuator after each positive pulse.

Python methods:

setForce( float x , float y , float z , bool local );

Sets the "Force" parameters for the Motion Actuator.

list [x,y,z,local] getForce( );

Gets the "Force" parameter from the Motion Actuator, local indicates if the local button is set (1).

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

Sets the "Torque" parameter for the Motion Actuator.

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

Gets the "Torque" parameter for the Motion Actuator.

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

Sets the dLoc parameters from the Motion Actuator.

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

Gets the dLoc parameters from the Motion Actuator.

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

Sets the dRot parameters for the Motion Actuator.

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

Gets the dRot parameters from the Motion Actuator.

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

Sets the linV parameters for the Motion Actuator.

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

Gets the linV parameters from the Motion Actuator.

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

Sets the angV parameters for the Motion Actuator.

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

Gets the angV parameters from the Motion Actuator.

27.3.3. Constraint Actuator

With the Constraint Actuator you can limit an object's freedom to a certain degree.

With the MenuButton you specify which channel's freedom should be constrained. With the NumberButtons "Min" and "Max" you define the minimum and maximum values for the constraint selected. To constrain an object to more than one channel simply use more than one Constraint actuator.

Python methods:

setDamp( int damp );

Sets the Damp parameter

int damp getDamp( );

Gets the Damp parameter

setMin( int min );

Sets the Min parameter

int min getMin( );

Gets the Min parameter

setMax( int max );

Sets the Max parameter

int max getMax( );

Gets the Max parameter

setMin( int min );

Sets the Min parameter

int min getMin( );

Gets the Min parameter

setLimit( int limit );

Sets the limit for the constraint. None = 1, LocX = 2, LocY = 3, LocZ = 4

int limit getLimit( );

Gets the constraint

27.3.4. Ipo Actuator

The Ipo Actuator can play the Ipo-curves for the object that owns the Actuator. If the object has a child with an Ipo (in a parenting chain) and you activate "Child" in the Actuator, the Ipo for the child is also played.

The "Force" Button will convert the "Loc" Ipo curves into forces for dynamic objects. When pressed, the "L" Button appears which cares for applying the forces locally to the objects coordinate system.

Ipo play modes

Play: Plays the Ipo from "Sta" to "End" at every positive pulse the Actuator gets. Other pulses received while playing are discarded.
Ping Pong: Plays the Ipo from "Sta" to "End" on the first positive pulse, then backwards from "End" to "Sta" when the second positive pulse is received.
Flipper: Plays the Ipo for as long as the pulse is positive. When the pulse changes to negative the Ipo is played from the current frame to "Sta".
Loop Stop: Plays the Ipo in a loop for as long as the pulse is positive. It stops at the current position when the pulse turns negative.
Loop End: This plays the Ipo repeatedly for as long as there is a positive pulse. When the pulse stops it continiues to play the Ipo to the end and then stops.
Property: Plays the Ipo for exactly the frame indicated by the property named in the field "Prop:".

Currently the following Ipos are supported by the game engine:

Mesh Objects: Loc, Rot, Size and Col
Lamps: Loc, Rot, RGB, Energy
Cameras: Loc, Rot, Lens, ClipSta, ClipEnd

Python methods:

SetType( int type );

Sets the type, 1 indicates the first play type from the menu button etc.

int type GetType( );

Sets the type, 1 indicates the first play type from the menu button

SetStart( int frame );

Sets the Sta: frame

SetEnd( int frame );

Sets the End: frame

int frameGetStart( );

Gets the Sta: frame

int frameGetEnd( );

Gets the End: frame

27.3.5. Camera Actuator

The Camera Actuator tries to mimic a real cameraman. It keeps the actor in the field of view and tries to stay at a certain distance from the object. The motion is soft and there is some delay in the reaction on the motion of the object.

Enter the object that should be followed by the camera (you can also use the Camera Actuator for non-camera objects) into the "OB:" field. The field "Height:" determines the height above the object the camera stays at. "Min:" and "Max:" are the bounds of distance from the object to which the camera is allowed to move. The "X" and "Y" buttons specify which axis of the object the camera tries to stay behind.

27.3.6. Sound Actuator

The Sound Actuator plays a SoundObject loaded using the SoundButtons (see Section 26.10). Use the MenuButton to browse and choose between the SoundObjects in the scene.

Sound play modes (MenuBut)

Play Stop: Plays the sound for as long as there is a positive pulse.
Play End: Plays the sound to the end, when a positive pulse is given.
Loop Stop: Plays and repeats the sound, when a positive pulse is given.
Loop End: Plays the sound repeatedly, when a positive pulse is given. When the pulse stops the sound is played to its end.

Custom set. (TogBut)

Checking the "Custom set." button will copy the SoundObject (sharing the sample data) and allows you to quickly change the volume and pitch of the sound with the appearing NumberButtons.

Python methods:

float gain getGain( );

Get the gain (volume) setting.

setGain( float gain );

Set the gain (volume) setting.

float pitch getPitch( );

Get the pitch setting.

setPitch( float pitch );

Set the pitch setting.

27.3.7. Property Actuator

Property modes

Assign: Assigns a value or Expression (given in the "Value" field) to a Property. For example with an Expression like "Proppy + 1" the "Assign" works like an "Add". To assign strings you need to add quotes to the string ("...").
Add: Adds the value or result of an expression to a property. To subtract simply give a negative number in the "Value:" field.
Copy: This copies a Property (here "Prop: SProp") from the Object with the name given in "OB: Sphere" into the Property "Prop: Proppy". This is an easy and safe way to pass information between objects. You cannot pass information between scenes with this Actuator!

Python methods:

SetProperty( string name );

string name GetProperty( );

SetValue( string value );

string value GetValue( );

More on using Expressions can be found in Section 26.9.

27.3.8. Edit Object Actuator

This actuator performs actions on Objects itself, like adding new objects, deleting objects, etc.

Edit Object Actuator types

Add Object

The Add Object actuator adds an object to the scene. The new object is oriented along the X-axis of the creating object.

Keep the object you'd like to add on a seperate and hidden layer. You will see an error message on the console or debug output when not following this rule.

Enter the name of the Object to add in the "OB:" field. The "Time:" field determines how long (in frames) the object should exist. The value "0" denotes it will exist forever. Be careful not to slow down the game engine by generating too many objects! If the time an object should exist is not predictable, you can also use other events (collisions, properties, etc.) to trigger an "End Object" for the added object using LogicBricks.

With the "linV" buttons it is possible to assign an initial velocity to the added object. This velocity is given in X, Y and Z components. The "L" button stands for local. When it is pressed the velocity is interpreted as local to the added object.

Python methods:

setObject( string name );

Sets the Object (name) to be added

string name getObject( );

Gets the Object name

setTime( int time );

Time in frames the added Object should exist. Zero means unlimited

int time getTime( );

Gets the time the added object should exist

setLinearVelocity( list [vx,vy,vz] );

Sets the linear velocity [Blenderunits/sec] components for added Objects.

list [vx,vy,vz] getLinearVelocity( );

Gets the linear velocity [Blenderunits/sec] components from the Actuator

gameObject* getLastCreatedObject( );

Gets a pointer to the last created object. This way you can manipulate dynamically added objects.

End Object

The "End Object" type simply ends the life of the object with the actuator when it gets a pulse. This is very useful for ending a bullet's life after a collision or something similar.

Replace Mesh

The "Replace Mesh" type, replaces the mesh of the object by a new one, given in the "ME:" field. Remember that the mesh name is not implicitly equal to the objectname.

Python methods:

setMesh( string name );

Sets the Mesh for the ReplaceMesh Actuator to "name"

string name getMesh( );

Gets the Mesh-name from the ReplaceMesh actuator

Track to

The "Track to" type, rotates the object in such a way that the Y-axis points to the target specified in the "OB:" field. Normally this happens only in the X/Y plane of the object (indicated by the "3D" button not beeing pressed). With "3D" pressed the tracking is done in 3D. The "Time:" parameter sets how fast the tracking is done. Zero means immedeately, values above zero produce a delay (are slower) in tracking.

Python methods:

setObject( string name );

string name getObject( );

setTime( int time );

Sets the time needed to track

int time getTime( );

Gets the time needed to track

setUse3D( bool 3d );

Set if "3D" should be used leading to full 3-D tracking

27.3.9. Scene Actuator

The Scene Actuator is meant for switching Scenes and Cameras in the game engine or adding overlay or background scenes.

Choose the desired action with the MenuButton and enter an existing camera or scene name into the text field. If the name does not exist, the button will be blanked!

Reset

Simply restarts and resets the scene. It has the same effect as stopping the game with ESC and restarting with PKEY.

Set Scene

Switch to the scene indicated into the text field. During the switch all properties are reset!

Python methods for all types of Scene Actuators:

setScene( char* scene );

Sets the Scene to switch to

char* scene getScene( );

Gets the Scene name from the Actuator

Set Camera

Switch to the Camera indicated in the text field.

Python methods:

setCamera( char* camera );

Sets the Camera to switch to

char* camera getCamera( );

Gets the Camera name from the Actuator

Add OverlayScene

Adds an overlay scene which is rendered on top of all other (existing) scenes.

Add BackgroundScene

Adds a background scene which will be rendered behind all other scenes.

Remove Scene

Removes a scene.

Suspend Scene

Suspends a scene until "Resume Scene" is called.

Resume Scene

Resumes a suspended Scene.

27.3.10. Random Actuator

An often-needed function for games is a random value to get more variation in movements or enemy behavior.

The Seed parameter is the value fed into the random generator as a start value for the random number generation. Because computer generated random numbers are only "pseudo" random (they will repeat after a (long) while) you can get the same random numbers again if you choose the same Seed.

Enter the name of the property you want to be filled with the random number into the "Property:" field.

Random Actuators types

Boolean Constant: This is not a random function at all, use this type to test your game logic with a TRUE or FALSE value.
Boolean Uniform: This is the classic random 50-50 pick. It results in TRUE or FALSE with an equal chance. This is like an (ideal) flip of a coin.
Boolean Bernoulli: This random function results in a boolean value of TRUE or FALSE, but instead of having the same chance for both values you can control the chance of having a TRUE pick with the "Chance" parameter. A chance of 0.5 will be the same as "Bool Uniform". A chance of 0.1 will result in 1 out of 10 cases in a TRUE (on average).
Integer Constant: For testing your logic with a value given in the "Value:" field
Integer Uniform: This random type randomly produces an integer value between (and including) "Min:" and "Max:". The classical use for it is to simulate a dice pick with "Min: 1" and "Max: 6".
Integer Poisson: The random numbers are distributed in such a way that an average of "Mean:" is reached with an infinite number of picks.
Float Constant: For debugging your game logic with a given value.
Float Uniform: This returns a random floating point value between "Min:" and "Max:".
Float Normal: Returns a weighted random number around "Mean:" and with a standard deviation of "SD:".
Float Negative Exponential: Returns a random number which is well suited to describe natural processes like radioactive decay or lifetimes of bacteria. The "Half-life time:" sets the average value of this distribution.

Python methods:

setSeed( int seed );

Sets the random seed (the init value of the random generation)

int seed getSeed( );

Gets the random seed (the init value of the random generation) from the Actuator

float para1 getPara1( );

Gets the first parameter for the selected random distribution

float para2 getPara2( );

Gets the second parameter for the selected random distribution

setProperty( string propname );

Sets the Property to which the random value should go

string propname getProperty( );

Gets the Property name from the Actuator

setDistribution( int dist );

Set the distribution, "dist = 1" means the fist choice from the type MenuButton

int dist getDistribution( );

Gets the random distribution method from the Actuator

27.3.11. Message Actuator

This LogicBrick sends a message out, which can be received and processed by the Message Sensor.

The "To:" field indicates that the message should only be sent to objects with the Property indicated by "To:". The subject of the message is indicated in the "Subject:" field. With these two possibilities you can control the messaging very effectively.

The body (content) of the message can either be a text ("Body:") string or the content of a Property when "T/P" is activated ("Propname:"). See Section 27.1.11 on how to get the body of a message.

Python methods:

setToPropName( char* propname );

Sets the property name the message should be send to.

setSubject( char* subject );

Sets the subject of the message.

setBody( char* body );

Sets the body of the message.

setBodyType( int bodytype );

Sets whether the body should be text or a Property name.