runal

package module
v0.10.0 Latest Latest
Warning

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

 Go to latest Published: Nov 14, 2025 License: MIT Imports: 33 Imported by: 1

README

Runal

GitHub release (latest SemVer) GitHub Workflow Status

📓 User Manual

Runal is a text-based creative coding environment for the terminal. It works similarly as processing or p5js but it does all the rendering as text. It can either be programmed with JavaScript, or used as a Go package.

Runal is a work-in-progress. The API should not be considered as stable until it reaches 1.0.

Feel free to open an issue.

signls screenshot

Installation

Quick-install

On linux or macOS, you can run this quick-install bash script:

curl -sSL empr.cl/get/runal | bash
Packages
AUR

https://aur.archlinux.org/packages/runal

Manual installation
Linux & macOS

Download the last release for your platform.

Then:

# Extract files
mkdir -p runal && tar -zxvf runal_VERSION_PLATFORM.tar.gz -C runal
cd runal

# Run runal
./runal

# Run runal demo
./runal -demo
Windows

We recommend using Windows Terminal with a good monospace font like Iosevka to display Signls correctly on Windows.

Unzip the last windows release and, in the same directory, run:

; Run runal
.\runal.exe

; Run runal demo
.\runal.exe -demo
Build it yourself

You'll need go 1.23 minimum. Although you should be able to build it for either linux, macOS or Windows, it has only been tested on linux.

# Linux
make GOLANG_OS=linux build

# macOS
make GOLANG_OS=darwin build

# Windows
make GOLANG_OS=windows build

# Raspberry Pi OS
make GOLANG_OS=linux GOLANG_ARCH=arm64 build

Usage

JavaScript runtime

You can use JavaScript for scripting your sketch. Your js file should contain a setup and a draw method. Both methods take a single argument (here c) representing a canvas object that holds all the available primitives:

// sketch.js

function setup(c) {}

function draw(c) {}

You can add extra methods onKey, onMouseMove, onMouseClick, onMouseRelease and onMouseWheel to catch keyboard and mouse events:

function onKey(c, e) {}
function onMouseMove(c, e) {}
function onMouseClick(c, e) {}
function onMouseRelease(c, e) {}
function onMouseWheel(c, e) {}

And you can then execute the file with:

./runal -f sketch.js

The js file will be automatically reloaded when modified, no need to restart the command.

Standalone executable

You can create a standalone executable from the JavaScript file specified with -f using -o [FILE]:

./runal -f sketch.js -o sketch

# Run the standalone executable
./sketch
Go package

Because Runal is written in Go, you can also use it as a Go package.

// sketch.go
package main

import (
	"context"
	"os"
	"os/signal"

	"github.com/emprcl/runal"
)

func main() {
	runal.Run(context.Background(),	setup, draw, runal.WithOnKey(onKey), runal.WithOnMouseClick(onMouseClick))
}

func setup(c *runal.Canvas) {}

func draw(c *runal.Canvas) {}

func onKey(c *runal.Canvas, e runal.KeyEvent) {}
func onMouseClick(c *runal.Canvas, e runal.MouseEvent) {}

Then, simply build it:

go run sketch.go

Documentation

Check the API reference. You can also check some examples in the examples directory.

Contributing

Contributions are very welcome, even if you're a beginner! Whether it's code, documentation, bug reports, examples, or just ideas, you're encouraged to join in.

Just be kind, inclusive, and patient. We're all here to learn and build something cool together.

How to contribute:

  1. Start with a discussion or open an issue to report a bug or suggest an enhancement. Please check if one already exists on the same topic first.
  2. Open a Pull Request. Please keep it small and focused.

You can also contribute by sharing what you've made with Runal on GitHub, social media, or anywhere else. We'd love to see it!

Acknowledgments

Runal uses a few awesome packages:

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Run 

func Run(ctx context.Context, setup, draw func(c *Canvas), opts ...callbackOption)

func Start 

func Start(ctx context.Context, done chan struct{}, setup, draw func(c *Canvas), opts ...callbackOption) *sync.WaitGroup

func WithOnKey added in v0.8.0 

func WithOnKey(onKey func(c *Canvas, e KeyEvent)) callbackOption

func WithOnMouseClick added in v0.8.0 

func WithOnMouseClick(onMouseClick func(c *Canvas, e MouseEvent)) callbackOption

func WithOnMouseMove added in v0.8.0 

func WithOnMouseMove(onMouseMove func(c *Canvas, e MouseEvent)) callbackOption

func WithOnMouseRelease added in v0.8.0 

func WithOnMouseRelease(onMouseRelease func(c *Canvas, e MouseEvent)) callbackOption

func WithOnMouseWheel added in v0.8.0 

func WithOnMouseWheel(onMouseWheel func(c *Canvas, e MouseEvent)) callbackOption

Types

type Canvas 

type Canvas struct {
	Width, Height  int
	MouseX, MouseY int
	Framecount     int

	IsLooping bool
	// contains filtered or unexported fields
}

Canvas represents a drawable area where shapes, text, and effects can be rendered.

func (*Canvas) Background 

func (c *Canvas) Background(text, fg, bg string)

Background sets the background character and colors for the entire canvas.

func (*Canvas) BackgroundBg 

func (c *Canvas) BackgroundBg(bg string)

BackgroundBg sets the background color used by the background fill.

func (*Canvas) BackgroundFg 

func (c *Canvas) BackgroundFg(fg string)

BackgroundFg sets the foreground (text) color used by the background fill.

func (*Canvas) BackgroundText 

func (c *Canvas) BackgroundText(text string)

BackgroundText sets the character used for the background fill.

func (*Canvas) Bezier 

func (c *Canvas) Bezier(x1, y1, x2, y2, x3, y3, x4, y4 int)

Bezier draws a Bézier curve using four control points.

func (*Canvas) CellModeCustom added in v0.9.0 

func (c *Canvas) CellModeCustom(char string)

CellModeCustom sets a specific character used for cell spacing between elements.

func (*Canvas) CellModeDefault added in v0.9.0 

func (c *Canvas) CellModeDefault()

CellModeDefault disables cell mode.

func (*Canvas) CellModeDouble added in v0.9.0 

func (c *Canvas) CellModeDouble()

CellModeDouble makes every cell duplicated.

func (*Canvas) CellPadding 

func (c *Canvas) CellPadding(char string)

DEPRECATED: Use CellModeCustom() instead.

func (*Canvas) CellPaddingDouble 

func (c *Canvas) CellPaddingDouble(char string)

DEPRECATED: Use CellModeDouble() instead.

func (*Canvas) Circle 

func (c *Canvas) Circle(xCenter, yCenter, r int)

Circle draws a circle centered at (x, y) with the given radius.

func (*Canvas) Clear 

func (c *Canvas) Clear()

Clear clears the canvas contents.

func (*Canvas) ColorHSL added in v0.10.0 

func (c *Canvas) ColorHSL(h, s, l int) string

func (*Canvas) ColorHSV added in v0.10.0 

func (c *Canvas) ColorHSV(h, s, v int) string

func (*Canvas) ColorRGB added in v0.10.0 

func (c *Canvas) ColorRGB(r, g, b int) string

func (*Canvas) Debug added in v0.9.0 

func (c *Canvas) Debug(messages ...any)

func (*Canvas) DisableRendering 

func (c *Canvas) DisableRendering()

DisableRendering disables all rendering updates. Used when an error is rendered.

func (*Canvas) Dist 

func (c *Canvas) Dist(x1, y1, x2, y2 int) float64

Dist returns the Euclidean distance between two points.

func (*Canvas) Ellipse 

func (c *Canvas) Ellipse(xCenter, yCenter, rx, ry int)

Ellipse draws an ellipse centered at (x, y) with radiuses rx and ry.

func (*Canvas) Exit added in v0.6.0 

func (c *Canvas) Exit()

Exit ends the program execution.

func (*Canvas) Fill 

func (c *Canvas) Fill(text, fg, bg string)

Fill sets the fill character and its foreground and background colors.

func (*Canvas) FillBg 

func (c *Canvas) FillBg(bg string)

FillBg sets the background color used for fill operations.

func (*Canvas) FillFg 

func (c *Canvas) FillFg(fg string)

FillFg sets the foreground color used for fill operations.

func (*Canvas) FillText 

func (c *Canvas) FillText(text string)

FillText sets the character used for fill operations.

func (*Canvas) Fps 

func (c *Canvas) Fps(fps int)

Fps sets the rendering framerate in frames per second.

func (*Canvas) Get added in v0.6.0 

func (c *Canvas) Get(x, y, w, h int) Image

func (*Canvas) Image added in v0.6.0 

func (c *Canvas) Image(img Image, x, y, w, h int)

func (*Canvas) Line 

func (c *Canvas) Line(x1, y1, x2, y2 int)

Line draws a straight line between two points.

func (*Canvas) LoadImage added in v0.6.0 

func (c *Canvas) LoadImage(path string) Image

func (*Canvas) Loop 

func (c *Canvas) Loop()

Loop enables continuous redrawing of the canvas.

func (*Canvas) LoopAngle added in v0.2.0 

func (c *Canvas) LoopAngle(duration int) float64

LoopAngle returns the angular progress (in radians, range [0, 2π]) through a looping cycle of given duration in seconds.

func (*Canvas) Map 

func (c *Canvas) Map(value, inputStart, inputEnd, outputStart, outputEnd float64) float64

Map linearly maps a value from one range to another.

func (*Canvas) NoCellPadding added in v0.7.0 

func (c *Canvas) NoCellPadding()

DEPRECATED: Use CellModeDefault() instead.

func (*Canvas) NoFill 

func (c *Canvas) NoFill()

NoFill disables fill for subsequent shapes.

func (*Canvas) NoLoop 

func (c *Canvas) NoLoop()

NoLoop disables automatic canvas redrawing.

func (*Canvas) NoStroke added in v0.6.0 

func (c *Canvas) NoStroke()

NoStroke disables stroke for subsequent shapes.

func (*Canvas) Noise1D 

func (c *Canvas) Noise1D(x float64) float64

Noise1D generates 1D Perlin noise (range [0, 1]) for a given input.

func (*Canvas) Noise2D 

func (c *Canvas) Noise2D(x, y float64) float64

Noise2D generates 2D Perlin noise (range [0, 1]) for a given (x, y) coordinate.

func (*Canvas) NoiseLoop added in v0.2.0 

func (c *Canvas) NoiseLoop(angle, radius float64) float64

NoiseLoop returns a noise value by sampling the noise on a circular path of the given radius. This is useful for creating cyclic animations or evolving patterns that repeat perfectly after one full loop.

Parameters:

  • angle: the loop angle in radians, from 0 to 2π.
  • radius: the radius of the circular path in noise space. the higher the radius, the more instable it gets.

Returns:

  • A float64 noise value in the range [0, 1].

func (*Canvas) NoiseLoop1D added in v0.2.0 

func (c *Canvas) NoiseLoop1D(angle, radius float64, x int) float64

NoiseLoop1D returns a 1D noise value that loops as the angle progresses. It samples a 2D noise space using the given radius and combines it with a horizontal offset.

Parameters:

  • angle: the loop angle in radians, typically from 0 to 2π.
  • radius: the radius of the circular path in noise space.
  • x: horizontal position to offset the noise sampling.

Returns:

  • A float64 noise value in the range [0, 1].

func (*Canvas) NoiseLoop2D added in v0.2.0 

func (c *Canvas) NoiseLoop2D(angle, radius float64, x, y int) float64

NoiseLoop2D returns a 2D noise value that loops as the angle progresses. It samples a circular path in 2D noise space, offset by the (x, y) coordinates.

Parameters:

  • angle: the loop angle in radians, typically from 0 to 2π.
  • radius: the radius of the circular path in noise space.
  • x, y: coordinates used to offset the sampled position in the noise field.

Returns:

  • A float64 noise value in the range [0, 1].

func (*Canvas) NoiseSeed 

func (c *Canvas) NoiseSeed(seed int64)

NoiseSeed sets the random seed for noise generation.

func (*Canvas) Point 

func (c *Canvas) Point(x, y int)

Point draws a single point at the given position.

func (*Canvas) Pop 

func (c *Canvas) Pop()

Pop restores the previous transformation state.

func (*Canvas) Push 

func (c *Canvas) Push()

Push saves the current transformation state.

func (*Canvas) Quad 

func (c *Canvas) Quad(x1, y1, x2, y2, x3, y3, x4, y4 int)

Quad draws a quadrilateral defined by four points.

func (*Canvas) Random 

func (c *Canvas) Random(minimum, maximum int) float64

Random returns a random float between minimum and maximum.

func (*Canvas) RandomSeed 

func (c *Canvas) RandomSeed(seed int64)

RandomSeed sets the random number generator seed.

func (*Canvas) Rect 

func (c *Canvas) Rect(x, y, w, h int)

Rect draws a rectangle starting at (x, y) with width w and height h.

func (*Canvas) Redraw 

func (c *Canvas) Redraw()

Redraw triggers a manual rendering pass.

func (*Canvas) Rotate 

func (c *Canvas) Rotate(angle float64)

Rotate rotates the drawing context by the given angle in radians.

func (*Canvas) SaveCanvasToGIF added in v0.2.0 

func (c *Canvas) SaveCanvasToGIF(filename string, duration int)

SaveCanvasToGIF exports the canvas to an animated gif for a given duration (in seconds).

func (*Canvas) SaveCanvasToMP4 added in v0.4.0 

func (c *Canvas) SaveCanvasToMP4(filename string, duration int)

SaveCanvasToMP4 exports the canvas to a mp4 (h264) video for a given duration (in seconds). Depends on ffmpeg.

func (*Canvas) SaveCanvasToPNG added in v0.2.0 

func (c *Canvas) SaveCanvasToPNG(filename string)

SaveCanvasToPNG exports the canvas to a png image file.

func (*Canvas) SavedCanvasFont 

func (c *Canvas) SavedCanvasFont(filename string)

SavedCanvasFont sets a custom font (tff) file used for rendering text characters in exported images generated via SaveCanvasTo...().

func (*Canvas) SavedCanvasFontSize added in v0.2.0 

func (c *Canvas) SavedCanvasFontSize(size int)

SavedCanvasFontSize sets the font size used for rendering text characters in exported images generated via SaveCanvas().

func (*Canvas) Scale 

func (c *Canvas) Scale(scale float64)

Scale scales the drawing context by the given factor.

func (*Canvas) Set added in v0.6.0 

func (c *Canvas) Set(x, y int, cells writable)

func (*Canvas) Size 

func (c *Canvas) Size(w, h int)

Size sets the dimensions of the canvas.

func (*Canvas) Square 

func (c *Canvas) Square(x, y, size int)

Square draws a square with the given top-left corner and side length.

func (*Canvas) Stroke 

func (c *Canvas) Stroke(text, fg, bg string)

Stroke sets the stroke (outline) character and colors.

func (*Canvas) StrokeBg 

func (c *Canvas) StrokeBg(bg string)

StrokeBg sets the background color for strokes.

func (*Canvas) StrokeFg 

func (c *Canvas) StrokeFg(fg string)

StrokeFg sets the foreground color for strokes.

func (*Canvas) StrokeText 

func (c *Canvas) StrokeText(text string)

StrokeText sets the character used for strokes.

func (*Canvas) Text 

func (c *Canvas) Text(text string, x, y int)

Text renders a string at the given canvas coordinates.

func (*Canvas) Translate 

func (c *Canvas) Translate(x, y int)

Translate offsets the drawing context by (x, y).

func (*Canvas) Triangle 

func (c *Canvas) Triangle(x1, y1, x2, y2, x3, y3 int)

Triangle draws a triangle using three vertex points.

type Cell added in v0.6.0 

type Cell struct {
	Char       string
	Foreground string
	Background string
}

type Image added in v0.6.0 

type Image interface {
	Cell(x, y int) Cell
	// contains filtered or unexported methods
}

type KeyEvent added in v0.5.0 

type KeyEvent struct {
	Key  string
	Code int
}

type MouseEvent added in v0.5.0 

type MouseEvent struct {
	X      int
	Y      int
	Button string
}

type Number added in v0.10.0 

type Number interface {
	constraints.Integer | constraints.Float
}

Source Files

View all Source files

Directories

Path Synopsis
cli module
pkg
mosaic
Package mosaic provides a unicode image renderer.
 Package mosaic provides a unicode image renderer.

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.