Utilities needed:
HCl's UTF Editor
Tyson Schoepflin's BiniQDU v1.1


Preparation
--------------

The feedback I got is that a lot of people don't understand the coordinate frames, especially in the Orientation section. I must emphasise that it is VERY IMPORTANT for you to draw diagrams as you read along, otherwise you will have a hard time trying to understand what I'm talking about!

To make a new weapon hardpoint, first find your ship's CMP file in ..\DATA\SHIPS\(your ship's fraction)\(your ship)\ . For example my Dromedary freighter uses a file called bw_freighter.cmp under C:\Program Files\Freelancer\DATA\SHIPS\BORDER_WORLD\BW_FREIGHTER\. Open the file with UTF Editor and selected "float array" under "interpret data as...".

Using the same example again, if you explore the tree structure of the file you will notice that the first level 'tree trunks' are mainly consisted of body parts such as "bw_freighter_lod1030109103849.3db" (fuselage), "bw_port_eng_lod1030109103849.3db" (left wing) and "bw_star_wing_lod1030109103849.3db" (right wing). Under these trunks there are branches called "Hardpoints" and further under them are sub-branches labeled "Fixed" , where all the non-moving hardpoints are stored (ie thruster, mine launcher, shield, running lights etc.), and "Revolute" , where all the gun, missile, torpedo/cruise disrupter and turret hardpoints are stored. You can add hardpoints to any body parts, but I've heard that it is a really bad idea to add hardpoints to the bay doors due to a game stability issue.

Find the right fuselage part tree trunk that you intend to mount your new hardpoint on, select the "Revolute" sub-branch under it and click "Add node". Rename the new node "HpWeaponXX" for gun/missile mounts; "HpTorpedoXX" for torpedo/cruise disrupter; or "HpTurretXX" for turrets, where XX is the next vacant mount number (if your ship has 4 guns originally, then the next gun slot would be "HpWeapon05". Same goes for torpedo and turret hardpoints). Create 5 more nodes under this new node, and rename them "Axis" , "Max" , "Min" , "Orientation" , and "Position" .


Axis
-----

Select "Axis" and click Edit. I've done some experiments to find out what this node does, but I was not able to alter the behaviour of a weapon with it and strangely a hardpoint would work just fine with this node incomplete or even missing. For all practical purposes this node does nothing but for the sake of completeness just add it in and assign it the following values, which are standard for all rotatable hardpoints:

0.000000
1.000000
0.000000


Max & Min
------------

These two nodes defines how much the weapon can rotate sideway ("sideway" refers to the weapon, not the fuselage). If you look at an existing hardpoint, you will notice that these two nodes have 2 elements each. The number at the top defines the rotation limit in radians, while the number at the bottom seems to be 0.000000 all the time. "Max" is used to define the limit to the left and has a positive value; while "Min" is used to define the limit to the right and takes a negative number. To make a weapon that doesn't have a rotation limit, enter 6.283185 (=2*pi) in "Max" , and -6.283185 in "Min" , remember to put in 0.000000 for the second row.

A quick summary:

Max node = Left, Positive
Min node = Right, Negative

EXAMPLE 1: A gun with rotation limit of 30 degrees (0.523599 radians) to the LEFT, and 40 degrees (0.698132 radians) to the RIGHT.

The Max node would be:
0.523599
0.000000

And the Min node would be:
-0.698132
0.000000

EXAMPLE 2: A turret that can rotate freely.

The Max node would be:
6.283185
0.000000

And the Min node would be:
-6.283185
0.000000

There is a way to alter the weapons' firing cones without making them rotatable, or allow them to shoot over a wider arch than they can point their muzzles to. This may be useful for those of you who are planning to build your new ship around some fixed mammoth killer cannon. You can alter the following setting in Constants.ini , which is located directly under Freelancer's Data directory:

MUZZLE_CONE_ANGLE = 10

Note that the number is in degrees, also this setting will affect every weapon on everybody's ships in the game. The guns in Freelancer won't shoot unless your cursor is within their firing cone, so if you set the number too small your weapons may sometimes seemingly refuse to fire when you maneuver too much, especially for your fixed killer cannon.


Position
----------

Each part of the fuselage has its own coordinate frame with the same orientation. The orientation is as follow (DRAW A DIAGRAM NOW):

Positive X: to the right
Positive Y: up
Positive Z: to the rear

Depending on which fuselage part you assign a weapon to, the Position entry is referenced to that fuselage part's own coordinate frame. Look at the existing hardpoints and guess some values for now, we will come back to it at the end.


Orientation - The Direct Approach
-----------------------------------------

This is the hard part that needs some vector mathematics. Each mountable weapon has its own coordinate frame and if they are to align with the Fuselage Coordinate Frame, ie, having their X,Y,Z axes facing the same directions, then the gun barrel has to be pointing FORWARD with the mounting point facing DOWN. DRAW A SEPERATED DIAGRAM OF THE WEAPON AND ITS COORDINATE FRAME NOW.

And here is the complication, the 9 elements in "Orientation" map the Fuselage's Coordinate Frame to the Weapon's Coordinate Frame (ie, describe where each of the Fuselage Coordinate Frame's axes are pointing on the Weapon's Coordinate Frame). The first 3 numbers form the 3D vector for the Fuselage Coordinate Frame's X axis, the second 3 for Y, and the last 3 for Z.

EXAMPLE 1: A gun mounted on the TOP of the fuselage facing FORWARD.

* The fuselage's X axis is pointing to the same direction as the gun's X axis, so the first 3 elements are 1,0,0.
* The fuselage's Y axis is pointing to the same direction as the gun's Y axis, so the next 3 elements are 0,1,0.
* The fuselage's Z axis is pointing to the same direction as the gun's Z axis, so the last 3 elements are 0,0,1.

Sum it all up, the entry for the gun's orientation would be:

1.000000
0.000000
0.000000
0.000000
1.000000
0.000000
0.000000
0.000000
1.000000

* This is the "aligned" orientation - the three axes of the Fuselage's Coordinate Frame are aligned with the Weapon's Coordinate Frame's three corresponding axes.

EXAMPLE 2: A gun mounted on the RIGHT side of the fuselage facing FORWARD.

* The fuselage's X axis is pointing to the same direction as the gun's Y axis, so the first 3 elements are 0,1,0.
* The fuselage's Y axis is pointing to the exact opposite direction as the gun's X axis, so the next 3 elements are -1,0,0.
* The fuselage's Z axis is pointing to the same direction as the gun's Z axis, so the last 3 elements are 0,0,1

Sum it all up, the entry for the gun's Orientation would be:

0.000000
1.000000
0.000000
-1.000000
0.000000
0.000000
0.000000
0.000000
1.000000

EXAMPLE 3: A turret mounted UNDER the fuselage facing to the REAR.

* The fuselage's X axis is pointing to the same direction as the turret's X axis, so the first 3 elements are 1,0,0.
* The fuselage's Y axis is pointing to the exact opposite direction as the turret's Y axis, so the next 3 elements are 0,-1,0.
* The fuselage's Z axis is pointing to the exact opposite direction as the turret's Z axis, so the last 3 elements are 0,0,-1

Sum it all up, the entry for the turret's Orientation would be:

1.000000
0.000000
0.000000
0.000000
-1.000000
0.000000
0.000000
0.000000
-1.000000

EXAMPLE 4: A gun mounted on a 45 degrees slope (the slope faces the morning sun) on the RIGHT side of the fuselage facing FORWARD. I will stick to the unit vector principle (keeping the hypotenuse = 1) for less confusion.

* The fuselage's X axis can be described as y=x on the gun's coordinate frame, so the first 3 elements are 0.707107,0.707107,0. (Remembering 0.707107^2 + 0.707107^2=1^2 from trigonometry; alternatively you can forget about the unit vector principle and use 1,1,0 instead, but it might get confusing if you have any angles other than 45 degrees.)
* The fuselage's Y axis can be described as y=-x on the gun's coordinate frame, so the next 3 elements are -0.707107,0.707107,0.
* The fuselage's Z axis is pointing to the same direction as the gun's Z axis, so the last 3 elements are 0,0,1.

Sum it all up, the entry for the gun's Orientation would be:

0.707107
0.707107
0.000000
-0.707107
0.707107
0.000000
0.000000
0.000000
1.000000

If you screw up the orientation matrix, the weapon you mount on the new hardpoint will appear somewhat transparent in the ship dealer, and will malfunction in flight.


Orientation - The Smart Aerospace Engineer's Approach
--------------------------------------------------------------------

If you are trying to mount your hardpoints on some odd-facing surfaces, it will kill a lot of your brain cells trying to come up with the orientation matrix directly. In this case we need to use a little bit more maths to save us the trouble. Make sure you know how to do matrix multiplication, else look up here for a quick (5 minutes) but sufficient primer.

What we are going to do here is taking a different approach by breaking the problem down into 3 easier to manage questions:

1) Starting from the "Aligned Orientation", how much in radians do I want to rotate the weapon around its X-axis?
2) How much in radians do I want to rotate the weapon around its Y-axis?
3) How much in radians do I want to rotate the weapon around its Z-axis?

("Aligned orientation": Recalling that if the Weapon's Coordinate Frame is to be aligned with the Fuselage's Coordinate Frame, then the gun barrel has to be pointing FORWARD with the mounting point facing DOWN.)

We are going to use this ugly looking formula 3 times, each for the X,Y and Z axes respectively:



Where,
* {u1;v1;w1} is the Fuselage's Coordinate Frame axis you are trying to transform. The Freelancer game engine wants the transformation of all three axes (hence 9 elements), so in this case use the formula 3 times, once for {1;0;0} (ie. the X-axis), once for {0;1;0} (ie. the Y-axis), and once for {0;0;1} (ie. the Z-axis).
* {u;v;w} is the resulting transformed axis that forms the elements in the orientation matrix.
* Phi (that circle with a stroke through it) stands for the rotation you want around the X-axis (ie. pitch).
* Theta stands for the rotation you want around the Y-axis (ie. yaw).
* Psi (that trident-like symbol) is the rotation you want around the Z-axis (ie. roll).

Whether the rotation is positive or negative is defined by the "Right Hand Rule". Hold up your right fist and stick up your thumb, if your thumb points towards the positive direction of the axis, then your other fingers signifies the positive direction of rotation around it.

To get your orientation matrix, follow these steps:

1) Figure out what Phi, Theta, Psi values you want, plug them into the formula.
2) Replace {u1; v1; w1} with {1, 0, 0}.
3) Solve the equation to get {u; v ;w}, that's the first 3 elements in the orientation matrix.
4) Replace {u1; v1; w1} with {0, 1, 0}.
5) Solve again, that's the middle 3 elements in the orientation matrix.
4) Replace {u1; v1; w1} with {0, 0, 1}.
5) Solve once more, that's the last 3 elements in the orientation matrix.
6) Put your orientation matrix into UTF editor and try it out in the game, if you don't like the result, go back to step 1.

EXAMPLE 5: The mine dropper on my brand new Nomad fighter!



It is definitely much less tedious if you get some computational maths package to do the calculations for you, I myself wrote this Matlab code to solve the problem:



To mount the mine dropper the way it is I had to roll it 1.047198 radians (60 degrees) to the left and pitch it 0.139626 radians (8 degrees) up. So for my case Phi=0.139626, Theta=0, and Psi=1.047198. Putting these three numbers into my code gave the following output:

0.500000
-0.857598
0.120527
0.866026
0.495134
-0.069586
0.000000
0.139173
0.990268

This orientation matrix would give me the mine dropper orientation shown in the picture.


Activating The Hardpoint
-------------------------------

That's it for orientation and the new hardpoint is now fully defined. The next step is to enable it in shiparch.ini which is located in ..\DATA\SHIPS\ . But before you do that, look up here for the unique ID number of your ship. Once you have the ID number, open shiparch.ini with BiniQDU and find your ship. If you created a gun hardpoint, find the lines starting with "hp_type = hp_gun_special_X, HpWeapon01, HpWeapon02, ..." and add your new hardpoint to the end of each line. Notice that X stands for the class of guns, so if you want your new hardpoint to take every gun in the game, add it to the back of all 10 lines. Unless you are modding the Eagle, Titan or Sabre, which take class 10 guns and missiles by default, you will need to add the missing lines for the higher classes. Just follow the pattern. Same goes for torpedos/cruise disrupters and turrets, under the lines "hp_type = hp_torpedo_special_X, ..." (there are 2 classes of torpedos/cruise disrupters) and "hp_type = hp_turret_special_X, ..." (10 classes) respectively.

Remember to save your work. The last step would be to run the game, put a weapon on your new hardpoint and see where it goes, then come back to refine the hardpoint's position.

That's it for adding hardpoints! Enjoy your overloaded super gunship!


Edited by - CW on 07-05-2003 15:18:09

I can't find the "Hardpoints" in the .cmp files.

Using my freighter as an example again, there are three chunks of the airframe where you would normally attach weapons to - the fuselage, left wing and right wing.

For my ship, the "Hardpoints" branches are found under "(root)\bw_freighter_lod1030109103849.3db\", "(root)\bw_port_wing_lod1030109103849.3db\" and "(root)\bw_star_wing_lod1030109103849.3db\".

All ships are similar. Although the first level branch names are different, they are fairly obvious.

Edited by - CW on 30-03-2003 18:43:48

Aaah, thanks.

I found that it was quite hard to rename the nodes:

This is how I did it:

Press and hold left mouse button. Then quickly tap the right mouse.

If anybody knows a better way, please tell!

Bump, tired of seeing all these get lost into the abyss and seeing the same stupid questions asked over and over.

Stannum, there is a simplier, Windows standard solution to your problem. Try left clicking on the name, move your mouse slightly to one side, then left click again.

hehe i wana add a hardpoint for the front of my titan and add a huge hammer to the game with the elcisty mod and wack people around

...as far as hardpoints go, can't you just create new hardpoints directly on the model, won't editing the .mat file for an existing ship just make weapon "clumps" on the existing hardpoints?

Like persay, if you put the model in Milkshape and add completely new hard points...you can space them out? I'm working on adding an entirely new ship of my own design into the game...so I hope i'm doing this right.

I don't quite get your question, but you are supposed to edit the .cmp file to add hardpoints NOT the .mat file.

-----------------------------------------------------------
War does not decide who is right, only who is left.

If you create your own ship and add the hardpoints with milkshape, is it necesary to add the things in the UTF editor?

{edit} I'm actually not too sure since I never had the time to try out Milkshape and create my own ship.

-----------------------------------------------------------
War does not decide who is right, only who is left.

Edited by - CW on 17-04-2003 18:09:14

How do I add a shield hardpoint? The mod I downloaded doesn't have one.

Check out the CMP file with UTF editor, if the entry HpShield01 exists but you still don't get to put a shield on the ship then it is a "shield link" problem in shiparch.ini. Add these lines in if that is the case:

shield_link = bw_vheavy_shield01, HpMount, HpShield01
hp_type = hp_elite_shield_special_10, HpShield01
hp_type = hp_elite_shield_special_9, HpShield01
hp_type = hp_elite_shield_special_8, HpShield01
hp_type = hp_elite_shield_special_7, HpShield01
hp_type = hp_elite_shield_special_6, HpShield01
hp_type = hp_elite_shield_special_5, HpShield01
hp_type = hp_elite_shield_special_4, HpShield01
hp_type = hp_elite_shield_special_3, HpShield01
hp_type = hp_elite_shield_special_2, HpShield01
hp_type = hp_elite_shield_special_1, HpShield01

If HpShield01 doesn't exist at all in the CMP file then add it as a Fixed node with only orientation and position nodes underneath, and the shield_link lines in shiparch.ini.

-----------------------------------------------------------
War does not decide who is right, only who is left.

Edited by - CW on 27-04-2003 07:52:10