Skip to content
imxenoPublic

About

CLI and Rust library for inspecting, unpacking, and packing NosTale client data formats.

Resources

Stars

8 stars

Watchers

1 watching

Forks

Latest commit

 

History

59 Commits

Folders and files

Repository files navigation

Taletool hammer logo

taletool

A CLI and Rust library for inspecting, unpacking, and packing NosTale client data formats.

License: AGPL-3.0-or-later Rust 1.97 or newer Last commit

Installation

Prebuilt binaries

Prebuilt CLI archives for Windows, Linux, and macOS are available from GitHub Releases. Download the archive for your platform, extract it, and place the taletool executable somewhere on your PATH.

taletool --help

Install from source with Cargo

Building from source requires Rust 1.97.0 or newer and a C compiler for the vendored zlib implementation. Cargo can build and install Taletool directly from the Git repository:

cargo install --locked --git https://github.com/imxeno/taletool.git taletool
taletool --help

For a development checkout, clone the repository and run the CLI without installing it by putting arguments after --:

git clone https://github.com/imxeno/taletool.git
cd taletool
cargo run -p taletool -- scan --data-dir "C:\GameforgeLive\Nostale\NostaleData"

All examples below assume that taletool is installed and available on PATH.

Support

Name Contains Container support Asset support
NS4BbData.NOS Free-size sprite resources ✅ ✅
NScliData*.NOS Client const strings ✅ ✅
NSedData.NOS Effect color animation keyframes ✅ ✅
NSeffData.NOS Effect definitions ✅ ✅
NSemData.NOS Effect transform animation keyframes ✅ ✅
NSesData.NOS Effect texture animation frame keys ✅ ✅
NSetcData.NOS Typewriter mini-game and unused “taboo” word lists ✅ ✅
NSgrdData*.NOS Optimized map height grid data ✅ ✅
NSgtdData.NOS Game data files ✅ ✅
NSipData.NOS Map-item sprite resources ✅ ✅
NSlangData_<locale>.NOS Language files ✅ ✅
NSmcData.NOS Monster/NPC animation definitions ✅ ✅
NSmnData.NOS Monster/NPC GBFC index N/A ✅
NSmpData*.NOS Monster/NPC sprites ✅ ✅
NSpcData.NOS Player animation definitions ✅ ✅
NSpmData.NOS Player frame/resource remap tables ✅ ✅
NSpnData.NOS Player GBFC index N/A ✅
NSppData*.NOS Player sprites ✅ ✅
NStcData.NOS Map cell flags ✅ ✅
NStgData*.NOS Geometry ✅ ✅
NStgeData.NOS Effect geometry ✅ ✅
NStkData.NOS Map neighborhood data ✅ ⚠️
NStpData*.NOS Textures ✅ ✅
NStpeData*.NOS Effect textures ✅ ✅
NStpuData*.NOS UI/widget textures ✅ ✅
NStsData.NOS Unknown and unused map-related data ✅ ❌
NStuData*.NOS Map settings and geometry object trees ✅ ✅
BGM* BGM audio files N/A N/A
*.ntm, *.nam Intro/act videos N/A N/A
snd.pck Audio files ✅ N/A
sndinfo.lst Audio metadata N/A ✅
*.PKG NosTale patch packages ⚠️ ⚠️

✅ supported, ⚠️ partial support, ❌ not supported, N/A not applicable as an independent container or asset layer

* groups the observed names for a family. Exact single, split, locale, and locale+chunk filename patterns are listed in the format docs.

See the docs for file format notes.

Usage

The CLI is intentionally low-level. It primarily showcases the functionality provided by the Taletool libraries and exposes the underlying file-format operations without imposing a higher-level modding workflow.

You are welcome to use the Taletool libraries in your own projects, including modding tools, graphical editors, and other NosTale utilities.

The CLI and library APIs are not stable yet. This is also why the project has not been published to crates.io. Expect breaking changes and pin an exact commit when consuming Taletool from another project.

The command tree follows the data hierarchy: archive handles full .NOS and .pck containers, while commands such as map, texture, and text handle individual payloads extracted from those containers.

taletool [OPTIONS] <COMMAND>

Use taletool --help, taletool <COMMAND> --help, or taletool <COMMAND> <SUBCOMMAND> --help for built-in help.

Global Options and Input Paths

  • -v or --verbose enables informational diagnostics. Repeat it (-vv) for debug diagnostics. RUST_LOG overrides this verbosity-derived log filter.
  • Options marked as global, such as -v, can appear before or after a subcommand.
  • archive inspect, archive extract, archive unpack, patch inspect, and patch apply accept multiple paths. They also expand quoted * and ? filename patterns case-insensitively within one directory. You should quote wildcard inputs, especially in shells that perform their own wildcard expansion: "NStpData*.NOS".
  • --json writes machine-readable inspection output to stdout. --checksum adds a 64-bit FNV-1a checksum where the command supports it.

Command Overview

Command Purpose
scan Classify supported files in a client data directory.
archive Inspect, extract, unpack, and pack archive containers.
animation Work with NSmcData and NSpcData animation payloads.
map Work with NStuData map payloads.
ccinf Work with NSmnData and NSpnData GBFC index files.
effect Work with definitions and animation payloads for effects.
geometry Work with NStgData and NStgeData geometry payloads.
height-grid Work with NSgrdData optimized height grids.
map-neighborhood Work with NStkData map-neighborhood payloads.
sprite Convert map-object or free-size sprites to and from PNG.
sprite-remap Work with NSpmData frame/resource remap payloads.
patch Inspect or apply original .PKG patch packages.
text Decode or encode individual DAT, LST, and raw text payloads.
audio Convert sndinfo.lst audio metadata to and from JSON.
texture Convert texture payloads and mip levels to and from PNG.
cell-flag Export an extracted NStcData grid as PNG.

Scanning a Data Directory

taletool scan --data-dir <DATA_DIR> [--no-recursive] [--show-unsupported]
  [--json] [-v]

scan recursively examines a client data directory and reports paths relative to that directory. By default, it shows recognized .NOS and .pck files and identifies Ogg, MP3, RIFF/WAVE, and MPEG media from their header bytes, regardless of the filename or extension. Media files are reported as type=audio or type=video. Add --no-recursive to examine only immediate files. Add --show-unsupported to include every other regular file with type=unsupported. Add -v to include archive counts and media format details. Combine -v with --json to include those details in each JSON result.

taletool scan --data-dir "C:\NosTale\NostaleData"
taletool scan --data-dir "C:\NosTale\NostaleData" --show-unsupported -v --json

Archive Containers

The archive commands support binary .NOS tables, text .NOS record archives, and snd.pck.

taletool archive inspect <INPUT>... [--type <TYPE>] [--json] [--checksum]
taletool archive extract <INPUT>... (--id <ID>... | --ids <FILE>) --out <DIR> [--convert]
taletool archive unpack <INPUT>... --out <DIR> [--type <TYPE>] [--convert] [--encoding <ENCODING>] [--plain-text]
taletool archive pack <DIR> --out <OUT> [OPTIONS]

--type accepts auto (the default), binary, text, or sound. Automatic detection requires exactly one parser to match. Use an explicit type for a renamed or ambiguous file. Text and sound archives take one input; binary archives may take multiple chunks from the same family. Automatic detection only accepts text archives without trailing bytes, while --type text also accepts parsed text archives that contain trailing data.

CCINF files (NSmnData.NOS and NSpnData.NOS) are standalone assets rather than archive containers. Use the dedicated ccinf command for them.

Inspecting and Unpacking

taletool archive inspect "NStpData*.NOS"
taletool archive inspect snd.pck --type sound --json --checksum
taletool archive unpack "NSlangData_UK*.NOS" --out work/lang

The unpacked layout depends on the container:

Type Output layout
binary Raw payloads named by numeric ID, for example 42.bin.
text Encoded record payloads plus a text-archive.json manifest.
sound Ordered payload files plus a required sound-pack.json manifest.

Binary filenames preserve metadata needed for a stable round trip. A filename can contain a duplicate ordinal (42__2.bin), an explicit table slot (42__index7.bin), and a per-entry compression override (42__raw.bin or 42__zlib.bin). archive pack reads immediate files whose names begin with a decimal ID and ignores other files.

IDs accept signed 32-bit decimal values or unsigned values through 4294967295; for example, -1.bin and 4294967295.bin represent the same ID bits. Unindexed payloads are sorted by unsigned ID. Explicit table slots preserve archive order, including direct-index layouts and duplicate rows.

Text archive filenames use %HH escapes for characters that are not ASCII letters, digits, ., -, or _. text-archive.json keeps each record's original name, ID, packed flag, and order, so repeated names get numbered filenames such as Item__2.dat. Archive unpacking without --convert preserves the encoded DAT/LST payloads for a lossless archive-level unpack/pack workflow.

Add --convert to export supported binary archives as JSON, PNGs, or manifests, and supported text archives as structured JSON. Use --plain-text to unwrap text DAT/LST records instead. Sound packs keep their unpacked layout.

Extracting Specific IDs

archive extract selects numeric IDs from binary .NOS archives using NosTale's direct-index and unsigned binary-search rules. Supply one archive or chunks from one family. Among supplied paths, an unsuffixed archive takes precedence; otherwise each ID selects its family's numbered chunk. Missing chunks and IDs are reported as missing without searching other chunks. Only the supplied paths are considered.

taletool archive extract "NStgData*.NOS" --id 42 99 --id 100 --out work/selected
taletool archive extract "NStpData*.NOS" --ids ids.txt --out work/textures --convert

Use either repeated --id options or --ids <FILE>. The UTF-8 file accepts whitespace-separated IDs, blank lines, and # comments. IDs accept signed 32-bit decimal, unsigned decimal, and 0x hexadecimal values; they are normalized to signed decimal in filenames and reports. Repeated IDs are extracted once, in first-requested order. Invalid or empty ID lists fail before writing output.

Found payloads are decompressed and written as <id>.bin. With --convert, selected payloads use the same family-specific JSON, PNG, or manifest-directory output as archive unpack --convert, named for the requested ID. The output directory must not already exist and is published only after all selected payloads are read and converted successfully. Conversion requires a recognized binary family and is export-only. Text archives and sound packs are handled by archive unpack.

Each requested ID gets a found or missing line. Found lines include the decoded payload's byte size and SHA-256, stored row ID and size, source archive, and output path. The size and SHA-256 always describe the payload before conversion, including when conversion creates multiple files. Missing lines use size=- sha256=-; the final line gives found and missing counts. Missing IDs do not cause a failing exit status.

Packing

For known binary archive names, the default --preset auto infers the archive header, direct-index byte, compression profile, chunk count, routing strategy, and filename pattern from --out. An explicit preset is useful when --out is a directory or a renamed file:

taletool archive pack work/nstp --out rebuilt --preset NStpData
taletool archive pack work/lang --out NSlangData_UK.NOS --type text
taletool archive pack work/sound --out snd.pck --type sound

With --type auto, a sound-pack.json manifest or .pck output selects sound; an NSgtdData/NSlangData preset or output name selects text; a directory containing only numeric payload filenames selects binary; and any other directory selects text.

Binary packing options are:

Option Meaning
--preset <NAME> Known family, auto (default), or none.
--header-hex <HEX> Exact 16-byte header as 32 hex digits.
--direct-index <0..255> Override the header's direct-index byte.
--compression <MODE> auto, raw, or zlib; per-file suffixes can override it.
--zlib-profile <PROFILE> auto or zlib112-levelN-STRATEGY.
--chunking <MODE> single, family, or low-byte.
--chunk-count <COUNT> Number of output chunks; must be greater than zero.
--chunk-format <FORMAT> Chunk filename pattern below the --out directory.

--header-hex may contain whitespace and underscores. A zlib profile level is 0 through 9, and its strategy is default, filtered, or huffman. Family chunking uses the selected preset's client routing rule and defaults to its addressable chunk count. Low-byte chunking explicitly uses file_id & 0xff. The selected chunk must be smaller than --chunk-count. Single chunking writes one unsuffixed archive by default and requires a chunk count of one.

Split output patterns may contain {chunk}, {chunk:02x}, or {chunk:02X}. Use the token directly in --out, or pass a base directory in --out and the filename through --chunk-format:

taletool archive pack work/custom --type binary \
  --out "rebuilt/Custom{chunk:02X}.NOS" \
  --header-hex "4e542044617461203939000015070420" \
  --compression zlib --zlib-profile zlib112-level9-default \
  --chunking low-byte --chunk-count 4

Known presets are:

Preset Storage Chunks Default output
NS4BbData zlib-9 1 NS4BbData.NOS
NSedData raw 1 NSedData.NOS
NSeffData raw 1 NSeffData.NOS
NSemData raw 1 NSemData.NOS
NSesData raw 1 NSesData.NOS
NSgrdData raw 1 NSgrdData.NOS
NSipData zlib-1 1 NSipData.NOS
NSmcData raw 1 NSmcData.NOS
NSmpData zlib-1 16 NSmpData{chunk:02X}.NOS
NSpcData raw 1 NSpcData.NOS
NSpmData raw 1 NSpmData.NOS
NSppData zlib-1 32 NSppData{chunk:02X}.NOS
NStcData zlib-9 1 NStcData.NOS
NStgData raw 4 NStgData{chunk:02X}.NOS
NStgeData raw 1 NStgeData.NOS
NStkData raw 1 NStkData.NOS
NStpData raw 32 NStpData{chunk:02X}.NOS
NStpeData raw 8 NStpeData{chunk:02X}.NOS
NStpuData raw 4 NStpuData{chunk:02X}.NOS
NStuData zlib-9 1 NStuData.NOS

zlib-1 and zlib-9 mean the zlib 1.1.2 default strategy at the indicated level. All multi-chunk presets use family routing: NStgData and NStpuData use id & 3; NStpData uses id & 31; NStpeData uses id & 7; NSmpData uses (id & 0x3c00) >> 10; and NSppData uses (id & 0xf800) >> 11.

NSgrdData and NS4BbData retain single-file defaults. Select --chunking family to write their split layouts (8 chunks using id & 7, and 4 chunks using id & 3, respectively). See split archive rules for loading behavior.

JSON Payload Commands

The following command groups share the same inspect/unpack/pack interface:

taletool <GROUP> inspect <INPUT> [--json] [--checksum]
taletool <GROUP> unpack <INPUT> --out <OUTPUT.json>
taletool <GROUP> pack <INPUT.json> --out <OUTPUT>
Group Payload family
animation NSmcData and NSpcData sprite animations.
map NStuData scene settings and object trees.
ccinf NSmnData and NSpnData GBFC indexes.
geometry NStgData and NStgeData geometry.
height-grid NSgrdData optimized height grids.
map-neighborhood NStkData neighbor maps and point sequences.
sprite-remap NSpmData frame/resource ordering tables.

inspect prints a summary without writing files. unpack writes an editable JSON document, and pack rebuilds a payload from that document. The round-trip editing workflow is to unpack, modify, and pack the generated document:

taletool geometry inspect work/nstg/100.bin --json --checksum
taletool geometry unpack work/nstg/100.bin --out work/geometry-100.json
taletool geometry pack work/geometry-100.json --out work/nstg/100.bin

Map documents represent NaN floating-point values as null. map pack reads those nulls back as NaN. JSON round trips preserve NaN values but do not preserve their original bit patterns.

Effect payloads use the same pattern, with an additional kind selector on inspect and unpack:

taletool effect inspect <INPUT> [--kind <KIND>] [--json] [--checksum]
taletool effect unpack <INPUT> --out <OUTPUT.json> [--kind <KIND>]
taletool effect pack <INPUT.json> --out <OUTPUT>

--kind accepts auto, color-animation (NSedData), definition (NSeffData), transform-animation (NSemData), or texture-animation (NSesData). Automatic detection requires exactly one semantic format to match. Packing reads the kind from the JSON document.

Effect and geometry key times may repeat or decrease within a track, as they do in shipped effects. inspect, unpack, pack, and archive unpack --convert keep them as stored and warn about each key whose time is lower than the one before it, because NosTale's key search can then return keys out of order.

Sprites

taletool sprite inspect <INPUT> [--kind <KIND>] [--json] [--checksum]
taletool sprite unpack <INPUT> --out <OUTPUT> [--kind <KIND>]
  [--format png|bmp] [--png-only]
taletool sprite pack <INPUT> --out <OUTPUT> [--kind <KIND>]

--kind accepts auto, map-object, or free-size:

  • Map-object sprites are counted A4R4G4B4 frame sets used by NSmpData, NSppData, and NSipData. Unpacking normally creates a directory containing sprite.json and frame-NNN.png files. Packing takes that directory. --png-only writes directly to one .png file and therefore requires a single populated frame. Empty frames and dimensions above 512 pixels are accepted. Empty frames retain their dimensions and source coordinates in the manifest and have no image file.
  • Free-size sprites are single block-interlaced A8R8G8B8 images used by NS4BbData. Unpacking writes directly to the .png or .bmp path supplied by --out, and packing takes a PNG or BMP file.

--format defaults to png. Select --format bmp to avoid PNG compression. Map-object output then contains frame-NNN.bmp images and sprite.json. BMP output uses a 108-byte V4 header, 32-bit BGRA pixels, BI_BITFIELDS, and explicit red, green, blue, and alpha masks (0x00FF0000, 0x0000FF00, 0x000000FF, 0xFF000000). The signed height is negative, so rows run from top to bottom. Alpha is straight; RGB values are preserved even when alpha is zero. Each A4R4G4B4 channel expands by multiplying by 17. BMP size calculations are checked against its 32-bit file-size fields. --png-only cannot be combined with --format bmp.

Populated PNG frame sets continue to use version 1 manifests. BMP exports and frame sets containing empty frames use version 2. Both versions are accepted by sprite pack. Version 2 records width and height for every frame and encoding (png or bmp) for each populated frame. Empty frames have "image": null and no encoding. For example:

{
  "format": "sprite",
  "version": 2,
  "pixel_format": "a4r4g4b4",
  "frames": [
    {
      "image": null,
      "source_x": -7,
      "source_y": 12,
      "width": 0,
      "height": 17
    },
    {
      "image": "frame-001.bmp",
      "source_x": 4,
      "source_y": -3,
      "encoding": "bmp",
      "width": 513,
      "height": 2
    }
  ]
}

Packing takes populated frame dimensions from the image, allowing resizing; empty frame dimensions come from the manifest. Image references must be unique filenames within the sprite directory and match their declared encoding.

For packing, auto selects map-object for a directory and free-size for a PNG or BMP file. For inspection and unpacking, auto validates both payload layouts and requires exactly one to match, without decoding image buffers. Unpacking buffers the encoded input; map-object BMP export expands only one row at a time, while PNG export decodes one frame at a time.

taletool sprite unpack work/nsip/17.bin --out work/sprite-17
taletool sprite unpack work/nsmp/42.bin --out work/sprite-42 --format bmp
taletool sprite pack work/sprite-17 --out work/nsip/17.bin
taletool sprite unpack work/ns4bb/5.bin --kind free-size --out work/5.png
taletool sprite pack work/5.png --kind free-size --out work/ns4bb/5.bin
taletool sprite unpack work/ns4bb/5.bin --out work/5.bmp --format bmp
taletool sprite pack work/5.bmp --out work/ns4bb/5.bin

Text Payloads

taletool text inspect <PAYLOAD> [--kind <KIND>]
taletool text unpack <PAYLOAD> --out <OUTPUT> [--kind <KIND>]
  [--json] [--format <FORMAT>] [--encoding <ENCODING>]
taletool text pack <INPUT> --out <OUTPUT> [--kind <KIND>]
  [--json] [--format <FORMAT>] [--encoding <ENCODING>]

The payload kind controls the byte-level codec:

Kind Automatic filename match Behavior
dat .dat, .txt NosTale compact DAT encoding.
list .lst Length-prefixed LST line table.
raw Any other extension Copy bytes unchanged.

--kind auto is the default and uses the input filename for inspect/unpack or the output filename for pack. For plain-text unpacking, an --out path with an extension is used directly. A path without an extension is treated as a directory and receives <payload-stem>.txt.

taletool text inspect work/lang/_code_uk_Item.txt
taletool text unpack work/lang/_code_uk_Item.txt --out work/text/Item.txt
taletool text pack work/text/Item.txt --out work/lang/_code_uk_Item.txt

Add --json for structured NSgtdData, language, constant-string, and NSetc string data. --format accepts auto, gtd, lang, cli, or etc and may only be used with --json. NSgtdData documents are versioned, source-oriented objects selected by their native record name. Language and constant-string documents require DAT payloads and use an ordered [[key, value], ...] JSON shape; language keys are strings and constant-string keys are signed integers. NSetc documents accept DAT or LST payloads and use an ordered [value, ...] string array.

NSgtdData JSON retains source order, duplicate entries, repeated fields, signed values, opaque ZTS keys, and independently declared counts. Each document has a schema_version and a filename-selected kind. Item documents keep line_desc_count independent from their description. description holds the rows read after a positive count; with a non-positive count, the client reads only the text after the count on the LINEDESC row, stored as inline_description. Packing rejects a non-empty description with a non-positive count. Likewise, Skill description.lines holds the rows read after a positive count, and the text after a non-positive count on the Z_DESC row is stored as inline_text; packing rejects lines with text under a non-positive count. BCard, Card, Item, monster, and Skill entries omit numeric rows that their source entry lacks, and Card entries keep an ICON row as icon. BCard entries hold the client's five text slots, whatever their DESC count: subject_slots holds SUBJ0 through SUBJ4, and list_slots holds LIST1-1 through LIST5-2. Other numbered SUBJ and LIST rows, which the client ignores, are kept in ignored_rows. When a row is repeated in one BCard, Card, Item, monster, or Skill entry, or a Card KIT or Z_ETC row is repeated for one slot, only what the client loads is kept, with a warning when a later row replaces different values or text; Skill BASIC rows are all kept. Abuse documents distinguish a zero-byte payload from a counted empty list; undecodable legacy text uses a reversible bytes_base64 entry instead.

Rows whose field counts vary between data revisions retain their complete token sequences in JSON. Packing writes those sequences unchanged, including empty, shorter, longer, and partially grouped rows. In BCard, Card, Item, monster, and Skill rows, each token is stored as the number the client reads, so $10 becomes 16. A token the client cannot read as a number becomes, with a warning, the client's default for its position, or -1 where the client ignores the value. Monster ETC booleans keep a decimal integer, and other tokens become 1 or 0 as the client reads them, with a warning for text other than a number, True, or False.

Map ID, map point, and fish rows instead follow the client's reader. A missing or non-numeric value becomes -1 with a warning in map ID and map point rows and in the fish values the client reads, although a DATA row without values stays empty. Map and point names keep the rest of their row, including spaces. Fish ITEM and BASIC weights are optional, and weight is omitted from JSON when a row has none. Other tokens after the values of a fish VNUM, LEVEL, MAPT, MAP, ITEMT, or ITEM row are dropped with a warning unless they start a // comment. Fish POST, POS, BASICT, and BASIC rows, which the client ignores, are kept only with exactly their integer fields, the BASIC weight being optional; other such rows are dropped with a warning. Of repeated LEVEL, MAPT, ITEMT, or BASICT rows in one fish, or POST rows for one map, only the last is kept, with a warning. Fish ITEM rows with a slot outside 0-61 and MAP rows with a slot outside 0-2 are dropped with a warning, and packing rejects such slots, because the client writes them into other fields of the fish.

NosMall entries require only vnum; rows absent from the source are omitted. A NosMall row value that is not a plain decimal integer, such as a True VNUM flag or a +$2 LINK count, stays a JSON string, and link holds the LINK count followed by the linked IDs. Packing rejects a LINK count that the client reads as a negative 16-bit value, ID and title values that start with whitespace, and description lines that the client would read as a terminator or, past its 20-row description scan, as a tagged row.

Decorative END, end, E, and ~ rows are not exposed as JSON framing. Reader-visible exceptions are normalized semantically: tutorial ~ becomes a step -1 command, shop-type ~ becomes a vnum -1 row, Skill END outside a description becomes an empty effect row, and Skill output adds the leading-# boundary required to keep a positive description from consuming the following skill.

The recognized core filenames are act_desc.dat, BCard.dat, Card.dat, Item.dat, monster.dat, npctalk.dat, Skill.dat, quest.dat, qstprize.dat, tutorial.dat, shoptype.dat, MapIDData.dat, MapPointData.dat, qstnpc.dat, team.dat, and fish.dat. Locale records use <locale>_nosmall.dat and <locale>_abuse.lst for cn, cz, de, es, fr, gsp, hk, in, it, jp, kr, my, pl, ru, tr, tw, and uk.

taletool text unpack work/lang/_code_uk_Item.txt --out work/Item.json --json
taletool text pack work/Item.json --out work/lang/_code_uk_Item.txt --json

taletool text unpack work/cli/conststring.dat --out work/conststring.json \
  --json --encoding windows-1252
taletool text pack work/conststring.json --out work/cli/conststring.dat \
  --json --encoding windows-1252

taletool text unpack work/etc/MiniGame6WordData.dat \
  --out work/MiniGame6WordData.json --json
taletool text pack work/MiniGame6WordData.json \
  --out work/etc/MiniGame6WordData.dat --json

taletool text unpack work/etc/TabooStr.lst --out work/TabooStr.json --json
taletool text pack work/TabooStr.json --out work/etc/TabooStr.lst --json

taletool text unpack work/gtd/Item.dat --out work/Item.json --json
taletool text pack work/Item.json --out work/gtd/Item.dat --json

lang is inferred from native _code_<locale>_<table>.txt names. Its encoding is inferred as follows:

Locales Encoding
cz, pl Windows-1250
ru Windows-1251
de, es, fr, gsp, in, it, my, uk Windows-1252
tr Windows-1254
hk, tw Big5
jp Shift_JIS
cn GBK

Use --encoding for an unknown or renamed locale. cli is inferred from conststring.dat but always requires --encoding. etc is inferred from MiniGame6WordData.dat and TabooStr.lst; it defaults to EUC-KR and accepts an encoding override. Accepted labels are big5, euc-kr/euckr/windows-949/cp949, gbk/windows-936/cp936, shift-jis/shiftjis/sjis/windows-932/cp932, and windows-1250 through windows-1254 (or the corresponding cp1250, cp1251, cp1252, and cp1254 aliases).

Textures

taletool texture inspect <INPUT> [--json] [--checksum]
taletool texture unpack <INPUT> --out <DIR>
taletool texture pack <DIR> --out <OUTPUT>

Unpacking creates texture.json and ordered mip-NNN.png images. Edit the PNG files and manifest in place, then pass the directory back to pack. The version 2 manifest preserves the pixel format, filtering fields, and stored mip count. Each mip_levels entry contains the PNG filename in image and its exported width and height. PNG dimensions determine the rebuilt dimensions and must form a valid mip chain; the manifest dimensions are informational. pack also accepts version 1 manifests that list only PNG filenames.

taletool texture unpack work/nstp/100.bin --out work/texture-100
taletool texture pack work/texture-100 --out work/nstp/100.bin

Audio Metadata

The audio command handles sndinfo.lst. The audio data in snd.pck is handled by archive --type sound.

taletool audio inspect <INPUT> [--json] [--wave-dir <DIR>]
taletool audio unpack <INPUT> --out <OUTPUT.json>
taletool audio pack <INPUT.json> --out <OUTPUT>

--wave-dir resolves each metadata entry against loose files in the client's wave directory and reports the resolved path or a missing entry. The generated JSON preserves ordered keys, filename storage, unknown bytes, and trailing bytes for round trips.

taletool audio inspect sndinfo.lst --wave-dir "C:\NosTale\wave"
taletool audio unpack sndinfo.lst --out work/sndinfo.json
taletool audio pack work/sndinfo.json --out rebuilt/sndinfo.lst

Map Cell Flags

taletool cell-flag export-png <PAYLOAD> --out <OUTPUT.png> [--flag <FLAG>]

Without --flag, every distinct flag byte receives a stable color and the CLI prints a value/color/count legend. With --flag, cells containing the selected bit are black and all other cells are white.

Named flags are walking-disabled, attack-through-disabled, unknown-04, monster-aggro-disabled, and pvp-disabled. Any single non-zero bit from 0x01 through 0x80 can also be supplied in decimal or hexadecimal. Combined masks such as 0x03 are rejected.

taletool cell-flag export-png work/nstc/42.bin --out work/map-42-flags.png
taletool cell-flag export-png work/nstc/42.bin --out work/map-42-walls.png \
  --flag walking-disabled

Patch Packages

patch (also available as pak) parses original NosTale .PKG patch packages.

taletool patch inspect <PACKAGE>... [--json]
taletool patch apply --root <CLIENT_ROOT> <PACKAGE>...
  [--dry-run] [--backup-dir <DIR>]

Inspect packages before applying them, then perform a dry run against the target client:

taletool patch inspect "patches/*.PKG" --json
taletool patch apply --root "C:\NosTale" "patches/*.PKG" --dry-run
taletool patch apply --root "C:\NosTale" "patches/*.PKG" \
  --backup-dir "C:\NosTale-backups\update-1"

Package paths are wildcard-expanded, sorted, and deduplicated before parsing. Because package operations are order-dependent, ensure that lexical path order is the intended application order.

--dry-run resolves all operations and prints planned writes and removals without changing the client. A real apply backs up replaced or removed files before committing changes. Without --backup-dir, backups go below <CLIENT_ROOT>/.taletool/backups/run-<timestamp>-<pid>. If a commit fails, taletool attempts to roll back files already changed during that run.

License

Taletool is licensed under the GNU Affero General Public License version 3 or later (AGPL-3.0-or-later). See LICENSE.

Third-party code keeps its original license. See NOTICE.md.

About

CLI and Rust library for inspecting, unpacking, and packing NosTale client data formats.

Resources

Stars

8 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages