$Revision: 1.18 $
Copyright © 2003 Urpo Lankinen
NeverBlender package is distributed under an extremely free license.
Basically, the package is © 2003 The NeverBlender Contributors. It is copyrighted - not public domain.
You are allowed to distribute, modify and use the source code / scripts in any way you want. However, the copyright notices must remain as they are. You may add notes describing which parts you have changed to copies you distribute, but this copyright notice (and the COPYING and AUTHORS files) must accompany the distribution, and all copyright notices on the files must remain as they are.
There is no warranty whatsoever, expressed or implied. You are using this software at your own risk!
This documentation is supplied under the same terms, except that electronic or printed versions of the documentation need not to be accompanied by the COPYING and AUTHORS files, in case the file is distributed separate from the whole distribution. This whole copyright notice must be present, however.
Neverwinter Nights™ © 2002 Bioware and Infogrames (Atari). All rights reserved. Neverwinter Nights™, Dungeons & Dragons® and Forgotten Realms® are trademarks of Wizards of the Coast.
$Date: 2004/07/22 20:35:53 $
Abstract
This document describes the usage and philosophy of NeverBlender package, a package intended to make Blender modeller and the Neverwinter Nights™ computer game cooperate.
Table of Contents
Table of Contents
NeverBlender is a project to build some sort of bridge between Blender Foundation's Blender 3D modelling application and Bioware's computer game Neverwinter Nights™.
At the moment, NeverBlender is able to export models from Blender in Bioware .mdl format. There is also an importer script.
The general strategy is to have a single script file with a small library of reusable stuff. Quite simply, Open Script and Run It, that's it.
NWN features with direct equivalents in Blender are directly supported (or planned). Examples include UV editor use for texture coordinates and Blender's animation support for animations (at the moment, only attempted in importer).
NWN-specific data can be conveniently stored alongside your .blend since the data is stored in a normal Text.
Exports to ASCII MDL files.
Many (but not that many =/ ) NWN-specific properties, such as tile fade, are supported.
Capable of exporting Meshes, parented to a single Empty.
Supports texturing of the objects. You can normally texture the objects using Blender's own UV map editor!
Supports flat-shading and smooth shading of individual mesh faces.
It is quirky. You shouldn't use the scripts to do anything serious unless you're at least a little bit familiar with Blender, the NWN .mdl ASCII format, and preferrably also Python and especially Blender Python API.
But don't worry, I'm moderately skilled with Blender, don't know too much about the format, and Python is all Greek to me, yet I'm the author and got it working! =)
Neverwinter Nights is a game that I waited with a great anticipation as soon as I heard what kind of things were possible in it. It seemed like that if even fraction of the hype was true, that would be the game I had waited forever. Most of the computer RPGs I had played were either infinite in length but quite weak plotwise or on hackability (Nethack, for example), or with good and enjoyable plot but limited in length and content and with even less hackability (Baldur's Gate, for example). Now, NWN promised more than this: A plot-driven CRPG with advanced network play (with dungeon master support, even), and above all, a toolset that allows us to do stuff and render all "expansion sets" obsolte. (Weird, isn't it, that I'm really waiting for Shadows of Undrentide? =)
Now, as NWN was released, it was obvious to me that the toolset wasn't the tool to get the wildest dreams true. Sure it was the tool to create adventures, but the amount of building blocks was limited. And it really felt like building blocks. So few different blocks! I did appreciate the concept, but it felt like there still were limits.[1]
Now, later I found Eligio Sacateca's excellent Custom Content Guide, and realized that I can make more of the building blocks on myself! This book was really an eye-opener and definitely gave me more interest in creating more content.
Now, there is just one problem. NWN's official custom content tools rely on 3DS MAX, which is, from the point of view of a starving student, an Awfully Expensive Program. The other option, less official, is gmax. There are other modelling tools too.
Yet, none of these options are like the One True Modeller. I personally found Blender to be the most smoothly used program I've ever used - creating meshes with it is very very easy. Indeed, I'm one of those 3D modellers who learned that and then decided not to use anything else because Blender actually rules. Too bad I'm not a full-time 3D freak, otherwise I'd use Blender even more than I do now...
I first thought writing a script for Blender would be difficult. Yet, after I got ahead, I learned a few things: Firstly, the rumors of difficulty of getting anything done in Blender's Python api are greatly exaggerated (the documentation stinks, that's all), and Python is not as nice as the Python fanatics would like us Perl people to think. Not as ugly syntax, but fundamentally it's the same ugly stuff.
I'm surprised that NeverBlender has become basically working and sort of releaseable in such a short time, and I'm even more surprised that it actually works more conveniently than the competition. I recently tried modelling something again in gmax and found it rather annoying to copy things from the listener window - even more so when gmax was misbehaving if I tried to copy more than 10 lines at a time... Blender has a "listener window", yeah, but it also has access to Python's file I/O functions. =)
[1] My first intent was to "port" a PnP adventure from an old issue of a Finnish RPG magazine Sininen Lohikäärme, however, the supplied set of content was far too narrow. For example, in order to port 99% of adventures published in Finnish RPG mags, I would have needed the items that appeared in all of the adventuresf or some reason, such as "an erotic painting on wall" and "a beautiful young woman who is chained on altar"... though I don't know why they were included in the adventures in first place.
Table of Contents
There are two distinct branches of NeverBlender code. The released versions are guaranteed to do something at the time of the release, but are often lagging behind in development. Then, there's the development code, found in the Blender Projects Site CVS.
The easiest way to get NeverBlender is to go to NeverBlender's home page, or the NeverBlender Project Page. As of writing, latest release is Prerelease 2, which is not exactly a recent version. It is available through NeverBlender website. All further releases will be available in NeverBlender Project Page.
To get the most recent CVS version, you need a CVS client program. Windows version can be got from CVS home page, Linux versions are usually pre-packaged with the distribution. And are there MacOSX users who can live without Fink, which among other things, by the way, doth package CVS? (heck, even my sister needs Lincity...)
The following illustrates how to get the code from CVS:
$ cvs -d:pserver:anonymous@cvs.blender.org:/cvsroot/neverblender login Logging in to :pserver:anonymous@cvs.blender.org:2401/cvsroot/neverblender CVS password: (Just press enter) $ cvs -z3 -d:pserver:anonymous@cvs.blender.org:/cvsroot/neverblender co neverblender cvs server: Updating neverblender U neverblender/AUTHORS U neverblender/COPYING U neverblender/ChangeLog ...
After this, the code should be in the neverblender directory.
My original intent was to make every NeverBlender script a wholly self-contained package. However, this was not possible - the code became rather ugly even in my standards. I decided it was easy to split the code in separate modules and utilize an object-oriented approach.
Basically, NeverBlender requires Blender 2.28 or later (or any release with the New and Improved Python API). It may work on earlier Python APIs, but I wouldn't guarantee that. At the moment, I'm developing on Blender 2.32.
I develop NeverBlender on Windows version of Blender. You do, however, need Python 2.2.3 as well (Windows Python v2.3 doesn't want to coexist with Blender); My scripts use a couple of things not provided with the abridged Windows Blender library, and the importer cooks the shit out of it. Since most of the useful custom content tools seem to be working only in Windows, I absolutely insist that the code will work in Windows version of Blender, though. You don't need any weird UNIX-dependant things.
The installation is quite simple: You need to copy the lib directory, or its contents, wherever Blender sees it. The directory is named lib because Blender in Windows will also look in .\lib\ (that is, under directory lib under the current working directory). Archeological reasons, you know.
Sorry, this doesn't work. I got carried away. Looks like it works just fine in regular Python but not inside Blender. Goddamn it.
Well, I told you it was too easy? =)
This installation method is easiest because it doesn't need any weird environment variables or messing with system directories. This method works in Debian GNU/Linux. It may work on other Linux distributions. Some other dists may have similar method available. You may refer to the site.py file (in Debian, /etc/python2.3/site.py) and see if something similar works for your platform.
First, you need to put all Neverblender files to, say, /usr/local/lib/neverblender.
After this, you'll just need to do this command as root:
$ echo "/usr/local/lib/neverblender/lib" > /usr/local/lib/python2.3/site-packages/NeverBlender.pth
...and the libraries should be installed!
This feature is only partially supported the way it should, and it's only 0% elegant.
You can stick NeverBlender in /usr/local/lib/neverblender or symlink it there. It should work.
Should.
Easy way is to run Blender so that the NeverBlender scripts are in the current directory and library files are under it in lib. In all cases, Blender's Python interpreter will, by default, look for lib directory in current working directory.
In Windows version, Blender's work folder (in the shortcut) can be set to NeverBlender directory (you can create a new shortcut that has different working directory if you wish); In Linux, blender can be run on command line in NeverBlender directory.
This is probably the most easiest way to run Blender, but it has certain disadvantages - most notably you need to hunt around for your usual work folders.
A more flexible and far more comfortable way is to add the lib to your PYTHONPATH. This is definitely recommended. PYTHONPATH tells what directories to look Python libraries from.
As for finding where Blender/Python looks libraries from, you can use Blender's own built-in script for this task. You should start up Blender, go to Script Window, then choose ->->, then switch to Text editor and see the Text called system-info.txt. Scroll up and you should be able to see which directories are in your PYTHONPATH.
Now, Python has had a rather weird handling of PYTHONPATH over time. Some versions of Python seem to want that if you specify your own path, you also have to specify the previous contents there or they won't be found. The version I have right now at hand (2.3.5) seems to think that PYTHONPATH is, logically enough, added to "system" path, so you don't need to specify special contents.
In Windows98SE, this kind of spell is needed to be put in c:\autoexec.bat:
SET PYTHONPATH=c:\Python;...;d:\NeverBlender\lib
where NeverBlender is in d:\NeverBlender. (I don't know how to set the variable in Win2K or WinXP, probably something similar but entirely different...)
In Linux, when using bash shell, following works in ~/.bash_profile:
export PYTHONPATH=/usr/lib/python2.3:...:/opt/neverblender/lib
where NeverBlender is in /opt/neverblender.
In general, you probably want to try first setting the PYTHONPATH to just the directory where you installed it to, for example,
SET PYTHONPATH=d:\NeverBlender\lib
in Windows or
export PYTHONPATH=/opt/neverblender/lib
in Linux.
Then start up Blender and do the path-show script trick mentioned earlier. You should see a lot of Python system directories and your directory added to the whole lot. If you only see your added directory, remove the setting, add all paths that you see when you run the system info script, and on top of that your own directory.
The files nwnmdlexport.py and nwnmdlimport.py can be just about anywhere you choose. However, you should put them, or at least a symbolic link to them, to ~/.blender/scripts/ directory (or wherever you keep your scripts - check your Blender settings). This will make the scripts appear in the Blender menus.
Table of Contents
It is highly recommended to not save your work after you have used NeverBlender.
In other words, the following work cycle is highly recommended: first save your work, then run the exporter; if the result is unsatisfactory, use -> (Ctrl-O) to open the last saved version, work from there, again save, and so on.
The reason is that while NeverBlender tries to avoid touching your data, it somehow might, and there are (as noted elsewhere) no warranties on software these days. And think about it - this is just beta software right now, anyway! Who knows what it does to your data...
In fact, I guess the best possible way to use the exporter is to quit right after running the exporter, and if there are any needs to edit the thing later, restart Blender and use the Reopen Last trick mentioned earlier (or use file name on command line, or start Blender up by clicking file, or something).
MDL format itself is somewhat limited compared to the full feature set of Blender - which shouldn't be a surprise. You should use NeverBlender like all other low-poly things: Patience, care, and not getting too angry when the stupid game engine messes everything up while the exporter maker and game engine vendor point at each other. Patience is the most valuable thing a modder can have. The second most important thing is to say no to all deadlines, sticking to the "when it's done" schedule. And third... I don't know, I haven't been using this thing for that long yet.
There used to be time when this manual had separate sections for actual usage instructions and "bugs and limitations". Not so anymore, either because things are improving, or because there never will be a fix due to limitations of the system.
Modelling in NeverBlender could not be easier, but there are some things that must be considered. Basically, to create whatever you are creating, you create one or more Meshes.
It should be noted tha only Meshes are supported, and the Meshes should consist of triangle and quad faces. Anything bigger than that must be broken down manually. It doesn't really matter what the meshes are named, as long as their names do not have spaces (I think?) - also note that only the names of the Objects are used, not the names of the Meshes (in other words, in EditButtons, the relevant part is OB:Something, not ME:Something).
It should be also noted that the smoothing and flat-shading of objects should work normally! You can set faces smooth or flat using the EditButtons in the Edit Mode, as usual.
Once you have made your Meshes, you need to create an Empty. You should then give this Empty the name you want to give to this object in NWN - be it "merewidget" or "wplss_t_011". As mentioned, the Custom Content Guide is a wonderful work when considering the name of an object.
Next, you need to make this Empty of yours the parent of every Mesh you want to include in the object. Simply select your Mesh with mouse button, Then select the Empty with Shift-, and hit Ctrl-P. Repeat for each item.
Now, you should have an Empty that has Mesh objects as its children.
The object three can, unlike in the earlier versions of NeverBlender, actually have depth. Objects can be parented to each other.
Armatures aren't exported along with Mesh Objects. However, if you parent your Meshes to an Armature, the Meshes are parented to Armature's parent.
The script does not, in any way, check that the items are in any way conflictless and the tree builder will get the parent/child relationships all wrong if you give conflicting names. I do not know how NWN reacts if the items in NWN have conflicting names...
There used to be a requirement that the Mesh and Object must have the same name, but it has since been removed. At least in theory...
The scalings and rotations in Object Mode may or may not work. Therefore, it's recommended that you use Edit Mode to apply scalings and rotations to your object. Not only is it more versatile but also safer - you do, however, lose the benefit of having separate transformation, if this little figure of geekspeak is allowed.
First of all, only uniform scaling (x = y = z) is supported in Object Mode. While Blender supports it non-uniform scaling, NWN does not. This is a limitation of the .MDL format. If the Blender Object's scaling is not uniform, an average of the x,y,z scalings will be used. This feature is still present mostly to counter possible rounding errors, and shouldn't be relied on as a modeling tool.
Objects may be moved around normally in both Edit Mode and Object Mode.
Reason why all this is so: Blender has two separate datablocks for each mesh: Object and Mesh. Mesh stores locations of each vertex. Object stores position, rotation and scaling. Basically, the Mesh corresponds to the Trimesh's data, and Object corresponds to the Trimesh's properties, or sometimes the properties of the MDL itself.
Object's location is directly interpreted as the Trimesh "position" property. Object's rotation could be used as the "orientation" property, but as mentioned, it is not very well documented.
To find more about this topic, you can refer to what Blender manual says about this, or refer to Custom Content Guide (in v3.0, this topic is discussed on page 20).
The Custom Content Guide mentions some heavy voodoo technobabble on how to counter the evil world space transformation problems with ResetXForm and Reset Transform commands. Most of it went over my head. That's 3DMax for you! The thing is far easier explained in this modeling program of ours: In Blender 2.30 and later, the relevant commands can be found from -> menu. The most helpful commands here are ->-> (Alt-S) and ->-> (Alt-R), either of which should be enough to make the object look more or less what it should be. You can also try other transformation clearing commands if it looks like those might help. After that, try to stick to Edit Mode transformations until I fix the code that deals with stuff in Object Mode, if ever.
Exporter can handle triangle and quad faces. To process faces with more than 4 vertices, you need to break it down. One technique is to select the face's vertexes in Edit Mode and hit Shift-F to triangle-fill the face.
It should be noted that NeverBlender exports only single face side, and will not do double-sided faces. This is probably a feature, as doing double-sided faces properly would imply producing two faces instead of one - NWN only does single-sided faces. If you export a mesh, and note only a couple of the faces can be seen, try looking from the other side - only the front side of the face can be seen.
A good way to manage your normals is to keep Draw Normals set in the Mesh Tools 1 panel in EditButtons. If the normals point the wrong way, you can use Flip Normals in the Mesh Tools to flip the selected face's normals.
To specify NWN-specific properties of the mesh, and to control the general behavior of NeverBlender as well, you need to create a new Text called nwnprops.
This Text will hold all NWN-related properties of the objects. The format is rather simple. All empty lines and lines beginning with # are ignored. The format for all properties is this:
objectname.property=value
This consists of an object name, dot, name of an property of the object, equals sign, and the value.
Object properties naturally correspond to Meshes with same object name. There are properties that affect animations, and names of these "objects" are in form ANIM:name. There are also some objects that affect the generated model file as a whole, instead of any individual object. These are all properties of "object" SCENE.
Here are all properties that are recognized at the moment. You are strongly recommended to at least provide the base object name. Alternates are separated with | symbols.
Do note that animation properties are not actually supported by the exporter, simply because there is no code yet. This is just here in anticipation of the implementation, for specification purposes only. Since there is no implementation, the animation properties are subject to change. They already have a couple of times...
Possible NWN properties
The "base object name" of the scene. Its meaning is twofold: First of all, it specifies the name of the Empty that you have parented the Meshes to, and it is also used as the name of the object itself, and also used as the file name. If unspecified, well, I can't remember what happens. Probably it uses the selected object and coughs itself to death. Or maybe it starts a chain reaction that destroys the universe. It has been a long time since I tried.
The "classification" of the item. If not specified, it will be "Item", which is probably what you want at the moment.
The super model. The name of the model whence this model will inherit its animations and properties. Useful, in theory, for all those creatures. I think. I have never tried this option.
The object that shall be used to create the PWK. We will tell more about this later.
Comma-separated list of Actions that will not be rendered into MDL animations.
This is the directory the resulting NWN model files etcetera will be written. If not specified, everything will go to the current working directory.
If specified, the NeverBlender console log will also be written to the specified file.
The texture the object uses, without the .dds or .tga filename extensions. If specified, the exporter will take the UV texture coordinates and export them too. Otherwise the object will be single-colored (there's no way to control the color at the moment, though, you need to edit the file).
The tile fade property (whether or not the thing will disappear when your vision is obstructed by the object). None is the default. Fade is probably what you want for tall objects. I do not know what the other things do.
So, you want to use Blender object names like "HoeofDestruction_Head" instead of highly uninformative "wplss_t_051". Sure. With this property, you can. This property will rename the object in the resulting file. (Unimplemented!)
Specifies the algorithm with which the keyframes are generated for the .mdl.
"Constant" mode will generate keyframes based on ipos on constant intervals.
"IpoKeys" will generate keyframes only on places where they exist on ipocurves. This mode is unimplemented!
The default mode is "constant". While "ipokeys" may be more conservative, it will usually be less accurate, because the "slopes" of IPOs are not saved, which may be a little bit less interesting... (Unimplemented!)
In "Constant" keying mode, defines the interval between keyframes in frames. Default is 5 frames. (Unimplemented!)
Per-animation framerate setting. Default 25 frames/second. (It would default to whatever's set in RenderButtons, but it beats me on how to read that value from Python...) (Unimplemented!)
Use this to rename an animation to whatever you want. this is handy if you want to use your preferred naming of animations and find NWN's ideas ludicruous. Like if you prefer "peek_left" instead of whatever it's really called internally by NWN (too lazy to check and I don't have modelling experience, so nyah.) (Unimplemented!)
If you are creating a placeable object, it's often nice to create another mesh object that's at the ground level and specifies whether or not you can walk over that object. You can create this object easily (a plane, for example), then use the pwkobjectname property to point to this object. You should not parent this object to the Empty - doing so would also make it part of the MDL, which in turn would make the object visible in the model itself! PWK mesh itself, naturally, is not visible in the game.
I have no idea how this works at the file level. It appears to just work the way I described it. If all else fails, see if the normals point to right direction.
Animations are not yet supported at all, but they will be done through Actions with object-linked Armatures. More details will come as code will be written.
After you have made the object hierarchy and specified the properties, it's time to rock and roll!
This only applies to Blender 2.32 and later, if the script is installed correctly.
If the installation was successful, the exporter should be around in the -> menu. Just select ->-> to export.
Further fine-tuning of the menu options may occurr in the future. Even with the tweaks, rest assured it doesn't take a rocket scientist's skills to run this thing in the future either. =)
For Blender versions before 2.32, and optionally for the new versions, it's possible to run the script as a Text. This is slightly more inconvenient than running it from the menu.
First, it's best if you save at this point and work on a scratch copy. You want to work on the object, save your changes, then load the script and export all the way you please, and quit without saving - I've found this method of work best, as the script will not be included in the work file then.
To export, you may want to make sure the lib files are in right place, then flip to the text editor and open the nwnmdlexport.py file.
To run the script, type Alt-P.
As the smoke dissipates, there should be messages regarding the success on the console (in Windows version, they appear in Blender's log window). The object will be saved in the baseobjectname.mdl file. If you used a PWK object, it will be written to baseobjectname.pwk.
Table of Contents
Or, "Two great scripts that taste great together." What other scripts are out there that could make scripting easy and nice?
The Knife script or something similar might be useful when doing tile slicing á la Tile Slicer. The trick would be then to generate the meshes along which the tiles would be sliced... this probably calls for some further scripting.
Here is a list of things that should definitely work in the 1.0 release.
There absolutely needs to be some kind of support for animations. The action-based animation system is the way to do this thing. The animation support is relatively simple to code, but damn it, I don't have enough time. I keep wasting my time.
Possibly support for NWN emitters that is manipulated through Blender's particle effect system. (Having this feature would be unquestionably leet, because - well - is there proper support for this in gmax? Just hearsay. I have no real information.)
Now that there's a script menu in Blender, and other neat GUI tricks, it would be highly neat to have an app that would act as a GUI to all these NWN-specific settings. Hmm, is it possible to implement a Buttons panel (like the Blender WhateverButtons panels) in Python? That would be leet.
Rotation and scaling is sometimes weird, even with the uniform object scaling implemented. Likewise, rotations sometimes look pretty strange. These bugs need to be checked by someone with proper insight.
There should be better support for all those esoteric NWN object and trimesh properties (like the dreaded danglymesh property that makes... you know, Aribeth what she is, and all that).
Revision of the console logging. Perhaps there should be a static class that would handle message output - store log in file in various formats, etc etc. The default log format should also be thought of: What do all of those asterisks mean in the output, anyway?
Cleaning up and modularization of the code is going very well. Now if only it would go even further... Bleah. Everyone wants clean and modular code. Let's not talk more about this, OK? Maybe it will clean and modularize itself.
Some people I'd like to thank:
Bioware folks for the amazing game and their general caring, of course!
Ton Roosendaal for the greatest modelling program in existence =)
Eligio Sacateca for the Custom Content Guide
Anthony D'Agostino for the Blender Import-Export Suite that demystified a couple of things about Blender API...
Solias of Worlds of Neverwinter for the NWN model format documentation
Wayland, for the gmax mdl script (even when I don't really hack the maxscript syntax...)
Yann Vernier for slipping the importer under my door when I had a headache after thinking of how to write that one (well, not really, but the gesture was very syrprising anyway).
Also, I'd like to wave my "You were not really helping" picket sign toward:
Guido for the awful, frustrating, can't-find-a-damn-thing, my-eyes-truly-do-bleed format of Python docs...
...and Ton for picking Python as the Blender scripting language. (This makes him a high-ranked nominee of Geniuses Can Make Mistakes Award.)
(No, I don't hate these people. Just that they didn't particularly help, that's all. =)
My home page is at http://www.iki.fi/wwwwolf/. You may also visit my NWN page, and you are cordially invited to NeverBlender's home page.
I may be reached via E-mail at wwwwolf@iki.fi.
The importer was written by Yann Vernier (yann@algonet.se).