棋譜フォーマット

局面、指し手列、対局メタデータは別の情報であり、用途に応じて異なる形式で扱う。

SFEN

SFEN は単一局面をテキストで表す。

盤面は段ごとに駒と空きマスを記し、続けて手番、持ち駒、手数を置く。

Position の SFEN 変換はデバッグ、USI、テストフィクスチャ、ユーザー入力に適する。

SFEN は局面履歴を保持しないため、千日手など履歴依存の判定を復元する形式ではない。

PackedSfen と HuffmanCodedPos は 32 バイトの局面本体を扱う。

前者は PackedSfenSink を通じた復元と little-endian u32 語への変換を持つ。

後者はハフマン符号化された局面を扱う。

どちらも復元可能な局面データであって、SFEN の文字列を単にバイト列へ切り詰めたものではない。

棋譜形式は初期局面に指し手列と結果などのメタデータを重ねる。

バイナリ学習レコードは固定長局面に加え、指し手、評価、方策、結果などを定義することがある。

そのレコードのフィールドとエンディアンは各フォーマットの仕様に従い、PackedSfen 単体のレイアウトから推測してはならない。

形式を選ぶときは、人間が編集するなら SFEN、固定サイズの局面ストレージなら対応する 32 バイト形式、棋譜全体なら棋譜用 API を選ぶ。

必要な情報	適する形式	理由
一局面を表示・手入力する。	SFEN。	可読性があり、USI とテストで扱いやすい。
一局面を固定間隔で格納する。	`PackedSfen` または `HuffmanCodedPos`。	32 バイトの境界を持つ。
指し手列と結果を保持する。	棋譜形式。	局面スナップショットだけでは履歴を表せない。
学習用の教師値を保持する。	レコード仕様に対応する学習形式。	局面以外のフィールドを別に定義できる。

変換は情報を増やさない。

たとえば SFEN から固定長局面へ変換しても、元のコメント、対局者、消費時間、指し手列は得られない。

固定長局面から SFEN へ戻すときも、呼び出し側が渡した ply の意味は元の棋譜の履歴とは別である。

日本語棋譜の KIF、KI2、CSA、JKF などは、局面以外に表記、コメント、時刻、変化手順を持ち得る。

ファイルを読むときは形式名だけで文字コードや変化手順の規則を推測せず、それぞれのパーサと仕様に従う。

同じ指し手表記でも、局面がなければ同名の駒を区別できないことがある。

そのため局面を必要とする変換は、初期局面と直前までの指し手列を一緒に扱う。

形式変換のテストは、変換後の文字列やバイト列だけでなく、復元した局面の盤面、手番、持ち駒を比較する。

棋譜形式ではさらに指し手列、終局理由、コメントなど、その形式が保持する情報を比較対象に加える。

変換できない情報は、既定値で埋めたことを隠さず、呼び出し側に明示する。