0xDocs 0x.limo

Docs / JavaScript SDK

@0xlimo/byo-assets

Partly live

Bring your own assets. Recipes convert a game's files, from a player's install or an unpacked tree, into web formats, deterministically and pinned by hash. The 0x assets command runs them.

Some worlds are built from a commercial game's graphics. Los Santos, for example, uses GTA V's. @0xlimo/byo-assets holds recipes: small JSON files that say which file of the game to read, how to convert it, and which hashes the result must have. The output is ordinary world content: publish it and let the swarm share it like any other asset. Running an import locally is optional; a world can ship the converted files directly.

Registry version: 0.1.1 (Node.js 20+). The 0x CLI routes 0x assets … to this package's x1-assets command (also installed as 0x-assets).

bash
npm install @0xlimo/byo-assets --@0xlimo:registry=https://0x.limo/npm/

v0

Implemented end to end: GTA V texture dictionaries (ytd@1) to PNG, glTF swatches or the Los Santos texture library layout. GTA V install detection (retail and extracted trees) and nested RPF7 archives. The proc-texture@1 fallback generator. Not implemented yet (each throws NotImplementedConverter): models (ydr/ydd, yft to glTF), collisions (ybn), placements (ymap/ytyp), the voxel library, Cyberpunk 2077 conversion (install detection only), decrypting retail NG/AES archives (the keys seam), and BC7 textures (skipped and reported).

#Commands

bash
0x assets locate --game gta5 [--path <dir>]                          # show the install found
0x assets import --game gta5 [--path <install>] [--recipes <file|dir>] [--cache <dir>] [--force] [--json]
0x assets fallback [--recipes <file|dir>] --out <dir>                # write the stand-ins (0x-owned, publishable)
  • import runs the recipes for that game (the built-in recipes/<game> by default) into the local cache.
  • A recipe whose run is cached, and whose source hash is unchanged, is not converted again unless --force is given.
  • Exit codes: 0 ok, 2 a recipe ended mismatch or error, 1 failure, 64 unknown command.

The cache is $ZEROX_BYO_CACHE, else $XDG_CACHE_HOME/0x/byo, else ~/.cache/0x/byo:

PathContents
objects/<aa>/<sha256>converted files, by content hash
runs/<recipeHash>.jsonone record per recipe run
views/<game>/<target>/<name>hard links (or copies), so engines can load by name

#Recipes

json
{
  "schema": "x1.byo.recipe/1",
  "id": "gta5/props/v_garden/prop_lawn/png",
  "game": "gta5",
  "gameVersions": ["*"],
  "source": { "path": "x64f.rpf/levels/gta5/props/residential/v_garden.rpf/prop_lawn.ytd", "sha256": "02e9…" },
  "converter": { "name": "ytd", "version": "1" },
  "target": "png",
  "settings": { "maxDim": 512 },
  "outputs": { "<name>": { "sha256": "<file bytes>", "content": "<decoded pixels>" } },
  "fallback": { "generator": "proc-texture", "version": "1", "settings": { "palette": ["#556b2f", "#6b8e23"], "seed": 7 } }
}
  • Identity: the SHA-256 of the canonical JSON, with outputs left out.
  • source.sha256 pins the player's file. A different hash means another game version or a modded file, and the run ends source-mismatch.
  • outputs pins the result. content hashes the decoded pixels, so a pin still verifies when only the PNG encoder changes.
  • target is one of png, gltf or bitize-texlib.
  • A file can hold one recipe, or a set: {"schema": "x1.byo.recipeset/1", "recipes": [...]}.
  • Run status is one of verified, unpinned, mismatch, source-mismatch, missing, unsupported or error.

Source paths are written as they appear inside the game. Each segment resolves to a real directory, to the same directory without its .rpf suffix, or to an RPF7 archive (nested archives are supported).

#Fallbacks

Every recipe can name a stand-in. proc-texture@1 is an original, deterministic generator (noise, bricks or stripes from a palette and a seed). Its PNGs carry the text chunk x1:fallback with the licence CC0-1.0 (0x original). resolve(recipe, cache) returns the player's converted files when the cache has them all, and the stand-ins otherwise, under the same names.

#Declaring imported content in a listing

A universe (store entry) can say which games its content comes from, so the launcher can show it and offer the local import:

json
"content": { "imported": { "games": [{ "id": "gta5", "title": "Grand Theft Auto V" }], "recipes": "<sha256>",
                           "paths": ["lsvehmesh/**"], "fallback": "required" } }

validateImported(universe) checks it: games with id is required, recipes must be a SHA-256, paths a list of globs, and fallback either required or optional. The field does not affect publishing or the swarm.

The functions are listed in the reference.