Crate thunderstore_engine 

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 a zstd + bincode package-index cache (per community), keyed by a Last-Modified freshness check. UI-agnostic progress via the progress traits.
• models: the package/version data model (struct-of-arrays + lasso string interning) and the on-disk cache wire format.
• resolve: dependency-graph resolution over the package index.
• manifest: parsing of a package’s manifest.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 compressed zstd snapshot 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, the mods.yml model, a per-game package cache, .r2z export/import, and computing a LaunchPlan that 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:

cargo add thunderstore-engine

Quick start

use thunderstore_engine::client::ThunderstoreClient;

#[tokio::main]
async fn main() -> thunderstore_engine::Result<()> {
  let client = ThunderstoreClient::builder()
    .base_url("https://thunderstore.io")
    .community("valheim")
    .cache_dir("/path/to/cache")
    .build()?;

  let index = client.get_manifest().await?;

  println!("{} packages", index.len());

  Ok(())
}

Cargo features

The HTTP/TLS backend is selectable so downstream builds can avoid a backend’s build dependency. Pick exactly one:

• rustls-tls (default): rustls with the aws-lc-rs provider (needs a C toolchain to build).

• native-tls: links the platform’s TLS stack instead:

  thunderstore-engine = { version = "0.1", default-features = false, features = ["native-tls"] }

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:

curl -s https://thunderstore.io/api/experimental/schema/dev/latest/ \
  | zstd -19 -o assets/ecosystem-schema.json.zst

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

Re-exports

pub use error::Error;

pub use error::Result;

pub use progress::NoopProgress;

pub use progress::ProgressHandle;

pub use progress::ProgressReporter;

Modules

client

Async Thunderstore API client and package-index cache. Async Thunderstore API client and package-index cache.

ecosystem

Ecosystem-schema: games, mod loaders, and install rules. The Thunderstore ecosystem schema: games, mod loaders, and install rules.

error

Error types and the engine Result alias.

extract

CRC-verified zip extraction primitives. Generic, CRC-verified zip extraction primitives.

install

Schema-driven, root-relative mod install routing. Schema-driven, root-relative mod install routing.

manifest

Per-mod manifest.json parsing.

models

Package data model and the cache wire format.

profile

r2modman-compatible profile management. Profile installs on top of crate::install: five high-level operations (install an extracted package, uninstall, enable, disable, and the full download-resolve-install pipeline) that work against an arbitrary target directory. mods.yml (modlist) is the authoritative install record in every mode.

progress

UI-agnostic progress reporting. UI-agnostic progress reporting.

resolve

Dependency-graph resolution. Dependency-graph resolution.

steam

Whether the running Steam client can resolve a path. Host facts about the Steam client: where its executable lives, and whether it can resolve a path a caller hands it.

Structs

RetryPolicy

Policy for retrying transient network failures.