Ebitengine v2 移行ガイド

概要

Ebitengine v2 は v1 からのメジャーバージョンアップデートです。 API に関して破壊的変更を伴います。そのため v2 への移行はプログラムの修正が必要です。

このドキュメントでは、 v2 移行の際に実際にやらなければならないことを列挙します。

v2 には過激な変更を入れるのではなく、代わりにおとなしめの変更が入ります。

すでに廃止予定の機能を削除 (例: Run)
いくつかの関数から、戻り値のエラーを削除 (例: DrawImage)
整数型に代わる新しい型を追加 (例: GamepadIDs が []int の代わりに []GamepadID を返すようになる)

プラットフォーム

GopherJS は v2 からサポートされません。代わりに WebAssembly を使用してください。

やることリスト

インポートパスの更新

import 内の github.com/hajimehoshi/ebiten をすべて github.com/hajimehoshi/ebiten/v2 に更新します。 github.com/hajimehoshi/ebiten/text は github.com/hajimehoshi/ebiten/v2/text になります。

最後に go mod tidy コマンドを実行します。 go.mod に github.com/hajimehoshi/ebiten/v2 が含まれるようになり、 github.com/hajimehoshi/ebiten が消えるはずです。

Ebitengine v1 と v2 は 1 つのアプリケーションに混ぜて使用することが出来ません。 go mod tidy を実行したあとにも関わらず go.mod で両方記述されてしまっている場合は、依存関係を確認して v1 の依存を消してください。ただし複数のアプリケーションを 1 つのモジュールで意図的に管理するような場合は、その限りではありません。

API の更新

`github.com/hajimehoshi/ebiten`

DrawTriangleOptions の Address デフォルト値は v2 では AddressUnsafe になります。
インターフェイス Game の Draw 関数は v1 ではオプショナルでしたが、 v2 からは必須になります。
インターフェイス Game の Update 引数は v2 で削除されます。
IsRunnableOnUnfocused のデフォルト値は v2 では true になります。

次の型が導入されます。

GamepadID
TouchID

次の API のシグニチャが変更されます。

v1	v2
`func GamepadAxisNum(id int, axis int) int`	`func GamepadAxisNum(id GamepadID, axis int) int`
`func GamepadAxisNum(id int) int`	`func GamepadAxisNum(id GamepadID) int`
`func GamepadButtonNum(id int) int`	`func GamepadButtonNum(id GamepadID) int`
`func GamepadIDs() []int`	`func GamepadIDs() []GamepadID`
`func GamepadName(id int) string`	`func GamepadName(id GamepadID) string`
`func GamepadSDLID(id int) string`	`func GamepadSDLID(id GamepadID) string`
`func (*Image).Clear() error`	`func (*Image).Clear()`
`func (*Image).Dispose() error`	`func (*Image).Dispose()`
`func (Image).DrawImage(img Image, options *DrawImageOptions) error`	`func (Image).DrawImage(img Image, options *DrawImageOptions)`
`func (*Image).Fill(clr color.Color) error`	`func (*Image).Fill(clr color.Color)`
`func (*Image).ReplacePixels(pixels []byte) error`	`func (*Image).ReplacePixels(pixels []byte)`
`func IsGamepadButtonPressed(id int, button GamepadButton) bool`	`func IsGamepadButtonPressed(id GamepadID, button GamepadButton) bool`
`func NewImage(width, height int, filter Filter) (*Image, error)`	`func NewImage(width, height int) *Image`
`func NewImageFromImage(source image.Image, filter Filter) (*Image, error)`	`func NewImageFromImage(source image.Image) *Image`
`func TouchIDs() []int`	`func TouchIDs() []TouchID`
`func TouchPosition(id int) (int, int)`	`func TouchPosition(id TouchID) (int, int)`

次の API が削除されるか置き換えられます。

v1	v2
`const FilterDefault`	(置き換え先なし)
`const FPS`	(置き換え先なし)
`const MaxImageSize`	(置き換え先なし)
`DrawImageOptions` 構造体の `ImageParts`	`func (*Image).SubImage`
`DrawImageOptions` 構造体の `Parts`	`func (*Image).SubImage`
`DrawImageOptions` 構造体の `SourceRect`	`func (*Image).SubImage`
`interface Touch`	func TouchPosition
`func (*ColorM).Add`	(置き換え先なし)
`func (*GeoM).Add`	(置き換え先なし)
`func IsCursorVisible`	`func CursorMode`
`func IsDrawingSkipped`	`RunGame` 関数と `Game` インターフェイスの `Draw`
`func IsRunningInBackground`	`func IsRunnableOnUnfocused`
`func IsRunningSlowly`	`RunGame` 関数と `Game` インターフェイスの `Draw`
`func MonitorSize`	`func ScreenSizeInFullscreen`
`func Monochrome`	`(*ColorM).ChangeHSV` 関数 (引数は `0, 0, 1`)
`func RotateGeo`	`func (*GeoM).Rotate`
`func RotateHue`	`func (*ColorM).RotateHue`
`func Run`	`func RunGame`
`func ScaleColor`	`func (*ColorM).Scale`
`func ScaleGeo`	`func (*GeoM).Scale`
`func ScreenScale`	`func WindowSize`
`func SetCursorVisible`	`func SetCursorMode`
`func SetCursorVisibility`	`func SetCursorMode`
`func SetRunningInBackground`	`func SetRunnableOnUnfocused`
`func SetScreenScale`	`RunGame` 関数と `Game` インターフェイスの `Layout`
`func SetScreenSize`	`RunGame` 関数と `Game` インターフェイスの `Layout`
`func Touches`	`func TouchIDs`
`func TranslateColor`	`func (*ColorM).Translate`
`func TranslateGeo`	`func (*GeoM).Translate`

`github.com/hajimehoshi/ebiten/audio`

v2 では、 Player は io.Closer ではないソースを取ることができるようになり、 Player はもはや元のソースをクローズしません。

次の API のシグニチャが変更されます。

v1	v2
`func NewContext(sampleRate int) (*Context, error)`	`func NewContext(sampleRate int) *Context`
`func NewInfiniteLoop(src ReadSeekCloser, length int64) *InfiniteLoop`	`func NewInfiniteLoop(src io.ReadSeeker, length int64) *InfiniteLoop`
`func NewInfiniteLoopWithIntro(src ReadSeekCloser, introLength int64, loopLength int64) *InfiniteLoop`	`func NewInfiniteLoopWithIntro(src io.ReadSeeker, introLength int64, loopLength int64) *InfiniteLoop`
`func NewPlayer(context Context, src io.ReadCloser) (Player, error)`	`func NewPlayer(context Context, src io.Reader) (Player, error)`
`func NewPlayerFromBytes(context Context, src []byte) (Player, error)`	`func NewPlayerFromBytes(context Context, src []byte) Player`
`func (*Player).Pause() error`	`func (*Player).Pause()`
`func (*Player).Play() error`	`func (*Player).Play()`

次の API が削除されるか置き換えられます。

v1	v2
`BytesReadSeekCloser`	(置き換え先はないが、大抵の場合 `bytes.NewReader` で事足りる)
`func (*Context).Update`	(置き換え先なし)
`ReadSeekCloser`	(置き換え先はないが、大抵の場合 `io.ReadSeeker` で事足りる)

`github.com/hajimehoshi/ebiten/audio/mp3`

v2 では Stream の Close は削除され、 Stream はもはや元のソースをクローズしません。

次の API のシグニチャが変更されます。

v1	v2
`func Decode(context audio.Context, src audio.ReadSeekCloser) (Stream, error)`	`func Decode(context audio.Context, src io.ReadSeeker) (Stream, error)`

次の API が削除されるか置き換えられます。

v1	v2
`func (*Stream).Close`	`(置き換え先なし)`
`func (*Stream).Size`	`func (*Stream).Length`

`github.com/hajimehoshi/ebiten/audio/vorbis`

v2 では Stream の Close は削除され、 Stream はもはや元のソースをクローズしません。

次の API のシグニチャが変更されます。

v1	v2
`func Decode(context audio.Context, src audio.ReadSeekCloser) (Stream, error)`	`func Decode(context audio.Context, src io.ReadSeeker) (Stream, error)`

次の API が削除されるか置き換えられます。

v1	v2
`func (*Stream).Close`	`(置き換え先なし)`
`func (*Stream).Size`	`func (*Stream).Length`

`github.com/hajimehoshi/ebiten/audio/wav`

v2 では Stream の Close は削除され、 Stream はもはや元のソースをクローズしません。

次の API のシグニチャが変更されます。

v1	v2
`func Decode(context audio.Context, src audio.ReadSeekCloser) (Stream, error)`	`func Decode(context audio.Context, src io.ReadSeeker) (Stream, error)`

次の API が削除されるか置き換えられます。

v1	v2
`func (*Stream).Close`	`(置き換え先なし)`
`func (*Stream).Size`	`func (*Stream).Length`

`github.com/hajimehoshi/ebiten/ebitenutil`

v2 から、ebitenutil はもはや image/gif や image/png をインポートしません。これは image.Decode の挙動に影響を与えます。

次の API のシグニチャが変更されます。

v1	v2
`func DebugPrint(image *ebiten.Image, str string) error`	`func DebugPrint(image *ebiten.Image, str string)`

`github.com/hajimehoshi/ebiten/inpututil`

次の API のシグニチャが変更されます。

v1	v2
`func GamepadButtonPressDuration(id int, button ebiten.GamepadButton) int`	`func GamepadButtonPressDuration(id ebiten.GamepadID, button ebiten.GamepadButton) int`
`func IsGamepadButtonJustPressed(id int, button ebiten.GamepadButton) bool`	`func IsGamepadButtonJustPressed(id ebiten.GamepadID, button ebiten.GamepadButton) bool`
`func IsGamepadButtonJustReleased(id int, button ebiten.GamepadButton) bool`	`func IsGamepadButtonJustReleased(id ebiten.GamepadID, button ebiten.GamepadButton) bool`
`func IsGamepadJustDisconnected(id int) bool`	`func IsGamepadJustDisconnected(id ebiten.GamepadID) bool`
`func IsTouchJustReleased(id int) bool`	`func IsTouchJustReleased(id ebiten.TouchID) bool`
`func JustConnectedGamepadIDs() []int`	`func JustConnectedGamepadIDs() []ebiten.GamepadID`
`func JustPressedTouchIDs() []int`	`func JustPressedTouchIDs() []ebiten.TouchID`
`func TouchPressDuration(id int) int`	`func TouchPressDuration(id ebiten.TouchID) int`

`github.com/hajimehoshi/ebiten/mobile`

次の API が削除されるか置き換えられます。

v1	v2
`interface Game`	`ebiten` の `Game` インターフェイス
`func Start`	`ebitenmobile` コマンドと `SetGame` 関数
`func Update`	`ebitenmobile` コマンドと `SetGame` 関数
`func UpdateTouchesOnAndroid`	`ebitenmobile` コマンド
`func UpdateTouchesOnIOS`	`ebitenmobile` コマンド