BGE API cleanup: DynamicActuator, ReplaceMeshActuator, TrackToActuator.
[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         Properties:
60         @ivar mesh: the name of the mesh that will replace the current one
61                     Set to None to disable actuator
62         @type mesh: string or None if no mesh is set
63         """
64         def setMesh(name):
65                 """
66         DEPRECATED: Use the mesh property instead.
67                 Sets the name of the mesh that will replace the current one.
68                 When the name is None it will unset the mesh value so no action is taken.
69                 
70                 @type name: string or None
71                 """
72         def getMesh():
73                 """
74         DEPRECATED: Use the mesh property instead.
75                 Returns the name of the mesh that will replace the current one.
76                 
77                 Returns None if no mesh has been scheduled to be added.
78                 
79                 @rtype: string or None
80                 """
81