MAXLancer Tools

MAXLancer Tools is a set of MaxScript tools for Autodesk 3ds Max to import and export 3D models for Freelancer.

Features

• Rigid model (.3db, .cmp) import and export, including LODs, hardpoints, HUD wireframes and compound joints.
• Deformable model (.dfm) import with animation scripts (.anm) (experimental feature).
• Collision detection surface (.sur) import and export. BHV validation.
• Material and texture (.mat, .txm) import and export.
• Automatic texture extraction, decompression and compression (using Nvidia Texture Tools).
• Convex mesh generation for surface hulls (using Nvidia PhysX/MassFX or built-in functions).

Prerequisites

• Autodesk 3ds Max 2017 or above (tested with 3ds Max 2018)
• Nvidia Texture Tools (available from Github or Nvidia)
• Microsoft Freelancer

Download

Latest version: Beta 4 (2020-06-28)

It may trigger SmartScreen window. To resolve this go into properties of downloaded file, at the bottom to the right of security tick Unblock checkbox.

Installation

By default installer will attempt to find most recent supported version of 3ds Max installed in the system.

After installation is complete you'll need to open (or re-open if it was opened during installation) 3ds Max to finish these steps:

Create toolbar

1. Open Customize→Customize User Interface.
2. Switch to Toolbars tab.
3. Press New... button to create new toolbar.
4. In Category dropdown menu select MAXLancer.
5. Drag and drop actions from the list below to newly made toolbar.

Set external paths

1. In MAXLancer sidebar press Settings button.
2. Specify paths:
   • Freelancer (C:\Program Files\Microsoft Games\Freelancer).
   • Nvidia Texture Tools.
   • Textures (C:\Users\User\Documents\3dsMax\sceneassets\images\MAXLancer).
   • Shaders (C:\Program Files\Autodesk\3ds Max 2018\maps\fx\MAXLancer).
3. Press OK button.

Path to Nvidia Texture Tools should point to binary folder (bin32 or bin64) containing executables.

Disable gamma/LUT

1. Open Customize→Preferences→Gamma and LUT.
2. Uncheck Enable Gamma\LUT Correction.

Default settings in 3ds Max may overbright textures when previewed in viewport via DirectX shader. This will also affect exported textures.

Sidebar

MAXLancer Tools

Alignemnt Tool

Simple normal alignment tool primarily made to align hardpoint helpers to mesh.

Rescale Model

This tool is used to uniformly scale model hierarchy. Meshes are rescaled, while positions for hardpoints and non-scalable objects are adjusted.

Rigid Models

Hardpoints

Change base/arrow size of all hardpoint helpers in selection.

Replace Selection will replace all selected objects with hardpoint helpers while retaining transform matrix.

Shader Display

Applies common settings to all MAXLancer supported DirectX shaders.

FLCRC32

Simple Freelancer hash calculator.

Rigid Models

Ships, stations, scenery and generally most 3D assets in Freelancer as well as user interface elements are rigid models. Typically they are stored in .3db or .cmp files. .3db consist of a single model while .cmp contains one or more embedded .3db files with compound hierarchy.

In 3ds Max model parts are represented by Rigid part helper object (Command Panel→Create→Helpers→MAXLancer→Rigid). This objects acts as a group to hold different elements within: meshes for LODs, meshes for collision hulls, hardpoints, etc.

Part names must be unique for model, within ASCII character range and maximum 64 characters.

Hardpoints

Equipment, effects and other objects are attached to models via hardpoints. Freelancer has three types of hardpoints: fixed, revolute and prismatic.

Fixed hardpoints are simple points locked in place relative to their parent part.

Revolute hardpoints allow for attached object to rotate across specified axis vector within minimum and maximum angles. Setting up rotation arc minimum and maximum to -360 and 360 will allow object to spin freely. Revolute hardpoints are typically used for guns and turrets.

Prismatic hardpoints were never used in game.

In 3ds Max hardpoints are represented by Hardpoint helper object (Command Panel→Create→Helpers→MAXLancer→Hardpoint).

Hardpoint names must be unique for model, within ASCII character range.

Meshes

Each rigid part in a model may have different number of detail levels, for example Root part may have 3 levels while engine part may have 2.

It is not necssary to make a full set of LODs for every part but it is still highly recommended to do so for performance reasons, especially for large models with lots of materials and triangles. While modern graphics cards may be many times more powerful it is still relatively easy to saturate draw calls by having a lot of detailed models.

3ds Max provides multiple ways to progressively reduce geometry complexity and there are many third-party plugins providing similar functionality.

A part may have no meshes at all, useful to group multiple other parts for animation purposes.

Model parts provide only a reference to mesh and while mesh data is typically stored within model file this isn't the case for a number of files in user interface.

In 3ds Max LOD meshes are represented by Editable mesh object with Level of Detail attributes. Editable poly and other types of meshes will not be exported so make sure mesh objects are converted to right type.

Mesh object name isn't used in exported model, it can be anything, but it is recommended to add suffix specifying what level it is and/or arrange LODs into 3ds Max layers.

To assign Level of Detail attributes to Editable mesh:

1. Open MAXLancer sidebar.
2. Select Edtiable mesh.
3. Press Set button below Level of Detail label.

Avoid mixing fully opaque and transparent materials in same mesh. Split faces using transparent material(s) into separate Editable mesh and separate model part.

Materials

To import materials and textures into scene:

1. Click on Import Materials
2. Select material library file to import
3. Select which materials found in library to import
4. Press Import button

To export materials and textures from selected scene objects:

1. Select meshes in scene
2. Click on Export Materials
3. Check the output list of material
4. Press Export button

An extra caution should be exercised when it comes to material names. As with objects in scene 3ds Max permits multiple materials to have same names and this can cause problems later.

Freelancer stores and retrieves materials by name, once a material has been loaded it will not be overwritten until material library is flushed, which typically occurs when switching between systems and scenes. As such you must avoid different materials having duplicate names.

This doesn't mean that for every material you use must provide unique name. If you use existing materials and don't alter them then continue to use their original names and reference original .mat files in object archetypes (such as ones defined in solararch.ini, shiparch.ini, etc).

When exporting rigid model you have an option whether to embed materials and textures into resulting model file. If these resources are absolutely unique to the model and there is no plan to re-use them in other models then you may as well embed them there. Otherwise materials and textures should be exported into separate .mat file and linked to in object archetype definition. A few exception exists where regardless of use case for materials and textures you must embed these resources into model file: starspheres and cutscene objects referenced in petaldb.ini.

Deformable models always embed materials and textures as there's no mechanism to reference external libraries in body parts definitions.

To create material supported by MAXLancer exporter:

1. Open Render→Materials→Compact Material Editor.
2. Change type of material by clicking on Standard button and selecting DirectX Shader.
3. Click on shader file path button and navigate to MAXLancer shaders folder.
4. Select .fx file and select material type in techniques list.

Textures

Textures are expected in uncompressed Targa (.tga) format with 24 or 32 bit depth, or DirectDrawSurface (.dds).

Internally Freelancer stores inverted DDS textures. Only DXT compression is supported. Targa RLE compression is unsupported.

Depending on filename pattern textures can be compressed automatically upon exporting materials.

Wireframes

Wireframe for model is drawn in HUD contact targeting menu. It consists of lines drawn between vertices of display mesh. As it uses display mesh data it can only be drawn between vertices of a LOD mesh. Each part in rigid model can have only one wireframe and each part wireframe is limited to maximum of 32768 lines.

Wireframe can be made using Line shape object to draw lines between vertices of a LOD mesh. Alternatively visible edges can be used to create wireframe by toggling Use Edges for Wireframe in LOD mesh parameters.

MAXLancer will discard duplicate lines (lines drawn between same two coordinates where another line was already taken).

Import Rigid Model

To import rigid model click on Import Rigid icon in MAXLancer toolbar and select file to import.

Any missing meshes, materials and textures will prompt to locate and search through additional files for them. Materials and textures are typically stored either in same folder or a parent folder.

If rigid model has no .sur file in the same folder matching filename or .sur contains no parts to match any parts in model file the Surface Components block will be disabled.

It is not necessary to arrange model object into layers for exporting but it is recommended to do so show/hide objects quicker to work on different types objects.

Export Rigid Model

To export rigid model select root rigid part helper and click on Export Rigid icon in MAXLancer toolbar.

Children parts must have Fixed Joint, Fixed Axis Joint, Sphere Joint or Loose Joint transform controller.

Inspect tree list to the left to ensure all elements of model are detected correctly.