gtav-ymt-creator

A small command-line tool that builds a GTA V ped variation meta (.ymt) from one or more .ydd drawable dictionaries, using the gtax.dev API. Each .ydd maps to a component slot from its filename prefix (lowr_057_u.ydd -> lowr), so a folder of freemode clothing drawables becomes a ready-to-use .ymt in one command. It can also encode a raw model straight from JSON or <CPedVariationInfo> XML.

Prefer a point-and-click tool? Use the browser version at gtax.dev/tools/ymt-creator: no install, runs in your browser, and is friendlier for one-off builds. This CLI is aimed at scripting, automation, and batch jobs.

gtav-ymt-creator lowr_057_u.ydd jbib_000_u.ydd        # -> clothing_pack.ymt
gtav-ymt-creator -i lowr_057_u.ydd -name pants        # -> pants.ymt
gtav-ymt-creator -json model.json -o clothing.ymt     # encode a raw JSON model
gtav-ymt-creator -xml variation.xml                   # encode a CPedVariationInfo XML doc

Example

The example/ folder has two freemode drawables ready to use:

gtav-ymt-creator example/feet_006_u.ydd example/jbib_000_u.ydd -o clothing_pack.ymt

This maps feet_006_u.ydd to the feet slot and jbib_000_u.ydd to the jbib slot and writes a best-effort clothing_pack.ymt (one default texture per drawable; open it in the browser tool or your usual editor to fine-tune).

Install

Download a prebuilt binary from the Releases page (linux / macOS / windows, amd64 / arm64), unpack it, and put it on your PATH.

From source (Go 1.21+):

go install github.com/gtax-dev/gtav-ymt-creator@latest

Authentication

Building needs your global gtax.dev API key (gtax_dglb_...), the same key the other gtax tools use. Get one at gtax.dev/api-keys and provide it via the environment (preferred) or the -api-key flag:

export GTAX_API_KEY="gtax_dglb_your_key"
gtav-ymt-creator example/feet_006_u.ydd

Limits

Tier	Daily limit
API key - Free / Basic	3 builds per 24 h
API key - Pro	Unlimited
API key - Ultra	Unlimited

Each successful build counts as one unit, regardless of how many .ydd files it contains.

Component slots

Each .ydd maps to a slot from its filename prefix. Valid prefixes:

head  berd  hair  uppr  lowr  hand  feet  teef  accs  task  decl  jbib

Files whose prefix is not one of these are skipped with a warning: line on stderr (the rest of the build still succeeds). If two files map to the same slot, the later one wins.

Usage

gtav-ymt-creator [options] <file.ydd> [more.ydd ...]

The tool has three modes:

• build (default): posts the .ydd files as multipart/form-data to POST {base}/build and saves the returned .ymt.
• -json <file>: posts the file to POST {base}/from-json (a raw ymtModelVersion 1 model).
• -xml <file>: posts the file to POST {base}/from-xml (a <CPedVariationInfo> XML document).

Errors are JSON: {"error":"..."}. Rate-limit info (rate_remaining, rate_limit, retry_after_s) and any skipped-file warnings are printed to stderr.

Flags

Flag	Default	Description
-i	-	Input .ydd file. Repeatable; positional arguments work too.
-o	derived	Output path. Defaults to the server result name, else -name + .ymt, else clothing_pack.ymt.
-name	clothing_pack	Output basename sent to the API (sanitized to [a-z0-9_-]).
-num-tex	1	Texture rows generated per drawable (1..255). Build mode only.
-json	-	Encode a raw ymtModelVersion 1 JSON model file instead of building from .ydd.
-xml	-	Encode a <CPedVariationInfo> XML file instead of building from .ydd.
-api-key	$GTAX_API_KEY	API key (falls back to $YMT_API_KEY).
-api-url	$GTAX_API_URL or https://public-ymt-creator.gtax.dev	API base URL override.
-timeout	5m	HTTP client timeout.
-quiet	false	Suppress progress output on stderr.
-version	-	Print the version and exit.

Examples

Build from a folder of drawables:

gtav-ymt-creator ./stream/*.ydd -name my_outfit -o my_outfit.ymt

Multiple texture variations per drawable:

gtav-ymt-creator -i uppr_001_r.ydd -num-tex 4 -name colorways

Encode a model you exported as JSON (the same shape the browser tool builds):

gtav-ymt-creator -json model.json -o clothing_pack.ymt

Encode a Sollumz / CodeWalker <CPedVariationInfo> XML:

gtav-ymt-creator -xml variation.xml -name my_outfit

Point at a local instance of the service (for development):

gtav-ymt-creator -api-url http://localhost:8896 -api-key "$GTAX_API_KEY" example/*.ydd