HN 日本語サマリー

← 一覧へ戻る
プログラミング

OdinでREXPaintファイルをデコードする

Decoding REXPaint Files in Odin (tylerelton.com)

12 pointsby tylerelton1 コメント

要約

この記事では、Odinプログラミング言語を使用して、REXPaintの.xpバイナリファイルのデコード方法を解説しています。ファイルフォーマットの構造、圧縮、データレイアウト、バイトレベルの解析について説明し、バージョン、レイヤー、セルの読み込みのためのOdinコードスニペットを提供しています。

全文翻訳

OdinでREXPaintファイルをデコードする

REXPaintは、素晴らしいローグライクゲームCogmindの開発者であるKyzrati氏によるASCIIアートツールです。UI、フルスクリーンのアート、レベルのプレハブをデザインするために使用でき、私のゲームであるFimbulに最適です。この記事では、REXPaintの.xpファイルをデコードする手順を説明します。バイナリファイルフォーマットを扱ったことがない場合、これは開始するのに適した簡単なものです!

Grid Sage Gamesは、公式のREXPaintマニュアルをプレーンテキスト1で公開しており、Steve Landey氏がより読みやすいHTML版2をホストしています。この記事では、セクションに直接リンクがあるため、HTML版を参照します。ここに記載されているすべては、REXPaint v1.70に基づいています。

注意

この記事では、Odinプログラミング言語を使用します。すべての構文を網羅するわけではありませんが、コードのより高度なセクションについては説明を試みます。言語のより完全な概要については、demo.odinを参照してください。

前提条件

ついていくためには、Odinコンパイラが必要です。私はバージョンdev-2026-10を使用しています。以下のスニペットは、main.odinの隣の独自のディレクトリにxpパッケージを構築します。

.
├── main.odin
├── test.xp
└── xp
    ├── decode.odin
    └── xp.odin

各スニペットは追加するインポートを示していますが、それらはファイルの先頭に配置されます。

警告

最新バージョンdev-2026-11は、core:compressパッケージをオーバーホールし、この記事で使用しているcore:compress/gzipを含むいくつかのものを非推奨にしました。そのバージョンはまだnixpkgs-unstableにはありません(ちなみに私はNixOSを使用しています)。それが利用可能になったら、この記事を新しいコードで更新します。

ステップ0: フォーマット

xxdでREXPaintファイルを見ると、gzip圧縮されていることがわかります。

$ xxd ./assets/screens/title.xp | head -1
00000000: 1f8b 0800 0000 0000 000b ed9c db6d c330  .............m.0

最初の2バイト1f8bはマジックナンバーであり、ファイルフォーマットを識別する固定バイトシーケンスです。すべてのgzipファイルはこれに始まります。次に08、圧縮方法が続きます。RFC 1952は、DEFLATEであるメソッド8のみを定義し、0から7を予約しています3。DEFLATE自体はLZ77とハフマンコーディングを組み合わせています。

解凍後、レイアウトはシンプルです。すべての値はリトルエンディアンであり、ファイル全体はいくつかの整数とそれに続く長いセルの実行です4。

フィールドタイプサイズ備考
versioni324バイト常に負、通常は-1
レイヤー数i324バイトREXPaint v1.70では1〜9
widthi324バイトレイヤーごとに1回
heighti324バイトレイヤーごとに1回
characteri324バイトセルごとに1回
foreground3 × u83バイトRGB、セルごとに1回
background3 × u83バイトRGB、セルごとに1回

これらのフィールドを実際のファイルで確認するには、まず解凍する必要があります。この記事の後半にあるテストファイルをzcatにパイプすると、次のようになります。

$ zcat ./test.xp | xxd | head -1
00000000: ffff ffff 0100 0000 4600 0000 0700 0000  ........F.......

4バイトずつ読むと、versionは-1、レイヤーは1つ、widthは70(0x46)、heightは7です。

各レイヤーは独自のwidthとheightを格納し、その後にwidth * height個のセルがそれぞれ10バイトずつ続きます。セルは列優先順序で格納されており、REXPaintは最初の列全体を上から下へ書き込み、次に2番目の列を書き込みます。各セルのcharacterフィールドは、REXPaintのフォントへのインデックスであり、デフォルトではCP437コードページを使用しています5。つまり、1は制御文字ではなく、スマイリーフェイス(☺)です。

空のセルはさらに別のルールに従います。REXPaintは、背景色255, 0, 255(ホットピンク)を透明として扱い、すべての空のセルは、ベースレイヤー上であってもこれを使用します6。レイヤーが互いに重ねて描画される場合、最も低いレイヤーに表示される透明なセルは黒として描画されるべきです。

Odinでは、これらの各部分がstructになります。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Color :: struct {
	r: u8,
	g: u8,
	b: u8,
}

Cell :: struct {
	character:  i32,
	foreground: Color,
	background: Color,
}

Layer :: struct {
	width:  i32,
	height: i32,
	cells:  []Cell,
}

File :: struct {
	version: i32,
	layers:  []Layer,
}

デコードはいくつかの異なる方法で失敗する可能性があり、どの方法で失敗したかを知りたいです。単純なboolでは、何かが間違っていたことしかわかりませんが、なぜ間違っていたかはわかりません。そのため、まず独自のカスタムエラータイプを定義します。

1
2
3
4
5
6
7
8
9
10
11
12
13
import "core:compress/gzip"

Read_Error :: enum {
	None = 0,
	Offset_Goes_Past_Data, // データが終了する前に読み込みを終了しました
	Bad_Dimensions, // レイヤー数、幅、または高さが負です
	Size_Overflow, // レイヤーがMAX_CELLS_PER_LAYERを超えるセル数を持っています
}

Decode_Error :: union #shared_nil {
	gzip.Error,
	Read_Error,
}

Read_Errorは、私たち自身の解析で間違いうるすべてのことをカバーします。Decode_Errorはこれをgzipのエラータイプとまとめてラップし、単一の戻り値でどちらの種類の失敗も記述できるようにします。#shared_nilディレクティブは、任意のバリアント(Read_Error.Noneを含む)からのnilがユニオン全体をnilにし、err == nilは「すべて正常に動作した」と読み取れることを意味します。バイトを解析するプロシージャはRead_Errorを返し、トップレベルのプロシージャのみが完全なDecode_Errorを返します。

ステップ1: core:compress/gzipによる展開

Odinのcore:compress/gzip7パッケージは、ファイルをバイトバッファに解凍できます。decode_from_fileという名前のプロシージャ(Odinでは関数、または略して「proc」)を作成し、後でdecode_from_bytesをスタブします。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
package xp

import "core:bytes"
import "core:compress/gzip"

decode_from_file :: proc(
	path: string,
	allocator := context.allocator,
) -> (
	f: File,
	err: Decode_Error,
) {
	buf: bytes.Buffer
	defer bytes.buffer_destroy(&buf)
	gzip.load_from_file(path, &buf, allocator = allocator) or_return

	raw := bytes.buffer_to_bytes(&buf)

	return decode_from_bytes(raw, allocator)
}

decode_from_bytes :: proc(
	b: []u8,
	allocator := context.allocator,
) -> (
	f: File,
	err: Decode_Error,
) {
	// TODO: バージョンとレイヤーを読み込む...
	return {}, nil
}

decode_from_fileは以下を行います。

  1. bufという名前の空のbytes.Buffer8構造体を宣言します。
  2. スコープの終了までbufのクリーンアップを遅延させます。
  3. allocatorを使用して、pathにあるファイルを解凍してbufにロードします。
  4. bytes.buffer_to_bytesを使用して、解凍されたバイトをbufから取得します。
  5. それらのバイトをスタブされたdecode_from_bytesに渡し、その結果を返します。

gzip行はor_returnを使用しており、これはOdinで最も一般的なエラー処理パターンのショートハンドです。呼び出しが返す最後の値がnilでないエラーの場合、or_returnはそのエラーを現在のprocからすぐに返します。gzip.ErrorがDecode_Errorのバリアントの1つであるため、gzipのエラーは呼び出し元に直接渡されます。or_returnがない場合、その行は次のようになります。

1
2
3
4
// roughly the same as: gzip.load_from_file(path, &buf, allocator = allocator) or_return
if load_err := gzip.load_from_file(path, &buf, allocator = allocator); load_err != nil {
	return {}, load_err
}

rawがbufを指しており、deferによって解放されることに気づくかもしれません。解放しても安全です。なぜなら、戻り値の式は遅延ステートメントの前に実行され、decode_from_bytesは必要なすべての値をFileにコピーするためです。このスタブはすぐに埋めます!

この時点で、解凍された.xpファイルの生のバイトがあります。それらをFile構造体に変換するには、固定サイズのチャンク(i32の場合は4バイト、u8の場合は1バイト)を読み取る必要があります。

ステップ2: 小さなカーソル

パーサーは2つのこと、つまりバイトとその中の位置だけを知る必要があります。2つのフィールドを持つstructで両方をカバーできます。

1
2
3
4
Reader :: struct {
	raw:    []u8,
	offset: int,
}

Readerの上に、2つのヘルパーが必要です。1つはi32を読み取り、もう1つはu8を読み取ります。それぞれが値を返し、offsetを前進させます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import "core:encoding/endian"

read_i32 :: proc(r: ^Reader) -> (v: i32, err: Read_Error) {
	if r.offset + 4 > len(r.raw) {
		return 0, .Offset_Goes_Past_Data
	}

	// 上記の長さチェックは、get_i32が失敗する唯一の方法です。
	val, _ := endian.get_i32(r.raw[r.offset:], .Little)
	r.offset += 4

	return val, .None
}

read_u8 :: proc(r: ^Reader) -> (v: u8, err: Read_Error) {
	if r.offset >= len(r.raw) {
		return 0, .Offset_Goes_Past_Data
	}

	val := r.raw[r.offset]
	r.offset += 1

	return val, .None
}

read_i32は、core:encoding/endianパッケージ9に依存して、4つのリトルエンディアンバイトをデコードします。endian.get_i32は独自の長さチェックを行い、4バイト未満のバイトが残っている場合はfalseを返しますが、なぜ失敗したかは教えてくれません。最初に自分で長さをチェックすることで、切り詰められたファイルが実際にヒットするエラーである.Offset_Goes_Past_Dataを報告できます。その長さチェックはget_i32が失敗する唯一の方法なので、ここではそのboolは常にtrueであり、無視できます。read_u8はスライスを直接インデックス付けし、チェックなしでは、末尾を超えて読み取るとパニックが発生します。

ステップ3: レイヤーとセルの解析

最初に解析する必要があるフィールドはversionです。新しいread_i32 procがそれを処理し、残りのバイトをread_layersに渡します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
decode_from_bytes :: proc(
	b: []u8,
	allocator := context.allocator,
) -> (
	f: File,
	err: Decode_Error,
) {
	r := Reader {
		raw    = b,
		offset = 0,
	}

	f.version = read_i32(&r) or_return
	f.layers = read_layers(&r, allocator) or_return

	return f, nil
}

read_i32はRead_Errorを返しますが、decode_from_bytesはDecode_Errorを返します。Read_Errorがユニオンのバリアントの1つであるため、or_returnはここでも機能します。

read_layersは、より興味深い部分です。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
import "base:runtime"

// レイヤーヘッダーは、幅と高さで構成されます。i32 + i32 = 4バイト + 4バイト = 8バイト
LAYER_HEADER_BYTES :: 8

read_layers :: proc(r: ^Reader, allocator: runtime.Allocator) -> (l: []Layer, err: Read_Error) {
	count := read_i32(r) or_return
	if count < 0 {
		return nil, .Bad_Dimensions
	}

	// 各レイヤーには少なくともヘッダーが必要なため、残りのバイト数
	// を保持できないカウントは不正です。割り当てる前に拒否します。
	if i64(count) * LAYER_HEADER_BYTES > i64(len(r.raw) - r.offset) {
		return nil, .Offset_Goes_Past_Data
	}

	l = make([]Layer, int(count), allocator = allocator)
	// エラーが発生した場合、私たちのゴミをクリーンアップします。
	defer if err != .None {
		for layer in l {
			delete(layer.cells, allocator)
		}

		delete(l, allocator)
	}

	for i in 0 ..< int(count) {
		l[i] = read_layer(r, allocator) or_return
	}

	return l, .None
}

ここでは、2つのアイデアが注目に値します。

1つ目は、ファイルから取得した数値を、実際に持っているデータと比較してチェックするまで決して信頼しないということです。レイヤーカウントは、誰かが書いた4バイトにすぎません。ファイルが切り詰められたり破損したりすると、20億レイヤーがあると主張する可能性があり、単純なmakeはすべてを割り当てようとします。各レイヤーには少なくとも8バイトのヘッダーが必要です。残りのバイトに収まらない可能性のあるカウントは、何も割り当てる前に拒否されます。また、i32がオーバーフローする可能性のある大きなcount * 8のために、乗算する前にi64に拡張します。

2つ目はdefer ifです。Odinのdeferはスコープを終了するときにステートメントを実行し、defer ifはその条件がその時点で真である場合にのみ実行します。ここでは条件はerr != .Noneなので、ブロックは失敗した場合にのみ実行されます。いずれかのread_layer呼び出しが途中で失敗した場合、or_returnはerrをそのエラーに設定して返され、遅延ブロックは既に読み取ったすべてのレイヤーを解放します。成功した場合、errは.Noneになり、呼び出し元がメモリを所有します。

read_layerも同様のパターンに従います。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// 健全性の制限。そのため、破損したヘッダーは大きなレイヤーを要求できません。
MAX_CELLS_PER_LAYER :: 4096 * 4096

// セルは、文字、前景、背景色で構成されます。
// i32 + 3 × u8 + 3 × u8 = 4バイト + 3バイト + 3バイト = 10バイト
CELL_BYTES :: 10

read_layer :: proc(r: ^Reader, allocator: runtime.Allocator) -> (l: Layer, err: Read_Error) {
	width := read_i32(r) or_return
	height := read_i32(r) or_return

	if width < 0 || height < 0 {
		return {}, .Bad_Dimensions
	}
	l.width, l.height = width, height

	n := i64(l.width) * i64(l.height)
	if n > MAX_CELLS_PER_LAYER {
		return {}, .Size_Overflow
	}

	// レイヤーカウントと同じ考え方:存在しないセルのために割り当てない。
	if n * CELL_BYTES > i64(len(r.raw) - r.offset) {
		return {}, .Offset_Goes_Past_Data
	}

	l.cells = make([]Cell, int(n), allocator = allocator)
	defer if err != .None {
		delete(l.cells, allocator)
	}

	for i in 0 ..< int(n) {
		l.cells[i] = read_cell(r) or_return
	}

	return l, .None
}

失敗したread_layerは、それ自身のセルをクリーンアップすることに注意してください。or_returnはread_layersでl[i]が割り当てられる前に終了するため、失敗したレイヤーはスライスに決して入りません。何も二重に解放されません。

最後に、セルと色は数回の読み取りで完了します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
read_cell :: proc(r: ^Reader) -> (c: Cell, err: Read_Error) {
	c.character = read_i32(r) or_return
	c.foreground = read_color(r) or_return
	c.background = read_color(r) or_return

	return c, .None
}

read_color :: proc(r: ^Reader) -> (c: Color, err: Read_Error) {
	c.r = read_u8(r) or_return
	c.g = read_u8(r) or_return
	c.b = read_u8(r) or_return

	return c, .None
}

セルは列優先順序で格納されていることを忘れないでください。(x, y)のセルは、y * width + xではなく、インデックスx * height + yにあります。小さなヘルパーがその詳細を1か所に保持します。

1
2
3
cell_at :: proc(l: Layer, x, y: i32) -> Cell {
	return l.cells[x * l.height + y]
}

ステップ4: 使用方法

decode_from_bytesは、各レイヤーがセルのスライスを所有しているため、ネストされた割り当てを持つFileを返します。それを呼び出す誰かがそのすべてのメモリを所有しており、デコードしたのと同じアロケータで解放する方法が必要です。

1
2
3
4
5
6
7
file_destroy :: proc(f: File, allocator := context.allocator) {
	for layer in f.layers {
		delete(layer.cells, allocator)
	}

	delete(f.layers, allocator)
}

これで、実際のファイルをデコードし、最初のレイヤーをターミナルに印刷できます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
package main

import "core:fmt"
import "xp"

main :: proc() {
	f, err := xp.decode_from_file("test.xp")
	if err != nil {
		fmt.eprintln("failed to decode test.xp:", err)
		return
	}
	defer xp.file_destroy(f)

	if len(f.layers) == 0 {
		fmt.eprintln("test.xp has no layers")
		return
	}

	layer := f.layers[0]
	for y in 0 ..< layer.height {
		for x in 0 ..< layer.width {
			c := xp.cell_at(layer, x, y)
			// CP437とASCIIは印刷可能な範囲でのみ一致します。
			if c.character >= 32 && c.character <= 126 {
				fmt.print(rune(c.character))
			} else {
				fmt.print(' ')
			}
		}
		fmt.println()
	}
}

デコードが失敗した場合、fmtはユニオン内のバリアントを印刷するため、切り詰められたファイルはベアな「うまくいかなかった」ではなくOffset_Goes_Past_Dataを報告します。異なる反応が必要な呼び出し元は、代わりにerrでswitchできます。小さなテストファイルhttps://tylerelton.com/test.xpに対して実行すると、各文字がそのコピーから描画されています。

 H   H EEEEE L     L      OOO         W   W  OOO  RRRR  L     DDDD  !
 H   H E     L     L     O   O        W   W O   O R   R L     D   D !
 HHHHH EEEE  L     L     O   O        W W W O   O RRRR  L     D   D !
 H   H E     L     L     O   O  ,     WW WW O   O R  R  L     D   D
 H   H EEEEE LLLLL LLLLL  OOO  ,      W   W  OOO  R   R LLLLL DDDD  !

ターミナルは行ごとに印刷するため、外側にy、内側にxをループします。cell_atは、下にある列優先順序のストレージを処理します。印刷可能なASCII範囲外のグリフは、正しく表示するためにCP437からUnicodeへのルックアップテーブルが必要ですが、これは画面が表示されるのを見るのに十分です。

まとめ

約150行のOdinで、バイナリファイルを取得し、解凍し、プログラムがどこでも使用できる構造体にマッピングしました。逆方向で、File構造体から.xpファイルを書き込むことは、主に逆のコードと同じですが、圧縮を処理するためにOdinの標準ライブラリ以外のものが必要になります。すべてを1か所で見たい場合は、完全なソースがCodebergにあります:decode.odinとxp.odin。

将来の記事では、Fimbulでタイトル、勝利、死亡画面、および敵やアイテムをスポーンするプレハブに.xpファイルをどのように使用しているかについて説明したいと思います。それまでの間、.xpファイルをzcatとxxdで実行してみて、今どれだけ手で読めるか見てみてください!

次回まで🤙


  1. REXPaint v1.70 manual (plaintext), Grid Sage Games ↩︎
  2. REXPaint manual (HTML), hosted by Steve Landey ↩︎
  3. RFC 1952: GZIP file format specification, section 2.3.1 ↩︎
  4. “Appendix B: .xp Format Specification” in the HTML manual, also available in the official plaintext manual ↩︎
  5. REXPaint manual: Fonts ↩︎
  6. REXPaint manual: Transparency and Appendix B ↩︎
  7. Odin core:compress/gzip package ↩︎
  8. Odin bytes.Buffer struct ↩︎
  9. Odin core:encoding/endian package ↩︎