MAXLancer Tools is a set of MaxScript tools for Autodesk 3ds Max to import and export 3D models for Freelancer.
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.
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:
Path to Nvidia Texture Tools should point to binary folder (bin32 or bin64) containing executables.
Default settings in 3ds Max may overbright textures when previewed in viewport via DirectX shader. This will also affect exported textures.
Change base/arrow size of all hardpoint helpers in selection.
Replace Selection will replace all selected objects with hardpoint helpers while retaining transform matrix.
Applies common settings to all MAXLancer supported DirectX shaders.
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.
|Dummy Size||Specified size for helper display model.|
|Force Compound||Forces type of output model created from this part to be compound even in absence of subparts.|
|Force MultiLevel||Forces part to contain levels of detail setup in absence of multiple meshes for LODs.|
|Force LOD Center Zero||Forces bounding sphere center to zero. Enable for parts in starspheres.|
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.
|Constraint Type||Specifies type of hardpoint: Fixed, Revolute or Prismatic.|
|Axis||Rotation axis vector for revolute hardpoint.|
|Limits||Rotation arc minimum and maximum angles for revolute hardpoint.|
|Display||Specifies size for base and arrow of helper model.|
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:
Avoid mixing fully opaque and transparent materials in same mesh. Split faces using transparent material(s) into separate Editable mesh and separate model part.
|Primitive Type||Specifies mesh type for output. Currently only Triangle List is supported.|
|Automatic Center||Automatically calculates center for bounding sphere of mesh using Ritter algorithm. Otherwise pivot of mesh will be used for bounding sphere center calculation. Mesh bounding sphere is used in various cases, such center and range for displaying HUD wireframe and offset for starspheres.|
|Visible Edges to Wireframe||Visible edges in this mesh will be used to create HUD wireframe for output model.|
|Detail Level||Part detail level. Starting with level 0 being mesh at full detail quality and each level increment is expected to be reduction in quality. Freelancer assets typically have three or four for fighter ships, about six for capital ships and somewhere in between for stations. A single part of model may have only one mesh per level. Level number must be assigned incrementally starting with 0.|
|View Range||Specifies maximum view range for this mesh. These values are often overriden by LODRanges property in solar/ship archetype INIs.|
|Color and Transparency||Vertex data to contain vertex color and transparency values from 3ds max map channels -2 and 0 respectively. Both channels are required to export mesh!|
|Normals Acquisition Method||3ds Max provides different methods to read vertex normals. This option allows you to indicate which method should be used during export.|
|UV Maps||Number of texture maps. Freelancer uses maximum up two texture maps, but format allows up to eight channels. Corresponds to 3ds Max map channels from 1 to 8.|
|Mesh Library Name||Specifies explicit mesh library name to be used for mesh buffer data. Normally this field should be left empty.|
|None||Mesh buffer vertices will not contain normals (as such mesh typically will be fully lit). Typically starspheres don't need normals as they are unaffected by light sources.|
|Auto/Explicit Normals||Uses Edit Normals modifier to read vertex normals. Slowest but surest method.|
|Smoothing Groups||Reads vertex normals generated by smoothing groups but ignoes explicit normals. Use this method if mesh has smoothing groups but no explicit vertex normals.|
|Per-Vertex Normal||One normal per vertex. This value is set by default when importing models.|
To import materials and textures into scene:
To export materials and textures from selected scene objects:
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:
|SinglePassMaterial.fx||DcDt||No||Simple opaque material with diffuse texture and diffuse color tint.|
|DcDtOcOt||Yes||Transparent material with diffuse texture, diffuse color and opacity from diffuse texture alpha channel w/explicit value.|
|DtDtEc||No||Opaque material with diffuse texture, diffuse color and emission color.|
|DcDtEcOcOt||Yes||Transparent material with diffuse texture, diffuse color, emission color and diffuse texture alpha channel w/explicit value.|
|DetailMaterial.fx||BtDetailMapMaterial||No||Diffuse texture with overlay detail material on second texture map channel.|
|Nebula.fx||Nebula||Yes||Additive blending material. Used for starscapes.|
|GlassMaterial.fx||GlassMaterial||Yes||Transparent material with specular effect. Used for fighter cockpits.|
|NomadMaterial.fx||NomadMaterial||Yes||Transparent material with wrapped environment map. Used by nomad ships. Cannot be combined with regular environment map specified in archetype.|
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.
|*_dxt1.tga||Export as MIPS inverted DDS compressed DXT1.|
|*_dxt1a.tga||Export as MIPS inverted DDS compressed DXT1a.|
|*_dxt3.tga||Export as MIPS inverted DDS compressed DXT3.|
|*_dxt5.tga||Export as MIPS inverted DDS compressed DXT5.|
|*_rgba.tga||Export as MIPS inverted DDS uncompressed 32-bit RGBA.|
|*_mip0.tga||Export as sequence of MIP0 to maximum level found in matching filenames.|
|*.tga||Unmatched .tga exported as MIP0 only.|
|*.dds||Unmatched .dds exported as MIPS without vertical flip.|
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).
To import rigid model click on Import Rigid icon in MAXLancer toolbar and select file to import.
|Hardpoints||Import hardpoints as Hardpoint helper objects. Imported objects are assigned to Hardpoints layer.|
|Meshes||Import LOD meshes as Editable mesh with Rigid Mesh parameters. Imported objects are assigned to Level layer(s), Level0 is visible and subsequent levels are hitden by default.|
|Bounds||Imports LOD bounding volumes as helpers. For debugging purposes only.|
|Wireframes||Import HUD wireframes as Line objects. If meshes enabled they will be attached to associated LOD meshes. Imported objects are assigned to Wireframes layer.|
|Materials and Textures||Import materials and textures. First 24 materials are assigned to Compact Material Editor slots.|
|Compound Animations||Import animation scripts into animation layers. By default all atded animations layers will be muted and active layer will be reset to Base Layer.|
|Collision Hulls||Import part hulls from .sur file matching model filename as Editable mesh. Imported objects are assigned to Hulls layer. Individual convex hulls with matching ID will be merged into single mesh unless Hierarchy Volumes is enabled.|
|Keep Duplicates||Retains duplicate hulls in ancestor parts.|
|Group Hulls||Imports group hulls of surface part as Editable mesh. Imported objects are assigned to Wraps layer. Debug feature.|
|Center of Mass||Imports surface part center as Point object. Center of Mass is used for aiming reticle. Imported objects are assigned to Centers layer.|
|Boundary Extents||Imports surface part boundary box as Dummy object. Imported objects are assigned to Extents layer. Debug feature.|
|Hierarchy Volumes||Imports surface part bounding volume hierarchy (BHV) nodes as Surface node object and colors wireframe based on intersection tests. Imported objects are assigned to Nodes layer. Debug feature.|
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.
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.
|Hardpoints||Export Hardpoint helper objects into model hardpoints. Hardpoints must be children of rigid part helper objects.|
|Meshes||Export Editable mesh objects with Rigid Mesh parameters into model LOD meshes. Embeds mesh library into model file.|
|Wireframes||Export Line objects or visible edges of LOD Editable mesh into model HUD wireframes. Line knots (points) must be at vertices of editable mesh Line object is attached to. Knot position doesn't have to be bit perfect match. A part in model must have either one detail level mesh with Visible Edges to Wireframe toggled on or have Line object attached to it with knots snapped to mesh vertices.|
|Materials and Textures||Exports and embeds materials and textures into model file. When toggled off mesh groups will still refer to used material names.|
|Material Animations||Exports and embeds material animation into model file. Material animation must be stored within model file but materials may be stored externally and linked via material_library property in INIs.|
|Compound Animations||Exports and embeds animation library into model file. Available only to compound models with animation layers.|
|Timestamp Fragments||Adds timestamp marker to filenames of embetded .3db fragments in compound model.|
|Add Exporter Version||Adds Exporter version entry to model file. Text message can be customized in MAXLancer settings.|
|Collision Surfaces||Exports any Editable mesh found in Rigid part helpers but not assigned to LODs into surface file.|