KX_Scene(EXP_PyObjectPlus)

base class — EXP_PyObjectPlus

class bge.types.KX_Scene(EXP_PyObjectPlus)

An active scene that gives access to objects, cameras, lights and scene attributes.

The activity culling stuff is supposed to disable logic bricks when their owner gets too far from the active camera. It was taken from some code lurking at the back of KX_Scene - who knows what it does!

from bge import logic

# get the scene
scene = logic.getCurrentScene()

# print all the objects in the scene
for object in scene.objects:
   print(object.name)

# get an object named 'Cube'
object = scene.objects["Cube"]

# get the first object in the scene.
object = scene.objects[0]

# Get the depth of an object in the camera view.
from bge import logic

object = logic.getCurrentController().owner
cam = logic.getCurrentScene().active_camera

# Depth is negative and decreasing further from the camera
depth = object.position[0]*cam.world_to_camera[2][0] + object.position[1]*cam.world_to_camera[2][1] + object.position[2]*cam.world_to_camera[2][2] + cam.world_to_camera[2][3]

@bug: All attributes are read only at the moment.

name

The scene’s name, (read-only).

Type: string

objects

A list of objects in the scene, (read-only).

Type: EXP_ListValue of KX_GameObject

objectsInactive

A list of objects on background layers (used for the addObject actuator), (read-only).

Type: EXP_ListValue of KX_GameObject

lights

A list of lights in the scene, (read-only).

Type: EXP_ListValue of KX_LightObject

cameras

A list of cameras in the scene, (read-only).

Type: EXP_ListValue of KX_Camera

texts

A list of texts in the scene, (read-only).

Type: EXP_ListValue of KX_FontObject

active_camera

The current active camera.

import bge

own = bge.logic.getCurrentController().owner
scene = own.scene

scene.active_camera = scene.objects["Camera.001"]

Type: KX_Camera

Note

This can be set directly from python to avoid using the KX_SceneActuator.

overrideCullingCamera

Deprecated since version 0.3.0: The override camera used for scene culling, if set to None the culling is proceeded with the camera used to render.

type: KX_Camera or None

world

Deprecated since version 0.3.0: The current active world, (read-only).

type: KX_WorldInfo

filterManager

The scene’s 2D filter manager, (read-only).

Type: KX_2DFilterManager

suspended

Deprecated since version 0.3.0: True if the scene is suspended, (read-only).

type: boolean

activityCulling

True if the scene allow object activity culling.

Type: boolean

dbvt_culling

Deprecated since version 0.3.0: True when Dynamic Bounding box Volume Tree is set (read-only).

type: boolean

pre_draw

A list of callables to be run before the render step. The callbacks can take as argument the rendered camera.

Type: list

post_draw

A list of callables to be run after the render step.

Type: list

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). The callbacks can take as argument the rendered camera, the camera could be temporary in case of stereo rendering.

Type: list

onRemove

A list of callables to run when the scene is destroyed.

@scene.onRemove.append
def callback(scene):
   print('exiting %s...' % scene.name)

Type: list

gravity

The scene gravity using the world x, y and z axis.

Type: Vector((gx, gy, gz))

property logger

A logger instance that can be used to log messages related to this object (read-only).

Type: logging.Logger

property loggerName

A name used to create the logger instance. By default, it takes the form KX_Scene[Name].

Type: str

addObject(object, reference, time=0.0, dupli=False)

Adds an object to the scene like the Add Object Actuator would.

Parameters

object (KX_GameObject or string) – The (name of the) object to add.
reference (KX_GameObject or string) – 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.
time (float) – The lifetime of the added object, in frames (assumes one frame is 1/60 second). A time of 0.0 means the object will last forever (optional).
dupli (boolean) – Full duplication of object data (mesh, materials…).

Returns

The newly added object.

Return type

KX_GameObject

end(): Removes the scene from the game.

restart(): Restarts the scene.

replace(scene)

Replaces this scene with another one.

Parameters: scene (string) – The name of the scene to replace this scene with.
Returns: True if the scene exists and was scheduled for addition, False otherwise.
Return type: boolean

suspend()

Deprecated since version 0.3.0: Suspends this scene.

resume()

Deprecated since version 0.3.0: Resume this scene.

get(key, default=None): Return the value matching key, or the default value if its not found. :return: The key value or a default.

drawObstacleSimulation(): Draw debug visualization of obstacle simulation.

convertBlenderObject(blenderObject)

Converts a Object into a KX_GameObject during runtime. For example, you can append an Object from another .blend file during bge runtime using: bpy.ops.wm.append(…) then convert this Object into a KX_GameObject to have logic bricks, physics… converted. This is meant to replace libload.

Parameters: blenderObject (Object) – The Object to be converted.
Returns: Returns the newly converted gameobject.
Return type: KX_GameObject

convertBlenderObjectsList(blenderObjectsList, asynchronous)

Converts all bpy.types.Object inside a python List into its correspondent KX_GameObject during runtime. For example, you can append an Object List during bge runtime using: ob = object_data_add(…) and ML.append(ob) then convert the Objects inside the List into several KX_GameObject to have logic bricks, physics… converted. This is meant to replace libload. The conversion can be asynchronous or synchronous.

Parameters

blenderObjectsList (list of Object) – The Object list to be converted.
asynchronous (boolean) – The Object list conversion can be asynchronous or not.

convertBlenderCollection(blenderCollection, asynchronous)

Converts all bpy.types.Object inside a Collection into its correspondent KX_GameObject during runtime. For example, you can append a Collection from another .blend file during bge runtime using: bpy.ops.wm.append(…) then convert the Objects inside the Collection into several KX_GameObject to have logic bricks, physics… converted. This is meant to replace libload. The conversion can be asynchronous or synchronous.

Parameters

blenderCollection (Collection) – The collection to be converted.
asynchronous (boolean) – The collection conversion can be asynchronous or not.

convertBlenderAction(Action)

Registers a bpy.types.Action into the bge logic manager to be abled to play it during runtime. For example, you can append an Action from another .blend file during bge runtime using: bpy.ops.wm.append(…) then register this Action to be abled to play it.

Parameters: Action (Action) – The Action to be converted.

unregisterBlenderAction(Action)

Unregisters a bpy.types.Action from the bge logic manager. The unregistered action will still be in the .blend file but can’t be played anymore with bge. If you want to completely remove the action you need to call bpy.data.actions.remove(Action, do_unlink=True) after you unregistered it from bge logic manager.

Parameters: Action (Action) – The Action to be unregistered.

addOverlayCollection(kxCamera, blenderCollection)

Adds an overlay collection (as with collection actuator) to render this collection objects during a second render pass in overlay using the KX_Camera passed as argument.

Parameters

kxCamera (KX_Camera) – The camera used to render the overlay collection.
blenderCollection (Collection) – The overlay collection to add.

removeOverlayCollection(blenderCollection)

Removes an overlay collection (as with collection actuator).

Parameters: blenderCollection (Collection) – The overlay collection to remove.

getGameObjectFromObject(blenderObject)

Get the KX_GameObject corresponding to the blenderObject.

Parameters: blenderObject (bpy.types.Object) – the Object from which we want to get the KX_GameObject.
Return type: KX_GameObject