AssetForge

AssetForge is a Rust library for discovering and archiving freely licensed 3D assets through official provider APIs. It supports Poly Haven, ambientCG, authenticated user-directed Sketchfab CC0 downloads, and Google Scanned Objects through Gazebo Fuel.

Poly Haven provides dependency-complete glTF, FBX, Blender, and USD bundles at 1K through 8K. ambientCG provides curated 3D model archives. Sketchfab supplies the largest searchable catalog, restricted to downloadable CC0 models and requiring the user's own API token. Google Scanned Objects adds real-world OBJ/textured archives under CC BY 4.0 with mandatory Google Research attribution.

Google Scanned Objects resolve Auto to the provider's original ZIP archive and Original resolution. Search ranking covers the complete official collection, and exact IDs are rejected unless they are collection members.

AssetForge does not scrape websites, bypass access controls, or change provider licenses.

Install

[dependencies]
assetforge = "0.3.2"

Example

use assetforge::{
    ArchiveOptions, AssetForge, AssetProvider, AssetResolution, AssetTarget,
};

let forge = AssetForge::with_user_agent(
    AssetProvider::PolyHaven,
    "my-asset-tool/1.0 (contact@example.com)",
)?;
let forge = forge.with_discovery_limit(20);
let assets = forge.discover(&AssetTarget::Search("wooden chair".into()))?;
let options = ArchiveOptions {
    resolution: AssetResolution::TwoK,
    ..ArchiveOptions::default()
};
let summary = forge.archive_assets(&assets[..1], &options)?;
assert!(summary.is_success());
# Ok::<(), assetforge::AssetForgeError>(())

Search results are ranked by query relevance first and provider download count second. This keeps a direct name/tag match above a popular item that mentions the query only in its description. top and category results are ordered by downloads; collection limits default to 20 and are configurable from 1 through 100.

Downloads stream through progress callbacks into staged files. Provider sizes and MD5 values are checked when available, and every archived file receives a local BLAKE3 digest. Each archive contains assetforge-asset.json with source, license, creator/provider attribution, the actual selected bundle variant, and integrity metadata.

Target forms include a canonical provider id or URL, search:<text>, category:<name>, top, and latest. AssetFormat::Auto and AssetResolution::Auto select honest provider defaults: Poly Haven 2K glTF, ambientCG 2K archive, or Sketchfab original glTF archive.

AssetForge does not scrape provider websites. API and download origins are bound per provider; ambientCG redirects are followed manually only to its documented CDN, and Sketchfab temporary URLs are accepted only from its HTTPS delivery domains. Responses, redirects, paths, bundle sizes, staging, and skip_existing verification are bounded.

Poly Haven API use is separately limited to reasonable non-commercial use unless licensed. Sketchfab downloads must use an end user's token and preserve creator plus Sketchfab attribution. Google Scanned Objects must preserve the recorded CC BY 4.0 attribution. Consult the provider terms surfaced in each result.

Agent guide

AGENT_GUIDE.md is included in the published package and embedded verbatim as assetforge::AGENT_GUIDE. It documents target parsing, provider-specific bundle choices, ranking, rights, archive verification, safety boundaries, and examples using current API identifiers.

Development

cargo fmt
cargo test
cargo clippy --all-targets -- -D warnings