Weapons and projectiles are used over many levels and from game to game and it is time consuming to have to use an entity in each level to define them. Instead the weapon.ini file is used to predefine all weapons and projectiles. This allows you to define these objects only once, instead of in each level. The format of the INI file is as follows :
Each weapon/projectile definition is headed by the name of the weapon/projectile,
enclosed in square brackets, such as [rocket] or [GrenadeLauncher].
This name will be used by other entities to reference this weapon or projectile.
Following the name, up to the next weapon/projectile name or end of the file,
is the information needed to define the weapon/projectile. The important line
here is the one starting with type =. This defines whether the definition
is for a weapon or a projectile.
This is defined by type = projectile. The following variables must
have data assigned to them to define a projectile. If a variable does not have
data assigned to it in the definition block it will be set to 0 or NULL.
actor |
name of the actor file used for the projectile |
rotation |
the rotation values, in degrees, required to align the actor correctly |
scale |
the amount that the actor is to be scaled, with 1 being 100% |
animation |
the name of the animation used by the actor, if any |
gravity |
true if projectile is subject to gravity, false if not |
bounce |
true if projectile bounces off objects, false if it explodes on contact |
speed |
speed that projectile moves, in texels per second |
lifetime |
number of seconds before projectile explodes |
boundingbox |
size of the bounding box cube used to determine collision |
explosion |
name of the predefined explosion to use when the projectile explodes |
actorexplosion |
name of the predefined explosion to use when the projectile explodes on an actor |
showboth |
if true then the regular and the actor explosions will be shown when an actor is hit; if false then only the
actor explosion will be shown when an actor is hit, this is the default state |
bonelevel |
if true then the projectile will do bone level collision testing when colliding with an actor |
shakeamount |
amount of screen shake caused by the projectile's explosion, 0 is none |
shakedecay |
speed of decay of screen shake |
damage |
amount of damage done by projectile impact |
altdamage |
amount of damage done to alternate attribute by projectile impact |
explosionradius |
radius of projectile explosion |
explosiondamage |
amount of damage done by explosion |
decal |
number of decal to use at impact point |
movesound |
name of the sound file played while projectile is moving |
impactsound |
name of sound file played at projectile impact |
bouncesound |
name of sound file played when projectile bounces off an object |
effect0 |
name of predefined effect attached to projectile |
effectbone0 |
name of bone to attach effect to, if not defined then the root bone is used |
effect1 |
name of predefined effect attached to projectile |
effectbone1 |
name of bone to attach effect to, if not defined then the root bone is used |
effect2 |
name of predefined effect attached to projectile |
effectbone2 |
name of bone to attach effect to, if not defined then the root bone is used |
effect3 |
name of predefined effect attached to projectile |
effectbone3 |
name of bone to attach effect to, if not defined then the root bone is used |
effect4 |
name of predefined effect attached to projectile |
effectbone4 |
name of bone to attach effect to, if not defined then the root bone is used |
When an actor is hit by a projectile you may wish the actor explosion to attach itself to the actor bone it hit so it will move with the actor. This is useful for explosions with a long animation time. To allow this feature add this line to the projectile definition:
attachactor = true (the default is false)
The boundingbox variable is used to assign a fixed bounding box
to a projectile, rather than use the actual actor's bounding box. This allows a
much smaller bounding box to be used for collision testing on the projectile,
which can lead to a more realistic flight. All the effects that can be attached
to the projectile must be predefined and will move with the projectile as it
moves. See Predefined Effects for more details on
constructing these effects.
Projectiles can do bone level collisions with actors. Unless the projectile hits a bone on the actor it will pass through. This allows shooting under arms and beside heads without hitting the larger actor bounding box.
This is defined by type = weapon. The following variables must have
data assigned to them to define a weapon :
slot |
which of 10 weapon slots this weapon is bound to |
firerate |
number of seconds until weapon can attack again |
catagory |
either projectile or melee, to chose which weapon type is used |
maxdeviationangle |
accuracy of weapon in terms of maximum deviation angle in degrees (0 to 89.9) (Projectile weapon only) |
projectile |
the name of the projectile to fire (Projectile weapon only) |
attribute |
attribute that the weapon damages |
altattribute |
alternate attribute to damage if attribute is 0 or nonexistant |
ammunition |
name of the ammunition required by the weapon |
ammopershot |
amount of ammunition used each attack |
damage |
amount of damage done by each hit of a melee weapon (Melee weapon only) |
altdamage |
amount of damage done to alternate attribute (Melee weapon only) |
attacksound |
sound file played when weapon is used |
hitsound |
sound file played when melee weapons hits something (Melee weapon only) |
emptysound |
sound file played if using weapon with no ammunition |
worksunderwater |
if true then weapons works when under water (Projectile weapon only) |
meleexplosion |
name of explosion shown when melee weapons hits something (Melee weapon only) |
meleeammoactivate |
if true then activate melee ammunition Hud display when weapon is active (Melee weapon only) |
forceviewto = viewtype - set weapons so that they work
only in one view and when you switch to that weapon the view will change to
suit it. The view will switch back to the original state when switching to
another weapon. viewtype is one of these:
firstperson
thirdperson
isometric
fixed
shotpermagazine |
# of shots in the magazine: weapon reloading, if # of shots is 0 or the line is omitted then no reloading will take place. |
reloadsound |
sound file played when reloading takes place |
loosemag |
if true then the contents of the clip you just removed is discarded, by default this is false |
viewactor |
name of actor file to use as 1st person weapon actor |
viewfillcolor |
color applied to the 1st person weapon actor |
viewambientcolor |
color used when applying lighting to the 1st person weapon actor |
viewambientlightfromfloor |
if true use ambient light from floor when applying lighting to actor |
viewrotation |
rotation, in degrees, in the X, Y and Z axis needed to position 1st person weapon actor |
viewoffset |
offset in X, Y and Z directions needed to position 1st person weapon actor |
viewscale |
amount to scale the 1st person weapon actor, with 1 equal 100% |
viewlaunchoffset |
offset in the X, Y and Z directions from screen center to the projectile launch point (Projectile weapon only) |
viewlaunchbone |
name of bone in viewactor to launch projectile from (Projectile weapon only) |
viewanimationspeed |
amount to scale the speed of the 1st person weapon animations, with 1 equal 100% |
viewarmanim |
name of the 1st person weapon actor arming animation |
viewidleanim |
name of the 1st person weapon actor idle animation |
viewattackanim |
name of the 1st person weapon actor attack animation |
viewaltattackanim |
name of the 1st person weapon actor alternate attack animation (Melee weapon only) |
viewhitanim |
name of the 1st person weapon actor attack and hit animation (Melee weapon only) |
viewalthitanim |
name of the 1st person weapon actor alternate attack and hit animation (Melee weapon only) |
viewuseanim |
name of the 1st person weapon actor use animation (Melee weapon only) |
viewwalkanim |
name of the 1st person weapon actor walking animation |
muzzleflash |
name of the predefined explosion to use as a muzzle flash (Projectile weapon only) |
crosshair |
name of the bitmap file used as the weapon's crosshair (Projectile weapon only) |
crosshairalpha |
name of the alpha map file used to define transparency in the crosshair (Projectile weapon only) |
crosshairfixed |
if true the crosshair remains in the center of the screen, if false then it moves in/out (Projectile weapon only) |
allowlitcrosshair |
if true then allow nonfixed crosshair to light up actors that it is on (Projectile weapon only) |
crosshairlitcolor |
color that crosshair will change to when over a lit up actor (Projectile weapon only) |
zoomamount |
the amount of zoom this weapon can achieve (ie. 5x zoom) using the zoom key (Projectile weapon only) |
zoomoverlay |
name of bitmap placed over screen when weapon is in zoom mode (Projectile weapon only) |
zoomoverlayalpha |
name of alpha map used to define transparency of zoom overlay (Projectile weapon only) |
allowzoommove |
if true then keep in zoom mode when moving. If false the cancel zoom mode when moving. (Projectile weapon only) |
recoilamount |
amount of screen recoil from a 1st person weapon (Projectile weapon only) |
recoildecay |
speed at which recoil returns to 0. Total time in seconds is (recoilamount/recoildecay) (Projectile weapon only) |
bobamount |
if greater than 0 then the weapon will move in and out when moving with Head Bobbing enabled. The Head Bob amount is divided by this value to produce the weapon motion. Larger values produce less motion. A starting value would be 20. |
viewreloadanim |
reload animation that is played when the weapon's magazine is empty, if no reloading is to be done then this define can be omitted. |
It is also possible to force the weapon to reload even if the clip is not empty. By default the R key will do this but this can be changed in the menu. The animation played when this happens is defined in the first person section of the weapon as:
viewkeyreloadanim key reload animation
There is also an animation that will be played when the weapon is out of ammunition, if you want one that is different than the normal shooting animation. Define it by adding to the weapon definition this line:
viewattackemptyanim |
empty shoot animation |
environmentmapping |
if true then apply environment mapping to actor material |
allmaterial |
if true apply environment mapping to all actor materials |
percentmapping |
percentage of mapping to apply to material (0 to 100) |
percentmaterial |
percentage of material to use while mapping |
If environmentmapping is set to true and
allmaterial is false then only those actor
materials whose name starts with 'env_' will have environment mapping
applied to them.
playeractor |
name of actor file used as the 3rd person weapon |
playerfillcolor |
color applied to the 3rd person weapon actor |
playerambientcolor |
color used when applying lighting to the 3rd person weapon actor |
playerambientlightfromfloor |
if true use ambient light from floor when applying lighting to actor |
playerrotation |
rotation, in degrees, in the X, Y and Z axis needed to position 3rd person weapon actor |
playerscale |
amount to scale the 3rd person weapon actor, with 1 equal 100% |
playerlaunchoffset |
offset in the X, Y and Z directions from playerbone to the projectile launch point (Projectile weapon only) |
playermuzzleoffset |
offset in Z direction from playerbone to muzzleflash location (Projectile weapon only) |
playerbone |
name of bone in playeractor to launch projectile from (Projectile weapon only) |
muzzleflash3rd |
name of the predefined explosion to use as a muzzle flash for 3rd person weapons. If this is undefined then the regular muzzleflash is used.(Projectile weapon only) |
playerenvironmentmapping |
if true then apply environment mapping to actor material |
playerallmaterial |
if true apply environment mapping to all actor materials |
playerpercentmapping |
percentage of mapping to apply to material (0 to 100) |
playerpercentmaterial |
percentage of material to use while mapping |
If playerenvironmentmapping is set to true and
playerallmaterial is false then only those actor
materials whose name starts with 'env_' will have environment mapping applied to them.
The following animation names are used to override the default 3rd person animations provided by the PlayerSetup.ini file. If no animation is provided then the default animation is used.
idle |
idle animation |
idletowalk |
transition animation from idle to walking |
idletorun |
transition animation from idle to running |
walk |
walking animation |
walktoidle |
transition animation from walking to idle |
run |
running animation |
jump |
jumping animation |
starttojump |
start to jump animation |
fall |
falling animation |
land |
landing animation |
slidetoleft |
strafe (slide) to left animation |
slideruntoleft |
strafe (slide) running to left animation |
slidetoright |
strafe (slide) to right animation |
slideruntoright |
strafe (slide) running to right |
crawl |
walking crouched animation |
crouchidle |
crouched idle animation |
crawltoidle |
transition animation from crawling to crouching |
crouchstarttojump |
start to jump from a crouch animation |
crouchland |
land in a crouch animation |
crawlslidetoleft |
crawl strafe (slide) to left animation |
crawlslidetoright |
crawl strafe (slide) to right animation |
swim |
swimming animation |
treadwater |
tread water or floating animation |
The following animations deal with the weapon. Each action performed requires two animations, one for up and one for down. These animations are blended together to produce an animation that reflects where the player is looking. The up animation is how the player would look when shooting or aiming up at the maximum angle. The down animation is how the player would look at the maximum look down angle.
shootup |
idle attack up animation |
shootdwn |
idle attack down animation |
aimup |
transition animation from attack up to idle |
aimdwn |
transition animation from attack down to idle |
walkshootup |
walking attack up animation |
walkshootdwn |
walking attack down animation |
runshootup |
running attack up animation |
runshootdwn |
running attack down animation |
slidetoleftshootup |
strafe (slide) attack to left up animation |
slidetoleftshootdwn |
strafe (slide) attack to left down animation |
slideruntoleftshootup |
strafe (slide) running attack to left up animation |
slideruntoleftshootdwn |
strafe (slide) running attack to left down animation |
slidetorightshootup |
strafe (slide) attack to right up animation |
slidetorightshootdwn |
strafe (slide) attack to right down animation |
slideruntorightshootup |
strafe (slide) running attack to right up animation |
slideruntorightshootdwn |
strafe (slide) running attack to right down animation |
jumpshootup |
jumping attack up animation |
jumpshootdwn |
jumping attack down animation |
fallshootup |
falling attack up animation |
fallshootdwn |
falling attack down animation |
crouchaimup |
transition animation from crouch attack up to crouch idle |
crouchaimdwn |
transition animation from crouch attack downto crouch idle |
crouchshootup |
crouch attack up animation |
crouchshootdwn |
crouch attack down animation |
crawlshootup |
crawling attack up animation |
crawlshootdwn |
crawling attack down animation |
crawlslidetoleftshootup |
crawling strafe (slide) attack to left up animation |
crawlslidetoleftshootdwn |
crawling strafe (slide) attack to left down animation |
crawlslidetorightshootup |
crawling strafe (slide) attack to right up animation |
crawlslidetorightshootdwn |
crawling strafe (slide) attack to right down animation |
The slot variable assigns a weapon slot to the weapon. There
are 10 slots available, corresponding to Weapon 0 thru Weapon 9, which are
selected by (default) keys 1 thru 9 and 0. Certain variables are only required
if the weapon is a projectile weapon and are marked by (Projectile weapon only).
Other variables are only required if the weapon is a melee weapon and are
marked by (Melee weapon only).
It is possible to drop a weapon and free up that slot so you can pick up another weapon. The key that has been defined to accomplish this is set to P by default. This key can be changed in the menu.
If a dropped weapon actor is specified an Attribute will be spawned when dropping a weapon so you can pick it up again, otherwise the weapon will simply be removed.
dropactor |
name of actor file used as dropped weapon |
dropfillcolor |
color applied to dropped weapon actor |
dropambientcolor |
color used when applying lighting to the dropped weapon actor |
dropambientlightfromfloor |
if true use ambient light from floor when applying lighting to actor |
droprotation |
rotation, in degrees, in the X, Y and Z axis of the dropped weapon actor |
dropscale |
amount to scale the dropped weapon actor, with 1 equal 100% |
dropenvironmentmapping |
if true then apply environment mapping to actor material |
dropallmaterial |
if true apply environment mapping to all actor materials |
droppercentmapping |
percentage of mapping to apply to material (0 to 100) |
droppercentmaterial |
percentage of material to use while mapping |
dropgravity |
if true apply gravity to dropped weapon actor |
drophidefromradar |
if true hide from radar |
The variables viewfillcolor and viewambientcolor
are used to color and brighten the weapon actor - viewfillcolor
changes the overall color of the actor while viewambientcolor
changes the overall brightness.
The variables viewrotation, viewoffset and
viewscale are used to position the 1st person weapon
actor correctly on the screen. If you are using a converted Half-Life weapon
model then set these variables to the following to roughly position them.
viewrotation = -7.1 86.9 29.7
viewoffset = 0 -1.5 -0.2
viewscale = 0.23
If you are using a 3D Studio Max made model try these values for the rough positioning:
viewrotation = -7.1 86.9 0
viewoffset = 0 -1.5 -0.2
viewscale = 0.23
To fine tune the positioning, the following steps are required:
Use the IniEditor to turn on Weapon Positioning, then run Reality Factory.
At the menu, go to Options->Debug and turn on the Debug Info box.
Run the level containing your new weapons and pickup the desired weapon.
Press NumLock to activate the numeric keypad. In some cases this may have to be done prior to running the game, as some keyboards don't allow NumLock activation while Reality Factory is running.
The numeric keypad can now be used to position the weapon. The values for rotation, offset and scale will be shown on the screen and can be copied down after the weapon is in the proper place and used to replace the rough values in the weapon.ini file.
The key pairs used to increase and decrease the values are as follows:
| 7 and 8 | Change X offset (side to side) |
| 4 and 5 | Change Y offset (up and down) |
| 1 and 2 | Change Z offset (in and out) |
| 7 and 8 with 0 held down | Change X rotation |
| 4 and 5 with 0 held down | Change Y rotation |
| 1 and 2 with 0 held down | Change Z rotation |
| 9 and 6 | Change actor scale |
The changes made to a particular weapon do not affect any other weapons that you may have acquired so it is possible to switch between weapons to see if they are positioned properly in relation to each other.
For those users that don't have a number pad on their keyboard, you can switch
which keys are used to move the first person weapon around on the screen.
To do this add the following line to the [Debug] section of
internal_config.ini:
AlternateKey = true
When this is set the keys are as follows:
| J&K | Change X offset (side to side) |
| N&M | Change Y offset (up and down) |
| O&P | Change Z offset (in and out) |
| J&K w/Y held down | Change X rotation |
| N&M w/Y held down | Change Y rotation |
| O&P w/Y held down | Change Z rotation |
| Q&W | Change actor scale |
The variable viewlaunchoffset is used to change the point at
which the projectile launches. The default point is right in the center of the
screen, with the projectile aimed right at the cross hairs (assuming cross
hairs are turned on). If your view weapon is not positioned to this point (and
it is very unlikely it is) then viewlaunchoffset must be changed.
Regardless of the launch point, the projectile will be aimed right at the cross
hairs in the center of the screen. Changing the X value will move the launch
point side to side, with negative values moving it to the right. Changing the Y
value will move the point up and down, with negative values moving it down. The
Z value is a little different than the other two values. The launch point is
always moved out from the center, on a line to the impact point, far enough to
clear the player's bounding box. Therefore, a Z value of 0 will have the launch
point forward enough to clear the player's bounding box, regardless of what
values you have for X and Y. The Z value only has to be increased enough that
the projectile's bounding box does not intersect the player's box. The inital
starting location of the projectile is at the actor's center point so you have
to set Z to be large enough to have the projectile bounding box (set by
boundingbox in the projectile definition) clear the player's box.
This must be adjusted by trial and error, with the most likely intersection
points coming when shooting upward at extreme angles.
If you are using a bone to define the launch point, by having a name in
viewlaunchbone, then the launch point starts at that location.
It is then moved out from the center, on a line to the impact point, far enough
to clear the player's bounding box. At this point the Z value from
viewlaunchoffset is added to the location, to allow the
projectile to clear the player's bounding box. If a muzzleflash is used it will
appear at the viewlaunchbone location during the first frame of
the attacking animation.
The variables playerfillcolor and playerambientcolor
are used to color and brighten the weapon actor - playerfillcolor
changes the overall color of the actor while playerambientcolor
changes the overall brightness.
The 3rd person weapon is the player skeleton with the weapon mesh
attached to it. It requires no motions of its own, as it uses the motions built
in to the player actor for animating. Because of this the playerrotation
and playerscale values will be the same as those used by the
player actor.
The variable playerlaunchoffset is used to change the point at
which the projectile launches. The default point is at the bone location as
specified by playerbone. Changing the X value will move the
launch point side to side, with negative values moving it to the right.
Changing the Y value will move the point up and down, with negative values
moving it down. The Z value is a little different than the other two values.
The launch point is always moved out from the center, on a line to the impact
point, far enough to clear the player's bounding box. Therefore, a Z value of
0 will have the launch point forward enough to clear the player's bounding box,
regardless of what values you have for X and Y. The Z value only has to be
increased enough that the projectile's bounding box does not intersect the
player's box. The weapon does not have a bounding box so it is not a factor in
this.
Weapons, in common with all other objects the player can pickup, are acquired by use of the Attribute entity. Weapons are considered attributes and they must be defined in the AttributeInfo file before you can use them. See AttributeInfoFile for more details. The name of the attribute is the name that you gave the weapon when defining it, such as RocketLauncher or Sword. Set the low value to 0, the high to 1 and the initial value to 0, if you want the player to have to pick it up, or 1 if you wish him to start the level with it. Use the Attribute entity to place weapon pickups in the level, with the attribute name being the weapon name and the amount being 1.