| 28 | | {{{ |
| 29 | | data |
| 30 | | config |
| 31 | | Contains the system.cfg, this is used to setup the engine |
| 32 | | Contains Hot key set up. Ect. |
| 33 | | mods |
| 34 | | This is where the game/s lies containing all the game data. |
| 35 | | The main game lies in the "official" directory |
| 36 | | Each directory or zip will contain a different game |
| 37 | | profiles |
| 38 | | Each profile contains that particular player's saved games, config settings, |
| 39 | | and user statistics. |
| 40 | | screenshots |
| 41 | | Screenshots taken by the player, grouped by game type. |
| 42 | | tools |
| 43 | | Data for external tools |
| 44 | | logs |
| 45 | | Error reports generated by Prometheus. |
| 46 | | system |
| 47 | | Binaries (the main game engine, Scenario Editor, and other tools such as xmbcleanup) |
| 48 | | and relevant DLLs |
| 49 | | }}} |
| | 21 | === data === |
| | 22 | This directory contains data distributed to all users of the game. However, some data saved during games is stored in a separate location, depending on the user's OS: |
| | 23 | * Windows: local user data is stored in `%appdata%/0ad/` |
| | 24 | * Linux/OS X: local user data is stored in `~\.local\shared\0ad\` or `~\.config\0ad\` |
| | 25 | |
| | 26 | A typical user data directory is arranged like this: |
| | 27 | * `cache`: Game data cached for more efficient access. |
| | 28 | * `config` (see below) |
| | 29 | * `data` |
| | 30 | * `screenshots`: PNG and BMP screenshots from the game. |
| | 31 | * `logs`: Logs files and crash dumps. |
| | 32 | * `sim_log`: Includes data for precisely replaying a simulation. |
| | 33 | |
| | 34 | Screenshots, logs, config files, and crash dumps generally end up in these directories. |
| | 35 | |
| | 36 | ==== config ==== |
| | 37 | Contains the default configuration file `default.cfg`, a simple text file containing pairs of `key = value` entries. To make changes to the configuration, the user should create or modify `local.cfg` or `user.cfg` files in their user data directory (see above). Also contains a list of hot key definitions which can be used in the config files. |
| | 38 | |
| | 39 | ==== mods ==== |
| | 40 | This contains the game data and is of primary interest to the game's artists, developers and the modding community. The official mod is in the `public` directory. For official releases, the mod is compressed into a ZIP file. Mods can be selectively loaded by users, for a different game experience. |
| | 41 | |
| | 42 | TODO - LINK TO MOD STRUCTURE |
| | 43 | |
| | 44 | ==== tests ==== |
| | 45 | TODO |
| | 46 | |
| | 47 | ==== tools ==== |
| | 48 | Some data associated with tools separate from the engine itself, like Atlas and font builder. |
| | 49 | |
| | 50 | |
| | 51 | === system === |
| | 52 | Binares and required libraries for the game are found here. For Windows users, the game's executables (EXEs) and libraries (DLLs) can be found here along with the game's tools. Similarly for developers building the game themselves, the binaries will end up here. |
| | 53 | |
| 53 | | {{{ |
| 54 | | premake |
| 55 | | This useful little tool generates the Make files for different formats (i.e VisualStudio, Linux and Mac OS/X) this |
| 56 | | is usefull to us to create different workspaces for different compilers for when new files are |
| 57 | | added. Note: this defines all compile settings; they are automatically translated to each IDE's format. More info : http://premake.sourceforge.net/ |
| 58 | | workspaces |
| 59 | | This is where the workspaces are generated. Run ''update workspaces'' batch. |
| 60 | | Relevant directories for editors then appear. |
| 61 | | xmbcleanup |
| 62 | | XMBCleanup is a utility that gets rid of extra XMBs so only the latest one for each XML exists |
| 63 | | (it needs to create a new one each time the file is modified to ensure it's new). |
| 64 | | bin |
| 65 | | contains pearl dll to run pearl scripts |
| 66 | | errorlist |
| 67 | | A tool for regenerating the error.h file (list of error codes and exception types) |
| 68 | | linefix |
| 69 | | 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, |
| 70 | | since the entire file is considered modified) |
| 71 | | }}} |
| | 57 | === autobuild2 === |
| | 58 | TODO |
| | 59 | |
| | 60 | === bin === |
| | 61 | Some utilities for the build process. |
| | 62 | |
| | 63 | === coverage === |
| | 64 | TODO |
| | 65 | |
| | 66 | === dehydra === |
| | 67 | Some analysis scripts for Dehydra, a tool for custom static analysis of C++ code. |
| | 68 | |
| | 69 | === errorlist === |
| | 70 | A tool for generating the error and exception codes used in the game. |
| | 71 | |
| | 72 | === premake === |
| | 73 | Building the game is eased by an automated tool called [http://industriousone.com/premake Premake], which creates platform-specific workspaces for developers. Premake uses scripts written in [http://www.lua.org/ Lua]. Windows, Linux, and OS X are the supported environments, as are a few major IDEs (namely Visual C++ and Xcode). |
| | 74 | |
| | 75 | === resources === |
| | 76 | Icons and data files for the game's installer. |
| | 77 | |
| | 78 | === svn_revision === |
| | 79 | Utility for outputting the current game build's revision number. |
| | 80 | |
| | 81 | === workspaces === |
| | 82 | Build workspaces and the scripts for generating them are found here. Windows users should run `update-workspaces.bat` while Linux/OS X users should run `update-workspaces.sh`. |
| | 83 | |
| 75 | | {{{ |
| 76 | | Devil |
| 77 | | Graphics format Reader |
| 78 | | Developer's Image Library (DevIL) is a programmer's library to develop applications with very |
| 79 | | powerful image loading capabilities, yet is easy for a developer to learn and use. Ultimate |
| 80 | | control of images is left to the developer, so unnecessary conversions, etc. are not performed. |
| 81 | | DevIL utilises a simple, yet powerful, syntax. DevIL can load, save, convert, manipulate, filter |
| 82 | | and display a wide variety of image formats. |
| 83 | | More info : http://openil.sourceforge.net/ |
| 84 | | |
| 85 | | SpiderMonkey |
| 86 | | Mozilla's Javascript engine. |
| 87 | | SpiderMonkey is the code-name for the Mozilla's C implementation of JavaScript. |
| 88 | | This is used for scripting though out the game. |
| 89 | | More info : http://www.mozilla.org/js/spidermonkey/ |
| 90 | | }}} |
| 91 | | {{{ |
| 92 | | OpenAL |
| 93 | | Platform independent audio driver, equivalent to OpenGL in audio terms. |
| 94 | | OpenAL is a cross-platform 3D audio API appropriate for use with gaming applications and many |
| 95 | | other types of audio applications |
| 96 | | More info : http://www.openal.org/ |
| 97 | | }}} |
| 98 | | {{{ |
| 99 | | Vorbis |
| 100 | | Audio Driver plays .ogg files which is a free alternative version of MP3s |
| 101 | | Ogg Vorbis is a completely open, patent-free, professional audio encoding and streaming |
| 102 | | technology with all the benefits of Open Source |
| 103 | | More info : http://www.vorbis.com/ |
| 104 | | }}} |
| 105 | | {{{ |
| 106 | | Boost |
| 107 | | The Boost web site provides free peer-reviewed portable C++ source libraries. The emphasis is on |
| 108 | | libraries which work well with the C++ Standard Library |
| 109 | | More info : http://www.boost.org/ |
| 110 | | }}} |
| 111 | | {{{ |
| 112 | | Xerces |
| 113 | | XML Reader (eXtensible Markup Language) simple text format for storing information |
| 114 | | Xerces (named after the Xerces Blue butterfly) provides world-class XML parsing and generation. |
| 115 | | Fully-validating parsers are available for both Java and C++, implementing the W3C XML and DOM |
| 116 | | (Level 1 and 2) standards, as well as the de facto SAX (version 2) standard. The parsers are |
| 117 | | highly modular and configurable. Initial support for XML Schema (draft W3C standard) is also |
| 118 | | provided. |
| 119 | | More info : http://xml.apache.org/ |
| 120 | | }}} |
| 121 | | {{{ |
| 122 | | OpenGL |
| 123 | | OpenGL is an API for 2D and 3D graphics applications. OpenGL fosters innovation and speeds |
| 124 | | application development by incorporating a broad set of rendering, texture mapping, special |
| 125 | | effects, and other powerful visualization functions. Developers can leverage the power of OpenGL |
| 126 | | across all popular desktop and workstation platforms, ensuring wide application deployment. |
| 127 | | More info : http://www.opengl.org/ |
| 128 | | }}} |
| 129 | | {{{ |
| 130 | | SDL |
| 131 | | Simple DirectMedia Layer is a cross-platform multimedia library designed to provide low level |
| 132 | | access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL, and 2D video framebuffer. |
| 133 | | More info : http://www.libsdl.org/ |
| 134 | | }}} |
| 135 | | ''Other Libs'' [description minimal because they are mostly self-explanatory] |
| 136 | | |
| 137 | | * libjpg: Jpeg Reader |
| 138 | | * libpng: Png Reader (portable nework graphics) graphic format |
| 139 | | * Zlib: Zip archive Reader. |
| 140 | | * Dbghelp: Microsoft's debug support functions. |
| 141 | | * Misc: Contains the OGL extensions. |
| 142 | | * DirectX: minimal part of SDK needed to compile (used by wsdl) |
| | 87 | * '''boost''': Boost provides free peer-reviewed portable C++ source libraries. The emphasis is on libraries which work well with the C++ Standard Library. http://www.boost.org/ |
| | 88 | * '''cryptopp''': Crypto++ Library is a free C++ class library of cryptographic schemes. http://www.cryptopp.com/ |
| | 89 | * '''cxxtest''': !CxxTest is a JUnit/CppUnit/xUnit-like framework for C/C++. It is focussed on being a lightweight framework that is well suited for integration into embedded systems development projects. http://cxxtest.tigris.org/ |
| | 90 | * '''enet''': ENet's purpose is to provide a relatively thin, simple and robust network communication layer on top of UDP (User Datagram Protocol). The primary feature it provides is optional reliable, in-order delivery of packets. http://enet.bespin.org/ |
| | 91 | * '''fcollada''': FCollada is a C++ library which offers support for COLLADA interoperability. http://collada.org/mediawiki/index.php/FCollada |
| | 92 | * '''libcurl''': curl is a command line tool for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, TELNET and TFTP. curl supports SSL certificates, HTTP POST, HTTP PUT, FTP uploading, HTTP form based upload, proxies, cookies, user+password authentication (Basic, Digest, NTLM, Negotiate, kerberos...), file transfer resume, proxy tunneling and a busload of other useful tricks. http://curl.haxx.se/ |
| | 93 | * '''libjpg''': libjpeg is a library written entirely in C which contains a widely-used implementation of a JPEG decoder, JPEG encoder and other JPEG utilities. This library is maintained by the Independent JPEG Group. http://www.ijg.org/ |
| | 94 | * '''libpng''': libpng is the official PNG (portable network graphics) reference library. It supports almost all PNG features, is extensible, and has been extensively tested for over 15 years. http://www.libpng.org/ |
| | 95 | * '''libxml2''': Libxml2 is the XML C parser and toolkit developed for the Gnome project (but usable outside of the Gnome platform), it is free software available under the MIT License. XML itself is a metalanguage to design markup languages, i.e. text language where semantic and structure are added to the content using extra "markup" information enclosed between angle brackets. http://xmlsoft.org/ |
| | 96 | * '''nvtt''': The NVIDIA Texture Tools is a collection of image processing and texture manipulation tools, designed to be integrated in game tools and asset conditioning pipelines. The primary features of the library are mipmap and normal map generation, format conversion and DXT compression. http://code.google.com/p/nvidia-texture-tools/ |
| | 97 | * '''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. http://www.openal.org/ |
| | 98 | * '''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. http://www.opengl.org/ |
| | 99 | * '''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. http://www.libsdl.org/ |
| | 100 | * '''spidermonkey''': Mozilla's JavaScript engine written in C/C++. JavaScript is the game's scripting language of choice (game logic, AIs, random maps, etc). http://www.mozilla.org/js/spidermonkey/ |
| | 101 | * '''valgrind''': Valgrind is an instrumentation framework for building dynamic analysis tools. There are Valgrind tools that can automatically detect many memory management and threading bugs, and profile your programs in detail http://valgrind.org/ |
| | 102 | * '''vorbis''': Ogg Vorbis is a completely open, patent-free, professional audio encoding and streaming technology with all the benefits of Open Source. http://www.vorbis.com/ |
| | 103 | * '''wxwidgets''': (This directory is empty, as wxWidgets is not included in the SVN. It is only needed for developers who plan to build Atlas, according to the [wiki:BuildInstructions Build Instructions]) wxWidgets is a class library that allows you to compile graphical C++ programs on a range of different platforms. wxWidgets defines a common API across platforms, but uses the native graphical user interface (GUI) on each platform, so your program will take on the native 'look and feel' that users are familiar with. http://www.wxwidgets.org/ |
| | 104 | * '''zlib''': zlib is designed to be a free, general-purpose, legally unencumbered -- that is, not covered by any patents -- lossless data-compression library for use on virtually any computer hardware and operating system. http://zlib.net/ |
| 223 | | === CParticleManager: === |
| 224 | | Manager class for all the particle systems. |
| 225 | | |
| 226 | | === CTexture: === |
| 227 | | A texture as represented in OpenGL. Width and height are powers of 2. |
| 228 | | |
| 229 | | === CCamera: === |
| 230 | | Simple class to encapsulate camera. |
| 231 | | |
| 232 | | === CImageLoader: === |
| 233 | | Loads various formats (PNG, JPG, BMP, TGA, etc). |
| 234 | | |
| 235 | | === CLight: === |
| 236 | | Directional lights, just specify a color and direction. |
| 237 | | |
| 238 | | === CMaterial: === |
| 239 | | Set material properties for meshes. |
| 240 | | |
| 241 | | === CSelection: === |
| 242 | | Get the index of the object which is selected when the user clicks on a point on the screen. |
| 243 | | |
| 244 | | === CFont: === |
| 245 | | Holds the description of a font, and used by renderer for outputting text. |
| 246 | | |
| 247 | | = Useful Features for Testing = |
| 248 | | == Starting the Game in a Window == |
| 249 | | 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. |
| 250 | | |
| 251 | | == Using the Console == |
| 252 | | Press the ~ key (top left key for non US) 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. |
| 253 | | |
| 254 | | == Logging and Debugging Functions == |
| 255 | | 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. |
| 256 | | |
| 257 | | 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. |
| 258 | | |
| 259 | | '''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. |
| | 178 | TODO - DESCRIBE THE OTHERS |
