Realistic Ragdolls Skeleton Converter - v0.4
by LogicDragon


=============
Introduction
=============

The Realistic Ragdolls Skeleton Converter (RRSC) program can be used to convert
skeleton nifs to have the same physics as in Realistic Ragdolls/Physics and Force.
This was created because certain mods, such as Universal Skeleton Nif that adds
new bones for wings, etc, are incompatible with Realistic Ragdolls as they modify
the same skeleton. So this program was created as a way to easily convent skeletons
to give them the same physical properties in Realistic Ragdolls.



=============
Requirements
=============

Windows Operating System (maybe Wine on Linux)



================================
Installation/Usage Instructions
================================

1. Extract to your Oblivion folder or a sub-folder
(this allows you to use ScanNif.exe to scan for nif files).

2. Place files to convert into the "in" folder.
This can be done automatically by running ScanNif.exe.


3. (Only if you ran ScanNif.exe) Open the "in" folder.

- Check that it has a Meshes\Characters\_male folder that includes two files,
skeleton.nif and skeletonbeast.nif. If not, extract ob_npc_skeletons.zip
into the "in" folder to add the original Oblivion npc skeletons.

- If your skeleton.nif and skeletonbeast.nif is from a previous version
of Realistic Ragdolls, extract ob_npc_skeletons.zip into the "in" folder
to replace them with the original Oblivion skeletons. Do not convert a
Realistic Ragdoll skeleton or it could cause problems.


4. Run RRSC.exe to convert the skeletons. Alternatively, run
"RRSC Collidable.bat" or "RRSC Non-Collidable.bat" if you only want to
convert collidable or non-collidable versions of the skeletons.

5. Copy converted nifs from "out" folder back to the Oblivion\Data folder
and overwrite. See below for package descriptions.


Notes:
- If you have Windows Vista or 7 and Oblivion is installed in the
program files folder, you may need to use "Run as Administrator" or disable UAC
for ScanNif.exe or RRSC.exe to work.

- When installing mods that modify npc skeletons, it is easiest to first copy
the contents of the "in" folder back into the Oblivion\Data folder. This reverts
the skeletons back into their original version. Now install the mod, delete the
"in" folder, and run ScanNif.exe and RRSC.exe to convert the new skeletons.

- Special note when processing VORB, it contains 1000+ skeleton nif files so it's
going to be slow. I recommend opening the "cfg" and deleting the config files
that you don't want to use so it doesn't spend more time than necessary.



===============
Uninstallation
===============

1. Copy the files in the "in" folder back to the Oblivion\Data folder.
This reverts them back to the original version.

2. Delete the RRSC folder and everything in it.



=====================
Package Descriptions
=====================

The following packages are created in the "out" folder

1. Original
These ragdolls have the same physics as standard Oblivion. Because they
the exact same, they are only created when generating collidable bodies.


2. Original_Body_Lifting
These ragdolls have the same physics as standard Oblivion but grab-points have
been added to the thighs. They still float when falling and have flailing limbs.


3. Friction_Increase_&_Less_Rigid
Ragdolls are now more rigid than standard Oblivion so they have less flailing limbs.
Also increases fall speed and increases friction to prevent sliding.


4. Friction_Increase_&_Less_Rigid_Body_Lifting
Same as Friction_Increase_&_Less_Rigid but with grab-points added to the thighs.
This is the package recommended by the 46&2 in Realistic Physics and Force.


5. Friction_Increase_&_More_Rigid
Makes ragdolls much more rigid than standard Oblivion so limbs will not flail too much.
Also increases fall speed and increases friction to prevent sliding.


6. Friction_Increase_&_More_Rigid_Body_Lifting
Same as Friction_Increase_&_More_Rigid but with grab-points added to the thighs.
This is most similar to Realistic Ragdolls v3.



=====================
Editing Config Files
=====================

This section is only useful if you want to create or edit the config files,
otherwise you can skip this section.

Config files are placed in the cfg folder and must have a .txt extension for them
to be recognized. The name of the config file is used as the name of the output
folder when RRSC is run. Each config file is made up of a series of blocks that tell the
RRSC how to process the nif files. Each block starts with the name of the NiNode that
contains the bhkRigidBody to modify followed by a series of statements that describe
the operations to perform on that bhkRigidBody.

[Default] is a special keyword that can be used in place of a NiNode name to tell
the RRSC to apply the modifications to every bhkRigidBody in the skeleton.

Comments can be added by placing a '#' character at the start of a line.
Only single line comments are accepted.
ex.
# This is a comment


Each statement has the following format:
[AttributeID] [Operator] [Value]

ex.
MaxLinearVelocity = 1000
This sets the MaxLinearVelocity to 1000


[AttributeID]
The AttributeID can be any of the following, make sure that there
are no spaces and it is case sensitive. This program allows you
to modify most of the physics attributes in the bhkRigidBody.

AttributeID - Description
---------------------------------
Inertia - Defines how the body's mass is distributed
Mass - The body's mass
LinearDamping - Damping value for linear movement
AngularDamping - Damping value for angular movement
Friction - The body's friction
Restitution - The body's restitution (or elasticity)
MaxLinearVelocity - Maximal linear velocity
MaxAngularVelocity - Maximal angular velocity
PenetrationDepth - The maximum allowed penetration


[Operator]
There are four operation types (Inertia only supports Multiplication)
= (Assignment), + (Addition), - (Subtraction), * (Multiplication)


[Value]
The Value can be any floating point number (ex. 3.14159)



=======================
Problems and Solutions
=======================

1. ScanNif.exe or RRSC.exe does not work

If you have Win7 or Vista and Oblivion is in the program files then
there could be a conflict with UAC. Try using "Run as Administrator"
on the exe file or disable UAC.


2. ScanNif.exe gives an error message:
Error: Cannot find Oblivion\Data folder

ScanNif.exe can only find the Oblivion\Data folder if RRSC is
extracted to the Oblivion folder or a sub-folder. Move the RRSC
folder into the Oblivion folder and try again.


3. You are using a non-bodylifting skeleton but it is still able
to be lifted from the thighs.

This is caused by converting a skeleton from a previous version of
Realistic Ragdolls that had bodylifting. Revert back to the original
Oblivion skeleton then convert.


4. The skeleton seems to have high friction and do not slide at all.
It doesn't even slide when going downhill.

This is also caused by converting a skeleton from a previous version of
Realistic Ragdolls. Revert back to the original Oblivion skeleton.


5. When using collidable skeletons, you do not collide with dead bodies
if the npc was previously paralyzed or knocked out.

This bug is fixed using the Havok Collision Fix included in
the Realistic Physics and Force package update.


========
Contact
========

PM me on TESNexus, username: LogicDragon

Note: when reporting bugs, please post the
operating system that you are using.



===========
Change log
===========

v0.4 (7/12/11)
- RRSC can now generate collidable bodies.
- Added Inertia to the list of attributes that can be modified.

v0.3 (5/12/11)
- Initial Release


========
Credits
========

Thanks to 46&2 for the original Realistic Ragdolls/Physics and Force mods
that this program is designed to convert skeletons to.

Thanks to the Oblivion Mod Gods team (RPG-BlackDragon and MrMuh)
for the original Havok Skeletons mod that added collidable bodies.

Thanks to the NifLib Team (Shon, amorilia, tazpn, xoalin)
for an excellent library that made it incredibly easy to edit nif files.



========
License
========

This program is licensed under the BSD 2-Clause:

Copyright (c) 2011, LogicDragon
All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.