Changes between Version 14 and Version 15 of EngineDocumentation


Ignore:
Timestamp:
Jan 13, 2016, 10:53:44 PM (8 years ago)
Author:
leper
Comment:

Remove obsolete documentation.

Legend:

Unmodified
Added
Removed
Modified
  • EngineDocumentation

    v14 v15  
    1 = Pyrogenesis Engine Overview =
    2 
    3 == Introduction ==
    4 
    5 Pyrogenesis is the game engine for 0 A.D. Its design goals include cross-platform compatibility (Windows, Linux and Mac OS X), efficiency (including hardware-accelerated 3D graphics), and extensibility through game mods and scripts. The core engine is written in C++. However, much of the high level game logic and user interface is implemented by scripts, which are written in !JavaScript. This document focuses on the C++ engine (present in the source folder in SVN). We first describe the "life cycle" of a game and how the different engine modules interact. We then provide an overview of each module in the engine.
    6 
    7 == Life of a Game Session ==
    8 
    9 When you launch 0 A.D, the game first loads from a combination of plain files in binaries/data as well as a ''zip archive'' containing commonly used files. The Virtual File System (VFS) module (implemented in lib/file) makes both files in the archive and regular files look like the same kind of File object to the game. Once the game is loaded, it displays a main menu GUI. The GUI engine is implemented by the gui module. It supports defining a GUI page layout in XML and then responding to events using !JavaScript. These files are present in binaries/data/mods/official/gui/test. They interact with the game using the script functions exposed by the various C++ modules, which are generally in scripting/ScriptGlue.cpp. From the main menu, players may either start a single player game, host a multiplayer game, or join a multiplayer game.
    10 
    11 The game logic code works the same way whether the game is multiplayer or single player - all that differs is how commands are treated. We'll first describe how the game logic code is organized before explaining the details of setting up multiplayer. The game logic is implemented in the simulation module, most notably in CSimulation, which handles all updates, and CEntity, which represents and updates an in-game object (unit, building, etc). In both multiplayer and single player, the game state is updated in ''turns'', which are about 150 milliseconds each. Each turn, objects move to some new position, units may gather resources or do damage (depending on their gather rates), etc. A turn is handled in the CSimulation::Update method. In addition, between turns, the graphical objects in the game are animated continuously as fast as the frame rate permits by interpolating between their previous turn's position and their next turn's position. This is done by CSimulation::Interpolate. There is a CTurnManager object which says when it is time for a new turn (the simulation queries this object each frame). While the game is running, commands from the player (obtained through the GUI) are queued up using CTurnManager::!QueueLocalCommand. Each turn, the turn manager provides a ''batch'' of commands to the simulation based on what was queued up. The only difference between single player and multiplayer is which turn manager is used: The multiplayer turn manager sends commands to the host, which buffers a batch of orders and then broadcasts them to all players, thus making sure that all clients get the same batches of commands, keeping their simulations in lockstep. The single player turn manager sends commands directly to the simulation. All commands are validated before being played, to prevent cheating. When AI is implemented, it will be done by simply sending orders from the AI player to the order queue as if a human player had issued them.
    12 
    13 In summary, a game runs like this:
    14  * Initialize
    15  * Loop forever
    16    * Check the current time
    17    * If turn manager says it is time for a new turn, call CSimulation::Update
    18    * Else call CSimulation::Interpolate
    19    * Handle inputs (queue up orders)
    20    * Render a new frame
    21 
    22 Most of the game logic happens in CEntity and its related scripts (binaries/data/mods/official/entity_functions.js) and helper classes (like CEntityManager). All objects that a player may interact with in the game are ''entities'' - including units, buildings, trees, any obstacle that has an effect on pathfinding, etc. Each entity is represented in the game world by an ''actor'' - a graphical mesh with potentially some other meshes attached to it at ''prop points'' (things like shields, weapons, or the rider on a horse). There are also purely decorative objects that are not entities, such as grass blades or shrubs. These are implemented by having an actor with no entity. Actor drawing and animation is handled in the graphics package, including loading meshes and animations from 0 A.D.'s custom compressed formats, PMD (Pyrogenesis !MoDel) and PSA (PyrogenesiS Animation).
    23 
    24 Each entity has a hierarchical tree of ''properties'' as well as a number of ''event handlers'' implemented in !JavaScript. Entity types (such as different soldier types) are defined as XML "template" files in binaries/data/mods/official/entities. These XML templates can inherit from each other, so that, for example, all spearmen can inherit some properties from template_infantry_spearman.xml, but Celtic and Persian spearmen can be differentiated by modifying celt_infantry_spearman.xml and pers_infantry_spearman.xml. A property such as maximum health might be implemented in an XML file as <traits><health><max>100</max></health></traits> and will then be accessible through scripts and C++ code as traits.health.max. The XML files also define script functions that can handle various ''events'' for an entity. For example, an entity may choose to react when it's damaged by attacking the entity that damaged it. Most orders which require the entity to do some work are implemented as events. For example, if a unit has an attack with attack rate of 1 hit per 2 seconds, then as long as it is trying to attack a target, it will get a "handle generic order" event with action "attack" ever 2 seconds, and then a !JavaScript function will decide how much damage to inflict on the target and do so. The C++ code only does the "heavy-duty" work like pathfinding and collision detection, allowing most of the game logic to be handled in !JavaScript for a quick development cycle. One last thing to note about entities is that although they have many properties, only the properties that differ from those in the template, such as "current health", are maintained for each CEntity object. The rest are held by the template (CEntityTemplate). This means that it's possible to, for example, upgrade the attack of all current and future entities of some type by applying a change to their template. Entity properties and event handlers are described in detail at [wiki:XML.Entity XML.Entity]. Scripting helper functions are implemented in the scripting module - Most notably, the CJSObject class, which makes it possible to expose C++ instance variables and methods in an object to !JavaScript fields and functions.
    25 
    26 The graphics in 0 A.D. are handled by two packages - graphics, which manages graphical objects like meshes, animations and textures, and renderer, which figures out what items to draw and also manages global effects such as shadows and water rendering. Sound is implemented in the sound module and provides basic support for playing music and playing short sounds on various events. The game view (including camera) is maintained in CGameView (graphics/GameView.cpp). Player input is handled in engine/Interact.cpp.
    27 
    28 One final thing to note about game life is how the map editor, Atlas, works. Atlas is launched by running pyrogenesis with the -editor option. It creates a window using the wxWidgets library, and then runs a special copy of the game within this window. This makes it possible to render objects in Atlas using the same code that renders them in the game, and to start testing the game at any time by pressing the Play Simulation button in Atlas. The Atlas GUI is also scriptable. It is implemented in binaries/data/tools/atlas/scripts. Atlas also supports ''hotloading'' GUI scripts, so it is possible to edit a script and immediately see its effect in a running Atlas window. The goal is to eventually support hotloading for the game GUI and possibly even game logic scripts in 0 A.D.
    29 
    30 
    31 = Code Organization =
    32 
    33 
    34 
    35 = Module Descriptions =
    36 
    37 == Low-Level ==
    38 
    39 == Simulation ==
    40 
    41 == Rendering ==
    42 
    43 == Scripting ==
    44 
    45 == Network ==
    46 
    47 == Input ==
    48 
    49 == Sound ==
    50 
    51 == Atlas (Map Editor) ==
    52 
    53 == Standalone Tools ==
    54 
    55 
    56 = Developing Pyrogenesis =
    57 
    58 == Build Process ==
    59 To build 0. a.d., one can follows the [http://trac.wildfiregames.com/wiki/BuildInstructions Build Instruction] page. In general, Pyrogenesis engine reads setting from binaries/data/config/default.cfg for configuring e.g. fragment shaders, vertex shaders, etc. Configuration can be tweaked by
    60 
    61  * create local.cfg (cp default.cfg local.cfg)
    62 
    63 And disable/ enable some features such as
    64 
    65  * fancywater=false (to avoid fragment shaders)
    66  * renderpath=fixed (to avoid vertex shaders)
    67  * shadows=false
    68  * novbo=true
    69 
    70 Reference: [http://www.wildfiregames.com/forum/index.php?showtopic=12982&hl= Driver problem]
    71 
    72 
    73 == Automated Tests ==
    74 
    75 == Useful Features for Testing ==
    76 
    77 
    78 = Outline for this document (from Gobby): =
    79 {{{
    80 engine overview
    81   life of a game session from start to finish (pyrogenesis startup, VFS, menu GUI,
    82     creation of game object, loading, gameplay, scripts, etc), mentioning the
    83     components involved in each part
    84   explanation of multiplayer sessions
    85   explanation of how Atlas fits in
    86 
    87 how to build the distribution
    88   supported compilers
    89  
    90   build system
    91     * only one copy of settings for Mac, Win, Unix (helps keep workspaces in sync)
    92     * what it means to update-workspaces
    93     * organization of the tree as static libraries
    94     * external libraries and how they are linked in
    95     * required libraries for Linux and OS X ("manual" installation of the game)
    96 
    97 finding your way around: brief description of all repository directories
    98   merge the below descriptions of svn/source and those already found in "finding your way"
    99 
    100 
    101 overview of svn/source directories:
    102   collada: routines for loading COLLADA 3d models
    103   dcdt: triangulation library used by the pathfinder
    104   graphics: manages objects drawn on the screen, like textures, animated models,
    105     terrain patches, etc
    106   gui: a homemade OpenGL in-game GUI based on XML files
    107   i18n: routines for internationalization (translating in-game text)
    108   lib: Jan's collection of mostly low-level routines.
    109     allocators: memory (sub)allocators
    110     posix: POSIX emulation when on Windows
    111       file: efficient file loading code.
    112         http://trac.wildfiregames.com/wiki/Virtual_File_System
    113         http://www.stud.uni-karlsruhe.de/~urkt/articles/study_thesis.pdf
    114     res: resource handling (textures and sounds)
    115     sysdep: bridges differences between systems and allows 'portable' code
    116     debug (asserts), error handling, timing bit bashing, etc. - all the dirty details.
    117   maths: math code (linear algebra, geometry)
    118   network: the network engine (based on Enet; serializes game messages)
    119   pch: pre-compiled headers (this directory is required by the build system)
    120   ps: pyrogenesis engine - basically, 'everything else'
    121     utility classes, console, profiler, XML loader
    122   renderer: rendering algorithms, including sorting, quality settings, shadows and water
    123   script: scripting engine (!JavaScript)
    124   simulation: most of the actual RTS game logic
    125     simulation turns, entities, techs, unit AI, pathfinding, ..
    126   sound: (WIP) high-level sound and music engine
    127     builds on an abstraction of OpenAL
    128   tools
    129     particle engine, archive builder, map editor, random map generator, PMD exporter
    130   overview of scripts in data/mods/official/scripts (entity functions & game startup)
    131  
    132 misc topics:
    133   self-test
    134     * purpose
    135     * mechanism in VC IDE
    136     * where they lie
    137  
    138   overview of art formats
    139  
    140   useful features for testing/development
    141     copy from the finding your way around - doc
    142 }}}
     1See http://svn.wildfiregames.com/docs or [[WikiStart#Forprogrammers: | WikiStart]].