Exporting-a-weapon-for-Xonotic.md

   1 _This article looks complete, [old methodology](#old-methodology) isn't a very complete section due to  the obsolescence_
   2
   3 # Modeling requirements
   4 ### To follow this, you need knowledge about modeling using Blender
   5
   6 Blender version recommended: 2.79b or later
   7
   8 You need [dpmodel](https://icculus.org/twilight/darkplaces/files/) to convert SMD files:
   9 - [dpmodel tool](https://icculus.org/twilight/darkplaces/files/dpmodel20091008beta1.zip)
  10
  11 Requires these following tools (addons) for Blender:
  12 - [IQM exporter](https://gitlab.com/xonotic/iqm) to export IQM files.
  13 - [Source Tools (SMD importer/exporter)](http://steamreview.org/BlenderSourceTools/archives/) to import/export SMD files.
  14
  15 Optional:
  16 - [MD3 importer/exporter](https://github.com/neumond/blender-md3) to import/export MD3 files.
  17
  18 ***IMPORTANT NOTE**: if you want to contribute, it's strongly important use 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!*<br/>
  19 *If the version of a file is later than 2.79b, we may to make some tweaks and become tedious.*
  20
  21 # Introduction to export a weapon
  22 **Keep in mind about weapon systems:**
  23
  24 - `g_*.md3`: model mesh for item pickup spawn and third person.
  25 - `h_*.iqm`: for first person animations (if this step used [old methodology](#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](framegroups), you can look `*.iqm.framegroups` opening a notepad to see what animations contain and the keyframes where these are set)
  26 - `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.
  27
  28 More info: [Weapon modeling system](Weaponsystem)
  29
  30
  31 # Textures and UV map
  32
  33 ### For MD3 exportation:
  34
  35 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).
  36 <br />
  37 Keep in mind, when you've done your UV map in your model, you need to set this:
  38 <br />
  39 <br />
  40 <img src="uploads/efee46a2a80a232ebe5fa63e30f4e2d9/Md3exp.png" alt="Md3exp" width="300" />
  41 <br />
  42 Texture must:
  43
  44 - be of **Image** type
  45 - mapping type **UV**
  46 - have UV map assigned
  47
  48 otherwise resulting data block will be filled with zeroes.
  49 <br />
  50 <br />
  51 <img src="uploads/c48fb7565453eab24faca2d6ffec4347/Md3_textures.png" alt="Md3_textures" width="360" />
  52 <br />
  53 <br />
  54 If you didn't this, the model will be invisible and it won't be able to interact shaders.
  55 <br />
  56 <br />
  57 [Blender reference about UV in MD3](https://archive.blender.org/wiki/index.php/Extensions:2.6/Py/Scripts/Import-Export/MD3/)
  58
  59 # Starting to export
  60
  61 ## Modifiers
  62
  63 Keep in mind, you need to set these modifiers for the mesh/model object:
  64
  65 <img src="uploads/447f6abe0f73c6d6cadce97e4ed66e8b/blendermodifiersiqmandmd3.jpg" alt="blendermodifiersiqmandmd3" />
  66
  67 ## Bones and animations
  68
  69 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.
  70
  71 `tag_Somename` is another one, you can add if you need some optional animation in this bone. (Not useful for [old methodology](#old-methodology))
  72
  73 Moreover, watch out about position and rotation. `h_*.iqm` alterates the position and rotation of `v_*.md3`. The positions may not be equal.
  74
  75 `g_*` and `v_*` MUST contain one bone. The animations can't be included. It isn't like `h_*`.
  76
  77 Required animations:
  78 - `fire`
  79 - `fire2`
  80 - `idle`
  81 - `reload`
  82
  83 ## Textures and materials
  84
  85 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):
  86 ```
  87 crylink_new // your material/texture name
  88 {
  89         dpreflectcube cubemaps/default/sky
  90         {
  91                 map textures/crylink_new.tga // your attached texture from Blender
  92                 rgbgen lightingDiffuse
  93         }
  94 }
  95 ```
  96 Note: `crylink_new` must appear in the material and texture.
  97 <br/><br/>Material:<br/>
  98 <img src="uploads/abef98eaddd7c61bec7eb467efe4c3fe/crylinkblendermaterialsample.jpg" alt="crylinkblendermaterialsample" width=920 />
  99 <br/><br/>Texture:<br/>
 100 <img src="uploads/ca88b1a8cbab9b9c5b81ef43bb9809f3/crylinkblendertexturesample.jpg" alt="crylinkblendertexturesample" width=920 />
 101 <br/>
 102
 103 # New methodology
 104
 105 You can make optional customized animations adding bones for the animations.
 106
 107 ## SMD (includes IQM converter and dpmodel guide)
 108
 109 Use Source Tools addon in Blender to export the model and animations.
 110
 111 - For `h_*`:<br/>
 112 Select the mesh and 1 animation and click Export, you need to export all animations one per one:
 113 <br/><img src="uploads/3775545047aa58d6e4fcb37df4f500a1/blenderSMDexport1.jpg" alt="blenderSMDexport1" width=380 /><br/><br/>
 114 Repeat the process:<br/><img src="uploads/b7c8b250fc1af6b30c999506e7143930/blenderSMDexport2.jpg" alt="blenderSMDexport2" width=350 /><br/><br/>
 115 <img src="uploads/9e9efa19232d1c47fd982ad0da2eb1df/blenderSMDexport3.jpg" alt="blenderSMDexport3" width=350 /><br/><br/><img src="uploads/2c929b6993d5e370c1d5498a03cb4ba8/blenderSMDexport4.jpg" alt="blenderSMDexport4" width=350 />
 116 <br/><br/>
 117
 118 - For `g_*` and `v_*`:<br/>
 119 Just select the mesh:
 120 <br/><img src="uploads/ec37639792378bb6ef9684b19d45a056/blenderSMDexport5.jpg" alt="blenderSMDexport5" width=350 /><br/>
 121
 122 Use `iqm.exe` from [IQM exporter](https://gitlab.com/xonotic/iqm), in Windows, in CMD execute for convert SMD to IQM for `v_*` and `g_*`: <br/>`iqm v_myweapon.iqm v_mesh.smd`
 123 <br/>`iqm g_myweapon.iqm g_mesh.smd`
 124 <br/><br/>Linux: `./iqm.exe g_myweapon.iqm g_mesh.smd`
 125 <br/>`./iqm.exe v_myweapon.iqm v_mesh.smd`
 126
 127 Rename extension to MD3: <br/>`g_myweapon.iqm` to `g_myweapon.md3`<br/>and `v_myweapon.iqm` to `v_myweapon.md3`
 128
 129 Use dpmodel tool to generate `h_myweapon.dpm` and `h_myweapon.dpm.framegroups`, in command line execute: `dpmodel yourconfig.txt`
 130 <br/>More info explained about dpmodel tool: [dpmodel](dpmodel)
 131 <br/>Rename extension to IQM: `h_myweapon.dpm` to `h_myweapon.iqm` and `h_myweapon.dpm.framegroups` to `h_myweapon.iqm.framegroups`.
 132
 133 Save those compiled model files into `models/weapons/` folder where they belong.
 134
 135 **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
 136
 137 ## Export troubleshooting
 138
 139 - Spamming CSQC errors:<br/>
 140 If you received spamming errors like that:<br/>
 141 <img src="uploads/1f769ede89975be78d88eaad1b062a3d/spammingerrorstagweapon.jpg" alt="spammingerrorstagweapon" width=450 /><br/>
 142 It's because you didn't do correctly the steps after exporting the models. Remember, `g_*` and `v_*` MUST contain one bone.
 143
 144 - Broken shadow artifacts (enabled with `r_shadows 2` and disabled `r_shadow_shadowmapping 0`):<br/>
 145 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.
 146 <br/>Reference: https://gitlab.com/xonotic/xonotic-data.pk3dir/-/issues/2667
 147
 148 - When exporting to IQM, get duplicated names in the texture:<br/>
 149 <img src="uploads/cdb90908aab4a52580019c871a936156/duplicatedtexturenameloadingerror.jpg" alt="duplicatedtexturenameloadingerror" width=700 /><br/>
 150 Take a closer look what is telling here:<br/>
 151 _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)._ <br/><br/>
 152 When you export to IQM, you need to watch out that detail after selected File > Export > Inter-Quake Model (.iqm, .iqe).<br/>
 153 Pay attention to this [section](##textures-and-materials) when you need to export correctly, the material/texture(image) should be one thing, in Export IQM > Materials: > select `material` or `image` instead `material+image-ext`.<br/>
 154 <img src="uploads/4fa75dca8ebb724b89d5fd5513fd2787/exportiqmiqeblenderdetails.jpg" alt="exportiqmiqeblenderdetails" width=200 /><br/>
 155
 156 # Old methodology
 157
 158 *Note: this section is obsolete.*
 159
 160 **IMPORTANT**: In this methodology, you can't make cool animations with separated objects, because `h_*.iqm` here is a plane mesh with bones.
 161
 162 Note: the model should be rotated as YXZ, instead being XYZ. Because the tip of the weapon is Y, horizontally is X.
 163
 164 `tag_weapon` is a MUST bone for this methodology.
 165
 166 ## MD3
 167
 168 Before to export, you need to select all objects in the scene. (Pressing A, seeing all objects highlighting orange or red)
 169
 170 <img src="uploads/f3f39c9a06a408bffd5e48bc5e07eac6/exporttutorialMD3.jpg" alt="exporttutorialMD3" />
 171
 172 ## IQM
 173
 174 Before to export, you need to select all objects and bones in the scene. (Pressing A, seeing all objects highlighting orange or red)
 175
 176 <img src="uploads/7df860d73a6fae27408c8f0c024122c7/exporttutorialIQM.jpg" alt="exporttutorialIQM" />
 177
 178 <br/>
 179 <br/>
 180 There's a post from InsideQC Forums explaining about IQM:
 181
 182 For `h_*.iqm`, you will need to do this:
 183
 184 There is a simple way:
 185
 186 You just can use an iqm model like a regular mdl file, you only need to use each frame as a framegroup.
 187
 188 For example, if you have an iqm called "rocketlauncher.iqm" with 20 frames you need to create a framegroup file with notepad like this:
 189
 190 ```
 191 1 1 1 0
 192 2 1 1 0
 193 3 1 1 0
 194 4 1 1 0
 195 5 1 1 0
 196 6 1 1 0
 197 7 1 1 0
 198 8 1 1 0
 199 9 1 1 0
 200 10 1 1 0
 201 11 1 1 0
 202 12 1 1 0
 203 13 1 1 0
 204 14 1 1 0
 205 15 1 1 0
 206 16 1 1 0
 207 17 1 1 0
 208 18 1 1 0
 209 19 1 1 0
 210 20 1 1 0
 211 ```
 212 So you will save it with the name.
 213
 214 "rocketlauncher.iqm.framegroups" and place it in the same directory where "rocketlauncher.iqm" is located.
 215
 216 About the framegroups file (explained on [Framegroups](framegroups)):
 217
 218 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).
 219
 220 The second number represents how many frames is in that specific frame group.
 221
 222 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.
 223
 224 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.
 225
 226 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)
 227
 228 Reference: [IQM animation framegroups (InsideQC Forums)](https://forums.insideqc.com/viewtopic.php?p=55949&sid=952cd347938ae5f2bb8bde276b5a35cd#p55949)
 229