Decoding REXPaint Files in Odin: From Binary Format to Readable Data

Decode REXPaint's .xp binary format field by field in Odin, from file header to compressed blocks.
The article explains native decoding of REXPaint's .xp files in Odin. .xp is a binary format interleaving version numbers, layers, tiles, and compressed data. Decoding proceeds in stages—header, layer metadata, compressed blocks—with attention to byte order and field widths. Odin's slices offer readability plus low-level control for high-performance asset loading.
Why REXPaint Files Are Worth Decoding
REXPaint is a popular ASCII art editor used by roguelike developers. The .xp files it generates are not plain text but a binary format that interleaves version information, layers, tiles, and compressed data. For engineers building games or toolchains in Odin, being able to read these files natively means they can plug art assets directly into their own pipeline without relying on external conversion scripts.
The technical article discussed on Hacker News centers on exactly this need: rather than stopping at "call an existing library," the author parses the file field by field starting from the header, demonstrating a complete decoding path. The value of this kind of content is that it turns "format documentation" into "executable code logic."
Breaking Down the REXPaint File Structure
File Header and Version Number
The beginning of a .xp file contains a version identifier, and different versions may differ in layer count and data layout. The first step in decoding is to read and validate that version number; otherwise, the offsets of all subsequent fields will be misaligned.
In binary formats, a "version number" is usually not a simple integer but may appear as a magic number plus a version field. The magic number is a fixed byte sequence at the start of the file used to quickly identify the file type; the version field tells the parser the rules for the subsequent data layout. For .xp files, the version number determines the size of tile records, the offset of layer metadata, and whether extended fields are present. If a parser skips version validation, it may misinterpret unrelated bytes as valid data when encountering an older or newer file, leading to out-of-bounds reads or rendering corruption. A robust decoder therefore validates the magic number first, then branches into different parsing paths based on the version number, or at least performs compatibility checks against known versions. This "version-aware" design is very common in game asset formats and is a fundamental means of maintaining backward compatibility as formats evolve.
Layer and Tile Data
REXPaint organizes content using layers, and each layer consists of tiles on a two-dimensional grid. Each tile records not only the character code but also foreground and background color information. This means the decoder must advance in the order "layer → width/height → read cell by cell," rather than treating the entire file as a linear byte stream.
When parsing, the author pays particular attention to byte order and field-width alignment—details that are often hot spots for bugs in binary format handling.
Endianness refers to the order in which multi-byte data is arranged in memory or in a file: big-endian places the most significant byte first, while little-endian does the opposite. The x86 architecture generally uses little-endian, while some file formats or network protocols specify big-endian. If a parser does not read according to the byte order specified by the format, multi-byte integers will be misinterpreted—for example, color values or coordinate offsets will be completely misaligned. Field width is equally critical: a 16-bit integer and a 32-bit integer occupy different amounts of space in the byte stream, and if the width assumption is wrong, the starting position of every subsequent field will be offset. In Odin, you can use the binary package or explicit type conversions to handle byte order; for example, reading a u32 requires functions like le_u32 or be_u32 to ensure cross-platform consistency.
Compressed Data and Odin's Reading Strategy
REXPaint stores some data in compressed form, which adds complexity to direct reading. The article shows how to handle this in stages: first parse the uncompressed metadata, then decompress the compressed blocks, and finally map the restored bytes to the concrete tile structures.
In Odin, this workflow can be implemented with its built-in slices and byte manipulation capabilities. Compared with manually managing buffers in C, Odin's explicit type conversions and memory semantics make parsing code easier to read while still retaining full control over the underlying bytes. For game projects that need high-performance asset loading, this is a pragmatic compromise.
The implementation presented in the article is not a "one-line call" convenience wrapper but a parsing skeleton that readers can trim as needed. This style is more popular in systems programming communities because it exposes the format's boundary conditions instead of hiding complexity in a black box.
A slice is a value type in Odin that describes a contiguous memory range, consisting of a pointer and a length, and does not own the underlying data. When parsing binary files, slices are very suitable for representing "raw byte blocks that have not yet been parsed": you can read the entire buffer from the file and then advance through it slice by slice according to fields, avoiding frequent memory allocations. Odin's slices also support bounds checking (in safe mode), which can reduce the risk of out-of-bounds reads. Compared with manual management using raw pointers plus lengths in C, slices let length information travel with the data, making the code clearer. At the same time, Odin allows you to obtain the underlying pointer with raw_data when needed, balancing interoperability with C libraries or system calls. This "safe by default, low-level when needed" semantics is exactly the practical balance point of systems programming languages in parsing tasks.
Practical Significance for the Roguelike Toolchain
Reducing Format Lock-In
When developers can read .xp files directly in their own runtime, no intermediate export step is needed between art editing and game loading. After changing a character or map, simply rerun to see the result, significantly shortening the iteration loop.
Reusable Decoding Patterns
REXPaint's decoding approach—versioned file header, layered structure, separation of compressed blocks—recurs in many game asset formats. Once you master this pattern, you can reuse a great deal of the mental model when migrating to other binary formats.
Directions for Further Exploration
If you are building a game or development tool with Odin, you can extend this parser further: add write-back functionality, support batch conversion, or map tile data directly to the render buffer. Although the Hacker News discussion is not particularly high-traffic, it points to an often overlooked fact—format parsing capability itself is part of toolchain autonomy.
One-line Summary
Decode REXPaint's .xp binary format field by field in Odin, from file header to compressed blocks, unlocking the roguelike art asset pipeline.
Paragraph Summary
The article focuses on natively decoding REXPaint's .xp files in Odin. .xp is not plain text but a binary format that interleaves version numbers, layers, tiles, and compressed data. Decoding must proceed in stages: file header, layer metadata, and compressed blocks, with particular attention to byte order and field-width alignment. Odin's slices and byte manipulation capabilities let the parser balance readability with low-level control, making it suitable for high-performance asset loading. Native reading eliminates intermediate export steps, shortens the art iteration loop, and reduces format lock-in. The parsing skeleton presented in the article exposes boundary conditions rather than offering a black-box wrapper, and its patterns—versioned file header, layered structure, separation of compressed blocks—can be transferred to other game asset formats.
Related articles

Zed Editor Releases v1.29.2: Observations on a Routine Version Iteration
Zed editor releases patch v1.29.2, version bump by @JosephTLyons, commit verified via GitHub signature. This article covers the release's basic info, what a patch version means, and practical upgrade advice for users.

Anthropic IPO Questioned: Hacker News Debates Timing of Going Public
A Hacker News post titled "Just say no to Anthropic's IPO" sparks debate on the timing of Anthropic's public listing and AI capitalization, touching on valuation bubbles and mission independence.

Hands-On with the Genie 4 World Model: Directing Worlds in Real Time Like a Puppeteer
Google DeepMind's Genie 4 world model in depth: Special Guest X's hands-on demo of real-time scene direction via prompts, custom interactive apps in Project Genie, and prompts-as-seeds reproducibility.