**Tutorial** Creating custom .surs via the .sur splicer

Sun Jun 18, 2006 3:46 pm by Dev

This is a step-by-step tutorial on how to use my .sur splicing utility to generate custom .surs (download it here).

The first thing to do is to put together the .sur for the ship. How you go about doing this is up to you, but the general rule is that each piece must be convex. Additionally, the .cmp exporter (which you will be using later) is limited to 18 groups, so consider that the absolute maximum number of pieces that you can use. Also, I find that it helps to start from the basic MS3D objects (boxes, spheres, etc). Pieces may overlap as much as you wish. The names of the pieces at this stage do not have any significance, as you will be renaming them all anyway with the .sur splicer.
Step 1

Next, export each piece as a separate .sur file. Be sure to use the "Shrink Wrapped" option for the shield.
Step 2

Now, put together the file that will tell the .sur splicer what to splice together. The part names you choose here do have significance, as they will need to match with the names you use in the .cmp a bit later. The format is as follows:

<output .sur file>
<output cons_fix file> - this one will be explained later
<approximate radius of ship> - you are better off being too large than too small
<inertia_x> <inertia_y> <inertia_z> - the inertia values of the ship (larger = greater resistance to collisions)
<partial .sur file> <name of part>
<partial .sur file> <name of part>
...
Step 3

Once you've got that set up, it's time to run the .sur splicer. Put the file above plus all of your partial .sur files into the sur splicer's directory, and then run the splicer.
Step 4

The splicer will output two files, as specified in the input file. The .sur file is done; now all you need to do is prepare your ship's .cmp file.
Step 5

To get the .cmp file ready, import it into MS3D as normal.
Step 6

Next, add a bunch of dummy parts; the number of pieces in the .cmp file should equal the number of pieces in the .sur file, so you need to add (number of parts in .sur file - 1) dummy parts. However, there is no problem with adding more if you want. The names you use are significant in that they should not match with the names of any other any other groups in any other ships. This is nothing new; you should never have two ships with groups that have the same names. In this example, I would need to make sure that there were no ships with groups named ISD1 or zomgbayz1 through 13 (so be sure to adopt a naming convention that avoids overlaps).
Step 7

Now it's time to export the model as a new .cmp file. In this example, the actual ISD model has five parts to it (ISD1 and Group2 through Group5); each of the dummy parts has just one part.
Step 8

Next up is some manual editing of the .cmp file. Open it up in utf_edit and change the Object Names to equal the names of the parts you used when splicing the .sur file.
Step 9

While you have the .cmp file open, import the cons_fix file produced by the sur splicer into the Cons.Fix node. This sets the dummy parts as children of the Root component, which is what you want (if you don't do this, the dummy parts will be ignored, as will the parts of the .sur assosciated with them). Be sure to save the .cmp file when you're done.
Step 10

Lastly, it's time to check your work. Open the .cmp file in HardCMP and display the .sur file (press 'S'; you will need to open the .sur file from the file menu first). Ideally the .sur file will match the actual surface of the ship very closely. Next, try adding a hardpoint and check the "Attached to:" dropdown list. You should see a list containing Root plus all of the dummy parts you added; if you don't, you probably didn't import the cons_fix file that the sur splicer produced.
Step 11

As an addendum, there is no reason why the parts you add need to be dummy parts. If you want, you can create the .cmp and .sur files such that you end up with breakable components, though you will need to set up the CollisionGroup entries for your ship in shiparch.ini to make this work.

Sun Jul 02, 2006 2:55 am by Cold_Void

UPDATED September 10th

vital rules for using sur_splice, and making ships and surs part-for-part accurate.

A. the CMP exporter creates your Cmpnd nodes incorrectly, the Object Name should be different than the File Name. The Part Name has no effect on anything! it could be flibbertygibits and it wouldn't make a difference as far as i can tell - so just leave it as is from the exporter
so, to show you exactly what i mean

Part_Star_Wing_lod1
->filename:Star_Wing_lod1.3db <- WRONG!
->index:part #
->Object Name:Star_Wing_lod1

the right way:
Part_Star_Wing_lod1
->File Name:Star_Wing_lod1.3db (should include a CRC but this will work)
->index:part #
->Object Name:Star_Wing
(or Object Name:Star_Wing_lod1 and File Name:Star_Wing_lod1+CRC- which is how FL's stock models are - the key is that the two names must be different!)

B. You don't need a sur mesh for every group, but if you have a sur-less group you will need to perform an extra step with sur splicer:

if you have a surless group in the model you need to include it in the sursplice .ini file so the cons_fix.dat will register it and it will show up. write the INI without the surless groups, like cockpit glass - then run the splicer and move the SUR it makes - insert the surless groups into the INI and use one of the existing surs for its INI filename entry - the sur you'll make will be discarded anyway. now run the splicer and import the cons_fix as directed and use the first SUR - rename all your object names to be accurate to the INI, including the surless ones

these are for models with multiple parts, and making damage caps

C.Group your ship in a format like Star_Wing/Port_Wing/Top_Fin/etc - sign each group with the Decimal CRC of your ships name, like this Star_Wing_94304380 - this goes for all parts, except submeshs(in groups with multiple meshs, only the mesh that sets the group name needs a CRC to prevent collision afaik)

this is important to keep two different ship's parts from colliding and getting mixed up, and also to setting up your SUR using traditional freelancer name conventions (Object Names include _lod1 extension and exclude CRC)

D. save your CMP settings after you set all the group counts/mesh counts - you'll probably want to use them later. hardpoints don't need to be counted as groups or meshes

E. rescale the SUR and CMP to full size,export the CMP and save the SUR in a second copy (i usually name it SUR (scale)x.ms3d) - open the sur #X.ms3d and delete all the groups but the one you're exporting, export it using all the rules in Dev's tute - then open recent/sur/repeat with next group - - remember to export everything in a consistent orientation, eg backwards or upside down - i use backwards because its easier for me

F. use ms3d hardpoint templates to create "Dp?part?" hardpoints, these need to be placed a little inside the mesh you want them to be attached to - their placement in milkshape's list doesn't matter, because they will be attached to the nearest group on exporting. you better do this in milkshape because you have 0 chance of getting the hardpoints precisely position-aligned for both the ship and cap in hardcmp.

G. When you go to export the damage-caps, reuse the Dp's - delete all other groups but the damage-cap and corresponding Dp - then rename the Dp to DpConnect and export the model as a .3db

setting up the INI collisiongroups, designing damage caps, and making fuses(if desired) is up to you, and remember kids: the power is yours!

the grail!

i've been working on this model awhile, anticipating these new tools - knocking out some poor looking damage caps and the sur, plus splicing and hardpoint orientation correction all counted the destructible-groups & sur were made in two days or approximately 4-6 hours of solid work.

Edited by - Cold_Void on 7/2/2006 4:02:19 AM

Edited by - Cold_Void on 9/10/2006 8:52:04 AM

Tue Jul 04, 2006 6:43 am by polyfiller

Right .... time for toys out of pram..... not because of everyones valliant efforts (at EOA), plus Dev & Cold void here .... it's just that SUR's and the tools we use are so damn annoying.

I've been trying to use the above to create a custom sur for a Klingon trading station. I haven't gotten very far into the process because ... I can't get the SUR parts lined up with the CMP. I get the CMP by importing from a SFC model. I then scale it by a factor of 11 ins MS3d (this makes it the same size as the CMP I already created and resized using FLModel tool ... and hardpointed using HARDCMP ... before I decided to brave the world of custom SURs). I then create simple boxes and two cylinders to form the shape of the SUR objects ... lined up by editing over the original model. I then delete all the original model groups and this leaves me with my basic SUR objects in all the right places (or so I thought ... read on). I scale by a factor of 11 in MS3D and exported all the groups in one go just to make sure the scaling looks right before I go down the road of exprting each part seperately..... AND the .SUR and .CMP do not lign up when viewed in hardcmp.... the SUR is around 50% higher than the CMP.

SOooo key question / reason for my rant .... is it improtant to lign up the .SUR components with the corresponding .CMP parts. And if so .... why am I getting different centre points for the .SUR and .CMP.

BTW ... I tried moving the groups up and down on the Y axis in MS3D and it made no difference with the .SUR ... it still looks "high" when viewed in hardcmp.

Tue Jul 04, 2006 8:26 am by Cold_Void

so its not aligned after importing the new cons_fix.dat and adding new parts/renaming original 'object names'? i've seen what you're describing and i believe it may be linked to the root sur piece, as i fixed this problem by exporting a new root sur for the gunstar when the sur was out of alignment in the Z axis.

if this fails repeatedly i recommend saving the sur and model scaled to the same size in MS3d,then re-exporting the model at the exact same size as the sur- if it has a lot of hardpoints, you might save some labor by using the XML project to convert it to .xml, where you can cut and paste hardpoint code from the old to the new, and then reconvert it - although i have noticed it omits two polygons everytime it re-encodes stock multi-part models.

anyways, stick with it and i'm sure you'll strike joy soon enough - these tools(CMP v0.3, SUR exporter 1.1, SUR splice) are really good

Tue Jul 04, 2006 1:12 pm by polyfiller

Cold void ... thanks for the suggestions. I've now got my first custom station SUR working. Many thanks Dev, Col void and BJ for inputs on other threads & Colin (for original SUR exporter). My problems were caused by using an old version of the CMP exporter ... the origin points from the SUR and CMP exporters seemed different and I could nevver get them lined up. I also had some "fun" with scaling in MS3D.

Here's a few more tips for those, like me, with a less active brain;

1) When re-sclaing in MS3D, make sure you select scale at origin, not center of mass.

2) If, like me, you re-scale before turning things upside down, do the scaling first and consistently i.e. don't scale the CMP model and invert, then export and then on the SUR model, invert, scale and export.

3) When using the CMP exporter, specify the number of groups and group quantities. If you've already used the exporter before, then you should know how many groups you had before adding the dummy ones. Example; if your model had one group, and you define 4 SUR component groups i.e. 4 SUR shapes, then enter 5 in number of groups and then enter a 1 in the group quantities for each group.

4) It doesn't matter where you create the dummy SUR groups. I just created a series of boxes somewhere in the middle of the main CMP.

5) As stated above by cold void, you can name the groups to match the names of the SUR components, but the exporter gets it wrong anyhow, so don't bother.

6) What cold means above about correcting the object names in the CMP file is;

open the CMP file with UTFEDIT

expand the CMpnd tree

you should see the names of the SUR compnents you assignedd in MS3d as trees. For example if you created a SUR group and named it blobbysship_top_hull_1, you will see a tree called; Part_blobbysship_top_hull_1_lod. Expand the tree. Click on the object name within the tree. On the right, select interpret data as string and then edit. Change the text in the box from; blobbysship_top_hull_1_lod to blobbysship_top_hull_1. Click on update.

Repeat this for all the tree node for the custom SUR parts under CMpnd tree.

When finished save the CMP file. At this point you should now be ready to test the sur.

7) Make sure you are using V0.3 of the SUR exporter (the one released in 2005). If you don't see the number of groups menu when exporting then you've got the old version.

Final tip for super muppets like me ..... quadruple check the spelling of you SUR file name before testing.

Once again thanks to all for their hard work. Much appreciated.

Tue Aug 01, 2006 3:32 pm by cjabates

Might not be the best place for this, but I'll give it a shot- you guys could point me in the right direction, at least, I'm sure.

Anyway- the problem:

I've got a new ship I'm trying to make a SUR for, but the SUR exporter is telling me it can't create the D3D device. This is immediately after I tell MS3D to export the SUR.

My system: (Dell Inspiron 5160)
P4HT 3.0GHz, 512MB RAM
NVidia GeForce Go 5200 64MB
XP Pro SP2, DX 9.0c
Milkshape 1.7.6

Chris Bates

Tue Aug 01, 2006 5:22 pm by Cold_Void

hmm i've never seen that but some guesses: make sure direct-x mesh reduction is off, and restart your computer too

p4 1.5 ghz
512 mb rdram
geforce fx 5200
ms3d 1.74

Wed Aug 02, 2006 1:42 pm by cjabates

it may have been one thing or another, but I got it working now. I upgraded to MS3D 1.7.9, and found that my SUR model had all the materials from the ship model.

I got rid of the materials, and now the exporter shows up.

Thu Aug 03, 2006 2:14 pm by Bejaymac

@ cjabates, your in luck, I had a dozy morning today and created the same errors and figured out what caused it. The grouplist in the exporter doesn't match the list in MS3D, 2 things cause this- 1} Exporting more than 1 group and miss counting how many you have in MS3D's group list, 2} having a hardpoint in among the groups (hardpoints should always be last in the group list). Most of my early work with the Exporter was with the textured ship models, so it wasn't the materials that caused it as the exporter ignores them.

@ Dev, I just can't get any where with the splicer, I've followed everybody's instructions and still can't get one to work, or I should say that lets me test it as every time I launch into space Freelancer freezes on me. But that doesn't bother me atm, and now my healths improving I can get back to working with the Exporter.

I'm about to test my second ship & SUR of the day and if this works as good as the first then it may be a case of pleasure overload

. The first one is about 90-95% fully working (Dp's and the rest) so fingers crossed.

*EDIT* Test one went well, now for the Dp's. One query guy's, when you repair the damage that gets done to your ship do you also see damage on the weapon's & equipment, atm I'm not getting any with the exporter.

**shuffles of with a new headache**

Edited by - Bejaymac on 8/3/2006 3:51:46 PM

Fri Sep 01, 2006 6:59 pm by Cold_Void

post deleted (it was a dumb post and waste of space)

Edited by - Cold_Void on 9/10/2006 6:41:10 AM

Fri Sep 01, 2006 9:57 pm by Dev

Except that the game will use only one of the objects with the name Root... or any particular name, for that matter. It is either the first or the last such object with that name, I don't remember offhand.

You are probably thinking of the trick in which all groups are renamed to Root by FlModelTool (which is actually my old trick that I used for my sur resizer back in the day). However, what this actually does is rename all subgroups of the first group to Root; all other groups are then removed (at least by my sur resizer, I don't know what the model tool does). The sur splicer, on the other hand, uses multiple groups, each with only one subgroup apiece. The reason for this is that getting the game to recognize multiple subgroups in any single group is a mysterious process that I eventually gave up on trying to figure out.

Sun Sep 03, 2006 7:51 am by Cold_Void

ok, decided to clear both these dumb posts - also, my hints/tips have been revised so that even one as stupid as myself can get good use out of them lol

Edited by - Cold_Void on 9/10/2006 8:14:40 AM

Wed Sep 13, 2006 6:30 am by Cold_Void

Dev, I have noticed that Root has the only reliable physical-collision detection, while parts can take projectile damage but no collision - its quite frustrating, because root is so solid yet the parts (made with the same methods) are not at all - which leads me to think you have overlooked something there, and yes i have tried increasing the radius quite a bit

Edited by - Cold_Void on 9/13/2006 7:31:34 AM

Wed Sep 13, 2006 11:35 am by Bejaymac

Cold_Void if you look at a vanilla SUR you'll find that parts have 2 meshes, 1 for damage and the other for collision, they also have a third that encompasses the part and the hardpoints attached to that part, this is for equipment damage. I don't know if the splicer can be used to create these or not.

**shuffles of with a new headache**

Wed Sep 13, 2006 11:05 pm by Dev

I know all about the collision thing... I know I've mentioned it at least a few times. If I knew how to solve it I would do so without hesitation.

Important Message

You are browsing the archived Lancers Reactor forums. You cannot register or login.
The content may be outdated and links may not be functional.

To get the latest in Freelancer news, mods, modding and downloads, go to
The-Starport