0xDocs 0x.limo

Docs / JavaScript SDK

@0xlimo/byo-assets reference

Partly live

Every export of @0xlimo/byo-assets 0.1.1 (pipeline, recipes, cache, fallbacks, universe field and CLI) with signatures.

The package has no typings. It has one entry point, @0xlimo/byo-assets (src/index.mjs), and a binary, x1-assets (alias 0x-assets). The signatures below are written as TypeScript for readability.

#Pipeline

ts
importAssets(o: {
  gameId: string;            // "gta5"
  path?: string;             // install or extracted tree; default: detected
  recipes: Recipe[];         // only those with recipe.game === gameId run
  cacheRoot?: string;        // default defaultCacheRoot()
  keys?: unknown;            // decryption seam (retail archives), not implemented in v0
  force?: boolean;
  log?: (line: string) => void;
}): Promise<{ install: Install; cacheRoot: string; results: RunResult[] }>

runRecipe(recipe: Recipe, o: { install: Install; cache: Cache; keys?: unknown; force?: boolean }): Promise<RunResult>
// RunResult: {id, recipe: <recipeHash>, target, status, outputs?, error?, cached?, mismatched?}
// status: "verified" | "unpinned" | "mismatch" | "source-mismatch" | "missing" | "unsupported" | "error"

#Recipes

ts
const SCHEMA = "x1.byo.recipe/1";
const SET_SCHEMA = "x1.byo.recipeset/1";
const TARGETS = ["png", "gltf", "bitize-texlib"];

parseRecipes(text: string): Recipe[]          // one recipe or a set; validates each
validateRecipe(r: object): Recipe             // throws "recipe <id>: <problems>"
recipeHash(r: Recipe): string                 // sha256 of canonicalJson(r without outputs)
canonicalJson(v: unknown): string             // keys sorted recursively, no whitespace
checkOutputs(recipe: Recipe, outputs: Array<{ name: string; sha256: string; content?: string }>):
  { status: "verified" | "unpinned" | "mismatch"; mismatched: string[] }

Validation rules:

  • schema must be the recipe schema, and id and game are required.
  • source.path must be relative, with no ... source.sha256 is 64 hex digits or null.
  • converter needs a name and a version. target must be one of TARGETS.
  • Output pins are 64 hex digits.

#Cache

ts
defaultCacheRoot(env?: NodeJS.ProcessEnv): string   // $ZEROX_BYO_CACHE | $XDG_CACHE_HOME/0x/byo | ~/.cache/0x/byo
openCache(root?: string): Promise<{
  root: string;
  objPath(id: string): string;
  put(bytes: Uint8Array): Promise<string>;                 // -> sha256 id (atomic write)
  get(id: string): Promise<Buffer | null>;                 // null if missing or not matching id
  getRun(recipeHash: string): Promise<object | null>;
  putRun(recipeHash: string, run: object): Promise<void>;
  link(game: string, target: string, name: string, id: string): Promise<string>;   // views/<game>/<target>/<name>
}>

#Fallbacks

ts
generateFallback(recipe: Recipe): Array<{ name: string; bytes: Buffer; sha256: string }>
resolve(recipe: Recipe, cache?: Cache): Promise<{ kind: "imported" | "fallback"; files: Map<string, Uint8Array> }>

generateFallback throws when the recipe has no fallback, when the fallback names an asset by hash (not in v0), or when the generator is unknown. proc-texture@1 settings: width, height (64), palette (hex colours), seed (1), pattern (bricks or stripes), and names (output names; default <last id segment>.png).

#Universe field

ts
validateImported(universe: object): object | null    // the content.imported field, null if absent; throws on errors

#CLI

ts
run(argv: string[], io?: { stdout?: Writable; stderr?: Writable }): Promise<number>   // exit code
CommandFlags
import--game (required), --path, --recipes (default: built-in recipes/<game>), --cache, --force, --json
fallback--recipes (default: all built-in), --out (required)
locate--game (default gta5), --path

Exit codes: 0 ok, 1 error (0x assets: <message> on stderr), 2 an import with mismatch or error results, 64 unknown command (prints the usage).