buoyexample.txt -- Buoys and setting them up
Written by Jeremy Statz <Terata> -- jstatz@mail.ravensoft.com

If you're reading this, I'm going to assume you've already looked at the map,
gif file, or both.  If you haven't, go check them out quick so you have some
context for what I'm saying.  This also isn't likely to make much sense if
you're not very familiar with Quake engine level editing.  Take a close look at
the map and you can probably figure out how this stuff works on your own.

I recommend also running around in a bit in the example map, and leading the
T'Chekrik around a bit.  You'll find he's capable of opening doors, finding you
anywhere in the maze, jumping through that tube in the north part of the map,
and generally follow you around pretty well.  The maze section of the map has
translucent walls so you can see the monster moving around.

Now brace yourself, this is long and drawn out.  heh

 -- What buoys do --

First thing you probably noticed is that there are a lot of buoys in this map.
This is typical... a good sized single player map could easily have 75-100
buoys scattered throughout.  Don't worry, they don't count as entities in view
or anything like that, so they're not a speed hit as far as that goes.

Buoys basically act as set of markers to help the AI find its way around.
Whenever a monster realizes it can't get to you, it'll look for the closest
buoy, find the closest buoy to the player, then proceed to figure out a path
that'll take it from one to the other.  This path follows the connections made
by the buoys, so how effectively you place the buoys in a map directly
influences how intelligent some of the monsters are going to act.  There are
also triggers that will tell a monster to go to a specific buoy, and you'll
need a good buoy network to make use of these.

 -- How they should be placed --

Buoys should always have a direct line of sight to other buoys.  There are a
few exceptions, but in general you should be able to draw a direct line between
 each buoy and the ones it's connected to.  The sample map follows this.  There
are direct, clear lines of connection between the buoys, and nothing that gets
too close to a wall.  Admittedly the architecture is extremely simple, but the
rules are the same for a real level.

So, assuming there's a clear line of sight along all the connections, we need
room around the buoy itself.  Monsters that are using buoys for pathfinding
need to be able to touch the buoys.  This is how they know they're on the right
track, and decide it's now safe to go after the next buoy in line.  So, buoys
need to be kept close to or on the ground, and out of corners and weird
architecture that might get a monster stuck on its way there.  If you look at
the sample map in a level editor, you'll see that none of the buoys are more
than 16 off the ground.

Buoys use target and targetname like any other entity.  The difference is that
each buoy needs to have a unique targetname... you can't give two buoys the
same targetname without making a mess of the nice clean network we're setting
up.  The problem is, if each buoy needs a different targetname, we can't have
a branch, right?  Because of this, buoys have a "target2" field that lets them
point at more than one other buoy.  If you open the sample map in an editor,
and look at the buoy that's labeled "A" in the gif file, you'll see an example
of this.  The branch that buoy A creates us done via "target" and "target2"
fields.

You've also probably noticed that every buoy in the map is connected somehow.
You should never have buoys or small bunches of buoys standing alone if you can
avoid it.  Obviously if there's some small room or something that monsters
couldn't possibly get out of, that area doesn't need to be connected to the
rest of the buuoy network, but areas like that are usually an exception.

So, in a nutshell... keep buoys away from walls and complex architecture --
they work best in the open.  Make sure there's a clear line of sight between
any connected buoys, that they're not too far from the floor, and that all
buoys are part of the same network.  That basically covers the functionality of
the maze section of the example map.

 -- Buoy flags and fields --

There's a room located at "B" (look at the gif) without any buoys in it.  This
is basically a demonstration... go wake up the T'Chekrik and run over to that
room.  Once he gets to the nearest buoy, he'll find that he can't get to you,
and spend several seconds milling around looking for a way (he may open the
door and wander into the adjoining room, then back out in the process).  Watch
this if you want, then climb out and let the T'Chekcik kill you.  You should
see him pause for a second, then wander somewhere else in the map.  Any buoy-
using monster (everything except rats, harpies, and fish, I believe) will go
into wander mode (the same as setting a "wander" spawnflag on them) and
randomly patrol the map once its target is dead (until it finds something else
to attack, naturally).

Now that I've used three sets of parentheses in a single sentence, let's move
on...

 - Activate

There are a few types of buoys that need special attention.  First is the
Activate flag.  Buoys flagged with Activate are used to let monsters open doors
and use switches and lifts.  These are somewhat complicated, so I recommend
looking in the map file to clarify things.  Take a look at the buoy labeled
"C."

When a buoy is flagged to Activate, any monster that reaches that buoy will
activate the object specified in the "pathtarget" field.  In this case,
pathtarget is "door", which is the targetname of the door blocking the
monsters' way.  So, the monster will open the door when it reaches this buoy.
To prevent the monster from running ahead and bumping into the door while its
opening, the buoy has a "delay" of 0.5 (half a second).  Delay can be used on
any buoy, and simply tells the monster to stand there for that long when they
reach that point.  The other field used on this buoy is "wait", which basically
tells the buoy how long it should be before it allows another monster to try to
use the door again.  In this case, the door opens in about a second and a half,
waits two seconds, then closes in about a second and a half.  (for a total of 5
seconds) So, I've set the wait on the buoy to 5.5 seconds.

 - Oneway

Another flag that's available is the "one way" flag.  This will basically
prevent a monster from following a link to that buoy backwards.  If you look at
buoy C again, you'll see that it has a oneway flag on it, and that there's some
odd linking going on around that door.  There is a reason for this (it prevents
the monster from opening the door twice while walking through it), but that's
not what I'm trying to explain here...

The oneway flag on buoy C basically means that a monster can arrive at that
buoy ONLY if it's coming from buoy X.  If it's coming from buoy Y, it would be
following the connection backward (would be going from a targetname to its
equivelant target), which a oneway flagged buoy won't allow.  This is useful
in situations with doors and lifts (because a monster may have to behave
differently based on the direction its going) or on buoy paths with long jumps
down that a monster wouldn't be able to take back up.

 - Jump

Finally, take a look at the spot labeled D.  This is a raised hole in the wall,
basically, and I want the monster to be able to jump through it.  This is where
the "jump" flag comes into play.  It works pretty much like a trigger_monsterjump,
for those who've been doing this a while.  Basically, you set a "angle" for the
monster to jump at, a "speed" for them to move forward, and a "height" for them
to jump.  A bit of tweaking with these three fields can get a monster to jump
through or into pretty much anything.

Buoys with the jump flag need an additional field called "jumptarget", though.
The monster will only jump if the next buoy in its path has the same targetname 
as the "jumptarget" field does.  That way we keep monster from jumping when
they're going the wrong direction.  The buoy right next to D has a jumptarget
field of "jump1", which matches the targetname of the buoy directly to its west
(the little E).  So, when a monster reaches D, if the next buoy in the path its
taking is E, it'll jump.  Otherwise, it'll just keep walking.