Xprite のしくみ

Xprite のしくみ

Xprite は Aseprite のエディターをブラウザに持ち込みました。インストールもアカウント作成も不要で、作品を保存するサーバーもありません。この記事では、ブラウザで .aseprite を読み書きする方法、Canvas でくっきりしたピクセルを描く方法、作品の保存場所、オフラインでエディターを開くしくみ、そしてマウス向けに作られたデスクトップの画面を指やペン、スマホの画面にどう合わせているかを、技術的な側面から説明します。

全体像

エディターの処理はすべてブラウザ内で行われます。重い処理は Web Worker で動き、保存にはブラウザ標準の IndexedDB と OPFS を使います。ネットワークを使うのは、ページの読み込み、匿名のアクセス解析の送信、フィードバックの送信だけです。

ブラウザ内の Xprite の構成
ブラウザ内の Xprite
  • ファイルの読み書き
    • .aseprite の解析Worker でデコードし、メインスレッドをフォールバックに使う
    • 画像のエクスポートOffscreenCanvas または canvas でエンコード
  • キャンバスの表示
    • レイヤーの合成Canvas 2D のみで、WebGL は使わない
    • ピクセルの拡大整数倍はそのまま描画し、小数倍はルックアップテーブルからサンプリング
  • 作品の保存
    • 端末のファイルに書き込むFile System Access API、使えない場合はダウンロード
    • ブラウザに保存IndexedDB のカタログ + OPFS のデータ
  • 入力の処理
    • ペンと指を区別ペンが優先され、指はスクロールに切り替わる
    • ジェスチャーの認識ピンチでズーム、2 本指・3 本指タップで元に戻す・やり直し

ブラウザで .aseprite を読み書きする

ファイル形式

.aseprite はリトルエンディアンのバイナリ形式で、128 バイトのヘッダーの後に、複数のチャンクからなるフレームが続きます。ヘッダーのマジックナンバーは 0xA5E0、各フレームのものは 0xF1FA です。デコーダーは次のチャンクを扱います。

チャンクの種類 内容
0x2004 レイヤー:通常レイヤー、グループ、タイルマップレイヤー
0x2005 セル:生のピクセル、リンクセル、zlib 圧縮ピクセル、圧縮タイルマップ
0x2006 セルの追加データ(正確な位置とサイズ)
0x2007 カラープロファイル
0x2008 外部ファイルの参照
0x2018 タグ(アニメーションの範囲)
0x2019 パレット
0x2020 ユーザーデータ(テキスト、色、プロパティ)
0x2022 スライス
0x2023 タイルセット

古い 0x0004 と 0x000B のパレットチャンクも読み込み、非推奨のマスク(0x2016)とパス(0x2017)のチャンクも認識します。

先に検査し、それからデコード

ブラウザで開くファイルはどこから来たものかわからないので、デコードは 2 段階で行います。1 回目はファイル全体を走査し、すべてのチャンクの長さ、オフセット、個数がファイル内に収まっているかを確認します。実際のデコードはその後で始まります。壊れたファイルや上限を超えるファイルは、途中で失敗するのではなく走査の段階で見つかります。現在の上限は次のとおりです。

項目 上限
キャンバスの一辺 32,768 ピクセル
1 枚の画像 6,400 万ピクセル
フレーム 4,096
レイヤー 256

Worker でデコード

数十フレームを展開するには時間がかかり、メインスレッドで行うと画面が固まってしまいます。ファイルを開くと専用のデコード用 Worker に渡し、デコードしたピクセルバッファーは Transferable オブジェクトとしてコピーせずにメインスレッドへ戻します。ブラウザが Worker に対応していない場合や Worker が失敗した場合は、メインスレッドでのデコードにフォールバックします。

ピクセルデータは zlib で圧縮されています。ブラウザ標準の DecompressionStream("deflate") を優先し、展開爆弾を防ぐため出力をチャンクヘッダーで宣言されたサイズまでに制限します。対応していない場合は fflate を使います。もう一方の展開経路では、宣言されたサイズちょうどの出力バッファーを確保し、Adler-32 チェックサムを検証します。

必要なピクセルだけ展開する

ファイルを開いたとき、RGB のセルは検証されますが、すべてが展開されるわけではありません。元の圧縮バイトはメモリに残し、各フレームは必要になったときに展開します。大きなプロジェクトでも、一度にすべてをメモリに展開する必要はありません。

変更していない部分はそのまま書き戻す

.aseprite に保存するとき、エンコーダーは手を加えていない内容をそのまま残します。

  • 変更していないセルは、開いたときから保持している圧縮バイトから再圧縮せずに書き戻します。
  • 未知のチャンクはそのまま書き戻すので、新しいバージョンの Aseprite で作ったファイルを Xprite で保存してもデータは失われません。
  • 再圧縮したセルは、圧縮版が生データより小さい場合にだけ圧縮版を使います。
  • 圧縮にはブラウザ標準の CompressionStream を使います。対応していない場合は非圧縮で保存されます。サイズは大きくなりますが、Aseprite で開けます。

Canvas 2D だけでキャンバスを描画する

Xprite は WebGL を使いません。ドット絵のキャンバスはたいてい小さく、難しいのはすべてのピクセルをくっきり保つことです。どのズーム倍率でも、どの画面密度でも、ピクセルはブラウザがぼかしたものではなく、縁のはっきりした正方形として表示されなければなりません。

レイヤーから画面まで

画面更新 1 回の流れ
  1. レイヤーを合成現在のフレームをレイヤー順、不透明度、合成モードに従って重ねる
  2. 色を変換プロジェクトのカラープロファイルで変換し、結果をキャッシュ
  3. 変更範囲をアップロードこのストロークで変わった矩形だけを putImageData で画像キャンバスへ
  4. ビューを描画ズーム倍率でピクセルを並べ、市松模様、ピクセルグリッド、枠を追加
  5. 画面に表示整数倍はそのまま描画し、小数倍はルックアップテーブルからサンプリング

描画中、エディターは各ストロークで変わった矩形を記録し、描画処理では毎回画像全体を送り直すのではなく、その範囲だけを画像キャンバスに書き込みます。できあがったビュー(ピクセル、市松模様、グリッド)はベースキャンバスにキャッシュします。キャッシュキーにはピクセルのバージョン、ビューの位置、表示設定などが含まれます。カーソルを動かしてもキーは変わらないので、ベースキャンバスを再利用し、ブラシカーソルのプレビューだけを描き直します。

整数倍と小数倍

最後の段階でビューを画面に描画します。ビューが画面にちょうど整数倍で対応する場合は、画像のスムージングをオフにしてブラウザの drawImage に任せます。

if (Number.isInteger(scaleX) && Number.isInteger(scaleY) /* and no offset */) {
  presentation.imageSmoothingEnabled = false;
  presentation.drawImage(sourceCanvas, 0, 0, sourceWidth, sourceHeight,
                         0, 0, canvas.width, canvas.height);
  return;
}
presentation.putImageData(renderer.render(context.getImageData(...)), 0, 0);

画面密度 1.5 やブラウザのズーム 110% のような小数倍では、ブラウザごとに drawImage のサンプリングが異なります。ピクセルの列の幅が不揃いになったり、画像全体が半ピクセルずれたりします。その場合はニアレストネイバーのサンプリングを自前で行います。描画先のサイズに対して、各列・各行がどの元ピクセルに対応するかを事前に計算し、2 つの Int32Array ルックアップテーブルに保存します。サンプリングでは各ピクセルを 1 つの Uint32 としてコピーし、同じ行が続く部分は copyWithin でまとめてコピーします。

インターフェースも同じ考え方で、すべてのコントロールを論理ピクセルあたり 2 サンプルで描画します。ブラウザのウィンドウサイズを変えても変わるのはワークスペースの大きさだけで、ボタンやメニューの大きさは変わりません。

画像の読み込みとエクスポート

PNG、JPEG、WebP などの画像のエンコードとデコードはブラウザが行います。

  • デコードは createImageBitmap を優先し、<img> 要素をフォールバックに使います。
  • エンコードは OffscreenCanvas.convertToBlob を優先し、<canvas> の toBlob をフォールバックに使います。
  • ブラウザが形式に対応していないとき、toBlob はエラーを出さずに黙って PNG を返します。そのため、エンコード後に結果の実際の種類を確認し、エクスポートの前に 1×1 のテスト画像をエンコードして、ブラウザがどの形式をエクスポートできるかを調べます。

作品の保存場所

プロジェクトの保存先は 2 つあり、名前を付けて保存... の 保存先 で選びます。

名前を付けて保存ダイアログ:ファイル名、形式、保存先のブラウザとファイルマネージャーの選択肢

保存先 使うブラウザの機能 使えない場合
ファイルマネージャー File System Access API 代わりにファイルをダウンロード
ブラウザ IndexedDB + OPFS プロジェクトのデータを代わりに IndexedDB に保存

ブラウザ内のプロジェクトはこの端末のこのブラウザにだけ存在し、同期されません。サイトのデータを消去すると削除されます。ユーザーガイドをご覧ください。

ファイルマネージャー:元のファイルに直接書き戻す

File System Access API に対応したブラウザ(デスクトップ版の Chrome、Edge など)では、開く と 保存 でシステムのファイルダイアログが表示されます。得られるのはファイルのコピーではなく、ファイルハンドルです。

  • ファイルハンドルは IndexedDB に保存されるので、次の 保存 では保存先を尋ねずに同じファイルに書き戻します。
  • 書き込む前に読み書きの権限を求め、createWritable() で書き込みます。
  • ブラウザはファイルダイアログをユーザーのクリックから直接開くことを求めるので、クリック直後に他の非同期処理を挟まず showSaveFilePicker() を呼び出します。
  • ページが他のサイトの iframe(ゲームポータルなど)に埋め込まれている場合、ブラウザはファイルダイアログを許可しません。その場合 Xprite は、非対応のブラウザと同じようにファイルをダウンロードします。

ブラウザ:IndexedDB のカタログと OPFS のデータ

ブラウザに保存したプロジェクトのカタログ(名前、サイズ、更新日時、現在のバージョン)は常に IndexedDB にあります。プロジェクトのデータは、できる限り OPFS(オリジンプライベートファイルシステム。ブラウザが各サイトに与える非公開のディスク領域)に保存します。OPFS を使うのは、ブラウザが Worker、navigator.storage.getDirectory()、Web Locks、書き込み可能なファイルハンドルに対応している場合だけです。保存方式はプロジェクトの作成時に決まり、その後は変わらないので、ブラウザの対応状況が変わっても古いプロジェクトが消えることはありません。

OPFS の読み書きは専用の Worker で行い、同期アクセスハンドル(createSyncAccessHandle)で書き込み、切り詰め、フラッシュを行います。保存のたびに次の手順をたどります。

ブラウザへのプロジェクトの保存
  1. プロジェクトをエンコードWorker で、現在のフレームやレイヤーなどのメタデータとともに .aseprite としてエンコード
  2. データを分割256 KiB を超える場合、.aseprite のチャンク境界に沿って最大 1 MiB のセグメントに分割
  3. 新しいセグメントを書き込むサイズと SHA-256 で重複を除き、内容が同じセグメントは再利用
  4. 読み戻して検証すべて読み戻してチェックサムを比較し、切り詰めがあればすぐに中止
  5. バージョンを公開IndexedDB のトランザクションでカタログを新しいバージョンに向け、前のバージョンも残す

データの破損を防ぐためのルールがいくつかあります。

  • 書き込んだデータは追記のみです。各キーは一度しか書き込めず、途中で失敗したファイルは削除されます。
  • 現在のバージョンを切り替えるのは最後のカタログのトランザクションだけで、それも他のタブが先に現在のバージョンを変えていない場合に限ります(コンペア・アンド・スワップ)。
  • Xprite が複数のタブで開かれているときは、Web Locks で書き込みを排他制御します。
  • .aseprite のチャンク境界で分割するので、変更していないフレームやレイヤーは同じセグメントに残ります。1 フレームを編集しても、変わったセグメントだけが書き込まれます。

自動復元

自動復元はブラウザへの保存と同じ保存経路を使います。編集中、Xprite は初期設定で 2 分ごとに復元データを保存し、7 日間保持します。間隔と日数は 編集 → 環境設定 → ファイル で変更できます。ブラウザが突然閉じた場合は、ホームで ファイルを復元... を選ぶと作業を取り戻せます。

共有リンク:スプライトは # の後ろにある

ファイル → 共有... は何もアップロードしません。スプライトは圧縮されて、リンクの #share= 以降の部分(URL フラグメント)に書き込まれます。ブラウザは # 以降をサーバーに送らないので、共有でサーバーに触れることはありません。

共有ダイアログ:現在のフレームや表示中のレイヤーだけを共有するオプションと、https://xprite.cc/editor#share= で始まる共有リンクとその文字数

共有リンクの作成
  1. 候補を作るチャンネルごとのプレーン、フレーム差分、インデックスカラー、タイルなど、複数の方法でピクセルをまとめる
  2. 最小のものを残す各候補を非圧縮、DEFLATE、Zstd で試し、最も小さいものを残す
  3. テキストにエンコードリンクは Base64url、QR コードは Base32 と Base43 を試して最短のものを使う
  4. リンクを組み立てるエディターのアドレス + #share= + エンコードの識別子 + データ
  • まとめる処理、圧縮、デコードはすべて Worker で行います。Zstd は WebAssembly として動き、まずレベル 19 で圧縮し、1 MiB 未満の結果はさらに高いレベルで圧縮し直します。WebAssembly の読み込みに失敗した場合は DEFLATE だけを使い、リンクは問題なく開けます。
  • QR コードの英数字モードは 1 文字あたり 5.5 ビットしか使わず、バイトモードよりコンパクトなので、QR コードにはこのモードの文字だけでできた Base43 エンコードを使います。
  • リンクを開くと、エディターは #share= 以降のデータを読み取り、すぐに history.replaceState でアドレスバーから取り除いてから、Worker に渡してデコードします。
  • 1,800 文字を超えるリンクには、チャットアプリによっては途中で切れることがあるという警告が表示されます。8,192 文字を超えるリンクは作成されません。

リンクには編集可能なプロジェクトがまるごと含まれます。リンク全体を持つ人は誰でも開けて、有効期限はなく、取り消すこともできません。リンクや QR コードをチャットアプリで送ると、そのアプリにも作品のデータが渡ります。

オフライン利用:一度に 1 つの完全なバージョン

Xprite をデスクトップやホーム画面に追加すると、Service Worker がエディターをキャッシュし、ネットワークがなくても開けるようになります(キャッシュには、先に一度オンラインでエディターを開く必要があります。手順はユーザーガイドをご覧ください)。キャッシュの方針は、バージョンの一貫性を保つことを軸にしています。

  • ビルドごとに、そのバージョンのリソースマニフェストを生成し、すべてのファイルに SRI ハッシュを付けます。インストール時に cache.addAll でマニフェスト全体を一度にキャッシュします。1 つでもダウンロードに失敗したりハッシュが一致しなかったりすると、そのバージョンは有効にならないので、新旧のファイルが混ざることはありません。
  • すべてキャッシュし終えると「準備完了」のマーカーを書き込み、オフライン起動ではこのマーカーがあるバージョンだけを使います。
  • 新しいバージョンはインストールされるとすぐに切り替わりますが、すでに開いているページは古いコードで動き続けます。ハッシュ付きのファイル名を持つ古いアセットは残しておくので、それらのページも読み込めます。
  • キャッシュするのはビルド成果物だけです。アクセス解析、フィードバックの送信先、サイトのページはキャッシュを通りません。
  • 古いバージョンのキャッシュは、すべてのエディターウィンドウが閉じた後でだけ削除します。

対応しているブラウザでは永続ストレージ(navigator.storage.persist())も要求し、容量が足りなくなったときにブラウザが作品を消去する可能性を下げています。

タッチスクリーンとペン

マウスのポインターは 1 つですが、タッチスクリーンにはペンと複数の指が同時に触れることがあります。入力レイヤーは次のルールで処理します。

状況 動作
ペンと指が同時に触れた ペンが優先され、指の操作を中断する
ペンを検出した後 手のひらの誤タッチを防ぐため、初期設定では 1 本指でキャンバスをスクロール
2 本目の指が触れた 現在のストロークを取り消し、2 本指のジェスチャーを開始
2 本指でピンチ キャンバスをズーム
2 本指・3 本指でタップ 元に戻す・やり直し
指が触れた後 まずタップかドラッグかを判定してから編集を始める

ドラッグのしきい値もポインターの種類で変わります。指は 8 CSS ピクセルを超えて動かないとドラッグとみなされませんが、マウスやペンは 1 ピクセルで十分です。

より細かいストローク

ブラウザは処理を減らすため、1 フレーム内の複数の pointermove イベントを 1 つにまとめます。ペンで描くときは、getCoalescedEvents() からまとめられたサンプルをすべて取り出し、それぞれの筆圧の値も使います。ブラウザは予測サンプルも提供しますが、Xprite は使いません。予測した点は実際のストロークと一致しないことがあり、操作履歴に入ってはならないからです。

/** Real samples only: predicted input must never reach document history. */
const coalesced = event.getCoalescedEvents?.() ?? [];
const actual = coalesced.filter(
  (point) => point.pointerId === event.pointerId && point.pointerType === "pen",
);

iPad の Apple Pencil

iPad の Safari では、Apple Pencil で触れると初期設定でテキスト選択やスクリブルなどのシステムの動作が起きます。React のタッチリスナーはパッシブで既定の動作を止められないため、キャンバスとドラッグ可能なコントロールに非パッシブのネイティブ touchstart リスナーを直接登録し、touchType が stylus のときだけ preventDefault() を呼び出します。テキスト欄などの編集可能な領域には影響しないので、そこではスクリブルで書き込めます。

レイアウト:デスクトップのウィンドウから縦向きのスマホまで

Xprite のインターフェースは Aseprite 1.3 を再現しています。ダイアログのサイズやコントロールの位置は Aseprite 1.3.18 を計測したもので、テストで一致を保っています。テーマの画像は Aseprite のドット絵スタイルに倣い、中国語・日本語・韓国語のインターフェースには Fusion Pixel フォントを使っています。

ワイドな画面では、上にメニューバー、左にパレット、右にツール、下にタイムラインという、おなじみのデスクトップレイアウトになります。

ワイドレイアウト:上にメニューバー、左にパレットとカラーピッカー、右にツール、下にタイムライン

このレイアウトは縦向きのスマホには収まりません。ワークスペースのレイアウト が 自動(初期設定)のときは、使える領域に合わせてレイアウトを選びます。ワイドレイアウト か コンパクトレイアウト に固定することもできます。ユーザーガイドをご覧ください。ルールは次のとおりです。

基準 条件 結果
使える領域の縦横比 1.2 以上 ワイドレイアウト:パネルを周囲に配置
使える領域の縦横比 1.2 未満 コンパクトレイアウト:ツールを上に一列に並べ、パレットとタイムラインはキャンバスの下のタブに
使える領域の幅 768 CSS ピクセル未満 インターフェースをコンパクトな密度に切り替え
タッチポイントまたはポインターの精度 タッチポイントがある、または (pointer: coarse) タッチ操作モード

コンパクトレイアウトでは、メニューバーは左上の ☰ ボタンにまとめられ、インターフェースはノッチや角丸などのセーフエリアを避けて配置されます。

縦向きのスマホでのコンパクトレイアウト:上にタブとツールの列、中央にキャンバス、下にパレットとタイムラインのタブ

レイアウトと操作モードは別々に決まります。横向きの iPad はワイドレイアウトとタッチ操作を同時に使います。デスクトップのブラウザのウィンドウを狭めるとコンパクトレイアウトに切り替わりますが、マウス操作のままです。

Xprite が送信するデータ

編集、保存、共有ではネットワークを使いません。送信されるデータは 2 種類だけです。

データ 送信されるとき 含まれるもの 含まれないもの
利用状況の解析 公式のウェブ版を使ったとき ページの訪問、機能の利用、エラーの種類、ブラウザの機能、おおよその位置 作品のピクセル、ドキュメント名、ローカルのファイルパス
フィードバック 不具合・ご要望 を送信したとき フィードバックの種類、メッセージ、任意のメールアドレス、現在の訪問の詳細 —

利用状況の解析は PostHog Cloud(米国)に送られます。

  • 訪問者 ID はブラウザの localStorage に保存されます。
  • 元の IP アドレスは、おおよその位置を付けた後に破棄されます。
  • クリックの自動取得はオフです。一部のセッションはセッションリプレイとして録画されますが、テキスト入力はマスクされ、作品などのキャンバスの内容は含まれず、ページのアドレスはパスのみになります。
  • ブラウザでトラッキング拒否(Do Not Track)をオンにして Xprite を開き直すと、それ以降は利用データが送信されません。

詳しくはプライバシーについてをご覧ください。

オープンソース

ここで説明したすべてのソースコードは GitHub で公開しています。エディターのコードは GPL-2.0-only ライセンスです。