termloop

Termloop is a pure Go game engine for the terminal built on top of Termbox. It provides a render loop designed to make terminal game development easy.

Key features include:

• Input Handling: Support for keyboard and mouse input.
• Game Mechanics: Collision detection and level offsets to simulate 'camera' movement.
• Rendering: Render timers and an optional 'pixel mode' (which draws two 'pixels' to a single terminal character to double screen height, though text rendering is disabled in this mode).
• Built-in Entities: Framerate counters, Rectangles, and Text.
• Data Loading: Support for loading entities from ASCII art, color maps from images, and level maps from JSON.
• Portability: Being pure Go, it allows for easy portability and built-in cross-compilation.

Termloop provides two interfaces for handling collisions:

1. Physical: Represents an object that can be collided with. It must implement Position() (int, int) and Size() (int, int). Use this for static objects like walls or lakes.
2. DynamicPhysical: Represents an object that can actively process its own collisions. It implements Physical and adds the Collide(Physical) method. Use this for moving objects like players that need to react to hitting something.

Best Practice: For performance, use Physical for as many objects as possible and reserve DynamicPhysical only for objects that require active logic (like the player).

The termloop/extra package provides functionality that requires external dependencies, meaning using them may prevent your binary from being fully portable.

To use the audio playback features, you must have the following requirements installed on your system:

• PortAudio
• libsndfile

To create custom game objects, you should use object composition by embedding *tl.Entity into your own struct. To make your struct renderable and interactive, you must implement the Drawable interface by providing two methods:

• Draw(screen *tl.Screen): Defines how the entity is drawn to the screen. If you override this, ensure you call the underlying entity's Draw method to maintain standard rendering.
• Tick(event tl.Event): Handles input and logic updates. You can check event.Type == tl.EventKey to process keyboard input using constants like tl.KeyArrowRight.

type Player struct {
	*tl.Entity
}

func (player *Player) Tick(event tl.Event) {
	if event.Type == tl.EventKey {
		x, y := player.Position()
		switch event.Key {
		case tl.KeyArrowRight:
			player.SetPosition(x+1, y)
		// ... other keys
		}
	}
}

To initialize a basic Termloop game, create a new game instance using tl.NewGame() and call .Start() to begin the game loop. This provides a blank terminal screen.

package main

import tl "github.com/JoelOtter/termloop"

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

Termloop does not have a dedicated camera object. Instead, 'scrolling' is achieved by setting an offset on the Level. To keep a player centered, you can override the player's Draw method to calculate the required offset based on the screen size and the player's position, then call level.SetOffset(x, y).

func (player *Player) Draw(screen *tl.Screen) {
	screenWidth, screenHeight := screen.Size()
	x, y := player.Position()
	player.level.SetOffset(screenWidth/2-x, screenHeight/2-y)
	// Ensure the underlying Entity is still drawn
	player.Entity.Draw(screen)
}

To install or update Termloop in your Go project, use the following command:

go get -u github.com/JoelOtter/termloop

The click.go example shows how to implement mouse click detection, allowing users to interact with entities (like rectangles) by clicking on them.

go run click.go

The movingtext.go example demonstrates how to handle keyboard input and utilize the Text builtin to render strings to the terminal.

go run movingtext.go "Some text here"