libloadorder-ffi

libloadorder-ffi provides a C API wrapper around libloadorder, a free software library for manipulating the load order and active status of plugins for the following games:

TES III: Morrowind
TES IV: Oblivion
TES V: Skyrim
TES V: Skyrim Special Edition
Fallout 3
Fallout: New Vegas
Fallout 4
Fallout 4 VR

Variable Types

libloadorder-ffi uses character strings and integers for information input/output.

All strings are null-terminated byte character strings encoded in UTF-8.
All return, game and load order method codes are unsigned integers at least 16 bits in size.
All array sizes are unsigned integers at least 16 bits in size.
File paths are case-sensitive if and only if the underlying file system is case-sensitive.

Thread Safety

libloadorder-ffi is thread-safe. Reading and writing data for a single game handle is protected by a reader-writer lock, and error messages are stored thread-locally.

Game handles operate independently, so using more than one game handle for a single game across multiple threads is not advised, as filesystem changes made when writing data are not atomic and data races may occur under such usage.

Data Caching

libloadorder caches plugin data to improve performance. Each game handle has its own unique cache, which is cleared when

calling lo_load_current_state()
calling lo_fix_plugin_lists()
an error is encountered writing a change.

Plugin Validity

Where libloadorder functions take one or more plugin filenames, it checks that these filenames correspond to valid plugins. libloadorder defines a valid plugin as one that:

Ends with .esp, .esm, .esp.ghost or .esm.ghost (or .esl or .esl.ghost for Skyrim Special Edition, Fallout 4 and Fallout 4 VR).
Contains a header record with:
- The correct type (TES3 for Morrowind, TES4 otherwise).
- A size that is not larger than the total file size.
- Subrecords with sizes that do not together sum to larger than the expected total subrecords size.

This definition is substantially more permissive than games or other utilities may be for performance reasons, and because libloadorder uses no plugin data beyond the header record, so later corruption or invalid data would not affect its behaviour.

This permissivity does allow more strictly invalid plugins to be positioned in the load order and activated, which may cause game issues, but protecting against such circumstances is beyond the scope of libloadorder.

Valid Load Orders

Any load order that is set using libloadorder must meet all the following conditions:

Contains only installed plugins.
Contains no duplicate entries.
Loads all master files (including light masters and false-flagged plugins) before all plugin files.
Contains no more than 255 active plugins, excluding light masters.
Contains no more than 4096 active light masters.
Contains all the game's implicitly active plugins that are installed (e.g. Skyrim.esm and Update.esm for Skyrim).
Starts with the game's main master file (Skyrim, Skyrim SE, Fallout 4 and Fallout 4 VR only).

Libloadorder considers a load order that fulfills all the above conditions to be valid, though there are additional conditions that may be enforced by the game (e.g. a plugin must load after all the plugins it depends on).