termloop

package module
v0.0.0-...-1f74208 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 5, 2023 License: MIT Imports: 13 Imported by: 0

README

Termloop

GoDoc

Termloop is a pure Go game engine for the terminal, built on top of the excellent Termbox. It provides a simple render loop for building games in the terminal, and is focused on making terminal game development as easy and as fun as possible.

Termloop is still under active development so changes may be breaking. I add any breaking changes to the Changelog - hopefully at this stage there shouldn't be too many. Pull requests and issues are very welcome, and do feel free to ask any questions you might have on the Gitter. I hope you enjoy using Termloop; I've had a blast making it.

Installing

Install and update with go get -u github.com/JoelOtter/termloop

Features

  • Keyboard and mouse input
  • Collision detection
  • Render timers
  • Level offsets to simulate 'camera' movement
  • Debug logging
  • Built-in entity types such as:
  • Framerate counters
  • Rectangles
  • Text
  • Loading entities from ASCII art
  • Loading colour maps from images
  • Loading level maps from JSON
  • Optional 'pixel mode' - draw two 'pixels' to a terminal character, doubling screen height at the expense of being able to render text.
  • Pure Go - easy portability of compiled games, and cross-compilation built right in.

To see what's on the roadmap, have a look at the issue tracker.

termloop/extra

The Termloop extras are a collection of types and functions, the use of which will not result in a fully portable binary - that is, they have some external dependencies. However, if you're willing to require these dependencies in your project, they should integrate quite nicely with the rest of Termloop. Some of the included examples use these extras.

  • Audio playback
  • audio.go
  • Requirements: PortAudio and libsndfile

Cool stuff built with Termloop

Feel free to add yours with a pull request!

Tutorial

More full documentation will be added to the Wiki soon. In the meantime, check out this tutorial, the GoDoc, or the included examples. If you get stuck during this tutorial, worry not, the full source is here.

Creating a blank Termloop game is as simple as:

package main

import tl "github.com/JoelOtter/termloop"

func main() {
	game := tl.NewGame()
	game.Start()
}

We can press Ctrl+C to exit. It's just a blank screen - let's make it a little more interesting.

Let's make a green background, because grass is really nice to run around on. We create a new level like so:

level := tl.NewBaseLevel(tl.Cell{
	Bg: tl.ColorGreen,
	Fg: tl.ColorBlack,
	Ch: 'v',
})

Cell is a struct that represents one cell on the terminal. We can set its background and foreground colours, and the character that is displayed. Creating a BaseLevel in this way will fill the level with this Cell.

Let's make a nice pretty lake, too. We'll use a Rectangle for this. We'll put the lake at position (10, 10), with width 50 and height 20. All measurements are in terminal characters! The last argument is the colour of the Rectangle.

level.AddEntity(tl.NewRectangle(10, 10, 50, 20, tl.ColorBlue))

We don't need to use a Level - we can add entities directly to the Screen! This is great for building a HUD, or a very simple app. However, if we want camera scrolling or collision detection, we're going to need to use a Level.

Putting together what we have so far:

package main

import tl "github.com/JoelOtter/termloop"

func main() {
	game := tl.NewGame()
	level := tl.NewBaseLevel(tl.Cell{
		Bg: tl.ColorGreen,
		Fg: tl.ColorBlack,
		Ch: 'v',
	})
	level.AddEntity(tl.NewRectangle(10, 10, 50, 20, tl.ColorBlue))
	game.Screen().SetLevel(level)
	game.Start()
}

When we run it with go run tutorial.go, it looks like this:

Pretty! Ish. OK, let's create a character that can walk around the environment. We're going to use object composition here - we'll create a new struct type, which extends an Entity.

To have Termloop draw our new type, we need to implement the Drawable interface, which means we need two methods: Draw() and Tick(). The Draw method defines how our type is drawn to the Screen (Termloop's internal drawing surface), and the Tick method defines how we handle input.

We don't need to do anything special for Draw, and it's already handled by Entity, so we just need a Tick:

type Player struct {
	*tl.Entity
}

func (player *Player) Tick(event tl.Event) {
	if event.Type == tl.EventKey { // Is it a keyboard event?
		x, y := player.Position()
		switch event.Key { // If so, switch on the pressed key.
		case tl.KeyArrowRight:
			player.SetPosition(x+1, y)
		case tl.KeyArrowLeft:
			player.SetPosition(x-1, y)
		case tl.KeyArrowUp:
			player.SetPosition(x, y-1)
		case tl.KeyArrowDown:
			player.SetPosition(x, y+1)
		}
	}
}

Now that we've built our Player type, let's add one to the level. I'm going to use the character '옷', because I think it looks a bit like a stick man.

player := Player{tl.NewEntity(1, 1, 1, 1)}
// Set the character at position (0, 0) on the entity.
player.SetCell(0, 0, &tl.Cell{Fg: tl.ColorRed, Ch: '옷'})
level.AddEntity(&player)

Running the game again, we see that we can now move around the map using the arrow keys. Neato! However, we can stroll across the lake just as easily as the grass. Our character isn't the Messiah, he's a very naughty boy, so let's add some collisions.

In Termloop, we have two interfaces that are used for collisions. Here they are.

// Physical represents something that can collide with another
// Physical, but cannot process its own collisions.
// Optional addition to Drawable.
type Physical interface {
	Position() (int, int) // Return position, x and y
	Size() (int, int)     // Return width and height
}

// DynamicPhysical represents something that can process its own collisions.
// Implementing this is an optional addition to Drawable.
type DynamicPhysical interface {
	Position() (int, int) // Return position, x and y
	Size() (int, int)     // Return width and height
	Collide(Physical)     // Handle collisions with another Physical
}

It's pretty simple - if we want our object to be 'solid', then we implement Physical. If we want a solid object that actually does some processing on its own collisions, we implement DynamicPhysical! Essentially this just involves adding one more method to your type.

Note that, for performance reasons, you should try and have as few DynamicPhysicals as possible - for example, our Player will be one, but the lake need only be a Physical.

The Rectangle type already implements Physical, so we don't actually need to do anything. As well, Player already implements DynamicPhysical because of the embedded Entity. However, we want custom behaviour for Collide, so let's implement that method. For that, we'll have to modify our struct and Tick method, to keep track of the Player's previous position so we can move it back there if it collides with something.

type Player struct {
	*tl.Entity
	prevX  int
	prevY  int
}

func (player *Player) Tick(event tl.Event) {
	if event.Type == tl.EventKey { // Is it a keyboard event?
		player.prevX, player.prevY = player.Position()
		switch event.Key { // If so, switch on the pressed key.
		case tl.KeyArrowRight:
			player.SetPosition(player.prevX+1, player.prevY)
		case tl.KeyArrowLeft:
			player.SetPosition(player.prevX-1, player.prevY)
		case tl.KeyArrowUp:
			player.SetPosition(player.prevX, player.prevY-1)
		case tl.KeyArrowDown:
			player.SetPosition(player.prevX, player.prevY+1)
		}
	}
}

func (player *Player) Collide(collision tl.Physical) {
	// Check if it's a Rectangle we're colliding with
	if _, ok := collision.(*tl.Rectangle); ok {
		player.SetPosition(player.prevX, player.prevY)
	}
}

Not too much extra code! We can now see that the Player can't walk out into the lake. If you see the Player overlap the lake slightly on one side, that's likely because the 'stick man' character we used isn't quite standard width.

We've now got something that looks a bit like a very simple exploration game. There's one more thing to add - let's have the camera scroll to keep the Player in the centre of the screen!

There isn't really a 'camera' in Termloop, like you might find in another graphics library. Instead, we set an offset, and the Screen draws our level appropriately. In our case it's really simple - all we need is for the Player to have a pointer to the Level, so we can make calls on it. Then we simply modify our Draw method, like so:

type Player struct {
	*tl.Entity
	prevX  int
	prevY  int
	level  *tl.BaseLevel
}

func (player *Player) Draw(screen *tl.Screen) {
	screenWidth, screenHeight := screen.Size()
	x, y := player.Position()
	player.level.SetOffset(screenWidth/2-x, screenHeight/2-y)
  // We need to make sure and call Draw on the underlying Entity.
	player.Entity.Draw(screen)
}


// in func main
player := Player{
	Entity:   tl.NewEntity(1, 1, 1, 1),
	level: level,
}

That's all it takes. We should now see the camera moving. Of course, due to the static, repeating background, this doesn't look terribly convincing - it kind of looks like the player is standing still and everything else is moving! We could remedy this by, for example, only updating the offset when the player is closer to the edge of the screen. I'll leave it up to you as a challenge.

We've now reached the end of our tutorial - I hope it's been useful! If you'd like to learn a little more about Termloop, more comprehensive documentation is coming on the Wiki. In the meantime, you can check out the GoDoc, or the included examples. I'll be hanging out on the Gitter too, if you have any questions. Have fun, and please do show me if you make something cool!

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CellsEqual 

func CellsEqual(c1 *tb.Cell, c2 *tb.Cell) bool

func LoadLevelFromMap 

func LoadLevelFromMap(jsonMap string, parsers map[string]EntityParser, l Level) error

LoadLevelFromMap can be used to populate a Level with entities, given a JSON string to read from (jsonMap).

The map 'parsers' is a map of entity names to EntityParser functions. This can be used to define parsers for objects that are not Termloop builtins.

The JSON string should take the format of an array of objects, like so: [ {"type": "Rectangle", "data": {"x: 12 ...}}, ... ] For Rectangles and Text, all attributes must be defined in the JSON. For an Entity, fg and bg can be left as empty strings if you do not wish to color the Entity with an image, but the keys must still be present or the parsing will break.

There is an example of how to use this method at _examples/levelmap.go.

LoadLevelFromMap returns an error, or nil if all is well.

func RgbTo256Color 

func RgbTo256Color(r, g, b int) tb.Attribute

RgbTo256Color takes RGB values and returns the closest color for a 256-color terminal, as an Attr type.

Types

type BaseLevel 

type BaseLevel struct {
	Entities []Drawable
	// contains filtered or unexported fields
}

BaseLevel type represents a Level with a background defined as a Cell, which is tiled. The background is drawn first, then all Entities.

func NewBaseLevel 

func NewBaseLevel(bg tb.Cell) *BaseLevel

NewBaseLevel creates a new BaseLevel with background bg. Returns a pointer to the new BaseLevel.

func (*BaseLevel) AddEntity 

func (l *BaseLevel) AddEntity(d Drawable)

AddEntity adds Drawable d to the level's entities.

func (*BaseLevel) Draw 

func (l *BaseLevel) Draw(s *Screen)

Draw draws the level's entities to the Screen s.

func (*BaseLevel) DrawBackground 

func (l *BaseLevel) DrawBackground(s *Screen)

DrawBackground draws the background Cell bg to each Cell of the Screen s.

func (*BaseLevel) Offset 

func (l *BaseLevel) Offset() (int, int)

Offset returns the level's drawing offset.

func (*BaseLevel) RemoveEntity 

func (l *BaseLevel) RemoveEntity(d Drawable)

RemoveEntity removes Drawable d from the level's entities.

func (*BaseLevel) SetOffset 

func (l *BaseLevel) SetOffset(x, y int)

SetOffset sets the level's drawing offset to be (x, y). The drawing offset can be used to simulate moving the level, or moving the 'camera'.

func (*BaseLevel) Tick 

func (l *BaseLevel) Tick(ev tb.Event)

Tick handles any collisions between Physicals in the level's entities, and processes any input.

type Canvas 

type Canvas [][]tb.Cell

A Canvas is a 2D array of Cells, used for drawing. The structure of a Canvas is an array of columns. This is so it can be addressed canvas[x][y].

func BackgroundCanvasFromFile 

func BackgroundCanvasFromFile(filename string) *Canvas

BackgroundCanvasFromFile takes a path to an image file, and creates a canvas of background-only Cells representing the image. This can be applied to an Entity with ApplyCanvas.

func CanvasFromString 

func CanvasFromString(str string) Canvas

CanvasFromString returns a new Canvas, built from the characters in the string str. Newline characters in the string are interpreted as a new Canvas row.

func ForegroundCanvasFromFile 

func ForegroundCanvasFromFile(filename string) *Canvas

ForegroundCanvasFromFile takes a path to an image file, and creates a canvas of foreground-only Cells representing the image. This can be applied to an Entity with ApplyCanvas.

func NewCanvas 

func NewCanvas(width, height int) Canvas

NewCanvas returns a new Canvas, with width and height defined by arguments.

type Drawable 

type Drawable interface {
	Tick(tb.Event) // Method for processing events, e.g. input
	Draw(*Screen)  // Method for drawing to the screen
}

Drawable represents something that can be drawn, and placed in a Level.

type DynamicPhysical 

type DynamicPhysical interface {
	Position() (int, int) // Return position, x and y
	Size() (int, int)     // Return width and height
	Collide(Physical)     // Handle collisions with another Physical
}

DynamicPhysical represents something that can process its own collisions. Implementing this is an optional addition to Drawable.

type Entity 

type Entity struct {
	// contains filtered or unexported fields
}

Entity provides a general Drawable to be rendered.

func NewEntity 

func NewEntity(x, y, width, height int) *Entity

NewEntity creates a new Entity, with position (x, y) and size (width, height). Returns a pointer to the new Entity.

func NewEntityFromCanvas 

func NewEntityFromCanvas(x, y int, c Canvas) *Entity

NewEntityFromCanvas returns a pointer to a new Entity, with position (x, y) and Canvas c. Width and height are calculated using the Canvas.

func (*Entity) ApplyCanvas 

func (e *Entity) ApplyCanvas(c *Canvas)

ApplyCanvas takes a pointer to a Canvas, c, and applies this canvas over the top of the Entity's canvas. Any new values in c will overwrite those in the entity.

func (*Entity) Draw 

func (e *Entity) Draw(s *Screen)

Draw draws the entity to its current position on the screen. This is usually called every frame.

func (*Entity) Fill 

func (e *Entity) Fill(c *tb.Cell)

Fill fills the canvas of the Entity with a Cell c.

func (*Entity) Position 

func (e *Entity) Position() (int, int)

Position returns the (x, y) coordinates of the Entity.

func (*Entity) SetCanvas 

func (e *Entity) SetCanvas(c *Canvas)

SetCanvas takes a pointer to a Canvas and replaces the Entity's canvas with the pointer's. It also updates the Entity's dimensions.

func (*Entity) SetCell 

func (e *Entity) SetCell(x, y int, c *tb.Cell)

SetCell updates the attribute of the Cell at x, y to match those of c. The coordinates are relative to the entity itself, not the Screen.

func (*Entity) SetPosition 

func (e *Entity) SetPosition(x, y int)

SetPosition sets the x and y coordinates of the Entity.

func (*Entity) Size 

func (e *Entity) Size() (int, int)

Size returns the width and height of the entity, in characters.

func (*Entity) Tick 

func (e *Entity) Tick(ev tb.Event)

Tick needs to be implemented to satisfy the Drawable interface. It updates the Entity based on the Screen's FPS

type EntityParser 

type EntityParser func(map[string]interface{}) Drawable

An EntityParser is a function which composes an object from data that has been parsed from a JSON file. Returns a Drawable

type FpsText 

type FpsText struct {
	*Text
	// contains filtered or unexported fields
}

FpsText provides a Text which updates with the current 'framerate' at specified intervals, to be used for testing performance. Please note that the framerate displayed is a measure of Termloop's processing speed - visible framerate is largely dependent on your terminal!

func NewFpsText 

func NewFpsText(x, y int, fg, bg tb.Attribute, update float64) *FpsText

NewFpsText creates a new FpsText at position (x, y) and with background and foreground colors fg and bg respectively. It will refresh every 'update' seconds. Returns a pointer to the new FpsText.

func (*FpsText) Draw 

func (f *FpsText) Draw(s *Screen)

Draw updates the framerate on the FpsText and draws it to the Screen s.

type Game 

type Game struct {
	// contains filtered or unexported fields
}

Represents a top-level Termloop application.

func NewGame 

func NewGame() *Game

NewGame creates a new Game, along with a Screen and input handler. Returns a pointer to the new Game.

func (*Game) DebugOn 

func (g *Game) DebugOn() bool

DebugOn returns a bool showing whether or not debug mode is on.

func (*Game) Log 

func (g *Game) Log(log string, items ...interface{})

Log takes a log string and additional parameters, which can be substituted into the string using standard fmt.Printf rules. The formatted string is added to Game g's logs. If debug mode is on, the log will be printed to the terminal when Termloop exits.

func (*Game) Screen 

func (g *Game) Screen() *Screen

Screen returns the current Screen of a Game.

func (*Game) SetDebugOn 

func (g *Game) SetDebugOn(debugOn bool)

SetDebugOn sets debug mode's on status to be debugOn.

func (*Game) SetEndKey 

func (g *Game) SetEndKey(key tb.Key)

SetEndKey sets the Key used to end the game. Default is KeyCtrlC. If you don't want an end key, set it to KeyEsc, as this key isn't supported and will do nothing. (We recommend always having an end key for development/testing.)

func (*Game) SetScreen 

func (g *Game) SetScreen(s *Screen)

SetScreen sets the current Screen of a Game.

func (*Game) Start 

func (g *Game) Start()

Start starts a Game running. This should be the last thing called in your main function. By default, the escape key exits.

type Level 

type Level interface {
	DrawBackground(*Screen)
	AddEntity(Drawable)
	RemoveEntity(Drawable)
	Draw(*Screen)
	Tick(tb.Event)
}

Level interface represents a Drawable with a separate background that is drawn first. It can also contain Drawables of its own.

type Physical 

type Physical interface {
	Position() (int, int) // Return position, x and y
	Size() (int, int)     // Return width and height
}

Physical represents something that can collide with another Physical, but cannot process its own collisions. Optional addition to Drawable.

type Rectangle 

type Rectangle struct {
	// contains filtered or unexported fields
}

A type representing a 2D rectangle, with position, size and color.

func NewRectangle 

func NewRectangle(x, y, w, h int, color tb.Attribute) *Rectangle

NewRectangle creates a new Rectangle at position (x, y), with size (width, height) and color color. Returns a pointer to the new Rectangle.

func (*Rectangle) Color 

func (r *Rectangle) Color() tb.Attribute

Color returns the color of the Rectangle.

func (*Rectangle) Draw 

func (r *Rectangle) Draw(s *Screen)

Draws the Rectangle r onto Screen s.

func (*Rectangle) Position 

func (r *Rectangle) Position() (int, int)

Position returns the x and y coordinates of the Rectangle.

func (*Rectangle) SetColor 

func (r *Rectangle) SetColor(color tb.Attribute)

SetColor sets the color of the Rectangle.

func (*Rectangle) SetPosition 

func (r *Rectangle) SetPosition(x, y int)

SetPosition sets the coordinates of the Rectangle to be x and y.

func (*Rectangle) SetSize 

func (r *Rectangle) SetSize(w, h int)

SetSize sets the width and height of the Rectangle to be w and h.

func (*Rectangle) Size 

func (r *Rectangle) Size() (int, int)

Size returns the width and height in characters of the Rectangle.

func (*Rectangle) Tick 

func (r *Rectangle) Tick(ev tb.Event)

type Screen 

type Screen struct {
	Entities []Drawable
	// contains filtered or unexported fields
}

A Screen represents the current state of the display. To draw on the screen, create Drawables and set their positions. Then, add them to the Screen's Level, or to the Screen directly (e.g. a HUD).

func NewScreen 

func NewScreen() *Screen

NewScreen creates a new Screen, with no entities or level. Returns a pointer to the new Screen.

func (*Screen) AddEntity 

func (s *Screen) AddEntity(d Drawable)

AddEntity adds a Drawable to the current Screen, to be rendered.

func (*Screen) Draw 

func (s *Screen) Draw()

Draw is called every frame by the Game to render the current state of the screen.

func (*Screen) EnablePixelMode 

func (s *Screen) EnablePixelMode()

EnablePixelMode sets the screen to 'pixel mode' - giving double the canvas height while sacrificing character drawing ability.

func (*Screen) Level 

func (s *Screen) Level() Level

Level returns the Screen's current level.

func (*Screen) RemoveEntity 

func (s *Screen) RemoveEntity(d Drawable)

RemoveEntity removes Drawable d from the screen's entities.

func (*Screen) RenderCell 

func (s *Screen) RenderCell(x, y int, c *tb.Cell)

RenderCell updates the Cell at a given position on the Screen with the attributes in Cell c.

func (*Screen) SetFps 

func (s *Screen) SetFps(f float64)

Set the screen framerate. By default, termloop will draw the the screen as fast as possible, which may use a lot of system resources.

func (*Screen) SetLevel 

func (s *Screen) SetLevel(l Level)

SetLevel sets the Screen's current level to be l.

func (*Screen) Size 

func (s *Screen) Size() (int, int)

Size returns the width and height of the Screen in characters.

func (*Screen) Tick 

func (s *Screen) Tick(ev tb.Event)

Tick is used to process events such as input. It is called on every frame by the Game.

func (*Screen) TimeDelta 

func (s *Screen) TimeDelta() float64

TimeDelta returns the number of seconds since the previous frame was rendered. Can be used for timings and animation.

type Text 

type Text struct {
	// contains filtered or unexported fields
}

Text represents a string that can be drawn to the screen.

func NewText 

func NewText(x, y int, text string, fg, bg tb.Attribute) *Text

NewText creates a new Text, at position (x, y). It sets the Text's background and foreground colors to fg and bg respectively, and sets the Text's text to be text. Returns a pointer to the new Text.

func (*Text) Color 

func (t *Text) Color() (tb.Attribute, tb.Attribute)

Color returns the (foreground, background) colors of the Text.

func (*Text) Draw 

func (t *Text) Draw(s *Screen)

Draw draws the Text to the Screen s.

func (*Text) Position 

func (t *Text) Position() (int, int)

Position returns the (x, y) coordinates of the Text.

func (*Text) SetColor 

func (t *Text) SetColor(fg, bg tb.Attribute)

SetColor sets the (foreground, background) colors of the Text to fg, bg respectively.

func (*Text) SetPosition 

func (t *Text) SetPosition(x, y int)

SetPosition sets the coordinates of the Text to be (x, y).

func (*Text) SetText 

func (t *Text) SetText(text string)

SetText sets the text of the Text to be text.

func (*Text) Size 

func (t *Text) Size() (int, int)

Size returns the width and height of the Text.

func (*Text) Text 

func (t *Text) Text() string

Text returns the text of the Text.

func (*Text) Tick 

func (t *Text) Tick(ev tb.Event)

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.