doc/guided_tour.txt

   1 A guided tour of the FS2 source code,  by DaveB
   2 -----------------------------------------------
   3
   4 Within this code you will find both razor sharp coolness and horrifying
   5 atrocities. I'm hoping it'll serve not just as tool for learning how to
   6 do things, but also for learning how _not_ to do things. Have fun with it.
   7
   8
   9 Overview
  10 --------
  11 FS2 is an MsDev 6.0 project. Within the workspace are several subprojects.
  12
  13 - Ac. This is the animation conversion utility for generating FS2's
  14   custom .ani files.
  15
  16 - CFileArchiver. A very simple command line utility for quickly packing
  17   files into .vp files.
  18
  19 - code. 99% of all FS2 code exists in this module. Many of the utility
  20   projects have this library as a dependancy and it is organized as a
  21   simple set of code folders.
  22
  23 - Cryptstring. A command-line tool for generating super-secret codes from
  24   input text. More of a curiosity than anything else ;)
  25
  26 - Fonttool. A simple utility for generating and kerning the font files
  27   FS2 uses.
  28
  29 - Fred2. The FS2 mission editor. A giant mass of MFC code - it references
  30   plenty of stuff from the code library.
  31
  32 - Freespace2. This generates the FS2 executable. There are only a
  33   handful of files in this subproject - most of the game comes from the
  34   code library.
  35
  36 - Nebedit. An old utility used for generating FS1 style background nebulae
  37   patterns. Not used directly in FS2, but the code to display the old
  38   nebulae still exists in the FS2 codebase.
  39
  40 - Pofview. A simple MFC app for viewing POF files as they would appear
  41   ingame.
  42
  43 - Scramble. Top-secret Canadian encryption program. Guaranteed to be
  44   unbreakable for at least 20 to 25 minutes.
  45
  46 The critical subprojects most people will be concerned with are code,
  47 Freespace2, and Fred2. All of these subprojects have Debug and Release
  48 (optimized) builds. pstypes.h also contains quite a few conditional
  49 build switches.
  50
  51 All source safe checkin headers have been left in for maximum comedy.
  52
  53 This is code-only. You cannot run without having a full copy of the game
  54 to supply the data.
  55
  56
  57 Stuff that doesn't exist
  58 ------------------------
  59
  60 Several bits of the game have been removed from this release. Nothing
  61 of major importance. They include the launcher, the movie player, the
  62 auto-updater, and all code related to PXO and squadwar (for obvious
  63 reasons).
  64
  65
  66 Project settings (Msdev 6.0)
  67 ----------------------------
  68
  69 All of the subprojects that rely on the FS2 data tree to run (code, fred2,
  70 freespace2, nebedit, pofview) are all currently targeted at
  71
  72 e:\games\freespace2\
  73
  74 which is the directory I had on my local hard drive for putting this together.
  75 Before you'll really be able to do anything, you'll need to point the targets
  76 at wherever your local FS2 install is (make sure to make a copy of your
  77 installed executables so you can backtrack!).
  78
  79 To change the destination in MsDev, you'll need to change
  80 settings->debug->executable for debug session
  81 settings->debug->working directory
  82 settings->link->output file name
  83
  84 All projects have been verified as compiling and running properly. So, unless
  85 I screwed something up between the time of checking everything and building
  86 the zip file (entirely possible) you should just be able to load the workspace
  87 and hit F7. If not, hey, just one more thing to play with ;)
  88
  89
  90 Post-release addition
  91 ---------------------
  92
  93 I hacked in very quick-and-dirty windowed support for Direct3d mode.
  94 The way FS2 was developed, we always could rely on running Glide
  95 on a second monitor. Trying to do any kind of serious debugging in full
  96 screen Direct3D is just a recipe for agonizing pain. So windowed D3D
  97 should make debugging a whole lot easier for the average guy. I make no
  98 guarantees about completeness or stability since it was hacked together
  99 in 3 hours - however it does appear to function properly in both resolutions,
 100 in both 16 and 32 bit desktops. Depending on your 3d card and your driver
 101 settings, you may get some texture coordinate wackiness (particularly
 102 visible on interface screens) but for the purpose of debugging/development
 103 it should be sufficient. Fiddling with your driver settings in Control Panel
 104 can make this go away.
 105
 106 You can run the game in windowed mode by adding -window on the command-line.
 107
 108
 109
 110 Interesting projects
 111 --------------------
 112 There's a bunch of cool things that could be done with the code.
 113
 114 - It uses directX 5. It might be fun to bring that whole thing up to
 115   speed with DX8.
 116
 117 - The lighting and model rendering code works, but is much more expensive
 118   than it needs to be on average. With even a little bit of work, it
 119   wouldn't be too hard to probably triple the throughput of that part of
 120   the pipeline (taking advantage of the guard band present in almost all
 121   modern 3d cards, maybe even a dash of T&L).
 122
 123 - The multiplayer code is huge and scary. Its nor particularly "modern" in
 124   terms of motion prediction and lag compensation. It could use some taming.
 125
 126 - With the higher fillrates available on video cards today, I'm sure the
 127   full nebula effect could be improved/changed quite a bit.
 128
 129 - The FS community has been clamoring for higher ship counts and object limits.
 130   It would be a pretty trivial matter to have a commandline option that lets
 131   you specify MAX_SHIPS and similar constants. The internal stuff could be
 132   changed from a static array to a dynamically allocated array at startup. A
 133   few #defines would be need to changed to ints, but beyond that it should be
 134   pretty trivial.
 135
 136 - The Ai code is another huge, intimidating system. There's plenty of room for
 137   cool AI functionality.
 138
 139 - There's a mostly empty opengl implementation of the low level graphics code.
 140   Might be fun to complete. Although I doubt it would be nearly as fast as D3D
 141   or Glide, you never know.
 142
 143 - Fred2 is the omega of all giant unwieldy pieces of code. Its big, its horrifying,
 144   and it just doesn't care. View it at your own risk.
 145
 146 - The physics library is pretty well partitioned and lives in its own little
 147   world. If you want to add newtonian motion, that's where you'd start.
 148
 149 - The particle system code, while also functional is a bit old fashioned. A
 150   little elbow grease could really bring it up to speed and make it able to
 151   handle much higher particle counts.
 152
 153 - Mods. Have at it.
 154
 155 - Multi-res interface. For all the masochists out there.
 156
 157 - There was a demo recording/playback system I half-heartedly was playing with at
 158   one point. Its still in there, in very incomplete form.
 159
 160 - The math library is very powerful. Not necessarily a "project" on its own, but
 161   its very sophisticated.
 162
 163 - Bmpman is rather brutish. It could be made far more elegant.
 164
 165 - The sexpression code is some of the more elegant and powerful code in the game.
 166   Its very extensible and fairly easy to work with. Much functionality can be
 167   added with these.
 168
 169 - For every bug you can find, I'll give you $5. No, I'm kidding. I don't have
 170   that much money.