diff options
Diffstat (limited to 'doc/python_api/rst/bge_types')
17 files changed, 467 insertions, 350 deletions
diff --git a/doc/python_api/rst/bge_types/bge.types.KX_BlenderMaterial.rst b/doc/python_api/rst/bge_types/bge.types.KX_BlenderMaterial.rst index 0dfc7a10d13..17f54031ec3 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_BlenderMaterial.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_BlenderMaterial.rst @@ -7,11 +7,66 @@ base class --- :class:`PyObjectPlus` .. class:: KX_BlenderMaterial(PyObjectPlus) - KX_BlenderMaterial + This is the interface to materials in the game engine. + + Materials define the render state to be applied to mesh objects. + + The example below shows a simple GLSL shader setup allowing to dynamically mix two texture channels + in a material. All materials of the object executing this script should have two textures using + separate UV maps in the two first texture channels. + + The code works for both Multitexture and GLSL rendering modes. + + .. code-block:: python + + from bge import logic + + vertex_shader = """ + + void main(void) + { + // simple projection of the vertex position to view space + gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex; + // coordinate of the 1st texture channel + gl_TexCoord[0] = gl_MultiTexCoord0; + // coordinate of the 2nd texture channel + gl_TexCoord[1] = gl_MultiTexCoord1; + } + """ + + fragment_shader =""" + + uniform sampler2D texture_0; + uniform sampler2D texture_1; + uniform float factor; + + void main(void) + { + vec4 color_0 = texture2D(texture_0, gl_TexCoord[0].st); + vec4 color_1 = texture2D(texture_1, gl_TexCoord[1].st); + gl_FragColor = mix(color_0, color_1, factor); + } + """ + + object = logic.getCurrentController().owner + + for mesh in object.meshes: + for material in mesh.materials: + shader = material.getShader() + if shader is not None: + if not shader.isValid(): + shader.setSource(vertex_shader, fragment_shader, True) + + # get the first texture channel of the material + shader.setSampler('texture_0', 0) + # get the second texture channel of the material + shader.setSampler('texture_1', 1) + # pass another uniform to the shader + shader.setUniform1f('factor', 0.3) .. attribute:: shader - The materials shader. + The material's shader. :type: :class:`BL_Shader` @@ -34,39 +89,83 @@ base class --- :class:`PyObjectPlus` :return: the material's shader :rtype: :class:`BL_Shader` + .. attribute:: alpha + + The material's alpha transparency. + + :type: float between 0.0 and 1.0 inclusive + + .. attribute:: hardness + + How hard (sharp) the material's specular reflection is. + + :type: integer between 1 and 511 inclusive + + .. attribute:: emit + + Amount of light to emit. + + :type: float between 0.0 and 2.0 inclusive + + .. attribute:: specularIntensity + + How intense (bright) the material's specular reflection is. + + :type: float between 0.0 and 1.0 inclusive + + .. attribute:: diffuseIntensity + + The material's amount of diffuse reflection. + + :type: float between 0.0 and 1.0 inclusive + + .. attribute:: specularColor + + The material's specular color. + + :type: :class:`mathutils.Color` + + .. attribute:: diffuseColor + + The material's diffuse color. + + :type: :class:`mathutils.Color` + .. method:: setBlending(src, dest) Set the pixel color arithmetic functions. - :arg src: Specifies how the red, green, blue, and alpha source blending factors are computed. - :type src: Value in... - - * GL_ZERO, - * GL_ONE, - * GL_SRC_COLOR, - * GL_ONE_MINUS_SRC_COLOR, - * GL_DST_COLOR, - * GL_ONE_MINUS_DST_COLOR, - * GL_SRC_ALPHA, - * GL_ONE_MINUS_SRC_ALPHA, - * GL_DST_ALPHA, - * GL_ONE_MINUS_DST_ALPHA, - * GL_SRC_ALPHA_SATURATE - - :arg dest: Specifies how the red, green, blue, and alpha destination blending factors are computed. - :type dest: Value in... - - * GL_ZERO - * GL_ONE - * GL_SRC_COLOR - * GL_ONE_MINUS_SRC_COLOR - * GL_DST_COLOR - * GL_ONE_MINUS_DST_COLOR - * GL_SRC_ALPHA - * GL_ONE_MINUS_SRC_ALPHA - * GL_DST_ALPHA - * GL_ONE_MINUS_DST_ALPHA - * GL_SRC_ALPHA_SATURATE + :arg src: Specifies how the red, green, blue, and alpha source blending factors are computed, one of... + + * :data:`~bgl.GL_ZERO` + * :data:`~bgl.GL_ONE` + * :data:`~bgl.GL_SRC_COLOR` + * :data:`~bgl.GL_ONE_MINUS_SRC_COLOR` + * :data:`~bgl.GL_DST_COLOR` + * :data:`~bgl.GL_ONE_MINUS_DST_COLOR` + * :data:`~bgl.GL_SRC_ALPHA` + * :data:`~bgl.GL_ONE_MINUS_SRC_ALPHA` + * :data:`~bgl.GL_DST_ALPHA` + * :data:`~bgl.GL_ONE_MINUS_DST_ALPHA` + * :data:`~bgl.GL_SRC_ALPHA_SATURATE` + + :type src: int + + :arg dest: Specifies how the red, green, blue, and alpha destination blending factors are computed, one of... + + * :data:`~bgl.GL_ZERO` + * :data:`~bgl.GL_ONE` + * :data:`~bgl.GL_SRC_COLOR` + * :data:`~bgl.GL_ONE_MINUS_SRC_COLOR` + * :data:`~bgl.GL_DST_COLOR` + * :data:`~bgl.GL_ONE_MINUS_DST_COLOR` + * :data:`~bgl.GL_SRC_ALPHA` + * :data:`~bgl.GL_ONE_MINUS_SRC_ALPHA` + * :data:`~bgl.GL_DST_ALPHA` + * :data:`~bgl.GL_ONE_MINUS_DST_ALPHA` + * :data:`~bgl.GL_SRC_ALPHA_SATURATE` + + :type dest: int .. method:: getMaterialIndex() diff --git a/doc/python_api/rst/bge_types/bge.types.KX_Camera.rst b/doc/python_api/rst/bge_types/bge.types.KX_Camera.rst index 0baba5c3359..ac5ab4b5fe5 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_Camera.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_Camera.rst @@ -51,6 +51,18 @@ base class --- :class:`KX_GameObject` :type: float + .. attribute:: shift_x + + The camera's horizontal shift. + + :type: float + + .. attribute:: shift_y + + The camera's vertical shift. + + :type: float + .. attribute:: perspective True if this camera has a perspective transform, False for an orthographic projection. diff --git a/doc/python_api/rst/bge_types/bge.types.KX_CharacterWrapper.rst b/doc/python_api/rst/bge_types/bge.types.KX_CharacterWrapper.rst index 4d9dd5b5c34..e326892a824 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_CharacterWrapper.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_CharacterWrapper.rst @@ -37,7 +37,7 @@ base class --- :class:`PyObjectPlus` The speed and direction the character is traveling in using world coordinates. This should be used instead of applyMovement() to properly move the character. - :type: list [x, y, z] + :type: Vector((x, y, z)) .. method:: jump() diff --git a/doc/python_api/rst/bge_types/bge.types.KX_ConstraintWrapper.rst b/doc/python_api/rst/bge_types/bge.types.KX_ConstraintWrapper.rst index 53bef120f7a..d9f03395c34 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_ConstraintWrapper.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_ConstraintWrapper.rst @@ -23,15 +23,14 @@ base class --- :class:`PyObjectPlus` :arg axis: :type axis: integer - .. note:: - For each axis: - * Lowerlimit == Upperlimit -> axis is locked - * Lowerlimit > Upperlimit -> axis is free - * Lowerlimit < Upperlimit -> axis it limited in that range + .. note:: + * Lowerlimit == Upperlimit -> axis is locked + * Lowerlimit > Upperlimit -> axis is free + * Lowerlimit < Upperlimit -> axis it limited in that range - PHY_LINEHINGE_CONSTRAINT = 2 or PHY_ANGULAR_CONSTRAINT = 3: - axis = 3 is a constraint limit, with low/high limit value + For PHY_LINEHINGE_CONSTRAINT = 2 or PHY_ANGULAR_CONSTRAINT = 3: + axis = 3 is a constraint limit, with low/high limit value * 3: X axis angle :arg value0 (min): Set the minimum limit of the axis @@ -39,7 +38,8 @@ base class --- :class:`PyObjectPlus` :arg value1 (max): Set the maximum limit of the axis :type value1: float - PHY_CONE_TWIST_CONSTRAINT = 3: + For PHY_CONE_TWIST_CONSTRAINT = 4: + axis = 3..5 are constraint limits, high limit values * 3: X axis angle * 4: Y axis angle @@ -50,7 +50,8 @@ base class --- :class:`PyObjectPlus` :arg value1 (max): Set the maximum limit of the axis :type value1: float - PHY_GENERIC_6DOF_CONSTRAINT = 12: + For PHY_GENERIC_6DOF_CONSTRAINT = 12: + axis = 0..2 are constraint limits, with low/high limit value * 0: X axis position * 1: Y axis position @@ -133,9 +134,10 @@ base class --- :class:`PyObjectPlus` :type: integer - * 1 = POINTTOPOINT_CONSTRAINT - * 2 = LINEHINGE_CONSTRAINT - * 3 = ANGULAR_CONSTRAINT (aka LINEHINGE_CONSTRAINT) - * 4 = CONETWIST_CONSTRAINT - * 11 = VEHICLE_CONSTRAINT - * 12 = GENERIC_6DOF_CONSTRAINT + - :class:`~bge.constraints.POINTTOPOINT_CONSTRAINT` + - :class:`~bge.constraints.LINEHINGE_CONSTRAINT` + - :class:`~bge.constraints.ANGULAR_CONSTRAINT` + - :class:`~bge.constraints.CONETWIST_CONSTRAINT` + - :class:`~bge.constraints.VEHICLE_CONSTRAINT` + - :class:`~bge.constraints.GENERIC_6DOF_CONSTRAINT` + diff --git a/doc/python_api/rst/bge_types/bge.types.KX_FontObject.rst b/doc/python_api/rst/bge_types/bge.types.KX_FontObject.rst index 1961f5e3e92..ca35ff49a08 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_FontObject.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_FontObject.rst @@ -7,6 +7,26 @@ base class --- :class:`KX_GameObject` .. class:: KX_FontObject(KX_GameObject) - TODO. + A Font object. + .. code-block:: python + + # Display a message about the exit key using a Font object. + import bge + + co = bge.logic.getCurrentController() + font = co.owner + + exit_key = bge.events.EventToString(bge.logic.getExitKey()) + + if exit_key.endswith("KEY"): + exit_key = exit_key[:-3] + + font.text = "Press key '%s' to quit the game." % exit_key + + .. attribute:: text + + The text displayed by this Font object. + + :type: string diff --git a/doc/python_api/rst/bge_types/bge.types.KX_GameObject.rst b/doc/python_api/rst/bge_types/bge.types.KX_GameObject.rst index a6d03dee1a1..74df50ddb58 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_GameObject.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_GameObject.rst @@ -78,6 +78,35 @@ base class --- :class:`SCA_IObject` The object must have a physics controller for the mass to be applied, otherwise the mass value will be returned as 0.0. + .. attribute:: isSuspendDynamics + + The object's dynamic state (read-only). + + :type: boolean + + .. seealso:: :py:meth:`suspendDynamics` and :py:meth:`restoreDynamics` allow you to change the state. + + .. attribute:: linearDamping + + The object's linear damping, also known as translational damping. Can be set simultaneously with angular damping using the :py:meth:`setDamping` method. + + :type: float between 0 and 1 inclusive. + + .. note:: + + The object must have a physics controller for the linear damping to be applied, otherwise the value will be returned as 0.0. + + .. attribute:: angularDamping + + The object's angular damping, also known as rotationation damping. Can be set simultaneously with linear damping using the :py:meth:`setDamping` method. + + :type: float between 0 and 1 inclusive. + + .. note:: + + The object must have a physics controller for the angular damping to be applied, otherwise the value will be returned as 0.0. + + .. attribute:: linVelocityMin Enforces the object keeps moving at a minimum velocity. @@ -108,13 +137,36 @@ base class --- :class:`SCA_IObject` .. note:: - A value of 0.0 disables this option (rather then setting it stationary). + A value of 0.0 disables this option (rather than setting it stationary). + + .. attribute:: angularVelocityMin + + Enforces the object keeps rotating at a minimum velocity. A value of 0.0 disables this. + + :type: non-negative float + + .. note:: + + Applies to dynamic and rigid body objects only. + While objects are stationary the minimum velocity will not be applied. + + + .. attribute:: angularVelocityMax + + Clamp the maximum angular velocity to prevent objects rotating beyond a set speed. + A value of 0.0 disables clamping; it does not stop rotation. + + :type: non-negative float + + .. note:: + + Applies to dynamic and rigid body objects only. .. attribute:: localInertia the object's inertia vector in local coordinates. Read only. - :type: list [ix, iy, iz] + :type: Vector((ix, iy, iz)) .. attribute:: parent @@ -124,21 +176,70 @@ base class --- :class:`SCA_IObject` .. attribute:: groupMembers - Returns the list of group members if the object is a group object, otherwise None is returned. + Returns the list of group members if the object is a group object (dupli group instance), otherwise None is returned. :type: :class:`CListValue` of :class:`KX_GameObject` or None .. attribute:: groupObject - Returns the group object that the object belongs to or None if the object is not part of a group. + Returns the group object (dupli group instance) that the object belongs to or None if the object is not part of a group. :type: :class:`KX_GameObject` or None + .. attribute:: collisionGroup + + The object's collision group. + + :type: bitfield + + .. attribute:: collisionMask + + The object's collision mask. + + :type: bitfield + .. attribute:: collisionCallbacks - A list of callables to be run when a collision occurs. + A list of functions to be called when a collision occurs. - :type: list + :type: list of functions and/or methods + + Callbacks should either accept one argument `(object)`, or three + arguments `(object, point, normal)`. For simplicity, per + colliding object only the first collision point is reported. + + .. code-block:: python + + # Function form + def callback_three(object, point, normal): + print('Hit by %r at %s with normal %s' % (object.name, point, normal)) + + def callback_one(object): + print('Hit by %r' % object.name) + + def register_callback(controller): + controller.owner.collisionCallbacks.append(callback_three) + controller.owner.collisionCallbacks.append(callback_one) + + + # Method form + class YourGameEntity(bge.types.KX_GameObject): + def __init__(self, old_owner): + self.collisionCallbacks.append(self.on_collision_three) + self.collisionCallbacks.append(self.on_collision_one) + + def on_collision_three(self, object, point, normal): + print('Hit by %r at %s with normal %s' % (object.name, point, normal)) + + def on_collision_one(self, object): + print('Hit by %r' % object.name) + + .. note:: + For backward compatibility, a callback with variable number of + arguments (using `*args`) will be passed only the `object` + argument. Only when there is more than one fixed argument (not + counting `self` for methods) will the three-argument form be + used. .. attribute:: scene @@ -374,6 +475,12 @@ base class --- :class:`SCA_IObject` If true, the object's and children's debug properties will be displayed on screen. :type: boolean + + .. attribute:: currentLodLevel + + The index of the level of detail (LOD) currently used by this object (read-only). + + :type: int .. method:: endObject() @@ -496,7 +603,7 @@ base class --- :class:`SCA_IObject` * True: you get the "local" velocity ie: relative to object orientation. :type local: boolean :return: the object's linear velocity. - :rtype: list [vx, vy, vz] + :rtype: Vector((vx, vy, vz)) .. method:: setLinearVelocity(velocity, local=False) @@ -523,7 +630,7 @@ base class --- :class:`SCA_IObject` * True: you get the "local" velocity ie: relative to object orientation. :type local: boolean :return: the object's angular velocity. - :rtype: list [vx, vy, vz] + :rtype: Vector((vx, vy, vz)) .. method:: setAngularVelocity(velocity, local=False) @@ -547,7 +654,7 @@ base class --- :class:`SCA_IObject` :arg point: optional point to return the velocity for, in local coordinates. :type point: 3D Vector :return: the velocity at the specified point. - :rtype: list [vx, vy, vz] + :rtype: Vector((vx, vy, vz)) .. method:: getReactionForce() @@ -557,7 +664,7 @@ base class --- :class:`SCA_IObject` This also includes impulses, eg from collisions. :return: the reaction force of this object. - :rtype: list [fx, fy, fz] + :rtype: Vector((fx, fy, fz)) .. note:: @@ -580,13 +687,28 @@ base class --- :class:`SCA_IObject` * True: you get the "local" impulse ie: relative to local coordinates with object orientation. :type local: boolean - .. method:: suspendDynamics() + .. method:: setDamping(linear_damping, angular_damping) + + Sets both the :py:attr:`linearDamping` and :py:attr:`angularDamping` simultaneously. This is more efficient than setting both properties individually. + + :arg linear_damping: Linear ("translational") damping factor. + :type linear_damping: float ∈ [0, 1] + :arg angular_damping: Angular ("rotational") damping factor. + :type angular_damping: float ∈ [0, 1] + + .. method:: suspendDynamics([ghost]) Suspends physics for this object. + :arg ghost: When set to `True`, collisions with the object will be ignored, similar to the "ghost" checkbox in + Blender. When `False` (the default), the object becomes static but still collide with other objects. + :type ghost: bool + + .. seealso:: :py:attr:`isSuspendDynamics` allows you to inspect whether the object is in a suspended state. + .. method:: restoreDynamics() - Resumes physics for this object. + Resumes physics for this object. Also reinstates collisions; the object will no longer be a ghost. .. note:: @@ -850,6 +972,16 @@ base class --- :class:`SCA_IObject` :return: The current frame of the action :rtype: float + .. method:: getActionName(layer=0) + + Gets the name of the current action playing in the supplied layer. + + :arg layer: The layer that you want to get the action name from. + :type layer: integer + + :return: The name of the current action + :rtype: string + .. method:: setActionFrame(frame, layer=0) Set the current frame of the action playing in the supplied layer. @@ -876,4 +1008,4 @@ base class --- :class:`SCA_IObject` :arg name: name of the property that added to the debug list. :type name: string :arg debug: the debug state. - :type debug: boolean
\ No newline at end of file + :type debug: boolean diff --git a/doc/python_api/rst/bge_types/bge.types.KX_MeshProxy.rst b/doc/python_api/rst/bge_types/bge.types.KX_MeshProxy.rst index 9ef8d6b2026..13fb3263a59 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_MeshProxy.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_MeshProxy.rst @@ -51,7 +51,7 @@ base class --- :class:`SCA_IObject` .. attribute:: materials - :type: list of :class:`KX_BlenderMaterial` or :class:`KX_PolygonMaterial` types + :type: list of :class:`KX_BlenderMaterial` type .. attribute:: numPolygons diff --git a/doc/python_api/rst/bge_types/bge.types.KX_ObjectActuator.rst b/doc/python_api/rst/bge_types/bge.types.KX_ObjectActuator.rst index f10f101a4cc..347b000be3d 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_ObjectActuator.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_ObjectActuator.rst @@ -15,7 +15,7 @@ base class --- :class:`SCA_IActuator` The force applied by the actuator. - :type: list [x, y, z] + :type: Vector((x, y, z)) .. attribute:: useLocalForce @@ -27,7 +27,7 @@ base class --- :class:`SCA_IActuator` The torque applied by the actuator. - :type: list [x, y, z] + :type: Vector((x, y, z)) .. attribute:: useLocalTorque @@ -39,7 +39,7 @@ base class --- :class:`SCA_IActuator` The displacement vector applied by the actuator. - :type: list [x, y, z] + :type: Vector((x, y, z)) .. attribute:: useLocalDLoc @@ -51,7 +51,7 @@ base class --- :class:`SCA_IActuator` The angular displacement vector applied by the actuator - :type: list [x, y, z] + :type: Vector((x, y, z)) .. note:: @@ -67,7 +67,7 @@ base class --- :class:`SCA_IActuator` The linear velocity applied by the actuator. - :type: list [x, y, z] + :type: Vector((x, y, z)) .. attribute:: useLocalLinV @@ -83,7 +83,7 @@ base class --- :class:`SCA_IActuator` The angular velocity applied by the actuator. - :type: list [x, y, z] + :type: Vector((x, y, z)) .. attribute:: useLocalAngV diff --git a/doc/python_api/rst/bge_types/bge.types.KX_PolyProxy.rst b/doc/python_api/rst/bge_types/bge.types.KX_PolyProxy.rst index 534f6deedc0..f43cf62eec1 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_PolyProxy.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_PolyProxy.rst @@ -23,7 +23,7 @@ base class --- :class:`SCA_IObject` The material of the polygon. - :type: :class:`KX_PolygonMaterial` or :class:`KX_BlenderMaterial` + :type: :class:`KX_BlenderMaterial` .. attribute:: texture_name @@ -84,7 +84,7 @@ base class --- :class:`SCA_IObject` .. method:: getMaterial() :return: The polygon material - :rtype: :class:`KX_PolygonMaterial` or :class:`KX_BlenderMaterial` + :rtype: :class:`KX_BlenderMaterial` .. method:: getTextureName() diff --git a/doc/python_api/rst/bge_types/bge.types.KX_PolygonMaterial.rst b/doc/python_api/rst/bge_types/bge.types.KX_PolygonMaterial.rst deleted file mode 100644 index 3421e194d77..00000000000 --- a/doc/python_api/rst/bge_types/bge.types.KX_PolygonMaterial.rst +++ /dev/null @@ -1,250 +0,0 @@ -KX_PolygonMaterial(PyObjectPlus) -================================ - -.. module:: bge.types - -base class --- :class:`PyObjectPlus` - -.. class:: KX_PolygonMaterial(PyObjectPlus) - - This is the interface to materials in the game engine. - - Materials define the render state to be applied to mesh objects. - - .. warning:: - - Some of the methods/variables are CObjects. If you mix these up, you will crash blender. - - .. code-block:: python - - from bge import logic - - vertex_shader = """ - - void main(void) - { - // original vertex position, no changes - gl_Position = ftransform(); - // coordinate of the 1st texture channel - gl_TexCoord[0] = gl_MultiTexCoord0; - // coordinate of the 2nd texture channel - gl_TexCoord[1] = gl_MultiTexCoord1; - } - """ - - fragment_shader =""" - - uniform sampler2D color_0; - uniform sampler2D color_1; - uniform float factor; - - void main(void) - { - vec4 color_0 = texture2D(color_0, gl_TexCoord[0].st); - vec4 color_1 = texture2D(color_1, gl_TexCoord[1].st); - gl_FragColor = mix(color_0, color_1, factor); - } - """ - - object = logic.getCurrentController().owner - object = cont.owner - for mesh in object.meshes: - for material in mesh.materials: - shader = material.getShader() - if shader != None: - if not shader.isValid(): - shader.setSource(vertex_shader, fragment_shader, True) - - # get the first texture channel of the material - shader.setSampler('color_0', 0) - # get the second texture channel of the material - shader.setSampler('color_1', 1) - # pass another uniform to the shader - shader.setUniform1f('factor', 0.3) - - - .. attribute:: texture - - Texture name. - - :type: string (read-only) - - .. attribute:: gl_texture - - OpenGL texture handle (eg for glBindTexture(GL_TEXTURE_2D, gl_texture). - - :type: integer (read-only) - - .. attribute:: material - - Material name. - - :type: string (read-only) - - .. attribute:: tface - - Texture face properties. - - :type: CObject (read-only) - - .. attribute:: tile - - Texture is tiling. - - :type: boolean - - .. attribute:: tilexrep - - Number of tile repetitions in x direction. - - :type: integer - - .. attribute:: tileyrep - - Number of tile repetitions in y direction. - - :type: integer - - .. attribute:: drawingmode - - Drawing mode for the material. - - 2 (drawingmode & 4) Textured - - 4 (drawingmode & 16) Light - - 14 (drawingmode & 16384) 3d Polygon Text. - - :type: bitfield - - .. attribute:: transparent - - This material is transparent. All meshes with this - material will be rendered after non transparent meshes from back - to front. - - :type: boolean - - .. attribute:: zsort - - Transparent polygons in meshes with this material will be sorted back to - front before rendering. - Non-Transparent polygons will be sorted front to back before rendering. - - :type: boolean - - .. attribute:: diffuse - - The diffuse color of the material. black = [0.0, 0.0, 0.0] white = [1.0, 1.0, 1.0]. - - :type: list [r, g, b] - - .. attribute:: specular - - The specular color of the material. black = [0.0, 0.0, 0.0] white = [1.0, 1.0, 1.0]. - - :type: list [r, g, b] - - .. attribute:: shininess - - The shininess (specular exponent) of the material. 0.0 <= shininess <= 128.0. - - :type: float - - .. attribute:: specularity - - The amount of specular of the material. 0.0 <= specularity <= 1.0. - - :type: float - - .. method:: updateTexture(tface, rasty) - - Updates a realtime animation. - - :arg tface: Texture face (eg mat.tface) - :type tface: CObject - :arg rasty: Rasterizer - :type rasty: CObject - - .. method:: setTexture(tface) - - Sets texture render state. - - :arg tface: Texture face - :type tface: CObject - - .. code-block:: python - - mat.setTexture(mat.tface) - - .. method:: activate(rasty, cachingInfo) - - Sets material parameters for this object for rendering. - - Material Parameters set: - - #. Texture - #. Backface culling - #. Line drawing - #. Specular Colour - #. Shininess - #. Diffuse Colour - #. Polygon Offset. - - :arg rasty: Rasterizer instance. - :type rasty: CObject - :arg cachingInfo: Material cache instance. - :type cachingInfo: CObject - - .. method:: setCustomMaterial(material) - - Sets the material state setup object. - - Using this method, you can extend or completely replace the gameengine material - to do your own advanced multipass effects. - - Use this method to register your material class. Instead of the normal material, - your class's activate method will be called just before rendering the mesh. - This should setup the texture, material, and any other state you would like. - It should return True to render the mesh, or False if you are finished. You should - clean up any state Blender does not set before returning False. - - Activate Method Definition: - - .. code-block:: python - - def activate(self, rasty, cachingInfo, material): - - :arg material: The material object. - :type material: instance - - .. code-block:: python - - class PyMaterial: - def __init__(self): - self.pass_no = -1 - - def activate(self, rasty, cachingInfo, material): - # Activate the material here. - # - # The activate method will be called until it returns False. - # Every time the activate method returns True the mesh will - # be rendered. - # - # rasty is a CObject for passing to material.updateTexture() - # and material.activate() - # cachingInfo is a CObject for passing to material.activate() - # material is the KX_PolygonMaterial instance this material - # was added to - - # default material properties: - self.pass_no += 1 - if self.pass_no == 0: - material.activate(rasty, cachingInfo) - # Return True to do this pass - return True - - # clean up and return False to finish. - self.pass_no = -1 - return False - - # Create a new Python Material and pass it to the renderer. - mat.setCustomMaterial(PyMaterial()) - diff --git a/doc/python_api/rst/bge_types/bge.types.KX_Scene.rst b/doc/python_api/rst/bge_types/bge.types.KX_Scene.rst index f2dad58731c..5bd8e3a77de 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_Scene.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_Scene.rst @@ -83,6 +83,12 @@ base class --- :class:`PyObjectPlus` This can be set directly from python to avoid using the :class:`KX_SceneActuator`. + .. attribute:: world + + The current active world, (read-only). + + :type: :class:`KX_WorldInfo` + .. attribute:: suspended True if the scene is suspended, (read-only). @@ -119,21 +125,27 @@ base class --- :class:`PyObjectPlus` :type: list + .. attribute:: pre_draw_setup + + A list of callables to be run before the drawing setup (i.e., before the model view and projection matrices are computed). + + :type: list + .. attribute:: gravity The scene gravity using the world x, y and z axis. - :type: list [fx, fy, fz] + :type: Vector((gx, gy, gz)) - .. method:: addObject(object, other, time=0) + .. method:: addObject(object, reference, time=0) Adds an object to the scene like the Add Object Actuator would. - :arg object: The object to add + :arg object: The (name of the) object to add. :type object: :class:`KX_GameObject` or string - :arg other: The object's center to use when adding the object - :type other: :class:`KX_GameObject` or string - :arg time: The lifetime of the added object, in frames. A time of 0 means the object will last forever. + :arg reference: The (name of the) object which position, orientation, and scale to copy (optional), if the object to add is a light and there is not reference the light's layer will be the same that the active layer in the blender scene. + :type reference: :class:`KX_GameObject` or string + :arg time: The lifetime of the added object, in frames. A time of 0 means the object will last forever (optional). :type time: integer :return: The newly added object. :rtype: :class:`KX_GameObject` diff --git a/doc/python_api/rst/bge_types/bge.types.KX_VehicleWrapper.rst b/doc/python_api/rst/bge_types/bge.types.KX_VehicleWrapper.rst index 9340d33f8a9..631075363ca 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_VehicleWrapper.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_VehicleWrapper.rst @@ -11,22 +11,25 @@ base class --- :class:`PyObjectPlus` TODO - description - .. method:: addWheel(wheel, attachPos, attachDir, axleDir, suspensionRestLength, wheelRadius, hasSteering) + .. method:: addWheel(wheel, attachPos, downDir, axleDir, suspensionRestLength, wheelRadius, hasSteering) Add a wheel to the vehicle :arg wheel: The object to use as a wheel. - :type wheel: :class:`KX_GameObject` or a KX_GameObject name - :arg attachPos: The position that this wheel will attach to. + :type wheel: :class:`KX_GameObject` or a :class:`KX_GameObject` name + :arg attachPos: The position to attach the wheel, relative to the chassis object center. :type attachPos: vector of 3 floats - :arg attachDir: The direction this wheel points. - :type attachDir: vector of 3 floats - :arg axleDir: The direction of this wheels axle. + :arg downDir: The direction vector pointing down to where the vehicle should collide with the floor. + :type downDir: vector of 3 floats + :arg axleDir: The axis the wheel rotates around, relative to the chassis. :type axleDir: vector of 3 floats - :arg suspensionRestLength: TODO - Description + :arg suspensionRestLength: The length of the suspension when no forces are being applied. :type suspensionRestLength: float - :arg wheelRadius: The size of the wheel. + :arg wheelRadius: The radius of the wheel (half the diameter). :type wheelRadius: float + :arg hasSteering: True if the wheel should turn with steering, typically used in front wheels. + :type hasSteering: boolean + .. method:: applyBraking(force, wheelIndex) @@ -38,6 +41,7 @@ base class --- :class:`PyObjectPlus` :arg wheelIndex: index of the wheel where the force needs to be applied :type wheelIndex: integer + .. method:: applyEngineForce(force, wheelIndex) Apply an engine force to the specified wheel @@ -48,6 +52,7 @@ base class --- :class:`PyObjectPlus` :arg wheelIndex: index of the wheel where the force needs to be applied :type wheelIndex: integer + .. method:: getConstraintId() Get the constraint ID diff --git a/doc/python_api/rst/bge_types/bge.types.KX_VertexProxy.rst b/doc/python_api/rst/bge_types/bge.types.KX_VertexProxy.rst index 9c0d1169d49..73d692770d6 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_VertexProxy.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_VertexProxy.rst @@ -17,25 +17,25 @@ base class --- :class:`SCA_IObject` The position of the vertex. - :type: list [x, y, z] + :type: Vector((x, y, z)) .. attribute:: UV The texture coordinates of the vertex. - :type: list [u, v] + :type: Vector((u, v)) .. attribute:: normal The normal of the vertex. - :type: list [nx, ny, nz] + :type: Vector((nx, ny, nz)) .. attribute:: color The color of the vertex. - :type: list [r, g, b, a] + :type: Vector((r, g, b, a)) Black = [0.0, 0.0, 0.0, 1.0], White = [1.0, 1.0, 1.0, 1.0] @@ -110,13 +110,13 @@ base class --- :class:`SCA_IObject` Gets the position of this vertex. :return: this vertexes position in local coordinates. - :rtype: list [x, y, z] + :rtype: Vector((x, y, z)) .. method:: setXYZ(pos) Sets the position of this vertex. - :type: list [x, y, z] + :type: Vector((x, y, z)) :arg pos: the new position for this vertex in local coordinates. @@ -125,26 +125,26 @@ base class --- :class:`SCA_IObject` Gets the UV (texture) coordinates of this vertex. :return: this vertexes UV (texture) coordinates. - :rtype: list [u, v] + :rtype: Vector((u, v)) .. method:: setUV(uv) Sets the UV (texture) coordinates of this vertex. - :type: list [u, v] + :type: Vector((u, v)) .. method:: getUV2() Gets the 2nd UV (texture) coordinates of this vertex. :return: this vertexes UV (texture) coordinates. - :rtype: list [u, v] + :rtype: Vector((u, v)) .. method:: setUV2(uv, unit) Sets the 2nd UV (texture) coordinates of this vertex. - :type: list [u, v] + :type: Vector((u, v)) :arg unit: optional argument, FLAT==1, SECOND_UV==2, defaults to SECOND_UV :arg unit: integer @@ -197,7 +197,7 @@ base class --- :class:`SCA_IObject` Gets the normal vector of this vertex. :return: normalized normal vector. - :rtype: list [nx, ny, nz] + :rtype: Vector((nx, ny, nz)) .. method:: setNormal(normal) diff --git a/doc/python_api/rst/bge_types/bge.types.KX_WorldInfo.rst b/doc/python_api/rst/bge_types/bge.types.KX_WorldInfo.rst new file mode 100644 index 00000000000..a636af4f083 --- /dev/null +++ b/doc/python_api/rst/bge_types/bge.types.KX_WorldInfo.rst @@ -0,0 +1,79 @@ +KX_WorldInfo(PyObjectPlus) +============================= + +.. module:: bge.types + +base class --- :class:`PyObjectPlus` + +.. class:: KX_WorldInfo(PyObjectPlus) + + A world object. + + .. code-block:: python + + # Set the mist color to red. + import bge + + sce = bge.logic.getCurrentScene() + + sce.world.mistColor = [1.0, 0.0, 0.0] + + .. data:: KX_MIST_QUADRATIC + + Type of quadratic attenuation used to fade mist. + + .. data:: KX_MIST_LINEAR + + Type of linear attenuation used to fade mist. + + .. data:: KX_MIST_INV_QUADRATIC + + Type of inverse quadratic attenuation used to fade mist. + + .. attribute:: mistEnable + + Return the state of the mist. + + :type: bool + + .. attribute:: mistStart + + The mist start point. + + :type: float + + .. attribute:: mistDistance + + The mist distance fom the start point to reach 100% mist. + + :type: float + + .. attribute:: mistIntensity + + The mist intensity. + + :type: float + + .. attribute:: mistType + + The type of mist - must be KX_MIST_QUADRATIC, KX_MIST_LINEAR or KX_MIST_INV_QUADRATIC + + .. attribute:: mistColor + + The color of the mist. Black = [0.0, 0.0, 0.0], White = [1.0, 1.0, 1.0]. + Mist and background color sould always set to the same color. + + :type: :class:`mathutils.Vector` + + .. attribute:: backgroundColor + + The color of the background. Black = [0.0, 0.0, 0.0], White = [1.0, 1.0, 1.0]. + Mist and background color sould always set to the same color. + + :type: :class:`mathutils.Vector` + + .. attribute:: ambientColor + + The color of the ambient light. Black = [0.0, 0.0, 0.0], White = [1.0, 1.0, 1.0]. + + :type: :class:`mathutils.Vector` diff --git a/doc/python_api/rst/bge_types/bge.types.SCA_2DFilterActuator.rst b/doc/python_api/rst/bge_types/bge.types.SCA_2DFilterActuator.rst index 291ee8426cf..0a6c5fc9025 100644 --- a/doc/python_api/rst/bge_types/bge.types.SCA_2DFilterActuator.rst +++ b/doc/python_api/rst/bge_types/bge.types.SCA_2DFilterActuator.rst @@ -7,7 +7,7 @@ base class --- :class:`SCA_IActuator` .. class:: SCA_2DFilterActuator(SCA_IActuator) - Create, enable and disable 2D filters + Create, enable and disable 2D filters. The following properties don't have an immediate effect. You must active the actuator to get the result. @@ -29,7 +29,7 @@ base class --- :class:`SCA_IActuator` .. attribute:: mode - Type of 2D filter, use one of :ref:`these constants <Two-D-FilterActuator-mode>` + Type of 2D filter, use one of :ref:`these constants <Two-D-FilterActuator-mode>`. :type: integer diff --git a/doc/python_api/rst/bge_types/bge.types.SCA_ISensor.rst b/doc/python_api/rst/bge_types/bge.types.SCA_ISensor.rst index 9efd2e2d63a..af444fb9e65 100644 --- a/doc/python_api/rst/bge_types/bge.types.SCA_ISensor.rst +++ b/doc/python_api/rst/bge_types/bge.types.SCA_ISensor.rst @@ -23,8 +23,14 @@ base class --- :class:`SCA_ILogicBrick` .. attribute:: frequency - The frequency for pulse mode sensors. - + The frequency for pulse mode sensors. (Deprecated: use SCA_ISensor.skippedTicks) + + :type: integer + + .. attribute:: skippedTicks + + Number of logic ticks skipped between 2 active pulses + :type: integer .. attribute:: level diff --git a/doc/python_api/rst/bge_types/bge.types.SCA_PythonMouse.rst b/doc/python_api/rst/bge_types/bge.types.SCA_PythonMouse.rst index b1c6e5d1487..5dfa78d3942 100644 --- a/doc/python_api/rst/bge_types/bge.types.SCA_PythonMouse.rst +++ b/doc/python_api/rst/bge_types/bge.types.SCA_PythonMouse.rst @@ -25,7 +25,7 @@ base class --- :class:`PyObjectPlus` The normalized x and y position of the mouse cursor. - :type: list [x, y] + :type: tuple (x, y) .. attribute:: visible |