QuakeC Specs v1.0

[DarkSnow]

#1, Who were the original autors of the QC Specs? (anybody)

#2, I have cleaned up the specs and converted it to windows helpfile (.chm), any comments would be nice.

http://darksnow.quakedev.com/downloads/qcspecs.rar

[MauveBib]

There are a lot of mistakes in the QC Manual, I suggest you check out the quake wiki for more accurate, uptodate function definitions etc.

[Lardarse]

Great idea!

Idea for a future version: include information about the extension system.

LA

[DarkSnow]

Thanks for both the comments.

As of right now the chm only contains the specifics from qc specs. I thought it would be good to have as a basis to start from.

Populating it with better definitions from the wiki is a great idea, thanks.

In the future i will include documentation on the extensions aswell, la - thanks for bringning it up.

_____

Is the layout done well? Or are there some parts whitch needs improvement?

I think its easier to read/nav in the chm compared to the web specs, but i still think it could be better. Im open for any suggestions.

[leileilol]

ew chm

[Error]

would have been nice to have a HTML version for Inside3D

pretty damn cool

[DarkSnow]

would have been nice to have a HTML version for Inside3D

pretty damn cool

Thanks.

Since chm basicly is a compiled compressed form of html files, its not hard to make a plain html conversion - since all the work is already done.

Only problem would be that you'l miss the search functions that chm provides.


http://darksnow.quakedev.com/downloads/qcwebspecs.rar
Inside3d and anyone who would like to may use this in any way possible.

[Error]

posted on main site

soon to be integrated

[DarkSnow]

Cool

[FrikaC]

I have heaps of complaints toward the authors of every QuakeC guide to date. Here's just a sampling of what is wrong with QuakeC specs.

1.1 Comments names and types

"Those comments are the same as in C++ (and many C languages)."

This would be better phrased "This comment syntax is the same as C and many other C or C based languages."

It's obvious the author favors C++ by his comments, to the point of making awkward and ambiguous phrases to compare QuakeC to C++.

"Let's start with the bad news: it is impossible, in Quake-C, to define new types. That means for instance that you cannot create a type named ammo, derived from float, that will only be used to store ammo count. So much for the clean programming habits."

This is condescending bullshit, as it's not "bad news". If you've gone through some people's source code as I have, redefining types can be a headache. Yes, it's useful in a few, rare circumstances, but with preqcc and modern compilers it's not "impossible" either. "Clean programming habits"? There are clean programming habits for every language. QuakeC is no different, and it's lack of typedef or such features don't completely destroy programming habits. It would be better to say:

"QuakeC is strongly typed and allows for no means to alias or subclass types. For example you cannot create a type named ammo derived from float that will only be used to store an ammo count."

"It is often convenient, in C (or C++), to create new structures (or Objects, or record) to store a few related information at the same place. For instance, you may wish to use a single structure to store all the ammo count of the player, and also the current selected weapon, since that information are obviously related to each other.

Though both entity and vector are obviously structured types, it is impossible to create new structured types of that kind, in Quake-C. However, the entity type can be modified to suit some of your needs."

If you're well familiarized with C or C++, then yeah, you know that a vector is 'obviously' a structured type. But it is a language feature more than a structure. I think as an introduction to the QC language these paragraphs are completely out of place. They explain, once again, how QC differs from C++. However, this may need to be said for people coming from C/C++ so a better and less condescending rephrase:

"It is often conveinant, in C o C++, to create new structures (called Objects or records in other languages) to store related information in the same place. QuakeC does not provide this functionality, however, the basic entity type can be expanded with new fields."

Simpler too, we don't need a tutorial on C++ here.

1.2 Definition of Variables

"where type is one of the pre-defined simple types."

Perhaps a quick list of the simple types should have been included in this statement: float, vector, entity, string, void

"There are two levels of scoping. By default all variables are global: they can be accessed by any functions, and they are shared by all the functions (and all the clients of a given network server, of course)."

By default? How about:

"There are type types of scoping, when placed outside a function, variables are considered global. They can be accessed within any function, and are shared by all functions, even across files."

The addendum "(and all the clients of a given network server, of course)" is completely bogus. Variables are not shared with clients, because clients do not run QuakeC.

But inside the functions, using the keyword local just before the declaration of a variable, you can make this variable visible only the the function itself (i.e. it will be allocated on the stack).

This is somewhat confusing to a newb. It might be better to say (instead of just saying 'it goes on the stack', actually attempting to explain what that means):

"The second type of scope is the local scope. Variables declared within a function (by prefixing them with the local keyword) are instead only accessible to the function they are declared in. The state of these local variables are stored off upon each function call, so that recalling the same function will not alter the local variables of a previous call to that function."

Note that though it looks like a definition of variable, with a default initial value, is is totally different. There is no memory reserved for constants, and they are not saved to game files (only regular variables are).

To make matters worse, if you use a constant like a variable, and try to affect a new value to it... well, it's very likely that you will cause troubles to the program (malfunctions, or crashes). So never modify the value of a constant.

Again, assuming you're proficient with C/C++, this makes complete sense, but I'd rather not assume this. "There is no memory reserved for constants" is wrong. How about:

"To someone proficient with C/C++, that may look like the definition of a variable with a default value, however, in QuakeC this is the definition of a constant. Constants are merged with other constants of the same value, as such, if you accidently change a constant, it will result in odd game behavior. Never assign new values to constants. Constants are not saved to game saves, only regular variables are."

I'm too tired to go through the rest of the specs now. I may post a follow up, but as you can see I've always disliked how this documentation is worded. There are many many errors in it also.

[FrikaC]

Continued...

1.3 Operations

Operations on floats or integer

This heading is wrong or misleading. There's no integer type in QuakeC. A better title would have been "Operations on floats or vectors", however, divide (/) is not available on vectors, and one should note that vector * vector yields the dot product.

He goes on to direntiated integers from floats by making not that a float values is truncated when used in a logic operation.

1.4 Definition of Functions

It is strictly equivalent to:

This is nitpicky, but strictly equivalent means more than merely functionally identical, it means it is a 1:1 replacement. OP_STATE is not a 1:1 replacement to the example code. as using a state macro is far faster and more compact.

1.5 Loop and conditions

This, again is nitpicky, but most of my response to this file is that. There's no description whatsoever as to what any of this is.

2.1 The Simple Types

I don't like his description of the Entity type, and it appears throughout the document, but he treats the entity less like what it is, a pointer and more like it's some kind of struct. I don't know what I'd rather do here.


And so on...

[Lardarse]

Have you guys seen this?

http://www.gue-tech.org/quake/qcrm/index.html

[DarkSnow]

Have you guys seen this?

http://www.gue-tech.org/quake/qcrm/index.html

Sweet, i missed that one

[FrikaC]

There's more than a few errors in that also, but I'm too lazy to go looking for them currently.