Module GameTypes :: Class KX_GameObject

Class KX_GameObject

PyObjectPlus --+        
               |        
          CValue --+    
                   |    
         SCA_IObject --+
                       |
                      KX_GameObject

Known Subclasses:

All game objects are derived from this class.

Properties assigned to game objects are accessible as attributes of this class.

note: Calling ANY method or attribute on an object that has been removed from a scene will raise a SystemError, if an object may have been removed since last accessing it use the invalid attribute to check.

Instance Methods

endObject()
Delete this object, can be used inpace of the EndObject Actuator.

replaceMesh(mesh, useDisplayMesh=True, usePhysicsMesh=False)
Replace the mesh of this object with a new mesh.

setVisible(visible, recursive)
Sets the game object's visible flag.

setOcclusion(occlusion, recursive)
Sets the game object's occlusion capability.

alignAxisToVect(vect, axis, factor)
Aligns any of the game object's axis along the given vector.

3d vector.

getAxisVect(vect)
Returns the axis vector rotates by the objects worldspace orientation.

applyMovement(movement, local=0)
Sets the game object's movement.

applyRotation(rotation, local=0)
Sets the game object's rotation.

applyForce(force, local=0)
Sets the game object's force.

applyTorque(torque, local=0)
Sets the game object's torque.

list [vx, vy, vz]

getLinearVelocity(local=0)
Gets the game object's linear velocity.

setLinearVelocity(velocity, local=0)
Sets the game object's linear velocity.

list [vx, vy, vz]

getAngularVelocity(local=0)
Gets the game object's angular velocity.

setAngularVelocity(velocity, local=0)
Sets the game object's angular velocity.

list [vx, vy, vz]

getVelocity(point)
Gets the game object's velocity at the specified point.

list [fx, fy, fz]

getReactionForce()
Gets the game object's reaction force.

applyImpulse(point, impulse)
Applies an impulse to the game object.

suspendDynamics()
Suspends physics for this object.

restoreDynamics()
Resumes physics for this object.

enableRigidBody()
Enables rigid body physics for this object.

disableRigidBody()
Disables rigid body physics for this object.

setParent(parent, compound, ghost)
Sets this object's parent.

removeParent()
Removes this objects parent.

getPhysicsId()
Returns the user data object associated with this game object's physics controller.

float

getDistanceTo(other)
Returns the distance to another object or point.

3-tuple (float, 3-tuple (x,y,z), 3-tuple (x,y,z))

getVectTo(other)
Returns the vector and the distance to another object or point.

KX_GameObject

rayCastTo(other, dist, prop)
Look towards another point/object and find first object hit within dist that matches prop.

3-tuple (KX_GameObject, 3-tuple (x,y,z), 3-tuple (nx,ny,nz)) or 4-tuple (KX_GameObject, 3-tuple (x,y,z), 3-tuple (nx,ny,nz), KX_PolyProxy)

rayCast(objto, objfrom, dist, prop, face, xray, poly)
Look from a point/object to another point/object and find first object hit within dist that matches prop.

setCollisionMargin(margin)
Set the objects collision margin.

sendMessage(subject, body='', to='')
Sends a message.

boolean

reinstancePhysicsMesh(gameObject, meshObject)
Updates the physics system with the changed mesh.

bool

isA(game_type)
Check if this is a type or a subtype game_type. (Inherited from GameTypes.PyObjectPlus)

Deprecated

boolean

getVisible()
Gets the game object's visible flag.

int

getState()
Gets the game object's state bitmask.

setState(state)
Sets the game object's state flag.

setPosition(pos)
Sets the game object's position.

setWorldPosition(pos)
Sets the game object's position in world coordinates regardless if the object is root or child.

list [x, y, z]

getPosition()
Gets the game object's position.

setOrientation(orn)
Sets the game object's orientation.

3x3 rotation matrix

getOrientation()
Gets the game object's orientation.

float

getMass()
Gets the game object's mass.

KX_GameObject

getParent()
Gets this object's parent.

CListValue of KX_GameObject

getChildren()
Return a list of immediate children of this object.

CListValue of KX_GameObject

getChildrenRecursive()
Return a list of children of this object, including all their childrens children.

KX_MeshProxy

getMesh(mesh)
Gets the mesh object for this object.

string

getName()
Returns the name of the CValue. (Inherited from GameTypes.CValue)

Property Access

list

getPropertyNames()
Gets a list of all property names.

get(key, default=None)
Return the value matching key, or the default value if its not found.

boolean

has_key(key)
Return True if the key is found.

Property Access
Instance Variables
list	actuators a list of SCA_IActuator with string/index lookups and iterator support.
CListValue of KX_GameObject's	children direct children of this object, (read-only).
CListValue of KX_GameObject's	childrenRecursive all children of this object including childrens children, (read-only).
list of SCA_ISensor.	controllers a sequence of SCA_IController objects with string/index lookups and iterator support.
bool	invalid Test if the object has been freed by the game engine and is no longer valid. (Inherited from GameTypes.PyObjectPlus)
float	linVelocityMax Clamp the maximum linear velocity to prevent objects moving beyond a set speed.
float	linVelocityMin Enforces the object keeps moving at a minimum velocity.
list [ix, iy, iz]	localInertia the object's inertia vector in local coordinates.
3x3 Matrix [[float]]	localOrientation The object's local orientation.
list [x, y, z]	localPosition The object's local position.
list [sx, sy, sz]	localScale The object's local scaling factor.
float	mass The object's mass
list of KX_MeshProxy	meshes a list meshes for this object.
string	name The name of this CValue derived object (read-only).
boolean	occlusion occlusion capability flag.
3x3 Matrix [[float]] On write: local orientation, on read: world orientation	orientation The object's orientation.
KX_GameObject or None	parent The object's parent object.
list [x, y, z] On write: local position, on read: world position	position The object's position.
list [sx, sy, sz] On write: local scaling, on read: world scaling	scaling The object's scaling factor.
list	sensors a sequence of SCA_ISensor objects with string/index lookups and iterator support.
int	state the game object's state bitmask, using the first 30 bits, one bit must always be set.
float	timeOffset adjust the slowparent delay at runtime.
boolean	visible visibility flag.
3x3 Matrix [[float]]	worldOrientation The object's world orientation.
list [x, y, z]	worldPosition The object's world position.
list [sx, sy, sz]	worldScale The object's world scaling factor.
dict	attrDict get the objects internal python attribute dictionary for direct (faster) access.

Method Details

endObject()

Delete this object, can be used inpace of the EndObject Actuator. The actual removal of the object from the scene is delayed.

replaceMesh(mesh, useDisplayMesh=True, usePhysicsMesh=False)

Replace the mesh of this object with a new mesh. This works the same was as the actuator.

Parameters:

useDisplayMesh (bool) - when enabled the display mesh will be replaced (optional argument).
usePhysicsMesh (bool) - when enabled the physics mesh will be replaced (optional argument).
mesh (KX_MeshProxy or mesh name)

getVisible()

Gets the game object's visible flag.

Returns: boolean

Deprecated: use visible

setVisible(visible, recursive)

Sets the game object's visible flag.

Parameters:

recursive (boolean) - optional argument to set all childrens visibility flag too.
visible (boolean)

setOcclusion(occlusion, recursive)

Sets the game object's occlusion capability.

Parameters:

recursive (boolean) - optional argument to set all childrens occlusion flag too.
occlusion (boolean)

getState()

Gets the game object's state bitmask.

Returns: int: the objects state.

Deprecated: use state

setState(state)

Sets the game object's state flag. The bitmasks for states from 1 to 30 can be set with (1<<0, 1<<1, 1<<2 ... 1<<29)

Parameters:

state (integer)

Deprecated: use state

setPosition(pos)

Sets the game object's position. Global coordinates for root object, local for child objects.

Parameters:

pos ([x, y, z]) - the new position, in local coordinates.

Deprecated: use localPosition

setWorldPosition(pos)

Sets the game object's position in world coordinates regardless if the object is root or child.

Parameters:

pos ([x, y, z]) - the new position, in world coordinates.

Deprecated: use worldPosition

getPosition()

Gets the game object's position.

Returns: list [x, y, z]: the object's position in world coordinates.

Deprecated: use worldPosition

setOrientation(orn)

Sets the game object's orientation.

Parameters:

orn (3x3 rotation matrix, or Quaternion.) - a rotation matrix specifying the new rotation.

Deprecated: use localOrientation

Note: When using this matrix with Blender.Mathutils.Matrix() types, it will need to be transposed.

alignAxisToVect(vect, axis, factor)

Aligns any of the game object's axis along the given vector.

Parameters:

vect (3d vector.) - a vector to align the axis.
axis (integer.) - The axis you want to align
- 0: X axis
- 1: Y axis
- 2: Z axis (default)
factor (float) - Only rotate a feaction of the distance to the target vector (0.0 - 1.0)

getAxisVect(vect)

Returns the axis vector rotates by the objects worldspace orientation. This is the equivalent if multiplying the vector by the orientation matrix.

Parameters:

vect (3d vector.) - a vector to align the axis.

Returns: 3d vector.

The vector in relation to the objects rotation.

getOrientation()

Gets the game object's orientation.

Returns: 3x3 rotation matrix: The game object's rotation matrix

Deprecated: use worldOrientation

Note: When using this matrix with Blender.Mathutils.Matrix() types, it will need to be transposed.

applyMovement(movement, local=0)

Sets the game object's movement.

Parameters:

movement (3d vector.) - movement vector.
local (boolean) - - False: you get the "global" movement ie: relative to world orientation (default).
- True: you get the "local" movement ie: relative to object orientation.

applyRotation(rotation, local=0)

Sets the game object's rotation.

Parameters:

rotation (3d vector.) - rotation vector.
local (boolean) - - False: you get the "global" rotation ie: relative to world orientation (default).
- True: you get the "local" rotation ie: relative to object orientation.

applyForce(force, local=0)

Sets the game object's force.

This requires a dynamic object.

Parameters:

force (3d vector.) - force vector.
local (boolean) - - False: you get the "global" force ie: relative to world orientation (default).
- True: you get the "local" force ie: relative to object orientation.

applyTorque(torque, local=0)

Sets the game object's torque.

This requires a dynamic object.

Parameters:

torque (3d vector.) - torque vector.
local (boolean) - - False: you get the "global" torque ie: relative to world orientation (default).
- True: you get the "local" torque ie: relative to object orientation.

getLinearVelocity(local=0)

Gets the game object's linear velocity.

This method returns the game object's velocity through it's centre of mass, ie no angular velocity component.

Parameters:

local (boolean) - - False: you get the "global" velocity ie: relative to world orientation (default).
- True: you get the "local" velocity ie: relative to object orientation.

Returns: list [vx, vy, vz]

the object's linear velocity.

setLinearVelocity(velocity, local=0)

Sets the game object's linear velocity.

This method sets game object's velocity through it's centre of mass, ie no angular velocity component.

This requires a dynamic object.

Parameters:

velocity (3d vector.) - linear velocity vector.
local (boolean) - - False: you get the "global" velocity ie: relative to world orientation (default).
- True: you get the "local" velocity ie: relative to object orientation.

getAngularVelocity(local=0)

Gets the game object's angular velocity.

Parameters:

local (boolean) - - False: you get the "global" velocity ie: relative to world orientation (default).
- True: you get the "local" velocity ie: relative to object orientation.

Returns: list [vx, vy, vz]

the object's angular velocity.

setAngularVelocity(velocity, local=0)

Sets the game object's angular velocity.

This requires a dynamic object.

Parameters:

velocity (3d vector.) - angular velocity vector.
local (boolean) - - False: you get the "global" velocity ie: relative to world orientation (default).
- True: you get the "local" velocity ie: relative to object orientation.

getVelocity(point)

Gets the game object's velocity at the specified point.

Gets the game object's velocity at the specified point, including angular components.

Parameters:

point (list [x, y, z]) - the point to return the velocity for, in local coordinates. (optional: default = [0, 0, 0])

Returns: list [vx, vy, vz]

the velocity at the specified point.

getMass()

Gets the game object's mass.

Returns: float: the object's mass.

Deprecated: use mass

getReactionForce()

Gets the game object's reaction force.

The reaction force is the force applied to this object over the last simulation timestep. This also includes impulses, eg from collisions.

(This is not implimented for bullet physics at the moment)

Returns: list [fx, fy, fz]: the reaction force of this object.

applyImpulse(point, impulse)

Applies an impulse to the game object.

This will apply the specified impulse to the game object at the specified point. If point != getPosition(), applyImpulse will also change the object's angular momentum. Otherwise, only linear momentum will change.

Parameters:

point (list [x, y, z]) - the point to apply the impulse to (in world coordinates)

restoreDynamics()

Resumes physics for this object.

Note: The objects linear velocity will be applied from when the dynamics were suspended.

enableRigidBody()

Enables rigid body physics for this object.

Rigid body physics allows the object to roll on collisions.

Note: This is not working with bullet physics yet.

disableRigidBody()

Disables rigid body physics for this object.

Note: This is not working with bullet physics yet. The angular is removed but rigid body physics can still rotate it later.

getParent()

Gets this object's parent.

Returns: KX_GameObject: this object's parent object, or None if this object has no parent.

Deprecated: use parent

setParent(parent, compound, ghost)

Sets this object's parent. Control the shape status with the optional compound and ghost parameters: compound=1: the object shape should be added to the parent compound shape (default) compound=0: the object should keep its individual shape. In that case you can control if it should be ghost or not: ghost=1 if the object should be made ghost while parented (default) ghost=0 if the object should be solid while parented Note: if the object type is sensor, it stays ghost regardless of ghost parameter

Parameters:

parent (KX_GameObject) - new parent object.
compound (int) - whether the shape should be added to the parent compound shape
ghost (int) - whether the object should be ghost while parented

getChildren()

Return a list of immediate children of this object.

Returns: CListValue of KX_GameObject: a list of all this objects children.

getChildrenRecursive()

Return a list of children of this object, including all their childrens children.

Returns: CListValue of KX_GameObject: a list of all this objects children recursivly.

getMesh(mesh)

Gets the mesh object for this object.

Parameters:

mesh (integer) - the mesh object to return (optional: default mesh = 0)

Returns: KX_MeshProxy

the first mesh object associated with this game object, or None if this object has no meshs.

getPropertyNames()

Gets a list of all property names.

Returns: list: All property names for this object.

getDistanceTo(other)

Returns the distance to another object or point.

Parameters:

other (KX_GameObject or list [x, y, z]) - a point or another KX_GameObject to measure the distance to.

Returns: float

getVectTo(other)

Returns the vector and the distance to another object or point. The vector is normalized unless the distance is 0, in which a NULL vector is returned.

Parameters:

other (KX_GameObject or list [x, y, z]) - a point or another KX_GameObject to get the vector and distance to.

Returns: 3-tuple (float, 3-tuple (x,y,z), 3-tuple (x,y,z))

(distance, globalVector(3), localVector(3))

rayCastTo(other, dist, prop)

Look towards another point/object and find first object hit within dist that matches prop.

The ray is always casted from the center of the object, ignoring the object itself. The ray is casted towards the center of another object or an explicit [x,y,z] point. Use rayCast() if you need to retrieve the hit point

Parameters:

other (KX_GameObject or 3-tuple) - [x,y,z] or object towards which the ray is casted
dist (float) - max distance to look (can be negative => look behind); 0 or omitted => detect up to other
prop (string) - property name that object must have; can be omitted => detect any object

Returns: KX_GameObject

the first object hit or None if no object or object does not match prop

rayCast(objto, objfrom, dist, prop, face, xray, poly)

Look from a point/object to another point/object and find first object hit within dist that matches prop. if poly is 0, 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.

Ex:

       # shoot along the axis gun-gunAim (gunAim should be collision-free)
       ob,point,normal = gun.rayCast(gunAim,None,50)
       if ob:
               # hit something

Notes: The ray ignores the object on which the method is called. It is casted from/to object center or explicit [x,y,z] points.

The face paremeter determines the orientation of the normal:

 0 => 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.

The KX_PolyProxy 4th element of the return tuple when poly=1 allows to retrieve information on the polygon hit by the ray. If there is no hit or the hit object is not a static mesh, None is returned as 4th element.

The ray ignores collision-free objects and faces that dont have the collision flag enabled, you can however use ghost objects.

Parameters:

objto (KX_GameObject or 3-tuple) - [x,y,z] or object to which the ray is casted
objfrom (KX_GameObject or 3-tuple or None) - [x,y,z] or object from which the ray is casted; None or omitted => use self object center
dist (float) - max distance to look (can be negative => look behind); 0 or omitted => detect up to to
prop (string) - property name that object must have; can be omitted or "" => detect any object
face (int) - normal option: 1=>return face normal; 0 or omitted => normal is oriented towards origin
xray (int) - X-ray option: 1=>skip objects that don't match prop; 0 or omitted => stop on first object
poly (int) - polygon option: 1=>return value is a 4-tuple and the 4th element is a KX_PolyProxy

Returns: 3-tuple (KX_GameObject, 3-tuple (x,y,z), 3-tuple (nx,ny,nz)) or 4-tuple (KX_GameObject, 3-tuple (x,y,z), 3-tuple (nx,ny,nz), KX_PolyProxy)

(object,hitpoint,hitnormal) or (object,hitpoint,hitnormal,polygon) If no hit, returns (None,None,None) or (None,None,None,None) If the object hit is not a static mesh, polygon is None

setCollisionMargin(margin)

Set the objects collision margin.

note: If this object has no physics controller (a physics ID of zero), this function will raise RuntimeError.

Parameters:

margin (float) - the collision margin distance in blender units.

sendMessage(subject, body=`''`, to=`''`)

Sends a message.

Parameters:

subject (string) - The subject of the message
body (string) - The body of the message (optional)
to (string) - The name of the object to send the message to (optional)

reinstancePhysicsMesh(gameObject, meshObject)

Updates the physics system with the changed mesh.

If no arguments are given the physics mesh will be re-created from the first mesh assigned to the game object.

Parameters:

gameObject (string, KX_GameObject or None) - optional argument, set the physics shape from this gameObjets mesh.
meshObject (string, KX_MeshProxy or None) - optional argument, set the physics shape from this mesh.

Returns: boolean

True if reinstance succeeded, False if it failed.

Notes:

if this object has instances the other instances will be updated too.
the gameObject argument has an advantage that it can convert from a mesh with modifiers applied (such as subsurf).

Warnings:

only triangle mesh type objects are supported currently (not convex hull)
if the object is a part of a combound object it will fail (parent or child)
rebuilding the physics mesh can be slow, running many times per second will give a performance hit.

get(key, default=None)

Return the value matching key, or the default value if its not found.

Returns:: The key value or a default.

has_key(key)

Return True if the key is found.

Returns: boolean: The key value or a default.

Instance Variable Details

actuators

a list of SCA_IActuator with string/index lookups and iterator support.

note: This attribute is experemental and may be removed (but probably wont be).
note: Changes to this list will not update the KX_GameObject.

Type:: list

controllers

a sequence of SCA_IController objects with string/index lookups and iterator support.

note: This attribute is experemental and may be removed (but probably wont be).
note: Changes to this list will not update the KX_GameObject.

Type:: list of SCA_ISensor.

linVelocityMax

Clamp the maximum linear velocity to prevent objects moving beyond a set speed.

note: Applies to dynamic and rigid body objects only.
note: A value of 0.0 disables this option (rather then setting it stationary).

Type:: float

linVelocityMin

Enforces the object keeps moving at a minimum velocity.

note: Applies to dynamic and rigid body objects only.
note: A value of 0.0 disables this option.
note: While objects are stationary the minimum velocity will not be applied.

Type:: float

localInertia

the object's inertia vector in local coordinates. Read only.

Type:: list [ix, iy, iz]

localOrientation

The object's local orientation. 3x3 Matrix. You can also write a Quaternion or Euler vector.

Type:: 3x3 Matrix [[float]]

mass

The object's mass

note: The object must have a physics controller for the mass to be applied, otherwise the mass value will be returned as 0.0

Type:: float

meshes

a list meshes for this object.

note: Most objects use only 1 mesh.
note: Changes to this list will not update the KX_GameObject.

Type:: list of KX_MeshProxy

name

The name of this CValue derived object (read-only).

Type:: string

orientation

The object's orientation. 3x3 Matrix. You can also write a Quaternion or Euler vector.

deprecated: use localOrientation and worldOrientation

Type:: 3x3 Matrix [[float]] On write: local orientation, on read: world orientation

parent

The object's parent object. (read-only)

Type:: KX_GameObject or None

position

The object's position.

deprecated: use localPosition and worldPosition

Type:: list [x, y, z] On write: local position, on read: world position

scaling

The object's scaling factor. list [sx, sy, sz]

deprecated: use localScale and worldScale

Type:: list [sx, sy, sz] On write: local scaling, on read: world scaling

sensors

a sequence of SCA_ISensor objects with string/index lookups and iterator support.

note: This attribute is experemental and may be removed (but probably wont be).
note: Changes to this list will not update the KX_GameObject.

Type:: list

visible

visibility flag.

note: Game logic will still run for invisible objects.

Type:: boolean

worldScale

The object's world scaling factor. Read-only

Type:: list [sx, sy, sz]

Class KX_GameObject

endObject()

replaceMesh(mesh, useDisplayMesh=True, usePhysicsMesh=False)

getVisible()

setVisible(visible, recursive)

setOcclusion(occlusion, recursive)

getState()

setState(state)

setPosition(pos)

setWorldPosition(pos)

getPosition()

setOrientation(orn)

alignAxisToVect(vect, axis, factor)

getAxisVect(vect)

getOrientation()

applyMovement(movement, local=0)

applyRotation(rotation, local=0)

applyForce(force, local=0)

applyTorque(torque, local=0)

getLinearVelocity(local=0)

setLinearVelocity(velocity, local=0)

getAngularVelocity(local=0)

setAngularVelocity(velocity, local=0)

getVelocity(point)

getMass()

getReactionForce()

applyImpulse(point, impulse)

restoreDynamics()

enableRigidBody()

disableRigidBody()

getParent()

setParent(parent, compound, ghost)

getChildren()

getChildrenRecursive()

getMesh(mesh)

getPropertyNames()

getDistanceTo(other)

getVectTo(other)

rayCastTo(other, dist, prop)

rayCast(objto, objfrom, dist, prop, face, xray, poly)

setCollisionMargin(margin)

sendMessage(subject, body='', to='')

reinstancePhysicsMesh(gameObject, meshObject)

get(key, default=None)

has_key(key)

actuators

controllers

linVelocityMax

linVelocityMin

localInertia

localOrientation

mass

meshes

name

orientation

parent

position

scaling

sensors

visible

worldScale

sendMessage(subject, body=`''`, to=`''`)