| |
All of the files that make up a custom weapon design
must be placed in the Mods\Weapons directory, or one of
its subdirectories. The
For example, to create a new Fighter Plasma cannon
called the "PPG", start by creating
a directory named Mods\Weapons.
You may wish to create a subdirectory named
Mods\Weapons\PPG to hold the
meshes and texture bitmaps for the weapon.
The properties for your weapon design are defined in
a text file called a "Weapon Definition File". This file
can be created with any text editor (e.g. notepad) and
must have the same name as the weapon design.
For our PPG example, the weapon definition file would
be Mods\Weapons\PPG.def.
The weapon definition file contains all of the physical
properties of the ship (name, type, damage, fire rate,
etc.) and also names the graphics
and wave files that define how the weapon looks
and sounds.
Weapon turrets and missile bodies are modeled
using 3D mesh files created by the low-poly editor
Magic, written especially for the game. Magic stores
meshes in files with .mag extensions.
You can download a free, unsupported copy of Magic 1.1 from the
Downloads
Page of the official website.
Texture maps for weapon graphics must be stored
in PCX format. Textures must be square powers of
two (e.g. 64x64 or 256x56) in size. You should
store your textures in 24 bit RGB format. You can
use Adobe Photoshop, JASC Paint Shop Pro, or any
other bitmap graphics editor to create textures
for your models.
Sounds for weapons fire are stored in standard
Wave files. You may use any bit depth (8 or 16 bits
per channel) and sample rate (22 kHz or 44 kHz)
for your sound effects that you wish. Weapons fire
is localized in 3D, so it should be record in
a monaural, not stereo, format.
Weapon Definition File and Structure
The weapon definition file is a text file that has a
.def extension. All definition files
in Starshatter use the same C-like syntax.
The weapon definition file defines the logical, graphical,
physical, and functional properties of a type of
weapon.
The weapon definition file starts with the keyword
WEAPON, in all-caps to indicate that the file contains
a weapon definition. The logical parameters for the
weapon are contained in struct that is introduced by
a type label name. There are several broad categories of
weapons:
- primary: bolt type energy weapons
- beam: beam type energy weapons
- missile: guided or unguided missiles
- drone: sensor and combat drones
Primary and beam weapons are tied to the primary
weapon trigger. Missile and drone weapons are tied to
the pickle switch or secondary weapon trigger.
Many weapon design parameters refer to the number
of barrels the weapon has. The number of barrels is
actually part of the weapon mounting, not the weapon
design, and is determined by the number of muzzle
attributes in the weapon structure in the ship definition
file. A single Laser weapon may be deployed in single
barrel or multibarrel configuration in different
ships.
Logical Properties
| name |
The name of the weapon design. This is the same name as
the definition file, without the .def extension. |
| group |
The name of the default weapon group to use when controlling
this type of weapon. This parameter is optional. If no group is
specified, the design name will be used. |
| target_type |
A bit vector that identifies the ship classes that this
weapon can target. Each bit corresponds to a single ship class
from combat drones (bit 0) to starbases (bit 21). A weapon that
can target fighters and drones would have a target type of 0x0000000f.
Starship weapons have a target type of 0x0000fff0. Air-to-ground
weapons have a target type of 0xffff0000.
|
| value |
A number from 1 to 5 that is used by the enemy AI to evaluate
how dangerous this weapon is. |
EXAMPLES:
WEAPON
primary: {
name: Turret,
group: Turret,
target_type: 0x000fffff,
value: 3,
|
Physical Properties
| ammo |
The number of shots that may be fired from each barrel
of this weapon in a given mission. This parameter is
optional. If no ammo limit is specified, the weapon
can continue to fire shots until the reactor power runs out.
|
| capacity |
A number indicating the size of the weapon's capacitor
in megajoules.
|
| recharge_rate |
The rate at which the capacitor can be recharged
in megawatts. |
| refire_delay |
A number defining the delay between shots
fired from this weapon in seconds. |
| salvo_delay |
Used by the AI to impose and additional delay between shots
after the last barrel has been fired. |
EXAMPLES:
capacity: 1000,
recharge_rate: 20,
refire_delay: 0.2,
charge: 10,
min_charge: 10,
damage: 5,
speed: 10e3,
life: 2,
|
Shot Properties
| damage |
The amount of damage delivered by the shot in hitpoints per
megajoule. This number is multiplied by the amount of energy
in the shot to determine the number of hitpoints to apply to
the target if the shot connects. For beam weapons, this is
the amount of damage to deliver for each second the beam is
in contact with the target.
|
| lethal_radius |
The maximum distance in meters from the target at which this shot
will do some damage if it misses. This property is only used
in conjunction with the guided property.
|
| speed |
The speed of the shot in meters per second. For missile
weapons, this is used as an approximate value for targeting
purposes. The actual speed of a missile is controlled by
the mass of the weapon, the drag value, and the thrust
available in the missile's drive. See below for more
information on those parameters.
|
| life |
The lifetime of the shot in seconds.
|
| charge |
The normal or maximum amount of energy delivered from the capacitor
for each shot in megajoules. Missile weapons should use a value of 1
for this parameter.
|
| min_charge |
The minimum amount of energy that must be delivered from the capacitor
in order to fire a single shot. This number must not be greater than
the normal charge parameter. For most weapons, these two parameters should
have the same value. Beam weapons can use the min_charge parameter to allow
firing with less than a full load, full duration shot.
Missile weapons should use a value of 1 for this parameter.
|
| carry_mass |
The mass in tonnes of a single shot when it is still aboard ship.
|
| carry_resist |
The amount of agility lost by the ship for each shot that is
still aboard ship.
|
| mass |
The mass in tonnes of a single shot while it is in flight.
|
| thrust |
The thrust in kilonewtons of the missile drive.
|
| drag |
Body drag coefficient of the shot. |
| roll_rate |
How quickly the shot can roll. |
| pitch_rate |
How quickly the shot pitch. |
| yaw_rate |
How quickly the shot can yaw. |
| roll_drag |
How quickly the shot stops rolling after the AI releases roll input. |
| pitch_drag |
How quickly the shot stops pitching after the AI releases pitch input. |
| yaw_drag |
How quickly the shot stops yawing after the AI releases yaw input. |
EXAMPLES:
mass: 0.2,
thrust: 2e3,
drag: 2,
roll_drag: 4,
pitch_drag: 4,
yaw_drag: 4,
roll_rate: 1,
pitch_rate: 8,
yaw_rate: 8,
|
Tracking and AI Properties
| min_range |
The minimum effective range of the weapon in meters.
The AI will not fire the weapon if the target is closer
than this distance. |
| max_range |
The maximum effective range of the weapon in meters.
The AI will not fire the weapon if the target is farther
than this distance. |
| max_track |
The maximum range at which the fire control computer
will track a target for this weapon. |
| guided |
A number indicating the level of guidance on
the shot. Set to 1 if the weapon's shots have onboard guidance
and will seek their target.
If this parameter is 0, the shots will fly straight. |
| syncro |
True if all barrels of the weapon should fire at
the same time. False if the barrels should fire in
sequence. |
| self_aiming |
True if the weapon can adjust the initial firing
angle of the shot to better aim at the target. This
is true for turrets, and may also be used for non-turreted
weapons to give the player a slight boost in aiming. |
| aim_az_max |
The azimuth range of the turret in radians.
Optional, only used if self-aiming is true. |
| aim_el_max |
The elevation range of the turret in radians.
Optional, only used if self-aiming is true. |
EXAMPLES:
guided: 1,
self_aiming: true,
aim_az_max: 1,
aim_el_max: 1,
min_range: 10e3,
max_range: 50e3,
max_track: 90e3,
|
Graphical Properties
| visible_stores |
True if the weapon's shots should be visible even
before they are fired. This is used by fighter missiles
that are mounted on underwing hardpoints. |
| graphic_type |
A number identifying the type of graphic representation
to use for the shot fired by this weapon. 1=solid, 2=sprite,
3=blob. A blob is an elongated polygon oriented to the
direction of the shot's travel. Blobs are used for bolt
and beam style primary weapons. |
| bitmap |
The name of the bitmap file to use when rendering
the shot as a blob or sprite. Must be a PCX file that
can be used as a texture. |
| model |
The name of the 3D model file to use when rendering
the shot as a solid object like a missile. Must be a
.mag file. |
| turret |
The name of the 3D model file to use when rendering
the turret of the weapon itslef. Optional. Must be a
.mag file. |
| trail |
The name of the bitmap file to use when rendering
the vapor trail left behind by a missile type weapon. Optional.
Must be a PCX file that can be used as a texture. |
| flash |
The name of the bitmap file to use when rendering
the muzzle flash for the weapon. Optional.
Must be a PCX file that can be used as a texture. |
| flare |
The name of the bitmap file to use when rendering
the drive flare of the shot. Optional.
Must be a PCX file that can be used as a texture. |
| width |
The width of the blob in meters. |
| length |
The length of the blob in meters. |
| scale |
The scale of the sprite graphic. |
| trail_width |
The width in meters of the missile vapor trail. |
| flash_scale |
The scale of the muzzle flash sprite. |
| flare_scale |
The scale of the drive flare sprite. |
| light |
The amount of light given off by the shot. Optional. |
| sound |
The name of the sound file to use when rendering
firing the weapon. Optional.
Must be a WAV file. |
| sound_min_dist |
The distance in meters from the weapon at which point
the sound begins to diminish in volume. At any point
closer than this distance, the sound will be heard at
full volume. |
| sound_max_dist |
The distance in meters from the weapon at which point
the sound of the weapon can no longer be heard at all. |
EXAMPLES:
turret: "rocket_launcher.mag",
scale: 0.15,
graphic_type: 1, // solid
scale: 0.15,
light: 200,
model: "missile00.mag",
trail: "smoke.pcx",
trail_width: 1,
flare: "drive.pcx",
flare_scale: 0.25,
sound: "missile2.wav",
sound_min_dist: 1e3,
sound_max_dist: 10e3
|
|
|
