The terminal is a powerful tool that can be used for more than just running commands. In this tutorial, we will create a simple snake game that runs in the terminal using Go; no dependencies, no assets. Although the game could be done in a single script, I will break it down into multiple files so that we can learn how to structure a Go project.
Each go module will be responsible for a different part of the game. We will have a module for the terminal, one for reading the user's input, one for the game logic, and one for rendering.
Let's get started!
Before we start, make sure you have Go installed on your machine, our only dependency for this project. If you don't have it installed, you can download it from the official website.
Then, create a new directory for the project and navigate to it.
mkdir snake-game
cd snake-game
To start a new Go project, we need to create a new module. We can do this by running the following command.
go mod init snake
This will create a new file called go.mod in the current directory. This file is used to define the module and its dependencies.
Now that we have our module set up, we can start writing the code for our game. Let's start by creating a new file called main.go and adding some temporary code to it.
package main
import (
"fmt"
)
func main() {
fmt.Println("Hello, World!")
}
By default, the terminal is in canonical mode. This means that the terminal waits for the user to press Enter before sending the input to the program. This is not suitable for games, as we want to process the input as soon as the user presses a key. To do this, we need to put the terminal in raw mode.
Let's create a new directory called terminal and add a new file called termios.go to it. This file will contain a struct called Termios that we will use to store the terminal attributes.
package terminal
type Termios struct {
Iflag, Oflag, Cflag, Lflag uint32
Cc [20]byte
Ispeed, Ospeed uint32
}
Iflag, Oflag, Cflag, and Lflag are used to store the input, output, control, and local modes, respectively. Cc is used to store the control characters. Ispeed and Ospeed are used to store the input and output baud rates.
The next step is to create a new function called getTermios that will return the current terminal attributes. For this, we will use the syscall and unsafe packages.
package terminal
import (
"syscall"
"unsafe"
)
func getTermios(fd uintptr) (*Termios, error) {
termios := &Termios{}
_, _, errno := syscall.Syscall(syscall.SYS_IOCTL, fd, syscall.TCGETS, uintptr(unsafe.Pointer(termios)))
if errno != 0 {
return nil, errno
}
return termios, nil
}
This function accepts a file descriptor fd as an argument, which is used to identify the terminal. We initialize a new Termios struct and use the syscall.Syscall function to make a system call to ioctl (input/output control) with syscall.TCGETS indicating that the current settings of the terminal are to be read. The memory address of the Termios struct is passed to ioctl through unsafe.Pointer, facilitating direct memory manipulation. If the operation is successful, the function returns a pointer to a Termios struct populated with the current terminal settings. If there's an error (indicated by a non-zero errno), an error is returned instead.
For setting back the terminal attributes given a Termios struct, we can create a new function called setTermios.
func setTermios(fd uintptr, termios *Termios) error {
_, _, errno := syscall.Syscall(syscall.SYS_IOCTL, fd, uintptr(syscall.TCSETS+1), uintptr(unsafe.Pointer(termios)))
if errno != 0 {
return errno
}
return nil
}
The main idea is the same as the getTermios function, but this time we use syscall.TCSETS to set the terminal attributes. We add one to the constant to indicate that we want to change the terminal settings.
Now that we have the functions to get and set the terminal attributes, we can create a new struct called Terminal that will store all of our terminal-related data. This struct will contain:
package terminal
type Terminal struct {
fd uintptr
original Termios
modified *Termios
NCols int
NRows int
}
We will also create a new function called New that will return a new Terminal object.
import (
"os"
)
func New() (*Terminal, error) {
t := &Terminal{}
t.fd = os.Stdout.Fd()
termios, err := getTermios(t.fd)
if err != nil {
return nil, err
}
t.original = *termios
t.modified = termios
return t, nil
}
This function initializes a new Terminal object and sets the file descriptor to the standard output. It then gets the current terminal attributes and stores them in the original and modified attributes. If an error occurs, the function returns nil and the error.
We can then create a new method called Restore that will restore the terminal to its original state.
func (t *Terminal) Restore() error {
return setTermios(t.fd, &t.original)
}
This method calls the setTermios function with the file descriptor and the original terminal attributes. If an error occurs, the method returns the error.
We will also create a new method called getWindowSize that will get the number of columns and rows of the terminal. First, we need to import again the syscall and unsafe packages, as we will also make a system call to ioctl to get the window size.
import (
"os"
"syscall"
"unsafe"
)
func (t *Terminal) getWindowSize() error {
ws := struct {
row uint16
col uint16
}{}
_, _, errno := syscall.Syscall(syscall.SYS_IOCTL, t.fd, syscall.TIOCGWINSZ, uintptr(unsafe.Pointer(&ws)))
if errno != 0 {
return errno
}
t.NCols = int(ws.col)
t.NRows = int(ws.row)
return nil
}
In this function, we create an anonymous struct called ws that contains two fields: row and col. We then use the syscall.Syscall function to make a system call to ioctl with syscall.TIOCGWINSZ indicating that the window size is to be read. The memory address of the ws struct is passed to ioctl through unsafe.Pointer. If the operation is successful, the function returns the number of columns and rows of the terminal. If there's an error (indicated by a non-zero errno), an error is returned instead.
Finally, we will create a new method called enableRawMode that will put the terminal in raw mode.
func (t *Terminal) enableRawMode() {
t.modified.Lflag &^= syscall.ECHO | syscall.ICANON | syscall.ISIG | syscall.IEXTEN
t.modified.Iflag &^= syscall.BRKINT | syscall.ICRNL | syscall.INPCK | syscall.ISTRIP | syscall.IXON
t.modified.Cflag |= syscall.CS8
t.modified.Oflag &^= syscall.OPOST
t.modified.Cc[syscall.VMIN+1] = 0
t.modified.Cc[syscall.VTIME+1] = 1
}
This method modifies the terminal attributes to put the terminal in raw mode. It turns off a bunch of flags that are enabled by default in our terminal. Basically,
it turns off the echoing of input, canonical mode, and signals. It also sets the character size to 8 bits and turns off output processing. Finally, it sets the minimum number of characters to read before returning from a read and the maximum amount of time to wait before returning from a read.
If you are interested in learning more about the terminal attributes, you can check the kilo tutorial, which explains in great detail how to put the terminal in raw mode.
Now, we can complete the New function by calling the enableRawMode and getWindowSize methods.
func New() (*Terminal, error) {
t := &Terminal{}
t.fd = os.Stdout.Fd()
termios, err := getTermios(t.fd)
if err != nil {
return nil, err
}
t.original = *termios
t.modified = termios
t.enableRawMode()
err = t.getWindowSize()
if err != nil {
return nil, err
}
err = setTermios(t.fd, t.modified)
if err != nil {
return nil, err
}
return t, nil
}
Now that we have our terminal object, let's modify the main function to use it. We will create a new terminal object and defer a call to its Restore method to ensure that the terminal is restored to its original state when the program exits. Additionally, we will add a loop that reads a single byte from the standard input and exits when the user presses the q key.
package main
import (
"os"
"snake/terminal"
)
func main() {
t, err := terminal.New()
if err != nil {
panic(err)
}
defer t.Restore()
buffer := make([]byte, 1)
for {
os.Stdin.Read(buffer)
if buffer[0] == 'q' {
break
}
}
}
When you run the program, you should see that the terminal is now in raw mode, meaning that the input is processed as soon as the user presses a key. For now, nothing will happen when you press a key, but we will use this functionality to move the snake in the following sections.
When you press the q key, the program will exit and the terminal will be restored to its original state.
We will create a new module named inputreader which will be responsible for reading the user's input and sending the corresponding key to the game loop.
This module will contain a struct called InputReader that will store a buffer to read the user's input.
package inputreader
type InputReader struct {
buffer []byte
}
We create a new function called New that will return a new InputReader object.
func New() *InputReader {
return &InputReader{buffer: make([]byte, 1)}
}
The buffer will be used to store a single byte of the user's input.
We also create a new method called Read that will read the byte from the standard input and return it.
import (
"os"
)
func (ir *InputReader) Read() byte {
os.Stdin.Read(ir.buffer)
return ir.buffer[0]
}
It's always important to catch errors when reading from the standard input, but for this application, we don't want the program to panic if an error occurs. Instead, we will ignore the error so the game can continue running.
Now, let's update the main function to use the InputReader object.
import (
"snake/terminal"
"snake/inputreader"
)
func main() {
t, err := terminal.New()
if err != nil {
panic(err)
}
defer t.Restore()
ir := inputreader.New()
for {
key := ir.Read()
if key == 'q' {
break
}
}
}
If you run the program now, you should see that the terminal is still in raw mode and that the program exits when you press the q key.
Arrow keys are a bit special, as they are represented by three bytes instead of one:
We will update the Read method to detect arrow keys and map them to a single byte, corresponding with the WASD keys.
func (ir *InputReader) Read() byte {
os.Stdin.Read(ir.buffer)
if ir.buffer[0] == 27 {
seq := make([]byte, 2)
os.Stdin.Read(seq)
if seq[0] == 91 {
switch seq[1] {
case 65:
return 'w'
case 66:
return 's'
case 67:
return 'd'
case 68:
return 'a'
}
}
}
return ir.buffer[0]
}
With this, we have finished with the user's input for a long time. We will now move on to the game loop and rendering.
Once we have the user's input, we can start working on the game loop. The game loop will be responsible for updating the game state. For now, we will use the cursor as the object we want to move around the terminal. Then, it will be easy to replace the cursor with the snake.
Let's create a struct called Game that will store the cursor position, and the respective New function.
package game
type Game struct {
X int
Y int
}
func New() *Game {
return &Game{X: 0, Y: 0}
}
Now, we can create a new method called Update that will update the game state based on the user's input.
func (g *Game) Update(key byte) {
switch key {
case 'w':
g.Y--
case 's':
g.Y++
case 'a':
g.X--
case 'd':
g.X++
}
}
With all this, we can update the main function to use the Game object and update the game state based on the user's input.
func main() {
t, err := terminal.New()
if err != nil {
panic(err)
}
defer t.Restore()
ir := inputreader.New()
g := game.New()
for {
key := ir.Read()
if key == 'q' {
break
}
g.Update(key)
}
}
If you run the program, nothing should have changed.
Now that we have the game state, we can start rendering the game. We will create a new module called renderer that will be responsible for rendering the game state to the terminal.
Inside the renderer module, we will create a new struct called Renderer and a new function called New that will return a new Renderer object.
package renderer
type Renderer struct {
}
func New() *Renderer {
return &Renderer{}
}
We will also create a new method called Render that will render the game state to the terminal.
import (
"fmt"
"os"
"snake/game"
)
func (r *Renderer) Render(g *game.Game) {
cursorPos := fmt.Sprintf("\x1b[%d;%dH", g.Y+1, g.X+1)
os.Stdout.WriteString(cursorPos)
}
This method uses the fmt.Sprintf function to create a string with the escape sequence ESC[n;mH, where n and m are the row and column of the cursor, respectively. The string is then written to the standard output, a.k.a, the terminal GUI.
Now, we can update the main function to use the Renderer object and render the game state.
import (
"snake/terminal"
"snake/inputreader"
"snake/game"
"snake/renderer"
)
func main() {
t, err := terminal.New()
if err != nil {
panic(err)
}
defer t.Restore()
ir := inputreader.New()
g := game.New()
r := renderer.New()
for {
key := ir.Read()
if key == 'q' {
break
}
g.Update(key)
r.Render(g)
}
}
If you run your program, you will be able to move the cursor around the terminal using the WASD and arrow keys. However, you can notice several issues:
Let's solve these issues one by one.
This is the easiest issue to solve. In the Update method of the Game object, we can clamp the cursor position to the terminal's boundaries. For this, we will need to tell the game object the size of the terminal, or board, in this case. That information is stored in the Terminal object. So, let's add two new attributes to the Game object and update the New function to accept the number of columns and rows of the terminal.
type Game struct {
X int
Y int
NRows int
NCols int
}
func New(nRows, nCols int) *Game {
return &Game{X: 0, Y: 0, NRows: nRows, NCols: nCols}
}
In the main function, we can update the New function call to pass the number of columns and rows of the terminal.
g := game.New(t.NRows, t.NCols)
Now, we can update the Update method to clamp the cursor position to the terminal's boundaries.
func (g *Game) Update(key byte) {
switch key {
case 'w':
if g.Y > 0 {
g.Y--
}
case 's':
if g.Y < g.NRows-1 {
g.Y++
}
case 'a':
if g.X > 0 {
g.X--
}
case 'd':
if g.X < g.NCols-1 {
g.X++
}
}
}
If you run the program now, you should see that the cursor is clamped to the terminal's boundaries.
This issue is caused by the fact that we are not restoring the cursor position when the program exits. We can solve this issue by adding a new method to the Renderer object that will restore the cursor position to its original state.
To restore the terminal correctly, we will need to add the following escape sequences by order:
Let's create all these constants in the renderer module.
const (
clearScreen = "\x1b[2J"
cursorHide = "\x1b[?25l"
cursorShow = "\x1b[?25h"
cursorHome = "\x1b[H"
)
Now, we can create a new method called Restore that will restore the cursor position to its original state.
func (r *Renderer) Restore() {
outString := cursorHide
outString += clearScreen
outString += cursorHome
outString += cursorShow
os.Stdout.WriteString(outString)
}
Let's change the main function to call all the Restore methods when the program exits. For that, we will create a new function called atExit that will be called when the program exits.
func atExit(t *terminal.Terminal, r *renderer.Renderer) {
t.Restore()
r.Restore()
}
func main() {
t, err := terminal.New()
if err != nil {
panic(err)
}
ir := inputreader.New()
g := game.New(t.NRows, t.NCols)
r := renderer.New()
defer atExit(t, r)
for {
key := ir.Read()
if key == 'q' {
break
}
g.Update(key)
r.Render(g)
}
}
The program should now restore the cursor position when it exits.
The last issue is caused by the fact that we are rendering the game continuously. We can solve this issue by adding a game tick to the game loop. A game tick is a fundamental concept that allows you to control the flow and timing of game processes, ensuring that movement and other game mechanics are executed at a consistent rate, independent of the system's processing speed.
This can be achieved by using a time.Ticker from the time package. A ticker can be set to emit events at a fixed interval, which you can use to update game states such as cursor movement, input handling, and rendering.
import (
"time"
"snake/terminal"
"snake/inputreader"
"snake/game"
"snake/renderer"
)
Let's add the tick rate and the ticker to the main function.
tickRate := time.Second / 10
ticker := time.NewTicker(tickRate)
And update the atExit function to stop the ticker when the program exits.
func atExit(t *terminal.Terminal, r *renderer.Renderer, ticker *time.Ticker) {
t.Restore()
r.Restore()
ticker.Stop()
}
Now, we can update the game loop to use the ticker.
defer atExit(t, r, ticker)
for {
select {
case <-ticker.C:
key := ir.Read()
if key == 'q' {
return
}
g.Update(key)
r.Render(g)
}
}
Note that the break when the q key is pressed was replaced by a return statement. This is because we are using a select statement, which is used to wait for multiple channel operations. In this case, we are waiting for the ticker to emit an event.
We haven't still solved the issue of smooth movement. The problem is that, as we have the code now, the input of the user is read only when the ticker emits an event. This means that the user's input is only processed at a fixed interval, which is not what we want. We want the user's input to be processed as soon as it is received.
In Go, we can achieve this by using goroutines and channels. Goroutines are lightweight threads managed by the Go runtime, and channels are Go's way of allowing goroutines to communicate with each other safely.
The first thing we need to do is to update the Read method of the InputReader object to use and store the input in a channel.
func (ir *InputReader) Read(events chan byte) {
for {
for {
readLen, _ := os.Stdin.Read(ir.buffer)
if readLen > 0 {
break
}
}
if ir.buffer[0] == 27 {
seq := make([]byte, 2)
os.Stdin.Read(seq)
if seq[0] == 91 {
switch seq[1] {
case 65:
events <- 'w'
continue
case 66:
events <- 's'
continue
case 67:
events <- 'd'
continue
case 68:
events <- 'a'
continue
}
}
}
events <- ir.buffer[0]
}
}
Note that we have made several key changes to the method:
Now, in the main function, we can create a new channel and start a new goroutine to read the user's input. Additionally, we create a new variable called input to store the user's input.
events := make(chan byte)
go ir.Read(events)
var input byte
And we update the main loop.
for {
select {
case <-ticker.C:
r.Render(g)
g.Update(input)
case input = <-events:
if input == 'q' {
return
}
}
}
If you run the game, you should see that the cursor moves smoothly and that the user's input is processed as soon as it is received.
You should also see that the cursor moves continuously, even if the user doesn't press any key. This is because the pressed key is stored in the input variable and used in the next iteration of the game loop. However, if you press any other key, the cursor will stop, as in the switch statement of the Update method of the Game object, there is no case for that key. We will fix that soon.
It's time we add the snake to the game. The snake will be represented by a list of coordinates, and it will move continuously in the direction of the last key pressed. When the snake eats the food, it will grow by one unit. If the snake collides with the boundaries of the terminal or with itself, the game will end.
Let's create a new file called snake.go inside the game module and add a new struct called Snake to it.
package game
type Snake struct {
Body []Point
Dir Direction
}
Now, let's define the Point and Direction types in the game.go file.
type Point struct {
X int
Y int
}
type Direction int
const (
Up Direction = iota
Down
Left
Right
)
Let's create a function to create a new snake.
func NewSnake() *Snake {
head := Point{1, 0}
body := Point{0, 0}
return &Snake{
Body: []Point{body, head},
Dir: Right,
}
}
We initialize the snake to be two units long, with the head at the position (1, 0) and the body at the position (0, 0). The direction of the snake is set to Right.
And finally, let's update the Game object to store the snake, and remove the X and Y attributes, as they are no longer needed.
type Game struct {
NRows int
NCols int
Snake *Snake
}
func New(nRows, nCols int) *Game {
return &Game{
NRows: nRows,
NCols: nCols,
Snake: NewSnake(),
}
}
We will handle the movement of the snake in a new method called Move of the Snake object.
func (s *Snake) Move() {
head := s.Body[len(s.Body)-1]
var newHead Point
switch s.Dir {
case Up:
newHead = Point{head.X, head.Y - 1}
case Down:
newHead = Point{head.X, head.Y + 1}
case Left:
newHead = Point{head.X - 1, head.Y}
case Right:
newHead = Point{head.X + 1, head.Y}
}
s.Body = append(s.Body, newHead)
}
And in the Game object, we will update the Update method to move the snake in the direction of the last key pressed.
func (g *Game) Update(key byte) {
switch key {
case 'w':
g.Snake.Dir = Up
case 's':
g.Snake.Dir = Down
case 'a':
g.Snake.Dir = Left
case 'd':
g.Snake.Dir = Right
}
g.Snake.Move()
}
With this, the snake will only grow on every iteration of the game loop. We will fix by adding a new method called Pop to the Snake object. This method will remove the first element of the snake's body, effectively making it move.
func (s *Snake) Pop() {
s.Body = s.Body[1:]
}
And we will update the Update method of the Game object to call the Pop method after the snake moves.
func (g *Game) Update(key byte) {
switch key {
case 'w':
g.Snake.Dir = Up
case 's':
g.Snake.Dir = Down
case 'a':
g.Snake.Dir = Left
case 'd':
g.Snake.Dir = Right
}
g.Snake.Move()
g.Snake.Pop()
}
Now, the snake will move continuously in the direction of the last key pressed.
We need to update the Render method of the Renderer object to render the snake to the terminal, instead of the cursor.
func (r *Renderer) Render(g *game.Game) {
strOut := clearScreen
for i, p := range g.Snake.Body {
if len(g.Snake.Body) - 1 == i {
strOut += fmt.Sprintf("\x1b[%d;%dHO", p.Y+1, p.X+1)
break
}
strOut += fmt.Sprintf("\x1b[%d;%dH@", p.Y+1, p.X+1)
}
strOut += cursorHide
os.Stdout.WriteString(strOut)
}
As we did previously with the cursor, we are using the escape sequence ESC[y;xH to move the cursor to the position (x, y). We are adding a @ . character to the position of the snake's body, and a O character to the position of the snake's head.
Remember that the terminal is one-indexed, so we need to add 1 to the position of the snake's body and head.
Now, if you run the game, you should be able to control the snake.
The last thing we need to do is to add the food to the game and handle the game over condition.
The food object will be represented by a single point, so we can reuse the Point type we created previously.
type Game struct {
NRows int
NCols int
Snake *Snake
Food Point
}
For placing the food, we will create a new method called spawnFood of the Game object. This method will generate a random position for the food and check if the position is not occupied by the snake. Let's import the math/rand module.
import (
"math/rand"
)
func (g *Game) spawnFood() {
x := rand.Intn(g.NCols)
y := rand.Intn(g.NRows)
g.Food = Point{x, y}
for _, p := range g.Snake.Body {
if p == g.Food {
g.spawnFood()
}
}
}
Note the beauty of recursion. If the food is placed in the same position as the snake, we call the spawnFood method again.
As the spawnFood method needs to know where the snake is, we will need to restructure the New function to call the spawnFood method after the snake is created.
func New(nRows, nCols int) *Game {
g := &Game{NRows: nRows, NCols: nCols}
g.Snake = NewSnake()
g.spawnFood()
return g
}
Lastly, we just simply update the condition of the Update function to check if the snake's head is in the same position as the food, right after the snake moves.
head := g.Snake.Body[len(g.Snake.Body)-1]
if head == g.Food {
g.spawnFood()
} else {
g.Snake.Pop()
}
If the snake's head is in the same position as the food, we call the spawnFood method again. Otherwise, we call the Pop method. This way, the snake will grow when it eats the food, as the Pop method is not called.
And we can render the food to the terminal adding the following line right after the snake is rendered.
strOut += fmt.Sprintf("\x1b[%d;%dH*", g.Food.Y+1, g.Food.X+1)
Now, if you run the game, you should be able to control the snake and eat the food.
The game over condition is simple. If the snake collides with the boundaries of the terminal or with itself, the game is over.
func (g *Game) GameOver() bool {
head := g.Snake.Body[len(g.Snake.Body)-1]
if head.X < 0 || head.X > g.NCols || head.Y < 0 || head.Y > g.NRows {
return true
}
for i, p := range g.Snake.Body {
if i == len(g.Snake.Body)-1 {
continue
}
if p == head {
return true
}
}
return false
}
And we will update the main loop to check if the game is over.
for {
select {
case <-ticker.C:
r.Render(g)
g.Update(input)
if g.GameOver() {
return
}
case input = <-events:
if input == 'q' {
return
}
}
}
Now, if you run the game, you should see that the game is over when the snake collides with the boundaries of the terminal or with itself. This, effectively, concludes our game.
In this tutorial, we have created a simple snake game using the terminal. We have learned how to store and restore the terminal attributes, read the user's input, move the cursor, and render the game state to the terminal. We have also learned how to use goroutines and channels to handle non-blocking input, and how to use a game tick to control the flow and timing of game processes.
I suggest you continue to improve the game by adding more features, such as:
I hope you have learned how versatile the terminal can be and how easy it is to create a simple game using it. I encourage you to experiment and see if you can create more complex games.