CullInstance

Inherits: Spatial < Node < Object

Inherited By: VisibilityNotifier, VisualInstance

Parent of all nodes that can be culled by the Portal system.

Description

Provides common functionality to nodes that can be culled by the Portal system.

Static and Dynamic objects are the most efficiently managed objects in the system, but there are some caveats. They are expected to be present initially when Rooms are converted using the RoomManager rooms_convert function, and their lifetime should be the same as the game level (i.e. present until you call rooms_clear on the RoomManager. Although you shouldn't create / delete these objects during gameplay, you can manage their visibility with the standard hide and show commands.

Roaming objects on the other hand, require extra processing to keep track of which Room they are within. This enables them to be culled effectively, wherever they are.

Global objects are not culled by the portal system, and use view frustum culling only.

Objects that are not Static or Dynamic can be freely created and deleted during the lifetime of the game level.

Properties

bool

allow_merging

true

int

autoplace_priority

0

bool

include_in_bound

true

PortalMode

portal_mode

0

Enumerations

enum PortalMode:

PortalMode PORTAL_MODE_STATIC = 0

Use for instances within Rooms that will not move - e.g. walls, floors.

Note: If you attempt to delete a PORTAL_MODE_STATIC instance while the room graph is loaded (converted), it will unload the room graph and deactivate portal culling. This is because the room graph data has been invalidated. You will need to reconvert the rooms using the RoomManager to activate the system again.

PortalMode PORTAL_MODE_DYNAMIC = 1

Use for instances within rooms that will move but not change room - e.g. moving platforms.

Note: If you attempt to delete a PORTAL_MODE_DYNAMIC instance while the room graph is loaded (converted), it will unload the room graph and deactivate portal culling. This is because the room graph data has been invalidated. You will need to reconvert the rooms using the RoomManager to activate the system again.

PortalMode PORTAL_MODE_ROAMING = 2

Use for instances that will move between Rooms - e.g. players.

PortalMode PORTAL_MODE_GLOBAL = 3

Use for instances that will be frustum culled only - e.g. first person weapon, debug.

PortalMode PORTAL_MODE_IGNORE = 4

Use for instances that will not be shown at all - e.g. manual room bounds (specified by prefix 'Bound_').

Property Descriptions

bool allow_merging = true

  • void set_allow_merging ( bool value )

  • bool get_allow_merging ( )

This allows fine control over the mesh merging feature in the RoomManager.

Setting this option to false can be used to prevent an instance being merged. When set to true (the default), merging will be determined by Spatial.merging_mode.

Deprecated. This property has been deprecated and is only included for backward compatibility. Please use Spatial.merging_mode instead.

int autoplace_priority = 0

  • void set_portal_autoplace_priority ( int value )

  • int get_portal_autoplace_priority ( )

When set to 0, CullInstances will be autoplaced in the Room with the highest priority.

When set to a value other than 0, the system will attempt to autoplace in a Room with the autoplace_priority, if it is present.

This can be used to control autoplacement of building exteriors in an outer RoomGroup.

bool include_in_bound = true

  • void set_include_in_bound ( bool value )

  • bool get_include_in_bound ( )

When a manual bound has not been explicitly specified for a Room, the convex hull bound will be estimated from the geometry of the objects within the room. This setting determines whether the geometry of an object is included in this estimate of the room bound.

Note: This setting is only relevant when the object is set to PORTAL_MODE_STATIC or PORTAL_MODE_DYNAMIC, and for Portals.

PortalMode portal_mode = 0

When using Rooms and Portals, this specifies how the CullInstance is processed in the system.