In order to automatically play an idle animation and to create the action required for the Greeter entity to wave, we need to add animations to the model and configure the appropriate actions. This is done in the Model Editor.

While an animation is a raw sequence of key frames, an action is a higher level concept. Actions are animation wrappers that contain extra information such as animation blending and what game-play situations will trigger the animation (e.g. idling, walking or running based on the velocity of the entity).

The Greeter will have two actions: an Idle action which is automatically selected when the entity is standing still, and a Wave action which will be explicitly invoked from the Greeter's Python scripts.

First off, we need to tell the engine about our new entity. Every entity must be defined in the entities.xml file located at tutorial/res path. We add the Greeter to the ClientServerEntities block since the entity will exist on both client and server.

<root>
   <ClientServerEntities>
      <Avatar/>
      <Greeter/>
   </ClientServerEntities>
   <ServerOnlyEntities>
      <Space/>
   </ServerOnlyEntities>
</root>

Remember that since the entity name corresponds with a Python class name, the name used here must conform with Python naming rules.

In order to allow the engine to know what methods and properties the entity has, we need to create a special file known as the entity definition file. In some ways this file is the most important part of an entity, as it defines how properties and methods are handled by the engine (e.g. property type, whether or not a property or method is exposed to clients, prioritisation of remote method calls and property updates, and configuring distance based LoD parameters for individual properties).

See the Server Programming Guide chapter The Entity Definition File for a detailed description of entity definitions.

For the Greeter entity, create a new file named Greeter.def and place it in tutorial/res/scripts/entity_defs/. We will define the following information for our entity:

<root>
    <Properties>
        <radius>
            <Type>          FLOAT
                <Widget>    RADIUS
                    <colour>    255 0 0 192   </colour>
                    <gizmoRadius>    2        </gizmoRadius>
                </Widget>
            </Type>
            <Flags>          CELL_PRIVATE    </Flags>
            <Default>        3.0             </Default>
            <Editable>       true            </Editable>
        </radius>
        
        <activated>
            <Type>           INT8            </Type>
            <Flags>          ALL_CLIENTS     </Flags>
            <Default>        1               </Default>
        </activated>

        <createOnCell>
             <Type>    MAILBOX        </Type>
             <Flags>   BASE           </Flags>
        </createOnCell>
    </Properties>

    <ClientMethods>
        <greet>
            <Arg> UINT32 </Arg> <!-- Entity ID of who we are greeting -->
            <Arg> STRING </Arg> <!-- Our greeting message -->
        </greet>
    </ClientMethods>

    <CellMethods>
        <toggleActive>
            <Exposed/>
        </toggleActive>
    </CellMethods>

    <BaseMethods>
    </BaseMethods>
</root>

Example tutorial/res/scripts/entity_defs/Greeter.def

The base part of the entity is the first part that gets created by the server. The base is created on one of the BaseApp processes, and is used to define entity logic which does not require spatial information (e.g. character inventory). The base part of an entity does not migrate between BaseApps after it has been created.

The base script for the Greeter entity is very simple and performs two tasks:

import BigWorld

class Greeter( BigWorld.Base ):
    def __init__( self ):
        BigWorld.Base.__init__( self )
        self.createCellEntity( self.createOnCell )

    def onLoseCell( self ):
        self.destroy()

Example tutorial/res/scripts/base/Greeter.py

The cell part of an entity represents the current position, orientation, and movement for an entity within a particular space. Managed by the CellApp processes, the cell part of an entity can be moved between CellApp processes at any time based on CPU load. Generally, all entity logic that requires access to spatial information is implemented in the cell part of an entity (e.g. any code that needs to find out about other nearby entities, such as AI).

The cell part of the Greeter performs the following tasks:

Cell entities must derive from the BigWorld.Entity class.

import BigWorld
import Avatar
import random

MESSAGES = [ "Hello BigWorld", "Have a nice day" ]

class Greeter( BigWorld.Entity ):

    def __init__( self ):
        BigWorld.Entity.__init__( self )

        # Setup the trap
        self.addProximity( self.radius, 0 )

    def onEnterTrap( self, entityEntering, range, controllerID ):
        # If we are not active, do nothing.
        if not self.activated:
            return

        # Filter by entity class type
        if not isinstance( entityEntering, Avatar.Avatar ):
            return

        # Notify clients.
        self.allClients.greet( entityEntering.id, random.choice(MESSAGES) )

    def toggleActive( self, sourceID ):
        # Get the entity who called us. If the entity can't be found then they
        # obviously not near by so just bail out.
        try:
            sourceEntity = BigWorld.entities[ sourceID ]
        except KeyError:
            return
            
        # Get the distance between ourself and the Avatar
        dist = sourceEntity.position.distTo( self.position )
        
        # Do a check to make sure they are close enough.
        if dist > self.radius:
            return
            
        # All good, toggle our state. The activated property will be automatically 
        # propagated to all clients once this server tick is complete.
        self.activated = not self.activated

Example tutorial/res/scripts/cell/Greeter.py

The client part of the entity is automatically created by the engine whenever an entity appears within your Avatar's area of interest (AoI). It is the job of the client scripts to coordinate all resources and logic required to represent the entity on the client based on the information provided by the server.

# Greeter.py

import BigWorld
import GUI
import Math

class Greeter( BigWorld.Entity ):
    def __init__( self ):
        BigWorld.Entity.__init__( self )

GREETER_MODEL_NAME = "characters/barbarian.model"

class Greeter( BigWorld.Entity ):
    ....

    def prerequisites( self ):
        return [ GREETER_MODEL_NAME ]

class Greeter( BigWorld.Entity ):
    ....

    def onEnterWorld( self, prereqs ):
        # Setup our model.
        self.model = BigWorld.Model( GREETER_MODEL_NAME )

        # Setup an appropriate filter.
        self.filter = BigWorld.DumbFilter()

    def onLeaveWorld( self ):
        # Clean up.
        self.model = None
        self.filter = None

class Greeter( BigWorld.Entity ):
    ....

    def greet( self, targetID, msg ):
        # Grab the entity instance, if for some reason we don't have it just do nothing.
        try:
            targetEntity = BigWorld.entities[targetID]
        except KeyError:
            return
            
        # Try to play the Wave action. If it doesn't exist, print a warning.
        try:
            self.model.Wave()
        except AttributeError:
            print "WARNING: Greeter model missing Wave action (%s)" % self.model.sources
    
        # Display the greet message above our head.
        addressee = targetEntity.name        
        if targetID == BigWorld.player().id:
            addressee += "! Yes you"
            
        self._displayMessage( "Hey %s! '%s'!" % (addressee, msg) )

class Greeter( BigWorld.Entity ):
    ....

    def _displayMessage( self, msg ):
        # First make sure any previous message is cleared.
        self._clearMessage()
        
        # Create our text component. Since we want to display it in the world
        # we shall explicitly set our width and height in world units.
        text = GUI.Text( msg )
        text.explicitSize = True
        text.size = ( 0, 0.5 )             # Specifying 0 for x to auto-calculate aspect ratio.
        text.colour = (255, 0, 0, 255)     # Change the colour.
        text.filterType = "LINEAR"         # Don't use point filtering.
        text.verticalAnchor = "BOTTOM"     # Position relative to the bottom of the text.
        
        # The origin of our model is at our feet. To place the text above
        # our head, move it up on the Y by our model's height.
        text.position = (0, self.model.height + 0.1, 0)
        
        # Setup our GUI->World attachment. Tell it that we want the GUI 
        # component to always face the camera.
        atch = GUI.Attachment()
        atch.component = text
        atch.faceCamera = True
        
        # Attach to our model's root node.
        self.model.root.attach( atch )
        
        # Save a reference to the attachment so we can clean it up later.
        self._messageAttachment = atch
        
        # Setup the timer.
        self._setMessageHideTimer()

class Greeter( BigWorld.Entity ):
    ....

    def _clearMessage( self ):
        self._cancelMessageTimer()
        if self._messageAttachment is not None:
            self.model.root.detach( self._messageAttachment )
            self._messageAttachment = None

    def _setMessageHideTimer( self, timeout=5.0 ):
        self._cancelMessageTimer()
        self._messageTimerHandle = \
            BigWorld.callback( timeout, self._handleMessageHideTimer )

    def _cancelMessageTimer( self ):
        if self._messageTimerHandle is not None:
            BigWorld.cancelCallback( self._messageTimerHandle )
            self._messageTimerHandle = None

    def _handleMessageHideTimer( self ):
        self._messageTimerHandle = None
        self._clearMessage()

    def set_activated( self, oldValue ):
        if self.activated:
            self._displayMessage( "Alright! I'm now ready to GREET." )
        else:
            self._displayMessage( "Shutting up now." )

The editor script for an entity allows programmatic control over how the entity behaves in the World Editor. For the Greeter entity, the script will simply override the default model used to represent the entity in the editor (it otherwise defaults to a red box).

Editor scripts are located in res/scripts/editor.

class Greeter:
    def modelName( self, props ):
        return "characters/barbarian.model"