As the first Ebiten game, let's show the message 'Hello, World!'.
Before executing the program, you need to install Ebiten. See the instruction to install Ebiten.
Create a file
main.go like this:
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 is the core package of Ebiten, which provides functions for drawing and inputs.
github.com/hajimehoshi/ebiten/ebitenutil is the utility package of Ebiten. In this program, this package is used to print a debug message on the screen.
There are other several packages in Ebiten. See the packages page for more details.
ebiten.Game has necessary functions for an Ebiten 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 Ebiten 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 takes an argument
screen, which is a pointer to an
ebiten.Image. This example doesn't use this.
Update returns an error value. In this code,
Update always returns
nil. In general, when updating function returns a non-nil error, the Ebiten game suspends. As this program never returns a non-nil error, the Ebiten 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 also takes an argument
screen, which is a pointer to an
ebiten.Image. In Ebiten, 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.
DebugPrint always returns
nil. The signature says this
DebugPrint returns an error value, but this is due to historical reasons. You can ignore the returned error of
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 Ebiten 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.