Ebitengine v2 Migration Guide

Ebitengine v2 移行ガイド

Ebitengine v2 升级迁移指南

Overview

概要

Ebitengine v2 is a major version update from v1. There are some breaking changes in the API. Thus, you have to update the program in order to migrate to Ebitengine v2.

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

This document lists the action items for the migration to Ebitengine v2.

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

We don't add drastic changes to v2. Instead, we plan to add quiet changes.

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

Removing already-deprecated features (e.g., Run)
すでに廃止予定の機能を削除 (例: Run)
Removing 'error' returning values from some functions (e.g., DrawImage)
いくつかの関数から、戻り値のエラーを削除 (例: DrawImage)
Adding new types to replace integers (e.g., GamepadIDss will return []GamepadID instead of []int)
整数型に代わる新しい型を追加 (例: GamepadIDs が []int の代わりに []GamepadID を返すようになる)

Platforms

プラットフォーム

GopherJS is no longer supported as of v2. Use WebAssembly instead.
GopherJS は v2 からサポートされません。代わりに WebAssembly を使用してください。

Action items

やることリスト

Updating the import paths

インポートパスの更新

Update all the github.com/hajimehoshi/ebiten in import to github.com/hajimehoshi/ebiten/v2. github.com/hajimehoshi/ebiten/text will be github.com/hajimehoshi/ebiten/v2/text.

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

Lastly, execute go mod tidy command so that your go.mod will include github.com/hajimehoshi/ebiten/v2 and exclude github.com/hajimehoshi/ebiten.

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

You cannot mix Ebitengine v1 and v2 for one application. If you run go mod tidy but there are both version in your go.mod, confirm the dependency relationships and remove the dependency on v1. However, you don't have to do it if you intentionally manage multiple applications in one module.

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

Updating the API usages

API の更新

`github.com/hajimehoshi/ebiten`

The default value of DrawTriangleOptions's Address is AddressUnsafe in v2.
DrawTriangleOptions の Address デフォルト値は v2 では AddressUnsafe になります。
Interface Game's Draw function was optional in v1, but is mandatory in v2.
インターフェイス Game の Draw 関数は v1 ではオプショナルでしたが、 v2 からは必須になります。
The argument in interface Game's Update is removed in v2.
インターフェイス Game の Update 引数は v2 で削除されます。
The default value of IsRunnableOnUnfocused is true in v2.
IsRunnableOnUnfocused のデフォルト値は v2 では true になります。

These types are introduced.

次の型が導入されます。

GamepadID
TouchID

These APIs' signatures are changed.

次の 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)`

These APIs are removed or replaced.

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

v1	v2
`const FilterDefault`	(No replacement)(置き換え先なし)
`const FPS`	(No replacement)(置き換え先なし)
`const MaxImageSize`	(No replacement)(置き換え先なし)
`struct DrawImageOptions`'s `ImagePartsDrawImageOptions` 構造体の `ImageParts`	`func (*Image).SubImage`
`struct DrawImageOptions`'s `PartsDrawImageOptions` 構造体の `Parts`	`func (*Image).SubImage`
`struct DrawImageOptions`'s `SourceRectDrawImageOptions` 構造体の `SourceRect`	`func (*Image).SubImage`
`interface Touch`	func TouchPosition
`func (*ColorM).Add`	(No replacement)(置き換え先なし)
`func (*GeoM).Add`	(No replacement)(置き換え先なし)
`func IsCursorVisible`	`func CursorMode`
`func IsDrawingSkipped`	`func RunGame` and interface `Game`'s `DrawRunGame` 関数と `Game` インターフェイスの `Draw`
`func IsRunningInBackground`	`func IsRunnableOnUnfocused`
`func IsRunningSlowly`	`func RunGame` and interface `Game`'s `DrawRunGame` 関数と `Game` インターフェイスの `Draw`
`func MonitorSize`	`func ScreenSizeInFullscreen`
`func Monochrome`	`func (ColorM).ChangeHSV` with arguments `0, 0, 1(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`	`func RunGame` and interface `Game`'s `LayoutRunGame` 関数と `Game` インターフェイスの `Layout`
`func SetScreenSize`	`func RunGame` and interface `Game`'s `LayoutRunGame` 関数と `Game` インターフェイスの `Layout`
`func Touches`	`func TouchIDs`
`func TranslateColor`	`func (*ColorM).Translate`
`func TranslateGeo`	`func (*GeoM).Translate`

`github.com/hajimehoshi/ebiten/audio`

Player can take a source that doesn't implement io.Closer, and Player no longer closes the original source in v2.
v2 では、 Player は io.Closer ではないソースを取ることができるようになり、 Player はもはや元のソースをクローズしません。

These APIs' signatures are changed.

次の 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()`

These APIs are removed or replaced.

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

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

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

Stream's Close is removed, and Stream no longer closes the original source in v2.
v2 では Stream の Close は削除され、 Stream はもはや元のソースをクローズしません。

These APIs' signatures are changed.

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

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

These APIs are removed or replaced.

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

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

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

Stream's Close is removed, and Stream no longer closes the original source in v2.
v2 では Stream の Close は削除され、 Stream はもはや元のソースをクローズしません。

These APIs' signatures are changed.

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

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

These APIs are removed or replaced.

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

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

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

Stream's Close is removed, and Stream no longer closes the original source in v2.
v2 では Stream の Close は削除され、 Stream はもはや元のソースをクローズしません。

These APIs' signatures are changed.

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

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

These APIs are removed or replaced.

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

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

`github.com/hajimehoshi/ebiten/ebitenutil`

ebitenutil no longer imports image/gif or image/png in v2. This affects the behavior of image.Decode.
v2 から、ebitenutil はもはや image/gif や image/png をインポートしません。これは image.Decode の挙動に影響を与えます。

These APIs' signatures are changed.

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

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

`github.com/hajimehoshi/ebiten/inpututil`

These APIs' signatures are changed.

次の 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`

These APIs are removed or replaced.

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

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