thunderstore-engine
A game-agnostic Rust engine for building Thunderstore
mod managers. Extracted from
valheim-mod-manager so it can
be shared across projects.
What it provides
client: async Thunderstore API client with azstd+bincodepackage-index cache (per community), keyed by aLast-Modifiedfreshness check. UI-agnostic progress via theprogresstraits, and per-operation progress events and cancellation viaprogress::Operation.models: the package/version data model (struct-of-arrays +lassostring interning) and the on-disk cache wire format.resolve: dependency-graph resolution over the package index.manifest: parsing of a package'smanifest.json.extract: CRC-verified, traversal-safe zip extraction primitives.ecosystem: Thunderstore's upstream ecosystem schema (games, mod loaders, install rules, and the mod-loader package registry), consumed directly so routing works for every Thunderstore game with no per-game maintenance. Ships a compressedzstdsnapshot as an offline fallback and refreshes over the network.install: schema-driven, root-relative mod install routing over the ecosystem's install rules (route-leaf matching, longest-extension precedence, recursive subroutes, all tracking methods,<Owner-Name>namespacing, and registry-based loader-pack handling) plus a recorded file manifest for exact uninstall.profile: r2modman-compatible profiles, covering directory layout, themods.ymlmodel, a per-game package cache,.r2zexport/import, and computing aLaunchPlanthat the caller spawns.steam: asks a running Steam client whether it can resolve a path, so a sandboxed Steam's silent launch failure surfaces before a launch instead of only in Steam's own console log.
The engine never resolves the absolute game directory, performs platform discovery, or launches games. Those are game-specific concerns left to the caller.
Installation
As a dependency of a Rust project:
Quick start
use ThunderstoreClient;
async
Cargo features
io (default)
Everything that touches disk or network: the client, the index cache, zip
extraction, and every profile operation that reads or writes a target. With
io off, the crate builds without an HTTP client, an async runtime, or an
archive library, and keeps what does no IO:
- the package, version, and ecosystem models (including
Ecosystem::require_profile), and the dependency resolver; - the game to community mapping (
GameProfile::community,GameDef::community), read from each game's package index location; - the
Errortype, which isCloneso a client can keep one in its state; - the plan types (
InstallPlan,InstallBatch,UninstallBatch,ToggleBatch,LaunchPlan,LaunchNotice) and themods.ymland export models; - profile name validation,
profile::layout::validate_name, which refuses names Windows cannot hold on every OS and gives the reason as aBadName; - pure planners that take what the
iofunctions would read as arguments:install::plan_install_from(a package's file list),install::plan_delisted_from,profile::plan_install_batch_from,profile::plan_set_enabled_batch_from,profile::plan_uninstall_batch_from,profile::launch::launch_plan_from, andprofile::launch::prepare_plan_from(a target'sLaunchFacts); - queries over installed packages:
query::dependants(every installed package that requires a given one, directly or transitively) andquery::outdated(installed packages the index has a newer version of), with "newer" defined by the total ordering onprofile::modlist::SemVer; - browsing the package index:
query::browsesearches, filters, and sorts it into package indices per aquery::BrowseQuery(r2modman's defaults: NSFW and deprecated hidden, community-pinned first, newest update first, orquery::SortKey::BestMatchto rank the closest match to the search first), andquery::PackageRowreads one package's list fields without building its versions;models::PackageIndex::prepare_searchbuilds what a best-match search reads ahead of the first one, for a background thread after loading; - the per-operation progress and cancel types in
progress(Operation,OperationId,ProgressEvent,Stage,StageUpdate,CancelToken) andprofile::BatchOutcome, so a client can store an operation's events and result.
Each io function with a pure counterpart reads its inputs and calls that
counterpart, so the two decide identically. To depend on the pure part only:
= { = "0.3", = false }
Cargo merges features across everything built together, so a crate that must
not reach the io functions is only held to that when it is built on its own.
TLS backend
The HTTP/TLS backend is selectable so downstream builds can avoid a backend's
build dependency. Either one turns on io. Pick exactly one:
-
rustls-tls(default): rustls with theaws-lc-rsprovider (needs a C toolchain to build). -
native-tls: links the platform's TLS stack instead:= { = "0.1", = false, = ["native-tls"] }
test-support
Off by default. Adds test_support, a mock Thunderstore built on mockito
that serves a small package index, real package archives, and their readmes,
so a client's tests can run the install pipeline with no network access.
MockThunderstore::start (or start_async in an async test) starts it, and
client_builder returns a client pointed at it. Turn it on for tests only:
[]
= { = "0.3", = ["test-support"] }
test-support turns on io, so it needs a TLS backend like any io build.
A client on native-tls repeats its own features, so the test build doesn't
also get the default rustls-tls:
[]
= { = "0.3", = false, = ["native-tls", "test-support"] }
Refreshing the bundled ecosystem snapshot
The crate embeds a compressed snapshot of Thunderstore's ecosystem schema as an
offline fallback (assets/ecosystem-schema.json.zst); Ecosystem::fetch_latest
pulls a fresh copy at runtime. Regenerate the embedded fallback with:
|
Credits / references
- Thunderstore API: https://thunderstore.io/api/docs/
- Ecosystem schema: https://github.com/thunderstore-io/ecosystem-schema
- Install routing follows the model proven in r2modman (https://github.com/ebkr/r2modmanPlus) and Gale (https://github.com/Kesomannen/gale).
License
MIT