Server Programming Guide

Table of Contents

I. Server Scripting Guide

1. Overview

2. Directory Structure for Entity Scripting

2.1. The entities.xml File

2.2. The Entity Definition File

2.3. The Entity Script Files

3. Directory Structure for Service Scripting

3.1. The services.xml File

3.2. The Service Definition File

3.3. The Service Script Files

4. Directory Structure for User Data Object Scripting

4.1. The user_data_objects.xml File

4.2. The User Data Object Definition File

4.3. The User Data Object Script Files

5. Properties

5.1. Property Types

5.1.1. Primitive Types

5.1.2. Composite Types

5.1.3. Custom User Types

5.1.4. Alias of Data Types

5.2. Server to Client bandwidth usage of Property updates

5.3. Default Values

5.4. Data Distribution

5.4.1. Valid Data Distribution Combinations

5.4.2. Using Distribution Flags

5.4.3. Data Propagation

5.5. Implementing Custom Property Data Types

5.5.1. Wrapping a FIXED_DICT Data Type

5.6. Volatile Properties

5.7. LOD (Level of Detail) on Properties

5.7.1. LOD and Hysteresis

5.8. Bandwidth Optimisation: Send Latest Only

5.9. Bandwidth Optimisation: Is Reliable

5.10. Detailed Position

5.11. Appeal Radius

5.12. Temporary Properties

5.13. Persistent

5.14. User Data Object Linking With UDO_REF Properties

6. Methods

6.1. Basic Method Specification

6.2. Two-way calls

6.2.1. Twisted Deferred Objects

6.2.2. Error objects

6.3. Service Methods

6.4. Intra-Entity Communication

6.5. Bandwidth Optimisation: Send Latest Only

6.6. Bandwidth Optimisation: Is Reliable

6.7. Sending Auxiliary Data to the Client Via Proxy

6.8. Exposed Methods ‐ Client-to-Server Communication

6.8.1. Security Considerations of Exposed Methods

6.9. Server to Client bandwidth usage of Method calls

6.10. Client callbacks on property changes

6.10.1. Implicit set_<property_name> Methods

6.10.2. Implicit setNested_<property_name> Methods

6.10.3. Implicit setSlice_<property_name> Methods

6.11. LOD on Methods

6.12. Inter-Entity Communication

6.12.1. Entity IDs

6.12.2. Retrieving Services

6.13. Mailboxes

6.13.1. Special Mailboxes

6.14. Method Execution Context

7. Inheritance in BigWorld

7.1. Python Class Inheritance

7.2. Entity Interfaces

7.3. Entity Parents

7.4. Client Entity Reuse

7.5. User Data Object Interfaces and Parents

8. Entity Instantiation and Destruction

8.1. Entity Instantiation on the BaseApp

8.1.1. ServiceApps

8.2. Cell Entity Creation From BaseApp

8.2.1. Creation Near an Existing Cell Entity

8.2.2. Creation in a Numbered Space

8.2.3. Creation in a New Space

8.2.4. Creation in Default Space

8.3. Entity Destruction

8.4. Entity Instantiation From The CellApp

8.4.1. Instantiation With No Base Counterpart

8.4.2. Instantiation With Base Counterpart

8.5. Loading Entities From Chunk Files

9. The Database Layer

9.1. Persistent Properties

9.1.1. Non-Persistent Properties

9.1.2. Built-In Properties

9.1.3. Database Indexing

9.1.4. The Identifier Tag

9.2. Reading and Writing Entities

9.3. Mapping BigWorld Properties Into SQL

9.3.1. Entity Tables

9.3.2. The databaseID property

9.3.3. Simple Data Types

9.3.4. VECTOR Data Types

9.3.5. STRING, UNICODE_STRING, BLOB, and PYTHON Data Types

9.3.6. PATROL_PATH and UDO_REF Data Types

9.3.7. ARRAYs and TUPLEs

9.3.8. FIXED_DICTs

9.3.9. USER_TYPEs

9.4. Execute Arbitrary Commands on Database

9.4.1. Execute Commands on SQL Database

9.4.2. Execute Commands on XML Database

9.5. Secondary Databases

9.5.1. Data Consolidation

9.5.2. Database Snapshot

10. Character Sets and Encodings

10.1. Python and Entity Properties

10.1.1. STRING

10.1.2. UNICODE_STRING

10.2. DBMgr and Encodings

10.2.1. UNICODE_STRING storage

10.2.2. Sorting search results

11. Profiling

11.1. Profiling Entities

11.1.1. Persistent Properties

11.1.2. Property Data Types

11.1.3. Property Data Propagation

11.2. Python Game Script

11.2.1. Understanding the output

11.2.2. Increasing Memory Usage / Entity Count

11.3. Profiling Server Processes (C++ Code)

11.3.1. Common Code Block Profiles

11.3.2. BaseApp Code Block Profiles

11.3.3. CellApp Code Block Profiles

11.4. Client Communication

11.4.1. Private Client Events

11.4.2. Public Client Events

11.4.3. Total Public Client Events

11.5. Server Communication

11.5.1. BaseApp Interface Summary

11.5.2. CellApp Interface Summary

12. Proxies and Players

12.1. Proxies

12.2. Witnesses

12.3. Entity Control

12.4. Physics Correction

12.4.1. Avoiding Y-axis rubber-banding.

13. Entities and the Universe

13.1. Multiple Spaces

13.1.1. Spaces Pool

13.2. Navigation System

13.2.1. Key Features

13.2.2. Navpoly Data Format

13.2.3. Script Interface

13.2.4. Navigate

13.2.5. Graph Searches

13.2.6. Auto-Generation of Navpoly Regions

13.3. Time

13.3.1. Real Time

13.3.2. Server Time

13.3.3. Game Time

13.4. Initialisation: Personality script, eload, and runscript

13.5. Global Data

13.5.1. globalData, baseAppData and cellAppData

13.6. Space Data

13.7. Global Bases

14. XML Data File Access

14.1. ResMgr.DataSection

14.2. Accessing Data

14.2.1. Opening a Section Within an XML File

14.3. Data Types

14.4. Writing Data

14.5. Performance Issues

14.6. API Reference

15. External Services

15.1. Non-blocking Methods

15.2. Background Threads

15.2.1. Caveats

16. Fault Tolerance

16.1. CellApp Fault Tolerance

16.1.1. Overview

16.1.2. Restoration process

16.1.3. Example

16.2. BaseApp Fault Tolerance

17. Disaster Recovery

18. Controlled Startup and Shutdown

18.1. Controlled Shutdown

18.2. Controlled Startup

19. Transactions and Handling Fault Tolerance and Disaster Recovery

19.1. Transaction logic

19.2. Fault Tolerance Behaviour

19.2.1. CellApp Fault Tolerance

19.2.2. BaseApp Fault Tolerance

19.3. Disaster Recovery Behaviour

20. Implementing Common Systems

20.1. General Scalability

20.2. Internal inter-component communication

20.3. Player AoI Updates

20.4. BigWorld Database Scalability

20.5. Player Look-up

20.5.1. Requirements

20.5.2. Design

20.6. Friends lists

20.6.1. Requirements

20.6.2. Design

20.7. Chat

20.7.1. P2P

20.7.2. AoI-based broadcast chat

20.7.3. Non-AoI-based broadcast chat

20.8. Mail

20.8.1. Requirements

20.8.2. Design

20.9. Inventory System

20.9.1. Requirements

20.9.2. Design

20.10. AoI-based Trading

20.10.1. Requirements

20.10.2. Design

21. User Authentication and Billing System Integration

21.1. Authentication by DBMgr

21.1.1. Default Authentication via MySQL

21.1.2. Default Authentication via XML

21.1.3. Custom Authentication and Billing System Integration

21.1.4. Accepting All Users

21.2. Authentication via a Base entity

22. Security

22.1. Client/Server Communications

22.2. Server-Side Network

22.3. Client Side

22.4. Client Cheating

22.4.1. General Rules for Managing Entity Data

22.4.2. Writing Secure Game Script

22.4.3. Balancing Security vs. Latency

22.4.4. Balancing Security vs. Server CPU Cost

23. Debugging

23.1. General Debugging

23.1.1. Information and Error Messages

23.1.2. Testing Scripts Using the Python Server

23.2. Performance Profiling

23.3. Common Mistakes

23.3.1. Definition Files Inconsistent Between the Server and Client

23.3.2. Implementation (.py) Does Not Match Definition (.def)

23.3.3. Accessing Other Entities' Properties and Methods Not Declared in the Definition File

23.3.4. Trying to Update the Properties of a Ghost Entity

23.3.5. Database backup and fault tolerance doesn't work for entities lacking a Base part

23.4. Fixed Cell Boundaries

23.5. Message Reliability And Ordering

24. Shared Development Environments

24.1. Windows and Linux cross platform development

24.1.1. Sharing resources from Windows

24.1.2. Accessing Windows share from Linux

24.2. Using BigWorld with a Version Control System

24.2.1. Customers using the Commercial Edition

24.2.2. Customers using the Indie Edition

24.2.3. Files to exclude from version control

24.3. DBMgr database conflicts

II. Server C++ Programming Guide

25. Overview

25.1. Compilation

25.1.1. Output Directories

26. Extending BigWorld Server

27. Entity Extras and Controllers

27.1. Implementing Entity Extras

27.2. Implementing Controllers

27.2.1. Configuring Portal's Permissivity

27.3. Integrating Entity Extras and Controllers

27.3.1. Restricting the Number of Controllers Per Entity

28. Updatable Objects

29. Encrypting Client-Server Traffic

29.1. Generating your own RSA keypair

29.2. Working with multiple keys

29.3. Customising the symmetric encryption algorithm

29.4. How PacketFilters work

29.4.1. High-level requirements

29.4.2. Filtering mechanics and requirements

29.4.3. Extra space for filtering

30. Mercury Packet Structure

30.1. Header

30.2. Messages

30.2.1. Fixed-Length Messages

30.2.2. Variable-Length Messages

30.3. Footers

30.3.1. Fragment Numbers

30.3.2. Sequence Number

30.3.3. ACKs

30.3.4. Indexed Channel ID

30.3.5. First Request Offset and replyID

31. The Watcher Interface

31.1. Callable Function Watchers

31.1.1. Forwarding Watchers

31.1.2. Implementing Function Watchers

32. Debug Message Macros

32.1. Centralised Logging

32.2. Filtering by Priority

32.3. Message Priority

33. Non-Blocking Socket I/O Using Mercury

33.1. Getting Callbacks From Mercury::EventDispatcher

34. MySQL Database Schema

34.1. Entity Tables

34.2. Non-Entity Tables

III. Extending WebConsole

35. Web Console

35.1. Adding a Page to a Module

35.1.1. Create a Template KID File

35.1.2. Edit controllers.py

35.2. Adding a Module

35.3. Add an Action Item to ClusterControl

35.3.1. Adding a Menu Item for an Existing Component Type

35.3.2. Adding a Menu Item for a New Component Type