Home

Expanded Library Wiki

Expanded Library (exlib) is the shared framework mod behind the Fallenstar Expanded family for Vintage Story - currently Iron Industry Expanded (iiex) and Steel Industry Expanded (siex). It ships no gameplay content of its own; you can use it because another mod depends on it or because it gives you batteries-included systems that are tedious to build from scratch:

• a generic block-network graph (auto-orienting node blocks, merge/fracture handling, a single manager) - used for gas pipes, steam pipes and molten-metal canals;
• multiblock structures with completion monitoring, build-outline projection and an invisible filler block that gives mega-blocks real per-cell collision;
• a production-machine tick lifecycle base;
• attribute-driven registration for blocks/items/entities/behaviours/commands, plus a source-generated, versioned, live-editable config system;
• a shared /exmod (server) and .exmod (client) command root, recipe-cost profiles, per-player preferences, block migrations, orphaned-BE healing, and a grab-bag of rotation / particle / sound / inventory helpers;
• a module system: an assembly that extends the framework or a mod built on it, driven through a host mod's lifecycle instead of carrying a ModSystem of its own.

This wiki documents both libraries the family publishes for reuse:

• exlib - the runtime framework mod other mods depend on and call. It ships as the Vintage Story mod artifact (exlib_<version>.zip) on the releases page.
• exlib.testing (ExpandedLib.Testing) - a headless xUnit harness that loads the real game assemblies and exercises network/block-entity logic under dotnet test, no game launch required. It's a build-/test-time developer library, not something installed in the game: you consume it as the ExpandedLib.Testing NuGet package, by referencing the project from source, or from the ExpandedLib.Testing.dll published with each GitHub release. Its API still moves between releases, so pin the version you build against.

Where to start

• New here? Read Getting Started - declare the dependency, set up a project reference, and register your first attribute-marked block. It walks samples/HelloExpanded, a buildable, bootable, tested mod using the convenience layer end to end - read it alongside the page.
• Wondering when exlib does what during world load, and what's safe to call where? Lifecycle.
• Wondering which types are the supported contract and which are internal plumbing? Supported API.
• Shipping a block, item or recipe from C# instead of JSON? Code-First Definitions.
• Building plumbing/wiring of any kind? Block Networks.
• Building a furnace, boiler or other big machine? Multiblock Structures and Production Machines.
• Writing a block entity and want its fields saved for free? Block Entities.
• Adding to a process our mods already ship - a roll set, a mold, a crop, a die? Extending Processes. Our machines name no product; you declare one.
• Want config, commands or recipe tuning? Registries, Config System, Commands, Recipe Costs.
• Want the content guards (dangling codes, missing lang, ...) to run against your own source, or on demand rather than only at load? Checks.
• Writing tests? Testing Harness and Testing API Reference.

A note on accuracy

These pages document the public surface a third-party mod consumes. Signatures are taken from the source in this repository; when in doubt, the code in src/ and src/ExpandedLib.Testing/ is the source of truth. Game-version differences (1.20 / 1.21 / 1.22) are handled by the Legacy/ shim and noted where they affect you.