Chapter 4. Directory Structure for User Data Object Scripting

Chapter 4. Directory Structure for User Data Object Scripting
Prev	Part I. Server Scripting Guide	Next

Chapter 4. Directory Structure for User Data Object Scripting

Table of Contents

4.1. The user_data_objects.xml File
4.2. The User Data Object Definition File
4.3. The User Data Object Script Files

User data objects are a way of embedding user defined data in Chunk files. Each user data object 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).

User data objects differ from entities in that they are immutable (i.e. their properties don't change), and that they are not propagated to other cells or clients. This makes them a lot lighter than entities.

A key feature of user data objects is their linkability. Entities are able to link to user data objects, and user data objects are able to link to other user data objects. This is achieved by including a UDO_REF property in the definition file for the user data object or entity that wishes to link to another user data object.

The list below summarises the important files and directories for user data objects in <res>:

<res> — Resource tree defined in ~/.bwmachined.conf.
- scripts — Folder containing all entity files.
  - user_data_objects.xml — Lists all user data objects to load into the client or the server at start-up time.
  - base — Folder contains Python scripts for user data objects with a base component.
  - cell — Folder contains Python scripts for user data objects with a cell component.
  - client — Folder contains Python scripts for user data objects 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.
  - user_data_object_defs — Contains the user data object definition files.
    
    <user_data_object.def> — User data object definition file. There is one such file for each user data object defined in <res>/scripts/user_data_objects.xml.
    
    interfaces — User data object interface definition files

4.1. The user_data_objects.xml File

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

The file structure matches that of the <res>/entities/entities.xml. For further details refer to The entities.xml File

4.2. The User Data Object Definition File

The user data object definition file <res>/scripts/user_data_object_defs/<user_data_object>.def determines the properties it will store and make accessible to BigWorld user data objects. The user data object definition file also specifies if the user data object should be created in the server or in the client.

The following file is a minimal entity definition file:

<root>

  <Domain> the execution context for this user </Domain> 

  <Parent> optional parent entity </Parent> 

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

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

</root>

<res>/scripts/user_data_object_defs/<user_data_object>.def — Minimal user data object definition file

	The domain for a user data object can be either CLIENT, CELL or BASE.
	For details, see Entity Parents.
	For details, see Entity Interfaces.
	For details, see Properties.

4.3. The User Data Object Script Files

BigWorld Technology divides processing of user data objects in a game world into three different execution contexts, depending on its Domain:

User Data Object Domain: Cell — Script File Location: <res>/scripts/cell

User data objects to be used by entities in the cell.
User Data Object Domain: Base — Script File Location: <res>/scripts/base

User data objects to be used by entities in the base.
User Data Object Domain: Client — Script File Location: <res>/scripts/client

User data objects to be used by entities in the client.

Most implementations of user data objects will only live either in the cell or in the client. For an example of a user data object that lives in the cell, see the PatrolNode user data object scripts and definition file in the <res>/scripts folder. For an example of a client-only user data object, look in the same place for the scripts and definition file of the CameraNode user data object.

Prev	Up	Next
Chapter 3. Directory Structure for Service Scripting	Home	Chapter 5. Properties
Copyright 1999-2012 BigWorld Pty. Ltd. All rights reserved. Proprietary commercial in confidence.