Hello, World!

As the first Ebitengine game, let's show the message 'Hello, World!'.

Before executing the program, you need to install Ebitengine. See the instruction to install Ebitengine.

Code

This tour assumes that you are in a working directory with go.mod. If not, please try these commands to create a directory and a go.mod file.

mkdir yourgame
cd yourgame
go mod init foo # or github.com/yourname/yourgame or something

Create a file main.go like this:

If you have just initialized the go.mod file by go mod init, please run this command to resolve dependencies.

go mod tidy

Then, execute this Go program by go run:

go run main.go

If you see the screen with the text 'Hello, World!', congratulations, your program succeeded to work!:

How the code works

Imports Ebitengine packages. This program imports two packages: github.com/hajimehoshi/ebiten/v2 and github.com/hajimehoshi/ebiten/v2/ebitenutil.

github.com/hajimehoshi/ebiten/v2 is the core package of Ebitengine, which provides functions for drawing and inputs.

github.com/hajimehoshi/ebiten/v2/ebitenutil is the utility package of Ebitengine. In this program, this package is used to print a debug message on the screen.

There are other several packages in Ebitengine. See the packages page for more details.

Defines Game struct. Game implements ebiten.Game interface. ebiten.Game has necessary functions for an Ebitengine game: Update, Draw and Layout. Let's see them one by one.

Defines (*Game).Update function, that is called every tick. Tick is a time unit for logical updating. The default value is 1/60 [s], then Update is called 60 times per second by default (i.e. an Ebitengine game works in 60 ticks-per-second).

Update updates the game's logical state. This hello-world example doesn't have any state and then this function does nothing.

Update returns an error value. In this code, Update always returns nil. In general, when updating function returns a non-nil error, the Ebitengine game suspends. As this program never returns a non-nil error, the Ebitengine game never stops unless the user closes the window.

Defines (*Game).Draw function, that is called every frame. Frame is a time unit for rendering and this depends on the display's refresh rate. If the monitor's refresh rate is 60 [Hz], Draw is called 60 times per second.

Draw takes an argument screen, which is a pointer to an ebiten.Image. In Ebitengine, all images like images created from image files, offscreen images (temporary render target), and the screen are represented as ebiten.Image objects. screen argument is the final destination of rendering. The window shows the final state of screen every frame.

ebitenutil.DebugPrint is a utility function to render a debug message on an image. In this case, screen is passed as the render target of the debug printing. As screen is reset (or cleared in another word) whenever Draw is called, DebugPrint should be called every time.

Defines (*Game).Layout function. Layout accepts an outside size, which is a window size on desktop, and returns the game's logical screen size. This code ignores the arguments and returns the fixed values. This means that the game screen size is always same, whatever the window's size is. Layout will be more meaningful e.g., when the window is resizable.

Defines the main function, which is the entry point of this program.

ebiten.SetWindowSize sets the window's size. Without calling this, the default window size is used.

ebiten.SetWindowTitle sets the window's title.

ebiten.RunGame is the function to run the main loop of an Ebitengine game. The argument is a Game object, that implements ebiten.Game. ebiten.RunGame returns a non-nil error value when an error happen. In this program, when a non-nil error is returned, this error is logged as a fatal error.