crt

README

crt — cathode-ray tube

About

CRT is a library to provide a simple terminal emulator that can be attached to a tea.Program. It uses ebitengine to render a terminal. It supports TrueColor, Mouse and Keyboard input. It interprets the CSI escape sequences coming from bubbletea and renders them to the terminal.

This started as a simple proof of concept for the game I'm writing with the help of bubbletea, called End Of Eden. I wanted to give people who have no clue about the terminal a simple option to play the game without interacting with the terminal directly. It's also possible to apply shaders to the terminal to give it a more retro look which is a nice side effect.

Usage

go get github.com/BigJk/crt@latest

package main

import (
	"github.com/BigJk/crt"
	bubbleadapter "github.com/BigJk/crt/bubbletea"
	tea "github.com/charmbracelet/bubbletea"
	"github.com/charmbracelet/lipgloss"
	"image/color"
)

// Some tea.Model ...

func main() {
	// Load fonts for normal, bold and italic text styles.
	fonts, err := crt.LoadFaces("./fonts/SomeFont-Regular.ttf", "./fonts/SomeFont-Bold.ttf", "./fonts/SomeFont-Italic.ttf", 72.0, 16.0)
	if err != nil {
		panic(err)
	}

	// Just pass your tea.Model to the bubbleadapter, and it will render it to the terminal.
	win, err := bubbleadapter.Window(1000, 600, fonts, someModel{}, color.Black, tea.WithAltScreen())
	if err != nil {
		panic(err)
	}

	// Star the terminal with the given title.
	if err := win.Run("Simple"); err != nil {
		panic(err)
	}
}

Limitations

• Only supports TrueColor at the moment (no 256 color support) so you need to use TrueColor colors in lipgloss (e.g. lipgloss.Color("#ff0000"))
• Not all CSI escape sequences are implemented but the ones that are used by bubbletea are implemented
• A lot of testing still needs to be done and there are probably edge cases that are not handled correctly yet

Credits

• Basic CRT Shader ./shader/crt_basic: https://quasilyte.dev/blog/post/ebitengine-shaders/
• Lottes CRT Shader ./shader/crt_lotte: Elias Daler https://github.com/eliasdaler/crten and Timothy Lottes.

Documentation

Index

• func LoadFace(file string, dpi float64, size float64) (font.Face, error)
• func LoadFaceBytes(file []byte, dpi float64, size float64) (font.Face, error)
• func SysKill()
• type ChangeScrollingRegionSeq
• type ConcurrentRW
  • func NewConcurrentRW() *ConcurrentRW
  • func (rw *ConcurrentRW) Read(p []byte) (n int, err error)
  • func (rw *ConcurrentRW) Run()
  • func (rw *ConcurrentRW) Write(p []byte) (n int, err error)
• type CursorBackSeq
• type CursorDownSeq
• type CursorForwardSeq
• type CursorHorizontalSeq
• type CursorNextLineSeq
• type CursorPositionSeq
• type CursorPreviousLineSeq
• type CursorUpSeq
• type DeleteLineSeq
• type EmptyAdapter
  • func NewEmptyAdapter() *EmptyAdapter
  • func (e *EmptyAdapter) HandleKeyPress()
  • func (e *EmptyAdapter) HandleMouseButton(button MouseButton)
  • func (e *EmptyAdapter) HandleMouseMotion(motion MouseMotion)
  • func (e *EmptyAdapter) HandleMouseWheel(wheel MouseWheel)
  • func (e *EmptyAdapter) HandleWindowSize(size WindowSize)
• type EraseDisplaySeq
• type EraseLineSeq
• type FontWeight
• type Fonts
  • func LoadFaces(normal string, bold string, italic string, dpi float64, size float64) (Fonts, error)
  • func LoadFacesBytes(normal []byte, bold []byte, italic []byte, dpi float64, size float64) (Fonts, error)
• type GridCell
• type InputAdapter
• type InsertLineSeq
• type KeyPress
• type MouseButton
• type MouseMotion
• type MouseWheel
• type RestoreCursorPositionSeq
• type SGRBgTrueColor
• type SGRBold
• type SGRFgTrueColor
• type SGRItalic
• type SGRReset
• type SGRUnsetBold
• type SGRUnsetItalic
• type SaveCursorPositionSeq
• type ScrollDownSeq
• type ScrollUpSeq
• type Window
  • func NewGame(width int, height int, fonts Fonts, tty io.Reader, adapter InputAdapter, ...) (*Window, error)
  • func (g *Window) Draw(screen *ebiten.Image)
  • func (g *Window) Kill()
  • func (g *Window) Layout(outsideWidth, outsideHeight int) (int, int)
  • func (g *Window) PrintChar(r rune, fg, bg color.Color, weight FontWeight)
  • func (g *Window) RecalculateBackgrounds()
  • func (g *Window) ResetSGR()
  • func (g *Window) Run(title string) error
  • func (g *Window) SetBgPixels(x, y int, c color.Color)
  • func (g *Window) SetShader(shader ...shader.Shader)
  • func (g *Window) ShowTPS(val bool)
  • func (g *Window) Update() error
• type WindowSize

Functions

func LoadFace

func LoadFace(file string, dpi float64, size float64) (font.Face, error)

LoadFace loads a font face from a file. The dpi and size are used to generate the font face. Supports ttf and otf.

Example: LoadFace("./fonts/Mono-Regular.ttf", 72.0, 16.0)

func LoadFaceBytes

func LoadFaceBytes(file []byte, dpi float64, size float64) (font.Face, error)

LoadFaceBytes loads a font face from bytes. The dpi and size are used to generate the font face. The normal, bold, and italic files must be provided. Supports ttf and otf.

func SysKill

func SysKill()

Types

type ChangeScrollingRegionSeq

type ChangeScrollingRegionSeq struct {
	Top    int
	Bottom int
}

type ConcurrentRW

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

ConcurrentRW is a concurrent read/write buffer via channels.

func NewConcurrentRW

func NewConcurrentRW() *ConcurrentRW

NewConcurrentRW creates a new concurrent read/write buffer.

func (*ConcurrentRW) Read

func (rw *ConcurrentRW) Read(p []byte) (n int, err error)

Read reads data from the buffer.

func (*ConcurrentRW) Run

func (rw *ConcurrentRW) Run()

Run starts the concurrent read/write buffer.

func (*ConcurrentRW) Write

func (rw *ConcurrentRW) Write(p []byte) (n int, err error)

Write writes data to the buffer.

type CursorBackSeq

type CursorBackSeq struct {
	Count int
}

type CursorDownSeq

type CursorDownSeq struct {
	Count int
}

type CursorForwardSeq

type CursorForwardSeq struct {
	Count int
}

type CursorHorizontalSeq

type CursorHorizontalSeq struct {
	Count int
}

type CursorNextLineSeq

type CursorNextLineSeq struct {
	Count int
}

type CursorPositionSeq

type CursorPositionSeq struct {
	Row int
	Col int
}

type CursorPreviousLineSeq

type CursorPreviousLineSeq struct {
	Count int
}

type CursorUpSeq

type CursorUpSeq struct {
	Count int
}

type DeleteLineSeq

type DeleteLineSeq struct {
	Count int
}

type EmptyAdapter

type EmptyAdapter struct{}

func NewEmptyAdapter

func NewEmptyAdapter() *EmptyAdapter

func (*EmptyAdapter) HandleKeyPress

func (e *EmptyAdapter) HandleKeyPress()

func (*EmptyAdapter) HandleMouseButton

func (e *EmptyAdapter) HandleMouseButton(button MouseButton)

func (*EmptyAdapter) HandleMouseMotion

func (e *EmptyAdapter) HandleMouseMotion(motion MouseMotion)

func (*EmptyAdapter) HandleMouseWheel

func (e *EmptyAdapter) HandleMouseWheel(wheel MouseWheel)

func (*EmptyAdapter) HandleWindowSize

func (e *EmptyAdapter) HandleWindowSize(size WindowSize)

type EraseDisplaySeq

type EraseDisplaySeq struct {
	Type int
}

type EraseLineSeq

type EraseLineSeq struct {
	Type int
}

type FontWeight

type FontWeight byte

FontWeight is the weight of a font at a certain terminal cell.

const (
	// FontWeightNormal is the default font weight.
	FontWeightNormal FontWeight = iota

	// FontWeightBold is a bold font weight.
	FontWeightBold

	// FontWeightItalic is an italic font weight.
	FontWeightItalic
)

type Fonts

type Fonts struct {
	Normal font.Face
	Bold   font.Face
	Italic font.Face
}

func LoadFaces

func LoadFaces(normal string, bold string, italic string, dpi float64, size float64) (Fonts, error)

LoadFaces loads a set of fonts from files. The normal, bold, and italic files must be provided. The dpi and size are used to generate the font faces. Supports ttf and otf.

func LoadFacesBytes

func LoadFacesBytes(normal []byte, bold []byte, italic []byte, dpi float64, size float64) (Fonts, error)

LoadFacesBytes loads a set of fonts from bytes. The normal, bold, and italic files must be provided. The dpi and size are used to generate the font faces. Supports ttf and otf.

type GridCell

type GridCell struct {
	Char   rune
	Fg     color.Color
	Bg     color.Color
	Weight FontWeight
}

GridCell is a single cell in the terminal grid.

type InputAdapter

type InputAdapter interface {
	HandleMouseButton(button MouseButton)
	HandleMouseMotion(motion MouseMotion)
	HandleMouseWheel(wheel MouseWheel)
	HandleKeyPress()
	HandleWindowSize(size WindowSize)
}

type InsertLineSeq

type InsertLineSeq struct {
	Count int
}

type KeyPress

type KeyPress struct {
	Key   ebiten.Key
	Runes []rune
	Shift bool
	Alt   bool
	Ctrl  bool
}

type MouseButton

type MouseButton struct {
	Button       ebiten.MouseButton
	X            int
	Y            int
	Shift        bool
	Alt          bool
	Ctrl         bool
	JustPressed  bool
	JustReleased bool
}

type MouseMotion

type MouseMotion struct {
	X int
	Y int
}

type MouseWheel

type MouseWheel struct {
	X     int
	Y     int
	DX    float64
	DY    float64
	Shift bool
	Alt   bool
	Ctrl  bool
}

type RestoreCursorPositionSeq

type RestoreCursorPositionSeq struct{}

type SGRBgTrueColor

type SGRBgTrueColor struct {
	R, G, B byte
}

type SGRBold

type SGRBold struct{}

type SGRFgTrueColor

type SGRFgTrueColor struct {
	R, G, B byte
}

type SGRItalic

type SGRItalic struct{}

type SGRReset

type SGRReset struct{}

type SGRUnsetBold

type SGRUnsetBold struct{}

type SGRUnsetItalic

type SGRUnsetItalic struct{}

type SaveCursorPositionSeq

type SaveCursorPositionSeq struct{}

type ScrollDownSeq

type ScrollDownSeq struct {
	Count int
}

type ScrollUpSeq

type ScrollUpSeq struct {
	Count int
}

type Window

type Window struct {
	sync.Mutex
	// contains filtered or unexported fields
}

func NewGame

func NewGame(width int, height int, fonts Fonts, tty io.Reader, adapter InputAdapter, defaultBg color.Color) (*Window, error)

NewGame creates a new terminal game with the given dimensions and font faces.

func (*Window) Draw

func (g *Window) Draw(screen *ebiten.Image)

func (*Window) Kill

func (g *Window) Kill()

func (*Window) Layout

func (g *Window) Layout(outsideWidth, outsideHeight int) (int, int)

func (*Window) PrintChar

func (g *Window) PrintChar(r rune, fg, bg color.Color, weight FontWeight)

PrintChar prints a character to the screen.

func (*Window) RecalculateBackgrounds

func (g *Window) RecalculateBackgrounds()

RecalculateBackgrounds syncs the background colors to the background pixels.

func (*Window) ResetSGR

func (g *Window) ResetSGR()

ResetSGR resets the SGR attributes to their default values.

func (*Window) Run

func (g *Window) Run(title string) error

func (*Window) SetBgPixels

func (g *Window) SetBgPixels(x, y int, c color.Color)

SetBgPixels sets a chunk of background pixels in the size of the cell.

func (*Window) SetShader

func (g *Window) SetShader(shader ...shader.Shader)

SetShader sets a shader that is applied to the whole screen.

func (*Window) ShowTPS

func (g *Window) ShowTPS(val bool)

ShowTPS enables or disables the TPS counter on the top left.

func (*Window) Update

func (g *Window) Update() error

type WindowSize

type WindowSize struct {
	Width  int
	Height int
}