EntityComponent Class
EntityComponent is part of the KBEngine module. More...
import KBEngine
Member Functions
def addTimer( self, start, interval=0.0, userData=0 ):
def delTimer( self, id ):
def clientEntity( self, destID ):
Callback Functions
def onAttached( self,owner ):
def onDetached( self ,owner):
def onDestroy( self ):
def onEnterTrap( self, entity, rangeXZ, rangeY, controllerID, userArg ):
def onEnteredView( self, entity ):
def onGetWitness( self ):
def onLeaveTrap( self, entity, rangeXZ, rangeY, controllerID, userArg ):
def onLoseControlledBy( self, id ):
def onLoseWitness( self ):
def onMove( self, controllerID, userData ):
def onMoveOver( self, controllerID, userData ):
def onMoveFailure( self, controllerID, userData ):
def onRestore( self ):
def onSpaceGone( self ):
def onTurn( self, controllerID, userData ):
def onTeleport( self ):
def onTeleportFailure( self ):
def onTeleportSuccess( self, nearbyEntity ):
def onTimer( self, timerHandle, userData ):
def onUpdateBegin( self ):
def onUpdateEnd( self ):
def onWitnessed( self, isWitnessed ):
def onWriteToDB( self ):
Properties
ownerID Read-only int32
owner Read-only ENTITYCALL
name Read-only string
allClients Read-only PyClient
base Read-only BaseEntityCall
client Read-only ClientEntityCall
isDestroyed Read-only bool
otherClients Read-only PyClient
Detailed Description
In traditional structural design, "inheritance" is generally used to describe the relationship between objects. Subclasses inherit from parent classes to obtain their functionality. When designing game objects, various functional supports such as rendering, collision, rigid body, particle system, etc., are added to game objects as needed by the game itself. To provide these general functions to all subclasses, they must be implemented in the base class. This leads to a very bloated and hard-to-maintain game object base class.
The "component-based" object model separates all basic functions needed by game objects into independent "component modules". A specific game object can combine the functional modules it needs. All "functions" are no longer interfaces in the parent class, but become sub-object instances that provide services for the game object. This ensures code reusability and increases the modularity and flexibility of the entire object system.
Member Function Documentation
def addTimer( self, start, interval=0.0, userData=0 ):
Description:
Registers a timer, which is triggered by the callback function onTimer. The callback will be executed for the first time after "initialOffset" seconds, and then every "repeatOffset" seconds. You can set a user parameter "userArg" (integer only).
The onTimer function must be defined in the cell part of the entity and must have two parameters: the first is the timer id (integer, can be used to remove the timer with "delTimer"), and the second is the user parameter "userArg".
Example:
# Example usage of addTimer
import KBEngine
class MyCellEntity( KBEngine.Entity ):
def __init__( self ):
KBEngine.Entity.__init__( self )
# Add a timer, first execution after 5 seconds, then every 1 second, user parameter is 9
self.addTimer( 5, 1, 9 )
# Add a timer, execute after 1 second, user parameter defaults to 0
self.addTimer( 1 )
# Entity's timer callback "onTimer" is called
def onTimer( self, id, userArg ):
print "MyCellEntity.onTimer called: id %i, userArg: %i" % ( id, userArg )
# if this is a repeating timer, call the following function to remove it when no longer needed:
# self.delTimer( id )Parameters:
initialOffset: float, specifies the interval (in seconds) from registration to the first callback.
repeatOffset: float, specifies the interval (in seconds) between each execution after the first callback. Must be removed with delTimer, otherwise it will repeat indefinitely. Values less than or equal to 0 will be ignored.
userArg: integer, specifies the userArg parameter value when the underlying "onTimer" is called.
Returns:
integer, the function returns the internal id of the timer, which can be used to remove the timer with delTimer.
def delTimer( self, id ):
Description:
The delTimer function is used to remove a registered timer. The removed timer will no longer execute. Timers that only execute once are automatically removed after the callback, so there is no need to remove them with delTimer. If delTimer is called with an invalid id (e.g., already removed), an error will occur.
Parameters:
id: integer, specifies the timer id to remove. If the parameter is the string "All", all timers will be removed at once.
def clientEntity( self, destID ):
Description:
This method allows you to access the methods of an entity on your own client (the current entity must be bound to a client), but only entities within the View range are synchronized to the client. It can only be called on a real entity.
Parameters:
destID: The target entity's ID.
Callback Function Documentation
def onAttached( self, owner ):
Description:
If this function is implemented in the script, it is called when the component is attached.
Parameters:
owner: The entity object that owns this component.
def onDetached( self, owner ):
Description:
If this function is implemented in the script, it is called when the component is detached.
Parameters:
owner: The entity object that owns this component.
def onDestroy( self ):
If this function is implemented in the script, it is called after Entity.destroy() is called but before the actual destruction. This function has no parameters.
def onEnterTrap( self, entity, rangeXZ, rangeY, controllerID, userArg ):
When a proximity trigger is registered using Entity.addProximity, and another entity enters the trigger, this callback is called.
Parameters:
entity: The entity that has entered the range.
rangeXZ: float, the size of the trigger area on the xz axis, must be greater than or equal to 0.
rangeY: float, the height of the trigger area on the y axis, must be greater than or equal to 0.
Note: For this parameter to take effect, you must enable kbengine_defaults.xml ->cellapp->coordinate_system->rangemgr_y.
Enabling y-axis management brings some overhead, as many games have a lot of entities at the same or similar y height, making collisions very dense.
3D space games or games with few entities in small rooms are more suitable for enabling this option.
controllerID: The controller id of this trigger.
userArg: The value of this parameter is given by the user when calling addProximity, and can be used to make judgments about the current behavior.
def onEnteredView( self, entity ):
If this function is implemented in the script, it is triggered when an entity enters the current entity's View range.
Parameters:
entity: The entity that entered the View range.
def onGetWitness( self ):
If this function is implemented in the script, it is called when the entity is bound to a Witness.
You can also access the entity property Entity.hasWitness to get the current state.
def onLeaveTrap( self, entity, rangeXZ, rangeY, controllerID, userArg ):
If this function is implemented in the script, it is triggered when an entity leaves the area of the proximity trigger registered by the current entity, which is registered by Entity.addProximity.
Parameters:
entity: The entity that has left the trigger area.
rangeXZ: float, the size of the trigger area on the xz axis, must be greater than or equal to 0.
rangeY: [ float, the height of the trigger area on the y axis, must be greater than or equal to 0. Note: For this parameter to take effect, you must enable kbengine_defaults.xml ->cellapp->coordinate_system->rangemgr_y.
Enabling y-axis management brings some overhead, as many games have a lot of entities at the same or similar y height, making collisions very dense. 3D space games or games with few entities in small rooms are more suitable for enabling this option.
controllerID: The controller ID of this trigger.
userArg: The value of this parameter is given by the user when calling addProximity, and can be used to make judgments about the current behavior.
def onLoseControlledBy( self, id ):
If this function is implemented in the script, it is called when the entity associated with Entity.controlledBy is lost.
Parameters:
id: The ID of the controlledBy entity.
def onLoseWitness( self ):
If this function is implemented in the script, it is triggered when the entity is unbound from Witness.
You can also access the entity property Entity.hasWitness to get the current state.
def onMove( self, controllerID, userData ):
If this function is implemented in the script, it is called every frame when Entity.moveToPoint, Entity.moveToEntity, or Entity.navigate is called and succeeds.
Parameters:
controllerID: The controller ID associated with a movement.
userData: The value of this parameter is given by the user when requesting movement-related interfaces.
def onMoveOver( self, controllerID, userData ):
If this function is implemented in the script, it is called when Entity.moveToPoint, Entity.moveToEntity, or Entity.navigate is called and the target point is reached.
Parameters:
controllerID: The controller ID associated with a movement.
userData: The value of this parameter is given by the user when requesting movement-related interfaces.
def onMoveFailure( self, controllerID, userData ):
If this function is implemented in the script, it is called when Entity.moveToPoint, Entity.moveToEntity, or Entity.navigate is called and fails.
Parameters:
controllerID: The controller ID associated with a movement.
userData: The value of this parameter is given by the user when requesting movement-related interfaces.
def onRestore( self ):
If this function is implemented in the script, it is called when the entity is recreated on another Cell application after the Cell application crashes. This function has no parameters.
def onSpaceGone( self ):
If this function is implemented in the script, it is triggered when the Space where the current entity is located is about to be destroyed. This function has no parameters.
def onTurn( self, controllerID, userData ):
If this function is implemented in the script, it is called when Entity.addYawRotator is called and the specified yaw is reached.
Parameters:
controllerID: The controller ID returned by Entity.addYawRotator.
userData: The value of this parameter is given by the user when requesting movement-related interfaces.
def onTeleport( self ):
If this function is implemented in the script, it is called before the entity (Real entity) is teleported when Entity.teleport is called on baseapp.
Note: Calling teleport on the cell will not trigger this callback. If you need this functionality, please call this callback after Entity.teleport.
def onTimer( self, timerHandle, userData ):
Description:
This function is called when a timer associated with this entity is triggered. A timer can be added using Entity.addTimer.
Parameters:
timerHandle: The id of the timer.
userData: The integer user data passed in Entity.addTimer.
def onTeleportFailure( self ):
If this function is implemented in the script, it is called when Entity.teleport fails.
def onTeleportSuccess( self, nearbyEntity ):
If this function is implemented in the script, it is called when Entity.teleport succeeds.
Parameters:
[nearbyEntity]
This parameter is given by the user when calling Entity.teleport. This is a real entity.
def onUpdateBegin( self ):
Called at the beginning of a synchronization frame.
def onUpdateEnd( self ):
Called at the end of a synchronization frame.
def onWitnessed( self, isWitnessed ):
If this function is implemented in the script, it is called when the current entity enters the View range of another entity bound to Witness (i.e., the entity is observed by an observer).
You can use this function to activate the entity's AI when it is observed, and stop the AI when it is no longer observed, reducing server computation and improving efficiency.
Parameters:
isWitnessed: bool, True when the entity is observed, False when it is no longer observed. You can also access the entity property Entity.isWitnessed to get the current state.
def onWriteToDB( self ):
If this function is implemented in the script, it is called when the entity is about to be archived to the database.
Property Documentation
ownerID
Description:
ownerID is the entity ID of the owner. This id is an integer. This property is read-only.
Type:
Read-only int32
owner
Description:
owner specifies the entity object that owns this component.
When using, call the corresponding method of the owner entity with self.owner.xxx
Type:
Read-only ENTITYCALL
name
Description:
The name of the component.
Type:
Read-only string
allClients
By calling the entity's client remote method through this property, the engine will broadcast the message to all other entities with clients in the entity's View range (including its own client; entities with clients are usually players).
Example:
There are player A, player B, and monster C in the avatar's View range.
avatar.allClients.attack(monsterID, skillID, damage)
At this time, the player's own client, player A's client, and player B's client will all call the entity's attack method, and the corresponding attack action can be performed on their clients.
See also:
Entity.clientEntity
Entity.otherClients
base
base is the entityCall used to contact the Entity entity. This property is read-only, and if the entity does not have an associated Entity entity, the property is None.
See also:
Entity.clientEntity
Entity.allClients
Entity.otherClients
Type:
Read-only ENTITYCALL
client
client is the entityCall used to contact the client. This property is read-only, and if the entity does not have an associated client, the property is None.
See also:
Entity.clientEntity
Entity.allClients
Entity.otherClients
Type:
Read-only ENTITYCALL
className
The class name of the entity.
Type:
Read-only string
isDestroyed
If this property is True, the Entity has been destroyed.
Type:
Read-only bool
otherClients
By calling the entity's client remote method through this property, the engine will broadcast the message to all other entities with clients in the entity's View range (excluding its own client; entities with clients are usually players).
Example:
There are player A, player B, and monster C in the avatar's View range.
avatar.otherClients.attack(monsterID, skillID, damage)
At this time, player A's and player B's clients will call the entity's attack method, and the corresponding attack action can be performed on their clients.
See also: