OnexExplorer

Commands

OnexExplorerCli download [-o <output-dir>] [--build-id <id>] [--all] <archive-names...>
OnexExplorerCli extract <file> -o <output-dir> [--entry <ids...>]
OnexExplorerCli list <file> [--json]
OnexExplorerCli info <file> [--entry <ids...>] [--json]

Global options

download — fetch archives from the Gameforge CDN

Fetches .NOS archive files from the Gameforge CDN. Downloads the patch manifest, resolves each archive name against it, and streams the file to disk with SHA1 verification.

Resolution tries an exact file-field match first, then falls back to a bare filename match. Names containing a * or ? wildcard are treated as case-insensitive glob patterns matched against the file field and the bare filename, so whole archive families can be fetched at once (e.g. "NostaleData\NStpData*.NOS"). An error is reported if a name matches more than one manifest entry or a pattern matches nothing. Files already present on disk with a matching SHA1 are skipped.

Examples:

# Download specific archives
OnexExplorerCli download -o ./downloads NSipData.NOS NostaleData\\NSipData.NOS

# Download all locale/chunk archives matching a glob pattern
OnexExplorerCli download -o ./downloads "NostaleData\\NSlangData_*.NOS"

# Download all archives from a specific build
OnexExplorerCli download -o ./downloads --build-id 12345 --all

extract — extract entries from a .NOS archive

Reads a .NOS archive and extracts entries to disk. Image entries (Texture, Icon, Image4B, TileGrid) are automatically converted to PNG. Sprite payloads (NSmpData/NSppData) produce one PNG per frame plus a <name>.json sidecar with frame metadata (width/height/xOrigin/yOrigin); sprite info (NSmnData/NSpnData) and effect definitions (NSeffData) are decoded to JSON. Entries whose type cannot be decoded yet are written raw.

Examples:

# Extract all entries
OnexExplorerCli extract path/to/file.NOS -o ./output

# Extract specific entries by ID
OnexExplorerCli extract path/to/file.NOS -o ./output --entry 0 1 2

list — list entries in a .NOS archive

Displays the entry table of a .NOS archive: ID, name, type, compression status, and sizes.

Examples:

# Human-readable table
OnexExplorerCli list path/to/file.NOS

# JSON output (pipeable)
OnexExplorerCli list path/to/file.NOS --json | jq '.[] | select(.type == "Icon")'

info — show entry details

Displays detailed information about entries in a .NOS archive: ID, name, type, creation date, compression, file offsets, and sizes.

Examples:

# Show all entries
OnexExplorerCli info path/to/file.NOS

# Show specific entries
OnexExplorerCli info path/to/file.NOS --entry 0 1 2

# JSON output for a single entry
OnexExplorerCli info path/to/file.NOS --entry 0 --json

Build and run the standalone CLI

cmake -S standalone -B build/standalone
cmake --build build/standalone
./build/standalone/OnexExplorerCli --help

Build and run the test suite

cmake -S test -B build/test
cmake --build build/test
CTEST_OUTPUT_ON_FAILURE=1 cmake --build build/test --target test

# or run the test executable directly:
./build/test/OnexExplorerTests

To collect code coverage information, run CMake with the -DENABLE_TEST_COVERAGE=1 option.

Run clang-format

cmake -S test -B build/test

# view changes
cmake --build build/test --target format

# apply changes
cmake --build build/test --target fix-format

See Format.cmake for details. Dependencies can be installed via pip:

pip install clang-format==14.0.6 cmake_format==0.6.11 pyyaml

Build the documentation

The documentation is automatically built and published whenever a GitHub Release is created. To manually build documentation:

cmake -S documentation -B build/doc
cmake --build build/doc --target GenerateDocs
# view the docs
open build/doc/doxygen/html/index.html

You will need Doxygen, jinja2 and Pygments installed on your system.

Build everything at once

cmake -S all -B build
cmake --build build

# run tests
./build/test/OnexExplorerTests
# format code
cmake --build build --target fix-format
# run standalone
./build/standalone/OnexExplorerCli --help
# build docs
cmake --build build --target GenerateDocs