3D Graphics

You can use 3D models to represent ships in Naev by exporting them to GLTF 2, which is supported by Blender and most other major 3D modelling software. The base game uses 3D ship models, which you can find at the naev-assets-sources repository.

Setting Up Ship Graphics

To give a 3D ship graphics, you have to define them in the ship definition. For example, the Llama ship graphics are defined as follows

 <base_type>Llama</base_type>
 <gfx size="47">llama.gltf</gfx>

Here, the base_type indicates that this ship is a Llama, and can be accessed from Lua with ship:baseType(). It is also used to define the path to the graphics.

In the case of 3D, you want to specify the GLTF file path, which will be searched for in gfx/ship3d/BASETYPE/GFXNAME. So in the case of llama.gltf with base type of Llama, it will search for in gfx/ship3d/Llama/llama.gltf and error if it is not found. The size tag specifies how many pixels the big it will be scaled in-game.

Collision Polygons

TODO

Blender Tutorial

It is recommended to start with an existing ship blend from the naev-assets-sources, removing the meshes, and adding things as needed, however, it is also possible to start from scratch.

You are going to have to create 3 scenes first if not starting from an existing blend:

1. base: this scene contains the base ship, and will be used to represent the ship in-game.
2. engine: this scene contains the ship with engine glow effects, and is used for when the ship is accelerating.
3. meta: this scene contains meta-data about the ship, and, in particular, the ship weapon mount locations and trails.

It is important to use materials and effects which get exported to GLTF. Things like shader-based procedural materials DO NOT GET EXPORTED and will have to be baked into textures before exporting.

base Scene

This scene is straight forward and should contain the ship. The ship should be pointing in the -Y direction, and the scale doesn’t matter, since it will get re-scaled on loading. You should be using the Principled BSDF material or other materials that can be exported to GLTF.

engine Scene

You usually want to link the mesh from the base scene to the engine scene, so that the base ship is exactly the same. Afterwards, you can add meshes with emission textures to create engine jet glows and other effects as you deem fit. You can also bake the global illumination effects from the engine glows into textures and use them as emission textures of the Principled BSDF if you are so inclined, but do note that it is a pain in the ass with blender, and isn’t that noticeable anyway.

meta Scene

This scene is trickier, since you have to add special empty objects to indicate where mount points and engine glows are. This can be done simply by adding a new object of type Empty. The shape, scale, and rotation do not matter, only the position (translation) matters! Afterwards, you have to add a custom property on the Object tag of type String. For weapon mounts you use NAEV_weapon_mount, and for trails you use NAEV_trail_generator.

For weapon mounts, you want to set the string value to a number that represents the ID, starting from 0. So if a ship has 4 weapon mounts defined, you would want to add 4 NAEV_weapon_mount objects with values of 0, 1, 2, and 3. If a ship has more weapon mounts defined than those in the model, it will loop around so with 4 NAEV_weapon_mount, the 5th weapon mount defined would use the one with ID 0 again.

For trail generators, the string should be set to the name of a trail generator defined in trails/. For example, if you want to use a trail called default, you would set NAEV_trail_generator to a value of default.

A summary of the custom properties is below:

You can see the weapon mounts in-game by clicking on the weapon slots of the ship. You can see the location of the trail generators by running naev.debugTrails() in the console.

Exporting to GLTF

Once you are happy with the ship or you want to test, you can export to GLTF. To do this, select File → Export → glTF 2.0 (.glb/.gltf). Next you have to change the following settings:

1. Format: change from glTF Binary (.glb) to glTF Separate (.gltf + .bin + .textures).
2. Include: expand it and enable Custom Properties

The rest should be fine. Make sure you export all the scenes!

Next you can put the files in the location specified above. Note that the .bin and textures will be loaded relative to the GLTF path. For example, the Llama ship is exported entirely as below:

1. gfx/shi3d/Llama/llama.gltf
2. gfx/shi3d/Llama/llama.bin
3. gfx/shi3d/Llama/llama.avif
4. gfx/shi3d/Llama/llamaGLO.avif
5. gfx/shi3d/Llama/AO_bake.avif

Make sure to double check the .gltf file to see if all the custom properties and scenes are exported, blender is sometimes bad at that.

GLTF Tricks

You can have Naev auto-detect image formats by not using the file extensions. This allows Naev to use .avif files even though they are not specified in the official specification.

You can automate the process with a python script, which also uses glTransform to optimize the model and such. Save the file to export2gltf.py and you can call it with:

blender "path/to/file.blend" -b -P export2gltf.py

It will output the data in ship3d/, which is directly what you should put in gfx/ship3d/.