Getting the source

All the files used in Pyrogenesis and game data are all stored via version control. For anyone not familiar with version control, it's a system that keeps us all up to date and allows us to work together (even work on the same file) by keeping track of multiple versions of a shared file.

It keeps track of all changes and provides a more powerful alternative to keeping backup files by storing every version put back in. This allows us to undo any mistakes. To use source control we need to download a client such as:

TortoiseSVN ... the easy-to-use Windows-Explorer-integrated frontend to our Subversion repository. This can be downloaded from here ​http://tortoisesvn.tigris.org/

For information about how to acquire, configure, and use TortoiseSVN, check out the TortoiseSVN Guide.

Notes for Visual Studio 2005 users

Users of ​VC++ 2005 Express Edition (not the more recent 2008 and 2010 versions) will need to download and install the ​Platform SDK, and add its include and lib directories to the appropriate lists (as per ​step 3 here).

Finding your way around

There are 4 main directories in the repository:

• Source : The source code for the main game and tools, as you would expect.
• Build : Tools and workspaces required to build the source.
• Binaries : This contains a working game exe, DLLs and Tools.
• Libraries : These are the libraries used in the product.

All these are covered in more depth below.

binaries

This is where everything that will eventually be released to the end user ends up. This is the only part that an artist or designer needs. It contains all the tools, data and of course the main game exe. This is where the any executables are compiled to.

The main game can be run from pyrogenesis.exe and the scenario editor from Atlas.bat (which invokes pyrogenesis.exe -editor). These both can be found in the Binaries\System\ directory. So to play the latest build it should be possible to just click on the ps.exe file.

  data
    config
  	Contains the system.cfg, this is used to setup the engine
  	Contains Hot key set up. Ect.
    mods
  	This is where the game/s lies containing all the game data.
  	The main game lies in the "official" directory
  	Each directory or zip will contain a different game
    profiles
  	Each profile contains that particular player's saved games, config settings,
        and user statistics.
    screenshots
        Screenshots taken by the player, grouped by game type.
    tools
	Data for external tools
    logs
        Error reports generated by Prometheus.
    system
        Binaries (the main game engine, Scenario Editor, and other tools such as xmbcleanup)
        and relevant DLLs

build

This is where the workspaces are generated so we can start work. This is done by going into the workspace directory and running the update-workspaces.bat file. This then creates all Visual Studio workspaces for VC2005 and VC2008. So depending on which editor your using enter the relevant directory and a workspace will have been created for your editor.

  premake		
    This useful little tool generates the Make files for different formats (i.e VisualStudio, Linux and Mac OS/X) this
    is usefull to us to create different workspaces for different compilers for when new files are 
    added. Note: this defines all compile settings; they are automatically translated to each IDE's format. More info : http://premake.sourceforge.net/
  workspaces
    This is where the workspaces are generated. Run ''update workspaces'' batch.
    Relevant directories for editors then appear.
  xmbcleanup
    XMBCleanup is a utility that gets rid of extra XMBs so only the latest one for each XML exists 
   (it needs to create a new one each time the file is modified to ensure it's new).
  bin
    contains pearl dll to run pearl scripts
  errorlist	
    A tool for regenerating the error.h file (list of error codes and exception types)
  linefix
    fixes line breaks in files (from unix/windows to whatever you're running). Avoid if possible (it reduces the usability of the SVN change information, 
    since the entire file is considered modified)

libraries

These are the third-party libraries currently stored in the repository; they are not necessarily used in the final game. Here are some descriptions of the libraries and where it can be downloaded from.

  Devil	
    Graphics format Reader
    Developer's Image Library (DevIL) is a programmer's library to develop applications with very 
    powerful image loading capabilities, yet is easy for a developer to learn and use. Ultimate 
    control of images is left to the developer, so unnecessary conversions, etc. are not performed. 
    DevIL utilises a simple, yet powerful, syntax. DevIL can load, save, convert, manipulate, filter 
    and display a wide variety of image formats.
    More info : http://openil.sourceforge.net/
	
  SpiderMonkey
    Mozilla's Javascript engine.
    SpiderMonkey is the code-name for the Mozilla's C implementation of JavaScript.
    This is used for scripting though out the game.
    More info : http://www.mozilla.org/js/spidermonkey/

  OpenAL	
    Platform independent audio driver, equivalent to OpenGL in audio terms.
    OpenAL is a cross-platform 3D audio API appropriate for use with gaming applications and many 
    other types of audio applications
    More info : http://www.openal.org/

  Vorbis	
    Audio Driver plays .ogg files which is a free alternative version of MP3s
    Ogg Vorbis is a completely open, patent-free, professional audio encoding and streaming 
    technology with all the benefits of Open Source
    More info :  http://www.vorbis.com/

  Boost
    The Boost web site provides free peer-reviewed portable C++ source libraries. The emphasis is on 
    libraries which work well with the C++ Standard Library
    More info :  http://www.boost.org/

  Xerces
    XML Reader (eXtensible Markup Language) simple text format  for storing information
    Xerces (named after the Xerces Blue butterfly) provides world-class XML parsing and generation. 
    Fully-validating parsers are available for both Java and C++, implementing the W3C XML and DOM 
    (Level 1 and 2) standards, as well as the de facto SAX (version 2) standard. The parsers are 
    highly modular and configurable. Initial support for XML Schema (draft W3C standard) is also 
    provided. 
    More info : http://xml.apache.org/

  OpenGL
    OpenGL is an API for 2D and 3D graphics applications. OpenGL fosters innovation and speeds 
    application development by incorporating a broad set of rendering, texture mapping, special 
    effects, and other powerful visualization functions. Developers can leverage the power of OpenGL 
    across all popular desktop and workstation platforms, ensuring wide application deployment.
    More info : http://www.opengl.org/

  SDL
    Simple DirectMedia Layer is a cross-platform multimedia library designed to provide low level 
    access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL, and 2D video framebuffer.
    More info : http://www.libsdl.org/ 

Other Libs [description minimal because they are mostly self-explanatory]

• libjpg: Jpeg Reader
• libpng: Png Reader (portable nework graphics) graphic format
• Zlib: Zip archive Reader.
• Dbghelp: Microsoft's debug support functions.
• Misc: Contains the OGL extensions.
• DirectX: minimal part of SDK needed to compile (used by wsdl)

source

The source can be broken down into the following sub directories

• Atlas: Game development tool (map editor, scenario editor, entities, etc.)
• Collada: Libraries for converting Collada digital assets to 0AD formats
• Engine: Math code, OpenAL sound stuff and other support code like profilers and hardware support.
• Graphics: Engine 3D Graphics (Cameras, Meshes, Particles, Shaders, etc.)
• Gui: Graphic user Interface (2D stuff for creating dialog boxes, text, buttons and other similar stuff)
• Lowlevel: Low level code that gives the engine some common functionality in different OS's
• Network: Code that manages network connectiviity between peers for multi-user games.
• Pyrogenesis: "Main" for the game. The game executable is called pyrogenesis.exe
• Scriptinginterface: Scripting Engine
• Simulation2: Game Simulation main work (Pathing, Motion, Command processing, Player Management, etc.)

Tools

These are separate stand alone tools not part of the main code. These are used to build the project files into something useable by the engine, these can be then placed in the binaries\mods directory

• Ape: Tool for Building particle systems
• Arch Builder: Builds Archived Project
• Auto Builder: Build Project
• Font Builder: Builds Font Texture
• I18n: Language Importing.
• pmdexp: Export Meshes to PMD format
• ScEd: Scenario Editor
• textureconv: Texture Conversion to DDS format

Main Classes

CWorld

• Owns the map and all entities

• Sends the visible map terrain and entities to the renderer

CMap

• Owns the terrain and the tile attributes

• Loads the map from a scenario file

• Stores the map into a scenario file

CSimulation

Each frame, CSimulation goes through CWorld and updates the state of all world objects according to the elapsed time. CSimulation will know which clients in an MP game are entitled to which information, so that a "map-hacked" client will see as little as possible and to ensure minimal bandwidth usage

CPlayer

Represents a player. Either human or computer, local or networked.

• Containing player-specific information such as name, score, color etc.

• Validating command messages on the server.

• Knowing the entities owned by the player

CGame

The CGame is the representation of the game itself. It is the container that holds the rules, resources and attributes of the game.

CSessionManager

The central nexus of network message handling. Contains the entry point called from the main thread. CMessageSocket's are registered with a corresponding message handler function which is used to handle the incoming messages. Messages are passed through CSessionManager from the socket code via the relevant message handler to CSimulation where they are queued to be simulated.

Graphics

CRender:

This is the class that maintains lists of objects to be rendered, and handles all the OGL calls to display them, etc.

IRenderableObject:

Base class for renderable objects.

CTerrain:

Terrain heightmap and rendering functions.

CModel:

Animated model, made out of multiple meshes and joints.

CMesh:

Mesh class to hold geometry, normals and textures.

CParticleSystem:

A single particle system.

CSprite:

Sprites can be any size, and may be composed of multiple textures.

CParticleManager:

Manager class for all the particle systems.

CTexture:

A texture as represented in OpenGL. Width and height are powers of 2.

CCamera:

Simple class to encapsulate camera.

CImageLoader:

Loads various formats (PNG, JPG, BMP, TGA, etc).

CLight:

Directional lights, just specify a color and direction.

CMaterial:

Set material properties for meshes.

CSelection:

Get the index of the object which is selected when the user clicks on a point on the screen.

CFont:

Holds the description of a font, and used by renderer for outputting text.

Useful Features for Testing

Starting the Game in a Window

Edit the binaries/config/system.cfg file and modify the "windowed" property to true. You can also modify "xres" and "yres" to change the window size.

Using the Console

Press the ~ key (top left key ( for UK)) to toggle the console. This allows you to view various debug output that has been written by scripts using console.write or from C++ using Console->!InsertMessage. It also lets you enter !JavaScript expressions to be evaluated. To do this, start a like with ":" to run an expression, or "?" to run it and print the output. For example, :new Entity("hele_infantry_spearman_b", new Vector3D(0,0,0)) will create a Hoplite at the left corner of the map, and ?1+1 will write 2. One useful variable is selection, the array of currently selected units. For example, type :selection[0].actions.attack.melee.damage *= 2 to double the selected unit's attack. One useful function is startPlacing(type)`, which will create a cursor for placing a unit of the given type. You can find most of the available functions in ScriptGlue.cpp. You are also free to use variables, loops, etc in the console.

Logging and Debugging Functions

debug_printf is a handy method for writing text to the IDE's output window from code. Its syntax is identical to printf. Note that it can be rather slow and may thus affect the timing of a routine being debugged.

MICROLOG is sometimes used to make a note of what the game is about to do next. This information is stored in a circular buffer and would be displayed when a crash is detected. This is helpful in case the (additionally generated) stack trace is incorrect; we at least have some idea of how far the game got. Since the stack trace now works fairly well and bugs during initialization are rare, this is no longer needed as much.

Tip: To log information from a function called very frequently, like a rendering function, while not flooding the console or logs, one trick is to simply put an if(rand()<RAND_MAX/10) before the print statement so that it will only print 10% of the time.