Hello, World!

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

Code

Create a file main.go like this:

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 Ebiten packages. That program imports two packages: github.com/hajimehoshi/ebiten and github.com/hajimehoshi/ebiten/ebitenutil.

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.

Defines 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 ebiten.Image objects. 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 nil when 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 DebugPrint.

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.

Defines the 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.