Adding your own weapon model to Freelancer: A tutorial

[Fab]

Adding your own weapon model to Freelancer: A tutorial

1. Introduction

---

This tutorial covers the process required to add a weapon model to the game: modelling, preparing, exporting, configuring, finishing*, playing*. All in a step-by-step guide.

*Finishing and playing sections are WIP.

2. Requirements

---

• A copy of Discovery Freelancer for modding. This copy should be disconnected from the main server.
  
• Blender.
  • Other modelling software of your choice, if you do not like/don't know how to use Blender. However, Blender is a hard requirement unless you know what you're doing.
    
• Librelancer Full SDK (For LancerEdit).
  

3. Set-up

---

• Create a copy of your Discovery Freelancer installation, and create a NEW shortcut to the copied Freelancer.exe.
  • This will be our test installation, and where you will see your model. I am not liable if you try logging into the main server with this installation.
    
• Download and install Blender.
  
• Download and unzip the Librelancer SDK.
  

4. Modelling

---

This guide won't teach you how to model. There are many tutorials around for that. You can use your favorite modelling software to create your weapon's model, as long as your software can export to a good 3D file format that Blender can import. Don't use legacy file/unused file formats.

You must have two models: A turret, with its origin point being where the turret will spin around and attach itself to the ship's hull, and a barrel. The barrel's origin point is where the barrel will connect to the turret and pitch up/down. That's all you need.

Attached in this post are the two files I used for this guide, in STL format for demonstration (OBJ is preferred). Feel free to use them and practice.

Some tips:

• Avoid making internal faces. Only faces that are visible by the player are required. Both your barrel and turret must have NO internal/unseen faces, and must be completely "hollow".
  
• Simple is better. Complicated and super futuristic guns might look cool, but might prove to be quite a challenge to edit and texture. Use flat, Square surfaces.
  

5. Preparing

---

5.1. Importing & Attaching

You have now finished your model and exported it to a file Blender can import. In this tutorial, I exported my models to .stl files.

You don't need to follow the import steps if you made your model in Blender.

With your models ( myturret.3dfile, mybarrel.3dfile [example names]) in hand and ready to use, open Blender.

By default, you'll be greeted by an empty scene containing a cube, a camera, and a light. Zoom out until you can see all of these elements, and use your mouse to select (Click and drag) and delete (Delete key in your keyboard) all of them. These won't be necessary.

Navigate to the top left corner. Select File -> Import. Select the file format your models are using. In my case, I select STL. Then you'll find and select your models. I'll import the turret first:

He's so handsome. Sometimes your model can look too smooth. Fix this by right clicking your model and choose Shade Flat.

Just for good measure, make sure your model is facing the right direction. On the top right of the 3D view, there's a gizmo displaying all six directions. Press the fully solid green Y. If you are not in a staring competition with your model, it requires rotation. Rotate your model using the Transform options on the right menu. A 90º turn to the correct direction should do the trick. After you're done, select the model and press CTRL+A. This menu applies your Transformations to the model. Select "All Transforms". Done! Your model is now permanently facing the correct direction.

After that's done, import your barrel as you imported your turret:

That looks wrong, but that's what we want. The turret's origin is its pivot point (0,0,0), and that makes it "spawn" at (0,0,0) like the turret. Remember to flat shade it if necessary.

Of course, we can't leave the barrel and the turret like that. It's time to use the Transform tool (Should be on the left corner-side menu, third option, looks like four arrows pointing in all directions). Position the turret where it seems logical and looks like a good fit:

That looks good. Now it's time to attach the turret to the barrel. To do this, hold the control key and select your barrel with a left click on the top-right hierarchy/collection view. While still holding control, select the turret. Their names should be different shades of orange by default. Now, press ctrl+P. That will open the Parent options. Select Object (Keep Transform). Done! Your hierarchy should look like this:

5.2. Properties

Now it's time for some renaming. In the hierarchy menu, double click the object's name to rename it. Rename the turret to "Root" and the barrel to "barrel". No need to rename the mesh name itself:

We renamed because such names are required by Freelancer to proper identify your model. This is our first step in making the model game-worthy. Now, we need to configure the barrel in a way the game knows how and how much it moves. On the Object menu located in the right, scroll all the way down until you see Custom Properties:

Press the + New button to add a new property. It'll create a line called "prop" right under the category, press the gear to edit it.

We'll need to create five properties in total.

The first property name's is "axis_rotation". Its type is an Integer Array of size 3. Here's how it should look:

Press OK to finish.

Now your property is ready. Change the 1,1,1 to 1,0,0, from top to bottom, if it isn't like that already.

Create and edit the second property: Name "construct", type "String". Value is "rev".

Create and edit the third property: Name "max", type "Float". Before pressing OK, change the max subproperty to 90. Then press OK and input the value 89.999.

Create and edit the fourth property: Name "min", type "Float". Value is 0. No need to change the subproperties for now.

Create and edit the fifth and final property: Name "offset", type "Integer Array", size 3. Change the values to 0,0,0 after creation.

Your final Custom Properties should look like this:

Now the game will know your barrel behaves like a barrel!

5.3. Hardpoints

That's not all the game needs to know, though. We need to give the game information about two important "hardpoints": HpConnect, that tells the game important information such as how much your turret moves to the left and right. The origin point itself is not enough, this is why we need to define HpConnect. The other hardpoint is simpler, and called HpFire01. That's where the projectile spawns.

Let's create HpConnect. To create a new object, press the Shift+A shortcut to bring up the Add menu. Select Empty, then Cube. The new object should spawn at 0,0,0 which is exactly where we want it to be! Rename it HpConnect on the hierarchy tree, just like you renamed the barrel and turret.

Now, time for some custom properties, again:

1. Name: "axis", type: "Integer Array", values: 0,1,0
   
2. Name: "hardpoint", type: "Boolean", value: checked
   
3. Name: "hptype", type: "String", value: "rev"
   
4. Name: "max", type: "Integer", value: 360
   
5. Name: "min", type: "Integer", value: -360
   

Your properties should look like this in the end:

Now, to finish HpConnect, Click and drag "HpConnect" in the hierarchy menu and drop it ON "Collection". Then, make "Root" (Your turret) its parent. HpConnect is Done!

Time for HpFire01. Create another empty object like we did with HpConnect. It'll spawn at 0,0,0 , but that's not where we want it. It must go in front of the barrel. Before we do this, Move it inside the collection and make the barrel its parent. Then use the transform tools to move it where you want. Tip: Use the same Z axis value for both the turret and HpFire01! That will make it centered. You should only need to finetune the Y axis.

After positioning it, create a custom property on HpFire01 called "hardpoint", type boolean, value checked. That's it!

Here is our final result, double check hierarchy:

5.4. Generating hitboxes, the .sur file

Hitboxes allow a gun to be hit and destroyed by projectile fire.

We need two hitboxes: One for the turret, one for the barrel.

Select the turret "Root". Copy and paste it. Drag and drop the copy (Called Root.001) inside the collection, make the Root its parent.

Now, change the mode from Object mode to Edit mode. To do this, select the drop down menu on the top left corner, below "Edit" and "Render". The 3d model should show edges and lines as a result.

Hide everything else (Root and barrel) by clicking on the respective eye icons in the hierarchy menu. You should only be able to see the Root.001.

On the same menu bar you changed the mode, click on Select, then select All. Your copy should be highlighted. Then now move to Mesh, then select Convex Hull.

This should be your result:

Now, rename the copy to "Root$hull". Our hull hitbox is done!

Return to the Object mode and select the barrel, and do the same steps. Attention! Make the barrel hitbox a child of the barrel itself, not the Root! When you copy and paste the barrel, you'll also copy the turret because the barrel is a child of the turret, and children are always accompanied by their parents. We don't need another turret, so, make the barrel an orphan by unparenting the barrel by selecting the barrel and pressing Alt+P. Select "Clear and Keep Transform". Delete the extra turret, and remember to name the hitbox "barrel$hull".

This should be the result. Pay attention to the hierarchy on the right:

6. Exporting

---

Our weapon is now ready for the game. Open LancerEdit, and add your Blender installation through the menu Tools -> Options.

Then, use Tools -> Import model. Select your project file. After the import is done, Click "Preview" on the left, and see if your weapon is there. If everything looks okay, press "Finish" on the top right.

After you press finish, two files will appear on the same folder as LancerEdit.exe: one .cmp, one .sur.

Copy and paste those files into your Discovery Freelancer copy. For example, I placed my files in DATA/EQUIPMENT/MODELS/TURRET.

7. Configuring

---

This part involves meddling with the bunch of .inis Freelancer has. But for simplicity's sake, we'll just switch the model for the cruiser pulse cannon.

To do this, navigate to DATA/EQUIPMENT/weapon_equip.ini. Open this file in notepad or any other text editor.

use CTRL+F to find the cruiser pulse cannon. Look for "infernocannon_cruiser".

Edit the property called "DA_archetype" filepath to your model name: "DA_archetype = equipment\models\turret\mymodel.cmp"

Save the file. You can now go in-game and see your model for yourself! Here's the result:

Attached Files

  boxgun.zip (Size: 3.38 KB / Downloads: 1)