CleanModels3

This is a new version (3.5) of CleanModels3 that has not been available anywhere before. It has more features and runs faster than versions 3.2 or 3.3 that you might have used previously. Please read the updated user guide thoroughly, because this version is different.

What this package does

CleanModels 3 is a stand-alone program for detecting and repairing commonplace faults (and some not-so-commonplace faults) automatically in batches of NWN models. It  was originally developed specifically for tilesets but has since been broadened in scope to fixing all kinds of models.

It imports the models from a folder you specify, scans them for over a hundred known types of fault, applies fixing algorithms where it can and exports clean models into an  output folder. At the same time, it writes log files in the output folder listing all the faults it has identified, the fixes it has done and things that remain unfixed. It can import both  uncompiled (ascii) models and compiled (binary) models even if they are mixed up in the same folder but it always exports the models in ascii format notwithstanding.

The program is meant to be used in addition to all the other ways of checking and fixing models. It does not replace the sanity checks in NWMax nor the time-honoured  procedure of running the models through a compiler to see if they break. Rather, it does things that they do not do. Everything it does could, of course, be done manually by any  experienced modeller such as yourself; it just does it a lot faster and more reliably, thereby saving you time and trouble. It is especially good for fixing other people's models.  Sometimes, though, it might even surprise you by fixing bugs in your own models that you didn't even know were bugs.

When it imports a binary model, it does so directly without decompiling it first. It can usually tell which compiler (Bioware or nwmmdlcomp) created the file and may be able to unravel errors already introduced into the model by bugs in that particular compiler. (Okay, there aren't many and they are fairly obscure but it's one less thing for you to have to  think about). Thus, if you are working from compiled source models, it is better to let CM3 read them directly than to try to help by decompiling them with nwnmdlcomp (or  NWMax or NWNExplorer which use nwnmdlcomp) and then let it try to fix them; too much subtle information may already have been lost.

When exporting models, it will try to ensure that the resulting files are compatible with the NWN Engine, the Bioware Model Compiler, the nwnmdlcomp compiler and NWMax.  However, it knows the limitations of each of those and, if the model has any features that are not supported by one or more of them, it will warn you about it.

If you are fixing tilesets and you include any *_edge.2da files in the import folder, the program will read the 2da's to determine which tiles are listed there, so that it can strip out  of those particular models any features that don't function in edge tiles (such as walkmeshes). Otherwise, when it exports a tile model, it also exports a .wok file for it. The  walkmesh aabb data is rebuilt using a similar algorithm to the one in Joco's NWmax, that is in turn based on the Bioware one.

Installation

Unpack the download bundle to a convenient folder. The eight .dll files need to stay in the same folder as the .exe. Make a shortcut to the .exe and you're done. The executable is compiled as a 32-bit program but it will run on 64-bit Windows machines without needing any special compatibility settings.

The program is written in SWI-Prolog (available free from www.swi-prolog.org) but is packaged as a stand-alone executable. The eight dll files are a part of the SWI-Prolog package that can be redistributed freely with applications such as this. They are from version 6.2.6 of SWI-Prolog, which was the current version as of July 2013.

Note that, if you are updating from an earlier version of this program, you must use the dll files from the new package - the executable will not work with the older dll's.

A pdf user guide is included in the bundle. Please read it thoroughly. Twice.

This is unsupported software

This is the last version ever of CM3 and it will not be supported. If you find it useful, great. If it trashes your models, empties your bank account and runs off with your wife, there's no need to tell me - I won't be here.

Update: 2014-03-24

I'm making CM3 Version 3.5.2 available. It has better performance when welding verts and tverts in large meshes and there are some tweaks related to skin meshes, bones and robes. But it hasn't been very extensively tested so you might wish to install it in a separate folder from CM351 in case it breaks and you want to revert. The eight dll files have the same names as the ones in CM351 but they are different versions, so don't mix them up. There is a change list bundled in the CM352 download and the user guide pdf is included again for completeness but it's identical to the one in the CM351 download so you don't need to read it all again.

Changelist: cleanmodels351a to cleanmodels352

• The CM352 executable is built with a newer version of SWI-Prolog (7.1.10).
  The eight dll files in the package have the same names as in CM351 but they are later versions and you must keep the right set of dll's with the right executable. If you want to keep both versions of CM3.5 available, install then in different folders.
   
• When loading ascii files, wrong modelnames in newanim/doneanim lines are now tolerated and corrected.
  It is not uncommon to find models where the animations have been copied from another model without being correctly renamed. In previous versions of CM3 this was treated as a hard error and the model would have been rejected. Since it is simple to correct, this is now done automatically.
   
•  In character models, bitmaps are now only corrected if they are just the wrong race or phenotype.
  So in pfd2_robe123, for example, bitmap pfd2_robe123 will be corrected to pfh0_robe123 but bitmap my_chain02 will be left alone. This is to allow pieces of mesh within the model to be bitmapped with tga's through txi redirection.
   
• Fixed a bug in the code for reporting faceless trimeshes.
  It was failing to initialize the list of nodes that were reported to have been fixed.
   
• Welding of verts and tverts has been recoded to run much faster.
  It now uses a hashing algorithm and defers renumbering verts and tverts in face data until welding is complete. This runs in time O(n) rather than O(n²). Previously, the time to process a model with a thousand-face mesh was half taken up with looking for verts to weld. Now it isn't.
   
• Vertices on opposite sides of double-sided meshes are no longer welded because it looks bad in NWExplorer.
  Vertex normals are computed from the average of the face normals around each vertex, ignoring smoothing. Then, if two co-incident verts are facing opposite ways, they are not welded. The threshold is arccos(-0.9) = 154deg.
   
• The code for listing animation keys in the output has been toughened.
  If a key is missing from the sequence it will be skipped to allow the remaining keys to be listed. Previously, a missing key broke the list, the "endlist" line was never sent and the output was malformed.
   
• When importing binary models, a '.' is output as each animation is imported, then a final '.' at the end.
  Importing animations from binary can be relatively slow, so this is a visible indication that the program hasn't just hung.
   
• The check that forces robe supermodels to phenotype has been relaxed somewhat.
  It only does this now, if the stated supermodel is a possible phenotype of the form p[mf][adegho]? but is actually the wrong one. Robes (such as the DLA coats) that are supermodelled directly to their own animation files and don't conform to the normal pattern, are now understood.
   
• Embedded spaces are stripped out of bone names in weight lists.
  Basically, it concatenates words until it finds a number for the weight. There was a problem if you imported skinmesh Morrowind or Skyrim character models into 3dsMax and exported through NWMax with sanity checks turned off. Their bones have spaces in their names and this broke the weight lists in NWN. Running the exported model through CM3 will now clean this up.
   
• If a bone is named multiple times in a vertex weight list, the weights are now added to make a single entry.
  Previously, the multiple instances would each have counted against the 4 bones-per-vertex limit.
   
•  When reading binary models, resolving bone weights on skins is now deferred until all nodes have been loaded.
  This is to allow for anomalous models where the skin precedes its bones in the binary file. The only known example of this is xp2:pfh0_robe005.
   
• Skinmeshes are automatically reparented to the model base with the pivot at position zero, orientation zero.
  Because they should be, okay?
   
• The hard limit of 17 bones for a skinmesh is raised to 21 for character models.
  The game engine will accept 24 but more than 21 crashes the toolset and there is still a warning if 17 is exceeded because the model will not compile.