Exporting a weapon for Xonotic

This article looks complete, old methodology isn't a very complete section due to the obsolescence.

Table of Contents

1. Modeling requirements

2. Introduction to export a weapon

3. Textures and UV map

4. Starting to export

4.1. Modifiers
4.2. Bones and animations
4.3. Textures and materials

5. New methodology

5.1. SMD (includes IQM converter and dpmodel guide)

6. Export troubleshooting

7. Old methodology

7.1. MD3
7.2. IQM

Modeling requirements

To follow this, you need knowledge about modeling using Blender

Blender version recommended: 2.79b or later

You need dpmodel to convert SMD files:

• dpmodel tool

Requires these following tools (addons) for Blender:

• IQM exporter to export IQM files.
• Source Tools (SMD importer/exporter) to import/export SMD files.

Optional:

• MD3 importer/exporter to import/export MD3 files.

IMPORTANT NOTE: if you want to contribute, it's strongly recommended using 2.79b version for compatibility cases, they need to open from this version. Share the .blend file using 2.79b or earlier , make sure to work properly from this version!
If the version of a file is later than 2.79b, maybe some tweaks would need to take and would become tedious.

Introduction to export a weapon

Keep in mind about weapon systems:

• g_*.md3: model mesh for item pickup spawn and third person.
• h_*.iqm: for first person animations (if this step used old methodology is a glue of v_*); the skeleton and the bones (the rigging and animation part). Keep in mind, you would need *.iqm.framegroups (more info: Framegroups, you can look *.iqm.framegroups opening a notepad to see what animations contain and the keyframes where these are set)
• v_*.md3: model mesh for third person; if h_*.iqm doesn't match with the animations needed of v_*.md3, it will generate spamming errors and bad pivot position (usually happens in the old methodology).

More info: Weapon modeling system

Textures and UV map

For MD3 exportation:

You have to add single material with single texture for every mesh object. Name of texture node will be written as is into MD3 data (suffixes like .001, .002 are ignored, feel free to use one texture for many meshes).
Keep in mind, when you've done your UV map in your model, you need to set this:


Texture must:

• be of Image type
• mapping type UV
• have UV map assigned

otherwise resulting data block will be filled with zeroes.



If you didn't this, the model will be invisible and it won't be able to interact shaders.

Blender reference about UV in MD3

Starting to export

Modifiers

Keep in mind, you need to set these modifiers for the mesh/model object:

Bones and animations

MUST contain tag_handle, tag_shell and tag_shot bone names attached. These tag_names MUST be attached, if not the model will cause errors.

tag_Somename is another one, you can add if you need some optional animation in this bone. (Not useful for old methodology)

Moreover, watch out about position and rotation. h_*.iqm alterates the position and rotation of v_*.md3. The positions may not be equal.

g_* and v_* MUST contain one bone. The animations can't be included. It isn't like h_*.

Required animations and in the correct order:

• fire
• fire2
• idle
• reload

Textures and materials

Please note that before exporting, about textures and materials, you have to assign the same as the script like this example shader file (crylink.shader file):

crylink_new // your material name
{
	dpreflectcube cubemaps/default/sky
	{
		map textures/crylink_new.tga // the texture you wanna display in-game, make sure to test in Blender!
		rgbgen lightingDiffuse
	}
}

Note: crylink_new must appear in the material.

Material:

New methodology

You can make optional customized animations adding bones for the animations.

SMD (includes IQM converter and dpmodel guide)

Use Source Tools addon in Blender to export the model and animations.

• For h_*:
  Select the mesh and 1 animation and click Export, you need to export all animations one per one:
  
  
  Repeat the process:
  
  
  
  
  
  
  

• For g_* and v_*:
  Just select the mesh:
  
  

Use iqm.exe from IQM exporter, in Windows, in CMD execute for convert SMD to IQM for v_* and g_*:
iqm v_myweapon.iqm v_mesh.smd
iqm g_myweapon.iqm g_mesh.smd

Linux: ./iqm.exe g_myweapon.iqm g_mesh.smd
./iqm.exe v_myweapon.iqm v_mesh.smd

Rename extension to MD3:
g_myweapon.iqm to g_myweapon.md3
and v_myweapon.iqm to v_myweapon.md3

Use dpmodel tool to generate h_myweapon.dpm and h_myweapon.dpm.framegroups, in command line execute: dpmodel yourconfig.txt
More info explained about dpmodel tool: dpmodel
Rename extension to IQM: h_myweapon.dpm to h_myweapon.iqm and h_myweapon.dpm.framegroups to h_myweapon.iqm.framegroups.

Save those compiled model files into models/weapons/ folder where they belong.

Conclusion: Sometimes, renaming formats can be useful to save effort. Note: it's a kind of weird way to do stuff, file formats are hardcoded in the gamecode rather than dynamically obtained. The issue of model resources was found here: https://gitlab.com/xonotic/xonotic-data.pk3dir/-/issues/2629#note_686988936

Export troubleshooting

• Spamming CSQC errors:
  If you received spamming errors like that:
  
  It's because you didn't do correctly the steps after exporting the models. Remember, g_* and v_* MUST contain one bone.

• Broken shadow artifacts (enabled with r_shadows 2 and disabled r_shadow_shadowmapping 0):
  To solve this, the possible way is exporting to IQM from Blender, selecting bone and mesh (both highlighted). Usually, this issue happens in g_* and v_* ones.
  Reference: https://gitlab.com/xonotic/xonotic-data.pk3dir/-/issues/2667

• When exporting to IQM, get duplicated names in the texture:
  
  Take a closer look what is telling here:
  The "Materials" option controls how material names are generated. "material+image-ext" combines the name of the material and the name of the UV-map image (without its extension or directory) to generate the material name, "material" uses only the name of the material, and "image" just uses the name of the UV-map image (without its directory).
  
  When you export to IQM, you need to watch out that detail after selected File > Export > Inter-Quake Model (.iqm, .iqe).
  Pay attention to this section when you need to export correctly, the material/texture(image) should be one thing, so do the following: Export IQM > Materials: > select material or image instead material+image-ext.
  
  

• Model scale animations aren't working:
  SMD format doesn't support bone scaling animations, although you try to compile them into dpmodel tool, it won't change nothing. More info here: https://steamcommunity.com/groups/BlenderSourceTools/discussions/1/152392786900223348/
  Same goes for IQM.

Old methodology

Note: this section is obsolete.

IMPORTANT: In this methodology, you can't make cool animations with separated objects, because h_*.iqm here is a plane mesh with bones.

Note: the model should be rotated as YXZ, instead being XYZ. Because the tip of the weapon is Y, horizontally is X.

tag_weapon is a MUST bone for this methodology.

MD3

Before to export, you need to select all objects in the scene. (Pressing A, seeing all objects highlighting orange or red)

And export the model to MD3. Attention: You can't export a model over than 8192 triangles/polys.

IQM

Before to export, you need to select all objects and bones in the scene. (Pressing A, seeing all objects highlighting orange or red)

For h_*.iqm, you will need to make a simple plane with a scale reduced to 0.01 and the following bones attached: tag_weapon, tag_shell and tag_shot.

There's a post from InsideQC Forums explaining about IQM:

There is a simple way:

You just can use an iqm model like a regular mdl file, you only need to use each frame as a framegroup.

For example, if you have an iqm called "rocketlauncher.iqm" with 20 frames you need to create a framegroup file with notepad like this:

1 1 1 0  
2 1 1 0  
3 1 1 0  
4 1 1 0  
5 1 1 0  
6 1 1 0  
7 1 1 0  
8 1 1 0  
9 1 1 0  
10 1 1 0  
11 1 1 0  
12 1 1 0  
13 1 1 0  
14 1 1 0  
15 1 1 0  
16 1 1 0  
17 1 1 0  
18 1 1 0  
19 1 1 0  
20 1 1 0  

So you will save it with the name.

"rocketlauncher.iqm.framegroups" and place it in the same directory where "rocketlauncher.iqm" is located.

About the framegroups file (explained on Framegroups):

The first number represents the start frame of the animation (.framegroups files always start at frame 0, some modeling software starts at 1, so you might have to subtract 1 for the start frame).

The second number represents how many frames is in that specific frame group.

The third number is the frame rate at which the sequence plays. This is independent from what the monsters "think" rate is, which I have set at 10 frames-per-second.

The fourth number is whether the frame sequence loops. 1 for true, 0 for false. The only frame groups that should loop are the standing, walking and running animations.

It becomes very tedious to make framegroups for models with really many frames, you can use this sample generated for the DarkPlaces model compiler. It will work in every iqm model (if you wan you only need to cut the specific number of frames in the framegroups file, but it will work anyway)

Reference: IQM animation framegroups (InsideQC Forums)