Python updates:
[blender.git] / source / gameengine / PyDoc / KX_SCA_ReplaceMeshActuator.py
1 # $Id$
2 # Documentation for KX_SCA_ReplaceMeshActuator
3 from SCA_IActuator import *
4
5 class KX_SCA_ReplaceMeshActuator(SCA_IActuator):
6         """
7         Edit Object actuator, in Replace Mesh mode.
8         
9         Example::
10                 # Level-of-detail
11                 # Switch a game object's mesh based on its depth in the camera view.
12                 # +----------+     +-----------+     +-------------------------------------+
13                 # | Always   +-----+ Python    +-----+ Edit Object (Replace Mesh) LOD.Mesh |
14                 # +----------+     +-----------+     +-------------------------------------+
15                 import GameLogic
16
17                 # List detail meshes here
18                 # Mesh (name, near, far)
19                 # Meshes overlap so that they don't 'pop' when on the edge of the distance.
20                 meshes = ((".Hi", 0.0, -20.0),
21                           (".Med", -15.0, -50.0),
22                           (".Lo", -40.0, -100.0)
23                           )
24                 
25                 co = GameLogic.getCurrentController()
26                 obj = co.getOwner()
27                 act = co.getActuator("LOD." + obj.getName())
28                 cam = GameLogic.getCurrentScene().active_camera
29                 
30                 def Depth(pos, plane):
31                         return pos[0]*plane[0] + pos[1]*plane[1] + pos[2]*plane[2] + plane[3]
32                 
33                 # Depth is negative and decreasing further from the camera
34                 depth = Depth(obj.position, cam.world_to_camera[2])
35                 
36                 newmesh = None
37                 curmesh = None
38                 # Find the lowest detail mesh for depth
39                 for mesh in meshes:
40                         if depth < mesh[1] and depth > mesh[2]:
41                                 newmesh = mesh
42                         if "ME" + obj.getName() + mesh[0] == act.getMesh():
43                                 curmesh = mesh
44                 
45                 if newmesh != None and "ME" + obj.getName() + newmesh[0] != act.getMesh():
46                         # The mesh is a different mesh - switch it.
47                         # Check the current mesh is not a better fit.
48                         if curmesh == None or curmesh[1] < depth or curmesh[2] > depth:
49                                 act.setMesh(obj.getName() + newmesh[0])
50                                 GameLogic.addActiveActuator(act, True)
51         
52         @warning: Replace mesh actuators will be ignored if at game start, the
53                 named mesh doesn't exist.
54                 
55                 This will generate a warning in the console:
56                 
57                 C{ERROR: GameObject I{OBName} ReplaceMeshActuator I{ActuatorName} without object}
58         """
59         def setMesh(name):
60                 """
61                 Sets the name of the mesh that will replace the current one.
62                 
63                 @type name: string
64                 """
65         def getMesh():
66                 """
67                 Returns the name of the mesh that will replace the current one.
68                 
69                 @rtype: string
70                 """
71