Particle CLI
Particle commands inspect and convert particles.xr libraries. Use the unpacked representation to edit a library, then
verify the packed result before adding it to gamedata.
Examples
Run from a working directory containing the source particles.xr. Use new destinations for the unpacked library and
rebuilt file:
xrf-cli particle info --path ./particles.xr
xrf-cli particle unpack --path ./particles.xr --dest ./particles_unpacked
Example output — inspect particles:
Read particle file ./gamedata/particles.xr
Particles file information:
Version: 1
Effects count: 921
Groups count: 350
Exit code: 0.
Edit the exported files, then validate and pack them:
xrf-cli particle verify --path ./particles_unpacked --unpacked
xrf-cli particle pack --path ./particles_unpacked --dest ./particles.rebuilt.xr
xrf-cli particle verify --path ./particles.rebuilt.xr
verify checks that the selected representation can be read. It does not resolve the library’s texture dependencies.
After installing the rebuilt file, use gamedata verification to check the library in its asset context,
and inspect the affected effects in game.
Re-serialize a library
xrf-cli particle repack --path ./particles.xr --dest ./particles.repacked.xr
xrf-cli particle re-unpack --path ./particles_unpacked --dest ./particles_unpacked_roundtrip
repack reads a packed library and writes another packed file. re-unpack imports an unpacked library and exports it
to another directory. Neither command automatically compares the result with its source. Serialization can change bytes,
so a hash difference alone does not demonstrate a change to the particle definitions.
Failure notes
Packing rejects an existing output file, and unpacking rejects an existing destination directory, unless --force is
supplied. Use that flag only when replacing the selected output is intended.
A successful read or conversion establishes that the tool accepts the data. It does not establish visual equivalence or correct behavior of every effect.
Command reference
xrf-cli particle info
Command to print information about provided particle file
xrf-cli particle info [OPTIONS] --path <path>
| Option | Required | Default | Description |
|---|---|---|---|
-p, --path <path> | yes | Path to particle file | |
-s, --silent | Turn off logging | ||
-v, --verbose | Turn on verbose logging | ||
--json | Write the run’s JSON report to stdout, moving human output to stderr | ||
--report <PATH> | Write the run’s JSON report to a file |
xrf-cli particle pack
Command to pack unpacked particle files into single particle.xr
xrf-cli particle pack [OPTIONS] --path <path>
| Option | Required | Default | Description |
|---|---|---|---|
-p, --path <path> | yes | Path to unpacked particle file folder | |
-d, --dest <dest> | unpacked | Path to resulting packed *.xr file | |
-f, --force | Whether existing packed particle should be pruned if destination folder exists | ||
-s, --silent | Turn off logging | ||
-v, --verbose | Turn on verbose logging | ||
--json | Write the run’s JSON report to stdout, moving human output to stderr | ||
--report <PATH> | Write the run’s JSON report to a file |
xrf-cli particle repack
Command to repack provided particle.xr into another file
xrf-cli particle repack [OPTIONS] --path <path> --dest <dest>
| Option | Required | Default | Description |
|---|---|---|---|
-p, --path <path> | yes | Path to particle file | |
-d, --dest <dest> | yes | Path to resulting particle file | |
-s, --silent | Turn off logging | ||
-v, --verbose | Turn on verbose logging | ||
--json | Write the run’s JSON report to stdout, moving human output to stderr | ||
--report <PATH> | Write the run’s JSON report to a file |
xrf-cli particle re-unpack
Command to re-unpack provided particle directory into another directory
xrf-cli particle re-unpack [OPTIONS] --path <path> --dest <dest>
| Option | Required | Default | Description |
|---|---|---|---|
-p, --path <path> | yes | Path to unpacked particle directory | |
-d, --dest <dest> | yes | Path to resulting unpacked particle | |
-s, --silent | Turn off logging | ||
-v, --verbose | Turn on verbose logging | ||
--json | Write the run’s JSON report to stdout, moving human output to stderr | ||
--report <PATH> | Write the run’s JSON report to a file |
xrf-cli particle unpack
Command to unpack provided particle.xr into separate files
xrf-cli particle unpack [OPTIONS] --path <path>
| Option | Required | Default | Description |
|---|---|---|---|
-p, --path <path> | yes | Path to particle.xr file | |
-d, --dest <dest> | unpacked | Path to folder for exporting | |
-f, --force | Whether existing unpacked data should be pruned if destination folder exists | ||
-s, --silent | Turn off logging | ||
-v, --verbose | Turn on verbose logging | ||
--json | Write the run’s JSON report to stdout, moving human output to stderr | ||
--report <PATH> | Write the run’s JSON report to a file |
xrf-cli particle verify
Command to verify provided particle file
xrf-cli particle verify [OPTIONS] --path <path>
| Option | Required | Default | Description |
|---|---|---|---|
-p, --path <path> | yes | Path to particle.xr file | |
-u, --unpacked | Whether should verify unpacked particle | ||
-s, --silent | Turn off logging | ||
-v, --verbose | Turn on verbose logging | ||
--json | Write the run’s JSON report to stdout, moving human output to stderr | ||
--report <PATH> | Write the run’s JSON report to a file |