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 that 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.
update function, that is called every frame. This is called 60 times per second (i.e. an Ebiten game work in 60 ticks-per-second by default). This function is passed to
ebiten.Run function later.
update 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.
ebiten.IsDrawingSkipped reports whether the drawing is skipped i.e. the final state of
screen is not adopted. Even though
update is called every frame, rendering skip can sometimes happen in any environments. When
IsDrawingSkipped returns true, any drawing operations should be skipped for performance since rendering result is not used. In usual Ebiten games, it is expected that updating game states happens before checking
IsDrawingSkipped, and drawing happens after checking
IsDrawingSkipped. In this hello-world example,
IsDrawingSkipped is places first since this doesn't have any game states.
update function returns
IsDrawingSkipped returns true. For the returning value of
update, I'll describe later.
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
update is called,
DebugPrint should be called every time.
DebugPrint always returns
nil. The signature says that
DebugPrint returns an error value, but this is due to historical reasons. You can ignore the returned error of
update returns an error value. In that code,
update always returns
nil. In general, when updating function returns a non-nil error, the Ebiten game suspends. As that program never returns a non-nil error, the Ebiten game never stops unless the user closes the window.
main function, which is the entry point of that program.
ebiten.Run is the function to run the main loop of an Ebiten game. The first argument is a function that is called every frame.
update is passed in that program. The other arguments are the screen width, the screen height, the screen scale, and the title respectively.
ebiten.Run returns a non-nil error value when an error happen. In that program, when a non-nil error is returned, that error is logged as a fatal error.