User Tools
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
cppdev:gamecodeoverview [2011-09-22 22:17] Carsten Rearranged and revised text |
cppdev:gamecodeoverview [2017-05-08 11:15] (current) Carsten deleted obsolete section (it's superseded by the component system) |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== Game Code Overview ====== | + | ====== Game Development Overview ====== |
| + | |||
| + | /* Should we say something about the term "MOD" somewhere on this page? | ||
| + | Cafu separates the core engine (the technical framework that is the common basis for each game or app) from the program code and the resources for each game. | ||
| + | MODs: | ||
| + | like plug-ins / architecture | ||
| + | multiple at the same time | ||
| + | each mod can be game or application | ||
| + | not let this stop you from modifyin the core engine | ||
| + | */ | ||
| The Cafu Engine can be used both for developing single- or multiplayer games that ship as individual products, | The Cafu Engine can be used both for developing single- or multiplayer games that ship as individual products, | ||
| Line 13: | Line 22: | ||
| ===== One directory per game ===== | ===== One directory per game ===== | ||
| - | In order to achieve these goals, all files, data and program code for a game are stored in one common directory, which in turn must be a subdirectory of ''[[http://trac.cafu.de/browser/cafu/trunk/Games/|Games/]]''. | + | In order to achieve these goals, all files, data and program code for a game are stored in one common directory, which in turn must be a subdirectory of ''Games/''. |
| - | For an example, see the ''[[http://trac.cafu.de/browser/cafu/trunk/Games/DeathMatch|Games/DeathMatch/]]'' directory of the DeathMatch example game that ships with Cafu: | + | For an example, see the ''Games/DeathMatch/'' directory of the DeathMatch example game that ships with Cafu: |
| {{:cppdev:deathmatchdirectory.png}} | {{:cppdev:deathmatchdirectory.png}} | ||
| + | |||
| + | (Also see [[cppdev:startnewgame]] for help about creating a new game directory.) | ||
| Although you're largely free to organize the contents of the game directory as desired, | Although you're largely free to organize the contents of the game directory as desired, | ||
| Line 26: | Line 37: | ||
| - | ==== EntityClassDefs.lua ==== | ||
| - | File ''EntityClassDefs.lua'' defines all entity types that can occur in the game. | + | ==== GUIs/ ==== |
| - | The file is read both by the world editor CaWE and the actual game code in order, and for each entity type specifies details like names, dimensions, properties, etc. | + | |
| + | The graphical user interfaces that are used in a game are kept in ''GUIs/''. | ||
| - | ==== Code/ ==== | + | GUIs are used both |
| + | * in "2D", e.g. for the main menu, the console window, the "HUD" (head-up display) in the game, etc., as well as | ||
| + | * in "3D", as parts of the game worlds, that the player can use e.g. to call lifts, to unlock doors, to activate teleporters, or to control any other game script action. | ||
| - | Directory ''Code/'' contains the source code for the implementation of this game. | + | The GUIs kept in ''GUIs/'' are usually "2D" GUIs, and "3D" GUIs that are universally used in multiple maps. "3D" GUIs that are specific to a single map can either be stored in ''GUIs/'' as well, or along with the map in the same directory as the map. |
| - | The source code is compiled into a program library that the Cafu Engine dynamically loads and binds to at runtime whenever it initializes for a new game. | + | At this time, the following GUIs are automatically loaded by the Cafu Engine: |
| - | The program libraries are known as "DLLs" (dynamic link libraries) under Windows, and "SOs" (shared object) under Linux. Independent of the platform, this library with the binary code is referred to as "DLL" in this documentation, and it is kept in another subdirectory of ''Code/'' as well. | + | * ''GUIs/ChatInput.cgui'' -- implements the text input when the player presses ''T'' to talk in the game. |
| + | * ''GUIs/Console.cgui'' -- implements the in-game command console, opened with ''F1''. | ||
| + | * ''GUIs/MainMenu/MainMenu_main.cgui'' -- implements the main menu that is shown after program start. | ||
| - | The DLL is expected to have the same name as the game, and thus expected to be found in | + | In addition, the DeathMatch game code in ''DeathMatch/Code/HumanPlayer.cpp'' loads |
| - | Games/DeathMatch/Code/build/.../DeathMatch.dll (Windows) | + | * ''GUIs/HUD_main.cgui'' -- implements the players head-up display (cross-hair, ammo count, etc.). |
| - | Games/DeathMatch/Code/build/.../DeathMatch.so (Linux) | + | |
| - | where ''%%...%%'' is a path that is automatically created by the build system according to your platform, compiler and build variant. | + | |
| - | The ''%%...%%'' path is also known to the Cafu Engine so that it can load the library. | + | |
| - | See section [[#the_game_source_code|The game source code]] for more details about the game source code. | + | You can replace all these GUIs by providing your own editions in their place, or just copy them from the DeathMatch example game and modify them as you like. |
| - | ==== GUIs/ ==== | + | ==== Maps/ ==== |
| - | , GUIs in ''GUIs'' | + | Contains the map files as saved by the CaWE Map Editor. |
| - | FIXME | + | |
| + | You don't actually have to save your map files in this directory, but we may merge ''Maps/'' and ''Worlds/'' sometime in the future, and thus ''Maps/'' is still the recommended place to save ''.cmap'' files. | ||
| - | === GUIs/Console.cgui === | ||
| - | FIXME | + | ==== Materials/ ==== |
| + | All material definitions for the game maps are kept in ''Materials/''. | ||
| + | Materials are often reused in several maps of a game, and thus ''Materials/'' is where all map materials are centrally stored. | ||
| - | === GUIs/MainMenu/MainMenu_main.cgui === | + | The CaWE Map Editor loads the material definitions from this folder in order to provide the map designer with the choices in the Material Browser dialog. The Cafu Engine loads the material definitions from ''Materials/'' as well in order to render the materials in the game. |
| - | FIXME | ||
| + | ==== Music/NextTitle.txt ==== | ||
| - | ==== Worlds/ ==== | + | Whenever the player enters a new map, the client calls console function ''StartLevelIntroMusic()'', that in turn is defined in file ''config.lua'' in the Cafu top level directory and that uses file ''Music/NextTitle.txt'' in order to play the next title from the list of files in ''Music/''. |
| - | , world files in ''Worlds/'', and so on. | ||
| - | FIXME | ||
| + | ==== Textures/ ==== | ||
| + | The texture images that the materials in ''Materials/'' are referring to are stored here. | ||
| - | ===== The game source code ===== | ||
| - | The source code for the DLL is in ''Code/'', inside which you can organize and arrange the source files at will. | + | ==== Worlds/ ==== |
| - | The first function that the engine calls in the game DLL is ''GetGame()''. | + | Maps from ''Maps/'' must be "compiled" in order to be used with the Cafu Engine. |
| - | For our example game DeathMatch, we have defined this function in file | + | Compiling turns a map file (suffix ''.cmap'') into a world file (suffix ''.cw'') and is documented at [[mapping:compiling_new]]. |
| - | [[http://trac.cafu.de/browser/cafu/trunk/Games/DeathMatch/Code/DeathMatch.cpp#L89|Games/DeathMatch/Code/DeathMatch.cpp]]. \\ | + | |
| - | //Please check out this file for more information on the function signature and documentation!// | + | |
| - | The next steps to get more familiar with the code is to check out the | + | The world files generated by compiling are stored in ''Worlds/'', where the main menu GUI (''MainMenu_main.cgui'' in the DeathMatch example game) looks for ''.cw'' files that the player can choose to enter. |
| - | [[http://api.cafu.de/classcf_1_1GameSys_1_1GameI.html|cf::GameSys::GameI]] interface, | + | It also looks for a matching screenshot image to show with the maps list. |
| - | and its implementation in ''GameImplT''. | + | |
| - | The core engine will call the methods of the ''cf::GameSys::GameI'' interface, e.g. those to have new entities created after a map file has been loaded or when another player joins the game, and it's the job of the game code to provide implementations for these methods. | + | The ''Worlds/'' directory is also the right place for [[http://api.cafu.de/lua/|map scripts]]: |
| - | See the code for class ''GameImplT'' in order to see how it was done for the DeathMatch game. | + | * A map scripts must be placed into the ''Worlds/'' directory "next" to the compiled world file. That is, the script must have the same base name as the world, but suffix ''.lua'' instead of ''.cw''. |
| + | * The map script is //not// compiled along with the ''.cw'' file: You can change it at any time, and the changes become effective as soon as the world is loaded/restarted the next time. In fact, it is even possible to [[general:developer_faq#how_do_i_dynamically_reload_the_map_script_in-game|update a map script while the game is running]], that is, //without interrupting it//. | ||
| - | With the ''BaseEntityT'' pointers to newly created entities, the engine will also call the virtual methods in the ''BaseEntityT'' interface, in order to let entities know about events or to have them carry out tasks. | ||
| - | These methods too are supposed to be overridden by the concrete entity implementation, and are in fact the essence of implementing a game: | ||
| - | An entity is considered a state machine that lives in a virtual world, interacting with the world and other entities, and for example its ''BaseEntity::Think()'' method is expected to update it over a small amount of time whenever the method is called (by the server code inside the engine). | ||
| ===== Exploring the code ===== | ===== Exploring the code ===== | ||
| - | This document is not complete, and we will continue to improve it. | + | The class hierarchy is shown in ''Ca3DE/ClassDiagram.dia'' |
| - | + | ||
| - | The class hierarchy is shown in | + | |
| - | - http://trac.cafu.de/browser/cafu/trunk/Ca3DE/ClassDiagram.dia and | + | |
| - | - http://trac.cafu.de/browser/cafu/trunk/Games/DeathMatch/CodeDesign.dia | + | |
| - | but these two documents need to be merged and updated and completed, where necessary. | + | |
| - | + | ||
| - | + | ||
| - | If you have questions about anything that is mentioned in this document (or is missing and should be mentioned), | + | |
| - | please let us know! We will be happy to answer you questions and use the answer to improve this text. | + | |
cppdev/gamecodeoverview.1316722676.txt.gz · Last modified: 2013-01-07 12:07 (external edit)