If you appreciate the work done within the wiki, please consider supporting The Cutting Room Floor on Patreon. Thanks for all your support!
Proto:Blood/Alpha Demo/Developer Notes
< Proto:Blood | Alpha Demo
Jump to navigation
Jump to search
This is a sub-page of Proto:Blood/Alpha Demo.
Present in the NOTES folder are several text files that contain developers' notes about various aspects of the game: ARTTASK.TXT, INFO.TXT, MONSTERS.TXT, STYLE.TXT, and WEAPONS.TXT.
In particular, the files GEORGE.TXT and EPIC.TXT are of interest as they detail the company's difficulties in dealing with Ken Silverman (creator of the BUILD engine) and a plan for terminating their business relationship with Apogee Software/3D Realms.
 | To do: BLOODSFX.DOC and IDEASF~1.DOC |
GEORGE.TXT
George: I just got off the phone with Nick, who told me he had passed my previous message about Ken to you. I hope that you understand that I was really just venting at Nick, and I didn't intend that my message be passed on to you, Ken, or his father. There is still, however, a very significant problem we (Q Studios) have in dealing with Ken. Every update Ken makes to his engine turns out to be a major tribulation for us. He regularly makes changes that break our code without any advance warning. He consistently ignores our requests for fixes or suggestions for design strategy. Nick is constantly on me to "Call him. Just get on the phone and talk to him," but to be honest, talking to Ken on the phone is pretty much near the bottom of the list of things I'd like to do with my life. The problem is, he's just so completely unresponsive. I'll ask him a question, and nine out of ten times I'll either get silence or "I don't know" as a response. I know he's highly intelligent, but so are a lot of people I know, and I can TALK to THEM. Okay, so perhaps his personality is a bit different, but he still needs to work WITH us, not AGAINST us. We've had a resource and memory manager in Blood since last year, and it's been working well and is very solid code at this point in time. To get it working back in December though, I had to completely replace parts of the engine, no thanks to Ken. A well designed system would have been built on the ground up from a good memory manager, or at the very least with hooks laid in so it could be developed later. To get our virtual memory system to work with Ken's engine, I had to spend weeks reverse engineering Ken's code, documenting variables, prototyping functions -- all things that Ken himself should have done or provided. Now in June, he hacks in his "group file" system, and says we have to use it. In one sense he's right -- he's hard coded the thing into his engine, and it's broken Blood unless I can figure out which parts of the engine I need to replace. By the time we're done with Blood, we probably won't have any of Ken's engine left... Perhaps you'll want to reconsider the royalties that you are paying him. A few months ago, Ken made a change to the engine that allowed each tile to have its own origin -- a reference point by which it could be positioned. This change was a good one, but there were some problems with the implementation. When the bit was turned on to enable sprites to be centered on their origin, animations bounced, and sprites appeared at the wrong position. It turns out the solution was one of procedure -- by setting the origin at the base for sprites that are supposed to be on the floor, everything appears correctly. Unfortunately, setting the origin for several thousand tiles using Ken's EDITART tool was just a bit too cumbersome for us, so I spent a few days developing a tool that would allow simple tweaking of the tile origins, among other things. This tool is integrated with our new sequence editor, which will be used to create and edit all the actor animations (walking, attack, death, etc.) Everything with this system was going fine until we discovered that Ken has some engine flaws in dealing with sprites that use origin based centering. The clipmove() function doesn't work, and neither does hitscan(). These two functions are pretty much essential to doing anything with the engine. I could rewrite them, of course, but that would be a few days to weeks out of our schedule, depending on how many more bugs and design problems crawl out of the woodwork. We had waited a few months before switching to the new origin based centering, so I was quite surprised to find such fundamental problems with it. We called up Ken and told him about it, and he said he didn't think anyone was using it, but he really didn't know. We asked him to fix it. Tonight I called up Ken because of the group file problems, and because we still don't have a fix for the clipmove() or hitscan() problems. Ken he wasn't going to fix it and we should go back to using the old centering mode. This is totally and completely unacceptable. We've already invested time and effort (need I say money?) into using something, and we're not about to waste more regressing. Ken understands algorithms, and he understands graphics. What he doesn't get is how to design SYSTEMS. Everything he does to the engine is a piecemeal enhancement to something that should have been designed right from the beginning. The memory system is a poignant example of this. It is a hack, like most of his code, and not very robust. From what I've disassembled of the group file code (trying to figure out a way to eliminate or replace it), it too demonstrates plentiful opportunities for crashing the system -- pointers being freed without validation, files being closed without verifying the handle, etc. Our resource and memory manager are quite superior to Ken's (no bragging), so to abandon our body of code would be a step in the wrong direction. When I mentioned to him that our resource manager used an LRU list to handle purging of resources, he said that he didn't understand how they worked and he didn't want to undertake something that complicated. It isn't that complex; it's just outside the realm of Ken's experience. I usually end my phone conversations with Ken with something like the following: "Ken, is there anything I can do, anything I can provide to you, that would help you make these fixes or changes?" The answer is invariably "No." After we hang up, I usually bang my head on the desk for about ten minutes. I've tried to explain to Nick that this is why I don't like to call Ken, but I think he already knows. Tonight I tried to explain to Ken what a library file is. I told him how linkers work, and how they resolve symbol name when producing an executable. I tried to impress on him the benefits of "code granularity" -- breaking a system up into as many small discrete modules as possible so that the linker can efficiently pack only used code into the executable. I informed him about "dead code", and why there was so much of his in Blood. I don't think I made any impression at all. George, I want you to understand one thing. When I ask Ken to make a fix or enhancement, it is most surely something we absolutely need for Blood. I wouldn't force myself to make the phone otherwise. However, everything that I ask for would benefit not only Blood, but EVERY OTHER build project. I've spent enough time as a Project Manager for commercial programming tools that I know what makes a good API, and I know what makes a system extensible. The things I've been asking for are "hooks" so we can implement our own features, not have him do them for us. I sometimes wonder, though, if I'm going against the flow. Perhaps Ken added his cache system in response to other teams request for a memory manager? Maybe the group file code was asked for by the Duke Nukem team? These fears usually turn out to be unfounded, since other teams report similar problems as a result of Ken's "updates." I realize that most of the problems I've been describing with Ken are highly historical in nature, and there's no way to change the past. What can and must be done though is to make Ken more responsive to our needs. He needs to work WITH us, not against us. I don't know why he is so combative, but I can guess -- ego. He probably feels about his code the way a lot of programmers do: it's okay to criticize your own code, but for anyone else to do so is blasphemy. I used to be that way until I realized that a lot of the suggestions people were making to me were actually right.
EPIC.TXT
Termination contract - Release agreement Send them a letter saying why we want out - make it clear that we will no longer continue our business relationship under any circumstances. Try to separate Scott and George from Apogee. Avoid personal attacks. Intro- recieved draft agreement. Doesn't follow intent of agreement. We left higher paying jobs. Apogees priorities changed. We lost creative control, potentional income. We can't work under a situation like this. Points: * stole development teams * quote emails * "mission of Apogee West is to ...." * "all games produced by AWD recieve xx%" * recruited Richard away from us * withdrawn Sonic Holography agreement * Promises about ports to consoles * "Nick met with people from several console platforms - Atari, Goldstar, Sony" * AWD was supposed to receive 70% of console * Apogees failures to produce a Blood contract despite frequent promises * Georges recommendation to defraud IRS Demands: * 35% on sales of ruins * Severence * compensation for amounts that would have been made through ports Conclusion: We want to be fair, we want a clean exit We should to be free to get back on track with the project, but this may not be possible due to the damage you have already caused. We feel that you owe us at least this. Avoid any mention of personality conflicts, i.e. Greg Malone.
ARTTASK.TXT
#: 644-47478 [MAIL]
03-Nov-95 18:13
Sb: Art Task List
Fm: Nick Newhard [Q Studios] 74017,163
To: Peter Freese [Q Studios] 74170,543
Peter,
We've implemented an art task list using the local e-mail system. Please
format any additions you may have and forward them to me. Thanks! (PS. Looks
like Oz hosed this one too. Maybe I should just upload these as files.)
* Before replying to this message, see INSTRUCTIONS, below.
===============================================================================
Status Owner Priority Date Description
===============================================================================
Open thamel *** 11/1 1 ricochet
Open thamel *** 11/1 1.1 water
Open thamel *** 11/1 1.2 mud
Open thamel *** 11/1 1.3 slime
Open thamel *** 11/1 2 character splash (Heretic/Hexen)
Open thamel *** 11/1 2.1 water
Open thamel *** 11/1 2.2 mud
Open thamel *** 11/1 2.3 slime
Open thamel *** 11/1 3 colorize flames on torches to match
new flame
Open **** 11/1 4 cold palette
Open *** 11/1 5 extend leaf anim to 8-10 frames
Open *** 11/1 6 new reflective shots indicator
Open *** 11/1 7 waterfall splash - again
Open thamel *** 11/1 8 re-colorize #512 (Haven stone)
Open *** 11/1 9 blown out masked bars
Open *** 11/1 10 metal shrapnel blown out masked bars
Open *** 11/1 11 wood overhaul
Open *** 11/1 12 lava lit from below textures
Open *** 11/1 12.1 dungeon set
Open *** 11/1 13 smoother cultist swimming anim - look
at Duke's
Open *** 11/1 14 better cultist crouching anim
Open thamel ** 11/1 15 tatter ghost cloak
** 11/3 Adjust extents for all beast art so
that the origin remains fixed relative
to the bottom of each tile. This will
fix the problem of the beast z bounce
while walking/running.
*** 11/3 Ricochet art and sequence for ALL
surface types. Even if we reuse some
of the art and sequences, it needs to
be defined what and how.
** 11/3 Make new fire CLU. This may require a
new fire PAL that uses colors closer
to the new blood palette to prevent
gradient jumping.
** 11/3 Tumbling art for all debris and gibs.
** 11/3 Debris: stone, glass, wood.
===============================================================================
Legend:
===============================================================================
Status:
Open = Work In Progress
Done = Done
Cancelled = Cancelled
Hold = On hold (see notes *)
Pending = Needs some other item completed first (see notes *)
-------------------------------------------------------------------------------
Owner:
thamel = that oatmeal and fruit guy
kkilstrom = that poop guy
-------------------------------------------------------------------------------
Priority:
****** = I'm an anus-sniffer and can't use legends.
***** = Must be done ASAFP and will be an immediate art update
**** = Get it done before next art update
*** = Soon, but higher priority items must be done first.
** = Must be done for game, but can wait until later.
* = Could be done later, may not make it to game.
===============================================================================
INFO.TXT
A general description of the game.
Blood -- an action 3D horror game that pits your wits and skill against the undead denizens of several ghastly worlds. Armed with only makeshift weapons and a surprise biological embellishment, you are the lone instrument of destruction for the Secret Society, and must eliminate the threat posed by the Cabal, a dangerous cult movement, which is even now enabling the entrance of Tchernobog, The Dark God, into your world. Blood features an advanced 3D (Doom style) rendering engine which allows 5 DOF, stacked sectors, bridges, dynamic lighting effects, translucency, dynamic textures, shadows, and realistic physics. Even the frame rate won't disappoint you. :-) What's the play like? Use your pitchfork to keep those pesky foes out of your personal space! Throw a bundle of TNT into that gaggle of gargoyles and watch the body parts go flying (just don't get hit by that chunk of flesh -- eww!) Flame the phantasm with your ad hoc flame thrower (you knew that lighter would come in handy). Just watch out for the guy on the ledge above you who's pushing that barrel of explosives... Blood also features some fiendishly clever traps and puzzles, some of which can only be solved by cooperating in network play. There are combination locks, multi-way doors, underwater areas, and even huge moving rooms. Blood is being developed by Q Studios, and will be published by Apogee/3D Realms and Formgen. Expected release date: Winter 95.
MONSTERS.TXT
Discussion between team members on the various enemies of the game. An "Earth Zombie" enemy is mentioned, which didn't make it into the final game.
My comments added. The following notice is meant to open a discussion on what the monsters can dish out as well as take. ============================================================== THE CULTIST Jay: I like the AI, but these guys are a little too tough. I see them being about as tough as an Imp in Doom, taken down by a well placed shot from a single barrel of the shotgun. We know how much damage they should do since they use the same weapons as the player. I think they throw off a little too much ammo right now. I think they should have an equal chance of dropping a few bullets or nothing at all, and then drop a lot of ammo less frequently, and finally drop an actual weapon least frequently of all. Peter: The shotgun cultists are really tough. The ones you level designers have been placing behind every door have been blasting my brains out without mercy. I agree that they should be a little easier to kill. ============================================================== AXE ZOMBIE Jay: Since this guy doesn't have a ranged attack he should be able to reach the player. He should probably be able to take both barrels (Kevin takes both barrels) of the shotgun dead on before he falls, and he should run pretty fast (faster than he runs now). I'd like to see the getting back up thing put in soon so we can play around with how to do that. I think it should be random, say a third of the time or so his head pops off. Peter: If we speed up his movement, we'll also need to modify his sequence. Right now, he looks like he's skating if we increase his speed. ============================================================== EARTH ZOMBIE Jay: Is the only difference the fact that this joker comes up out of the ground? I thought we were going to have it do some different stuff? ============================================================== FAT ZOMBIE Jay: The Fat Zombie should be able to take about the same amount of damage as the Axe Zombie, but since he is so slow we should give him a distance attack. I think the puke idea is cool, but he should projectile puke in a limited arc with a max range (like the tnt sticks but with maybe a little less range). It would be cool if the puke smoked when it hit whatever it's target is (or even just the ground). I like the idea of him throwing off a hellhand every now and then. ============================================================== GARGOYLE Jay: This guy should be as tough as nails. He should be about a little tougher than Doom's cacodemon, but not as tough as a Baron, and do comparable damage (maybe a little more damage than he does now). ============================================================== STONE GARGOYLE Jay: I think this guy should take even more damage than the regular Gargoyle. We were talking about having him be immune to certain weapons as well. I think if we are going to make him that different from the regular gargoyle he should look different somehow. Maybe if he had a greyish tinge to him or was completely grey, otherwise he shouldn't be different than a normal gargoyle. I'd also like to see him throw something different to make him more powerful, like the trademark ball of energy that does more damage than the bone. Peter: The stone gargoyle should already be using the gray palookup. Isn't it working? Note: unique palookups can NOT be used in fog levels. ============================================================== HELL HOUND Jay: A little weaker than a Cacodemon. He should be able to take some damage, but not like what the gargoyle can. I don't remember what he is supposed to do attack-wise. ============================================================== PHANTASM Jay: I think his health is just about right. What weapons will effect him and when? ============================================================== GILLBEAST ============================================================== BONE EEL ============================================================== HELLHAND ============================================================== BAT ============================================================== RAT ============================================================== SPIDERS Jay: I don't think we should go overboard with the pallette look-ups here. I've always kind of thought games that used Pallette look-ups for new characters were kind of cheap. We don't really do that since our pallette look-ups are mainly to distinguish a slightly different version of an already existing character, but I think we can still take it too far. What are the different spider types supposed to do? I think the big mother spider should be huge, I mean the size of the Hell Hound or even a little bigger. That would truly be a frightening sight. Please! Make it so! Peter: I'm not sure if the sizes of the spiders in MapEdit accurately reflects their size in the game. Anyone? ============================================================== SKELETONS I'd like to see a skeleton creature, kind of like a mini-Tchernobog devotee, but not Tchernobog. This thing would be a good size and would be about as tough as a Baron in Doom, throwing powerful balls of energy. When he gets shot bone fragments would fly off, possibly even damaging the player a little. I know it will never happen, but it's what I want, oh well. Peter: Blood II. ============================================================== CERBERUS ============================================================== TCHERNOBOG
WEAPONS.TXT
Discussion between team members on the player's weapons.
I've added my comments. 'Hope it isn't too hard to merge them in. ======================================================================== BLOODY WEAPONS Jay: It seems like something is missing. I think we need a low power long range weapon (like a pistol), and one of the weapons just needs to be awesome in power, appearance, and effect (the flare gun if that is possible) without costing the player a lot to use it (like the shadow gun does). Jay: I like the order that the weapons come in. If I were to change it I would put a weapon in between the pitchfork and spray can that does little damage but is still effective at a long range. Jay: The Guns Akimbo Power-up could be used to increase most of the weapons rate of fire instead of just giving you an extra shotgun to play around with, or we could create a new power up to do this. (increasing the rate of fire for weapons is one of the most popular modifications created by Dehacked for Doom, why not give the players what they want within the game itself. I think a cool effect like that can throw realism out the door and the player will still love you for it. I would.) I would like to see the dual shotgun power-up not be such a short-lived thing. It is just too cool. I think we should consider this as an actual weapon option and not just a temporary power up. Peter: I've made an important change to the way the auto-aiming works. You may love it, you may hate it. I'm commenting about it here because I'm sure it merits your discussion. Specifically, the auto-aim point does not track instantly, but sort of 'homes in' on a target. If your target is standing still and so are you, you should hit your target dead on. If your target is running a serpentine pattern you may miss him a bit unless you do a little bit of targeting yourself. The rate at which the auto-aim homes in is adjustable in the code. For some weapons, such as the tommy gun, the auto-aim point gets updated while you are firing. For others, such as the sawed-off, it doesn't. What this means is that you will get a more accurate shot with the sawed-off if you wait a tiny bit between each shot rather than just holding down the fire key. If you like the way this works, but want to visually see how the auto-aim point is tracking (for tuning, not for actual game release), I could add some sort of reticle. ======================================================================== PITCHFORK Jay: The range of this weapon needs to be extended. You shouldn't have to be right on top of somebody to hit them, even if this were realistic (like with a punch), it is not playable. Hexen is the first game that I've seen that really fixed this. The close range attacks of the fighter in Hexen have a good playable range, his punch looks like it goes too far, but it also makes his punch playable, which I think is much more important. With the pitchfork we have an excuse since it is about five or six feet long. Jay: I like the range now. Jay: What if we gave it some kind of power up that electrified it. When it hit someone arcs of electricity would course around the opponent, damaging them and temporarily freezing them in place. Terry-This is a cool idea. It could be as if you had a device that charges you, but the pitchfork acts as a lightning rod, attracting the energy to the tindels. Although you couldn't shoot the arc out, it's range could be extended and it be very dangerous. The victim would have a hard time getting out of the shock, kinda like DOOM's chainsaw. Kev-I like this idea Jay: I still really like this idea. Jay: The pitchfork should probably take 3 or 4 hits to take down a cultist (see monster comments to see how much damage a cultist should probably be able to take). ======================================================================== SPRAY CAN Jay: This weapon is pretty good. It is very hard to see anything when you are using it, and the fact that you have to use it in close quarters doesn't help, but it is more the nature of the weapon. I don't know how its damage works, but it should have a pretty wide cone of effect so that when you are in close it is hard to get away from. Jay: This weapon needs to be changed to truly be effective. It has two big disadvantages: short range, and it limits your vision. To make up for this the spray can needs to pack quite a punch. The way I'd like to see it do damage is it should do a ton of damage that decreases with distance within the cone of flame. At this point it seems like the flame will only do damage if the target is directly in front of you, but the flame has a wide cone and it should burn as soon as the target is hit. (BTW, I realize that the spray can does burn time, and not actual damage, but it is just easier for me to say damage). A cultist should be running around on fire almost immediately, otherwise why even bother with this weapon. You can use the Pitchfork instead and gain the advantage of vision as well. If you can get close enough to hit the cultist with this weapon without getting cut down by him or his friends than you should get the payoff of taking him out. Jay: When I was a kid there was always this myth about spray cans exploding if you used them like a flamethrower, what if we used the alternate fire key to allow you to light the nozzle on fire and throw the entire can. It would explode on impact using several explosions that expand out from a point (like that bomb missile gun from ROTT). The explosions themselves would do ok damage, but the nasty part would be that it would act like napalm, setting everything around it on long burning fire. This weapon would be balanced by the fact that it uses an entire spray can and would be incredibly dangerous to use since it would have such a large blast area. Terry-Totally cool. I second this motion. Kinda like a bundle of dynamite. Jay: Thanks! I'd like to see it have an even greater area of impact than the bundle of dynamite though, but do less short term and more long term damage. Kev-I like this, too. It wouldn't take much new art, probably just one frame for the qav and a rotating spraycan seq. Jay: I'm still really big on this one. I think it is one of the better weapon ideas. I think the area of effect should be pretty large (many explosions expanding out from ground zero), but the explosions should not do damage but rather effect burn time. I don't see any reason why the spray can graffiti can't still be an option, just hit the key for the spray can again to make the lighter go away, and there you go. Peter: Adding a radius explosion that burns everything shouldn't be too hard to program. I'm for this. ======================================================================== TNT Jay: Ouch. It's almost impossible to hit anything with these which makes this an unlikely weapon to use. It's cool looking, but not functional. I think the problem is with the way that it is thrown. Nobody throws dynamite and grenades underhanded in an arc unless they are aiming for a distant immobile target. I think the way that we could solve this would be to have the dynamite thrown overhanded, like someone would throw a knife, directly at the target. We could use the proximity detectors to allow the dynamite to go off on contact. This could be the dynamite's alt. fire mode, allowing for more accurate and dangerous throws with a loss of distance, we could also increase the range of the underhanded throw to counter balance the two modes. Jay: I still feel this way. I realize that we can't change the art but something needs to be done or this is doomed (no pun intended) to be the weapon that is never used. I've given up ever trying to hit anything with this weapon. I won't repeat my suggestions to improve this one since they are already here, and still apply. Terry: Agreed. I think that your strafing velocity and angle should NOT be added to the throw, because then you'll never be able to hit yor target when circling them. Jay: Amen Brother!!! Terry: Another way to account for distance would be to implement the way Dark Forces handles thermal detonators: the longer you hold down the mouse button, the further you'll throw it. Of course, if you wait too long, it'll blow up in your hand, ignting your inventory and taking you with it. Terry: I had a dream. Actually, I did. The cultists were throwing sticks of dynamite overhanded, so I gotta go with my subconscious. I'd like to see it changed to over instead of under. Would there be a reason for keeping under if there were an over? Will the cultists have a delay time like the player for switching to dynamite from their preferred weapon? Kev-The problem I have with changing the throwing from under to over is that it will require all new art. First of all, I would have to redigitize the cultist doing an overhand throw, which is very difficult due to the way the figure is made which is why I made him throw underhand in the first place. This includes touching up the frames and remaping him again. Second we would have to do an overhand throw for the players view and clean those frames. If we want the dynamite to travel faster or be more accurate why don't we try changing the angle that it's Jay: I, of course, agree with this, but I would be happy if you could throw in a much lower arc that travelled directly at a target (like an overhand throw would). Peter: Here's what's about to be added: Throwing of stick or bundle. Bundles should do a much larger radius of damage, so that should take care of the accuracy a bit. You'll be able to hold the stick in your hand until it blows up, so you can "burn-off" the TNT if you want. You'll be able to control how hard you throw it a la Dark Forces. You'll be able to drop/throw the sticks with the fire/alt fire keys. When you throw proximity bundles, they will explode on impact. When you drop (place) proximity bundles, they will arm in 5 seconds, so you should definitely leave the area. You'll be able to place multiple bundles to be triggered with the remote detonator. ======================================================================== FLARE GUN Jay: This weapon has to be our powerhouse. It doesn't look very impressive so it needs to have some big and spectacular effects. The bigger and more powerful the better. If I thought we could do it I would even suggest changing the flare gun completely to a much more impressive and faster firing weapon (like the rotating gas cannister gun in Terminator 2, imagine this thing throwing off flares at high speed!). Jay: Needs more starting ammo. I like the ideas we spoke about for this one, the napalm, star, and explosive flares, and once the auto-aiming for it is in I think this could be the weapon to have. Jay: Electric flares that freeze the target like a tazer (see Pitchfork). Terry-How about heat seeking flares? Like DOOM2 dudes, except these won't smash into you, they'll STICK into you and burn you out. Kinda like me. hahahaha Kev-I like both of these ideas. Maybe we should replace the old flaregun powerups with these. Jay: I don't really like the idea of heat-see Peter: Having more than one type of ammo per weapon is to be avoided according to the powers that be at Apogee. Two is pushing it, three is right out, and we're already complicating things with all the TNT options. Is there anything we can do with the existing ammo or fire modes without adding new ammo types? I think one shot with the flare gun should be enough to cause burning death in all but the most hardy creatures.
STYLE.TXT
==============================================================================
Programming Style Standards
Copyright (c) 1995 Q Studios Corporation
Contact: Peter Freese, CIS:74170,543
Last updated: 95/02/25
==============================================================================
This document provides standards for a uniform programming style to be used
in all Q Studios source code. This document is NOT meant to be an absolute
set of rule to be followed -- it is a collection of recommendations based on
the need for code to be readable, maintainable, and less susceptible to
error. The recommendations in this file apply specifically to C/C++.
COMMENTS
Each file should begin with a comment block of the following form:
/*****************************************************************************
FILE: MISC.H
DESCRIPTION: This header file contains prototypes and inline
declarations for miscellaneous utility functions which
don't fall into any particular category or subsystem.
AUTHOR: Peter M. Freese
CREATED: 95/02/01
COPYRIGHT: Copyright (c) 1995 Q Studios Corporation
*****************************************************************************/
Each function should be prefaced by a comment block of the following form:
/*****************************************************************************
FUNCTION: FindClosestColor()
DESCRIPTION: Finds the palette entry that most closely matches the
specified rgb value.
PARAMETERS: r, g, b are the DAC values to search for.
RETURNS: A palette index in the range 0 to 255.
NOTES: The global variable palette[] must already be
initialized.
*****************************************************************************/
Unused sections in the comment block may be omitted, e.g., void
functions do not need the RETURNS sections. The NOTES section should
describe any function side effects or prerequisites.
Comments should be used liberally throughout source code. C++ style //
comments are preferred for single line comments. If multiple line comments
are necessary, then use C style /* */ comment blocks. Avoid using visual
decoration such as '*' in the first column, since it makes text reformatting
difficult.
Comment blocks should be no wider than 80 characters. I have created
MultiEdit macros for automatically building the various types of comment
blocks.
NAMING CONVENTIONS
Variable prefixes:
a Array
b Boolean
c Char
g Global
i Integer
k Constant
l Long
p Pointer
s String
Function names should use mixed case and should 'read' well. This is best
accomplished by using a verb or verb and subject in the function name.
Examples of good function names are IsNumber(), ScrollScreen(), and
SpawnMissile(). Examples of bad function names are strncmpl(), neartag(),
and clockdir().
Aggragate types (structures, unions, and typedefs) should be declared in all
caps to distinguish them from variable and function names.
Functions which form a subsystem should all be prefaced by a 3 or 4 letter
lowercase abbreviation. This classification provides an explicit scope
and association for the function name. For example, it is obvious that
tioInit(), tioTerm(), and tioCursorOn() are all part of the same subsystem.
HEADER FILES
Every module should have it's own header file, and every exported variable,
function, or class should be prototyped in the header.
File wide variables and functions which are not explicitly exported
should be declared as static.
Header files should make use of exclusions to ensure that they are not
processed multiple times. This is accomplished as follows:
#ifndef __FILENAME_H
#define __FILENAME_H
.
. body of header file here
.
#endif
ASSERTIONS
FORMATTING
Everyone seems to have different ideas about what is best to use for tab
stops. In my programming career, I have use 2, 3, 4, 5, and 8. For C files,
I have settled on using tab stops of 4. Four is a nice binary number, and it
conveys indenting clearly without overdoing it. One argument against using
tab stops of 4 is that you can only indent half as many times as you can with
2 before running out of room. I say you shouldn't be indenting that much
anyway. If you need to nest conditionals 5 or 6 levels deep, you should
consider rewriting your function.
Opening and closing braces should align vertically, and should appear on
lines by themselves (with the exception of the do while construct. The
whitespace provided by the braces lessons the density of information, and
makes for easier reading. Blank lines should also be used to provided
visual separation between sub tasks.
Use 2 blank lines between the end of one function and the opening comment
block of another.
Here's a function example of coding style:
void InitControls( void )
{
for (int i = 0; i < kMaxControls; i++)
{
char *p = iniGetKeyString("BLOOD.INI", "Keys", conInfo[i].iniKey, NULL);
if ( p == NULL || *p == '\0' )
{
control[i] = &keystatus[conInfo[i].default];
}
else
{
long lScanId = strtoul(p, NULL, 16);
if ( lScanId == ULONG_MAX || lScanId > 255 )
lScanId = conInfo[i].default;
control[i] = &keystatus[lScanId];
}
}
}
