@0xlimo/byo-assets
v0.1.0-alpha.0
Published
Convert a game's files (an installed copy or an unpacked tree) into web formats from 0x recipes, deterministically and pinned by hash; outputs are ordinary world content
Readme
@0xlimo/byo-assets: bring your own assets
Tools for worlds built from a commercial game's graphics (Los Santos uses GTA V's): recipes that convert a game's files (from an installed copy, or a tree unpacked with OpenIV or CodeWalker) into web formats, deterministically and pinned by hash. What they produce is ordinary world content: it is published, served from the origin and shared through the swarm and the edge like every other asset. Running the import locally is optional (a world can ship the converted files directly).
Tests use synthetic files generated at test time. No game file is in this repo.
CLI
0x assets import --game gta5 [--path <install>] [--recipes <file|dir>] [--cache <dir>] [--force] [--json]
0x assets fallback [--recipes ...] --out <dir>
0x assets locate --game gta5 [--path <dir>]bin/x1-assets.mjs provides these commands. The 0x CLI in packages/cli routes
0x assets ... to it.
The cache is $ZEROX_BYO_CACHE, falling back to ~/.cache/0x/byo. Layout:
| Path | Contents |
|---|---|
| objects/<aa>/<sha256> | converted files, by content hash |
| runs/<recipeHash>.json | one record per recipe run |
| views/<game>/<target>/<recipe-id>/<name> | hard links, so engines can load by name |
Recipe format (src/recipe.mjs)
{ "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" | "gltf" | "bitize-texlib",
"settings": { "maxDim": 512 },
"outputs": { "<name>": { "sha256": "<file bytes>", "content": "<decoded pixels>" } },
"fallback": { "generator": "proc-texture", "version": "1", "settings": { … } } }- Identity. A recipe is identified by the sha256 of its canonical JSON with
outputsleft out. source.sha256. This pins the player's file. A different value means a different game version or a modded file, and the run reportssource-mismatch.outputs. This pins the outputs.contentis a hash over the decoded pixels, so a pin still verifies when only the PNG or zlib encoder changes.- Run status. Each run ends as one of:
verifiedunpinnedmismatchsource-mismatchmissingunsupportederror
Sources: install detection (src/games/)
gta5 recognises two kinds of install:
- retail: GTA5.exe or GTA5_Enhanced.exe beside x64a.rpf. Steam libraries are found
automatically from
libraryfolders.vdf;--pathalso works. - extracted: a tree the player unpacked from their own copy with OpenIV or CodeWalker, with archive names kept as directories.
Source paths are written as they appear inside the game. Each segment resolves to one of:
- a real directory;
- the same directory without its
.rpfsuffix; - an RPF7 archive file (
src/formats/rpf7.mjs), with nested archives supported.
Retail archives are NG/AES-encrypted. Their keys come from the player's own GTA5.exe, so
decrypting them is a seam (the keys option) and is not implemented in v0. cp2077 has
install detection only. Its seam is the player's local WolvenKit CLI.
Converters and targets (src/convert/)
ytd@1 is implemented end to end: a GTA V texture dictionary is read as an RSC7 resource. It
decodes these formats:
- BC1–BC5 (DXT1/3/5, ATI1/2), bit-exact with Pillow, which is what bitize.rage used;
- A8R8G8B8, A8B8G8R8, A1R5G5B5, A8 and L8.
It writes one of three targets:
| Target | Output |
|---|---|
| png | One PNG per texture. |
| gltf | textures.glb: one material per texture on a swatch quad. |
| bitize-texlib | tex/<key>.png: the Los Santos/PaperMCP texture-library layout (/var/cache/0x/lstex1/lib/tex). It uses the ≤128 px mip, and key is a blake2b-64 of the RGBA. |
The rest are seams: ydr/ydd and yft to glTF, ybn, ymap/ytyp to placements, the bitize voxel
library, and cp2077. Each throws NotImplementedConverter and names the reader to port
(bitize.rage ydr.py, fragment.py, meta.py and library.py). BC7 textures are skipped and
reported.
Fallbacks (src/fallback.mjs)
Every recipe may name a stand-in. There are two kinds:
- an original deterministic generator, such as
proc-texture@1(noise, bricks or stripes from a palette and a seed); - a permissive asset pinned by hash. Fetching it from the swarm is not in v0.
resolve(recipe, cache) returns the player's converted files if the cache has them, and
otherwise the stand-in. Both come back under the same logical names. Stand-ins carry
tEXt x1:fallback.
Universe field (src/universe.mjs)
A universe can declare which games its content comes from (the launcher can show it and offer the local import):
"content": { "imported": { "games": [{"id": "gta5"}], "recipes": "<sha256>", "paths": ["lsvehmesh/**"], "fallback": "required" } }validateImported() checks the field. It has no effect on publishing or the swarm.
Tests
Run npm test, which is node --test test/*.test.mjs. They cover:
- determinism: identical hashes across runs, caches and install layouts (retail RPF versus extracted tree);
- source and output pins;
- texlib keys;
- BCn decoding against Pillow on random blocks;
- fallbacks;
- the CLI;
- the universe field.
