bw logo
Chapter 2. Directory Structure for Entity Scripting
Prev  Part I. Server Scripting Guide  Next

Chapter 2. Directory Structure for Entity Scripting

Table of Contents

2.1. The entities.xml File
2.2. The Entity Definition File
2.3. The Entity Script Files

Entities are the objects that make up the game world. Using entities, you can create players, NPCs, loot, chat rooms, and many other interactive elements in your games.

Each entity type is implemented as a collection of Python scripts, and an XML-based definition file that ties the scripts together. These scripts are located in the resource tree under the folder scripts (i.e., <res>/scripts , where <res> is the virtual tree defined ~/.bwmachined.conf).

The list below summarises the important files and directories for entities in <res>:

  • <res> ‐ Resource tree defined in ~/.bwmachined.conf .

    • scripts ‐ Folder containing all entity files.

      • db.xml ‐ Persistent state for the XML database system.

      • entities.xml ‐ Lists all entities to load into the client or the server at start-up time.

      • base ‐ Folder contains Python scripts for entities with a base component.

      • cell ‐ Folder contains Python scripts for entities with a cell component.

      • client ‐ Folder contains Python scripts for entities with a client component.

      • common ‐ Folder listed in the Python search path for all components. Used for common game code.

        • lib ‐ Folder listed in the Python search path for all components. Used for common game code.

      • entity_defs ‐ Contains an XML .def file for each entity listed in file <res>/scripts/entities.xml.

        • alias.xml ‐ Data types aliases used in the project.

        • <entity>.def ‐ Entity definition file. There is one such file for each entity defined in <res>/scripts/entities.xml.

        • interfaces ‐ Entity interface definition files

    • server ‐ System-wide settings.

      • Default values for the system.

2.1. The entities.xml File

The file <res>/scripts/entities.xml is used by the BigWorld engine to determine the types of entities available for use.

Each tag in this file represents an entity type, and must have a corresponding definition file in the directory <res>/scripts/entity_defs, and at least one Python script file in either the <res>/scripts/base or <res>/scripts/cell directory. It may also have a script file in <res>/scripts/client.

The order in which the entity types are declared in this file corresponds to the final entity ID associated with each entity type.

In its simplest form, the entities file has one tag listed for each entity to be loaded.

To define an entity called NewEntityType, simply add a line like the one below: 

<root>
  ...
  <NewEntityType/>
</root>

<res>/scripts/entities.xml ‐ Entity definition

2.2. The Entity Definition File

The entity definition file <res>/scripts/entity_defs/<entity>.def determines how your scripts communicate in BigWorld. This allows the BigWorld system to abstract the tasks of sending and receiving messages into simply calling different script methods on your entities. In a sense, the definition file provides an interface to your entity, and the Python scripts provide the implementation.

The following diagram shows the conceptual parts of a BigWorld entity:

Conceptual parts of an entity

Each entity type has a corresponding definition file, named after the entity's type name followed by the extension '.def'. For example, a Seat entity type would have a file called Seat.def.

It is useful then, to have a 'minimal' definition file to aid in quickly defining a new entity, as well as to assist in explaining what the document's section is trying to accomplish.

The following file is a minimal entity definition file:

<root>

  <Parent> optional parent entity </Parent> 1

  <Implements> 2
     <!-- interface references -->
   </Implements>

  <ClientName> optional client type </ClientName> 3
  
  <Volatile> 4
     <!-- volatile definitions -->
   </Volatile>
  
  <AppealRadius> optional appeal radius </AppealRadius> 5
  
  <DetailedPosition> 6
     <SendLatestOnly> whether to only send the most recent position </SendLatestOnly>
   </DetailedPosition>

   <Properties> 7
     <!-- properties -->
   </Properties>

  <ClientMethods> 8
     <!-- declaration --> 
   </ClientMethods>

  <CellMethods> 9
     <!-- declaration --> 
   </CellMethods>

  <BaseMethods> 10
     <!-- declaration --> 
   </BaseMethods>

  <LoDLevels> 11
    <!-- levels of detail -->
   </LODLevels>

  <NetworkCompression> 12
    <!-- internal and external network compression -->
   </NetworkCompression>
</root>

<res>/scripts/entity_defs/<entity>.def ‐ Minimal entity definition file

1

For details, see Entity Parents.

2

For details, see Entity Interfaces.

3

For details, see Client Entity Reuse.

4

For details, see Volatile Properties.

5

For details, see Appeal Radius.

6

For details, see Detailed Position.

7

For details, see Properties.

8

For details, see Methods.

9

For details, see Methods.

10

For details, see Methods.

11

For details, see LOD (Level of Detail) on Properties.

12

For details, see Server Operations Guide's chapter General Configuration Options for the networkCompression options.

By the end of this chapter, we should be able to replace all placeholders (denoted by italics) in the example file above with actual code.

2.3. The Entity Script Files

BigWorld Technology divides processing of entities in a game world into three different execution contexts:

Entity type Script file location Description
Cell <res>/scripts/cell Takes care of the portions of an entity that affect the space around it. Processing takes place on the server cluster.
Base <res>/scripts/base Takes care of the portions of an entity that do not affect the space around it (as well as possibly acting as a proxy for a player). Processing takes place on the server cluster.
Client <res>/scripts/client Takes care of the portions of an entity that require heavy awareness of the surrounding environment.

Entity Types

It is possible for some entity instances to not have one of these three parts. Furthermore, some entity types may not support ever having one of these parts. For each entity type, there is a script file for each of CellApp, BaseApp, and Client, if that type supports that execution context.

These script files are named after the entity type, followed by the extension '.py'. This file must contain a class with the name of the entity type.

For example, if you have an entity type Seat that can have cell, base and client execution contexts, there would be three script files, each with the implementation of the class:

  • <res>/scripts/cell/Seat.py

  • <res>/scripts/base/Seat.py

  • <res>/scripts/client/Seat.py

The entity's base class defined in the script file is determined by the execution context that the file represents, as described below:

Script file execution context Entity's base class
Cell BigWorld.Entity
Base BigWorld.Base or BigWorld.Proxy
Client BigWorld.Entity

Entity's base class per execution context

For more details about the difference between the Base and Proxy classes, see Proxies and Players.

The start of the script for a Seat entity could be implemented as below:

  • Cell script file ‐ <res>/scripts/cell/Seat.py

    import BigWorld

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

  • Base script file ‐ <res>/scripts/base/Seat.py

    import BigWorld

class Seat( BigWorld.Base ):
  def __init__( self ):
    BigWorld.Base.__init__( self )

  • Client script file ‐ <res>/scripts/client/Seat.py

    import BigWorld

class Seat( BigWorld.Entity ):
  def __init__( self ):
    BigWorld.Entity.__init__( self )
Prev  Up  Next
Chapter 1. Overview  Home  Chapter 3. Directory Structure for Service Scripting
Copyright 1999-2012 BigWorld Pty. Ltd. All rights reserved. Proprietary commercial in confidence.