Give me some time until this is finished

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:

• How to get the compiler for the server-side and client-side QC
• How to use the compiler, what files it creates and where these files belong
• An easy way how to get a current build of an (unmodified) DarkPlaces engine
• Introduction to working with SVN using Eclipse and Subclipse
• 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 not that functional as C, you often to call functions of the engine (because the engine 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 later)

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!

TODO: Someone else has to do the linux part!

TODO: Someone else has to do the mac part!

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.

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 have to hope that your merge tool is good enough to do the job after the catastrophy happened. With Eclipse+Subclipse, there is the “Team synchronisation” perspective that allows you “spy first”, you click on “synchronize” and you will see which files would be updated if you clicked on “update”. You will also see which files would become a conflicted file, you can deal with the conflict before hand and save the merged file.

Here is how to use it: TODO
http://subclipse.tigris.org/update_1.4.x
TODO: Introduce Eclipse+Subclipse Plugin. Alternative: TortoiseSVN (what about Linux?)

TODO: good for patching patched files, diffing and patching in general

TODO: you linux gurus do that ;p

TODO: Introduction to CodeBLocks, explain the features of it. Explain known bugs.

TODO: Link to the article in this wiki. Some explanations.
TODO2: Explain how to access built-in functions.

TODO: Explain the common tasks that come with the usage of SVN and the fact that you likely changed (a lot of) code:
- Updating SVN by using Team Synchronisation feature of Subclipse to prevent conflicts when updating
- Creating patches to backup your work, keeping your work modular.