Celebrating 12 years of Quake!
Back to Main

Introduction to CSQC by Urre

CSQC, abbreviation for ClientSide QuakeC, QuakeC being the programming language used, clientside. The simple yet powerful language QuakeC, as originally concieved by id Software, only existed for serverside mods, which limited the ability to create many effects and optimisations, and modders lacked control over many things like HUD and rendering tricks.

CSQC is at the time of writing (050808) not a finished business, but finished enough to be mostly implemented in at least two engines, (at the time of writing only DarkPlaces and FTEQW), and being used by a number of modders.

This document is meant for people who are already rather proficient at QuakeC and know about the QSG extension system as implemented and used by most (if not all) modern Quake engines. This is for those who want to be in on the CSQC thing, but don't know where to start.

As a disclaimer I have to point out that this is my personal view of things, many things will be "wrong", and there's no "right" way of doing things.

Before we get into what CSQC is and what it can and can't do, i figured I should begin with a piece of history, for those interested.

History of CSQC

The history of CSQC goes way back, numerous people have talked and dreamed about it, but the need for it started to become more and more apparent as people started asking for numerous new features to popular engines, which could easily have been handled by the gamecode, had it access to certain subsystems. Most often it had to do with clientside effects, and HUD control.

Spike took it on himself to begin designing the extension, with input from LordHavoc. Spike began implementing CSQC to his FTEQW engine while writing the EXT_CSQC entry on the Quake wiki, but before the design was complete, Betwix-engine author [515], as struck down from clear sky, began implementing CSQC as a .patch for the DarkPlaces engine, on the request of Urre and LordHavoc, based on what Spike had written in EXT_CSQC so far. After a steady stream of screenshots of development posted in the #darkplaces IRC channel, featuring things like drawing polygons and random interesting effects, and finalizing the .patch from his view of the CSQC spec, [515] seemingly left the community. After further design work by Spike, LordHavoc implemented a modified version of [515]'s .patch into DarkPlaces, and Spike wrote his own implementation to his FTEQW engine.

Despite the long-run lack of CSQC documentation beyond what Spike had written in the EXT_CSQC entry on the Quake wiki, community members TimeServ, Dresk and Chris began experimenting with the extension, thus helping LordHavoc and Spike ironing out many bugs. Spike and modder TimeServ had written a piece of CSQC for use when playing the DarkPlaces-specific game Nexuiz on his FTEQW engine, to display Nexuiz' new HUD, which Chris and Dresk based their work on. Eventually, Dresk released a codebase which helped a number of modders get started, effectively making CSQC more of a reality. After the loss of QuakeSource, which hosted the original Quake Wiki, Krimzon wrote the new version of the EXT_CSQC entry in this wiki. Chris released a diablo-style inventory system written for CSQC, and later also a framework for the so called shared entities. Blub\0, a Nexuiz community member and DarkPlaces engine-team member, also tested most of CSQC's features in DarkPlaces, to make sure they worked as expected.

What is CSQC?

It is the attempt to create a more modder-friendly environment of the Quake engine. Instead of having to pester your favorite engine author, or author of your favorite engine, you could more than likely create the new feature all by yourself, provided you're good enough. It takes a very straightforward and simple gamecode language, into the world of clientside gamecode.

CSQC has a much cleaner design than that of SSQC (ServerSide QuakeC), and as thus doesn't include any of the very hacky methods for doing things QuakeC is generally known for. For example, in SSQC, setting the field .movetype to the constant MOVETYPE_FLY on an entity, and giving the .velocity field a vector value, would magicly make the entity fly in the direction and speed of the vector. This does not happen in CSQC. While generally considered a bad thing among new to CSQC, and some old, this kind of mindset provides a much cleaner and hack-less environment to work in. You would instead, to make an entity fly in the same manner, code a function which is called every frame, which reads the .movetype and .velocity fields of the entity, and do the moving yourself, using traceline/box and frametime.

This can take a lot of time to get used to, but once your mind is there, you will most likely find yourself avoiding these generally hacky ways of doing things even in SSQC, because you will most likely find the control you get from coding these behaviors yourself very satisfactory. One could argue that this was a bad design decision for the sake of matching the two (actually three if counting Menu QuakeC) versions, so that one could expect the same behavior of their code no matter where it existed, be it SSQC or CSQC. This especially being the case when creating mods which use shared code between SSQC and CSQC.

So what can CSQC do?

QuakeC is a gamecode language, bear that in mind. CSQC won't give you the ability to create new extensions, but almost.

For example, beyond what SSQC can do, it can do the following things:

- HUD control, mouse driven if you like
- Clientside movement for client entities
- Clientside movement for non-client entities
- Clientside entities
- Shared entities (an entity which exists in both SSQC and CSQC)
- Clientside effects of your own design
- Clientside sounds
- Polygon drawing
- Drawing multiple viewports

And some examples of practical uses:

- Overhead map with important entities such as clients and flags being displayed
- Debris from explosions at no networking cost
- A grenade with only two small network updates, state at being thrown, and once it explodes, instead of updating position over the network every frame
- Diablo-like inventory
- Laser beams drawn with the polygon drawing system
- Monsters which only send network updates whenever something important happens, like when spotting a new enemy, when shooting, or when getting damaged
- Doom3-like interfaces on screens in the world
- Drawing a miniscreen of what your teammate is seeing
- Drawing a 3D hud much like Metroid Prime games
- Make an entirely and truly 2D game using the 2D drawing builtins used for displaying the HUD

Generally speaking it is only your imagination which sets the limits, but here are some examples of things you can't do (at the time of writing):

- Can't display video in HUD
- Can't display video on world polygons (which Doom3 could, thus Doom3-like screens aren't *fully* possible, I lied)
- Cannot control vertexes, polygons or bones on models
- Just like SSQC, cannot read BSP leaf data for the gamecode to use as volumes for AI to navigate

These things popped into mind, as I've wanted to do them myself. Most of them could be added as exensions, or otherwise implemented support for.

Wow! Where do I get started?

First of all, you'll have to ask yourself what you want to do. A simple thing can require a lot of background work, so get your ideas straight. You'll also want to ask yourself if you're up for the task. As briefly mentioned before, CSQC doesn't do things for you, you're on your own. While giving lots of power back to the modder, it also strips a lot of things modders generally take for granted and have grown accustomed to. You will see yourself coding a lot of things you never even thought of having to. But once you're there, once you have a codebase running, you'll wonder how you ever managed without it.

Read up on EXT_CSQC on the Quake Wiki, and the underlying EXT_CSQC_System_Globals_Fields_and_Builtins_List for much a useful overview information. Although being shunned by many for being incomplete, it actually does contain very close to all the information you need. The problem is that it has no practical information, just a spec of sorts. The practical side, I will hope to help covering with upcoming tutorials. Good luck, and happy modding!

- Urre

Back to Main