Ebitengine 2.10 リリースノート

このドキュメントはドラフトです。 v2.10.0 はまだリリースされていません。内容はリリースまでに変更される可能性があります。

v2.10.0

このリリースでは、デスクトップ環境での Pure Go 化、アプリケーションの仮想化 (VM)、シェーダーの事前コンパイルに対応しました。また、テキスト描画や IME 入力、ウィンドウ操作などを改善しました。

Ebitengine 2.10 から Go 1.25 以上が必要になりました。

デスクトップ環境での Pure Go 化

macOS と Linux / BSD 向けの実装から Cgo への依存を取り除きました。これにより、デスクトップ向けの Ebitengine アプリケーションを Go だけでビルドできるようになりました。 C コンパイラーや開発用ヘッダーファイルのインストールが不要になります。また、別の OS 向けのクロスコンパイルも容易になります。ちなみに、 Windows 向けの実装はすでに Cgo が不要でした。

OS の API や共有ライブラリの呼び出しには PureGo を使用しています。 Linux などでは、実行時のライブラリは引き続き必要です。これにはウィンドウシステムやグラフィックス、音声のライブラリが含まれます。また、モバイルや一部のゲーム機向けのビルドには引き続き Cgo が必要です。

アプリケーションの仮想化 (VM)

Issue: #3438

Ebitengine アプリケーションを別プロセスの「ゲスト」として実行できるようになりました。ゲストは「ホスト」から操作できます。ホストはゲストに入力を送ります。また、ゲームの更新や描画のタイミングを制御します。ゲストは描画命令をホストに送ります。実際の描画にはホスト側の描画バックエンドを使います。音声もプレイヤーごとのストリームとしてホストから取得できます。

主な用途は次の 2 つです。

別の Ebitengine ゲームの埋め込み。ホストアプリケーション内にゲストのゲーム画面を表示できます。ゲームエディターのプレビューなどに利用できます。
プログラムや AI による自動テスト。ゲストに入力を送り、決まった回数だけゲームを更新できます。描画結果や音声を取得して検証できます。

すべての Ebitengine アプリケーションを VM ゲストとして実行できるわけではありません。作者が ebitenginevmguest ビルドタグを指定するか、 ebiten.RunGameOptions.VMGuestEndpoint を設定する必要があります。これは意図的な設計です。 VM 機能を使うと、外部プログラムからアプリケーションを簡単に操作できます。そのような操作を望まない作者もいるため、明示的に有効化する方式にしています。

AI エージェント向けに、スキルファイル run-ebitengine-app-headless を用意しています。このスキルを読み込ませると、 AI エージェントがアプリケーションを自動でデバッグできます。このテストはヘッドレステストです。テスト中にウィンドウが表示されないため、ユーザーの作業を妨げません。エージェントはゲストの実際の描画結果を画像として取得し、確認できます。入力を送って不具合を再現したり、音声を確認したりすることもできます。コードの修正後には、同じ操作で修正結果を検証できます。

ホスト側は新しい実験的パッケージ exp/vmhost を使用します。ゲスト側は ebitenginevmguest ビルドタグを指定してビルドします。実行時には、環境変数 EBITENGINE_VM_ENDPOINT でホストの接続先を指定します。この方法ではソースコードの変更は不要ですが、ビルドし直す必要があります。ビルドタグを使わず、プログラムから ebiten.RunGameOptions.VMGuestEndpoint を指定することもできます。

ゲストとしての実行はデスクトップ環境に対応しています。ゲストは自分のウィンドウや GPU を使いません。描画するホストにはグラフィックス環境が必要です。今回の VM 機能には、 GPU のない CI 環境向けのソフトウェアレンダラーは含まれていません。ホストとゲストには同じバージョンの Ebitengine を使用してください。 exp/vmhost は実験的パッケージです。今後 API が変更される可能性があります。

シェーダーの事前コンパイル

Issues: #2861、 #3157、 #3035

新しい実験的パッケージ exp/shaderprecomp により、事前にコンパイルしたシェーダーを利用できるようになりました。実行時のシェーダーコンパイル処理を減らし、ロード時間を短縮できます。

shadercollector ツールは、指定されたパッケージから Kage のソースを収集します。依存パッケージも収集の対象です。収集するシェーダーは、専用のディレクティブやマニフェストで指定します。収集したソースから、各描画バックエンド向けのソースを出力します。

DirectX や Metal 向けには、利用者が出力されたソースを別途コンパイルする必要があります。各プラットフォームのコンパイラーでバイナリを生成してください。生成したバイナリはアプリケーションの初期化時に登録します。通常の ebiten.NewShader 呼び出しや描画処理はそのまま利用できます。具体的な手順は shaderprecomp のサンプルを参照してください。

事前コンパイルによって、実行時のコンパイルがすべて不要になるわけではありません。 Kage の中間表現への変換は引き続き行われます。 OpenGL 向けには GLSL への変換を事前に行えます。ただし、 GPU ドライバーによる GLSL のコンパイルとリンクは実行時に行われます。

shadercollector は、各シェーダーのソースを識別する ID (SourceID) も出力します。この ID は、元の Kage ソースと事前コンパイル済みのデータを対応付けるために使います。同じ Kage ソースでも、 Ebitengine のバージョンが変わると ID が変わる可能性があります。 Ebitengine の更新時には、ソースの収集と事前コンパイルをやり直してください。 exp/shaderprecomp は実験的パッケージです。今後 API が変更される可能性があります。

Kage の変更

新機能

整数や固定長配列に対する for range が使えるようになりました (#2905、 #1897)。
ビット演算子 &^ と単項 ^ に対応しました (#2753)。
imageSrc1AtFromSrc0Pos などの関数を追加しました。 0 番目の画像の座標を受け取ることを名前で明示しています。従来の imageSrc1At なども引き続き同じ動作をします (#2813)。
imageDstTextureSize と imageSrc0TextureSize から imageSrc3TextureSize を追加しました。画像が格納されているテクスチャのサイズを取得できます (#3476)。

非推奨になった関数

以下の関数は非推奨になります。従来の関数も引き続き同じ動作をします。

2.9 以前	2.10 以降	Issue
`imageSrc1At()` から `imageSrc3At()`	`imageSrc1AtFromSrc0Pos()` から `imageSrc3AtFromSrc0Pos()`	#2813
`imageSrc1UnsafeAt()` から `imageSrc3UnsafeAt()`	`imageSrc1UnsafeAtFromSrc0Pos()` から `imageSrc3UnsafeAtFromSrc0Pos()`	#2813

バグ修正

定数式のゼロ除算でコンパイラーがパニックする問題を修正しました。コンパイルエラーを返すようになりました (#3533)。
配列同士の == と != による比較をコンパイルエラーにしました。従来は受け付けていましたが、描画バックエンドによってシェーダーのコンパイルに失敗していました (#3535)。

カラー絵文字とテキスト描画の改善

Issues: #2649、 #2956、 #3456、 #3457

text/v2 パッケージでカラー絵文字を描画できるようになりました。フォントに含まれるビットマップやカラーグリフを利用します。カラーグリフを持つフォントをアプリケーションで用意する必要があります。

双方向テキストは従来から対応しています。今回は、左から右と右から左の文字が混在する場合の表示順序を修正しました。新しい text.AdvanceAt 関数では、文字列中の指定位置に対応するキャレットの位置を取得できます。双方向テキストも考慮されます。

IME 入力の対応環境拡大

Issues: #2736、 #2831、 #3446

exp/textinput パッケージが Linux / UNIX と Android / iOS に対応しました。また、新しい textinput.Composer により、変換中の文字列や確定された文字列をコールバックで受け取れるようになりました。独自のテキストエディターや入力欄に IME を組み込む際に利用できます。

既存の textinput.Field は非推奨になります。新しく入力欄を実装する場合は textinput.Composer を使用してください。 exp/textinput は引き続き実験的パッケージです。

ウィンドウとデスクトップ操作の改善

ウィンドウのリサイズ中の描画を改善しました。画面の歪みや、一時的に黒い領域が表示される問題を修正しました (#2615、 #3477、 #3478)。
システムのライトモード・ダークモードを取得できるようになりました。また、アプリケーションが希望するカラーモードを指定できます。デスクトップではウィンドウのタイトルバーの外観に反映されます (#3386、 #3387、 #3480)。
ウィンドウを表示せずにアプリケーションを実行できるようになりました。実行中に表示・非表示を切り替えることもできます (#3470)。
Windows で、実行ファイルに埋め込まれたアイコンをウィンドウのアイコンとして自動的に利用するようになりました (#3459)。
デスクトップでドロップされたファイルやディレクトリの絶対パスを ebiten.AbsPather インターフェイスで取得できるようになりました (#3252)。

その他の新機能

Linux で、 X11 や Wayland を使用せず、フレームバッファーデバイス (fbdev) と EGL を使用して描画できるようになりました。対応するデバイスと EGL ドライバーが必要です。ウィンドウシステムのない携帯ゲーム機などで利用できます (#3491)。
Windows、 macOS、 Linux でゲームパッドの振動に対応しました。 Windows では XInput 対応のゲームパッドが対象です。 macOS では GameController フレームワークに対応したものが対象です。 Linux では振動機能に対応したものが対象です (#2014)。
(*audio.Player).SetVolume に 1 を超える値を指定できるようになりました (#3359)。
AI エージェント向けのスキルファイルを追加しました。ヘッドレス実行によるアプリケーションの自動デバッグと、 Kage シェーダーの作成を支援します。利用する際は、目的に合う SKILL.md をエージェントに読み込ませてください。

新しい API

新しい実験的パッケージ exp/vmhost と exp/shaderprecomp に加えて、主に以下の API を追加しました。

API	説明	Issue
`ebiten.AbsPather`	ドロップされたファイルやディレクトリの絶対パスを取得するインターフェイス。	#3252
`ebiten.ColorMode` と `ColorModeUnknown` `ColorModeLight` `ColorModeDark`	ライトモード・ダークモードなどのカラーモードを表す型と定数。	#3386
`ebiten.SystemColorMode()` `ebiten.PreferredColorMode()` `ebiten.SetPreferredColorMode()`	システムのカラーモードの取得と、アプリケーションが希望するカラーモードの取得・設定。	#3386、 #3387、 #3480
`(ebiten.ColorScale).Set()` `(ebiten.ColorScale).SetWithColor()`	RGBA 値、または `color.Color` から色の倍率を設定。	#3370
`ebiten.CursorPositionF()`	マウスカーソルの座標を浮動小数点数で取得。	#3394
`ebiten.TouchPositionF()` `inpututil.TouchPositionFInPreviousTick()`	現在、または直前のティックのタッチ座標を浮動小数点数で取得。	#3504
`ebiten.IsCapsLockOn()` `ebiten.IsNumLockOn()`	Caps Lock と Num Lock のオン・オフ状態を取得。	#3506
`ebiten.MaxImageSize()`	実行環境で利用できる画像の最大の幅・高さをピクセル単位で取得。	#1734
`ebiten.ScreenSize()`	`Game.Draw` に渡される画面画像のサイズをピクセル単位で取得。	#2986
`ebiten.RunOnMainThread()`	指定した関数をメインスレッドで同期的に実行。	#3385
`ebiten.IsWindowVisible()` `ebiten.SetWindowVisible()`	ウィンドウの表示状態の取得と、表示・非表示の切り替え。	#3470
`(ebiten.Image).RecyclableSubImage()` `(ebiten.Image).Recycle()`	再利用可能なサブ画像を作成し、使用後に返却してメモリ確保を削減。	#3418、 #3423
`ebiten.RunGameOptions.VMGuestEndpoint`	VM ゲストとして実行する際のホストの接続先を指定。	#3438
`(*audio.Player).PauseAndStopReading()`	音声を一時停止し、再生元からの読み込みも停止。進行中の読み込みがあれば完了を待つ。	#3510
`text.AdvanceAt()`	文字列中のバイト位置に対応する、行の原点からキャレットまでの距離を取得。	#3456
`text.Glyph.AdvanceX` `text.Glyph.AdvanceY` `text.Glyph.Colored`	グリフの横・縦方向の送り量と、カラーグリフかどうかを取得。	#3449、 #3496
`text.LazyGlyph` `text.AppendLazyGlyphs()`	画像の生成を必要になるまで遅延させて、グリフの配置情報を取得。	#3450
`text.VariationAxis` `(*text.GoTextFaceSource).AppendVariationAxes()`	可変フォントの軸と、各軸の最小値・既定値・最大値を取得。	#3486
`textinput.Composer` `textinput.SessionOptions` `textinput.Composition` `textinput.Commit`	IME セッションを管理し、変換中の文字列や確定された文字列をコールバックで取得。	#3446

非推奨になった API

2.9 以前	2.10 以降	Issue
`(*audio.Player).Close()`	`(*audio.Player).PauseAndStopReading()`	#3509、 #3510
`text.Advance()`	`text.AdvanceAt()`	#3456
`textinput.Field`	`textinput.Composer`	#3446

バグ修正

このリリースは、以下の修正に加えて、バージョン 2.9 にあった全てのバグ修正を含みます。

小数のディスプレイスケールでウィンドウサイズやフルスクリーンの解像度が正しくならなかった問題の修正。また、ブラウザーで描画がぼやけていた問題の修正 (#2978、 #2225、 #2958)。
macOS で起動前にフルスクリーンを指定すると画面が黒いままになっていた問題の修正。また、 Vsync の無効化が動作しなかった問題の修正 (#3508、 #3392)。
macOS の一部のゲームパッドでボタン入力が認識されなかった問題の修正 (#3471)。
修飾キーの入力状態が正しく更新されない問題の修正。また、ブラウザーでホイール入力が滑らかに取得できなかった問題の修正 (#3422、 #3453、 #3460、 #3467、 #3390)。
IME 入力が欠落する問題や、変換中にフォーカスを切り替えた場合の不具合の修正 (#3382、 #3463、 #3623)。
Android での OpenGL コンテキスト喪失時の描画復元と、一時停止時に応答しなくなる問題の修正 (#3215、 #3327、 #3334)。
Proton / DXVK 環境で DirectX の初期化時にクラッシュしていた問題の修正 (#3489)。
拡大縮小して描画したテキストが描画先の端で欠ける問題の修正。また、同じフォントソースを並行して使用した場合の競合状態の修正 (#3529、 #3605)。
音声のリサンプリングやシークで、長さや再生位置が正しくなくなる問題の修正。また、ストリームが壊れる問題の修正 (#3352、 #3545、 #3583、 #3584、 #3587、 #3589、 #3643)。
その他マイナーな問題の修正

パフォーマンス改善

GPU リソースの復元方式を見直し、描画履歴を保持するための処理を削減 (#3090、 #3215)。
ベクターグラフィックスの描画でテクスチャアトラスの使用量を削減 (#3358)。
text/v2 のグリフ画像の生成を遅延させ、不要な画像生成や描画呼び出しを削減 (#3450、 #3455)。
(*ebiten.Image).RecyclableSubImage と Recycle により、サブ画像のオブジェクトを再利用できるように変更。メモリ確保を削減できます。 Recycle は RecyclableSubImage で作成した画像にのみ使用できます (#3418、 #3423)。
ウィンドウ関連の処理でロックの使用を削減 (#3403)。
その他マイナーなパフォーマンス改善