pi

README

pi

Table of Contents

• Introduction
• What defines the retro games made with Pi?
• Why Pi?
• How to get started?
• How does it work?
• FAQ
• Attributions

Introduction

Pi is a game engine for creating retro games for modern computers. Its goal is to limit possibilities — to spark creativity and increase the chance of actually finishing your game. Too much freedom often leads to overly ambitious and never-ending projects. Pi was inspired by Pico-8 and is powered by Ebitengine.

Although Pi was inspired by fantasy consoles, it is not one itself. It doesn't emulate a fictional machine. Instead, it's a real Go library with dev-tools that make it simple (and fun!) to build retro games that run natively on modern hardware.

What defines the retro games made with Pi?

They resemble games from 8-bit and 16-bit computers, because:

• they run at (very) low resolutions — like 128×128 or 320×180
• they use only 64 colors displayed on screen at once
• they use graphics rendered directly by the CPU — just like in early home computers
• they work with limited resources — such as 256 sprites or tile maps with just a few thousand tiles
• their code is short — thousands, not millions, of lines
• they use game controllers with a small number of buttons
• they use sound effects and music made from predefined synthesized instruments

Why Pi?

Because it's probably the easiest and most fun way to write a game in Go. No complex engine setup. No boilerplate. Just write code and see things happen. Perfect for small projects, prototypes, jams — or simply to have fun.

How to get started?

1. Install dependencies

   • Go 1.24+
   • If you are not on Windows, install additional dependencies for:
     • Linux
     • macOS

2. Try examples from the _examples directory

   • Run the Snake example directly:

     go run github.com/elgopher/pi/_examples/snake@HEAD
     

   • Or clone the Pi repository and modify the example:

     git clone https://github.com/elgopher/pi
     cd pi/_examples/snake
     # edit main.go to experiment
     go run .
     

3. Create a new game

   • Use the provided GitHub template

4. Explore further

   • Read the rest of this README.md
   • Check out the godoc documentation

How does it work?

Pi is designed to make writing a game as simple as possible — even if you've never made one before.
It gives you just a few core concepts and keeps things minimal, so you can focus on making something fun.

---

Game loop

Pi runs your game in a loop. In each frame, it calls two functions you define:

• pi.Update — where you put your game logic, e.g. handling input.
• pi.Draw — where you put your rendering code. It runs right after pi.Update.

By default, Pi runs these functions 30 times per second, but this is configurable.

---

Backend

Pi has a modular architecture that allows using different backends.
A backend is a low-level package that runs your game on different devices.

Currently, the recommended backend is piebiten, which supports Windows, macOS, Linux, and more, using Ebitengine under the hood.

Here's a minimal example that displays "HELLO WORLD" on a 47×9 pixel screen using the piebiten backend:

package main

import (
   "github.com/elgopher/pi"          // core package
   "github.com/elgopher/pi/picofont" // tiny Pico-8 font
   "github.com/elgopher/pi/piebiten" // backend
)

func main() {
   pi.SetScreenSize(47, 9) // set custom screen size
   pi.Draw = func() {      // draw runs each frame
      picofont.Print("HELLO WORLD", 2, 2)
   }
   piebiten.Run()          // run the backend
}

When Pi opens a window for your game, it automatically adjusts the window size to match your monitor's resolution. Since modern monitors have much higher resolutions (e.g. 1920×1080 or even 3840×2160), Pi needs to scale up the game screen. Each game pixel is multiplied an integer number of times (integer scaling). This ensures that the game screen always stays true to its original pixel-perfect look without any distortion.

---

Game screen

Pi gives you a small, low-resolution pixel canvas to draw on. It's like an old-school screen: you can set pixels, draw lines, rectangles, sprites, and text. The limited resolution encourages you to focus on clear shapes and designs.

Each pixel on the game screen has (x, y) coordinates and a pi.Color. pi.Color is a number from 0 to 63, letting you use up to 64 colors on screen at once. Coordinate (0,0) is the top-left corner of the screen.

Pi does not impose any fixed screen size — you can choose resolutions like 128×128 or 320×180. However, there's a limit on the total number of pixels: 128 KB (131,072 pixels). It's recommended to start with a low resolution for your first game, such as 128×128.

---

Color palette

Pi uses a game-defined, configurable pi.Palette which maps each pi.Color to an RGB value. For example, by default color 0 is black (0x000000), and color 7 is white (0xFFF1E8).

You choose your game's palette, but you're limited to 64 colors. That may seem small, but for low-resolution pixel-art it's usually plenty. The palette can be changed during the game, but changes will appear only when rendering the frame at the end of the update cycle.

---

Canvas, sprites, and blitting

pi.Canvas is a 2D structure storing color values. The game screen itself is a Canvas. Your game can not only draw pixels on a Canvas but also read them back.

This makes it possible to copy pixels from one Canvas to another — for example, you can load a PNG file into a Canvas and then copy (blit) parts of it onto the game screen.

These source images (PNG files with your art) are typically called sprite sheets. Pi can decode them into Canvases and help you define sprites that you then blit onto the screen.

---

Keyboard, mouse, and gamepad input

Pi lets you check the state of buttons on various input devices. To make sure games work across different hardware, Pi defines a subset of buttons that exist on most modern keyboards, mice, and gamepads.

Pi also tries to offer only the kinds of input that were typical in the 16-bit era. For example, mice had just two buttons, and gamepads had only simple digital (on/off) buttons — no analog sticks or triggers.

For handling input devices, you can use these packages: pikey, pimouse, and pipad.

---

Concurrency

Most of Pi's code is not thread-safe. This is an intentional design choice to significantly improve performance.
You should not call Pi's API from any goroutine other than the one running your pi.Update and pi.Draw functions.

You can still create your own goroutines in your game, but they must not call any Pi functions or access Pi state (unless the package documentation explicitly says it's safe).

---

Philosophy: Limitations Make It Fun

Pi intentionally limits:

• resolution
• color palette

These constraints force you to be creative and keep things simple. It's easier to finish a game when you don't try to do everything at once. The goal is to have fun, not get lost in complexity!

FAQ

Is Pi ready to use?

Yes — the core functionality is implemented and ready to use.
Currently, the focus is on developer tools like piscope.

Note: Pi does not yet include built-in APIs for sound effects or music playback. However, you can use Ebitengine's audio API to play OGG or MP3 files, or the external Go module quasilyte/xm to play XM tracker files.

What similarities does Pi have with Pico-8 on the API level?

• Many core concepts are similar: game loop, drawing sprites and shapes, printing text, clipping, camera movement, palette swapping, and handling input. Some functions even share the same names.
• The screen resolution is small and the number of colors is limited — just like in Pico-8.
  However, in Pi you can freely change the resolution and customize the palette.

Can I use Pi in a game that already uses Ebitengine?

Yes! You can use the piebiten package to integrate Pi with your existing Ebitengine project. For example, you can copy pixel data from pi.Canvas into an ebiten.Image.

What platforms do Pi games run on?

Pi runs on all platforms supported by Ebitengine. However, it is currently tested only on Windows, Linux, and web browsers.

Can I write my own backend for Pi instead of Ebitengine?

Yes! You can create a specialized backend that runs on unusual devices or is optimized for a specific architecture. For example, there's piweb — an experimental backend for web browsers. Its goal is to cut the size of the generated WASM program roughly in half, which can be important for small browser-based games.

How can I contribute to Pi's development?

The best way to help Pi grow is by creating your own packages that add new or improved features. Pi is designed so that anyone can extend it without needing to contribute code directly to the main Pi repository.
Examples of useful packages include:

• developer tools that other programmers can run directly in their games
• packages for generating sound
• packages for drawing
• new backends

What tools are recommended for making games with Pi?

First of all, you'll need a good Go editor. I recommend GoLand (paid) or Visual Studio Code.

For creating sprites, I highly recommend Aseprite — probably the best pixel-art editor ever made. It has tons of features, scripting support, and can export images with metadata. In general, try to use the same color indices in your graphics program and in your game code. It really simplifies game development. Aseprite is one of the tools that supports editing images with indexed colors.

For creating tile maps, I recommend Tiled.

How can I persist game state or settings?

Pi itself doesn't include built-in save/load APIs. To store your game's progress or settings, you can use the external Go module quasilyte/gdata.

I have more questions or found a bug. Where can I ask?

Please open an Issue or start a Discussion on GitHub. Questions, ideas, bug reports, and contributions are all welcome!

Attributions

• picofont package uses original Pico-8 font created by Zep - CC-0 license
• default palette is the original Picotron palette created by Zep

Documentation

Overview

Package pi provides the core Pi functions for the game loop, screen, color palette, and drawing pixels, shapes, and sprites.

This package and all other pi* packages are not thread-safe. This is an intentional design choice to significantly improve performance. You should not call Pi's API from any goroutine other than the one running your `pi.Update` and `pi.Draw` functions. You can still create your own goroutines in your game, but they must not call any Pi functions or access Pi state.

Index

• Constants
• Variables
• func Blit(src Canvas, x int, y int)
• func Circ(cx, cy, r int)
• func CircFill(centerX, centerY, radius int)
• func Cls()
• func Line(x0, y0, x1, y1 int)
• func Pal(fromColor, toColor Color)
• func Palt(color Color, t bool)
• func Rect(x0, y0, x1, y1 int)
• func RectFill(x0 int, y0 int, x1 int, y1 int)
• func ResetColorTables()
• func ResetPalette()
• func ResetPaletteMapping()
• func SetPixel(x, y int)
• func SetScreenSize(width, height int)
• func Spr(sprite Sprite, dx, dy int)
• func Stretch(sprite Sprite, dx, dy, dw, dh int)
• type Area
  • func (a Area[T]) ClippedBy(clip Area[T]) (_ Area[T], dx, dy T)
  • func (a Area[T]) Contains(x, y T) bool
  • func (a Area[T]) MovedBy(dx, dy T) Area[T]
  • func (a Area[T]) Size() T
  • func (a Area[T]) WithH(h T) Area[T]
  • func (a Area[T]) WithW(w T) Area[T]
  • func (a Area[T]) WithX(x T) Area[T]
  • func (a Area[T]) WithY(y T) Area[T]
• type Canvas
  • func DecodeCanvas(pngFile []byte) Canvas
  • func DecodeCanvasOrErr(pngFile []byte) (Canvas, error)
  • func DrawTarget() Canvas
  • func NewCanvas(w, h int) Canvas
  • func Screen() Canvas
  • func SetDrawTarget(c Canvas) (prev Canvas)
• type Color
  • func GetColor() Color
  • func GetPixel(x, y int) (color Color)
  • func SetColor(c Color) (prev Color)
• type ColorTable
  • func (p ColorTable) String() string
• type IntArea
  • func Clip() IntArea
  • func SetClip(area IntArea) (prev IntArea)
• type Number
• type PaletteArray
  • func DecodePalette(pngFile []byte) PaletteArray
  • func DecodePaletteOrErr(pngFile []byte) (PaletteArray, error)
  • func (p PaletteArray) String() string
• type PaletteMap
  • func (p PaletteMap) String() string
• type Position
  • func (p Position) Add(other Position) Position
  • func (p Position) Subtract(other Position) Position
  • func (p Position) WithX(x int) Position
  • func (p Position) WithY(y int) Position
• type RGB
  • func FromRGB(r, g, b uint8) RGB
  • func FromRGBf(r, g, b float64) RGB
  • func (rgb RGB) RGB() (r, g, b uint8)
  • func (rgb RGB) RGBf() (r, g, b float64)
  • func (rgb RGB) String() string
• type Sprite
  • func CanvasSprite(canvas Canvas) Sprite
  • func SpriteFrom(canvas Canvas, x, y, w, h int) Sprite
  • func (s Sprite) String() string
  • func (s Sprite) WithFlipX(flip bool) Sprite
  • func (s Sprite) WithFlipY(flip bool) Sprite
  • func (s Sprite) WithSize(w, h int) Sprite
  • func (s Sprite) WithSizeScaled(w, h float64) Sprite
  • func (s Sprite) WithSource(source Canvas) Sprite
• type Surface
  • func NewSurface[T any](w, h int) Surface[T]
  • func (m Surface[T]) Clear(v T)
  • func (m Surface[T]) Clone() Surface[T]
  • func (m Surface[T]) CloneArea(area IntArea) Surface[T]
  • func (m Surface[T]) Data() []T
  • func (m Surface[T]) EntireArea() IntArea
  • func (m Surface[T]) FlatIndex(x, y int) int
  • func (m Surface[T]) Get(x, y int) T
  • func (m Surface[T]) Get2(x, y int) (T, T)
  • func (m Surface[T]) Get3(x, y int) (T, T, T)
  • func (m Surface[T]) GetLine(y int) []T
  • func (m Surface[T]) H() int
  • func (m Surface[T]) LinesIterator(area IntArea) iter.Seq2[Position, []T]
  • func (m Surface[T]) Set(x, y int, value T)
  • func (m Surface[T]) SetAll(values ...T)
  • func (m Surface[T]) SetArea(area IntArea, values ...T)
  • func (m Surface[T]) SetData(data []T)
  • func (m Surface[T]) SetMany(x, y int, values ...T)
  • func (m Surface[T]) SetSurface(x int, y int, src Surface[T])
  • func (m Surface[T]) String() string
  • func (m Surface[T]) W() int

Constants

const MaxColors = 64

MaxColors is the maximum number of colors that can be used simultaneously on the screen.

Variables

var (
	// Update is a user-provided function called every frame.
	//
	// This function handles user input, performs calculations, and updates
	// the game state. Typically, it does not draw anything on the screen.
	Update = func() {}

	// Draw is a user-provided function called up to once per frame.
	// Pi may skip calling this function if the previous frame took too long.
	//
	// The purpose of this function is to draw to the screen.
	Draw = func() {}
)

Game-loop function callbacks.

var (
	// Frame is the current game frame number.
	//
	// It is automatically incremented by the backend at the start of each game frame.
	Frame int

	// Time is the current game time in seconds.
	//
	// It is automatically incremented by the backend at the start of each frame.
	Time float64
)

var ColorTables [4]ColorTable

ColorTables defines 4 different ColorTable entries, selected based on bits 6 and 7 in the Color value.

When drawing a draw (source) color over a target (background) color, the following operation is performed:

(source | target) >> 6

The result of this operation determines the index of the ColorTable to use.

var TPS = 30

TPS defines the ticks per second.

You can change TPS while the game is running.

Functions

func Blit

func Blit(src Canvas, x int, y int)

Blit draws the contents of the src Canvas at (x, y) on the current draw target.

It takes into account the camera position, clipping region, color tables, and masks.

func Circ

func Circ(cx, cy, r int)

Circ draws the outline of a circle with center at (cx, cy) and radius r.

It takes into account the camera position, clipping region, color tables, and masks.

func CircFill

func CircFill(centerX, centerY, radius int)

CircFill draws a filled circle with center at (centerX, centerY) and the given radius.

It takes into account the camera position, clipping region, color tables, and masks.

func Cls

func Cls()

Cls clears the screen using color 0.

func Line

func Line(x0, y0, x1, y1 int)

Line draws a line on the screen between (x0, y0) and (x1, y1), inclusive.

It takes into account the camera position, clipping region, color tables, and masks.

func Pal

func Pal(fromColor, toColor Color)

func Palt

func Palt(color Color, t bool)

func Rect

func Rect(x0, y0, x1, y1 int)

Rect draws the outline of a rectangle between (x0, y0) and (x1, y1), inclusive.

It takes into account the camera position, clipping region, color tables, and masks.

func RectFill

func RectFill(x0 int, y0 int, x1 int, y1 int)

RectFill draws a filled rectangle between (x0, y0) and (x1, y1), inclusive.

It takes into account the camera position, clipping region, color tables, and masks.

func ResetColorTables

func ResetColorTables()

func ResetPalette

func ResetPalette()

ResetPalette resets the palette to the default Picotron palette.

func ResetPaletteMapping

func ResetPaletteMapping()

func SetPixel

func SetPixel(x, y int)

SetPixel sets the draw color at the given coordinates.

It takes into account the camera position, clipping region, color tables, and masks.

func SetScreenSize

func SetScreenSize(width, height int)

SetScreenSize sets the screen size in pixels.

The current screen will be replaced with a new, cleared screen. The new screen also automatically becomes the current draw target.

The maximum number of pixels is 131072 (128 KB).

func Spr

func Spr(sprite Sprite, dx, dy int)

Spr draws the given sprite at (dx, dy) on the current draw target.

It takes into account the camera position, clipping region, color tables, and masks.

func Stretch

func Stretch(sprite Sprite, dx, dy, dw, dh int)

Stretch draws the given sprite stretched to the specified size.

dx, dy specify the position on the current draw target. dw, dh specify the width and height on the current draw target.

It takes into account the camera position, clipping region, color tables, and masks.

Types

type Area

type Area[T Number] struct {
	X, Y, W, H T
}

Area specifies rectangular boundaries on a Surface.

It is used by Sprite, SetClip, Surface.CloneArea, Surface.LinesIterator, and others.

func (Area[T]) ClippedBy

func (a Area[T]) ClippedBy(clip Area[T]) (_ Area[T], dx, dy T)

ClippedBy clips the area so it does not extend beyond the given clip region.

In addition to the new area, it also returns how much it was shifted. The output parameters dx and dy are always positive.

func (Area[T]) Contains

func (a Area[T]) Contains(x, y T) bool

Contains reports whether the point (x, y) is inside the Area.

func (Area[T]) MovedBy

func (a Area[T]) MovedBy(dx, dy T) Area[T]

MovedBy returns a new Area moved by dx and dy.

func (Area[T]) Size

func (a Area[T]) Size() T

Size returns the number of values in the area.

func (Area[T]) WithH

func (a Area[T]) WithH(h T) Area[T]

WithH returns a new Area with the H value updated.

func (Area[T]) WithW

func (a Area[T]) WithW(w T) Area[T]

WithW returns a new Area with the W value updated.

func (Area[T]) WithX

func (a Area[T]) WithX(x T) Area[T]

WithX returns a new Area with the X value updated.

func (Area[T]) WithY

func (a Area[T]) WithY(y T) Area[T]

WithY returns a new Area with the Y value updated.

type Canvas

type Canvas = Surface[Color]

Canvas is used to store pixels

func DecodeCanvas

func DecodeCanvas(pngFile []byte) Canvas

DecodeCanvas decodes a PNG file into a Canvas using the current Palette.

Must be called after the Palette has been set.

This function can be slow for large images that do not use indexed color mode, or that use indexed color mode with a different palette. Whenever possible, use images with indexed color mode and the same Palette. Doing so will also simplify your workflow, since you can inspect color indexes directly in your graphics editor.

func DecodeCanvasOrErr

func DecodeCanvasOrErr(pngFile []byte) (Canvas, error)

DecodeCanvasOrErr is like DecodeCanvas but returns an error.

This function is useful when you need to validate user-provided PNG data. It returns an error if the input is not a valid PNG file or if the image contains more than 256 colors.

func DrawTarget

func DrawTarget() Canvas

func NewCanvas

func NewCanvas(w, h int) Canvas

NewCanvas creates a new Canvas with the specified dimensions.

func Screen

func Screen() Canvas

func SetDrawTarget

func SetDrawTarget(c Canvas) (prev Canvas)

SetDrawTarget sets c as the target Canvas for all subsequent drawing, including functions like Spr, SetPixel, Line, etc.

This function also automatically sets the clip region to cover the entire area of c.

type Color

type Color = uint8

Color represents a pixel color value in the range 0..63 (first 6 bits). Bits 6 and 7 specify the ColorTable index.

var (
	// ReadMask is the mask applied when reading the draw color.
	ReadMask Color = MaxColors - 1

	// TargetMask is the mask used when reading the target color in sprite operations.
	TargetMask Color = MaxColors - 1

	// ShapeTargetMask is the mask used when reading the target color in shape operations.
	ShapeTargetMask Color = MaxColors - 1
)

Masks used by drawing operations.

These define which bits of the color value are considered when reading or writing pixels.

func GetColor

func GetColor() Color

GetColor returns the current draw color.

func GetPixel

func GetPixel(x, y int) (color Color)

GetPixel returns the color at the given coordinates.

It takes into account the camera position and the clipping region.

func SetColor

func SetColor(c Color) (prev Color)

SetColor sets the current draw color.

Returns the previous color.

type ColorTable

type ColorTable [MaxColors][MaxColors]Color

ColorTable defines the color mapping rules used during drawing.

The first index is the draw (source) color index, and the second is the target (background) color index.

For example:

colorTable[7][0] = 6

means drawing color 7 over color 0 will result in color 6.

See more about color tables:

https://www.lexaloffle.com/bbs/?tid=149249

func (ColorTable) String

func (p ColorTable) String() string

type IntArea

type IntArea = Area[int]

IntArea is an Area with integer coordinates.

func Clip

func Clip() IntArea

func SetClip

func SetClip(area IntArea) (prev IntArea)

SetClip sets the clipping region to the specified area.

Returns the previous clipping area.

type Number

type Number interface {
	~int | ~float64 |
		~int8 | ~int16 | ~int32 | ~int64 |
		~float32 |
		~uint | ~byte | ~uint16 | ~uint32 | ~uint64
}

Number describes any numeric type in Go.

Includes signed integers, unsigned integers, and floating-point types.

type PaletteArray

type PaletteArray [MaxColors]RGB

PaletteArray maps each Color to an RGB value.

The array index is the Color, and the value is the RGB color, e.g., 0xFF00FF.

var Palette PaletteArray = defaultPalette()

Palette is the global color palette used before the final rendering of the Screen contents to the game window. It maps Color values to RGB.

The array index is the Color value, and the element is the RGB color, e.g., 0xFF00FF.

func DecodePalette

func DecodePalette(pngFile []byte) PaletteArray

DecodePalette extracts a palette from a PNG file.

• If the file uses an indexed palette, colors are read directly with their assigned indices.
• Otherwise, all unique colors are read and assigned indices automatically. Scanning starts from the top-left pixel and proceeds line by line.

func DecodePaletteOrErr

func DecodePaletteOrErr(pngFile []byte) (PaletteArray, error)

DecodePaletteOrErr works like DecodePalette but returns an error if the PNG file is invalid or contains too many colors.

func (PaletteArray) String

func (p PaletteArray) String() string

type PaletteMap

type PaletteMap [MaxColors]Color

PaletteMap defines the color mapping for display.

The array index is the original color, and the value is the mapped color.

var PaletteMapping PaletteMap = notSwappedPaletteMapping()

PaletteMapping defines the color mapping for display.

Colors are remapped at the end of each frame, just before rendering the contents of the Screen to the game window.

The array index is the original color, and the value is the mapped color.

func (PaletteMap) String

func (p PaletteMap) String() string

type Position

type Position struct{ X, Y int }

Position represents a 2D integer coordinate.

It stores X and Y values in a 2D grid.

var Camera Position

Camera is the camera offset applied to all subsequent draw operations.

func (Position) Add

func (p Position) Add(other Position) Position

Add returns a new Position after adding coordinates with other

func (Position) Subtract

func (p Position) Subtract(other Position) Position

Subtract returns a new Position after subtracting coordinates with other

func (Position) WithX

func (p Position) WithX(x int) Position

WithX returns a new Position with updated X.

func (Position) WithY

func (p Position) WithY(y int) Position

WithY returns a new Position with updated Y.

type RGB

type RGB uint32

RGB represents a color with three components: R (Red), G (Green), and B (Blue).

For example: black is 0x000000, white is 0xFFFFFF, green is 0x00FF00.

func FromRGB

func FromRGB(r, g, b uint8) RGB

FromRGB creates an RGB color from r, g, and b components.

func FromRGBf

func FromRGBf(r, g, b float64) RGB

FromRGBf creates an RGB value from normalized floating-point components.

The r, g, and b parameters should be in the range [0.0, 1.0]. Values are clamped, converted to 8-bit, and combined into a single RGB value.

func (RGB) RGB

func (rgb RGB) RGB() (r, g, b uint8)

RGB returns the red, green, and blue components as 8-bit values.

func (RGB) RGBf

func (rgb RGB) RGBf() (r, g, b float64)

RGBf returns the red, green, and blue components as normalized float values.

Each component is in the range [0.0, 1.0].

func (RGB) String

func (rgb RGB) String() string

type Sprite

type Sprite struct {
	Area[int]

	Source Canvas
	FlipX  bool
	FlipY  bool
}

Sprite represents a portion of a Canvas.

func CanvasSprite

func CanvasSprite(canvas Canvas) Sprite

CanvasSprite returns a Sprite covering the entire canvas.

func SpriteFrom

func SpriteFrom(canvas Canvas, x, y, w, h int) Sprite

SpriteFrom creates a Sprite from the specified region of the canvas.

func (Sprite) String

func (s Sprite) String() string

func (Sprite) WithFlipX

func (s Sprite) WithFlipX(flip bool) Sprite

WithFlipX returns a new Sprite with the FlipX value updated.

func (Sprite) WithFlipY

func (s Sprite) WithFlipY(flip bool) Sprite

WithFlipY returns a new Sprite with the FlipY value updated.

func (Sprite) WithSize

func (s Sprite) WithSize(w, h int) Sprite

WithSize returns a new Sprite with its size set to the given w and h.

func (Sprite) WithSizeScaled

func (s Sprite) WithSizeScaled(w, h float64) Sprite

WithSizeScaled returns a new Sprite scaled by w and h.

func (Sprite) WithSource

func (s Sprite) WithSource(source Canvas) Sprite

WithSource returns a new Sprite with its Source set to the given Canvas.

type Surface

type Surface[T any] struct {
	// contains filtered or unexported fields
}

Surface represents a 2D grid for storing arbitrary data.

Surface is a generic container that maps 2D coordinates (X, Y) to values of any type T. It can be used to represent game maps, tile layers, simulation grids, or any other 2D spatial data.

Surface is already used in Pi to store pixels in the Canvas type.

Example usage:

s := NewSurface[int](10, 10)
s.Set(3, 4, 42)
value := s.Get(3, 4)

func NewSurface

func NewSurface[T any](w, h int) Surface[T]

NewSurface creates a new Surface with the specified dimensions.

func (Surface[T]) Clear

func (m Surface[T]) Clear(v T)

func (Surface[T]) Clone

func (m Surface[T]) Clone() Surface[T]

func (Surface[T]) CloneArea

func (m Surface[T]) CloneArea(area IntArea) Surface[T]

CloneArea clones the specified area of the surface.

If the area extends outside the bounds, the missing regions are filled with zero values.

func (Surface[T]) Data

func (m Surface[T]) Data() []T

func (Surface[T]) EntireArea

func (m Surface[T]) EntireArea() IntArea

func (Surface[T]) FlatIndex

func (m Surface[T]) FlatIndex(x, y int) int

FlatIndex returns the index in Surface.Data for the given coordinates.

func (Surface[T]) Get

func (m Surface[T]) Get(x, y int) T

Get returns the value at the given coordinates.

If the coordinates are out of bounds, it returns the zero value of T.

func (Surface[T]) Get2

func (m Surface[T]) Get2(x, y int) (T, T)

Get2 returns zero value if there are no more elements.

func (Surface[T]) Get3

func (m Surface[T]) Get3(x, y int) (T, T, T)

Get3 returns zero value if there are no more elements.

func (Surface[T]) GetLine

func (m Surface[T]) GetLine(y int) []T

Returns nil if y is out of bounds

func (Surface[T]) H

func (m Surface[T]) H() int

func (Surface[T]) LinesIterator

func (m Surface[T]) LinesIterator(area IntArea) iter.Seq2[Position, []T]

LinesIterator returns an iterator for reading and writing data in lines.

This is a very efficient way to process regions in 2D space. LinesIterator enables writing advanced, low-level code.

The area must be clipped by m; otherwise, it will panic.

func (Surface[T]) Set

func (m Surface[T]) Set(x, y int, value T)

func (Surface[T]) SetAll

func (m Surface[T]) SetAll(values ...T)

func (Surface[T]) SetArea

func (m Surface[T]) SetArea(area IntArea, values ...T)

func (Surface[T]) SetData

func (m Surface[T]) SetData(data []T)

func (Surface[T]) SetMany

func (m Surface[T]) SetMany(x, y int, values ...T)

func (Surface[T]) SetSurface

func (m Surface[T]) SetSurface(x int, y int, src Surface[T])

func (Surface[T]) String

func (m Surface[T]) String() string

func (Surface[T]) W

func (m Surface[T]) W() int