Bain

From the Oblivion ConstructionSet Wiki
Jump to navigation Jump to search

Overview[edit | edit source]

Bain is a mod package installer built into Wrye Bash. While Bain understands regular most mod packages without special action, complex mod packages can be structured to be more "Bain Friendly". (Note: One of Bain's design goals is to work well with manual archives -- so a "Bain Friendly" package is also manual install friendly.) The rest of the document is concerned with building Bain friendly packages.

Related:

Package Structure[edit | edit source]

Bain understands two types of archive directory structures. Both types of structures are easily understood by players and work well for those who prefer to install archives manually. Below are some guidelines for structuring mod archives.

Simple Structure[edit | edit source]

For a mod that offers no options, the best structure is to have the top level of the archive match the top level of the Oblivion\Data directory. E.g.

Cool Mod.esp
Cool Mod Readme.txt
Meshes\
Textures\

Notes:

  • Bain will skip over the contents of any non-standard directories. (Standard directories are: Bash Patches, Distantlod, Docs, Facegen, Fonts, Menus, Meshes, Music, Shaders, Sound, Textures, Trees, Video.) Bain will also skip all archive files (7z, zip, etc.)
  • Bain will skip over executable files (exe, dll, dlx, etc.) Separate installation methods should be used for such files. (Which should be very rare anyway.)

Complex Packages[edit | edit source]

If it's desired for a mod to have optional sub-packages (e.g. to install one of three variants of a mod, or to allows optional installation of patch mods), then the complex structure can be used. In this format, the top level of the archive corresponds to the options -- i.e. each top level directory of the archive is an optional sub-package, while the top level of each of these directories again matches to the Oblivion\Data directory.

In short the complex archive structure is essentially a collection of Simple archive structures. Example:

00 Main Install\
   Main Mod.esm
   Main Mod.esp
   Main Mod Readme.txt
   Meshes\
   Textures\
   Sounds\
01 Alternate Main
   Main Mod.esp
02 Alpha Extras\
   Alpha 1.esp
   Alpha 2.esp
02 Beta Extras\
   Beta 1.esp
   Textures\

Notes:

  • After the user chooses which sub-packages to use, they will be applied in alphabetical order. So if there's a conflict between different options of the sub-package (e.g. if the textures in "02 Beta Extras" override the default textures from "01 Main Install"), be sure to name the archives in a way that the override options will indeed override the earlier options. An easy way to do this is to preface names with numbers as above.

Espm Filtering[edit | edit source]

Bain users can choose to not install any of the esps that are included with a mod. This feature is useful when there are alternate versions of a mod (e.g. "LeveledRates x2.esp" vs. "LeveledRates x3.esp"), or when a mod comes with many optional esps.

For package structuring, the mod maker can then ask whether they should create a separate sub-package for a given esp, or rather let the user use espm filtering. In general the best solution will probably be to group esps logically into groups. E.g. for Oscuro's Oblivion Overhaul, a good structure would be:

00 Resources
01 OOO-Full (one esp)
01 OOO-Lite (one esp)
02 OOO-Lite Add-Ons (many esps)
03 Harvest Flora (several esps)
03 Level Rates Modified (several esps)
03 Living Economy

E.g. a user going with the full installation would choose OOO-Full and not have to do any espm filtering. While a user going with a lite install would choose 01-Lite + 02 OOO-Lite Add-Ons, and then do espm filtering.

Package Organization[edit | edit source]

This section provides a bit more general advice on how to organize Bain projects. Some of this is a matter of taste and/or a trade off between pros and cons.

Docs[edit | edit source]

  • Ordinarily putting docs at the top level of an archive results in clutter in the Oblivion\Data directory. However, since Bain will just sweep those docs into Data\Docs anyway, it may be better to have them at the top level, since they're more accessible to people who are browsing through the archive.
  • However, if a doc is an html file with related images, then you should place the docs under a Docs directory in the archive (e.g. 00 Core\Docs\Wicked Mod.html, etc.). This is to keep Bain from failing to sweep images to the right directory.

Note: Bain will probably later have an option to skip over docs during installation.

Screenshots[edit | edit source]

Currently loose images are treated as docs and are swept into the Docs directory. This will probably change in a later release, so that they're instead swept into a Data\Screenshots directory (with a further option to merge Screenshots into Docs).

If you have a lot of screenshots, then can store them in a directory named "Screenshots" (which should be at same level as Docs, Meshes, etc.)

Subpackage Numbering[edit | edit source]

It's not required that you number subpackages, but there's an informal standard to do so.

  • Folks who get used to this standard may find it odd to have a subpackage that doesn't have numbers.
  • Numbering provides a clear order for subpackages. Keep in mind that subpackages are installed in alphabetical order. Hence numbering provides an easy way to provide correct order for subpackages.
  • When numbering, it's often useful to form "groups" of subpackages, but starting them with the same number.
    • Usually such groups indicate an exclusive choice, e.g. 01 Alpha OR 01 Beta or 01 Gamma.
    • However, sometimes they're used for just large numbers of subpackages. E.g. Better cities has about 42 subpackages which are divided into several groups. Some of those groups are exclusive, others (e.g. groups of independent fixes and patches) are non-exclusive.

Combining Archives[edit | edit source]

It's possible to combine different downloaded archives into one archive, possibly using sub-packages to mimic other choices. This isn't recommended, but some users may find it more organized, and may like that it keeps the order of mods "frozen". Keep in mind though:

  • There's no real performance gain. More likely there's a performance hit since whenever a file is extracted from the combined archive, the time taken is proportional to the total size of the archive.
  • It muddies the mapping between the original download and the merged archive. E.g. the "Open at TesNexus" command won't work, so it will be harder to check for updates for particular mods.

Project Management[edit | edit source]

Bain's project features make it fairly easy to create and update releases of your mods.

Creating the Project[edit | edit source]

Start by creating a project for your mod. Go to the Bash Installers directory, and create a directory with the name of the project and copy the project files into it. If you're building a complex package, set the directories up accordingly.

Note: When naming the project, it's best to not include the version number in the name. (E.g. "Cobl" instead of "Cobl 1.55".) (Keep in mind that you'll be using that one project directory to create different version archives.)

Project to Data Directory Mapping[edit | edit source]

For understanding how the project directory relates to the Data directory, it helps to understand the Bain configuration and installation process a bit better.

For installation, Bain essentially creates a mapping between files/directories in the package and files/directories in the Oblivion\Data directory. For an esp, this is simple -- the mapping is direct. But if sub-packages are involved or if document files are swept into the docs directory, things are a bit more complicated. But even in this case, there's a simple rule -- project synchronization simply reverses the install procedure. E.g. Bain sweeps a "readme.txt" file into "Docs\Cobl.txt", then when you sync a project to the data directory, it will copy "Docs\Cobl.txt" into "readme.txt" in the project directory.

Syncing Project to Data[edit | edit source]

After changing project files in the data directory, you can sync the project directory to those changes. (Sync == copy from data directory to project directory.) To do the sync, simply select the project and then use the "Sync from Data" command.

Before doing the sync:

  • Review the sub-package and espm filter settings. Generally, you'll want all sub-packages active and all espms checked under espm filtering.
  • Review files under missing and mismatched. Files listed under missing will be deleted from the project directory. Files listed under mismatched will be updated in the projects directory from the versions under Data.
  • If you need to add new files to the project, then use "Open" and manually add them into the projects directory. Then come back to Bain and run "Refresh" on the package.
  • Be sure to not accidentally select "Install"! That would be unfortunate. :(

Building the Archive[edit | edit source]

To create a release archive, just open the project directory, and generate the archive in the usual way.

If you're using 7-zip and have it configured to add commands to Explorer menus, you can do this easily by:

  1. Selecting all files/directories in the project directory,
  2. Right click and use 7-zip context menu to build the archive.

When you're done building the archive, rename it to include the version number (e.g. Cobl 155.7z) and move it up to the Installers directory. Then go back to Bain and review the new archive package. If you've done everything correctly and have it configured the same as the project package, then it should be the same color as the source project directory. (Which is preferably green at this point.)

Package Naming[edit | edit source]

  • It's suggested that you give your projects indicative names (e.g. "Cobl" not "manual install"). Projects should not have version numbers, but archives should (e.g. "Cobl" and "Cobl 155.7z").
  • If you have several related projects, then its best to start their names the same (e.g. "Cobl 1.55", "Cobl Cosmetics 01") -- that way they'll group together when the user sorts their packages by name.
  • Keep in mind that when archives are uploaded to mod sites, their names are usually mangled in a standard way. E.g. "UL - Arrius Creek v111.7z" becomes "UL_-_Arrius_Creek_v111-16812.7z" at TesNexus. The same name minus the "-" would convert more attractively.

Triple (Bain/OBMM/Manual) Archives[edit | edit source]

It's possible for a single archive to support Bain, OBMM and manual installs.

For simple archives, triple mod is simple -- just include the omod conversion info as you would with any omod ready archive.

For complicated archives (archives with subpackages), you need to include a obmm script to install the subpackages. Essentially, you'll need to turn off the default "install all files" behavior, and then use the script to specify which files should be installed. Of course, since things are divided into subpackages, you'll probably want to give the user a choice as to which subpackages to install.

Note: You can use the Omod Info... command for your project in Bain to create/edit the Omod config file (in the omod conversion data folder).

See Also[edit | edit source]

For contrast to OMOD creation, etc. see How To Create an OMOD.