diff options
Diffstat (limited to 'source/gameengine/PyDoc/GameTypes.py')
| -rw-r--r-- | source/gameengine/PyDoc/GameTypes.py | 465 |
1 files changed, 378 insertions, 87 deletions
diff --git a/source/gameengine/PyDoc/GameTypes.py b/source/gameengine/PyDoc/GameTypes.py index 63dd1a7fabf..60511f41c2b 100644 --- a/source/gameengine/PyDoc/GameTypes.py +++ b/source/gameengine/PyDoc/GameTypes.py @@ -4,15 +4,17 @@ Documentation for the GameTypes Module. @group Base: PyObjectPlus, CValue, CPropValue, SCA_ILogicBrick, SCA_IObject, SCA_ISensor, SCA_IController, SCA_IActuator -@group Object: KX_GameObject, KX_LightObject, KX_Camera +@group Object: KX_GameObject, KX_LightObject, KX_Camera, BL_ArmatureObject + +@group Animation: BL_ArmatureConstraint @group Mesh: KX_MeshProxy, KX_PolyProxy, KX_VertexProxy @group Shading: KX_PolygonMaterial, KX_BlenderMaterial, BL_Shader -@group Sensors: SCA_ActuatorSensor, SCA_AlwaysSensor, SCA_DelaySensor, SCA_JoystickSensor, SCA_KeyboardSensor, KX_MouseFocusSensor, SCA_MouseSensor, KX_NearSensor, KX_NetworkMessageSensor, SCA_PropertySensor, KX_RadarSensor, SCA_RandomSensor, KX_RaySensor, KX_TouchSensor +@group Sensors: SCA_ActuatorSensor, SCA_AlwaysSensor, SCA_DelaySensor, SCA_JoystickSensor, SCA_KeyboardSensor, KX_MouseFocusSensor, SCA_MouseSensor, KX_NearSensor, KX_NetworkMessageSensor, SCA_PropertySensor, KX_RadarSensor, SCA_RandomSensor, KX_RaySensor, KX_TouchSensor, KX_ArmatureSensor -@group Actuators: SCA_2DFilterActuator, BL_ActionActuator, KX_SCA_AddObjectActuator, KX_CameraActuator, KX_CDActuator, KX_ConstraintActuator, KX_SCA_DynamicActuator, KX_SCA_EndObjectActuator, KX_GameActuator, KX_IpoActuator, KX_NetworkMessageActuator, KX_ObjectActuator, KX_ParentActuator, SCA_PropertyActuator, SCA_RandomActuator, KX_SCA_ReplaceMeshActuator, KX_SceneActuator, BL_ShapeActionActuator, KX_SoundActuator, KX_StateActuator, KX_TrackToActuator, KX_VisibilityActuator +@group Actuators: SCA_2DFilterActuator, BL_ActionActuator, BL_ArmatureActuator, KX_SCA_AddObjectActuator, KX_CameraActuator, KX_ConstraintActuator, KX_SCA_DynamicActuator, KX_SCA_EndObjectActuator, KX_GameActuator, KX_IpoActuator, KX_NetworkMessageActuator, KX_ObjectActuator, KX_ParentActuator, SCA_PropertyActuator, SCA_RandomActuator, KX_SCA_ReplaceMeshActuator, KX_SceneActuator, BL_ShapeActionActuator, KX_SoundActuator, KX_StateActuator, KX_TrackToActuator, KX_VisibilityActuator @group Controllers: SCA_ANDController, SCA_NANDController, SCA_NORController, SCA_ORController, SCA_PythonController, SCA_XNORController, SCA_XORController """ @@ -310,6 +312,8 @@ class BL_ActionActuator(SCA_IActuator): @ivar action: The name of the action to set as the current action. @type action: string + @ivar channelNames: A list of channel names that may be used with L{setChannel} and L{getChannel} + @type channelNames: list of strings @ivar frameStart: Specifies the starting frame of the animation. @type frameStart: float @ivar frameEnd: Specifies the ending frame of the animation. @@ -340,7 +344,8 @@ class BL_ActionActuator(SCA_IActuator): """ Alternative to the 2 arguments, 4 arguments (channel, matrix, loc, size, quat) are also supported. - @param channel: A string specifying the name of the bone channel, created if missing. + @note: These values are relative to the bones rest position, currently the api has no way to get this info (which is annoying), but can be worked around by using bones with a rest pose that has no translation. + @param channel: A string specifying the name of the bone channel, error raised if not in L{channelNames}. @type channel: string @param matrix: A 4x4 matrix specifying the overriding transformation as an offset from the bone's rest position. @@ -349,7 +354,7 @@ class BL_ActionActuator(SCA_IActuator): def getChannel(channel): """ - @param channel: A string specifying the name of the bone channel. error raised if missing. + @param channel: A string specifying the name of the bone channel. error raised if not in L{channelNames}. @type channel: string @rtype: tuple @return: (loc, size, quat) @@ -1020,12 +1025,6 @@ class CListValue(CPropValue): Return the value matching key, or the default value if its not found. @return: The key value or a default. """ - def has_key(key): - """ - Return True if the key is found. - @rtype: boolean - @return: The key value or a default. - """ def from_id(id): """ This is a funtion especially for the game engine to return a value with a spesific id. @@ -1103,59 +1102,6 @@ class KX_BlenderMaterial(PyObjectPlus): # , RAS_IPolyMaterial) @return: the material's index """ -class KX_CDActuator(SCA_IActuator): - """ - CD Controller actuator. - @ivar volume: controls the volume to set the CD to. 0.0 = silent, 1.0 = max volume. - @type volume: float - @ivar track: the track selected to be played - @type track: integer - @ivar gain: the gain (volume) of the CD between 0.0 and 1.0. - @type gain: float - """ - def startCD(): - """ - Starts the CD playing. - """ - def stopCD(): - """ - Stops the CD playing. - """ - def pauseCD(): - """ - Pauses the CD. - """ - def resumeCD(): - """ - Resumes the CD after a pause. - """ - def playAll(): - """ - Plays the CD from the beginning. - """ - def playTrack(trackNumber): - """ - Plays the track selected. - """ -#{ Deprecated - def setGain(gain): - """ - Sets the gain (volume) of the CD. - - @deprecated: Use the L{volume} property. - @type gain: float - @param gain: the gain to set the CD to. 0.0 = silent, 1.0 = max volume. - """ - def getGain(): - """ - Gets the current gain (volume) of the CD. - - @deprecated: Use the L{volume} property. - @rtype: float - @return: Between 0.0 (silent) and 1.0 (max volume) - """ -#} - class KX_CameraActuator(SCA_IActuator): """ Applies changes to a camera. @@ -1632,17 +1578,21 @@ class KX_GameObject(SCA_IObject): @ivar childrenRecursive: all children of this object including childrens children, (read-only). @type childrenRecursive: L{CListValue} of L{KX_GameObject}'s @group Deprecated: getPosition, setPosition, setWorldPosition, getOrientation, setOrientation, getState, setState, getParent, getVisible, getMass, getMesh, getChildren, getChildrenRecursive - @group Property Access: get, has_key, attrDict, getPropertyNames + @group Property Access: get, attrDict, getPropertyNames """ def endObject(): """ Delete this object, can be used inpace of the EndObject Actuator. The actual removal of the object from the scene is delayed. """ - def replaceMesh(mesh): + def replaceMesh(mesh, useDisplayMesh=True, usePhysicsMesh=False): """ Replace the mesh of this object with a new mesh. This works the same was as the actuator. @type mesh: L{KX_MeshProxy} or mesh name + @type useDisplayMesh: bool + @param useDisplayMesh: when enabled the display mesh will be replaced (optional argument). + @type usePhysicsMesh: bool + @param usePhysicsMesh: when enabled the physics mesh will be replaced (optional argument). """ def getVisible(): """ @@ -2075,15 +2025,29 @@ class KX_GameObject(SCA_IObject): @param to: The name of the object to send the message to (optional) @type to: string """ - def get(key, default=None): + def reinstancePhysicsMesh(gameObject, meshObject): """ - Return the value matching key, or the default value if its not found. - @return: The key value or a default. + 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. + + @param gameObject: optional argument, set the physics shape from this gameObjets mesh. + @type gameObject: string, L{KX_GameObject} or None + @param meshObject: optional argument, set the physics shape from this mesh. + @type meshObject: string, L{KX_MeshProxy} or None + + @note: if this object has instances the other instances will be updated too. + @note: the gameObject argument has an advantage that it can convert from a mesh with modifiers applied (such as subsurf). + @warning: only triangle mesh type objects are supported currently (not convex hull) + @warning: if the object is a part of a combound object it will fail (parent or child) + @warning: rebuilding the physics mesh can be slow, running many times per second will give a performance hit. + @rtype: boolean + @return: True if reinstance succeeded, False if it failed. """ - def has_key(key): + + def get(key, default=None): """ - Return True if the key is found. - @rtype: boolean + Return the value matching key, or the default value if its not found. @return: The key value or a default. """ @@ -2384,18 +2348,6 @@ class KX_MeshProxy(SCA_IObject): @rtype: L{KX_PolyProxy} @return: a polygon object. """ - def reinstancePhysicsMesh(): - """ - Updates the physics system with the changed mesh. - - A mesh must have only one material with collision flags, - and have all collision primitives in one vertex array (ie. < 65535 verts) and - be either a polytope or polyheder mesh. If you don't get a warning in the - console when the collision type is polytope, the mesh is suitable for reinstance. - @bug: This currently does not work. - @rtype: boolean - @return: True if reinstance succeeded, False if it failed. - """ class SCA_MouseSensor(SCA_ISensor): """ @@ -2457,6 +2409,8 @@ class KX_MouseFocusSensor(SCA_MouseSensor): @type hitPosition: list (vector of 3 floats) @ivar hitNormal: the worldspace normal from the face at point of intersection. @type hitNormal: list (normalized vector of 3 floats) + @ivar usePulseFocus: When enabled, moving the mouse over a different object generates a pulse. (only used when the 'Mouse Over Any' sensor option is set) + @type usePulseFocus: bool """ #{ Deprecated def getHitNormal(): @@ -2518,7 +2472,7 @@ class KX_TouchSensor(SCA_ISensor): @ivar useMaterial: Determines if the sensor is looking for a property or material. KX_True = Find material; KX_False = Find property @type useMaterial: boolean - @ivar usePulseCollision: The last collided object. + @ivar usePulseCollision: When enabled, changes to the set of colliding objects generate a pulse. @type usePulseCollision: bool @ivar hitObject: The last collided object. (read-only) @type hitObject: L{KX_GameObject} or None @@ -3780,6 +3734,11 @@ class KX_SCA_ReplaceMeshActuator(SCA_IActuator): @ivar mesh: L{KX_MeshProxy} or the name of the mesh that will replace the current one Set to None to disable actuator @type mesh: L{KX_MeshProxy} or None if no mesh is set + + @ivar useDisplayMesh: when true the displayed mesh is replaced. + @type useDisplayMesh: boolean + @ivar usePhysicsMesh: when true the physics mesh is replaced. + @type usePhysicsMesh: boolean """ def setMesh(name): """ @@ -3899,6 +3858,12 @@ class KX_Scene(PyObjectPlus): @rtype: L{KX_GameObject} """ + + def get(key, default=None): + """ + Return the value matching key, or the default value if its not found. + @return: The key value or a default. + """ class KX_SceneActuator(SCA_IActuator): """ @@ -5723,6 +5688,332 @@ class KX_Camera(KX_GameObject): @return: the first object hit or None if no object or object does not match prop """ +class BL_ArmatureObject(KX_GameObject): + """ + An armature object. + + @ivar constraints: The list of armature constraint defined on this armature + Elements of the list can be accessed by index or string. + The key format for string access is '<bone_name>:<constraint_name>' + @type constraints: list of L{BL_ArmatureConstraint} + @ivar channels: The list of armature channels. + Elements of the list can be accessed by index or name the bone. + @type channels: list of L{BL_ArmatureChannel} + """ + + def update(): + """ + Ensures that the armature will be updated on next graphic frame. + + This action is unecessary if a KX_ArmatureActuator with mode run is active + or if an action is playing. Use this function in other cases. It must be called + on each frame to ensure that the armature is updated continously. + """ + +class BL_ArmatureActuator(SCA_IActuator): + """ + Armature Actuators change constraint condition on armatures. + + @group Constants: KX_ACT_ARMATURE_RUN, KX_ACT_ARMATURE_ENABLE, KX_ACT_ARMATURE_DISABLE, KX_ACT_ARMATURE_SETTARGET, KX_ACT_ARMATURE_SETWEIGHT + @ivar KX_ACT_ARMATURE_RUN: see type + @ivar KX_ACT_ARMATURE_ENABLE: see type + @ivar KX_ACT_ARMATURE_DISABLE: see type + @ivar KX_ACT_ARMATURE_SETTARGET: see type + @ivar KX_ACT_ARMATURE_SETWEIGHT: see type + @ivar type: The type of action that the actuator executes when it is active. + + KX_ACT_ARMATURE_RUN(0): just make sure the armature will be updated on the next graphic frame + This is the only persistent mode of the actuator: it executes automatically once per frame until stopped by a controller + + KX_ACT_ARMATURE_ENABLE(1): enable the constraint. + + KX_ACT_ARMATURE_DISABLE(2): disable the constraint (runtime constraint values are not updated). + + KX_ACT_ARMATURE_SETTARGET(3): change target and subtarget of constraint + + KX_ACT_ARMATURE_SETWEIGHT(4): change weight of (only for IK constraint) + @type type: integer + @ivar constraint: The constraint object this actuator is controlling. + @type constraint: L{BL_ArmatureConstraint} + @ivar target: The object that this actuator will set as primary target to the constraint it controls + @type target: L{KX_GameObject} + @ivar subtarget: The object that this actuator will set as secondary target to the constraint it controls. + Currently, the only secondary target is the pole target for IK constraint. + @type subtarget: L{KX_GameObject} + @ivar weight: The weight this actuator will set on the constraint it controls. + Currently only the IK constraint has a weight. It must be a value between 0 and 1. + A weight of 0 disables a constraint while still updating constraint runtime values (see L{BL_ArmatureConstraint}) + @type weight: float + """ + +class KX_ArmatureSensor(SCA_ISensor): + """ + Armature sensor detect conditions on armatures. + + @group Constants: KX_ARMSENSOR_STATE_CHANGED, KX_ARMSENSOR_LIN_ERROR_BELOW, KX_ARMSENSOR_LIN_ERROR_ABOVE, KX_ARMSENSOR_ROT_ERROR_BELOW, KX_ARMSENSOR_ROT_ERROR_ABOVE + @ivar KX_ARMSENSOR_STATE_CHANGED: see type + @ivar KX_ARMSENSOR_LIN_ERROR_BELOW: see type + @ivar KX_ARMSENSOR_LIN_ERROR_ABOVE: see type + @ivar KX_ARMSENSOR_ROT_ERROR_BELOW: see type + @ivar KX_ARMSENSOR_ROT_ERROR_ABOVE: see type + @ivar type: The type of measurement that the sensor make when it is active. + + KX_ARMSENSOR_STATE_CHANGED(0): detect that the constraint is changing state (active/inactive) + + KX_ARMSENSOR_LIN_ERROR_BELOW(1): detect that the constraint linear error is above a threshold + + KX_ARMSENSOR_LIN_ERROR_ABOVE(2): detect that the constraint linear error is below a threshold + + KX_ARMSENSOR_ROT_ERROR_BELOW(3): detect that the constraint rotation error is above a threshold + + KX_ARMSENSOR_ROT_ERROR_ABOVE(4): detect that the constraint rotation error is below a threshold + @type type: integer + @ivar constraint: The constraint object this sensor is watching. + @type constraint: L{BL_ArmatureConstraint} + @ivar value: The threshold used in the comparison with the constraint error + The linear error is only updated on CopyPose/Distance IK constraint with iTaSC solver + The rotation error is only updated on CopyPose+rotation IK constraint with iTaSC solver + The linear error on CopyPose is always >= 0: it is the norm of the distance between the target and the bone + The rotation error on CopyPose is always >= 0: it is the norm of the equivalent rotation vector between the bone and the target orientations + The linear error on Distance can be positive if the distance between the bone and the target is greater than the desired distance, and negative if the distance is smaller + @type value: float + """ + +class BL_ArmatureConstraint(PyObjectPlus): + """ + Proxy to Armature Constraint. Allows to change constraint on the fly. + Obtained through L{BL_ArmatureObject}.constraints. + Note: not all armature constraints are supported in the GE. + + @group Constants: CONSTRAINT_TYPE_TRACKTO, CONSTRAINT_TYPE_KINEMATIC, CONSTRAINT_TYPE_ROTLIKE, CONSTRAINT_TYPE_LOCLIKE, CONSTRAINT_TYPE_MINMAX, CONSTRAINT_TYPE_SIZELIKE, CONSTRAINT_TYPE_LOCKTRACK, CONSTRAINT_TYPE_STRETCHTO, CONSTRAINT_TYPE_CLAMPTO, CONSTRAINT_TYPE_TRANSFORM, CONSTRAINT_TYPE_DISTLIMIT,CONSTRAINT_IK_COPYPOSE, CONSTRAINT_IK_DISTANCE,CONSTRAINT_IK_MODE_INSIDE, CONSTRAINT_IK_MODE_OUTSIDE,CONSTRAINT_IK_MODE_ONSURFACE,CONSTRAINT_IK_FLAG_TIP,CONSTRAINT_IK_FLAG_ROT, CONSTRAINT_IK_FLAG_STRETCH, CONSTRAINT_IK_FLAG_POS + @ivar CONSTRAINT_TYPE_TRACKTO: see type + @ivar CONSTRAINT_TYPE_KINEMATIC: see type + @ivar CONSTRAINT_TYPE_ROTLIKE: see type + @ivar CONSTRAINT_TYPE_LOCLIKE: see type + @ivar CONSTRAINT_TYPE_MINMAX: see type + @ivar CONSTRAINT_TYPE_SIZELIKE: see type + @ivar CONSTRAINT_TYPE_LOCKTRACK: see type + @ivar CONSTRAINT_TYPE_STRETCHTO: see type + @ivar CONSTRAINT_TYPE_CLAMPTO: see type + @ivar CONSTRAINT_TYPE_TRANSFORM: see type + @ivar CONSTRAINT_TYPE_DISTLIMIT: see type + @ivar CONSTRAINT_IK_COPYPOSE: see ik_type + @ivar CONSTRAINT_IK_DISTANCE: see ik_type + @ivar CONSTRAINT_IK_MODE_INSIDE: see ik_mode + @ivar CONSTRAINT_IK_MODE_OUTSIDE: see ik_mode + @ivar CONSTRAINT_IK_MODE_ONSURFACE: see ik_mode + @ivar CONSTRAINT_IK_FLAG_TIP: see ik_flag + @ivar CONSTRAINT_IK_FLAG_ROT: see ik_flag + @ivar CONSTRAINT_IK_FLAG_STRETCH: see ik_flag + @ivar CONSTRAINT_IK_FLAG_POS: see ik_flag + @ivar type: Type of constraint, read-only + @type type: integer, one of CONSTRAINT_TYPE_ constant + @ivar name: Name of constraint constructed as <bone_name>:<constraint_name> + This name is also the key subscript on L{BL_ArmatureObject}.constraints list + @type name: string + @ivar enforce: fraction of constraint effect that is enforced. Between 0 and 1. + @type enforce: float + @ivar headtail: position of target between head and tail of the target bone: 0=head, 1=tail + Only used if the target is a bone (i.e target object is an armature) + @type headtail: float + @ivar lin_error: runtime linear error (in Blender unit) on constraint at the current frame. + This is a runtime value updated on each frame by the IK solver. Only available on IK constraint and iTaSC solver. + @type lin_error: float + @ivar rot_error: runtime rotation error (in radiant) on constraint at the current frame. + This is a runtime value updated on each frame by the IK solver. Only available on IK constraint and iTaSC solver. + It is only set if the constraint has a rotation part, for example, a CopyPose+Rotation IK constraint. + @type rot_error: float + @ivar target: Primary target object for the constraint. The position of this object in the GE will be used as target for the constraint. + @type target: L{KX_GameObject} + @ivar subtarget: Secondary target object for the constraint. The position of this object in the GE will be used as secondary target for the constraint. + Currently this is only used for pole target on IK constraint. + @type subtarget: L{KX_GameObject} + @ivar active: True if the constraint is active. + Note: an inactive constraint does not update lin_error and rot_error. + @type active: boolean + @ivar ik_weight: Weight of the IK constraint between 0 and 1. + Only defined for IK constraint. + @type ik_weight: float + @ivar ik_type: Type of IK constraint, read-only + + CONSTRAINT_IK_COPYPOSE(0): constraint is trying to match the position and eventually the rotation of the target. + + CONSTRAINT_IK_DISTANCE(1): constraint is maintaining a certain distance to target subject to ik_mode + @type ik_type: integer + @ivar ik_flag: Combination of IK constraint option flags, read-only + + CONSTRAINT_IK_FLAG_TIP(1) : set when the constraint operates on the head of the bone and not the tail + + CONSTRAINT_IK_FLAG_ROT(2) : set when the constraint tries to match the orientation of the target + + CONSTRAINT_IK_FLAG_STRETCH(16) : set when the armature is allowed to stretch (only the bones with stretch factor > 0.0) + + CONSTRAINT_IK_FLAG_POS(32) : set when the constraint tries to match the position of the target + @type ik_flag: integer + @ivar ik_dist: Distance the constraint is trying to maintain with target, only used when ik_type=CONSTRAINT_IK_DISTANCE + @type ik_dist: float + @ivar ik_mode: Additional mode for IK constraint. Currently only used for Distance constraint: + + CONSTRAINT_IK_MODE_INSIDE(0) : the constraint tries to keep the bone within ik_dist of target + + CONSTRAINT_IK_MODE_OUTSIDE(1) : the constraint tries to keep the bone outside ik_dist of the target + + CONSTRAINT_IK_MODE_ONSURFACE(2) : the constraint tries to keep the bone exactly at ik_dist of the target + @type ik_mode: integer + """ + +class BL_ArmatureChannel(PyObjectPlus): + """ + Proxy to armature pose channel. Allows to read and set armature pose. + The attributes are identical to RNA attributes, but mostly in read-only mode. + + @group Constants: PCHAN_ROT_QUAT, PCHAN_ROT_XYZ, PCHAN_ROT_XZY, PCHAN_ROT_YXZ, PCHAN_ROT_YZX, PCHAN_ROT_ZXY, PCHAN_ROT_ZYX + @ivar PCHAN_ROT_QUAT: see rotation_mode + @ivar PCHAN_ROT_XYZ: see rotation_mode + @ivar PCHAN_ROT_XZY: see rotation_mode + @ivar PCHAN_ROT_YXZ: see rotation_mode + @ivar PCHAN_ROT_YZX: see rotation_mode + @ivar PCHAN_ROT_ZXY: see rotation_mode + @ivar PCHAN_ROT_ZYX: see rotation_mode + @ivar name: channel name (=bone name), read-only. + @type name: string + @ivar bone: return the bone object corresponding to this pose channel, read-only. + @type bone: L{BL_ArmatureBone} + @ivar parent: return the parent channel object, None if root channel, read-only. + @type parent: L{BL_ArmatureChannel} + @ivar has_ik: true if the bone is part of an active IK chain, read-only. + This flag is not set when an IK constraint is defined but not enabled (miss target information for example) + @type has_ik: boolean + @ivar ik_dof_x: true if the bone is free to rotation in the X axis, read-only. + @type ik_dof_x: boolean + @ivar ik_dof_y: true if the bone is free to rotation in the Y axis, read-only. + @type ik_dof_y: boolean + @ivar ik_dof_z: true if the bone is free to rotation in the Z axis, read-only. + @type ik_dof_z: boolean + @ivar ik_limit_x: true if a limit is imposed on X rotation, read-only. + @type ik_limit_x: boolean + @ivar ik_limit_y: true if a limit is imposed on Y rotation, read-only. + @type ik_limit_y: boolean + @ivar ik_limit_z: true if a limit is imposed on Z rotation, read-only. + @type ik_limit_z: boolean + @ivar ik_rot_control: true if channel rotation should applied as IK constraint, read-only. + @type ik_rot_control: boolean + @ivar ik_lin_control: true if channel size should applied as IK constraint, read-only. + @type ik_lin_control: boolean + @ivar location: displacement of the bone head in armature local space, read-write. + You can only move a bone if it is unconnected to its parent. An action playing on the armature may change the value. An IK chain does not update this value, see joint_rotation. + Changing this field has no immediate effect, the pose is updated when the armature is updated during the graphic render (see L{BL_ArmatureObject.update}) + @type location: vector [X,Y,Z] + @ivar scale: scale of the bone relative to its parent, read-write. + An action playing on the armature may change the value. An IK chain does not update this value, see joint_rotation. + Changing this field has no immediate effect, the pose is updated when the armature is updated during the graphic render (see L{BL_ArmatureObject.update}) + @type scale: vector [sizeX, sizeY, sizeZ] + @ivar rotation: rotation of the bone relative to its parent expressed as a quaternion, read-write. + This field is only used if rotation_mode is 0. An action playing on the armature may change the value. An IK chain does not update this value, see joint_rotation. + Changing this field has no immediate effect, the pose is updated when the armature is updated during the graphic render (see L{BL_ArmatureObject.update}) + @type rotation: vector [qr, qi, qj, qk] + @ivar euler_rotation: rotation of the bone relative to its parent expressed as a set of euler angles, read-write. + This field is only used if rotation_mode is > 0. You must always pass the angles in [X,Y,Z] order; the order of applying the angles to the bone depends on rotation_mode. An action playing on the armature may change this field. An IK chain does not update this value, see joint_rotation. + Changing this field has no immediate effect, the pose is updated when the armature is updated during the graphic render (see L{BL_ArmatureObject.update}) + @type euler_rotation: vector [X, Y, Z] + @ivar rotation_mode: method of updating the bone rotation, read-write. + Use the following constants (euler mode are named as in BLender UI but the actual axis order is reversed): + - PCHAN_ROT_QUAT(0) : use quaternioin in rotation attribute to update bone rotation + - PCHAN_ROT_XYZ(1) : use euler_rotation and apply angles on bone's Z, Y, X axis successively + - PCHAN_ROT_XZY(2) : use euler_rotation and apply angles on bone's Y, Z, X axis successively + - PCHAN_ROT_YXZ(3) : use euler_rotation and apply angles on bone's Z, X, Y axis successively + - PCHAN_ROT_YZX(4) : use euler_rotation and apply angles on bone's X, Z, Y axis successively + - PCHAN_ROT_ZXY(5) : use euler_rotation and apply angles on bone's Y, X, Z axis successively + - PCHAN_ROT_ZYX(6) : use euler_rotation and apply angles on bone's X, Y, Z axis successively + @type rotation_mode: integer + @ivar channel_matrix: pose matrix in bone space (deformation of the bone due to action, constraint, etc), Read-only. + This field is updated after the graphic render, it represents the current pose. + @type channel_matrix: matrix [4][4] + @ivar pose_matrix: pose matrix in armature space, read-only, + This field is updated after the graphic render, it represents the current pose. + @type pose_matrix: matrix [4][4] + @ivar pose_head: position of bone head in armature space, read-only. + @type pose_head: vector [x, y, z] + @ivar pose_tail: position of bone tail in armature space, read-only. + @type pose_tail: vector [x, y, z] + @ivar ik_min_x: minimum value of X rotation in degree (<= 0) when X rotation is limited (see ik_limit_x), read-only. + @type ik_min_x: float + @ivar ik_max_x: maximum value of X rotation in degree (>= 0) when X rotation is limited (see ik_limit_x), read-only. + @type ik_max_x: float + @ivar ik_min_y: minimum value of Y rotation in degree (<= 0) when Y rotation is limited (see ik_limit_y), read-only. + @type ik_min_y: float + @ivar ik_max_y: maximum value of Y rotation in degree (>= 0) when Y rotation is limited (see ik_limit_y), read-only. + @type ik_max_y: float + @ivar ik_min_z: minimum value of Z rotation in degree (<= 0) when Z rotation is limited (see ik_limit_z), read-only. + @type ik_min_z: float + @ivar ik_max_z: maximum value of Z rotation in degree (>= 0) when Z rotation is limited (see ik_limit_z), read-only. + @type ik_max_z: float + @ivar ik_stiffness_x: bone rotation stiffness in X axis, read-only + @type ik_stiffness_x: float between 0 and 1 + @ivar ik_stiffness_y: bone rotation stiffness in Y axis, read-only + @type ik_stiffness_y: float between 0 and 1 + @ivar ik_stiffness_z: bone rotation stiffness in Z axis, read-only + @type ik_stiffness_z: float between 0 and 1 + @ivar ik_stretch: ratio of scale change that is allowed, 0=bone can't change size, read-only. + @type ik_stretch: float + @ivar ik_rot_weight: weight of rotation constraint when ik_rot_control is set, read-write. + @type ik_rot_weight: float between 0 and 1 + @ivar ik_lin_weight: weight of size constraint when ik_lin_control is set, read-write. + @type ik_lin_weight: float between 0 and 1 + @ivar joint_rotation: control bone rotation in term of joint angle (for robotic applications), read-write. + When writing to this attribute, you pass a [x, y, z] vector and an appropriate set of euler angles or quaternion is calculated according to the rotation_mode. + When you read this attribute, the current pose matrix is converted into a [x, y, z] vector representing the joint angles. + The value and the meaning of the x, y, z depends on the ik_dof_ attributes: + - 1DoF joint X, Y or Z: the corresponding x, y, or z value is used an a joint angle in radiant + - 2DoF joint X+Y or Z+Y: treated as 2 successive 1DoF joints: first X or Z, then Y. The x or z value is used as a joint angle in radiant along the X or Z axis, followed by a rotation along the new Y axis of y radiants. + - 2DoF joint X+Z: treated as a 2DoF joint with rotation axis on the X/Z plane. The x and z values are used as the coordinates of the rotation vector in the X/Z plane. + - 3DoF joint X+Y+Z: treated as a revolute joint. The [x,y,z] vector represents the equivalent rotation vector to bring the joint from the rest pose to the new pose. + + Notes: + - The bone must be part of an IK chain if you want to set the ik_dof_ attributes via the UI, but this will interfere with this attribute since the IK solver will overwrite the pose. You can stay in control of the armature if you create an IK constraint but do not finalize it (e.g. don't set a target): the IK solver will not run but the IK panel will show up on the UI for each bone in the chain. + - [0,0,0] always corresponds to the rest pose. + - You must request the armature pose to update and wait for the next graphic frame to see the effect of setting this attribute (see L{BL_ArmatureObject.update}). + - You can read the result of the calculation in rotation or euler_rotation attributes after setting this attribute. + @type joint_rotation: vector [x, y, z] + """ + +class BL_ArmatureBone(PyObjectPlus): + """ + Proxy to Blender bone structure. All fields are read-only and comply to RNA names. + All space attribute correspond to the rest pose. + + @ivar name: bone name + @type name: string + @ivar connected: true when the bone head is struck to the parent's tail + @type connected: boolean + @ivar hinge: true when bone doesn't inherit rotation or scale from parent bone + @type hinge: boolean + @ivar inherit_scale: true when bone inherits scaling from parent bone + @type inherit_scale: boolean + @ivar bbone_segments: number of B-bone segments + @type bbone_segments: integer + @ivar roll: bone rotation around head-tail axis + @type roll: float + @ivar head: location of head end of the bone in parent bone space + @type head: vector [x, y, z] + @ivar tail: location of head end of the bone in parent bone space + @type tail: vector [x, y, z] + @ivar length: bone length + @type length: float + @ivar arm_head: location of head end of the bone in armature space + @type arm_head: vector [x, y, z] + @ivar arm_tail: location of tail end of the bone in armature space + @type arm_tail: vector [x, y, z] + @ivar arm_mat: matrix of the bone head in armature space + This matrix has no scale part. + @type arm_mat: matrix [4][4] + @ivar bone_mat: rotation matrix of the bone in parent bone space. + @type bone_mat: matrix [3][3] + @ivar parent: parent bone, or None for root bone + @type parent: L{BL_ArmatureBone} + @ivar children: list of bone's children + @type children: list of L{BL_ArmatureBone} + """ # Util func to extract all attrs """ import types @@ -5770,7 +6061,7 @@ for name, val in locals().items(): # Store the mappings to new attributes in a list (because there # could be collisions). - if not depAttrs.has_key(attrName): + if attrName not in depAttrs: depAttrs[attrName] = {} mapping = depAttrs[attrName] @@ -5795,7 +6086,7 @@ for name, val in locals().items(): # Another mapping, from a conversion tuple to lists of class # names. conversion = (func, newAttrName) - if not mapping.has_key(conversion): + if conversion not in mapping: mapping[conversion] = [] mapping[conversion].append(name) break |