Caliente's Body Slide v0.9 -- Body Shape Generator

Welcome to Caliente's Body Slide! 

This tool provides you with the cabability to quickly and easily generate the body shape you wish for Caliente's Body Mod.  It provides thousands of possible body configurations, all guaranteed to work with the Skyrim in-game weight slider. Furthermore, it uses a simple configuration and data format, allowing it to be expanded to work for any body or armor.  

-== Installation ==-

Simply copy the BodySlide directory (where you found this Readme) and it's contents somewhere on your hard drive.  BodySlide will attempt to use the Windows Registry when you run it to determine the location of the Skyrim data directory.  If skyrim is not found, or you wish to have BodySlide save files in a different location, you can easily edit config.xml to indicate an alternate location. 

NOTE : BodySlide does not come with or install textures for the bodies -- you will need to install a texture set separately.

-== Usage ==-

Using BodySlide is easy, though the interface is currently not designed for aesthetics.  Pardon our dust!  There's also no preview window yet (coming soon, hopefully)...

Before beginning, be sure to install textures for the body you wish to create.  CBBE slim textures are recommended for bodies with smaller chests, while CBBE Curvy textures are recommended for larger sizes.  NeverNude and BBP versions use the same textures as CBBE.

[[ Step 1 ]]:  Select a body type from the topmost drop down box.  Please note that the items in this list are based on an input type, and do not (For the most part) correspond to the body types originally offered with CBBE.  Those body settings are more closely related to the presets.
	Bundled Body Types (Female):
	
	-- CalienteBody
		The version most people will want to use. Includes all the CBBE sliders from slim to super silly huge.  Uses Caliente Body V3, be sure to install textures!
		
	-- CalienteVanilla
		A shape that closely matches the default skyrim body shapes.  NOTE: there are no visible sliders for this version, due to there not being size options, so while no presets or sliders appear, creating bodies will work!
		
	-- CalienteBody BBP
		An experimental bouncing breast support version, relying on CherryHotaling's Breast and Butt physics mod. (http://www.skyrimnexus.com/downloads/file.php?id=4888)  Please install her mod prior to installing these body shapes, or you will not see any bounce!
		
	-- CalienteNeverNude
		The CalienteBody shapes, clothed in the the default skyrim underwear.  Featuring all the same sizing options as CalienteBody
	
	-- CalienteVanillaNeverNude
		A version of CalienteVanilla that's wearing underwear. Like CalienteVanilla, this version does not have sizing options, and thus the slider and preset areas will be empty -- Creating Bodies will still work.
		
[[ Step 2 ]]: Select a Preset (if desired).  For all but the Vanilla options, this will set the sliders to a classic setting. NOTE It is possible to create your own presets, but there's no interface for doing so currently in BodySlide (future enhancement).  Presets are defined by XML files within SliderPresets folder if you're feeling adventurous.

[[ Step 3 ]]: Alter the sliders to suit your preferences (if desired).  For now, there's no preview option -- this is something planned for a future version, apologies.
The sliders are paired left and right and correspond to low weight and high weight setting in skyrim.  If both are set to the same value, the affected body part will not change throughout the range.  It is possible to set them 'backwards' so features shrink instead of grow if so desired.  
IMPORTANT: Some sliders will appear to be missing (BreastsSmall, for example with the CalienteBody CBBE preset).  This is NOT A BUG.  These sliders are dependent on other sliders for their shape to be correctly represented, and thus will only appear when the dependent slider is at the right position.  See below for slider dependencies.  If you activate a invisible slider, then change it's value, that changed value WILL affect the result, (causing somewhat deformed shapes) so be careful.
	Bundled sliders (for all but Vanilla bodies)
	
	- Breasts:  The basic breast size slider, featuring the standard CBBE breast size range (C-DD or so).  Note	CBBE uses about 20% for it's small breast size!
	- BreastsSmall:  The small breast size, activated when Breasts is at 0%.  ranges from about an A to C cup.  (As a friendly note, the word small here is not meant to indicate that C sized breasts on real women is actually a small size, but merely to indicate a relative size to the CBBE range :) )
	- BreastsSH: The original SillyHuge breast sizes, in no way meant to be realistic.  This slider is activated when 'Breasts' is at 100%
	- BreastsSSH: Super silly huge breasts for truly outlandish proportions. This slider is activated when 'Breasts' is at 100%, and is independent of BreastsSH.  The two silly huge sliders can be used together, in fact.
	- NippleSize: Allows for a smaller sized nipple, primarily for use with small breast sizes.  (Note, this slider is not included with NeverNude as nipples are covered by the bra)
	- Butt: The standard CBBE healthy bottom size; Big to Bigger. 
	- ButtSmall: A smaller bottom size (appearing boyish when below about 50%).  This slider requires 'Butt' to be at 0%.
	- Waist: a waist size slider that allows for a slightly thicker waist.
	- Legs: Thin to thicker leg sizes.
	- Arms: skinny to thicker arm thicknesses.
	- ShoulderWidth:  allows for somewhat less broad shoulders.  Recommended with small breasts and small bottom sizes 
	
[[ Step 4 ]]: Once you're happy with the slider settings, click 'Create Bodies'.  By default, the two size meshes will be installed in your Skyrim Data directory.  You can configure an alternate location in Config.xml if you wish.  PRO TIP: if you hold control while clicking Create Bodies, BodySlide will instead save the meshes in the same directory as the BodySlide.exe.


-== Configuration ==-

There are currently only a few available options for using BodySlide, found in config.xml, and  described here:

<SkyrimDataPath>  :  Normally, BodySlide looks in the windows registry for this information, but if that isn't working for you, you can uncomment this and set this value to have BodySlide look in a different place.  The trailing slash is required.

<MeshOutputPath>  :  Pretty much the same effect as skyrim data path. By default, this is set the same as SkyrimDataPath (As of right now there's no real reason for them to be different values -- but MeshOutputPath takes precidence)

<EnableGenerator>  : Set this to "true" to cause a 'Generate' button to appear in BodySlide. This button attempts to analyze a .nif file for differences amongst internal meshes and generate BodySlide shape key files.  Should this process work, *.bsd files will be created in a new GenerateOutput folder  See 'Expanding Body Slide' below for more info.

<GeneratorFile> : A nif file for use by the generator (ignored if EnableGnerator is false.)

<GenBaseShapeName> : a name of a NiTriShape in the Generator File that is used as a basis for shape key generation.  See 'Expanding Body Slide' below for more info.

-== Known Issues / future enhancements ==-
- No preview window
- UGLY UI.
- No easy method to save presets
- No Batch processing to cause multiple outfits to use the same settings
- Generator function is very picky about input and may crash or silently fail 
- Limited room for additional sliders, make some kind of scrollable area.
- Source code to be released with a future version under MIT license


-== Version History ==-0

0.9	 Initial, beta release with CBBE V3

-== Expanding Body Slide ==-

Body slide is created to be expandable, both to allow individuals to create and share their own favorite presets, and to allow mod authors to create mesh options for their releases or even alternate sizing options  for other author's work.


The functionality that allows this is somewhat rough around the edges, and performing the operations without intimate knowlege of what's happening may be an exercise in frustration.  Full documentation on this will be forthcoming eventually, but in the mean time, here's some basics to help the entrepeneurial spirits out there.

[Overview]

Body slide operates on skyrim.nif Files (and possibly Fallout Nif files), and leverages the format's vertex order coherency.  It reads in base shape data, modifies the vertices with shape key files, and saves the file.  It is critically important that the shape key files match vertex order with the input file.  How the shape keys are applied to the base shape is determined by the slider values -- simply percentage progression from base to shape key.
The shape key files are simple differences between a base shape and a morphed shape.  Stored as vector deltas, the shape keys can be applied in any number and in any order to get a consistent result. 

[Slider Sets] 
The basis for the slider definitions are in the SliderSets folder.  The XML files provide information about all the sliders that are supported for a given outfit/body type.  

The SliderSet is the basis for a group of applicable shape keys.  Typically the sets are functionally differentiated by unique qualities of the input file.  For instance, CalienteBody uses an input .nif file that has only one shape within, as opposed to CalienteBodyNeverNude, which has two.  This isn't a hard and fast rule, however.  CalienteVanillaBody uses the same base shape as CalienteBody but simply defines different sliders.

A slider set operates on a single source file .nif located in a 'setfolder' within the ShapeData folder.  The set folder also contains vector delta data files (*.bsd files).  The slider set also allows configuration of the output path and file name.  The path is relative to the Skyrim data path, and the output file should be named whatever Skyrim is expecting at that location.  In the sliderset xml, the outputfile is specified without the "_1.nif" or "_0.nif" portion, which is automatically appended by BodySlide.  All of the included slider sets operate on the female body (femalebody_0 and femalebody_1 .nif files), but it should be possible to output any outfit (eg outfitf_0.nif and outfitf_1.nif).  Should the automatic appending not meet your needs, you can simply rename the output nif files as necessary.

A slider set looks within the source .nif for a NiTriShape named the same as the configured "BaseShapeName" in the xml.  this name IS CASE SENSITIVE, and must match exactly.  In cases where there is more than one NiTriShape within the nif (such as the case for outfits or multipart bodies like NeverNude), More than one BaseShapeName is required, one for each. Each BaseShapeName has a 'target' entry in the XML. The value of the target string is not important outside of the .xml, and is there to link data files with the shape they modify.  Obviously, the target string must be different for each BaseShapeName defined.

[Sliders] 
Each SliderSet has any number of slider definitions.  Each slider definition corresponds to two actual sliders in the app -- one for the low weight and one for the high weight.  The Slider's 'Name' defines what is displayed in the body slide screen and acts as a unique identifier within the application to track sliders.  

For CBBE, many shape deltas are actually negative, meaning the volume of the shape grows smaller as the percentage increases.  Thus, these sliders have the definition 'Invert="true"', which inverts the perceptual progression.  For an inverted slider, the actual percentage of applied delta is 100 minus the slider value.  As an example, note CalienteBody 'Breasts' slider is inverted.  When the slider is 100 in the UI, 100%-100% or 0% of the actual delta is applied.  Breasts SH is a counterexample, where the slider progression is equal to the delta progression.  the invert attribute is an optional one, and if left out, is considered false.

Each slider defines a pair of default values.  Named small and big, these define the initial state of the slider in absence of a preset.  Typically these are 0 and/or 100, though they can be anything within that range (including decimal values)

A slider can be Hidden, which means it does not appear on the UI, but still applies its effect when bodies are created.  This is useful for shapes that you don't wish to allow the user to change.  CalienteBody defines the small seam delta this way (the base shape has a large seam).  Thus, the user doesn't have to know to set the seam value appropriately.  Additionally CalienteBody has an always-full strength "shouldertweak" hidden slider that forces a small shoulder shape transformation.  (note that transformation is due to how CBBE is built, and is not something required in other meshes)

A slider contains a list of data files.  (normally just one).  These data files are linked to the bodyshape target, and refer to a .bsd file in the same directory as the source file.  For an example of two targets, examine NeverNude slider sets.

Finally, a slider contains a list of 'requirements', which are references to other sliders.  The sliders referenced must be defined higher in the .xml file than the requirement definition.  These requirements cause the UI to hide sliders when the referred to slider value is not equal to the required value.  For instance, BreastsSmall requires Breasts to be 0, which means the BreastsSmall slider is hidden while the Breasts slider is greater than 0.  This is done because the shape transformation of breastssmall is based on the smallest size of Breasts, and produces undesireble results when applied to breasts at a higher value.  

[Slider Presets] 

Slider presets are defined in the SliderPresets folder.  Again a series of XML files that contain definitions of preset slider values for a specific slider set.  A future version of BodySlide will likely allow an individual to save presets through the UI, but for now, you must add a preset in XML.

The preset name is the value that appears in the presets dropdown box, and should be unique per slider set.  The set value refers to what sliderset the preset pertains to.  There is no hierarchy or order required for the preset definitions, and they can be spread across multiple files.  Thus, if you want, you could create presets for an armor addon and also provide a matching body preset for someone else's body slider set, all in the same file.  (notably, without having to alter the original body preset file)

A preset is linked to a specifc slider set, as defined by the set attribute.

Within each preset is a series of setslider elements.  Each setslider element refers to a slider defined in a slider set (and that slider name must be exact, including caps).  The setslider contains a value to set the slider, and a size at which to set the value.  The size attribute can be 'small' to set the low-weight slider, 'big' to set the high weight slider, or 'both' to set both sliders to the same value.

[Generating New SliderSets]

Part of the goal in creating BodySlide is to allow armor mod authors to more easily add support for the various popular body sizes released with CBBE.  While the functionality to do so exists, it's a process that still requires careful attention to detail and knowledge on how to edit and export .nif files.  

Creating a new SliderSet is a matter of generating a number of vertex delta files, and creating a sliderset definition xml document.  The XML is described above.   A sliderset may have as many or as few sliders as you wish (Eg. vanilla cbbe has 0 visible sliders). Currently, however, there's only so much space in the window --- a future version will likely add some sort of scrolling capability.
Ideally, new armors should attempt to support the sizes available in CalienteBody (11 sliders, not all would be pertinent), and at least the non-SillyHuge sizes.  

Note While bodyslide was invented for CBBE, there's no functional reason it can't be adapted to other body mods or other sorts of things entirely (Imagine a mace mesh that allows a user to customize the length and quantity of spikes, the shape of the haft, and the overall size of the weapon).  Its all a matter of creating a base mesh, a series of delta files, and an associated slider set.

[Vertex delta files] 
Vertex delta files could not be simpler.  it is a binary list of vector offsets per vertex index.  the exact format is 
<int vertex count> 
[
<int vertex index 1><float diff x, diff y, diffz> 
<int vertex index 2><float diff x, diff y, diffz>
...
]

Generating the diff files is a matter of subtracting a morphed shape from a base shape, and storing all the vertices that differ by .0001 or more in any axis to the delta file.  While such an operation could be perfored in any way desired, BodySlide comes with a method to perform the calculations.

Warning, the code that does it is rather rough, and will silently fail or crash if the input isn't exactly right.  

The input file is a nif file containing any number of NiTriShapes.  One of these tri shapes must have a name that exactly matches the GenBaseShapeName value in the configuration .xml.  The bulk of the info in a .nif file is immaterial (shader properties, skinning properties, skeletons, etc), and BodySlide will simply ignore anything it doesn't need.  The version of the Nif file is important, however.  The version should be 20.2.0.7, and the userversion value in the header should be either 11 or 12.  
All NiTriShapeData blocks within the nif must have exactly the same vertex count and vertex order as the base shape. Very little validation is done, so if they differ, you could end up with some messy results.  

Included in the BodySlide folder is a CBBEshapekeys.nif file that contains all the shape keys used to generate CalienteBody sliderset.  It is included in case the layout is enlightening.  The shapes can also be used as sizing templates for outfits if desired.  

To generate the input nif, I found that exporting from a nif exporter (like from blender) was required -- if working in .obj format, the vertex order changes through the export (and vertices are added due to material seam duplication).  It may be possible to export an obj file from a nif, modify it (without changing vertex count or order) and import it back in as a separate shape, but I did not try this.



finally, thanks for using BodySlide!!

-Caliente




















