Ebitengine 2.5 Release Notes


Issues for v2.5.0

Xbox support


Ebitengine now supports Xbox! Odencat released a new Ebitengine game "Meg's Monster" on March 2nd, 2023. This game supports multiple platforms including Xbox One and Xbox Series X|S.

We are preparing more updates to make Ebitengine for Xbox available for other users. Stay tuned!

Vector graphics

(#1843, #2387)


An example 'lines'

Some APIs to render lines or various shapes were added to the vector package:

Also, a new member AntiAlias was added to ebiten.DrawTrianglesOptions and ebiten.DrawTrianglesShaderOptions. AntiAlias is useful to render vector graphics with smooth edges.


(#1450, #2382)


An example 'blend'

A new type ebiten.Blend was added. Blend aims to replace ebiten.CompositeMode. With Blend, you can have finer control than CompositeMode by specifying blend factors and operations for source/destination RGB/alpha values. You can also use preset Blend constants like BlendSourceOver.


(#2378, #1518)

A new function ebiten.RunGameWithOptions and a new struct ebiten.RunGameOptions were added. RunGameWithOptions is a new function to run a game with options. You can specify options by RunGameOptions.

Customizing the screen shader


A new interface ebiten.FinalScreenDrawer was added.

If a game implementing ebiten.Game also implements ebiten.FinalScreenDrawer, its method DrawFinalScreen is called after its Draw is called and you can customize the final screen rendering there. If a game implementing ebiten.Game does NOT implement ebiten.FinalScreenDrawer, the default screen shader, which is similar to the nearest-neighbor filter, is used.

The given arguments of the function DrawFinalScreen are the final screen image as the destination, the offscreen image as the source, and a geometry matrix to enlarge (or shrink) the offscreen to fit with the final screen. The offscreen image is the same as the argument of the game's Draw.

ebiten.ColorScale and colorm


A new struct ebiten.ColorScale and a new package colorm were added. These APIs aim to replace the existing APIs for color matrices. These make your code more explicit about execution costs i.e. a number of draw calls.

For just scalings, you can use the new struct ebiten.ColorScale. For more complex usages of a color matrix, you can use APIs in the package colorm.

A new member ColorScale was also added to ebiten.DrawImageOptions and ebiten.DrawRectShaderOptions.

Note that ColorScale is applied to premultiplied-alpha colors, while colorm.ColorM is applied to straight-alpha colors. Thus, ColorM.Scale(r, g, b, a) equals to ColorScale.Scale(r*a, g*a, b*a, a).

Drag and drop files

(#1868, #2552)

A new function ebiten.DroppedFiles was added. DroppedFiles returns a pseudo file system including the dropped files and directories, and you can access the dropped file contents via the file system. For an actual usage, see the example examples/dropfile.

A float-number version of Layout


A new interface ebiten.LayoutFer was added. LayoutFer has LayoutF method which is a float-number version of Game's Layout. If a game implementing ebiten.Game also implements LayoutFer, its LayoutF is invoked instead of its Layout. You can implement more precise layout caliculation with LayoutF than Layout.

GPU Optimization with SetScreenClearedEveryFrame(false)


When the screen is not cleared every frame by calling SetScreenClearedEveryFrame(false) and your Draw doesn't change the screen, Ebitengine saves GPU usages.

By this optimization, we no longer need FPSModeVsyncOffMinimum, which could save GPU power but was problematic for the performance e.g. when moving a mouse cursor quickly. In Ebitengine 2.5, the type FPSModeType and the APIs using it were deprecated. Instead, ebiten.SetVsyncEnabled and ebiten.IsVsyncEnabled were undeprecated.

Other new APIs

Kage (shader)



OpenGL ES is now automatically chosen when available. In order to specify OpenGL ES explicitly, set an environment variable EBITENGINE_OPENGL with es.

Performance improvement

Ebitengine 2.5 has performance improvements including these items:

Deprecated APIs

Some APIs were deprecated. The deprecated APIs are still available during the version 2, but it is recommended to replace them with the new APIs.

2.4 and older2.5 and newer
type ebiten.ColorMtype ebiten.ColorScale or the package colorm
type ebiten.CompositeModetype ebiten.Blend
type ebiten.FPSModeTypen/a
const ebiten.CompositeMode*const ebiten.Blend*
const ebiten.FPSMode*n/a
func (*ebiten.Image) Sizefunc (*ebiten.Image) Bounds
func ebiten.IsScreenFilterEnabledn/a
func ebiten.IsScreenTransparentn/a
func ebiten.FPSModefunc ebiten.IsVsyncEnabled
func ebiten.ScheduleFrameebiten.SetScreenClearedEveryFrame(false)
func ebiten.SetFPSModefunc ebiten.SetVsyncEnabled
func ebiten.SetInitFocusedfunc ebiten.RunGameWithOptions
func ebiten.SetScreenFilterEnabledinterface ebiten.FinalScreenDrawer
func ebiten.SetScreenTransparentfunc ebiten.RunGameWithOptions
func ebitenutil.DrawLinefunc vector.StrokeLine without anti-aliasing
func ebitenutil.DrawCirclefunc vector.DrawFilledCircle without anti-aliasing
func ebitenutil.DrawRectfunc vector.DrawFilledRect without anti-aliasing

Bug fixes

This release includes all the bug fixes in the version 2.4.

Breaking changes