Welcome to the QuakeC programming introduction. This article is intended for people who already have their fair share of experience in other programming languages like Java or C/C++. As you know, there is already the QuakeC reference guide which gives you an overview of the language used in server-side and client-side quake code. You will actually need to read that page at some point. Anyways, this page will provide the following information:

• Understanding of the engine and game code architecture
• How to get the compiler for the server-side and client-side game code
• How to use the compiler, what files it creates and where these files belong
• How to get a current SVN build of an (unmodified) DarkPlaces engine
• Introduction to working with SVN using Eclipse and Subclipse, as well as other tools
• Introduction to the CodeBlocks IDE that allows not only syntax-highlighting but also navigating through the code, as well as autocompletion
• Tips and tricks for staying up-to-date with your own probably massive code-changes, tips for merging conflicted code, and saving your work in modular patch files

To summarize this page: It explains how to setup an environment in which you can efficiently develop SVQC (server-side QC) and CSQC (client-side QC).
Keep in mind that this page does not provide coding tutorials. Some of these may be created another time at another place.

From the programming perspective, Nexuiz consists of two parts:

• The game engine (also called “engine”, “DarkPlaces” or “DP”)
• QuakeC byte code, which is run in a VM (virtual machine)

The game engine provides the capability to run a dedicated (console-only) server as well as acting as a client (which you use to play the game). As you know, DarkPlaces runs on Windows, Linux and Mac systems. To achieve that, the developers have to do quite a bit of work, as they'll have to use different APIs for accessing the hardware that Nexuiz interacts with (such as the keyboard, mouse, joystick, soundcard...), as each operation system provides different APIs for that purpose. This is the reason why all the game-specific logic, e.g. the program code of the game modes, weapons, items, etc. is not written in the engine, as this would mean to write it in the language of the engine, and would also mean that you have to compile the whole engine each time you do a change in the game code.

Instead, the game logic is implemented in its own language, QuakeC, which is compiled by its own compiler, in our case FTEQCC (FTE QuakeC Compiler). The compiled code generated by FTEQCC gets into a file which is the placed inside the data dir of Nexuiz. When you launch the engine, it will look for that file and run the compiled code which is in that file in a virtual machine. This has three advantages:

• Compilation is fast, as you compile the game code only
• You will get byte code which means that your game code is platform independent (as long as the engine which interprets it is able to run on the platform)
• There are defined “interfaces” that allow you to interact with the engine. Can raise the security of the code.

However, it also has disadvantages:

• QuakeC is a derivative of C, thus it has the disadvantages of C (no OOP, working with zillions of global variables and functions only)
• The compiler is not a standardized C compiler but maintained by a single person. Thus, the compiler has several bugs.
• QuakeC code performs much worse than compiled C code
• QuakeC is not that functional as C, you often call functions of the engine (because the engine already has the functionality or the function would simply be much faster when implemented in the engine). For this you call these “interfaces”. Actually, these are called built-in functions (more about them comes in another tutorial)

For compilation the FTEQCC needs a file called progs.src which basically contains a list of all .qc and .qh files (note the intended similarity to .c and .h files). FTEQCC then compiles all these qc and qh files after another and puts the result in a .dat file. Remember that I was talking about 1 file that is interpreted by the engine? In fact, you actually need 3 of these files (and you also need to run FTEQCC 3 times while you specify a different progs.src file each time):

• SVQC (server-side Quake code): This is the game code run on the server, it's usually the code where most parts of the game logic is implemented (because it is the server that controlles the game, not the client). The progs.src file you specify is the one in /data/qsrc/server . The resulting file is called progs.dat
• MenuQC: This is the menu code. The menu is actually written in C. Yet it is compiled using FTEQCC. The progs.src file you specify is the one in /data/qsrc/menu . The resulting file is called menu.dat
• CSQC (client-side Quake code): Since Nexuiz 2.4.2 DarkPlaces contains the CSQC extension which allows the developers to create code that is run on the client only. The coding is similar to SVQC, it is written in QuakeC. CSQC is used for things that would otherwise have to be customized by the server for each client, e.g. notification events, an intelligent HUD system, or simply things that actually were clientside before, but done completely in engine code.
  The progs.src file you specify is the one in /data/qsrc/client . The resulting file is called csprogs.dat

All 3 dat files need to be placed in the data directory of Nexuiz, as the engine expects them to be there.

Another note: FTEQCC also creates a lno file for each dat file. For Nexuiz these lno files are not important or needed. In case that you distribute a mod you created, you won't have to publish the lno files, only the dat files.

Hereby I assume that you are familiar with the basics of SVN and know how to check out code from a given location. Usually you would now have to download Nexuiz and it's QuakeC code, the DP engine and FTEQCC from SVN, compile FTEQCC and DP and then use your fresh FTEQCC binary to compile the code inside /data/qrsrc. However, the compilation of DP or FTEQCC can be non-trivial, especially for the ones that are not used to Makefiles and the C compiler.

This is the reason why beginners should use a premade build-system. However, the build systems are platform specific.

For windows you can get the build-system made by divVerent, located here. After you downloaded and extracted the zip file, all you have to do is to start the build.bat file and wait. The script will do all the work for you:

• Check out FTEQCC from SVN (having a recent FTEQCC version is always recommended, because of bugfixes)
• Compile FTEQCC
• Check out DarkPlaces from SVN
• Build the DarkPlaces engine (it also builds the SDL version!)
• Check out Nexuiz (textures, maps, models, game source code...)
• Build the three dat files using your new FTEQCC binary

Note 1: The compiled FTEQCC binary is the console version which makes sense as it is executed in the batch file, however, there is also a GUI version of FTEQCC that you can get in one Nexuiz source package builds also done by divVerent, e.g. here.

Note 2: For the future I would recommend that you take a closer look at the build.bat file and create your own modified versions of it, e.g. one that only compiles the Nexuiz game code with FTEQCC - you will need this one often when you change the game code in your future QuakeC coder career and you want to compile it fast.

Note 3: To start the game, all you need to do is to start the run-wgl.bat or run-sdl.bat file. The three dat files generated by FTEQCC will already be in the correct place, you don't need to worry about that!

Soulbringer has written a bash script to automatically do the dirty work for linux users. It keeps a checkout of SVN clean and exports your installs/updates to a folder with the revision number i.e. Nexuiz_SVN_5277. For this reason, it's recommended you have at least 4gb's free.

The dependencies are as follows (ubuntu or debian-based users can paste the following into the terminal to install them):

sudo apt-get install build-essential xserver-xorg-dev x11proto-xf86dri-dev x11proto-xf86dga-dev x11proto-xf86vidmode-dev  libxxf86dga-dev libxcb-xf86dri0-dev libxpm-dev libxxf86vm-dev libsdl1.2-dev libsdl-image1.2-dev libsdl1.2debian-alsa subversion libclalsadrv-dev libasound2-dev libxext-dev zenity

Then download the script to a folder... say ~/nexuiz_svn and chmod it +x (executable)

mkdir ~/nexuiz_svn
cd ~/nexuiz_svn
wget http://z.nexuizninjaz.com/bash_scripts/sb_install_010209.sh
chmod +x sb_install_010209.sh

type the following to display help:

./sb_install_010209.sh -h

most of you will want just the client:

./sb_install_010209.sh -t c

To update, just run the command again, the script will automatically create a new folder with revision number for you.

Note: this script isn't very verbose. It's not hanging, just be patient.

You can create a shortcut to the latest revision with the following script:

#!/bin/bash
# for use with soulbringer's nexuiz install script
# used to find the latest nexuiz revision and run it
 
# find the dir this file is in
base_dir=$(dirname $(which $0) | sed 's/\/.$//' )
# change to that directory
cd $base_dir
# change to the latest nexuiz revision directory
cd $(ls | grep Nexuiz_SVN_ | tail -n1)
# start nexuiz
./nexuiz-glx

(edit nexuiz-glx to nexuiz-sdl if you prefer this version)

save the code above as nexuiz_start.sh in the same folder your keep the sb_install script in then chmod +x nexuiz_start.sh

You can now call this file from a shortcut with:

/path/to/your/nexuiz_svn_directory/nexuiz_start.sh

TODO: Someone else has to do the mac part!

Please test some of the other clients and recommend the good, free ones here:
http://en.wikipedia.org/wiki/Comparison_of_Subversion_clients
http://subversion.tigris.org/links.html#clients

Even though the build-system mentioned above comes with a command-line svn client used for checking out the sources and updating them, you will need at least one good SVN client with a graphical user interface. If you are ambitious and, within given time, do more or less big changes to the QuakeC code base, you will find out that you will have to do a lot of conflict merging when you update your SVN copy, because it is likely that you changed parts of the code that were, in the meantime, also changed by the official developers. The other reason to use a handsome SVN tool is the ability to create and apply patches to your code base without being a victim of command line tools as well as having a good graphical diff utility which comes with these SVN tools nowadays.

Eclipse in combination with Subclipse is the only tool I know of that allows you to have a truly non-destructive update procedure. Normally, when you use other tools and you update your code and a conflict is detected, SVN will mess with your file system, create ”.mine” files, etc, and you better hope that your merge tool is good enough to do the job after the catastrophy happened. With Eclipse+Subclipse, there is the possibility to have a look at the files that would be affected, even before you actually update. You will also see which files would become conflicted, you can deal with the conflict before hand and save the merged file.

Anyways, the following instructions assume that you already have some knowledge about Eclipse, especially the use of its update manager!

Installation instructions

1. Get Eclipse (I'm using 3.4 here)
2. (Optional step) Get the C/C++ development tools by using the Eclipse update manager, use the URL http://download.eclipse.org/tools/cdt/releases/ganymede
   In the Eclipse Preferences, go to the C/C++ section, in there go to the File types dialog and add *.qh as C Header file and *.qc as C Source file
3. Get Subclipse by, again, using the Eclipse update manager and the URL http://subclipse.tigris.org/update_1.4.x
4. (Optional step) An alternative to Subclipse is Subversive. In this case, use the URLs from the “Latest release” on this page: http://www.polarion.com/products/svn/subversive.php?src=eclipseproject - you'll have to install both the Subversive plugin as well as one SVN connector for your operation system

Project setup

1. Create a new project. If you have installed the C/C++ development tools, you can create a C project. Otherwise create a normal project
2. Important: While you setup the new project using the wizard, for the location select the directory that you are planning to work in, and that contains the QuakeC code, e.g. C:\projects\Nexuiz\data\qsrc. The reason why you should do this is, is that you will immediately get the subfolders of the qsrc folder (the server, client, common and menu folder) into your project. Please note that I assume that this specified location is already connected with SVN (I mean that it has the .svn sub folders and could be updated, for example by using another SVN tool), which should already be the case if that folder was checked out using the build-system
3. In the project explorer, right click on your new Project and select Team → Share Project
4. Select SVN, click on Next and then Finish (there actually is nothing else to do, because that folder has always been connected to SVN due to the fact that SVN is file-system based, so we only had to make that clear to Eclipse, well, your eclipse project)

Now you are ready to work with Eclipse:

1. Right click on your project, select Team → Synchronize with repository
2. Eclipse automatically opens the Team synchronizing perspective
3. Now the real work starts: click on the Synchronize SVN icon. Eclipse will automatically present you a list (and only a list, it won't update your SVN copy yet) of files that are changed (either in SVN or in your local copy)
4. Make use of the icons next to the Synchronize SVN icon that allow you to switch between Incoming, Outgoing and Conflicts mode!
   1. Incoming: You will see which files changed only in SVN, these files would be updated without a problem
   2. Outgoing: You will see which files changed on your harddrive (working copy) compared to the original files that are committed to SVN (working base)
   3. Conflicts: Lists all the changed file on your harddrive that would become conflicted if you update your SVN directory, because you did code changes at some places where the Nexuiz development team also did changes to.
5. If you have conflicted files, double click on them.
6. The file diff viewer automatically opens. Have a look at the code changes, manually merge them and save the file. You can also click on the “copy all non-conflicting changes” button first (the function of that button self explanatory) and save the file (in order to get an updated view in the diff viewer) and deal with the rest of the code that is actually conflicted. After your conflict is solved, keep in mind to right click on the file and select “mark as merged”!
7. After you solved all the conflicts you can right click on your project and click on update, which will update all the remaining, non-conflicted files.

Hint 1: It makes sense to rid of files like .project files inside the synchronizing view. You can do that by right clicking on that file and select add to svn:ignore !

Hint 2: I have to admit that the team synchronization view will very often present you “conflicted” files that actually are not really conflicted, but could have been merged otherwise (or other tools would have been able to merge them without problems). You will recognize whether this is the case if you have a look at the small colored square on the right side of the diff viewer. Only if that square is red, you will have to deal with real conficts. If it has another color, e.g. blue, you can just right click on that file and click on Update. Subclipse's SVN client will merge your changes without problems.

Hint 3: Sometimes you might want to update to a particular, older revision. To do this, right click on your project, select Team → Switch. The URL you need to setup should already be correct (you might have to click on “Browse” and just close that window again). Do not, never ever, do the tempting thing to right click on your project and select the “replace with → Revision or url”.

Tortoise SVN is a very well known SVN client for Windows. It works as a shell extension, which means that you can right click on files and folders in your windows explorer and do the SVN operations you like.

The functionalities of SVN tools are very similar in general (across the different OSes). What I particular like about Tortoise SVN is the abilty to merge conflicts when you patch Quake sources that are already patched. Other than that it has a good change log viewer (you can search for strings in the change log description, this is really helpful), a good file differ and the merge utility is also good once you found out how to use it. Of course Tortoise SVN can apply and create patch files without problems.

From my experience, most Linux SVN gui's haven't been too good. RapidSVN is buggy as heck and kdesvn doesn't work properly in gnome. I've recently come to use Nautilus SVN which integrates with your file browser nicely.

The Linux tortoise SVN equivalent

http://code.google.com/p/nautilussvn/

Refer to their installation wiki page and use the 'manual installation' script for the latest version.

I assume that you are already used to some kind of comfort when working with a programming language. An example would be working with Java using a proper IDE such as Eclipse or Netbeans, or creating C/C++ code using an IDE like MS Visual Studio (or any other good commercial or even open source IDE). What these IDEs usually provide is at least an editor that allows syntax highlighting as well as various other features, such as finding the definition or implementation of a selected function by only pressing a key combination, looking for occurences of the selected symbol, or navigating through the source files efficiently.

As QuakeC is similar to C, you might think that you can use any IDE that has sufficient C support to get all the features you are used to when creating C code. However, the only IDE I found that was really able to recognize all symbols (including global variables and global functions), look for occurrences of selected symbols (well, text) in the code and is able to navigate through the code is the IDE Code::Blocks! Code::Blocks is platform independent!

On the official page you can download the binary release for your OS. If you are using Linux, you can also install Code::Blocks from your package manager, the package name will be similar to “codeblocks”. If you are using Windows, you can even download a version that includes the GNU C/C++ compiler from MinGW (if you don't know what MinGW is, then this is the right package for you to download, especially if you choose to modify the engine code and want to recompile the engine, for which you will need a C/C++ compiler, which you will already get shipped with Code::Blocks in this case). If you are on Linux, there is no special Code::Blocks package that includes a C/C++ compiler, because your linux package manager will usually provide the ability to install the GNU C compiler package using your distro repository.

Anyways, after you downloaded and installed Code::Blocks I recommend that you download the QuakeC syntax highlighter add-on. The zip contains the lexer_qc.xml and lexer_qc.sample files, which you have to put into your share/CodeBlocks/lexers directory! If you are on an ubuntu system, this directory is located in /usr/share/codeblocks/lexers. After that, make sure that in the Settings → Environment → File extension handling dialog the wildcards *.qc and *.qh are present and setup that they are opened inside the Code::Blocks editor. Also, you will discover that e.g. the background will be grey. If you don't like that bg-color or want to change the color of other elements, change them at Settings → Editor → Syntax Highlighting (select the QuakeC syntax highlighting and then modify the colors you want to change).

Then create a new, empty project somewhere on your hard disk. To do this click on File → New → Project. Select Emtpy project and click on Go. In the wizard that opens, enter a name for your project. When you come to the compiler-selection dialog, it doesn't matter which compiler you setup, as you will have to compile QuakeC outside of CodeBlocks anyway. After you finished setting up the project, right click on your project and select add files recursively. Select the qsrc directory and click OK. Then click on Wildcard select and enter *.qh;*.qc as wildcard, click OK and approve that you want to clear your previous selection. Finally click on OK.

Apart from that I recommend that you use one of the recent nightly builds of Code::Blocks (you can find them in this forum), because they have useful additional features. At least these two of them are interesting for you:

1. In the Symbols tab you can now search for symbols (e.g. function or global variable names)
2. A so-called “Threaded search”, which offers a new dialog for finding text in files. It works by providing a seperate window that shows/previews the search results, which is much more effective because you don't have open the source file that contained a “hit” in your main editor anymore, at least not every time when you just want to find out if the proposed file/line hit was the one you were looking for

Now some more details about the features of Code::Blocks:

• If you double click on a symbol, all other occurrences of that symbol will be highlighted in red color. Very handy to identify a symbol in other places in the same source file
• You can navigate to either the definition or the declaration of a function (or a variable). Just right click on the symbol and select the desired choice in the context menu.
• When hopping around in the code it is handy to have the ability to get back to the last position before you jumped (e.g. jumped to a definition of a function). There are two shortcuts for this.
  • When your jump was a jump from one source file to another one, use ALT+LeftArrowKey to get back to your previous file
  • When your jump was inside the same source file, you need to place a “BrowseTracker mark”. For this, you'll need to activate the BrowseTracker in the Editor Options! To place a bookmark, hold down your left mouse button for a short moment, you'll see a visual representation that the mark was set. Then jump to the other location. To get back, use ALT+ArrowUp (or ArrowDown)
• You can use Auto-Completion at anytime for global variables, functions or local variables by pressing STRG+Space
• If you want to open a file of which you know (part of) the name, use ALT+G to open the search mask to open your desired file
• If you know the name of a function that is located inside the source file that is currently open, use CTRL+ALT+G to open the search mask
• Keep in mind that for some of the introduced features there are valuable shortcuts, you will see them when you open the menu (not the context menu by right clicking on the symbol but click on “View” for example in the menu bar)

I've created a video demonstration (Download as Xvid, 66 MB) that shows the features in action.

Important: For me an unpleasant bug occurs: everytime I close Code::Blocks and open it again, I find out that I've got no entries in the Symbols tab anymore, and jumping to declarations or implementations of a function doesn't work anymore. To fix this, I just add the files recursively to my project again (right click on your Project and select add files recursively as explained above, you don't need to delete the files that already are in your project, they will be automatically replaced).

Now that you know how to setup your development environment you should start getting to know QuakeC. First of all, you will need to learn the basics of the C programming language, because QuakeC is based on it and the QuakeC reference guide will assume that the C basics are known to you already. Then continue and read the QuakeC reference guide!

I guess that most of the people who try to understand QuakeC or probably even the engine code does this for a reason: most of you would like to see their code make it into the Nexuiz codebase - and as long as it is a modification that makes sense, the chances aren't bad!

However, you should keep in mind to structure your work. It is likely that you are working on different modifications, possibly even at the same time. With “different modifications” I mean that you are working on different features that are basically independent.

In general it is highly recommended to backup your work regularly using patch files. You can create patches with most of the available SVN tools, such as the tools presented above! There are several advantages:

1. You can work on one feature, save its state to a patch file, revert your code base and then work on another feature
2. If you decide to submit one or more of your features to the Nexuiz development team they will expect you to give them the changes you made individually (one patch file per independent feature)

Apart from that, if you are working on the SVN codebase, you need to know that there can be a massive amounts of commits within a short time. Try to keep your SVN copy up to date by updating from time to time. The longer you wait the bigger the efforts get to solve conflicts that were introduced in the meanwhile.

TODO: If anyone has more general tips, put them here!