sketch

package module
v1.0.1 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2026 License: MIT Imports: 8 Imported by: 0

README

sketch

A simplified, opinionated wrapper around Ebiten Go's 2D game engine designed for creative coding and quick visual experiments. Instead of managing the full Ebiten game loop yourself, you implement a single Sketchable interface and call Run. The library handles window setup, frame scheduling, and coordinate-system transforms so you can focus on drawing.

Sketch gives you a Screen with a high-level drawing API: lines, rectangles, circles, arcs, polygons, all with both stroked and filled version and automatic transform support (translate, rotate, scale, push/pull). Keyboard and mouse input are exposed as simple package-level functions as well as through the State passed to each frame. A vector sub-package provides 2D Cartesian and polar vector types for convenient geometry math.

Getting started

Implementing your own Sketch

Embed sketch.Sketch into a struct and override whichever methods you need:

package main

import (
	"image/color"
    "log"

	"github.com/MichalMitros/sketch"
	"github.com/MichalMitros/sketch/vector"
)

type BouncingBall struct {
    // Embedding the Sketch struct makes the BouncingBall a noop Sketchable which can be added to Run.
    // It is not required, but makes implementation easier as it provides default noop implementations for required functions.
	sketch.Sketch

	pos      vector.Vector
	velocity vector.Vector
	radius   float64
}

// Setup is called once before first Update() call.
// It's the best way of initializing the sketch if its parameters require data from the State, like screen size.
func (b *BouncingBall) Setup(state *sketch.State) error {
	b.pos = state.ScreenSize().Scale(0.5) // center of the screen, screen width / 2 and screen height / 2
	b.velocity = vector.New(3, 2)
	b.radius = 30
	return nil
}

// Update is called every frame.
func (b *BouncingBall) Update(state *sketch.State) error {
	// move the ball
	b.pos = b.pos.Add(b.velocity)

    // check if the ball is out of bounds
    w, h := state.ScreenSize().Values() // Values() returns the vector's components for easy access
	if b.pos.X-b.radius < 0 || b.pos.X+b.radius > w {
		b.velocity.X *= -1
	}
	if b.pos.Y-b.radius < 0 || b.pos.Y+b.radius > h {
		b.velocity.Y *= -1
	}

    // terminate the sketch if the escape key is pressed,
    // can be also done by passing WithTerminationKeys(sketch.KeyEscape) to Run
	if state.IsKeyPressed(sketch.KeyEscape) {
		return sketch.Termination
	}
	return nil
}

// Draw is used each frame to render it.
func (b *BouncingBall) Draw(screen *sketch.Screen) {
    // fill red circle at b.pos with radius b.radius and stroke width 2
	screen.FillCircle(b.pos, b.radius, 2, color.RGBA{255, 0, 0, 255})
}

func main() {
    // run the BouncingBall sketch with 800x600 resolution, a black background and the title "Bouncing Ball"
	if err := sketch.Run(800, 600, new(BouncingBall),
		sketch.WithWindowTitle("Bouncing Ball"),
		sketch.WithBackgroundColor(color.Black),
	); err != nil {
		log.Fatal(err)
	}
}
Options

Run accepts optional configuration via functional options:

Option Default Description
WithWindowTitle(title) "" Sets the window title
WithBackgroundColor(c) [240,240,240,255] Background color
WithResizing(enable) disabled Allows the window to be resized
WithAntyaliasing(enable) enabled Toggles anti-aliased rendering
WithRunnableOnUnfocused(enable) enabled Keeps running when unfocused
WithTerminationKeys(keys...) none Keys that terminate the sketch

Input

Keyboard

All standard keys are available as Key constants:

sketch.IsKeyPressed(sketch.KeySpace)
Mouse

Three package-level functions cover mouse input:

sketch.IsMouseButtonPressed(sketch.MouseButtonLeft)    // bool
sketch.CursorPosition()                                // vector.Vector
sketch.Scroll()                                        // (dx, dy float64)

Available button constants: MouseButtonLeft, MouseButtonRight, MouseButtonMiddle, and MouseButton0-MouseButton4.

Utility
sketch.FPS()           // current frames per second
sketch.TPS()           // current ticks per second
sketch.Fullscreen(b)   // toggle fullscreen
sketch.IsFullscreen()  // check fullscreen state
sketch.MonitorSize()   // size (as vector.Vector) of the primary monitor

State

State is passed to both Setup and Update. It carries:

state.ScreenSize()           // vector.Vector - current width and height

When resizing of the window is enabled, always read dimensions from State instead of caching them from Setup.

Screen

Screen is the drawing surface passed to Draw. Every shape method accepts screen-space coordinates and a color.Color.

Transforms

Push/pull a transformation stack to isolate coordinate changes:

screen.Push()
screen.Translate(v)       // move origin
screen.Rotate(angle)      // rotate axes (radians)
screen.Scale(rate)        // uniform scale
screen.ScaleX(rate)       // scale only X
screen.ScaleY(rate)       // scale only Y
// ... draw shapes ...
screen.Pull()
Shapes

Stroked methods take a strokeWidth and color.Color; filled methods take only color.Color:

screen.Line(v1, v2, strokeWidth, color)
screen.Rectangle(pos, w, h, strokeWidth, color)
screen.FillRectangle(pos, w, h, color)
screen.Circle(center, radius, strokeWidth, color)
screen.FillCircle(center, radius, color)
screen.Arc(center, radius, startAngle, endAngle, strokeWidth, color)
screen.FillArc(center, radius, startAngle, endAngle, color)
screen.Shape(points, close, strokeWidth, color)
screen.FillShape(points, close, color)

Plus:

screen.Clear()            // fill with background color
screen.Fill(c)            // fill with arbitrary color
screen.At(x, y)           // sample pixel color
screen.Width() / screen.Height() / screen.Size()

Vector & Polar

The vector sub-package provides two types for 2D geometry.

Vector (vector.Vector) - Cartesian coordinates:

v := vector.New(x, y)
zero := vector.Zero()
x, y := v.Values()
v.Add(other)   | v.Sub(other)   | v.Mul(other)
v.Scale(s)     | v.Mag()        | v.SetMag(m)
v.Dist(other)  | v.Rotate(rad)  | v.Angle()
v.Polar()      // conversion to Polar

Polar (vector.Polar) - polar coordinates (angle in radians):

p := vector.NewPolar(radius, angle)
r, a := p.Values()
p.Rotate(rad)  | p.Add(other)  | p.Dist(other)
p.Vector()     // conversion to Cartesian

Documentation

Overview

Package sketch is a simplified wrapper around Ebiten Go's 2D game engine designed for creative coding and quick visual experiments. Instead of managing the full Ebiten game loop yourself, you implement a single `Sketchable` interface and call `Run`.

Index

Constants

View Source 
const (
	// Termination is returned when the sketch is terminated.
	Termination sketchErr = "sketch terminated"
	// ErrNilSketch is returned when the sketch is not provided.
	ErrNilSketch sketchErr = "sketch cannot be nil"
	// ErrInvalidScreenDimensions is returned when the screen dimensions are not positive.
	ErrInvalidScreenDimensions sketchErr = "screen dimensions must be positive"
	// ErrSketchAlreadyRunning is returned when the sketch is already running.
	ErrSketchAlreadyRunning sketchErr = "another sketch is already running"
)

Variables

This section is empty.

Functions

func CursorPosition 

func CursorPosition() vector.Vector

CursorPosition returns the current position of the mouse cursor.

func FPS 

func FPS() float64

FPS returns the current frames per second.

func Fullscreen 

func Fullscreen(enable bool)

Fullscreen sets the sketch to fullscreen.

func IsFullscreen 

func IsFullscreen() bool

IsFullscreen returns true if the sketch is currently in fullscreen.

func IsKeyPressed 

func IsKeyPressed(k Key) bool

IsKeyPressed returns true if the given key is currently pressed.

func IsMouseButtonPressed 

func IsMouseButtonPressed(k Key) bool

IsKeyPressed returns true if the given key is currently pressed.

func MonitorSize 

func MonitorSize() vector.Vector

MonitorSize returns the size of the monitor.

func Run 

func Run(
	screenWidth, screenHeight int,
	sketch Sketchable,
	opts ...Option,
) error

Run runs the sketch. It returns ErrNilSketch if sketch is nil. It returns ErrInvalidScreenDimensions if screenWidth or screenHeight is less than or equal to 0. It returns ErrSketchAlreadyRunning if another sketch is already running.

func Scroll 

func Scroll() (dx, dy float64)

Scroll returns the current scroll amount of the mouse wheel.

func TPS 

func TPS() float64

TPS returns the current ticks per second.

Types

type Key 

type Key int

Key is a key on the keyboard. 

const (
	KeyA              Key = Key(ebiten.KeyA)
	KeyB              Key = Key(ebiten.KeyB)
	KeyC              Key = Key(ebiten.KeyC)
	KeyD              Key = Key(ebiten.KeyD)
	KeyE              Key = Key(ebiten.KeyE)
	KeyF              Key = Key(ebiten.KeyF)
	KeyG              Key = Key(ebiten.KeyG)
	KeyH              Key = Key(ebiten.KeyH)
	KeyI              Key = Key(ebiten.KeyI)
	KeyJ              Key = Key(ebiten.KeyJ)
	KeyK              Key = Key(ebiten.KeyK)
	KeyL              Key = Key(ebiten.KeyL)
	KeyM              Key = Key(ebiten.KeyM)
	KeyN              Key = Key(ebiten.KeyN)
	KeyO              Key = Key(ebiten.KeyO)
	KeyP              Key = Key(ebiten.KeyP)
	KeyQ              Key = Key(ebiten.KeyQ)
	KeyR              Key = Key(ebiten.KeyR)
	KeyS              Key = Key(ebiten.KeyS)
	KeyT              Key = Key(ebiten.KeyT)
	KeyU              Key = Key(ebiten.KeyU)
	KeyV              Key = Key(ebiten.KeyV)
	KeyW              Key = Key(ebiten.KeyW)
	KeyX              Key = Key(ebiten.KeyX)
	KeyY              Key = Key(ebiten.KeyY)
	KeyZ              Key = Key(ebiten.KeyZ)
	KeyAltLeft        Key = Key(ebiten.KeyAltLeft)
	KeyAltRight       Key = Key(ebiten.KeyAltRight)
	KeyArrowDown      Key = Key(ebiten.KeyArrowDown)
	KeyArrowLeft      Key = Key(ebiten.KeyArrowLeft)
	KeyArrowRight     Key = Key(ebiten.KeyArrowRight)
	KeyArrowUp        Key = Key(ebiten.KeyArrowUp)
	KeyBackquote      Key = Key(ebiten.KeyBackquote)
	KeyBackslash      Key = Key(ebiten.KeyBackslash)
	KeyBackspace      Key = Key(ebiten.KeyBackspace)
	KeyBracketLeft    Key = Key(ebiten.KeyBracketLeft)
	KeyBracketRight   Key = Key(ebiten.KeyBracketRight)
	KeyCapsLock       Key = Key(ebiten.KeyCapsLock)
	KeyComma          Key = Key(ebiten.KeyComma)
	KeyContextMenu    Key = Key(ebiten.KeyContextMenu)
	KeyControlLeft    Key = Key(ebiten.KeyControlLeft)
	KeyControlRight   Key = Key(ebiten.KeyControlRight)
	KeyDelete         Key = Key(ebiten.KeyDelete)
	KeyDigit0         Key = Key(ebiten.KeyDigit0)
	KeyDigit1         Key = Key(ebiten.KeyDigit1)
	KeyDigit2         Key = Key(ebiten.KeyDigit2)
	KeyDigit3         Key = Key(ebiten.KeyDigit3)
	KeyDigit4         Key = Key(ebiten.KeyDigit4)
	KeyDigit5         Key = Key(ebiten.KeyDigit5)
	KeyDigit6         Key = Key(ebiten.KeyDigit6)
	KeyDigit7         Key = Key(ebiten.KeyDigit7)
	KeyDigit8         Key = Key(ebiten.KeyDigit8)
	KeyDigit9         Key = Key(ebiten.KeyDigit9)
	KeyEnd            Key = Key(ebiten.KeyEnd)
	KeyEnter          Key = Key(ebiten.KeyEnter)
	KeyEqual          Key = Key(ebiten.KeyEqual)
	KeyEscape         Key = Key(ebiten.KeyEscape)
	KeyF1             Key = Key(ebiten.KeyF1)
	KeyF2             Key = Key(ebiten.KeyF2)
	KeyF3             Key = Key(ebiten.KeyF3)
	KeyF4             Key = Key(ebiten.KeyF4)
	KeyF5             Key = Key(ebiten.KeyF5)
	KeyF6             Key = Key(ebiten.KeyF6)
	KeyF7             Key = Key(ebiten.KeyF7)
	KeyF8             Key = Key(ebiten.KeyF8)
	KeyF9             Key = Key(ebiten.KeyF9)
	KeyF10            Key = Key(ebiten.KeyF10)
	KeyF11            Key = Key(ebiten.KeyF11)
	KeyF12            Key = Key(ebiten.KeyF12)
	KeyF13            Key = Key(ebiten.KeyF13)
	KeyF14            Key = Key(ebiten.KeyF14)
	KeyF15            Key = Key(ebiten.KeyF15)
	KeyF16            Key = Key(ebiten.KeyF16)
	KeyF17            Key = Key(ebiten.KeyF17)
	KeyF18            Key = Key(ebiten.KeyF18)
	KeyF19            Key = Key(ebiten.KeyF19)
	KeyF20            Key = Key(ebiten.KeyF20)
	KeyF21            Key = Key(ebiten.KeyF21)
	KeyF22            Key = Key(ebiten.KeyF22)
	KeyF23            Key = Key(ebiten.KeyF23)
	KeyF24            Key = Key(ebiten.KeyF24)
	KeyHome           Key = Key(ebiten.KeyHome)
	KeyInsert         Key = Key(ebiten.KeyInsert)
	KeyIntlBackslash  Key = Key(ebiten.KeyIntlBackslash)
	KeyMetaLeft       Key = Key(ebiten.KeyMetaLeft)
	KeyMetaRight      Key = Key(ebiten.KeyMetaRight)
	KeyMinus          Key = Key(ebiten.KeyMinus)
	KeyNumLock        Key = Key(ebiten.KeyNumLock)
	KeyNumpad0        Key = Key(ebiten.KeyNumpad0)
	KeyNumpad1        Key = Key(ebiten.KeyNumpad1)
	KeyNumpad2        Key = Key(ebiten.KeyNumpad2)
	KeyNumpad3        Key = Key(ebiten.KeyNumpad3)
	KeyNumpad4        Key = Key(ebiten.KeyNumpad4)
	KeyNumpad5        Key = Key(ebiten.KeyNumpad5)
	KeyNumpad6        Key = Key(ebiten.KeyNumpad6)
	KeyNumpad7        Key = Key(ebiten.KeyNumpad7)
	KeyNumpad8        Key = Key(ebiten.KeyNumpad8)
	KeyNumpad9        Key = Key(ebiten.KeyNumpad9)
	KeyNumpadAdd      Key = Key(ebiten.KeyNumpadAdd)
	KeyNumpadDecimal  Key = Key(ebiten.KeyNumpadDecimal)
	KeyNumpadDivide   Key = Key(ebiten.KeyNumpadDivide)
	KeyNumpadEnter    Key = Key(ebiten.KeyNumpadEnter)
	KeyNumpadEqual    Key = Key(ebiten.KeyNumpadEqual)
	KeyNumpadMultiply Key = Key(ebiten.KeyNumpadMultiply)
	KeyNumpadSubtract Key = Key(ebiten.KeyNumpadSubtract)
	KeyPageDown       Key = Key(ebiten.KeyPageDown)
	KeyPageUp         Key = Key(ebiten.KeyPageUp)
	KeyPause          Key = Key(ebiten.KeyPause)
	KeyPeriod         Key = Key(ebiten.KeyPeriod)
	KeyPrintScreen    Key = Key(ebiten.KeyPrintScreen)
	KeyQuote          Key = Key(ebiten.KeyQuote)
	KeyScrollLock     Key = Key(ebiten.KeyScrollLock)
	KeySemicolon      Key = Key(ebiten.KeySemicolon)
	KeyShiftLeft      Key = Key(ebiten.KeyShiftLeft)
	KeyShiftRight     Key = Key(ebiten.KeyShiftRight)
	KeySlash          Key = Key(ebiten.KeySlash)
	KeySpace          Key = Key(ebiten.KeySpace)
	KeyTab            Key = Key(ebiten.KeyTab)
	KeyAlt            Key = Key(ebiten.KeyAlt)
	KeyControl        Key = Key(ebiten.KeyControl)
	KeyShift          Key = Key(ebiten.KeyShift)
)

type MouseButton 

type MouseButton int

MouseButton is a mouse button. 

const (
	MouseButtonLeft   MouseButton = MouseButton(ebiten.MouseButtonLeft)
	MouseButtonRight  MouseButton = MouseButton(ebiten.MouseButtonRight)
	MouseButtonMiddle MouseButton = MouseButton(ebiten.MouseButtonMiddle)
	MouseButton0      MouseButton = MouseButton(ebiten.MouseButton0)
	MouseButton1      MouseButton = MouseButton(ebiten.MouseButton1)
	MouseButton2      MouseButton = MouseButton(ebiten.MouseButton2)
	MouseButton3      MouseButton = MouseButton(ebiten.MouseButton3)
	MouseButton4      MouseButton = MouseButton(ebiten.MouseButton4)
)

type Option 

type Option func(sketchBuildParams)

Option is a function that configures a sketch.

func WithAntyaliasing 

func WithAntyaliasing(enable bool) Option

WithAntyaliasing enables or disables antialiasing (enabled by default).

func WithBackgroundColor 

func WithBackgroundColor(c color.Color) Option

WithBackgroundColor sets the background color of the sketch ([240, 240, 240, 255] by default).

func WithResizing 

func WithResizing(enable bool) Option

WithResizing enables or disables resizing (enabled by default).

func WithRunnableOnUnfocused 

func WithRunnableOnUnfocused(enable bool) Option

WithRunnableOnUnfocused enables or disables the game to be runnable on unfocused (enabled by default).

func WithTerminationKeys 

func WithTerminationKeys(k ...Key) Option

WithTerminationKey sets the key which will terminate the game.

func WithWindowTitle 

func WithWindowTitle(title string) Option

WithWindowTitle sets the window title of the sketch (no title by default).

type Screen 

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

Screen is the screen used to draw to.

func (*Screen) Arc 

func (s *Screen) Arc(v vector.Vector, radius, startAngle, endAngle, strokeWidth float64, c color.Color)

Arc draws an arc at the given position with the given radius, start angle, end angle, stroke width and color.

func (*Screen) At 

func (s *Screen) At(x, y int) color.Color

At returns the color at the given position.

func (*Screen) Circle 

func (s *Screen) Circle(v vector.Vector, radius, strokeWidth float64, c color.Color)

Circle draws a circle at the given position with the given radius, stroke width and color.

func (*Screen) Clear 

func (s *Screen) Clear()

Clear clears the screen.

func (*Screen) Fill 

func (s *Screen) Fill(c color.Color)

Fill fills the screen with the given color.

func (*Screen) FillArc 

func (s *Screen) FillArc(v vector.Vector, radius, startAngle, endAngle float64, c color.Color)

FillArc draws a filled arc (pie slice) at the given position with the given radius, start angle, end angle and color.

func (*Screen) FillCircle 

func (s *Screen) FillCircle(v vector.Vector, radius, strokeWidth float64, c color.Color)

FillCircle draws a filled circle at the given position with the given radius, stroke width and color.

func (*Screen) FillRectangle 

func (s *Screen) FillRectangle(v vector.Vector, width, height, strokeWidth float64, c color.Color)

FillRectangle draws a filled rectangle at the given position with the given width, height, stroke width and color.

func (*Screen) FillShape 

func (s *Screen) FillShape(points []vector.Vector, close bool, c color.Color)

FillShape draws a filled polygon through the given points with the given color. If close is true, the shape is closed. If len(points) < 2, nothing is drawn. If len(points) == 2, a line is drawn.

func (*Screen) Height 

func (s *Screen) Height() float64

Height returns the height of the screen.

func (*Screen) Line 

func (s *Screen) Line(v1, v2 vector.Vector, strokeWidth float64, c color.Color)

Line draws a line from v1 to v2 with the given stroke width and color.

func (*Screen) Pull 

func (s *Screen) Pull()

Pull removes the most recently pushed transformation layer. Pulling the initial layer has no effect.

func (*Screen) Push 

func (s *Screen) Push()

Push adds an identity transformation layer to the stack.

func (*Screen) Rectangle 

func (s *Screen) Rectangle(v vector.Vector, width, height, strokeWidth float64, c color.Color)

Rectangle draws a rectangle at the given position with the given width, height, stroke width and color.

func (*Screen) Rotate 

func (s *Screen) Rotate(angle float64)

Rotate rotates the coordinate system by angle radians.

func (*Screen) Scale 

func (s *Screen) Scale(rate float64)

Scale scales both coordinate axes by rate.

func (*Screen) ScaleX 

func (s *Screen) ScaleX(rate float64)

ScaleX scales the X coordinate axis by rate.

func (*Screen) ScaleY 

func (s *Screen) ScaleY(rate float64)

ScaleY scales the Y coordinate axis by rate.

func (*Screen) Shape 

func (s *Screen) Shape(points []vector.Vector, close bool, strokeWidth float64, c color.Color)

Shape draws a polygon through the given points with the given stroke width and color. If close is true, the shape is closed. If len(points) < 2, nothing is drawn. If len(points) == 2, a line is drawn.

func (*Screen) Size 

func (s *Screen) Size() vector.Vector

Size returns the width and height of the screen.

func (*Screen) Transform 

func (s *Screen) Transform(v vector.Vector)

Transform moves the origin of the coordinate system by v.

func (*Screen) TransformX 

func (s *Screen) TransformX(dx float64)

TransformX moves the origin of the coordinate system along the X axis.

func (*Screen) TransformY 

func (s *Screen) TransformY(dy float64)

TransformY moves the origin of the coordinate system along the Y axis.

func (*Screen) Width 

func (s *Screen) Width() float64

Width returns the width of the screen.

type Sketch 

type Sketch struct{}

Sketch is a noop Sketchable which can be embedded and added to Sketch.

func (*Sketch) Draw 

func (s *Sketch) Draw(screen *Screen)

Draw is used each frame to render it.

func (*Sketch) Setup 

func (s *Sketch) Setup(state *State) error

Setup is called once before first Update() call.

func (*Sketch) Update 

func (s *Sketch) Update(state *State) error

Update is called every frame.

type Sketchable 

type Sketchable interface {
	// Update is called every frame.
	Update(*State) error
	// Draw is used each frame to render it.
	Draw(*Screen)
	// Setup is called once before first Update() call.
	Setup(state *State) error
}

Sketchable is a single sketchable object.

type State 

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

State is the state of the sketch used to provide information about the current state of the sketch to Update().

func (*State) ScreenSize 

func (s *State) ScreenSize() vector.Vector

ScreenSize returns the width and height of the screen.

Source Files

View all Source files

Directories

Path Synopsis
Package vector provides a simple 2D vector type.
 Package vector provides a simple 2D vector type.

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.