/------------------\
 Weapons Tutorial 
\------------------/

Last Updated 10/06/2000

1.1 Introduction
1.2 [General]
1.3 [Projectile]
1.3.1 Actions and Times
1.3.2 Animations
1.4 [Fuse]
1.5 [Warheads]
2.1 Template weapon file


/-------------------\
 1.1: Introduction 
\-------------------/
Half the fun of Shrapnel is the ability to design totally new weapons. This
file is intended to explain that process, and answer any questions you may
have.

Weapons are defined by .wep files, found in the 'Weapons' directory. Every
property is case-INsensitive, apart from the name of the weapon, in which
case is preserved. Comments can be added at any point by including a ';'.

Virtually every property has a default value, which can be found in the
template weapon file in section 2.1.

A large number of properties can now be randomly chosen when a projectile
is created, allowing for more variety. For example, you could set the mass of
a weapon to "10+2", and then any projectile of this type will randomly have a
mass between 8 and 12 (2 either side of 10). See the template weapon for more
details about which propeties this applies to.

If you're making graphics for your weapons, you'll have to grab the palette
out of the standard weapons, unless you're using Paint Shop Pro when you
can use the file palette.pal, found in the main game directory.


/----------------\
 1.2: [General] 
\----------------/
The first section in any weapons file is the [General] section. This describes
such details as the name of the weapon, the cost, the classification of the
weapon and how many each player starts with.

---------------------------------------------------------------------------
 FIELD        DESCRIPTION                       NOTES                    
---------------------------------------------------------------------------
 Name         The name to use in the Shop                                
 Class        Categorises weapon in the shop                             
 Description  Describes weapon in the shop                               
 Author       Who made this weapon              Has no effect            
 Icon         Image to use in status bar        Read from 'weapons' dir. 
 Cost         How much weapon costs in shop     0 means you can't buy it 
 Initial      How many each player starts with  -1 means unlimited       
---------------------------------------------------------------------------


/-------------------\
 1.3: [Projectile] 
\-------------------/
The next section describes how the projectile that is fired by the player
behaves. You can specify properties such as how it is affected by gravity,
what it does and when it does it, as well as how much damage it does and the
sound effects to use.

---------------------------------------------------------------------------
 FIELD        DESCRIPTION                       NOTES                    
---------------------------------------------------------------------------
 Mass         How heavy the weapon is           Average value is 5       
 Damage       How much damage done if it hits   Players start with 100   
 Radius       Blast radius of explosion                                  
 Bitmap       Image to use for weapon           Read from 'weapons' dir. 
 Action       Behaviour of projectile           See Section 1.3.1        
 Time         When 'action' is carried out      See Section 1.3.1        
 Continue     Does proj. remain after split?                             
 Times        Max number of times it may split                           
 Rotating     Does projectile turn as it moves                            
 Directional  Is it mirrored as it moves?       Like a sheep bomb would  
 SpinRate     How fast does it spin             Spinning weapons do not  
              (see below)                       'rotate'                 
 Hitsound     Sound to play when fired          Read from 'weapons' dir. 
 Firesound    Sound to play upon contact         "    "       "      "   
 Generations  How many times a split can occur  0 means unlimited        
 Rounds       How many copies to make           Like a machine gun       
 Delay        Frames between firing each round                           
 Scale        Scale factor                                               
 Width        Width of each animation frame     See Section 1.3.2        
 Height       Height of each animation frame     "     "      "          
 Animrate     How often to change the frame      "     "      "          
 Animtype     Style of animation                 "     "      "          
 Border       Are frames surrounded by border?   "     "      "          
 Angle        Angle it bounces at               Only if action = 2       
 Homing       Makes weapon turn towards enemy                            
---------------------------------------------------------------------------

It's hard to explain spinning in a cramped table like that, so here's a better
explanation:
When a banana bomb moves, it rotates, so that it is always pointing in the
direction that it is moving in. So if it's moving upwards, it points upwards.
A spinning weapon will rotate whether it's changed direction or not. Setting
'spinrate' to 45 means that it will rotate through 45 degrees every frame.

/--------------------------\
 1.3.1: Actions and Times 
\--------------------------/
Projectiles can do one of three things at various different times, identified
by numerical values:

Value     Action       Description
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
0         Explode      Normal explosion
1         Split        Split into multiple warheads (see 1.4: [Warheads])
2         Reproject    Reproject at original angle and half power

N.B. I'll probably change reprojection soon so that you have more power over the
angle and power

These actions can happen at any of the following times:

Value     Time                         Description
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
< 0       Distance from any tank       Multiplied by -1, in pixels
0         When space bar is pressed    Self-explanatory
1         At peak of projection        As soon as vertical movement goes < 0
2         On contact                   Hits the ground, not a tank

By use of the continue property, you can make your original projectile
continue to exist even after it has split.


/-------------------\
 1.3.2: Animations 
\-------------------/
Weapons can now be animated! Each frame should be of the same dimensions,
and placed side by side in the same bitmap, as in Figure (a). You can also
make weapons use random sets of graphics, so you could make a fire work that
splits into red, green or blue sparks. To do this, simply place extra sets
of graphics immediately below the first set.
You can also put a one pixel border around each frame, if you set the 'border'
property to true. A line should be drawn around the bottom and right hand
sides of each frame.

Figure (a)
----------

   Set 1   |           |           |
  Frame 1  |  Frame 2  |  Frame 3  |<- Border
           |           |           |
-----------|-----------|-----------|
   Set 2   |           |           |
  Frame 1  |  Frame 2  |  Frame 3  |
           |           |           |
-----------|-----------|-----------|
  

You must specify a 'width' and 'height' property, so that Shrapnel knows how
big each frame is, and it will then automatically deduce how many frames there
are from this, and randomly select a graphics set.
You then need to tell it how many game cycles should pass between updating the
frame (1 for continuous animation) and the style of animation. This could be
any of the following:

0 - Loop animation continuously
1 - Play animation once then destroy object
2 - Pick a random frame each time (useful for fires)
3 - Play animation once then freeze on last frame


/-------------\
 1.4: [Fuse] 
\-------------/
One of the more recent additions to Shrapnel are fuses. Fuses are incredibly
useful when making weapons, as they not only allow you to precisely time when
a weapon splits, but they also allow you to make weapons that split more than
once, or maybe even constantly.

Basically, you have a starting fuse, which can be of any length, and which can
be lit at any time. When that reaches zero, the original projectile will
split (so you need a [Warheads] section, even if the 'action' is set to
explode or reproject). If you have set the 'continue' property in the
[Projectile] section to true, then you can then have any number of additional
fuses, but they must all be of the same length. When each of these reaches
zero, your projectile will split again.

There are four properties that you can put in the [Fuse] section:

Init: This is when the first fuse will be 'lit'. Setting it to -1 will light
      the fuse at the 'Time' specified in the [Projectile] section. So, if
      'time' is set to peak of projection, then the first fuse will light at
      the peak of projection. Simple, huh?
      Any value of zero or above will light it 'init' frames after launch. So
      an 'init' value of zero will make it light as soon as you fire the
      weapon.

Start: Start is pretty similar to 'init'. Basically, 'start' is the length of
       of the first fuse. Got that? So when the 'init' value is triggered,
       a fuse will be lit of length 'start'.

Loop: When any fuse reaches zero, the projectile will split, and optionally
      you can light another fuse. If you set 'loop' to 0, none will be lit,
      if you give a value greater than 0 a new one will be lit of length
      'loop'.

Count: 'Count' lets you limit the number of times a new fuse will be lit. A
       count of 1 is the same as setting 'loop' to 0.

/-----------------\
 1.5: [Warheads] 
\-----------------/
If you set the action to 1, Split, then you need an extra section, [Warheads].
This states how many warheads to split into, as well as letting you set
properties like the damage. There are two things you can do here: either
enter the name of any weapon as the 'Type' property, or let Shrapnel create a
new weapon type for you. You can then enter any of the properties from the
[Projectile] section, EXCEPT for action and time, which will then overide the properties of the weapon
type you selected. If you miss out the 'Type' property, your warheads will
just act like a simple projectile - the only way to make the warheads
themselves split or reproject themselves is to use another weapon type.
Let me try and make this a bit clearer with an example:

[Warheads]
Number = 5
Type = Cluster Bomb      ; Split into 5 Cluster Bombs
Mass = 50                ; But make these cluster bombs really really heavy

This weapon will then split into 5 cluster bombs, but instead of using the
normal mass of a cluster bomb, it overides it with 50.
At times, you want to stop weapons splitting too many times. You could have
a cluster bomb that splits into 5 cluster bombs, which then subsequently
split into 5 cluster bombs, but this would go on for ever, which is not a
good thing. By setting the 'generations' property in the [Projectile] section
you can make sure that there are never any more than, say, 5 splits.

There are also two other related properties: angle and relative.
The angle property specifies what angle each warhead will start off at, where
0 is facing to the right, 90 is vertically upwards, and so on. 'Relative'
states whether this is relative to the angle at which the projectile is
moving when it splits, so if it's already at an angle of 45, using '30' as
the angle property will actually result in an angle of 75.

N.B. There is a VERY serious bug which sometimes causes the game to crash if
you do not add 'Rotating = no' to the warhead section. I've no idea why it
happens, but if you find your cluster weapons crash, this is probably why.

/----------------------------\
 2.1: Template Weapons File 
\----------------------------/
This includes a slot for every property, but with none of them actually set,
if you see what I mean. Oh, just look at it.


; Andy's Cool Game File

; N.B. Numbers expressed in the form 1+0.5 means 1 +/- rand(0.5)
; (This is a complete lie, and has no effect, but it might one day)

; Name: Name to use in Shrapnel Shop
; Version: Useless property existing only to placate my mate Kit
; Class: Not used yet, may later be used to classify weapons in the Shrapnel Shop
; Cost: Price of weapon in Shrapnel Shop (def = 0  = not purchaseable)
; Initial: Number given to each player at the start of the game (def = -1  = unlimited)

[General]
Name=
Version=
Icon=
Author= 
Class=
Cost=
Initial=

; Mass: simulated kilograms, where 0 means do not arc (def = 5)
; Damage: Damage done upon contact (def = 5)
; Bitmap: Image file to use, either .bmp or .pcx (def = 2x2 black rectangle)
; Width: Width of each frame in bitmap (def = full width)
; Height: Height of each frame in bitmap (def = full height)
; Animrate: How often to change frames (def = 1)
; Animtype: Style of animation (def = 0)
;                  0 - Loop continuously
;                  1 - Play once then vanish
;                  2 - Pick random frames
; Generations: How many times a split can occur (def = 0  = unlimited)
; Radius: Size of explosion (def = 10)
; Rotating: Should bitmap rotate to match angle of movement (def = yes)
; Directional: Should it flip horizontally when moving in different directions
;              (def = no)
; Action: What happens when projectile hits ordinary ground -  (def = 0)
;               0 - Explode
;               1 - Split into warheads as described in [Warheads] section
;               2 - Reproject (e.g. bouncing bomb)
; Time: When projectile splits -  (def = 2)
;               0 - When space is pressed
;               1 - At peak of projection
;               2 - On contact
;               3 - When immediately above opponent
;               Negative values mean distance from target
; Continue: Should original projectile remain after it splits? (def = no)
; Times: Maximum number of times the weapon may split (def = -1  = unlimited)
; Angle: If it bounces, this is the angle it bounces at (def = original angle)
; Scale: Scale factor (def = 1.0)
; Homing: Makes weapon turn towards enemy (def = no)

[Projectile]
Mass=                      ; Can be randomised
Damage=                    ; Can be randomised
Radius=                    ; Can be randomised
Bitmap=
Width=
Animrate=                  ; Can be randomised
Animtype=
Action=
Time=
Continue=
Times=
Scale=                     ; Can be randomised
Firesound=
Spinrate=                  ; Can be randomised
Hitsound=
Generations=
Directional=
Rotating=
Homing=
Rounds=
Angle=                     ; Can be randomised
Delay=


; Init: When should fuse first start counting? (def = -1  = at 'Time')
        Any value >=0 means frames from when it is fired
; Start: How many frames after the 'init' event does the fuse start (def = 0)
; Loop: Once fuse has gone off, reset it to this value (def = 0  = no loop)
; Count: Maximum number of fuses (def = 0  = unlimited)

[Fuse]
Init=
Start=                     ; Can be randomised
Loop=                      ; Can be randomised
Count=


; Number: How many new warheads original projectile splits into (def = 1)
; Generations: Maximum number of splits that may occur
; Type: Name of an existing weapon type to spawn, e.g. Cluster Bomb (def = new projectile type)
; Angle: New angle of warheads (def = 0)
; Width: Width of each frame in bitmap (def = full width)
; Animrate: How often to change frames (def = 1)
; Animtype: Style of animation (def = 0)
;                  0 - Loop continuously
;                  1 - Play once then vanish
;                  2 - Pick random frames
; Relative: Is 'Angle' relative to original angle (def = yes)
; Spread: Range of angles warheads take up (def = 10)
; Damage: How much damage each warhead does upon contact (def = 5)
; Scale: Proportion of original bitmap to scale to (def = 1.0)
; Bitmap: Image file to use, either .bmp or .pcx (def = 2x2 black rectangle)
  
[Warheads]
Number=                             ; Can be randomised
Rotating=
Angle=                              ; Can be randomised
Relative=
Directional=
Scale=                              ; Can be randomised
Spinrate=                           ; Can be randomised
Damage=                             ; Can be randomised
Mass=                               ; Can be randomised
Radius=                             ; Can be randomised
Hitsound=
Type=
Bitmap=
Width=
Height=
Animrate=                           ; Can be randomised
Animtype=
