    All Packages  Class Hierarchy  Index

#

# Q2Java API Users's Guide v0.7

These are the JavaDocs for the Q2Java Interface and sample game classes. There are some gaps in the documentation, but hopefully they'll be filled in as time goes by. There should be enough here to give a good overview of the structure of the code.

## Name Changes

Since this is pretty much a rewrite of the original Quake II game code, I took some liberties changing the names of functions and fields. The Coding Conventions section below lists the stylistic changes made, but a few other major ones are:

- In the C code, the terms "player", "user", and "client" all mean pretty much the same thing. The Java code sticks to the term "player", so the equivalent to the `ClientThink()` function is named `playerThink()`, and the `usercmd_t` structure's Java equivalent is named `PlayerCmd`, and so on.
- In the C code, the terms "edict" and "entity" seem to mean the same thing. Q2Java sticks to the term "entity" (according to the dictionary, an edict is "a proclamation having the force of law" - kind of a strange thing to call a datastructure)
- The C `SpawnEntities()` function is renamed to `Game.startLevel()`, which seemed more descriptive of its actual significance.
- Many other C function names have been Java-ized by prefixing the names with "get" or "set" as in: `getSoundIndex()` instead of `soundindex()`, and `setConfigString()` instead of `configstring()`.

## Coding Conventions

The coding conventions used in the Q2Java packages are generally based on the way Sun does things, with a little bit of Taligent and Netscape conventions thrown in too.

- Package names are all lowercase, such as: `q2java`
- Class names begin with an uppercase character, have mixed case and no underscores, such as: `TraceResults`. (The classes in the `baseq2.spawn` package are an exception, they're named to match the entity classes found in maps)
- Method names begin with a lowercase character, have mixed case and no underscores, such as: `getPlayerKickAngles()`. (The `Player` class is an exception, in that methods to handle player commands are all lowercase and start with `cmd_`)
- Instance fields begin with a lowercase "`f`", have mixed case and no underscores, such as `fTargetGroup`. This makes it easy to distinguish object fields from automatic variables that will go away when a block is exited.
- Static fields begin with a lowercase "`g`", have mixed case and no underscores, such as: `gGameTime`.
- Constants (final statics) are all uppercase, with underscores used to separate words, such as: `DAMAGE_NO_KNOCKBACK`.

Throughout the code, I used the indentation style where the opening and closing brackets in a block are both indented, such as:

    while (true)
        {
        foo(a);
        bar(b);
        }

I realize that there are other styles more commonly used, but I'd ask that you don't mix styles within a single file - as Netscape says in their Java coding guidelines:

> When you pick a style, stick to it. When editing another person's code, respect the code, copy the style. (When in Rome, do as the Romans do).

Unfortunately, the overall indentation of the source files is a bit whacked because I used IBM's VisualAge for Java - and when it exports source code, it's not so smart about it. Sorry about that - maybe I can get something to fix it up for later versions.

Barry Pederson <bpederson@geocities.com>