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.
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
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 main.go
If you see the screen with the text 'Hello, World!', congratulations, your program succeeded to work!:
How the code works
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.
ebiten.Game has necessary functions for an Ebitengine game:
Layout. Let's see them one by one.
(*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.
(*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
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.
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.
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.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.