BGE API cleanup: apply patch from Moguri: Near, Radar, Touch sensor updated.
[blender.git] / source / gameengine / PyDoc / KX_Scene.py
1 # $Id$
2 # Documentation for KX_Scene.py
3
4 class KX_Scene:
5         """
6         Scene.
7         
8         The activity culling stuff is supposed to disable logic bricks when their owner gets too far
9         from the active camera.  It was taken from some code lurking at the back of KX_Scene - who knows 
10         what it does!
11         
12         Example::
13                 import GameLogic
14                 
15                 # get the scene
16                 scene = GameLogic.getCurrentScene()
17                 
18                 # print all the objects in the scene
19                 for obj in scene.getObjectList():
20                         print obj.getName()
21                 
22                 # get an object named 'Cube'
23                 obj = scene.getObjectList()["OBCube"]
24                 
25                 # get the first object in the scene.
26                 obj = scene.getObjectList()[0]
27         
28         Example::
29                 # Get the depth of an object in the camera view.
30                 import GameLogic
31                 
32                 obj = GameLogic.getCurrentController().getOwner()
33                 cam = GameLogic.getCurrentScene().active_camera
34                 
35                 # Depth is negative and decreasing further from the camera
36                 depth = obj.position[0]*cam.world_to_camera[2][0] + obj.position[1]*cam.world_to_camera[2][1] + obj.position[2]*cam.world_to_camera[2][2] + cam.world_to_camera[2][3]
37         
38         @bug: All attributes are read only at the moment.
39                 
40         @ivar name: The scene's name
41         @type name: string
42         @type objects: A list of objects in the scene.
43         @type objects: list [L{KX_GameObject}]
44         @ivar active_camera: The current active camera
45         @type active_camera: L{KX_Camera}
46         @ivar suspended: True if the scene is suspended.
47         @type suspended: boolean
48         @ivar activity_culling: True if the scene is activity culling
49         @type activity_culling: boolean
50         @ivar activity_culling_radius: The distance outside which to do activity culling.  Measured in manhattan distance.
51         @type activity_culling_radius: float
52         """
53         
54         def getLightList():
55                 """
56                 Returns the list of lights in the scene.
57                 
58                 @rtype: list [L{KX_Light}]
59                 """
60         def getObjectList():
61                 """
62                 Returns the list of objects in the scene.
63                 
64                 @rtype: list [L{KX_GameObject}]
65                 """
66         def getName():
67                 """
68                 Returns the name of the scene.
69                 
70                 @rtype: string
71                 """
72
73         def addObject(object, other, time=0)
74                 """
75                 Adds an object to the scene like the Add Object Actuator would, and returns the created object.
76                 
77                 @param object: The object to add
78                 @type object: L{KX_GameObject} or string
79                 @param other: The object's center to use when adding the object
80                 @type other: L{KX_GameObject} or string
81                 @param time: The lifetime of the added object, in frames. A time of 0 means the object will last forever.
82                 @type time: int
83                 
84                 @rtype: L{KX_GameObject}
85                 """