Ebitengine v2 Migration Guide

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.

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

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

Removing already-deprecated features (e.g., Run)
Removing 'error' returning values from some functions (e.g., DrawImage)
Adding new types to replace integers (e.g., GamepadIDss will return []GamepadID instead of []int)

Platforms

GopherJS is no longer supported as of v2. Use WebAssembly instead.

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.

Lastly, execute go mod tidy command so that your go.mod will include github.com/hajimehoshi/ebiten/v2 and exclude 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.

Updating the API usages

`github.com/hajimehoshi/ebiten`

The default value of DrawTriangleOptions's Address is AddressUnsafe in v2.
Interface Game's Draw function was optional in v1, but is mandatory in v2.
The argument in interface Game's Update is removed in v2.
The default value of IsRunnableOnUnfocused is true in v2.

These types are introduced.

GamepadID
TouchID

These APIs' signatures are changed.

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.

v1	v2
`const FilterDefault`	(No replacement)
`const FPS`	(No replacement)
`const MaxImageSize`	(No replacement)
`struct DrawImageOptions`'s `ImageParts`	`func (*Image).SubImage`
`struct DrawImageOptions`'s `Parts`	`func (*Image).SubImage`
`struct DrawImageOptions`'s `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 `Draw`
`func IsRunningInBackground`	`func IsRunnableOnUnfocused`
`func IsRunningSlowly`	`func RunGame` and interface `Game`'s `Draw`
`func MonitorSize`	`func ScreenSizeInFullscreen`
`func Monochrome`	`func (*ColorM).ChangeHSV` with arguments `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 `Layout`
`func SetScreenSize`	`func RunGame` and interface `Game`'s `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.

These APIs' signatures are changed.

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.

v1	v2
`BytesReadSeekCloser`	(No replacement, but `bytes.NewReader` works in most cases)
`func (*Context).Update`	(No replacement)
`ReadSeekCloser`	(No replacement, but `io.ReadSeeker` works in most cases)

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

Stream's Close is removed, and Stream no longer closes the original source in v2.

These APIs' signatures are changed.

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.

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.

These APIs' signatures are changed.

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.

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.

These APIs' signatures are changed.

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.

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.

These APIs' signatures are changed.

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.

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.

v1	v2
`interface Game`	`ebiten`'s `interface Game`
`func Start`	`ebitenmobile` command and `func SetGame`
`func Update`	`ebitenmobile` command and `func SetGame`
`func UpdateTouchesOnAndroid`	`ebitenmobile` command
`func UpdateTouchesOnIOS`	`ebitenmobile` command