Changes between Initial Version and Version 1 of Finding_Your_Way_Around

Timestamp:

Feb 23, 2008, 4:18:59 AM (16 years ago)

Author:

trac

Comment:

--

Finding_Your_Way_Around

@@ +1 @@
+= 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 off 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 [wiki:TortoiseSVN_Guide TortoiseSVN Guide].
+
+= Important notes for Visual Studio version 6 and .net 2002 users =
+
+Pyrogenesis uses a standardised compiler so anyone using not using version Microsoft studio.net 2003 or 2005 should Upgrade by download the Microsoft C++ tool kit 2003 from the Microsoft website using the link below. The example installation details are for Studio 2002.
+
+http://www.microsoft.com/downloads/details.aspx?!FamilyId=272BE09D-40BB-49FD-9CB0-4BFA122FA91B&displaylang=en
+
+This can either be installed over the current studio installation. 
+I.e. change the installation path to "C:\Program Files\Microsoft Visual Studio .NET\Vc7" this will then over write the relevant files.
+A more cautious way is installing to another directory and manually copying the bin/lib/include across into the relevant Vc7 directories. After backing up the bin/lib/include directories so you can put things back if all goes wrong.
+It might also be possible to install the Toolkit into a different directory and then use the options dialog for adding/changing include/lib/binary directories (this way you could switch back to your old buggy compiler, would you ever want to).
+
+In addition the following file may be needed so it should be downloaded and extracted into the lib directory.
+http://wildfiregames.com/~code/libraries/msvclibs.zip
+
+= Notes for Visual Studio 2005 users =
+Users of [http://lab.msdn.microsoft.com/express/visualc/default.aspx VC++ 2005 Express Edition] will probably need to download and install the [http://www.microsoft.com/msdownload/platformsdk/sdkupdate/ Platform SDK], and add its ''include'' and ''lib'' directories to the appropriate lists. (Beta 2 seems to be missing the global include/lib directory configuration screen, so you have to add it to the project properties instead.)
+
+= 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 Vc6, Vc7 and Vc2003. So depending on which editor your using enter the relevant directory and a workspace will have been created for your editor. Studio 6 & 2002 users should read the note below.
+
+{{{
+  premake               
+    This useful little tool generates the Make files for different formats (i.e Vstudio, Linux) 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
+
+ * Graphics:    ???
+ * Renderer:    ??? Break this down
+ * Gui:         Graphic user Interface
+ * i18n:                Text Localization.
+ * Lib:         System Specific code, utilities and low-level resource code
+ * Maths:       Relevant 3d Math functions
+ * Ps:          The �engine core�
+ * Scripting:   Scripting Engine
+ * Simulation:  Game Simulation main work�.
+ * Sound:       Audio
+
+= 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.
+ 
+= Engine Summary =
+
+This is basically the Main function a few twists and turns aside.
+
+MICROLOG()
+logs current activity, which is displayed after a crash.
+oglCheck()
+{{{
+        reports any errors that have occurred in OpenGL since the last call. 
+}}}
+
+'''INIT'''
+
+I18n::!LoadLanguage(NULL);      //Loads The Relevant Language Pack
+
+!InitVfs(argc?argv[0]:NULL);    // Vfs creates a Virtual File System
+// Protecting the system & allowing access to archived files
+
+CConsole()                      //Create Console (also see !InitPs)
+
+SDL_Init();                     //See SDL library
+
+!InitScripting();       //Init the script engine & init the //induvidual scripts
+
+!InitConfig(argc, argv);        //Load Config Files "config/system.cfg"
+{{{
+                                //and Parse Commandline Arguments
+}}}
+
+new CGUI;               //Init GUI system
+
+!InitPs();              //This seems to be a miscellaneous set up.
+{{{
+                        //Setup Console font
+                        //setup language
+                        //load hot keys
+                //Set up Some GUI stuff
+}}}
+
+!InitRenderer();        //Create the following And set up lights
+?       new CTextureManager;    //Containers for art resources,
+{{{
+        new CMaterialManager;   //with caching and on-demand loading
+        new CmeshManager;               //where appropriate
+        new CSkeletonAnimManager;
+        new CObjectManager;
+        new CUnitManager;
+        new CbaseEntityCollection;
+}}}
+
+new CPathfindEngine;            //Interface to Path Find Engine
+new CSelectedEntities;          //Selected Entities
+new CMouseoverEntities;         //Mouse over Entities
+new CSessionManager;            //Network Object
+new CGameAttributes;            //Contains The Players info Names etc.
+{{{
+                                //and Number of players
+}}}
+
+
+//Add Handlers
+//These allow an object to receive message from the system I.e. Key presses, similar to the way the windows message loop works.
+in_add_handler(game_view_handler);
+in_add_handler(interactInputHandler);
+in_add_handler(conInputHandler);
+in_add_handler(hotkeyInputHandler);
+in_add_handler(gui_handler);
+in_add_handler(handler);
+
+
+g_GUI.!SendEventToAll("load");  //tell all GUI objects to load up
+!RenderNoCull();        //Forces engine to load up anything that�s needed
+{{{
+                        //By drawing everything
+}}}
+
+'''MAIN LOOP "Frame()"'''
+
+!MusicPlayer.update();          //Call vorbis Music Library
+
+in_get_events();                        //Read Keyboard/Mouse events
+
+g_SessionManager.Poll();        //Call Networking Code
+
+g_GUI.!TickObjects();           //Call GUI Code
+
+
+g_Game->Update(!TimeSinceLastFrame);
+// Update all Entities and Perform Game simulation
+
+if (!g_FixedFrameTiming)
+g_Game->!GetView()->Update(float(!TimeSinceLastFrame));
+{{{
+                // Update Camera position view
+}}}
+
+//update for Mouse and selected Entities
+g_Mouseover.update( !TimeSinceLastFrame );      
+g_Selection.update();
+
+
+snd_update(pos, dir, up) ? g_Game->!GetView()->!GetCamera();    // SOUND
+{{{
+        // Pass camera position to Open AL for 3d positional Sound
+}}}
+
+g_Console->Update(!TimeSinceLastFrame); // Call Console Code
+
+Render();                       // Render Screen and display (see below)
+SDL_GL_SwapBuffers();
+
+'''RENDER'''
+
+g_Renderer.!BeginFrame();
+{{{
+        // calculate coefficients for terrain and unit lighting
+}}}
+m_ShadowBound.!SetEmpty(); //clear shaddows
+
+g_Game->!GetView()->Render();   //Create List of polys to draw.
+CGameView::!RenderTerrain(m_pWorld->!GetTerrain());
+CGameView::!RenderModels(m_pWorld->!GetUnitManager());
+
+g_Renderer.!FlushFrame();       //DO ACUTAL RENDER 
+�       g_TransparencyRenderer.Sort();
+!RenderShadowMap();     //Create Shaddow Map
+{{{
+        glClear()
+}}}
+!RenderPatches();               //Acutally render Patches
+!RenderModels();                //Acutally render Models
+
+!ApplyShadowMap();              //Render Shaddows onto ground
+g_PlayerRenderer.Render();
+g_TransparencyRenderer.Render();
+//Render any Defered Tranparencys
+
+//Clear all lists
+g_TransparencyRenderer.Clear();
+g_PlayerRenderer.Clear();
+{{{
+        CPatchRData::ClearSubmissions();
+        CModelRData::ClearSubmissions();
+}}}
+
+g_Mouseover.renderSelectionOutlines();
+g_Selection.renderSelectionOutlines();
+
+// overlay mode //Front end stuff.
+glOrtho(0.f, (float)g_xres, 0.f, (float)g_yres, -1.f, 1000.f);
+g_GUI.Draw();
+CFont font("console");
+font.Bind();
+g_Console->Render();
+g_Mouseover.renderOverlays();
+g_Selection.renderOverlays();
+cursor_draw(g_CursorName);
+g_Renderer.!EndFrame();
+
+= 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 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 ==
+
+Can someone list the most common ones?
+
+'''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.