P.O.T Entity usage tutorial.

Here's the table of contents:

1 - Introduction
    1.1 - What you need to know before you start

2 - Setting up the basic turret
    2.1 - Setting up movement axis and speed
          2.1.1 - Acceleration
    2.2 - Using max/min angle limits
    2.3 - control
    2.4 - snaping

3 - Firing
    3.1 - setting up a firing turret
    3.2 - using different kinds of ammo
    3.3 - firing fields
    3.4 - firing delay
    3.5 - offsets

4 - Specials
    4.1 - laser sight setup
    4.2 - range finder setup
    4.3 - zoom
    4.4 - custom viewheight
    4.5 - doors
          4.51 - disapearing doors
  


1 - Introduction

        This entity will enable you to create player operated turrets or P.O.T.'s but
    first you are going to need some stuff:

              The modified DLL
              A Q2 map editor
              And of course some minimum knowledge of q2 maping

    1.1 - What you need to know
  
             You got to have some knowledge of the rotating entities in Q2. I suggest
          you visit R.U.S.T.(www.gamedesign.com) for any turoials you need.

             Also you got to know what you are making and plan some stuff out before
          you start with this stuff.

2 - Setting up a basic turret

       Well after you got all your brushes how you want them you got to sperate them
    into parts. What i mean is that the base and breach of the turrets will be two
    seperate turret entities. Also the firing, snaping, door entities will be seperate.
    Don't forget tp give the turret entity an origin just like you would for a 
    func_roating except for the spawnflags.

    2.1 - Setting up movement axis and speed

          Lets say you got a small platform with what looks like a barel infront of it and
       you want to be able to plug in and fire some stuff. What you got to do first is
       take all the brushes and make them into an entity with a classname of turret.
       Now what you got to do is set up a general axis around which all the parts of the
       turret will travel. Lets say that you want the whole thing to rotate on the z axis or
       the YAW axis and just the barel to be able to pitched up and down on the Y AXIS or PITCH
       AXIS. Well for that you got to have a field/key pair. The field is called: OAXIS. This
       Will deside which parts will travel on which axis.

       Here is the list of all possible OAXIS keys:
   
            oaxis 1   This is to for the turret to be able to travel on all possible axis
            oaxis 2   X and Y axis only. This means that the turret would only pitch and roll
            oaxis 3   X and Z axis only. This means that the turret would only ROLL and YAW
            oaxis 4   Z and Y axis only. YAW and PITCH, this is mostly used for barels
            oaxis 5   X only, ROLL
            oaxis 6   Y only, PITCH
            oaxis 7   Z only, YAW

      For out platform we will use oaxis 7 since the whole thing whould only travel on
      its Z AXIS.

      Now we know that we want the barel to travel on the Z and Y axis so you should seperate
      the barel from the main entity and make it a turret and give it a oaxis of 4 since we
      want PITCH and YAW.
 
      Now we got 2 seperate entities with seperate oaxis fields.

      We need to move them so you should give both of them a speed of, lets say, 40.
      This means 4 units per cycle. All the turret entities of one turret should have
      the same speed. You don't want your barel to travel faster than the platform
      when turning. Now that you got the axis set up lets set up the min/max angles.

      2.1.1 - Acceleration
  
              Now that you have the speed set up you could make use the acceleration
              feature. You don't have to use this but its good if you want your
              turrets to be fast while still being accurate.

              Acceleration work like this:

                  First you have to give your turret entities an accel key
                  and give it a value of how fast you want it to accelerate.
                  For our eaxple we will use 4. This means that the turret
                  will move 4 degrees per cycle and reach its top speed of 40
                  after one second. The formula is like this:
               
                            top speed in = speed / accel * 10

                  So let review: the accel key is how many degrees the turret
                  will travel per cycle(0.1 seconds) untill it reaches its
                  top speed figured out by the fomrula above.
              
    2.2 - Using Max/min angles

      This is hard to get to read carefully.

      From the exaple i used you should have two turret entities: one with oaxis 4 and
      the other with oaxis 7. Both with the same speed.

      Now we need the angle limits. This forces you to build all of your turrets at
      0 pitch and toward angle 0 on the top view.

      The angle limits go like this:

          maxtyaw - maximum yaw angle of travel, usualy 360 or a mulitple of it. Z AXIS.
          maxtpitch - maximum pitch angle of travel, usualy 90 or so. Y AXIS.
          maxtbank - maximum roll angle of travel, usualy 90 or so. X AXIS.

          mintyaw - minimum yaw angle of travel, usualy -360 or a mulitple of it. Z AXIS.
          mintpitch - minimum pitch angle of travel, usualy -90 or so. Y AXIS.
          minxtbank - minimum roll angle of travel, usualy -90 or so. X AXIS.
           

      Usualy the max's are positive and min's negative.
 
      Now the platform with the oaxis of 7 should have a maxtyaw and mintyaw. Let say the max
      is 360 and min -360. It doesn't need much else.

      The one with oaxis of 4 will need a maxtpitch and muntpitch. Let say the max is 90
      and min is -90.

      You are done with angles. Now to the control.

    2.3 - Control
      
      All turrets must have a control entity otherwise you would not be able to
      turn them on.

      A control entity is an entity with the field control set to 1. It could be a
      func_wall or one of the turret entities themselves. Whatever you chose for
      a control entity you must give it a range field. Like a range of 150.

      If the player is 50 units from the control he/she can control turrets up to the
      range specified by the control.

      For out example lets use the main platform as a control. So give the turret entity
      a control of 1 and range of whatever you need to be able to control the turrets.

    2.4 - Snaping

      Snaping is kind of difficult but its a good way to keep the player from running out
      of your turret while its on.

      A snapping entity is a regular turret entity with a turtype field of 2. It must have a 
      target that points to an info_notnull. You should place the notnull where
      you want the player's origin to be when the turret is on. The origin moves as the
      turret does.

      For our example lets take a small part of the barel and seperate it from the barel
      turret entity. Give it the same values as the barel turret entity(same oaxis, min/max,
      speed). Now give it a turtype of 2 and a target of exsnap.

      Now place a notnull about 30 units above the top of the platform and give it a 
      targetname of exsnap.

      You take a part of the barel because you want the player's view to pitch down as the
      barel does, if not use part of the platform.

      There is a field of snapa that lets you select which axis you want the origin and
      model angles snaped. What i mean is you can select which axis the origin will be moved
      around with the turret and which of the turret angles you use for model angles.

      snapa works just like spawnflags.

            Here are all possible snapa keys:

                 snapa 1 - Z AXIS
                 snapa 2 - Y AXIS
                 snapa 3 - Z and Y AXIS
                 snapa 4 - X AXIS
                 snapa 5 - X and Z AXIS
                 snapa 6 - X and Y AXIS
                 snapa 7 - X,Y,Z AXIS
       

      For the example we will use a snapa of 1, only Z AXIS.
             
      Now you got a snaping entity now.


    Now you got a platform with 3 seperate turret entities(one main/control, one barrel,
    and one snaping). This is VERY important so excuse my use of capitals.

    EVERY TURRET ENTITY IN A LEVEL MUST HAVE A UNIQUE TARGETNAME.

    You are now ready to setup the firing of the turret.


3 - Firing

    This is a very flexible part of the entity, I will explain how you can fire
    any of the q2 weapons at any speed with any damage.

    3.1 - setting up a firing turret

          To set up a firing turret you have to give one of your turret entities a couple
          of field/key pairs. The most important of these is: target.

          Every firing turret entity must have this filed in order to know
          where the shot should come from. You should target it to an info_notnull
          which you place in the map in the place you want the shot to come from.

    3.2 - Using different kinds of ammo

          The field for this is fire.

          This only changes what is fired not the rate or speed.

          Here's a list:
      
                 fire 1 - blaster shots with trails
                 fire 2 - shotgun blast
                 fire 3 - sshotgun blast, more spread
                 fire 4 - machinegun shot, one bullet almost no spread
                 fire 5 - chaingun bullet, larger spread than fire 4
                 fire 6 - grenades
                 fire 7 - rockets
                 fire 8 - hyperblaster shots, same as blaster but no trails
                 fire 9 - rail shots
                 fire 10 - the dreaded BFG
 
    3.3 - Firing fields

          There are a couple of fields that firing turrets need.

          These are:

                 fspeed   - speed of shot, not always present
                 fdamage  - damage of shot, always present
                 fradius  - radius damage, present for rockets, grenades, bfg

          For our example lets use rockets with a damage of 100, speed of 700 and a damage
          radius of 150. Here's how the fields should look like.

                    fire 7
                    fspeed 700
                    fdamage 100
                    fradius 150

          This is prety easy and leaves the entity flexible.

    3.4 - Firing delay

          Firing delay is the time between shots or the time that has to pass
          before you can fire another shot.

          It is set through a field called: times
          It is in seconds so for our exaples lets use times of 1.2. This means that rockets
          will fire from your info_notnull that is targeted from the firing turret and will
          fly at a speed of 700 and inflict 100 points of direct damage and 150 of radius
          damage and will fire at a rate of 1 every 1.2 seconds.

    3.5 - Offsets

          There are optional offsets that we will not use for the exaple.

          The fields are:

                   zoffset - offset on the Z AXIS
                   yoffset - offset on the Y AXIS
                   xoffset - offset on the X AXIS
          
           They are not in degres but there is an easy way to convert from the offset to degres:

           offset of 0.1 = 1 degres. I'm not sure if this is right so try it out yourself.

4 - Specials

    There are a few special thing that you can do with a turret entity that i will not
    explain by example but that I have used in my turrets.

    4.1 - Laser Sight
         
          There are two field in the turret entity that are needed for a leaser sight, 
          these are:

                laser - targetname of notnull
                ldmg  - laser's damage, could be zero

          You should set up a info_notnull where you want the laser to come from and
          give it the same targetname as the laser field in the turret entity.
   
    4.2 - Range finder
 
          range finder is the same in setup as the laser except that instead of
          a laser field you have to use findrange and there is no damage.

    4.3 - Zoom

          Zoom is very easy to set up, One of the turret entities in a set have a
          field/key pair of zoom 1 you could zoom inside the turret.

    4.4 - Custom ViewHeight
  
          The snaping turret entity can have a field of cview that defines the viewheight 
          for a client once the turret is on.

    4.5 - Doors

          There is another option that one part of the turret could be moved by itself, like
          a door. 

          There are a few fields that a door needs to operate, these are:

                    turtype - This should be set to 1 for a door and 3 for a disapearing door
                    tdaxis - the axis on which the door would travel, 1=X, 2=Y, 3=Z.
                    tdmaxmove - max angle move on that axis
                    tdminmove - min angle move on that axis

          4.51 - Disapearing door
     
                 There are the doors that disapear once the turret has been turned off
                 reapear when on.

                 all you need for these is a turtype of 3.


FINAL NOTE:

I think thats all you need for a turret, i might be wrong. I usualy have to look into my
source code before i get a turret fully working. Any questions, problems, comments? Email me
at demolisher@planetquake.com

I should update this doc from time to time, depending on its usage.

I should also release a "What not to do tutorial".

I might have forgoten some stuff, so i hope you'll forgive me for my spelling, grammar and
neglegance.
