CurrentFPS returns the current number of FPS (frames per second), that represents how many swapping buffer happens per second.

On some environments, CurrentFPS doesn't return a reliable value since vsync doesn't work well there. If you want to measure the application's speed, Use CurrentTPS.

CurrentFPS is concurrent-safe.

CurrentTPS returns the current TPS (ticks per second), that represents how many update function is called in a second.

CurrentTPS is concurrent-safe.

func CursorPosition() (x, y int)

CursorPosition returns a position of a mouse cursor relative to the game screen (window). The cursor position is 'logical' position and this considers the scale of the screen.

CursorPosition is concurrent-safe.

DeviceScaleFactor returns a device scale factor value of the current monitor which the window belongs to.

DeviceScaleFactor returns a meaningful value on high-DPI display environment, otherwise DeviceScaleFactor returns 1.

DeviceScaleFactor might panic on init function on some devices like Android. Then, it is not recommended to call DeviceScaleFactor from init functions.

DeviceScaleFactor must be called on the main thread before the main loop, and is concurrent-safe after the main loop.

GamepadAxis returns the float value [-1.0 - 1.0] of the given gamepad (id)'s axis (axis).

GamepadAxis is concurrent-safe.

GamepadAxis always returns 0 on iOS.

func GamepadAxisNum(id int) int

GamepadAxisNum returns the number of axes of the gamepad (id).

GamepadAxisNum is concurrent-safe.

GamepadAxisNum always returns 0 on iOS.

func GamepadButtonNum(id int) int

GamepadButtonNum returns the number of the buttons of the given gamepad (id).

GamepadButtonNum is concurrent-safe.

GamepadButtonNum always returns 0 on iOS.

GamepadIDs returns a slice indicating available gamepad IDs.

GamepadIDs is concurrent-safe.

GamepadIDs always returns an empty slice on iOS.

GamepadName returns a string with the name. This function may vary in how it returns descriptions for the same device across platforms for example the following drivers/platforms see a Xbox One controller as the following:

• Windows: "Xbox Controller"
• Chrome: "Xbox 360 Controller (XInput STANDARD GAMEPAD)"
• Firefox: "xinput"

GamepadName always returns an empty string on iOS.

GamepadName is concurrent-safe.

GamepadSDLID returns a string with the GUID generated in the same way as SDL. To detect devices, see also the community project of gamepad devices database: https://github.com/gabomdq/SDL_GameControllerDB

GamepadSDLID always returns an empty string on browsers and mobiles.

GamepadSDLID is concurrent-safe.

InputChars return "printable" runes read from the keyboard at the time update is called.

InputChars represents the environment's locale-dependent translation of keyboard input to Unicode characters.

IsKeyPressed is based on a mapping of device (US keyboard) codes to input device keys. "Control" and modifier keys should be handled with IsKeyPressed.

InputChars is concurrent-safe.

On Android (ebitenmobile), EbitenView must be focusable to enable to handle keyboard keys.

Keyboards don't work on iOS yet (#1090).

func IsDrawingSkipped() bool

IsDrawingSkipped returns true if rendering result is not adopted. It is recommended to skip drawing images or screen when IsDrawingSkipped is true.

The typical code with IsDrawingSkipped is this:

func update(screen *ebiten.Image) error {
    // Update the state.
    // When IsDrawingSkipped is true, the rendered result is not adopted.
    // Skip rendering then.
    if ebiten.IsDrawingSkipped() {
        return nil
    }
    // Draw something to the screen.
    return nil
}

IsDrawingSkipped is useful if you use Run function or RunGame function without implementing Game's Draw. Otherwise, i.e., if you use RunGame function with implementing Game's Draw, IsDrawingSkipped should not be used. If you use RunGame and Draw, IsDrawingSkipped always returns true.

IsDrawingSkipped is concurrent-safe.

IsFocused returns a boolean value indicating whether the game is in focus or in the foreground.

IsFocused will only return true if IsRunnableOnUnfocused is false.

IsFocused is concurrent-safe.

IsFullscreen reports whether the current mode is fullscreen or not.

IsFullscreen always returns false on browsers. IsFullscreen works as this as of 1.10.0-alpha. Before that, IsFullscreen reported whether the current mode is fullscreen or not.

IsFullscreen always returns false on mobiles.

IsFullscreen is concurrent-safe.

func IsGamepadButtonPressed(id int, button GamepadButton) bool

IsGamepadButtonPressed returns the boolean indicating the given button of the gamepad (id) is pressed or not.

If you want to know whether the given button of gamepad (id) started being pressed in the current frame, use inpututil.IsGamepadButtonJustPressed

IsGamepadButtonPressed is concurrent-safe.

The relationships between physical buttons and buttion IDs depend on environments. There can be differences even between Chrome and Firefox.

IsGamepadButtonPressed always returns false on iOS.

func IsKeyPressed(key Key) bool

IsKeyPressed returns a boolean indicating whether key is pressed.

If you want to know whether the key started being pressed in the current frame, use inpututil.IsKeyJustPressed

Known issue: On Edge browser, some keys don't work well:

• KeyKPEnter and KeyKPEqual are recognized as KeyEnter and KeyEqual.
• KeyPrintScreen is only treated at keyup event.

IsKeyPressed is concurrent-safe.

On Android (ebitenmobile), EbitenView must be focusable to enable to handle keyboard keys.

Keyboards don't work on iOS yet (#1090).

func IsMouseButtonPressed(mouseButton MouseButton) bool

IsMouseButtonPressed returns a boolean indicating whether mouseButton is pressed.

If you want to know whether the mouseButton started being pressed in the current frame, use inpututil.IsMouseButtonJustPressed

IsMouseButtonPressed is concurrent-safe.

Note that touch events not longer affect IsMouseButtonPressed's result as of 1.4.0-alpha. Use Touches instead.

func IsRunnableOnUnfocused() bool

IsRunnableOnUnfocused returns a boolean value indicating whether the game runs even in background.

IsRunnableOnUnfocused is concurrent-safe.

func IsScreenClearedEveryFrame() bool

IsScreenClearedEveryFrame returns true if the frame isn't cleared at the beginning.

IsScreenClearedEveryFrame is concurrent-safe.

func IsScreenTransparent() bool

IsScreenTransparent reports whether the window is transparent.

IsScreenTransparent is concurrent-safe.

func IsVsyncEnabled() bool

IsVsyncEnabled returns a boolean value indicating whether the game uses the display's vsync.

IsVsyncEnabled is concurrent-safe.

func IsWindowDecorated() bool

IsWindowDecorated reports whether the window is decorated.

IsWindowDecorated is concurrent-safe.

func IsWindowFloating() bool

IsWindowFloating reports whether the window is always shown above all the other windows.

IsWindowFloating returns false on browsers and mobiles.

IsWindowFloating is concurrent-safe.

func IsWindowMaximized() bool

IsWindowMaximized reports whether the window is maximized or not.

IsWindowMaximized returns false when the window is not resizable.

IsWindowMaximized always returns false on browsers and mobiles.

IsWindowMaximized is concurrent-safe.

func IsWindowMinimized() bool

IsWindowMinimized reports whether the window is minimized or not.

IsWindowMinimized always returns false on browsers and mobiles.

IsWindowMinimized is concurrent-safe.

func IsWindowResizable() bool

IsWindowResizable reports whether the window is resizable by the user's dragging on desktops. On the other environments, IsWindowResizable always returns false.

IsWindowResizable is concurrent-safe.

MaxTPS returns the current maximum TPS.

MaxTPS is concurrent-safe.

func MaximizeWindow()

MaximizeWindow maximizes the window.

MaximizeWindow panics when the window is not resizable.

MaximizeWindow does nothing on browsers or mobiles.

MaximizeWindow is concurrent-safe.

func MinimizeWindow()

MinimizeWindow minimizes the window.

If the main loop does not start yet, MinimizeWindow does nothing.

MinimizeWindow does nothing on browsers or mobiles.

MinimizeWindow is concurrent-safe.

func RestoreWindow()

RestoreWindow restores the window from its maximized or minimized state.

RestoreWindow panics when the window is not maximized nor minimized.

RestoreWindow is concurrent-safe.

RunGame starts the main loop and runs the game. game's Update function is called every tick to update the game logic. game's Draw function is, if it exists, called every frame to draw the screen. game's Layout function is called when necessary, and you can specify the logical screen size by the function.

game must implement Game interface. Game's Draw function is optional, but it is recommended to implement Draw to seperate updating the logic and rendering.

RunGame is a more flexibile form of Run due to game's Layout function. You can make a resizable window if you use RunGame, while you cannot if you use Run. RunGame is more sophisticated way than Run and hides the notion of 'scale'.

While Run specifies the window size, RunGame does not. You need to call SetWindowSize before RunGame if you want. Otherwise, a default window size is adopted.

Some functions (ScreenScale, SetScreenScale, SetScreenSize) are not available with RunGame.

On browsers, it is strongly recommended to use iframe if you embed an Ebiten application in your website.

RunGame must be called on the main thread. Note that Ebiten bounds the main goroutine to the main OS thread by runtime.LockOSThread.

Ebiten tries to call game's Update function 60 times a second by default. In other words, TPS (ticks per second) is 60 by default. This is not related to framerate (display's refresh rate).

game's Update is not called when the window is in background by default. This setting is configurable with SetRunnableOnUnfocused.

On non-GopherJS environments, RunGame returns error when 1) OpenGL error happens, 2) audio error happens or 3) f returns error. In the case of 3), RunGame returns the same error.

On GopherJS, RunGame returns immediately. It is because the 'main' goroutine cannot be blocked on GopherJS due to the bug (gopherjs/gopherjs#826). When an error happens, this is shown as an error on the console.

The size unit is device-independent pixel.

Don't call RunGame twice or more in one process.

func RunGameWithoutMainLoop ¶ added in v1.11.0

func RunGameWithoutMainLoop(game Game)

RunGameWithoutMainLoop runs the game, but don't call the loop on the main (UI) thread. Different from Run, RunGameWithoutMainLoop returns immediately.

Ebiten users should NOT call RunGameWithoutMainLoop. Instead, functions in github.com/hajimehoshi/ebiten/mobile package calls this.

func ScreenSizeInFullscreen() (int, int)

ScreenSizeInFullscreen returns the size in device-independent pixels when the game is fullscreen. The adopted monitor is the 'current' monitor which the window belongs to. The returned value can be given to Run or SetSize function if the perfectly fit fullscreen is needed.

On browsers, ScreenSizeInFullscreen returns the 'window' (global object) size, not 'screen' size since an Ebiten game should not know the outside of the window object. For more details, see SetFullscreen API comment.

On mobiles, ScreenSizeInFullscreen returns (0, 0) so far.

ScreenSizeInFullscreen's use cases are limited. If you are making a fullscreen application, you can use RunGame and the Game interface's Layout function instead. If you are making a not-fullscreen application but the application's behavior depends on the monitor size, ScreenSizeInFullscreen is useful.

ScreenSizeInFullscreen must be called on the main thread before ebiten.Run, and is concurrent-safe after ebiten.Run.

func SetCursorMode(mode CursorModeType)

SetCursorMode sets the render and capture mode of the mouse cursor. CursorModeVisible sets the cursor to always be visible. CursorModeHidden hides the system cursor when over the window. CursorModeCaptured hides the system cursor and locks it to the window.

On browsers, only CursorModeVisible and CursorModeHidden are supported.

SetCursorMode does nothing on mobiles.

SetCursorMode is concurrent-safe.

func SetFullscreen(fullscreen bool)

SetFullscreen changes the current mode to fullscreen or not on desktops.

On fullscreen mode, the game screen is automatically enlarged to fit with the monitor. The current scale value is ignored.

On desktops, Ebiten uses 'windowed' fullscreen mode, which doesn't change your monitor's resolution.

SetFullscreen does nothing on browsers. SetFullscreen works as this as of 1.10.0-alpha. Before that, SetFullscreen affected the fullscreen mode.

SetFullscreen does nothing on mobiles.

SetFullscreen does nothing on macOS when the window is fullscreened natively by the macOS desktop instead of SetFullscreen(true).

SetFullscreen is concurrent-safe.

func SetInitFocused(focused bool)

SetInitFocused sets whether the application is focused on show. The default value is true, i.e., the application is focused. Note that the application does not proceed if this is not focused by default. This behavior can be changed by SetRunnableInBackground.

SetInitFocused does nothing on mobile.

SetInitFocused panics if this is called after the main loop.

SetInitFocused is cuncurrent-safe.

SetMaxTPS sets the maximum TPS (ticks per second), that represents how many updating function is called per second. The initial value is 60.

If tps is UncappedTPS, TPS is uncapped and the game is updated per frame. If tps is negative but not UncappedTPS, SetMaxTPS panics.

SetMaxTPS is concurrent-safe.

func SetRunnableOnUnfocused(runnableOnUnfocused bool)

SetRunnableOnUnfocused sets the state if the game runs even in background.

If the given value is true, the game runs in background e.g. when losing focus. The initial state is false.

Known issue: On browsers, even if the state is on, the game doesn't run in background tabs. This is because browsers throttles background tabs not to often update.

SetRunnableOnUnfocused does nothing on mobiles so far.

SetRunnableOnUnfocused is concurrent-safe.

func SetScreenClearedEveryFrame(cleared bool)

SetScreenClearedEveryFrame enables or disables the clearing of the screen at the beginning of each frame. The default value is true and the screen is cleared each frame by default.

SetScreenClearedEveryFrame is concurrent-safe.

func SetScreenTransparent(transparent bool)

SetScreenTransparent sets the state if the window is transparent.

SetScreenTransparent panics if SetScreenTransparent is called after the main loop.

SetScreenTransparent does nothing on mobiles.

SetScreenTransparent is concurrent-safe.

func SetVsyncEnabled(enabled bool)

SetVsyncEnabled sets a boolean value indicating whether the game uses the display's vsync.

If the given value is true, the game tries to sync the display's refresh rate. If false, the game ignores the display's refresh rate. The initial value is true. By disabling vsync, the game works more efficiently but consumes more CPU.

Note that the state doesn't affect TPS (ticks per second, i.e. how many the run function is updated per second).

SetVsyncEnabled does nothing on mobiles so far.

SetVsyncEnabled is concurrent-safe.

func SetWindowDecorated(decorated bool)

SetWindowDecorated sets the state if the window is decorated.

The window is decorated by default.

SetWindowDecorated works only on desktops. SetWindowDecorated does nothing on other platforms.

SetWindowDecorated does nothing on macOS when the window is fullscreened natively by the macOS desktop instead of SetFullscreen(true).

SetWindowDecorated is concurrent-safe.

func SetWindowFloating(float bool)

SetWindowFloating sets the state whether the window is always shown above all the other windows.

SetWindowFloating does nothing on browsers or mobiles.

SetWindowFloating does nothing on macOS when the window is fullscreened natively by the macOS desktop instead of SetFullscreen(true).

SetWindowFloating is concurrent-safe.

SetWindowIcon sets the icon of the game window.

If len(iconImages) is 0, SetWindowIcon reverts the icon to the default one.

For desktops, see the document of glfwSetWindowIcon of GLFW 3.2:

This function sets the icon of the specified window.
If passed an array of candidate images, those of or closest to the sizes
desired by the system are selected.
If no images are specified, the window reverts to its default icon.
The desired image sizes varies depending on platform and system settings.
The selected images will be rescaled as needed.
Good sizes include 16x16, 32x32 and 48x48.

As macOS windows don't have icons, SetWindowIcon doesn't work on macOS.

SetWindowIcon doesn't work on browsers or mobiles.

SetWindowIcon is concurrent-safe.

func SetWindowPosition(x, y int)

SetWindowPosition sets the window position. The origin position is the left-upper corner of the current monitor. The unit is device-independent pixels.

SetWindowPosition does nothing on fullscreen mode.

SetWindowPosition does nothing on browsers and mobiles.

SetWindowPosition is concurrent-safe.

func SetWindowResizable(resizable bool)

SetWindowResizable sets whether the window is resizable by the user's dragging on desktops. On the other environments, SetWindowResizable does nothing.

The window is not resizable by default.

If SetWindowResizable is called with true and Run is used, SetWindowResizable panics. Use RunGame instead.

SetWindowResizable does nothing on macOS when the window is fullscreened natively by the macOS desktop instead of SetFullscreen(true).

SetWindowResizable is concurrent-safe.

func SetWindowSize(width, height int)

SetWindowSize sets the window size on desktops. SetWindowSize does nothing on other environments.

On fullscreen mode, SetWindowSize sets the original window size.

SetWindowSize panics if width or height is not a positive number.

SetWindowSize is concurrent-safe.

func SetWindowTitle(title string)

SetWindowTitle sets the title of the window.

SetWindowTitle updated the title on browsers, but now does nothing on browsers as of 1.11.0-alpha.

SetWindowTitle does nothing on mobiles.

SetWindowTitle is concurrent-safe.

TouchIDs returns the current touch states.

If you want to know whether a touch started being pressed in the current frame, use inpututil.JustPressedTouchIDs

TouchIDs returns nil when there are no touches. TouchIDs always returns nil on desktops.

TouchIDs is concurrent-safe.

TouchPosition returns the position for the touch of the specified ID.

If the touch of the specified ID is not present, TouchPosition returns (0, 0).

TouchPosition is cuncurrent-safe.

Wheel returns the x and y offset of the mouse wheel or touchpad scroll. It returns 0 if the wheel isn't being rolled.

Wheel is concurrent-safe.

func WindowPosition() (x, y int)

WindowPosition returns the window position. The origin position is the left-upper corner of the current monitor. The unit is device-independent pixels.

WindowPosition panics if the main loop does not start yet.

WindowPosition returns the last window position on fullscreen mode.

WindowPosition returns (0, 0) on browsers and mobiles.

WindowPosition is concurrent-safe.

WindowSize returns the window size on desktops. WindowSize returns (0, 0) on other environments.

On fullscreen mode, WindowSize returns the original window size.

WindowSize is concurrent-safe.

Address represents a sampler address mode.

type ColorM struct {
}

A ColorM represents a matrix to transform coloring when rendering an image.

A ColorM is applied to the straight alpha color while an Image's pixels' format is alpha premultiplied. Before applying a matrix, a color is un-multiplied, and after applying the matrix, the color is multiplied again.

The initial value is identity.

func TranslateColor(r, g, b, a float64) ColorM

func (c *ColorM) Add(other ColorM)

func (c *ColorM) Concat(other ColorM)

func (c *ColorM) Invert()

func (c *ColorM) IsInvertible() bool

func (c *ColorM) Translate(r, g, b, a float64)

CompositeMode represents Porter-Duff composition mode.

CursorModeType represents a render and coordinate mode of a mouse cursor.

func CursorMode() CursorModeType

type DrawImageOptions struct {


	GeoM GeoM


	ColorM ColorM


	CompositeMode CompositeMode


	Filter Filter

	ImageParts ImageParts

	Parts []ImagePart

	SourceRect *image.Rectangle
}

DrawImageOptions represents options for DrawImage.

type DrawRectShaderOptions struct {


	GeoM GeoM


	CompositeMode CompositeMode


	Uniforms map[string]interface{}


	Images [4]*Image
}

DrawRectShaderOptions represents options for DrawRectShader.

This API is experimental.

type DrawTrianglesOptions struct {


	ColorM ColorM


	CompositeMode CompositeMode


	Filter Filter


	Address Address
}

DrawTrianglesOptions represents options for DrawTriangles.

type DrawTrianglesShaderOptions struct {


	CompositeMode CompositeMode


	Uniforms map[string]interface{}


	Images [4]*Image
}

DrawTrianglesShaderOptions represents options for DrawTrianglesShader.

This API is experimental.

Filter represents the type of texture filter to be used when an image is maginified or minified.

type Game interface {


	Update(screen *Image) error


	Layout(outsideWidth, outsideHeight int) (screenWidth, screenHeight int)
}

Game defines necessary functions for a game.

A GamepadButton represents a gamepad button.

type GeoM struct {
}

A GeoM represents a matrix to transform geometry when rendering an image.

The initial value is identity.

func (g *GeoM) Add(other GeoM)

func (g *GeoM) Concat(other GeoM)

func (g *GeoM) IsInvertible() bool

func (g *GeoM) Skew(skewX, skewY float64)

type Image struct {
}

Image represents a rectangle set of pixels. The pixel format is alpha-premultiplied RGBA. Image implements image.Image and draw.Image.

Functions of Image never returns error as of 1.5.0, and error values are always nil.

func NewImage(width, height int, filter Filter) (*Image, error)

func (i *Image) DrawImage(img *Image, options *DrawImageOptions) error

func (i *Image) DrawRectShader(width, height int, shader *Shader, options *DrawRectShaderOptions)

func (i *Image) DrawTriangles(vertices []Vertex, indices []uint16, img *Image, options *DrawTrianglesOptions)

func (i *Image) DrawTrianglesShader(vertices []Vertex, indices []uint16, shader *Shader, options *DrawTrianglesShaderOptions)

func (i *Image) Size() (width, height int)

A Key represents a keyboard key. These keys represent pysical keys of US keyboard. For example, KeyQ represents Q key on US keyboards and ' (quote) key on Dvorak keyboards.

A MouseButton represents a mouse button.

type Shader struct {
}

Shader represents a compiled shader program.

For the details about the shader, see https://ebiten.org/documents/shader.html.

func (s *Shader) Dispose()

Vertex represents a vertex passed to DrawTriangles.