Dev:Source/GameEngine/2.49/Logic

Collection of svn logs for 2.48 game logic work:

Delta Loc/Rot/Scale Ipo curves

Delta Loc/Rot/Scale Ipo curve are now supporting in the BGE with the following limitations:

1. All Ipo channels are now independent.

In Blender 2.45, all 3 Loc Ipo channels were automatically set together. For example, having just a LocX Ipo channel was sufficient to fix the X, Y and Z coordinates, with the Y and Z value taken from the object original Y and Z location in Blender. The same was true for the 3 Rot and the 3 Scale Ipo channels: the missing channels were assumed to have constant value taken from the object original orientation/scale in Blender.

With this patch, all Ipo channels are now independent. THIS WILL CREATE BACKWARD COMPATIBILITY PROBLEM if you omit to define the 3 channels of a same type together in your Blend file: the undefined Loc, Rot, Scale coordinates of the object will be influenced by the parent/spawner Loc/Rot/Scale in case the object is a child or dynamically created.

2. Delta Loc, Rot, Scale are now supported with the following

limitations:

• The delta Loc/Rot Ipo modify the object global (NOT local)

location/orientation

• The delta Scale change the object local scale
• The delta Ipo curves are relative to the object starting

Loc/Rot/Scale when the Ipo was first activated; after that, the delta Ipo becomes global. This means that the object will return to this initial Loc/Rot/Scale when you later restart the Ipo curve, even if you had changed the object Loc/Rot/Scale in the meantime. Of course this applies only to the specific Loc/Rot/Scale coordinate that are defined in the Ipo channels as the channels are now independent.

3. Non-Zero values in delta Ipo Curves to be taken note of

When the objects are converted from Blender to the BGE, the delta Loc/Rot/Scale that might result from initial non-zero values in delta Ipo Curves will be ignored. However, as soon as the delta Ipo curve is activated, the non-zero values will be taken into account and the object will jump to the same Loc/Rot/Scale situation as in Blender. Note that delta Ipo curves with initial non-zero values is bad practice; logically, a delta Ipo curve should always start from 0.

4. Defining Global & Delta Channel of same type

If you define both a global and delta channel of the same type (LocX and DLocX), the result will be a global channel equivalent to the sum of the two channels (LocX+DLocX).

New rayCastTo() python method for KX_GameObject:

rayCastTo(other,dist,prop)

Look towards another point/KX_GameObject and return first object hit within dist with a property that match prop, None if no object found or if it does not match prop.

Parameters:

other = 3-tuple (xyz coordinates) or object reference (target=center of object) (type = list [x,y,z] or object reference)

dist = max distance of detection (can be negative => look behind) If 0 or omitted => detect up to other (type=float)

prop = property name that object must have If empty or omitted => detect any object (type=string)

Realtime SetParent function in the BGE

This patch consists in new KX_GameObject::SetParent() and KX_GameObject::RemoveParent() functions to create and destroy parent relation during game. These functions are accessible through python and through a new actuator KX_ParentActuator. Function documentation in PyDoc. The object keeps its orientation, position and scale when it is parented but will further rotate, move and scale with its parent from that point on. When the parent relation is broken, the object keeps the orientation, position and scale it had at that time. The function has no effect if any of the X/Y/Z scale of the object or its new parent are below Epsilon.

Anaglyph settings

The best rules for stereo rendering are now applied to Blender. Here is the new situation: 1) The focal distance is now settable through the GUI: select the camera (each camera can have a different setting) and go to the camera data (F9): the "Dof Dist" and "Dof Ob" can be used to set the focal distance for that camera. The "Dof Ob" is interesting because it sets the focal distance so that the center this object will appear at the surface of the screen when running the game. 2) The eye separation is automatically set to focal_distance/30, which is considered to be a reasonable value. If you need a different value, you can always use Python scripting.

Notes: - If you switch camera during the game, the focal distance will also change unless you have set the focal distance by scripting, in which case it overwrites the focal distance setting of all cameras. - If you don't set the focal distance in the camera data or by scripting, the default value will be used. The default value corresponds more of less to the near clipping plane which means that all the objects will be very far with little 3D effect. - If you don't set the eye separation by scripting, it is automatically computed as focal_distance/30, regardless on how the focal distance was set.

Set Scene support

BGE patch: support Set Scene in BGE. Linked Set Scene should have no name conflict in Object, Object data and Action of the main scene to avoid confusion in Python scripting. Nested Set Scene are supported. You will need Python scripting to create cross references between objects in the main scene and the Set (e.g TrackTo actuator)

Shape Action support

BGE Patch: Add Shape Action support

Shape Action are now supported in the BGE. A new type of actuator "Shape Action" is available on mesh objects. It can be combined with Action actuator on parent armature. Only relative keys are supported. All the usual action options are available: type, blending, priority, Python API. Only actions with shape channels should be specified of course, otherwise the actuator has no effect. Shape action will still work after a mesh replacement provided that the new mesh has compatible shape keys.

Logic states

BGE patch: add state engine support in the logic bricks.

This patch introduces a simple state engine system with the logic bricks. This system features full backward compatibility, multiple active states, multiple state transitions, automatic disabling of sensor and actuators, full GUI support and selective display of sensors and actuators. Note: Python API is available but not documented yet. It will be added asap.

State internals

The state system is object based. The current state mask is stored in the object as a 32 bit value; each bit set in the mask is an active state. The controllers have a state mask too but only one bit can be set: a controller belongs to a single state. The game engine will only execute controllers that belong to active states. Sensors and actuators don't have a state mask but are effectively attached to states via their links to the controllers. Sensors and actuators can be connected to more than one state. When a controller becomes inactive because of a state change, its links to sensors and actuators are temporarily broken (until the state becomes active again). If an actuator gets isolated, i.e all the links to controllers are broken, it is automatically disabled. If a sensor gets isolated, the game engine will stop calling it to save CPU. It will also reset the sensor internal state so that it can react as if the game just started when it gets reconnected to an active controller. For example, an Always sensor in no pulse mode that is connected to a single state (i.e connected to one or more controllers of a single state) will generate a pulse each time the state becomes active. This feature is not available on all sensors, see the notes below.

GUI

This system system is fully configurable through the GUI: the object state mask is visible under the object bar in the controller's colum as an array of buttons just like the 3D view layer mask. Click on a state bit to only display the controllers of that state. You can select more than one state with SHIFT-click. The All button sets all the bits so that you can see all the controllers of the object. The Ini button sets the state mask back to the object default state. You can change the default state of object by first selecting the desired state mask and storing using the menu under the State button. If you define a default state mask, it will be loaded into the object state make when you load the blend file or when you run the game under the blenderplayer. However, when you run the game under Blender, the current selected state mask will be used as the startup state for the object. This allows you to test specific state during the game design.

The controller display the state they belong to with a new button in the controller header. When you add a new controller, it is added by default in the lowest enabled state. You can change the controller state by clicking on the button and selecting another state. If more than one state is enabled in the object state mask, controllers are grouped by state for more readibility.

The new Sta button in the sensor and actuator column header allows you to display only the sensors and actuators that are linked to visible controllers.

A new state actuator is available to modify the state during the game. It defines a bit mask and the operation to apply on the current object state mask:

Cpy: the bit mask is copied to the object state mask. Add: the bits that set in the bit mask will be turned on in the object state mask. Sub: the bits that set in the bit mask will be turned off in the object state mask. Inv: the bits that set in the bit mask will be inverted in the objecyy state mask.

• Although states have no name, a simply convention consists in using the name of the first controller of the state as the state name. The GUI will support that convention by displaying as a hint the name of the first controller of the state when you move the mouse over a state bit of the object state mask or of the state actuator bit mask.
• Each object has a state mask and each object can have a state engine but if several objects are part of a logical group, it is recommended to put the state engine only in the main object and to link the controllers of that object to the sensors and actuators of the different objects.
• When loading an old blend file, the state mask of all objects and controllers are initialized to 1 so that all the controllers belong to this single state. This ensures backward compatibility with existing game.
• When the state actuator is activated at the same time as other actuators, these actuators are guaranteed to execute before being eventually disabled due to the state change. This is useful for example to send a message or update a property at the time of changing the state.
• Sensors that depend on underlying resource won't reset fully when they are isolated. By the time they are acticated again, they will behave as follow:
• keyboard sensor: keys already pressed won't be detected. The keyboard sensor is only sensitive to new key press.
• collision sensor: objects already colliding won't be detected. Only new collisions are detected.
• near and radar sensor: same as collision sensor.

NAND, NOR, XOR, XNOR controllers.

• NAND controller is an inverted AND controller: the output is 1 if any of the input is 0.
• NOR controller is an inverted OR controller: the output is 0 if any of the input is 1.
• XOR controller is an exclusive OR: the output is 1 if and only if one input is 1 and all the other inputs are 0.
• XNOR controller is an inverted XOR: the output is 0 if and only if one input is 0 and all the other inputs are 0.

The NAND, NORT and XNOR controllers are very usefull to create complementary outputs to start and stop actuators synchronously. MSCV project files updated.

Damping and clamping option to motion actuator.

This patch introduces two options for the motion actuator:

damping: number of frames to reach the target velocity. It takes into account the startup velocityin the target velocity direction and add 1/damping fraction of target velocity until the full velocity is reached. Works only with linear and angular velocity. It will be extended to delta and force motion method in a future release.

clamping: apply the force and torque as long as the target velocity is not reached. If this option is set, the velocity specified in linV or angV are not applied to the object but used as target velocity. You should also specify a force in force or torque field: the force will be applied as long as the velocity along the axis of the vector set in linV or angV is not reached. Works best in low friction environment.

Automatic support for armature driven shape keys.

To take advantage of this feature, you must have a mesh with relative shape keys and shape Ipo curves with drivers referring to bones of the mesh's parent armature. The BGE will automatically detect the dependency between the shape keys and the armature and execute the Ipo drivers during the rendering of the armature actions. This technique is used to make the armature action more natural: the shape keys compensate in places where the armature deformation is uggly and the drivers make sure that the shape correction is synchronized with the bone position.

Note: This is not compatible with shape actions; BLender does not allow to have Shape Ipo Curves and Shape actions at the same time.

Edit Object Dynamics Actuator.

Add enable/disable dynamics actuator under the "Edit Object" category. The Enable/disable rigid body option is also availale but not implemented.

Servo control motion actuator, Distance constraint actuator, Orientation constraint actuator, Actuator sensor

General

- Removal of Damp option in motion actuator (replaced by Servo control motion). - No PyDoc at present, will be added soon.

Generalization of the Lvl option

A sensor with the Lvl option selected will always produce an event at the start of the game or when entering a state or at object creation. The event will be positive or negative depending of the sensor condition. A negative pulse makes sense when used with a NAND controller: it will be converted into an actuator activation.

Servo control motion

A new variant of the motion actuator allows to control speed with force. The control if of type "PID" (Propotional, Integral, Derivate): the force is automatically adapted to achieve the target speed. All the parameters of the servo controller are configurable. The result is a great variety of motion style: anysotropic friction, flying, sliding, pseudo Dloc... This actuator should be used in preference to Dloc and LinV as it produces more fluid movements and avoids the collision problem with Dloc.

• LinV : target speed as (X,Y,Z) vector in local or world coordinates (mostly useful in local coordinates).
• Limit: the force can be limited along each axis (in the same coordinates of LinV). No limitation means that the force will grow as large as necessary to achieve the target speed along that axis. Set a max value to limit the accelaration along an axis (slow start) and set a min value (negative) to limit the brake force.
• P: Proportional coefficient of servo controller, don't set directly unless you know what you're doing.
• I: Integral coefficient of servo controller. Use low value (<0.1) for slow reaction (sliding), high values (>0.5) for hard control. The P coefficient will be automatically set to 60 times the I coefficient (a reasonable value).
• D: Derivate coefficient. Leave to 0 unless you know what you're doing. High values create instability.

Notes:

• This actuator works perfectly in zero friction environment: the PID controller will simulate friction by applying force as needed.
• This actuator is compatible with simple Drot motion actuator but not with LinV and Dloc motion.
• (0,0,0) is a valid target speed.
• All parameters are accessible through Python.

Distance constraint actuator

A new variant of the constraint actuator allows to set the distance and orientation relative to a surface. The controller uses a ray to detect the surface (or any object) and adapt the distance and orientation parallel to the surface.

• Damp: Time constant (in nb of frames) of distance and orientation control.
• Dist: Select to enable distance control and set target distance. The object will be position at the given distance of surface along the ray direction.
• Direction: chose a local axis as the ray direction.
• Range: length of ray. Objecgt within this distance will be detected.
• N: Select to enable orientation control. The actuator will change the orientation and the location of the object so that it is parallel to the surface at the vertical of the point of contact of the ray.
• M/P  : Select to enable material detection. Default is property detection.
• Property/Material: name of property/material that the target of ray must have to be detected. If not set, property/material filter is disabled and any collisioning object within range will be detected.
• PER  : Select to enable persistent operation. Normally the actuator disables itself automatically if the ray does not reach a valid target.
• time : Maximum activation time of actuator. 0 : unlimited.
• 0: number of frames before automatic deactivation.
• rotDamp: Time constant (in nb of frame) of orientation control.
• 0 : use Damp parameter.
• 0: use a different time constant for orientation.

Notes:

• If neither N nor Dist options are set, the actuator does not change the position and orientation of the object; it works as a ray sensor.
• The ray has no "X-ray" capability: if the first object hit does not have the required property/material, it returns no hit and the actuator disables itself unless PER option is enabled.
• This actuator changes the position and orientation but not the speed of the object. This has an important implication in a gravity environment: the gravity will cause the speed to increase although the object seems to stay still (it is repositioned at each frame). The gravity must be compensated in one way or another.
• The new servo control motion actuator is the simplest way: set the target speed along the ray axis to 0 and the servo control will automatically compensate the gravity.
• This actuator changes the orientation of the object and will conflict with Drot motion unless it is placed BEFORE the Drot motion actuator (the order of actuator is important)
• All parameters are accessible through Python.

Orientation constraint

A new variant of the constraint actuator allows to align an object axis along a global direction.

• Damp : Time constant (in nb of frames) of orientation control.
• X,Y,Z: Global coordinates of reference direction.
• time : Maximum activation time of actuator. 0 : unlimited.
• 0: number of frames before automatic deactivation.

Notes:

• (X,Y,Z) = (0,0,0) is not a valid direction
• This actuator changes the orientation of the object and will conflict with Drot motion unless it is placed BEFORE the Drot motion actuator (the order of actuator is important).
• This actuator doesn't change the location and speed. It is compatible with gravity.
• All parameters are accessible through Python.

Actuator sensor

This sensor detects the activation and deactivation of actuators of the same object. The sensor generates a positive pulse when the corresponding sensor is activated and a negative pulse when it is deactivated (the contrary if the Inv option is selected). This is mostly useful to chain actions and to detect the loss of contact of the distance motion actuator.

Notes:

• Actuators are disabled at the start of the game; if you want to detect the On-Off transition of an actuator after it has been activated at least once, unselect the Lvl and Inv options and use a NAND controller.
• Some actuators deactivates themselves immediately after being activated. The sensor detects this situation as an On-Off transition.
• The actuator name can be set through Python.

New Add mode for Ipo actuator

A new Add button, mutually exclusive with Force button, is available in the Ipo actuator. When selected, it activates the Add mode that consists in adding the Ipo curve to the current object situation in world coordinates, or parent coordinates if the object has a parent. Scale Ipo curves are multiplied instead of added to the object current scale. If the local flag is selected, the Ipo curve is added (multiplied) in the object's local coordinates. Delta Ipo curves are handled identically to normal Ipo curve and there is no need to work with Delta Ipo curves provided that you make sure that the Ipo curve starts from origin. Origin means location 0 for Location Ipo curve, rotation 0 for Rotation Ipo curve and scale 1 for Scale Ipo curve.

The "current object situation" means the object's location, rotation and scale at the start of the Ipo curve. For Loop Stop and Loop End Ipo actuators, this means at the start of each loop. This initial state is used as a base during the execution of the Ipo Curve but when the Ipo curve is restarted (later or immediately in case of Loop mode), the object current situation at that time is used as the new base.

For reference, here is the exact operation of the Add mode for each type of Ipo curve (oLoc, oRot, oScale, oMat: object's loc/rot/scale and orientation matrix at the start of the curve; iLoc, iRot, iScale, iMat: Ipo curve loc/rot/scale and orientation matrix resulting from the rotation).

Location

  Local=false: newLoc = oLoc+iLoc
  Local=true : newLoc = oLoc+oScale*(oMat*iLoc)

Rotation

  Local=false: newMat = iMat*oMat
  Local=true : newMat = oMat*iMat

Scale

  Local=false: newScale = oScale*iScale
  Local=true : newScale = oScale*iScale

Add+Local mode is very useful to have dynamic object executing complex movement relative to their current location/orientation. Of cource, dynamics should be disabled during the execution of the curve.

Several corrections in state system

• Object initial state is taken into account when adding object dynamically
• Fix bug with link count when adding object dynamically
• Fix false on-off detection for Actuator sensor when actuator is trigged on negative event.
• Fix Parent actuator false activation on negative event
• Loop Ipo curve not restarting at correct frame when start frame is different from one.

DUPLIGROUP option supported in BGE.

Blender duplicates groups in the 3D view at the location of objects having the DUPLIGROUP option set. This feature is now supported in the BGE: the groups will be instantiated as in the 3D view when the scene is converted. This is useful to populate a scene with multiple enemies without having to actually duplicate the objects in the blend file.

• The BGE applies the same criteria to instantiate the group as Blender to display them: if you see the group in the 3D view, it will be instantiated in the BGE.
• Groups are instantiated as if the object having the DUPLIGROUP option (usually an empty) executed an AddObject actuator on the top objects of the group (objects without parent).
• As a result, only intra-group parent relationship is supported: the BGE will not instantiate objects that have parents outside the group.
• Intra-group logic bricks connections are preserved between the duplicated objects, even between the top objects of the group.
• For best result, the state engine of the objects in the group should be self-contained: logic bricks should only have intra-group connections. Use messages to communicate with state engines outside the group.
• Nested groups are supported: if one or more objects in the group have the DUPLIGROUP option set, the corresponding groups will be instantiated at the corresponding position and orientation.
• Nested groups are instantiated as separate groups, not as one big group.
• Linked groups are supported as well as groups containing objects from the active layers.
• There is a difference in the way Blender displays the groups in the 3D view and how BGE instantiates them: Blender does not take into account the parent relationship in the group and displays the objects as if they were all children of the object having the DUPLIGROUP option. That's correct for the top objects of the group but not for the children. Hence the orientation of the children objects may be different in the BGE.
• An AddGroup actuator will be added in a future release.

It follows the Blender convention to duplicate groups in the BGE so that the objects will be created with the location and orientation as in Blender. Note that the BGE handles scaling in a parent tree differently than Blender. To avoid discrepencies between the 3D view and the BGE, use only isotropic scaling on all your objects except the leaf objects (i.e. without children) that can have anisotropic scaling

Support for partial hierarchy in dupligroup instantiation

(and removal of links that point to inactive objects during group instantiation.)

This situation corresponds to a group containing only a portion of a parent hierarchy (the Apricot team needed that to avoid logic duplication). The BGE will instantiate only the children that are in the group so that it follows the 3D view more closely. As a result, the logic links to the objects in the portion of the hierarchy that was not replicated will point to inactive objects (if the groups are stored in inactive layers as they should be). To keep the logic system consistent, these links are automatically removed. This last part of the patch is a general fix that could go in 2.47 but as this situation does not normally occurs in pre-2.47 games, it is not needed.

Relinking actuators

Relink actuators with target within group when duplicating group; generalize protection against object deletion for all actuators that point to objects.

Certain actuators hold a pointer to an objects: Property, SceneCamera, AddObject, Camera, Parent, TractTo. When a group is duplicated, the actuators that point to objects within the group will be relinked to point to the replicated objects and not to the original objects. This helps to setup self-contained group with a camera following a character for example. This feature also works when adding a single object (and all its children) with the AddObject actuator.

The second part of the patch extends the protection against object deletion to all the actuators of the above list (previously, only the TrackTo, AddObject and Property actuators were protected). In case the target object of these actuators is deleted, the BGE won't crash.

Min/max parameters to orientation constraint actuator

The min/max parameters define a minimum/maximum angle that the object axis can have with the reference direction without being constrainted. The angle is expressed in degree and is limited to 0-180 range. The min/max parameters define a conical free zone around the reference direction.

If the object axis is outside that free zone, the actuator will tend to put it back using as a temporary reference direction the vector that is exactly at min or max degree of the reference direction (depending if the axis angle is below the minimum or above the maximum) and is located in the plane formed by the axis and the reference direction.

With a low damping value, this is equivalent to clamping the axis orientation within min/max degree of the reference direction.

Backward compatibility corresponds to the absence of free zone: min = max = 0.

Runtime group duplication

BGE patch: support runtime duplication of groups. Adding an object with Dupligroup option set will cause the group to be instantiated. No special actuator is needed for this feature, just put dupligroup objects in inactive layers and add them dynamically

logic optimization: remove inactive sensors from logic manager.

With this patch, only sensors that are connected to active states are actually registered in the logic manager. Inactive sensors won't take any CPU, especially the Radar and Near sensors that use a physical object for the detection: these objects are removed from the physics engine.

To take advantage of this optimization patch, you need to define very light idle state when the objects are inactive: make them transparent, suspend the physics, keep few sensors active (e,g a message sensor to wake up), etc.

New Delay sensor (derived from patch #17472)

Introduction of a new Delay sensor that can be used to generate positive and negative triggers at precise time, expressed in number of frames. The delay parameter defines the length of the initial OFF period. A positive trigger is generated at the end of this period. The duration parameter defines the length of the ON period following the OFF period. A negative trigger is generated at the end of the ON period. If duration is 0, the sensor stays ON and there is no negative trigger. The sensor runs the OFF-ON cycle once unless the repeat option is set: the OFF-ON cycle repeats indefinately (or the OFF cycle if duration is 0).

The new generic SCA_ISensor::reset() Python function can be used at any time to restart the sensor: the current cycle is interrupted and no trigger is generated.

BGE state system improvement

The sensor with Level option enabled will trigger the controller of a newly activated state, even if the sensor is already connected to an active state; new isTriggered() python function to determine which sensor triggered the current controller.

Previously, this behaviour was available only for sensors that were not connected to any active state, which was forcing the game designer to duplicate sensors in some cases. For example the Always sensors used to initialize the states needed to be duplicated for each state. With this patch, a single Always sensor with Level option enabled will suffice to initialize all the states. A Python controller can determine which sensor did trigger with the new SCA_ISensor::isTriggered() function.

Raycast improvements

BGE patch: KX_GameObject::rayCast() improvements to have X-Ray option, return true face normal and hit polygon information.

rayCast(to,from,dist,prop,face,xray,poly):

The face paremeter determines the orientation of the normal:

• 0 or omitted => hit normal is always oriented towards the ray origin (as if you casted the ray from outside)
• 1 => hit normal is the real face normal (only for mesh object, otherwise face has no effect)

The ray has X-Ray capability if xray parameter is 1, otherwise the first object hit (other than self object) stops the ray.

The prop and xray parameters interact as follow:

• prop off, xray off: return closest hit or no hit if there is no object on the full extend of the ray.
• prop off, xray on : idem.
• prop on, xray off: return closest hit if it matches prop, no hit otherwise.
• prop on, xray on : return closest hit matching prop or no hit if there is no object matching prop on the full extend of the ray.

if poly is 0 or omitted, returns a 3-tuple with object reference, hit point and hit normal or (None,None,None) if no hit. if poly is 1, returns a 4-tuple with in addition a KX_PolyProxy as 4th element.

The KX_PolyProxy object holds information on the polygon hit by the ray: the index of the vertex forming the poylgon, material, etc.

Attributes (read-only):

matname: The name of polygon material, empty if no material.
material: The material of the polygon
texture: The texture name of the polygon.
matid: The material index of the polygon, use this to retrieve vertex proxy from mesh proxy
v1: vertex index of the first vertex of the polygon, use this to retrieve vertex proxy from mesh proxy
v2: vertex index of the second vertex of the polygon, use this to retrieve vertex proxy from mesh proxy
v3: vertex index of the third vertex of the polygon, use this to retrieve vertex proxy from mesh proxy
v4: vertex index of the fourth vertex of the polygon, 0 if polygon has only 3 vertex
    use this to retrieve vertex proxy from mesh proxy
visible: visible state of the polygon: 1=visible, 0=invisible
collide: collide state of the polygon: 1=receives collision, 0=collision free.

Methods:

 getMaterialName(): Returns the polygon material name with MA prefix
 getMaterial(): Returns the polygon material
 getTextureName(): Returns the polygon texture name
 getMaterialIndex(): Returns the material bucket index of the polygon. 
 getNumVertex(): Returns the number of vertex of the polygon.
 isVisible(): Returns whether the polygon is visible or not
 isCollider(): Returns whether the polygon is receives collision or not
 getVertexIndex(vertex): Returns the mesh vertex index of a polygon vertex
 getMesh(): Returns a mesh proxy

New methods of KX_MeshProxy have been implemented to retrieve KX_PolyProxy objects:

 getNumPolygons(): Returns the number of polygon in the mesh.
 getPolygon(index): Gets the specified polygon from the mesh.

More details in PyDoc.

Bullet 2.71 update

BGE patch: new Physics button and margin parameter in Logic panel. Change subversion.

The Physics button controls the creation of a physics representation of the object when starting the game. If the button is not selected, the object is a pure graphical object with no physics representation and all the other physics buttons are hidden. Selecting this button gives access to the usual physics buttons. The physics button is enabled by default to match previous Blender behavior.

The margin parameter allows to control the collision margin from the UI. Previously, this parameter was only accessible through Python. By default, the collision margin is set to 0.0 on static objects and 0.06 on dynamic objects. To maintain compatibility with older games, the collision margin is set to 0.06 on all objects when loading older blend file.

• Note about the collision algorithms in Bullet 2.71

Bullet 2.71 handles the collision margin differently than Bullet 2.53 (the previous Bullet version in Blender). The collision margin is now kept "inside" the object for box, sphere and cylinder bound shapes. This means that two objects bound to any of these shape will come in close contact when colliding. The static mesh, convex hull and cone shapes still have their collision margin "outside" the object, which leaves a space of 1 or 2 times the collision margin between objects.

The situation with Bullet 2.53 was more complicated, generally leading to more space between objects, except for box-box collisions.

This means that running a old game under Bullet 2.71 may cause visual problems, especially if the objects are small. You can fix these problems by changing some visual aspect of the objects: center, shape, size, position of children, etc.

State manipulation

BGE patch: KX_STATEx constant to allow simple state manipulation in setState()

The constants KX_STATE1 to KX_STATE30 can be used with setState() to change the object state in a python controller. The constants are defined in the GameLogic module so that the full name is GameLogic.KX_STATE1 to GameLogic.KX_STATE30 but you can simplify this with the import statement:

from GameLogic import * cont = getCurrentController() ob = cont.getOwner() ob.setState(KX_STATE2) #go to state 2

KX_STATEx constants are defined as (1<<(x-1)) Binary operators |, &, ^ and ~ can be used to combine states:

You can activate more than one state at a time with the | operator:

ob.setState(KX_STATE1|KX_STATE2)  #activate state 1 and 2, stop all others

You can add a state to the current state mask with:

state = ob.getState()
ob.setState(state|KX_STATE3)      #activate state 3, keep others

You can substract a state to the current state mask with the & and operator:

state = ob.getState()
ob.setState(state&~KX_STATE2)     #stop state 2, keep others

You can invert a state with the ^ operator:

state = ob.getState()
ob.setState(state^KX_STATE2)     #invert state 2, keep others

Delta rotation notes

BGE bug #17657 fixed: dRotY doesn't work properly after 90 degrees rotation.

This problem is caused by discontinuities in the conversion orientation matrix -> euler angles: the angle sign can switch and thus the direction of the rotation produced by the dRot Ipo.

To avoid this bug, the matrix->euler conversion must be avoided during the game. I took the following approach that is compatible with Blender (identical effect in the game and in the 3D view):

- no change in Add mode: Rot and dRot are treated as additional rotation to the orientation at the start of the Ipo. There is no matrix->euler conversion and thus no discontinuities.

- Rot Ipo are treated as absolute rotation. All 3 axis should be specified but if they are not, the startup object orientation will be used to set the unspecified axis. By doing a matrix-> euler conversion once at the start, the discontinuities are avoided. If there are also dRot curves, they are treated as delta of the corresponding Rot curve or startup angle.

- dRot Ipo are treated as Add mode in Local axis.

Note about Add mode: Rot and dRot curves are treated identically during the game. However, only dRot curves make sense because they don't interfere with the object orientation in the 3D view.

Distance constraint

local/global flag to distance contraint actuator.

Previously the distance constraint actuator was always working in local axis. The local flag allows to cast the ray along a world axis (when the flag is not selected). The N flag works differently in this case: only the object orientation is changed to be parallel to the normal at the hit point.

The linear velocity is now changed so that the speed along the ray axis is null. This eliminates the need to compensate the gravity when casting along the Z axis.

Force field constraint actuator

A new type of constraint actuator is available: Force field. It provides a very similar service to the Fh material feature but with some specificities:

• It is defined at the object level: each object can have different settings and you don't need to use material.
• It can be applied in all 6 directions and not just -Z.
• It can be enabled/disabled easily (it's an actuator).
• You can have multiple force fields active at the same time on the same object in different direction (think of a space ship in a tunnel with a repulsive force field on each wall).
• You can have a different damping for the rotation.

Besides that it provides the same dynamic behavior and the parameters are self explanatory. It works by adapting the linear and angular velocity: the dynamic is independent of the mass. It is compatible with all other motion actuators.

Note: linear and anysotropic friction is not yet implemented, the only friction will come from the object damping parameters. Support for friction will be added in a future revision.

Joystick Sensor Improvements

• Support for up to 8 joysticks at once.
• Joystick evens were not being handled correctly, events are managed in a similar way to the keyboard sensor.
• Added an "All Events" option so python controllers can use 1 joystick sensor using the python api to detect the events.
• Python API additions, joystick.getButtonValue() - returns a list of all pressed buttons. joystick.isConnected() to detect if the sensor is connected to a physical joystick.

Miscellaneous

• Keyboard sensors "Hold" keys now work as modifier keys, required to be held before an event is triggered. (before they were not functional)
• The Add Object actuator now has an option to set the initial angular velocity.
• The Set Visibility actuator and python api now have options to set child objects visibility recursively.
• The "Restrict Render" option in the outliner is used to initialize objects invisible setting. This means you can easily have physics meshes without having to set the texture face invisibility toggle, or adding logic bricks to set the visibility at startup.