Crate loadorder_ffi

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).

Libloadorder is less strict when loading load orders and will adjust them at load time to be valid, similar to game behaviour.

Structs

GameHandle

Statics

LIBLO_ERROR_FILE_NOT_FOUND	The specified file could not be found.
LIBLO_ERROR_FILE_NOT_UTF8	The specified file is not encoded in UTF-8.
LIBLO_ERROR_FILE_PARSE_FAIL	There was an error parsing a plugin file.
LIBLO_ERROR_FILE_RENAME_FAIL	A file could not be renamed.
LIBLO_ERROR_INTERNAL_LOGIC_ERROR	The library encountered an error that should not have been possible to encounter.
LIBLO_ERROR_INVALID_ARGS	Invalid arguments were given for the function.
LIBLO_ERROR_IO_ERROR	An unknown I/O error occurred. This is used when the I/O error kind doesn't fit another error code.
LIBLO_ERROR_IO_PERMISSION_DENIED	Permission denied while trying to access a filesystem path.
LIBLO_ERROR_PANICKED	Something panicked.
LIBLO_ERROR_POISONED_THREAD_LOCK	A thread lock was poisoned.
LIBLO_ERROR_TEXT_DECODE_FAIL	Text expected to be encoded in Windows-1252 could not be decoded to UTF-8.
LIBLO_ERROR_TEXT_ENCODE_FAIL	A plugin filename contains characters that do not have Windows-1252 code points, or a character string contains a null character.
LIBLO_ERROR_TIMESTAMP_WRITE_FAIL	The modification date of a file could not be set.
LIBLO_GAME_FNV	Game code for Fallout: New Vegas.
LIBLO_GAME_FO3	Game code for Fallout 3.
LIBLO_GAME_FO4	Game code for Fallout 4.
LIBLO_GAME_FO4VR	Game code for Fallout 4 VR.
LIBLO_GAME_TES3	Game code for The Elder Scrolls III: Morrowind.
LIBLO_GAME_TES4	Game code for The Elder Scrolls IV: Oblivion.
LIBLO_GAME_TES5	Game code for The Elder Scrolls V: Skyrim.
LIBLO_GAME_TES5SE	Game code for The Elder Scrolls V: Skyrim Special Edition.
LIBLO_GAME_TES5VR	Game code for The Elder Scrolls V: Skyrim VR.
LIBLO_METHOD_ASTERISK	The asterisk load order system, used by Fallout 4 and Skyrim Special Edition.
LIBLO_METHOD_TEXTFILE	he game handle is using the textfile-based load order system. Skyrim uses this system.
LIBLO_METHOD_TIMESTAMP	The game handle is using the timestamp-based load order system. Morrowind, Oblivion, Fallout 3 and Fallout: New Vegas all use this system.
LIBLO_OK	Success return code.
LIBLO_RETURN_MAX	Matches the value of the highest-numbered return code.
LIBLO_WARN_LO_MISMATCH	There is a mismatch between the files used to keep track of load order.

Functions

lo_create_handle⚠	Initialise a new game handle.
lo_destroy_handle⚠	Destroy an existing game handle.
lo_fix_plugin_lists⚠	Fix up the text file(s) used by the load order and active plugins systems.
lo_free_string⚠	Free memory allocated to string output.
lo_free_string_array⚠	Free memory allocated to string array output.
lo_get_active_plugins⚠	Gets the list of currently active plugins.
lo_get_error_message⚠	Get the message for the last error or warning encountered.
lo_get_implicitly_active_plugins⚠	Get the list of implicitly active plugins for the given handle's game.
lo_get_indexed_plugin⚠	Get filename of the plugin at a specific load order position.
lo_get_load_order⚠	Get the current load order.
lo_get_load_order_method⚠	Get which method is used for the load order.
lo_get_plugin_active⚠	Checks if a given plugin is active.
lo_get_plugin_position⚠	Get the load order position of a plugin.
lo_get_version⚠	Gets the library version.
lo_load_current_state⚠	Load the current load order state, discarding any previously held state.
lo_set_active_plugins⚠	Sets the list of currently active plugins.
lo_set_load_order⚠	Set the load order.
lo_set_plugin_active⚠	Activates or deactivates a given plugin.
lo_set_plugin_position⚠	Set the load order position of a plugin.

Type Definitions

lo_game_handle

A structure that holds all game-specific data used by libloadorder.