Modding: Changing Weapon Functionality (Advanced)

Bionicle Heroes uses Weapon Configurations and Bullets to build the arsenal of weapons for the player. Many attributes can be changed and appended from character to character, independently from the rest. This breakdown will explore both aspects in great detail with explanations and providing examples.

### Weapon Configuration

Weapon Configuration will handle things such as rate of fire, shots per round and projectile spread as well as some visual effects directly related to the weapon itself. Before getting started, it is important to understand the basics of character configurations, as each weapon configuration is built directly into the character config blocks.

#### Basic Character Configuration Understanding

The few things needed to understand Character Configuration in regards to weapon configuration are where the blocks begin, segment, and end. Identifying where the block starts is key into isolating where your edits should be. Individual character configurations begin with the "BEGIN" function and are usually followed up with functions for movement speed, draw size in various states, HUD type, player character's body model, animations etc. Using Kongu's character configuration block as example, his code block begins as shown in the example below:

```
BEGIN CHAR_TOA_AIR
```
After the "BEGIN" section, there is a sub block for the mask model. This sub block defines where to pull the model from in the file directory and lays out animation related functions. The example below shows the string that begins the mask code block:

```
FACECHARBEGIN
```
The example below shows the strings that end this section and sub block:

```
ENDCHARACTER

FACECHAREND
```
From here, the Character configuration moves onto the individual weapons themselves. It starts with configuration of the weapon model, bindings, and animation functions at the string showed first, and ending with the second showed in the box below:

```
NEWTOYWEAPONCHARBEGIN

NEWTOYWEAPONCHAREND
```

The next sub block of the character configuration is the area that controls the first weapon's set of attributes. It would seem that its not immediately apparent whether its attached to the first weapon, but in the character configs, these values are tacked on to it by not starting another weapon config block. Weapon 2 starts with the next use of "NEWTOYWEAPONCHARBEGIN" with an added "1" to signify its separation from the first. The same applies for the first and third weapon. "0" is the first, second "1" and the third has a "2" attached.

#### Rate of Fire

The first of the three most important functions in this block is the string that controls rate of fire.

The function as used in Jaller's first weapon, Tahu's Fire Sword.

```
weaponFireDelay 0 0.09 0.35
```
At this moment in time, it is uncertain what the first variable controls. The second variable controls delay before pressing the fire button and the first projectile coming out is set to "0.09" and the third variable controls every following projectile comes out at a delay of "0.35" after the first. This is used on most, if not all weapons in the game to varying degrees. The special case uses however are with the "energy beam" projectiles, where all variables are set to zero to allow for a continuous stream of projectiles. Hahli and Vezok both use this configuration.

#### Shots Per Round

The second important function is shots per round.

The function as used in Kongu's first weapon, Lewa's Air Axe.

```
WeaponShotsPerRound 0 5
```
The second variable controls how many projectiles shot with a single press of the fire button. In the example above, Kongu is firing 5 different projectiles in one shot. If this function is used by itself, all of the projectiles will overlap each other.

#### Projectile Spread

The third important function is projectile spread.

The function as used in Kongu's first weapon, Lewa's Air Axe.

```
WeaponSpread 0 0.3
```
The second variable in this function controls the range of deviation a projectile can spread from. This is used in most if not all weapons to introduce weapon inaccuracy to distinguish the longer range weapons from the closer ranged ones. For example, without this function, Jaller's projectiles would maintain a straight and uniform line, perfectly hitting a target. Whereas with Kongu's weapons, it provides the necessary deviation to create a "shotgun" spread.

#### Basic Weapon Config Block Example

Inserted below is the weapon config block for Kongu's first weapon "Lewa's Air Axe"

```
WEAPONMUZZLEFADE 0 0.26
WEAPONMUZZLEVFX 0 GREENSHOCWAVE
WEAPONMUZZLEPTL 0 "greenshotsmoke"
BulletType 0 Green1
WeaponFireDelay 0 0.8
WeaponShotsPerRound 0 5
WeaponSpread 0 0.3
WeaponHeat 0 0.4
WeaponCool 0 4
WeaponAimType 0 7
WeaponAimRecoil 0 0 2 1
```
The function "WEAPONMUZZLEFADE" controls how long it takes for the selected visual effect to fade out or despawn, and "WEAPONMUZZLEVFX" assigns said visual effect to the action of firing the weapon. "WEAPONMUZZLEPTL" attaches a particle effect to the weapon. In this case, it is placing the green smoke particle seen in game. "WeaponHeat" and "WeaponCool" are assumed to be unused leftovers from the first person shooter design phase. AimType controls how the player grips their weapon. More on this in this page. AimRecoil controls how much kickback (or recoil) affects the weapon.

### Bullet Attributes

Bullet Attributes are the characteristics defined in a specific bullet. Names are assigned to the bullet, that are then used to call for it and use it in a weapon configuration block. Some examples of attributes controlled by the bullet are bullet models, visual and sound effects, projectile velocity, maximum range, damage, damage type, etc.

For example, the string below is used to call a bullet to be used in Kongu's first weapon "Lewa's Air Axe."

```
BulletType 0 Green1
```
"Green1" in this case is the name of the bullet being called. Bullets are defined separately from the weapon itself, and control different attributes such as damage and the visuals attached to the projectile.

#### Basic Bullet Block Example

Inserted below is the Bullet block that Tahu's Fire Sword uses, referred to as "Red1LARGE" in the .cfgc.

```
BULLET Red1LARGE
OBJ redtoashot_L
PARTICLE Firetrail
PARTICLE SPARKSRED
DETONATEVFX RED1HIT
SPEED 30
RANGE 50
DAMAGE 07
STEPSIZE 0.07 1.2
ONSFX wpn_red_start_1
FIRESFX wpn_red_1
OFFSFX wpn_red_end
IMPULSESTRENGTH 20
END
```
With the "BULLET" function, it begins the bullet block, as well as defines what the name of the bullet is. The name in this example, "Red1LARGE" is what the weapon configuration block uses to call for this projectile. Notice that there are two "PARTICLE" functions attached to this single projectile. By doing it this way, instead of using "ATTACHEDPARTICLE" it can run the two particles side by side, instead of one inside of the other. "ATTACHEDPARTICLE" is most often used in larger bullets such as Nuparu's grenades, Vezon's energy bullets, and Zamor Spheres to add the outer glow and energy field-esque particles to them. In this example, when a projectile is fired, it spawns the "redtoashot\_L" model, spawns "Firetrail" and "SPARKSRED" as it leaves the muzzle of the weapon. From there, if the projectile collides with collision, enemies, shootables, etc., it will spawn "RED1HIT" which is assigned by the "DETONATEVFX" function. The projectile moves at a speed of 30 world units per second, does damage out to a maximum of 50 world units as assigned by the "RANGE" function, and does 7 damage upon contact with a shootable or enemy. At this current time, it is unknown what "STEPSIZE" actually does, but the working theory is that it adjusts how far back the arms and torso bend back to display kickback from a weapon on the player's character model. When used with high rate of fire weapons that shoot projectiles very quickly in rapid succession, "ONSFX" assigns what sound effect should be called upon first pressing the fire button, "FIRESFX" assigns the sound to play and repeat during sustained fire, and "OFFSFX" assigns a sound effect to play when the fire button is released. The complete range of function that "IMPULSESTRENGTH" is currently unknown, but it is known that it does have some control over whether the player's automatic aim locks onto shootables and enemies within the set radius of the "RANGE" value. The "END" function then closes the bullet block.

#### Known Functions

Below is a list of the currently known bullet functions in alphabetical order.

```
ATTACHEDPARTICLE
BOUNCESFX
DAMAGE
DAMAGETYPE
DETONATEMODE
DETONATESFX
DETONATEVFX
ELECTRIC
ELECTRICBEAM
ELECTRICSEGMENT
ELECTRICSTREAMPARTICLE
END
ERRATIC
FIRESFX
GRAVITY
HITPARTICLE
IMPULSESTRENGTH
INSTANTFIRE
LIGHTBLEND
LIGHTCOLOUR
LIGHTRADIUS
MOTION
MUZZLEVFX
NEWBEAM
OBJ
OFFSFX
ONSFX
PARTICLE
PLASMA
RANGE
RECOILIMPULSE
SHOCKWAVE
SPEED
TENDRILMTL
```