Element 61

Tuesday, August 23, 2005

Looking at the Quake 3 Source -- Part 1

In case you're not aware (for example, you may have been living in a cave where the only internet is dial up access to a 3 month old backup of the google cache), the Quake 3 source is available for download, under the GPL. My initial impressions are good, given that when I looked at Q2 back in the day, I very nearly gave up hope of ever accomplishing anything. Things are for the most part well organized, categorized, and sensible. The id penchant for clumping a dozen header files into just one continues, but overall it's easy to find the code you're looking for. Hell, it took me 3 days to find the BSP code in Quake 2 because they had called it model_t or some such meaningless thing. I can see why Q3 was so popular for licensing, despite being in C. Is it perfect? Of course not. Naturally there are hacks here and there, and a few very weird design things...and the C versions of what would in C++ be inheritance and aggregation are hilarious. But it's not the horrible tangled mess we were all scared it could have been. Overall though, I think this code is going to go a lot farther than Q1 or Q2 source ever did. Compared to everything else out of id, this source is really quite nice. Most functions have documentation if it's not obvious what they do. All of the members of the major engine structs are well commented, for the most part. Now, there is still evidence of Carmack's "magic" at work. Long stretches of uncommented MMX assembly code. Really strange math code implementations at times, and occasionally stuff going on in the renderer that you have to stop and think about. Despite all that, the overall architecture is good. And I'll be poking around their architecture.

Before we go into the actual code, let's examine how Quake 3 is basically structured. No use looking at all the various structs if we don't know what they're for. So basically, every Quake and Quake based game since the beginning of time has revolved around the fundamental concept of an "entity". Everything in the game world is an entity. All the things you see -- the map, players, doors, items and weapons -- as well as plenty of things you don't see, are entities. Really, everything else that happens in the world is generated from the entities. All of the logic is controlled by interactions between the various entities. And when you're creating your own mods, the entities are what you'll really be working with the most. The core entity struct is the gentity_t, defined in code/game/g_local.h. I won't bother to replicate it here in its entirety, but let's take a look at what's in this thing. A quick glance through this struct will show that the lack of inheritance in C leaves its marks -- there are lots of things here that have no business being in a struct that represents every single object. That aside, I'll outline some of the most interesting members:

  • classname -- Roughly speaking, the type of the object. It's basically a string that tells us what this is -- a player, a part of the map, etc.
  • model, model2 -- The model (and alternate model) that this entity is rendered with. An invisible/non rendered entity wouldn't have an model associated with it.
  • flags -- This variable contains a list of flags bit-ORed together to tweak behaviors. God mode, for example, is set here.
  • physicsObject -- True if this is a movable object, false otherwise. The physics in Q3 is pretty damn simple, but there's great potential here (ODE or Novodex, somebody?).
  • parent -- There's a crude scene hierarchy here; entities can be attached to other entities.
  • speed, movedir -- This is our velocity. That's all we really need to update the object's position from frame to frame, since there's no real physics.
  • health -- Well, straightforward, really. Not just for players; it can be used to destroy any entity you want when its health reaches 0.
  • takedamage -- True if this is a thing that takes damage, dies, etc, false otherwise.
  • item -- When you pick up a quad damage or other item, it goes here. Q3 had a weak item system...well, almost no item system at all. This is another location that might be useful to mess with.
Now I've skipped one very important part of the entity struct, the block of function pointers in the middle. These function pointers basically provide logic and AI for all of the entities, and provide a fairly simple but powerful and flexible way of creating simple or complex behaviors. Let's look at the different pointers:
  • reached -- Happens when a "mover" entity reaches the end of its path.
  • blocked -- Happens when an entity's path is blocked by something.
  • touch -- Happens when an entity comes in contact with another entity. If you were writing a contact grenade or a rocket, you could use this to create an explosion.
  • use -- Happens when the player presses the 'use' key on the entity. You could use this to create some sort of switch or button.
  • pain -- Happens when the entity takes damage but isn't killed.
  • die -- Happens when the entity gets killed.
  • think -- Keep reading.
The think function is by far the most interesting of all of the function pointers. It allows us a great deal of flexibility in controlling what's going on. For example, suppose we were writing a machine gun that could fire 5 rounds per second. We would write a MGFireThink function that created a bullet, then set the nextthink member to current time + 200. Then, 200ms from now, the engine would notice that it's time to think and call our MGFireThink again, allowing us to fire another bullet. Or suppose we were making a grenade that explodes after 5 seconds. We could set its think function to GrenadeIdleThink, and its nextthink to current time + 5000. Then, the next time the think happened we could set it to GrenadeExplodeThink. When that function got called, we would create an explosion.

Anyway, I think that's quite enough for one blog post. Entities are the heart of Quake 3, and there's a lot to be gained by altering the base entity management. A lot of the code in code/game is concerned with working with entities; check out g_weapon.c for a lot of good examples of code that works with entities (specifically, weapon entities). Oh, and one last thing. If you're reading this, please, please leave a comment of some sort, preferably with suggestions of what to cover or what you did/didn't like. I'm a little unsure of where I'm going with this, and where people want me to go.

23 Comments:

  • Nice begining, And thanks for doing this.

    I'm personaly curious about the 3 virtual mechines and how they interact with both eachother and the main system. I can see that when the game is running that all the parts (server, client and UI) are seperate VM's, and that a VM can be either a DLL or some form of byte code that is run time compiled.

    I'd also argue that for what code there is, there is a hell of a lot of flexibility that even a very good OOP design might just manage, but there would be far more in the way of layering in it. (but thats my thoughts)

    But again, thanks.
    Yassim

    By Anonymous Yassim, at 8/24/2005 12:23 AM  

  • A very nice read. Could go over the main game loop? Specifically, how and when the different sub-systems are updated(client/server).

    Looking forward to reading part 2

    By Anonymous Jack Sotac, at 8/24/2005 2:35 AM  

  • Wouldn't mind if you elaborated even more on the global architecture. So it all revolves around entities but how does it all mesh with the rendering physics networking etc?

    I would like a birds view overlook over how the whole thing is tied togheter. Very nice read anyhow.

    By Anonymous DrunkenCoder, at 8/24/2005 5:40 AM  

  • Useful, I'll keep reading.

    By Anonymous Oli, at 8/24/2005 9:50 AM  

  • I was messing with the Quake 2 code last week in anticipation of the Q3 release, once it got released, I found myself lost in the code structure (I mean, there is a copy of the lcc compiler code in there, why?), thanks to you I might give it a second look.

    Thanks, and keep them comming!.

    By Anonymous Kwizatz, at 8/24/2005 11:29 AM  

  • Thank you very much for this article. Although this is a blog and not a technical text book, it would be nice if you went into further detail about some of the assertions you make. For example, a line like this: "Naturally there are hacks here and there, and a few very weird design things...and the C versions of what would in C++ be inheritance and aggregation are hilarious," begs for examples. I believe specific psuedo code or snippets of code that illustrate your points may be more conducive to discussion and may help promote further insight. (For me at least)

    I'm dying to continue reading. Please don't keep us waiting too long before you put out the next one.

    By Anonymous Paul, at 8/24/2005 12:11 PM  

  • Thank you, thank you.

    This is a great read, and well it is also the first good explination i have read of anything quake3. So my request is like the one above, the main game loop... Well, i found Win_main... But i am still trying to track down, where the engine enters the game code. I know mod makers know the tricks, but i have yet to read good docs/tutorials/ on what is going on.

    thank you again!

    By Anonymous Anonymous, at 8/24/2005 4:18 PM  

  • Damn straight! Keep it up! =D

    By Blogger dbzprogrammer, at 8/24/2005 9:10 PM  

  • Wow, now that is some clever design. Too bad I probably won't use it in my game that I'm making, but if I was making a more general purpose engine, this would be an excellent reference!

    By Anonymous Cypher, at 8/25/2005 12:45 PM  

  • I'm extreeeeeeeeemely interested in the Q3 code and naturally I'm extreeeeeeeeemely interested in seeing it explained and documented as I have absolutely no experience with it, and learning 325,000+ while doing a million other things unfortunately goes very very slowly.

    I'm really interested in:
    - Understanding how each system works on its own. That is, what the related structures are, what the main functions do etc.. For example, how does the scripting work? What scripting features are there? How do you extend it? How does the menu system work? Physics? Networking especially. Big pictures of the systems.
    - Understanding the overall architecture of how game and where game systems interact. Like how input triggers weapon firing and how that is sent to the server, back to the clients.... etc.
    - Figuring out how the whole shader system works (which is responsible for the animated textures etc).

    There are so many things to learn it's hard to say what I want to know and be specific, because I want to know it all.

    I'm sure that many people have the following goals:

    a) Figure out how the thing works.
    b) Figure out where the line between engine code, and game code is
    c) How to cut out the game code and figure out what code needs to be written to begin a new project.

    Other goals would be:

    a) Figure out how the "blah" system works
    b) Figure out how to complete a structural change to overhaul the "blah" system to be more modern.

    Like implementing a better lighting and shader system.

    Hope that helps....

    By Anonymous Seth Willits, at 8/27/2005 2:18 AM  

  • I'm extreeeeeeeeemely interested in the Q3 code and naturally I'm extreeeeeeeeemely interested in seeing it explained and documented as I have absolutely no experience with it, and learning 325,000+ while doing a million other things unfortunately goes very very slowly.

    I'm really interested in:
    - Understanding how each system works on its own. That is, what the related structures are, what the main functions do etc.. For example, how does the scripting work? What scripting features are there? How do you extend it? How does the menu system work? Physics? Networking especially. Big pictures of the systems.
    - Understanding the overall architecture of how game and where game systems interact. Like how input triggers weapon firing and how that is sent to the server, back to the clients.... etc.
    - Figuring out how the whole shader system works (which is responsible for the animated textures etc).

    There are so many things to learn it's hard to say what I want to know and be specific, because I want to know it all.

    I'm sure that many people have the following goals:

    a) Figure out how the thing works.
    b) Figure out where the line between engine code, and game code is
    c) How to cut out the game code and figure out what code needs to be written to begin a new project.

    Other goals would be:

    a) Figure out how the "blah" system works
    b) Figure out how to complete a structural change to overhaul the "blah" system to be more modern.

    Like implementing a better lighting and shader system.

    Hope that helps....

    By Anonymous Seth Willits, at 8/27/2005 2:18 AM  

  • Sorry about the double post. Finger spasm at just the wrong time.

    By Anonymous Seth Willits, at 8/27/2005 2:19 AM  

  • I'm really interested in all aspects of the Q3 source code. I'm just getting into game programming, so this is going to be very useful for me. Something no one else has mentioned (I don't think) is Q3's net code. I wouldn't mind to see a post on that.

    By Anonymous Chris, at 8/27/2005 11:08 PM  

  • Hey man keep up the good work.

    By Blogger Gor435, at 9/01/2005 9:20 PM  

  • Nice work man,
    I would love to see something more about how the entityes gets over the wire.

    Anyway just make more articles, they are a good read in any case.

    By Anonymous CoMaNdore, at 9/03/2005 4:24 AM  

  • Vous avez un blog très agréable et je l'aime, je vais placer un lien de retour à lui dans un de mon blogs qui égale votre contenu. Il peut prendre quelques jours mais je ferai besure pour poster un nouveau commentaire avec le lien arrière.

    Merci pour est un bon blogger.

    By Blogger vente, at 10/08/2005 10:33 AM  

  • AI, I am still working on clearing nightmare level, I am interested in how those bots live.

    By Anonymous Anonymous, at 6/13/2007 9:47 PM  

  • Hi! good stuff, good overview/introduction to the quake 3 engine. we're doing a game project with the quake 3 engine at our student club (www.acagamics.de) will read more. ;)

    By Blogger Yojimbo, at 11/14/2008 10:20 AM  

  • Catch the wow gold star that holds your gold in wow destiny,cheap wow gold the one that forever maplestory money twinkles within your heart. Take advantage of precious opportunities while they still sparkle before you. Always believe that your buy maplestory mesos ultimate goal is attainable cheap mesos as long as you commit yourself to it.maple money Though barriers may sometimes stand in the way of your dreams, remember that your destiny is hiding behind them.wow gold kaufen Accept the fact that not everyone is going to approve of the choices Maple Story Accounts you've made. Have faith in your judgment.wow gold farmen Catch the star that maple story money twinkles in your heart and it will lead you to your destiny's path. Follow that pathway and uncover the sweet sunrises that await you. Take pride in your accomplishments, as they are stepping stones to your dreams. Understand that you may make mistakes, powerlevelbut don't let them discourage you.ms mesos Value your capabilities and talents for they are what make you truly unique. The greatest gifts in life are not purchased, but acquired through hard work and determination.maplestory mesos Find the star that twinkles in your heart?for you alone maplestory powerleveling are capable of making your brightest dreams come true

    By Blogger wow power leveling, at 1/30/2009 8:56 PM  

  • This is the first bit of documentation I have read on Tech 3. I enjoyed this. Its educational.

    By Anonymous Anonymous, at 12/23/2009 1:01 PM  

  • Thank's!!
    I'm now jumping to part2!

    By Blogger Mik, at 1/08/2010 4:12 AM  

  • I definitely enjoying every little bit of it and I have you bookmarked to check out new stuff you post.
    epoxy coatings
    glue removal
    floor levelling
    Polished concrete sydney
    concrete repairs
    concrete coatings

    By Blogger hajjandumrah, at 3/20/2013 3:12 AM  

  • I definitely enjoying every little bit of it and I have you bookmarked to check out new stuff you post."

    POLISHED CONCRETE SYDNEY | CONCRETE RESURFACING SYDNEY

    By Blogger Saif austin, at 9/20/2013 4:06 AM  

Post a Comment

<< Home