Space Class
Space is part of the KBEngine module.
More...
import KBEngine
Member Functions
def addProximity( self, range, userArg ):
def addTimer( self, start, interval=0.0, userData=0 ):
def delTimer( self, id ):
def destroy( self ):
def entitiesInRange( self, range, entityType=None, position=None ):
def getRandomPoints( self, centerPos, maxRadius, maxPoints, layer ):
def getComponent( self, componentName, all ):
def fireEvent( self, eventName, *args ):
def registerEvent( self, eventName, callback ):
def deregisterEvent( self, eventName, callback ):
Callback Functions
def onDestroy( self ):
def onEnterTrap( self, entity, rangeXZ, rangeY, controllerID, userArg ):
def onLeaveTrap( self, entity, rangeXZ, rangeY, controllerID, userArg ):
def onRestore( self ):
def onSpaceGone( self ):
def onTimer( self, timerHandle, userData ):
def onUpdateBegin( self ):
def onUpdateEnd( self ):
Properties
spaceID Read-only Integer
base Read-only BaseEntityCall
className Read-only string
id Read-only Integer
isDestroyed Read-only bool
Detailed Description
Space is an abstract concept that exists only in CellApp memory.
By creating a KBEngine.Space entity on the BaseApp, the engine allocates a Space on the CellApp and creates the corresponding cell entity inside this new Space.
This Space is isolated from other Spaces. View management, trigger systems, entity collisions, and similar systems only interact with entities within the same Space.
Because Space is an abstract concept, its concrete meaning is defined by the user.
It can represent a scene, an instance, a room, and so on.
For example, in an MMORPG, a map or dungeon is a Space. Only characters, monsters, and NPCs within the Space can interact with each other. When teleporting to another map, monsters and NPCs in the previous map become invisible and non-interactable.
Similarly, in card games, there are usually many rooms. Each room represents a game session. Players in different rooms do not interact with each other (except for systems such as global chat).
Space itself is also an Entity. When a Space is created, it automatically calls createCellEntityInNewSpace.
All attributes and methods are the same as those of Entity. To avoid confusion, methods and properties that are not applicable to Space are removed here.
Member Function Documentation
def addProximity( self, rangeXZ, rangeY, userArg ):
Description:
Creates a proximity trigger. When another entity enters or leaves this trigger area, the associated Entity will be notified.
The trigger area is square (for performance reasons). If another entity is within the given distance on both the X and Z axes, it is considered inside the area.
The Entity is notified via the onEnterTrap and onLeaveTrap callbacks, which can be defined as:
def onEnterTrap( self, entityEntering, rangeXZ, rangeY, controllerID, userArg = 0 ):
def onLeaveTrap( self, entityLeaving, rangeXZ, rangeY, controllerID, userArg = 0 ):Since the proximity trigger is implemented as a controller, it can be removed using
Entity.cancelController with the controller ID.
Note that callbacks may be triggered immediately, even before addProximity() returns.
See Also:
Parameters:
rangeXZ: float
Size of the trigger area on the XZ plane. Must be >= 0.
rangeY: float
Height of the trigger area on the Y axis. Must be >= 0.
For this parameter to take effect, Y-axis range management must be enabled inkbengine_defaults.xml → cellapp → coordinate_system → rangemgr_y.
Enabling Y-axis management introduces additional overhead, especially in games where many entities share the same or similar Y coordinates, making collisions very dense.
This option is more suitable for 3D space games or small-room games with fewer entities.
userArg: integer
Optional user-defined value passed to callbacks.
It is recommended to define a default value of 0 in the callback signature.
Returns:
Controller ID of the created trigger.
def addTimer( self, start, interval=0.0, userData=0 ):
Description:
Registers a timer. The timer triggers the callback function onTimer.
The callback will be executed for the first time after initialOffset seconds, and then repeatedly every repeatOffset seconds.
The onTimer function must be defined in the entity’s cell part and must take two parameters:
- Timer ID (integer)
- User-defined argument
userArg
Example:
import KBEngine
class MyCellEntity( KBEngine.Entity ):
def __init__( self ):
KBEngine.Entity.__init__( self )
# First call after 5 seconds, then every 1 second, userArg = 9
self.addTimer( 5, 1, 9 )
# One-shot timer after 1 second
self.addTimer( 1 )
def onTimer( self, id, userArg ):
print "MyCellEntity.onTimer called: id %i, userArg: %i" % ( id, userArg )
# Remove repeating timer if no longer needed
# self.delTimer( id )Parameters:
initialOffset: float
Time in seconds before the first callback.
repeatOffset: float
Interval between callbacks. Must be removed using delTimer or it will repeat indefinitely.
Values <= 0 are ignored.
userArg: integer
User data passed to the callback.
Returns:
Integer timer ID.
def delTimer( self, id ):
Description:
Removes a registered timer.
One-shot timers are removed automatically after execution.
Using an invalid ID (for example, one that has already been removed) will raise an error.
Parameters:
id: integer
Timer ID to remove.
If the value is the string "All", all timers will be removed at once.
def destroy( self ):
Description:
Destroys the local Entity instance.
If the entity has ghost parts on other processes, they will also be notified and destroyed.
This method should generally be called by the entity itself.
Calling it on a ghost entity will raise an exception.
If implemented, the onDestroy() callback will be invoked.
def entitiesInRange( self, range, entityType=None, position=None ):
Description:
Searches for Entity objects within a given distance.
This is a spherical search: distances are measured on all three axes.
Entities outside the View range can be found, but entities on other Cell processes cannot.
Examples:
self.entitiesInRange( 100, 'Creature', (100, 0, 100) )Searches for entities of type Creature within 100 meters of position (100, 0, 100).
[ e for e in self.entitiesInRange( 100, None, (100,0,100) ) if isinstance( e, BaseType ) ]Returns entities that are instances of BaseType or its subclasses.
Parameters:
range: float
Search radius.
entityType: string (optional)
Entity type name for filtering.
If it is a valid entity class name (defined in res/scripts/entities.xml), only that type is returned.
position: Vector3 (optional)
Search center position. Defaults to the entity’s own position.
Returns:
List of Entity objects.
def getRandomPoints( self, centerPos, maxRadius, maxPoints, layer ):
Description:
Returns random positions reachable by
Entity.navigate within a given area.
Parameters:
centerPos: Vector3
Center position.
maxRadius: float
Maximum search radius.
maxPoints: uint32
Maximum number of random points to return.
layer: int8
Navmesh layer to use.
Returns:
tuple containing one or more positions.
def getComponent( self, componentName, all ):
Description:
Returns component instances of the specified type bound to the entity.
Parameters:
componentName: string
Component module name.
all: bool
If True, returns all matching components.
Otherwise, returns the first one or an empty list.
def fireEvent( self, eventName, *args ):
Description:
Triggers an entity event.
Parameters:
eventName: string
Event name.
args:
Event payload arguments.
def registerEvent( self, eventName, callback ):
Description:
Registers an event listener.
Parameters:
eventName: string
Event name.
callback:
Callback invoked when the event is fired.
def deregisterEvent( self, eventName, callback ):
Description:
Unregisters an event listener.
Parameters:
eventName: string
Event name.
callback:
Callback to remove.
Callback Function Documentation
def onDestroy( self ):
Called after Entity.destroy() is invoked and before the entity is actually destroyed.
def onEnterTrap( self, entity, rangeXZ, rangeY, controllerID, userArg ):
Called when another entity enters a proximity trigger.
def onLeaveTrap( self, entity, rangeXZ, rangeY, controllerID, userArg ):
Called when another entity leaves a proximity trigger.
def onRestore( self ):
Called when the entity is recreated on another CellApp after a CellApp crash.
def onSpaceGone( self ):
Called when the current Space is about to be destroyed.
def onTimer( self, timerHandle, userData ):
Called when a timer associated with this entity is triggered.
def onUpdateBegin( self ):
Called at the beginning of a synchronization frame.
def onUpdateEnd( self ):
Called at the end of a synchronization frame.
Property Documentation
base
Read-only EntityCall used to communicate with the corresponding
Entity on the BaseApp.
If the entity has no associated BaseApp entity, the value is None.
Type:
Read-only ENTITYCALL
spaceID
ID of the Space the entity belongs to.
Type:
Read-only Integer
className
Entity class name.
Type:
Read-only string
id
Object ID of the Entity.
The ID is shared between Base and Cell representations.
Type:
Read-only int32
isDestroyed
Indicates whether the entity has been destroyed.
Type:
Read-only bool