xp3 アーカイブツール¶

xp3 アーカイブツールについて¶

xp3 アーカイブツール ( krkrxp3 ) は、フォルダの中身を xp3 アーカイブ (吉里吉里標準のアーカイブ形式) にまとめるためのツールです。作成したアーカイブの中身の一覧・展開・検証もできます。

吉里吉里2 の Releaser ( krkrrel.exe ) のうち、アーカイブを作る部分の後継です。同じ書式で、拡張子ごとの既定の扱いも同じです。Releaser のプロファイル (.rpf) もそのまま読めます。

ほかの標準ツールと同じく、起動するとブラウザのウィンドウが画面になります。画面を開かずにコマンドラインで使うこともできます (後述の「コマンドラインでの使い方」参照)。

Note: 実行可能ファイル (exe) へのアーカイブの結合や、exe のオプション・アイコンの設定は、このツールでは行いません (Releaser を参照)。

アーカイブに入るファイル¶

指定したフォルダの中にあるファイル (階層下のフォルダも含む) を対象にします。アーカイブ内のファイル名は、そのフォルダからの相対パス ( / 区切り) になります。

Note: 名前の先頭が . (ドット)で始まるファイルやフォルダ (UNIX 風の隠しファイルや、Subversion / Git のメタ情報フォルダなど) は無視します。また、"CVS" という名前のフォルダ (CVS のメタ情報フォルダ) も無視します。

Note: 内容が全く同一のファイルを見つけると、たとえファイル名が異なっていても一つにまとめて、一つ分のファイルの容量しか使用しません。

拡張子ごとの扱い¶

拡張子ごとに、「圧縮するもの」「アーカイブには含めるが圧縮しないもの (格納のみ)」「アーカイブには含めないもの」を選ぶ事ができます。通常、既定の分類のままでかまいません。既定の分類は吉里吉里2 の Releaser と同じです。

扱い	既定で該当する拡張子
圧縮する	.wav .dll .tpi .spi .txt .mid .smf .swf .ks .tjs .ma .asq .asd .ttf .ttc .bmp .tft .cks
入れない	.xpk .xp3 .exe .bat .tmp .db .sue .vix .ico .aul .aue .rpf .bak .log .kep .cf .cfu、拡張子の無いファイル、.~ で始まる拡張子 (エディタのバックアップなど)
格納のみ	上記以外のすべて (.png .jpg .tlg .ogg .opus など)

拡張子の大文字・小文字は区別しません。また、作成するアーカイブのファイル自身がフォルダの中にあっても、それはアーカイブに入れません。

「圧縮するもの」にファイルを分類すると圧縮 (zlib) が行われるため、ファイルサイズが小さくなります。また、テキストエディタやバイナリエディタで中を覗いても簡単には解読できない状態になります。しかし、圧縮を行うと展開時に時間がかかるというデメリットもあります。PNG や JPEG や TLG、Ogg Vorbis などは既に圧縮されていて、「圧縮する」に分類しても効果が薄い上に、展開に余計に時間がかかるようになるので、圧縮することはお勧めできません。

なお、「圧縮するもの」に分類されていても、圧縮しても小さくならないファイルは圧縮せずに格納します。

オプション¶

大きなファイルを圧縮しない
もし該当するファイルが「圧縮するもの」に分類されていても、指定されたサイズ (既定 1024 KB) 以上であれば圧縮を行わない、という設定です (既定で有効)。吉里吉里の構造上、圧縮されたファイルはメモリ上に展開しなければならないため、大きなファイルを圧縮するのは実行時のコストが高くなります。
インデックスを圧縮する
アーカイブ内部のインデックス ( 格納されているファイルのリスト ) を圧縮し、サイズの節約をすることができます (既定で有効)。
展開プロテクト
アーカイブ内部のインデックスの各ファイルに「展開プロテクト」の属性を付加します。これによりアーカイブ展開ツールに対し「著作者はファイルが展開されることを望んでいない」という意思表示をすることができます (既定では無効)。

展開プロテクトを指定すると、吉里吉里2 の Releaser と同じく、アーカイブの先頭に警告文のエントリ (名前が「$$$ This is a protected archive. $$$ …」で始まり、展開しないよう求める文言が並んだもの) を入れます。

このツールは、展開プロテクトの付いたファイルと警告文のエントリを展開しません (一覧の表示と検証はできます)。

Note: 「展開プロテクト」を指定しても実際に展開ができないように暗号化をしたりする訳ではありません。意思表示を行うことができるだけです。吉里吉里本体は、展開プロテクトの付いたアーカイブも普通に読み込めます。また、アーカイブ展開ツールを作成される方は ( もしいるとして ) この展開プロテクトフラグの存在を考慮してください ( このフラグがたっていれば展開を拒否したり、展開する前に警告をするなど )。

プロファイル (.rpf)¶

アーカイブを作る設定 (拡張子ごとの扱い、上記のオプション、出力ファイル名) は、プロファイル (.rpf) に保存しておくことができます。プロファイルは吉里吉里2 の Releaser と同じ書式で、Releaser で作ったプロファイルをそのまま読むことができます。

対象のフォルダに default.rpf があれば、アーカイブを作るときにその設定を読みます (コマンドラインでは --rpf で別のプロファイルを指定できます)。
プロファイルに書かれていない拡張子は、既定の分類で扱います。
プロファイルに出力ファイル名 (拡張子 .xp3 のもの) が記録されていれば、それを出力ファイル名の既定値にします。
画面では「設定を default.rpf に保存」をチェックすると、作成時に対象フォルダの default.rpf へ設定を保存します。コマンドラインでは --save-rpf で保存先を指定します。
.rpf は既定で「入れない」に分類されているので、default.rpf がアーカイブに入ることはありません。

プロファイルは以下のような INI 形式のファイルです。

[Output]
Executable=0
OutputFileName=data.xp3
[Extensions]
Compress=.asd,.asq,.bmp,.cks,.dll,.ks,.ma,.mid,.smf,.spi,.swf,.tft,.tjs,.tpi,.ttc,.ttf,.txt,.wav
Store=
Discard="",.aue,.aul,.bak,.bat,.cf,.cfu,.db,.exe,.ico,.kep,.log,.rpf,.sue,.tmp,.vix,.xp3,.xpk
[Options]
DoCompressSizeLimit=1
CompressSizeLimit=1024
Protect=0
OVBookShare=0
CompressIndex=1

"" は拡張子の無いファイルを表します。OVBookShare (Ogg Vorbis のコードブック共有) はこのツールでは使いません (保存時は常に 0 を書きます)。

互換性¶

作成したアーカイブは、吉里吉里Z 本体で読み込めます。書式は吉里吉里2 の Releaser が作るものと同じです。
吉里吉里2 の Releaser で作ったアーカイブや、吉里吉里2 の実行可能ファイルに結合されたアーカイブ (exe) も、一覧・展開・検証できます。

Note: 以下は現在対応していません。

暗号化 (吉里吉里2 の Releaser の暗号化プラグイン xp3enc.dll による暗号化アーカイブの作成・読み込み)

Ogg Vorbis ファイルのコードブック共有 (Releaser の「OggVorbisコードブック共有化」)

画面での使い方¶

krkrxp3 を起動するとブラウザのウィンドウに画面が表示されます。起動時にフォルダを引数に渡すと「作成」画面にそのフォルダを、xp3 ファイル (または .exe) を渡すと「中身を見る」画面にそのファイルを開きます。

「作成」タブ¶

「元のフォルダ」
アーカイブにまとめるフォルダを指定します。「参照…」でフォルダを選ぶこともできます。

フォルダを指定すると、フォルダの中にある拡張子ごとに、ファイルの数・合計サイズと扱い (圧縮 / 格納のみ / 入れない) が一覧で表示されます。扱いはここで拡張子ごとに変更できます。フォルダに default.rpf があれば、その設定を読んだことが表示されます。 - 「出力ファイル」
出力する xp3 ファイルを指定します。既定では、元のフォルダと同じ場所に「フォルダ名.xp3」で出力します (プロファイルに出力ファイル名があればそれを使います)。 - オプション
「○ KB 以上のファイルは圧縮しない」「インデックスを圧縮する」「展開プロテクト」「設定を default.rpf に保存」を指定します (上記「オプション」「プロファイル (.rpf)」参照)。 - 「作成する」
アーカイブを作成します。進行中は「中断」で中断できます。

終了すると、格納したファイルの数 (うち圧縮したもの、中身が同じで共有したもの、入れなかったもの) と、元の合計サイズ → アーカイブのサイズが表示されます。

「中身を見る」タブ¶

「xp3 ファイル」
中身を見るアーカイブを指定し、「開く」をクリックします (「参照…」で選んだ場合はすぐに開きます)。

格納されているファイルの名前、サイズ、格納サイズ、圧縮の有無、展開プロテクトの有無が一覧で表示されます。実行可能ファイルに結合されたアーカイブの場合は、その位置も表示されます。 - 「検証」
格納されているすべてのファイルを読み出し、データが壊れていないか (展開できるか、チェックサムが一致するか) を確かめます。 - 「展開」
「展開先」に指定したフォルダにファイルを展開します。展開先の既定値は、xp3 ファイルと同じ場所の、xp3 ファイルの名前 (拡張子を除く) のフォルダです。展開プロテクトの付いたファイルは展開しません。

コマンドラインでの使い方¶

--cli を付けると、画面を開かずにコマンドラインで処理して終了します。

krkrxp3 --cli pack    <フォルダ> [--out=FILE] [--rpf=FILE] [--protect]
                      [--no-compress-index] [--size-limit=KB | --no-size-limit] [--save-rpf=FILE]
krkrxp3 --cli list    <xp3> [--json]
krkrxp3 --cli extract <xp3> [--out=DIR]
krkrxp3 --cli verify  <xp3>

pack
フォルダの中身からアーカイブを作ります。フォルダに default.rpf があれば (--rpf を指定しない場合) その設定を読み、コマンドラインのオプションでそれを上書きします。

出力ファイルは --out で指定します。省略すると、プロファイルの出力ファイル名 (.xp3 のもの)、それも無ければフォルダと同じ場所の「フォルダ名.xp3」になります。 - list
格納されているファイルの一覧を表示します。各行は「元のサイズ」「格納サイズ」「フラグ」「名前」で、フラグの 1 文字目は圧縮されていれば Z、2 文字目は展開プロテクトが付いていれば P です。 - extract
ファイルを展開します。展開先は --out で指定します。省略すると、xp3 ファイルと同じ場所の、xp3 ファイルの名前 (拡張子を除く) のフォルダになります。展開プロテクトの付いたファイルは展開しません。 - verify
格納されているすべてのファイルを読み出して、壊れていないか確かめます。壊れていたファイルは「破損」として表示します。

オプション	内容
`--out=PATH`	出力先 (pack: xp3 ファイル / extract: フォルダ)
`--rpf=FILE`	読み込むプロファイル (既定: 対象フォルダの default.rpf)
`--save-rpf=FILE`	使った設定をプロファイルとして保存する
`--protect`	展開プロテクトを付ける
`--no-compress-index`	インデックスを圧縮しない
`--size-limit=KB`	このサイズ以上のファイルは圧縮しない (既定 1024)
`--no-size-limit`	サイズに関わらず、圧縮する拡張子のファイルは圧縮する
`--json`	結果を JSON で出力する
`--quiet`	進捗を表示しない

たとえば、以下のように指定します。

# project フォルダを ../release/data.xp3 にまとめる
krkrxp3 --cli pack project --out=../release/data.xp3

# 展開プロテクトを付けて作り、設定を default.rpf に保存する
krkrxp3 --cli pack project --protect --save-rpf=project/default.rpf

# 中身の一覧と検証
krkrxp3 --cli list data.xp3
krkrxp3 --cli verify data.xp3

終了コード¶

値	意味
0	成功
1	verify で壊れたファイルが見つかった
2	失敗 (アーカイブを開けない、プロファイルが無い、展開に失敗したファイルがある、中断したなど)