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 --helpBuilding 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 --helpFor 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.
| 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,
* 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.
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.
-vor--verboseenables informational diagnostics. Repeat it (-vv) for debug diagnostics.RUST_LOGoverrides 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, andpatch applyaccept 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".--jsonwrites machine-readable inspection output to stdout.--checksumadds a 64-bit FNV-1a checksum where the command supports it.
| 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. |
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 --jsonThe 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.
taletool archive inspect "NStpData*.NOS"
taletool archive inspect snd.pck --type sound --json --checksum
taletool archive unpack "NSlangData_UK*.NOS" --out work/langThe 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.
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 --convertUse 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.
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 soundWith --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 4Known 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.
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.binMap 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.
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
A4R4G4B4frame sets used byNSmpData,NSppData, andNSipData. Unpacking normally creates a directory containingsprite.jsonandframe-NNN.pngfiles. Packing takes that directory.--png-onlywrites directly to one.pngfile 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
A8R8G8B8images used byNS4BbData. Unpacking writes directly to the.pngor.bmppath 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.bintaletool 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.txtAdd --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 --jsonlang 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).
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.binThe 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.lsttaletool 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-disabledpatch (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.
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.
