Categorygithub.com/anaseto/gruid
modulepackage
0.22.0
Repository: https://github.com/anaseto/gruid.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
11
Dependents
16
Files
1.1k SLOC

# README

Gruid

pkg.go.dev godocs.io

The gruid module provides packages for easily building grid-based applications in Go. The library abstracts rendering and input for different platforms. There are drivers available for terminal apps (gruid-tcell), native graphical apps (gruid-sdl) and browser apps (gruid-js). The original application for the library was creating grid-based games, but it's also well-suited for any grid-based application.

The core gruid package uses a convenient and flexible architecture of updating a model in response to messages strongly inspired from the bubbletea module for building terminal apps, which in turn is based on the functional Elm Architecture. The architecture has been adapted to be more idiomatic in Go in the context of grid-based applications: less functional and more efficient.

You can find examples below in the Examples section.

Overview of packages

The full documentation is linked at the top of this README. We provide here a quick overview.

The gruid package defines the Model and Driver interfaces and allows to start the “update on message then draw” main loop of an application. It also defines a convenient and efficient slice grid structure to represent the logical contents of the screen and manipulate them.

The ui package defines common UI widgets and utilities: menu/table widget, pager, text input, label, styled text drawing facilities and replay functionality.

The tiles package contains helpers for drawing fonts on images, which can be used to manage character tiles using a Driver from either gruid-sdl or gruid-js.

The paths package provides efficient implementations of some common pathfinding algorithms that are often used in grid-based games, such as roguelikes. You will find implementations of the A* and JPS algorithms, as well as Dijkstra, breadth first, and connected components maps computations. See move.go in the movement example in gruid-examples for an annotated example using JPS and the mouse.

The rl package provides some additional utilities commonly needed in grid-based games such as roguelikes. The package provides an event priority queue, two complementary field of view algorithms, map generation algorithms, as well as vault parsing and manipulation utilities.

Drivers

The tcell, sdl, and js packages in the (gruid-tcell), (gruid-sdl) and (gruid-js) modules provide specific rendering and input implementations satisfying gruid's package Driver interface. The provided terminal driver only handles full-window applications. See the README.md files in the respective repositories for specific build and deployment instructions (gruid-sdl will require SDL2, and gruid-js will require a bit of HTML and js).

Examples

The gruid-examples module offers some simple annotated examples of gruid usage.

You may want to look also into some real world examples of gruid programs:

See also

If you need to handle wide-characters, that is characters that take two cells in the terminal, you may want to look into go-runewidth.

The clipboard module may be of interest for some applications too, as copying and pasting is not handled by gruid. Note that, at this time, the clipboard module does not support the js platform, but there's at least one fork that does.

As gruid only provides a few map generation algorithms, you may be interested in the dngn module, which provides map generation algorithms too, though its representation of maps is different.

# Packages

Package paths provides utilities for efficient pathfinding in rectangular maps.
Package rl provides some facilities for common roguelike programming needs: event queue, field of view and map generation.
Package tiles provides common utilities for manipulation of graphical tiles, such as drawing fonts.
Package ui defines common UI utilities for gruid: menu/table widget, pager, text input, label, text drawing facilities and replay functionality.

# Functions

Batch peforms a bunch of effects concurrently with no ordering guarantees about the potential results.
End returns a special command that signals the application to end its Start loop.
NewApp creates a new App with the given configuration options.
NewFrameDecoder returns a FrameDecoder using a given reader as source for frames.
NewGrid returns a new grid with given width and height in cells.
NewRange returns a new Range with coordinates (x0, y0) for Min and (x1, y1) for Max.

# Constants

AttrsDefault represents the default styling attributes.
ColorDefault should get special treatment by drivers and be mapped, when it makes sense, to a default color, both for foreground and background.
can be KP_2.
can be KP_4.
can be KP_6.
can be KP_8.
This is the list of the supported non single-character named keys.
This is the list of the supported non single-character named keys.
can be KP_1.
can be KP_5 (arbitrary choice).
This is the list of the supported non single-character named keys.
can be KP_7.
This is the list of the supported non single-character named keys.
can be KP_3.
can be KP_9.
constant for clarity (single character).
This is the list of the supported non single-character named keys.
These values represent modifier keys for a MsgKeyDown message.
These values represent modifier keys for a MsgKeyDown message.
These values represent modifier keys for a MsgKeyDown message.
These values represent modifier keys for a MsgKeyDown message.
These values represent modifier keys for a MsgKeyDown message.
middle button.
left button.
mouse motion.
button release.
right button.
wheel impulse down.
wheel impulse up.

# Structs

App represents a message and model-driven application with a grid-based user interface.
AppConfig contains the configuration options for creating a new App.
Cell contains all the content and styling information to represent a cell in the grid.
Frame contains the necessary information to draw the frame changes from a frame to the next.
FrameCell represents a cell drawing instruction at a specific absolute position in the whole grid.
FrameDecoder manages the decoding of the frame recording stream produced by the running of an application, in case a FrameWriter was provided.
Grid represents the grid that is used to draw a model logical contents that are then sent to the driver.
GridIterator represents a stateful iterator for a grid.
MsgInit is a special message that is always sent first to Update after calling Start on the application.
MsgKeyDown represents a key press.
MsgMouse represents a mouse user input event.
MsgScreen is reported by some drivers when the screen has been exposed in some way and a complete redraw is necessary.
Point represents an (X,Y) position in a grid.
Range represents a rectangle in a grid that contains all the positions P such that Min <= P < Max coordinate-wise.
Style represents the styling information of a cell: foreground color, background color and custom attributes.

# Interfaces

Driver handles both user input and rendering.
DriverPollMsg is an optional interface that can be satisfied by drivers.
Effect is an interface type for representing either command or subscription functions.
Model contains the application's state.
Msg represents an action and triggers the Update function of the model.

# Type aliases

AttrMask can be used to add custom styling information.
Cmd is an Effect that returns a message.
Color is a generic value for representing colors.
Key represents the name of a key press.
ModMask is a bit mask of modifier keys.
MouseAction represents mouse buttons.
MsgQuit may be reported by some drivers to request termination of the application, such as when the main window is closed.
Sub is similar to Cmd, but instead of returning a message, it sends messages to a channel.