1Extended modding feature overview
2#################################
3
4OpenMW supports some extended modding features out of the box.
5These features can conflict with mods, and such situations should be handled as any other mod conflict by patching the mods themselves.
6The engine itself does not provide any kind of blacklisting of incompatible mods.
7
8
9Native herbalism support
10------------------------
11
12In OpenMW it is possible to add one or more NiSwitchNodes with a ``HerbalismSwitch`` name.
13Every switch node should have at least two child nodes (the first one represents the unharvested container, the second one - the harvested container).
14If an organic container's mesh has such nodes, it is considered to be a plant. During activation, a window with the plant's content is not shown,
15OpenMW transfers the contents directly into the player's inventory, triggers a theft crime event if the plant is owned and toggles the harvested model state.
16
17It is also possible to use scripts with ``OnActivate`` command for such containers. For example, when player needs a tool to harvest a plant (e.g. a pickaxe for ore).
18
19Keep in mind that the collision detection system ignores switch nodes, so add a ``RootCollisionNode`` or ``NCO`` NiStringExtraData to harvestable meshes.
20
21Advantages of described approach over old herbalism mods:
22
231. There is no need to spawn separate "harvested" objects
24
252. There is no need to attach a script to every container
26
273. It supports an ownership check (the original engine without MWSE does not)
28
294. It does not alter original respawn mechanics
30
31An example of mod which uses this feature is `Graphic Herbalism`_.
32
33Animated containers support
34---------------------------
35
36It is possible to attach opening/closing animations for containers. To do this, you need to create a KF-file for the container with the following groups:
37
381. ``ContainerOpen`` (with ``Start``, ``Loot`` and ``Stop`` keys)
39
402. ``ContainerClose`` (with ``Start`` and ``Stop`` keys)
41
42The ``Loot`` key for ``ContainerOpen`` allows to play a part of opening animation in the background.
43
44For example, with the following setup, the opening animation has 1.0 sec duration and shows the container window in the middle of opening animation:
45
46::
47
48    0.0: ContainerOpen: start
49    0.5: ContainerOpen: loot
50    1.0: ContainerOpen: stop
51
52It is also possible to attach opening/closing sounds to container's animations:
53
54::
55
56    1.0: ContainerClose: start
57    1.01: Sound: AC_dw_drawer_close
58    2.0: ContainerClose: stop
59
60The text key approach is the same as the one used for sound playback in animations in general
61Note that the sound starting time value is slightly higher than the closing animation start, otherwise sound will be played at the end of opening animation in this example.
62
63It is important to assign a RootCollisionNode to the container mesh -- the collision shape will depend on the animation state otherwise, and this can have a performance impact.
64
65Advantages of described approach over old animated containers mods:
66
671. There is no need to attach a script to every container
68
692. Part of the opening animation can be played in the background, so we do not waste the player's time
70
71An example of a mod which uses this feature is `OpenMW Containers Animated`_.
72
73
74Day/night state support
75-----------------------
76
77It is possible to add one or more NiSwitchNodes named ``NightDaySwitch``.
78Every such switch should have at least two child nodes
79(the first node represents the normal node state, the second one represents the node state during night,
80the optional third node represents the node state during daytime in interior cells).
81
82The behavior of such a model:
83
841. During the day in exteriors, it is in the "normal" mode (child 0).
85
862. During the night in exteriors, it is in the "night" mode (child 1).
87
883. During the day in interiors, it is in the "normal" mode or "interior day" mode (child 2) depending on weather.
89
904. During the night in interiors, it is in the "normal" mode.
91
92The actual state toggling time depends on the sunrise/sunset time settings in `openmw.cfg`:
93
94::
95
96    fallback=Weather_Sunrise_Time,6
97    fallback=Weather_Sunset_Time,18
98    fallback=Weather_Sunrise_Duration,2
99    fallback=Weather_Sunset_Duration,2
100
101These settings lead to the "night" starting at 20:00 and ending at 6:00.
102
103The engine checks if the weather is bright enough to support the "interior day" mode using the Glare_View setting. If it is >= 0.5, the engine considers the weather bright.
104
105::
106
107    fallback=Weather_Clear_Glare_View,1
108    fallback=Weather_Foggy_Glare_View,0.25
109
110With these settings, the "interior day" mode would be used for Clear weather, but would not be used for Foggy weather.
111
112Keep in mind that the engine will not update the weather type after a teleportation to a different region if the player did not move to an exterior cell in the new region yet.
113
114This feature can be used to implement street illumination, glowing windows, etc.
115
116Advantages of the described approach over old mods with glowing windows:
117
1181. There is no need to spawn additional objects for day and night mode
119
1202. There is no need to attach a script to every switchable object
121
122An example of a mod which uses this feature is `Glow in the Dahrk`_.
123
124
125Per-group animation files support
126---------------------------------
127
128In the original engine it is possible to add a custom animation file to NPC to override some animations (usually idle ones).
129In OpenMW it is possible to override animations via the same file for all actors which use a given basic animation file.
130
131If you want to override animations for all biped actors (which use the xbase_anim.nif skeleton), you can put your animations in the
132``Animations/xbase_anim`` folder in your ``Data Files``. You can also have them in a data folder with a higher priority.
133In this case any biped actor without a custom animation will use your animations, but – if he has additional animations – they have a higher priority.
134
135For example, all biped actors in Morrowind normally use the same spellcasting animations, so overriding xbase_anim spellcasting animations is sufficient.
136If you want to override walking animations, you should override ``xbase_anim_female`` and ``xbase_anim_kna`` animations -- these are used for women and beast races, and
137– because they have their own walking animations – they override ones which come from ``xbase_anim`` and its loose overrides.
138
139To enable this feature, you should have this line in your settings.cfg:
140
141::
142
143    [Game]
144    use additional anim sources = true
145
146An example of a mod which uses this feature is `Almalexia's Cast for Beasts`_.
147
148
149Weapon sheathing support
150------------------------
151
152In OpenMW it is possible to display equipped, but not currently wielded weapons on the actor's model, including quivers and scabbards.
153
154This feature conflicts with old mods which use scripted scabbards, arrows with particles or decorative quivers (attached to the left pauldron, for example).
155
1561. Basics
157
158The minimum you need is the ``xbase_anim_sh.nif`` file from the `Weapon Sheathing`_ mod and this line in your settings.cfg:
159
160::
161
162    [Game]
163    weapon sheathing = true
164
165The ``xbase_anim_sh.nif`` contains default placement points for different weapon types.
166That way you'll get Gothic-style weapon sheathing for all biped actors (without quivers and scabbards).
167
1682. Scabbards
169
170For a scabbard to be displayed, you need a mesh with an ``_sh`` suffix. For example, if the weapon has a model named foo.nif, the scabbard model must be named foo_sh.nif.
171
172There should be an least two nodes in the sheath file:
173
174``Bip01 Weapon`` - represents the weapon itself (may be just a grip for sword, for example). It is not shown when the weapon is drawn.
175
176``Bip01 Sheath`` - represents scabbards, quivers, etc. It is shown always when the weapon is equipped.
177
178You can move or rotate nodes if the default placement from the ``xbase_anim_sh.nif`` does not look good for your weapon.
179
180If you want to exempt a specific weapon from using this feature, you can create a stub sheath mesh with just one root node.
181
182If you want to use the common weapon mesh, but with custom placement, you can create a sheath mesh with an empty ``Bip01 Weapon`` node and move it as you want.
183
1843. Quivers
185
186To show the quiver for a ranged weapon, you need these nodes in the sheath file:
187
188``Bip01 Sheath`` node, as for scabbards
189
190``Bip01 Ammo`` node to show ammunition in the quiver
191
192``Bip01 Weapon`` to show the weapon itself (not needed for throwing weapons)
193
194The ``Bip01 Ammo`` should have some empty child nodes, to which the engine will attach ammunition nodes.
195
196The appearance and count of shown ammunition depends on type and count of equipped ammunition. If the ammunition has a wrong type (e.g. bolts for bow), it won't be shown.
197
198It is important to make sure the names of empty nodes start with ``"Bip01 "``, or the engine will optimize them out.
199
200An example of a mod which uses this feature is `Weapon Sheathing`_.
201
202
203Skeleton extensions
204-------------------
205
206It is possible to inject custom bones into actor skeletons:
207
208::
209
210    [Game]
211    use additional anim sources = true
212
213If this setting is enabled, OpenMW will seek for modified skeletons in the ``Animations/[skeleton name]`` folder in your ``Data Files``.
214For example, the biped creature skeleton folder is ``Animations/xbase_anim``, the female NPCs skeleton folder is ``Animations/xbase_anim_female``,
215the beast race skeleton folder is ``Animations/xbase_anim_kna``.
216Note that these are the third person view skeletons, and the first person view skeleton will have a different name.
217
218OpenMW scans every NIF file in such a folder for nodes which have "BONE" NiStringExtraData.
219It is recommended to give such nodes names that start with "Bip01 " so that the mesh optimizer doesn't try to optimize them out.
220Then OpenMW copies all found nodes to related skeleton. To determine the bone to which the new node should be attached,
221OpenMW checks the name of the parent node of the new node in the original NIF file.
222For example, to attach a custom weapon bone, you'll need to follow this NIF record hierarchy:
223
224::
225
226    NiNode "root"
227        NiNode "Bip01 L Hand"
228            NiNode "Weapon Bone Left"
229                NiStringExtraData "BONE"
230
231OpenMW will detect ``Weapon Bone Left`` node and attach it to ``Bip01 L Hand`` bone of the target skeleton.
232
233An example of a mod which uses this feature is `Weapon Sheathing`_.
234
235
236Extended weapon animations
237--------------------------
238
239It is possible to use unique animation groups for different weapon types.
240They are not mandatory, and the currently hardcoded weapon types will fall back to existing generic animations.
241Every weapon type has an attack animation group and a suffix for the movement animation groups.
242For example, long blades use ``weapononehand`` attack animation group, ``idle1h`` idle animation group, ``jump1h`` jumping animation group, etc.
243This is the full table of supported animation groups:
244
245+---------------+-------------------+------------------+----------------------+-----------------------+-----------------------+
246|  Weapon type  |  Animation group  |  Movement suffix |   Attack (fallback)  |   Suffix (fallback)   |      Attach bone      |
247+===============+===================+==================+======================+=======================+=======================+
248|  Short blade  | shortbladeonehand |        1s        |    weapononehand     |          1h           |      Weapon Bone      |
249+---------------+-------------------+------------------+----------------------+-----------------------+-----------------------+
250| Long blade 1H |   weapononehand   |        1h        |                      |                       |      Weapon Bone      |
251+---------------+-------------------+------------------+----------------------+-----------------------+-----------------------+
252| Long blade 2H |   weapontwohand   |        2c        |                      |                       |      Weapon Bone      |
253+---------------+-------------------+------------------+----------------------+-----------------------+-----------------------+
254|   Blunt 1H    |   bluntonehand    |        1b        |    weapononehand     |          1h           |      Weapon Bone      |
255+---------------+-------------------+------------------+----------------------+-----------------------+-----------------------+
256|   Blunt 2H    |   blunttwohand    |        2b        |    weapontwohand     |          2c           |      Weapon Bone      |
257+---------------+-------------------+------------------+----------------------+-----------------------+-----------------------+
258|    Axe 1H     |   bluntonehand    |        1b        |    weapononehand     |          1h           |      Weapon Bone      |
259+---------------+-------------------+------------------+----------------------+-----------------------+-----------------------+
260|    Axe 2H     |   blunttwohand    |        2b        |    weapontwohand     |          2c           |      Weapon Bone      |
261+---------------+-------------------+------------------+----------------------+-----------------------+-----------------------+
262| Blunt 2H wide |   weapontwowide   |        2w        |    weapontwohand     |          2c           |      Weapon Bone      |
263+---------------+-------------------+------------------+----------------------+-----------------------+-----------------------+
264|     Spear     |   weapontwowide   |        2w        |    weapontwohand     |          2c           |      Weapon Bone      |
265+---------------+-------------------+------------------+----------------------+-----------------------+-----------------------+
266|      Bow      |    bowandarrow    |        bow       |                      |          1h           |    Weapon Bone Left   |
267+---------------+-------------------+------------------+----------------------+-----------------------+-----------------------+
268|    Crossbow   |     crossbow      |     crossbow     |                      |          1h           |      Weapon Bone      |
269+---------------+-------------------+------------------+----------------------+-----------------------+-----------------------+
270|     Thrown    |    throwweapon    |        1t        |                      |          1h           |      Weapon Bone      |
271+---------------+-------------------+------------------+----------------------+-----------------------+-----------------------+
272
273Note that bows can be attached to the "Weapon Bone Left" bone if it is present in shooter's skeleton, and if it is not, "Weapon Bone" is used as a fallback.
274
275Also it is possible to add a "Bip01 Arrow" bone to actor skeletons. In this case OpenMW attaches arrows to this bone instead of ArrowBone in the bow mesh.
276Such approach allows to implement better shooting animations (for example, beast races have tail, so quivers should be attached under different angle and
277default arrow fetching animation does not look good).
278
279Groundcover support
280-------------------
281
282Groundcover objects is a special kind of objects (e.g. grass), which can be used to improve visual fidelity.
283They use these assumptions:
284
2851. Each object is independent, so part of objects can be removed from scene without causing graphical artifacts.
286
2872. Groundover should not have collisions.
288
2893. They are not important for some parts of game scene (e.g. local map).
290
2914. They can not be moved or disabled on the fly.
292
2935. They can not be interacted with.
294
295As result, such objects can be treated in the separate way:
296
2971. It is possible to tweak groundcover objects density.
298
2992. It is possible to safely merge such objects even near player.
300
3013. Such objects can be animated (to simulate wind, for example).
302
3034. Some parts of processing can be skipped.
304
305For example, we do not need to have collision or animation objects for groundcover,
306do not need to render groundcover on the map, do not need to render it for the whole visible area (which can be very large with Distant Terrain). It allows to increase performance a lot.
307
308General advices to create assets for this feature:
309
3101. Alpha properties from Nif files are not used, a unified alpha settings are used (alpha testing, "greater of equal" function, 128/255 threshold).
311
3122. Use a single NiTriShape in groundocver mesh, or at least use same properties (texture, alpha, material, etc), so OpenMW can merge them on the fly. Otherwise animations may not work properly.
313
3143. Smooth fading does not work for meshes, which have textures without alpha (e.g. rock).
315
316Groundcover mods can be registered in the openmw.cfg via "groundcover" entries instead of "content" ones:
317
318::
319
320    groundcover=my_grass_mod.esp
321
322Every static from such mod is treated as a groundcover object.
323Also groundcover detection should be enabled via settings.cfg:
324
325::
326
327    [Groundcover]
328    enabled = true
329
330.. _`Graphic Herbalism`: https://www.nexusmods.com/morrowind/mods/46599
331.. _`OpenMW Containers Animated`: https://www.nexusmods.com/morrowind/mods/46232
332.. _`Glow in the Dahrk`: https://www.nexusmods.com/morrowind/mods/45886
333.. _`Almalexia's Cast for Beasts`: https://www.nexusmods.com/morrowind/mods/45853
334.. _`Weapon sheathing`: https://www.nexusmods.com/morrowind/mods/46069
335