pi

README

pi

The retro game development engine for Go, inspired by Pico-8 and powered by Ebitengine.

FAQ

Is this a new fantasy console?

No, it's not. It's rather a game development library with some additional tools (like a console) which make it simple (and fun!) to write retro games in Go.

What is a retro game?

It's a game that resembles old 8-bit/16-bit games. This usually means:

• (extremely) Low resolution (like 128x128 pixels)
• Limited number of colors (like 16)
• Very small number of assets (like 256 sprites, map having up to 8K tiles)
• Simple rules (opposite to Paradox grand strategy games)
• Simplified music and SFX

What similarities does Pi have with Pico-8?

• Most API function names are similar and behave the same way.
• Screen resolution is small, and the number of colors is limited. Although in Pi you can change the resolution and palette.
• You have one small sprite sheet and a map.

Why would I use it?

Because it's the easiest way to write a game in Go. IMHO ;)

Is Pi ready to use?

Pi is under development. Only limited functionality is provided. API is not stable. See roadmap for details.

Roadmap

• Present game on the screen
  • add the ability to change the resolution and palette
  • add sprite-sheet loader
  • add more options: full screen, specifying tps and scale
  • Time function
  • add a programmatic way to stop the game
• Implement Graphics API
  • drawing sprites and pixels with camera and clipping support
  • add the ability to directly access pixels on the screen and sprite-sheet
  • palette transparency
  • palette swapping
  • printing text on the screen
  • drawing shapes
    • lines, rectangles, circles, ovals
    • add support for fill patterns
  • math API
    • Cos, Sin, Atan2
    • Min, Max, Mid
  • stretching sprites
• Add keyboard support
• Add gamepad/joystick support
• Add mouse support
• Development console
  • pausing, resuming the game
  • running public functions
  • sprite-sheet editor
  • map editor
  • sound editor
  • music editor
• Documentation
  • Go docs
• Examples
  • simple programs for beginners
  • interactive programs describing how functions work
    • Sin,Cos,Atan2 visualization

Documentation

Overview

Package pi provides API to develop retro games.

Index

• Constants
• Variables
• func Atan2(dx, dy float64) float64
• func Boot() error
• func BootOrPanic()
• func Camera(x, y int) (prevX, prevY int)
• func CameraReset() (prevX, prevY int)
• func Clip(x, y, w, h int) (prevX, prevY, prevW, prevH int)
• func ClipReset() (prevX, prevY, prevW, prevH int)
• func Cls()
• func ClsCol(col byte)
• func Cos(angle float64) float64
• func Pget(x, y int) byte
• func Pset(x, y int)
• func Reset()
• func Run() error
• func RunOrPanic()
• func Sget(x, y int) byte
• func Sin(angle float64) float64
• func Spr(n, x, y int)
• func SprSize(n, x, y int, w, h float64)
• func SprSizeFlip(n, x, y int, w, h float64, flipX, flipY bool)
• func Sset(x, y int, color byte)
• func Time() float64

Constants

const (
	SpriteWidth, SpriteHeight = 8, 8
)

Variables

var (
	Update = func() {} // Update is a user provided function executed each frame.
	Draw   = func() {} // Draw is a user provided function executed each frame (if he can).

	Resources fs.ReadFileFS // Resources contains files like sprite-sheet.png

	// SpriteSheetWidth will be used if sprite-sheet.png was not found.
	SpriteSheetWidth = defaultSpriteSheetWidth
	// SpriteSheetHeight will be used if sprite-sheet.png was not found.
	SpriteSheetHeight = defaultSpriteSheetHeight

	// ScreenWidth specifies the width of the screen (in pixels).
	ScreenWidth = defaultScreenWidth
	// ScreenHeight specifies the height of the screen (in pixels).
	ScreenHeight = defaultScreenHeight
)

User parameters. Will be used during Boot (and Run).

var (
	Color byte = 6 // Color is a currently used color in draw state. Used by Pset.

	// Palette has all colors available in the game. Up to 256.
	// Palette is taken from loaded sprite sheet (which must be
	// a PNG file with indexed color mode). If sprite-sheet.png was not
	// found, then default 16 color palette is used.
	//
	// Can be freely read and updated. Changes will be visible immediately.
	Palette [256]image.RGB

	// ScreenData contains pixel colors for the screen visible by the player.
	// Each pixel is one byte. It is initialized during pi.Boot.
	//
	// Pixels on the screen are organized from left to right,
	// top to bottom. Slice element number 0 has pixel located
	// in the top-left corner. Slice element number 1 has pixel color
	// on the right and so on.
	//
	// Can be freely read and updated. Useful when you want to use your own
	// functions for pixel manipulation.
	// Pi will panic if you try to change the length of the slice.
	ScreenData []byte
)

Screen-specific data

var (
	// SpriteSheetData contains pixel colors for the entire sprite sheet.
	// Each pixel is one byte. It is initialized during pi.Boot.
	//
	// Pixels in the sprite-sheet are organized from left to right,
	// top to bottom. Slice element number 0 has pixel located
	// in the top-left corner. Slice element number 1 has a pixel color
	// on the right and so on.
	//
	// Can be freely read and updated.
	// Useful when you want to use your own functions for pixel manipulation.
	// Pi will panic if you try to change the length of the slice.
	SpriteSheetData []byte
)

Sprite-sheet data

Functions

func Atan2

func Atan2(dx, dy float64) float64

Atan2 converts DX, DY into an angle from 0..1

Similar to Cos and Sin, angle is taken to run anticlockwise in screenspace. For example:

atan(0,-1)  // returns 0.25

func Boot

func Boot() error

Boot initializes the engine based on user parameters such as ScreenWidth and ScreenHeight. It loads the resources like sprite-sheet.png.

func BootOrPanic

func BootOrPanic()

BootOrPanic does the same as Boot, but panics instead of returning an error.

Useful for writing unit tests and quick and dirty prototypes. Do not use on production ;)

func Camera

func Camera(x, y int) (prevX, prevY int)

Camera sets the camera offset used for all subsequent draw operations.

func CameraReset

func CameraReset() (prevX, prevY int)

CameraReset resets the camera offset to origin (0,0).

func Clip

func Clip(x, y, w, h int) (prevX, prevY, prevW, prevH int)

Clip sets the clipping region in the form of rectangle. All screen drawing operations will not affect any pixels outside the region.

Clip returns previous clipping region.

func ClipReset

func ClipReset() (prevX, prevY, prevW, prevH int)

ClipReset resets the clipping region, which means that entire screen will be clipped.

func Cls

func Cls()

Cls cleans the entire screen with color 0. It does not take into account any draw state parameters such as clipping region or camera.

func ClsCol

func ClsCol(col byte)

ClsCol cleans the entire screen with specified color. It does not take into account any draw state parameters such as clipping region or camera.

func Cos

func Cos(angle float64) float64

Cos returns the cosine of angle which is in the range of 0.0-1.0 measured clockwise.

If you want to use conventional radian-based function use math.Cos.

func Pget

func Pget(x, y int) byte

Pget gets a pixel color on the screen.

func Pset

func Pset(x, y int)

Pset sets a pixel color on the screen to Color.

func Reset

func Reset()

Reset resets all user parameters to default values. Useful in unit tests.

func Run

func Run() error

Run boots the game, opens the window and run the game loop.

It returns error when something terrible happened during initialization.

func RunOrPanic

func RunOrPanic()

RunOrPanic does the same as Run, but panics instead of returning an error.

Useful for writing unit tests and quick and dirty prototypes. Do not use on production ;)

func Sget

func Sget(x, y int) byte

Sget gets the pixel color on the sprite sheet.

func Sin

func Sin(angle float64) float64

Sin returns the sine of angle which is in the range of 0.0-1.0 measured clockwise.

Sin returns an inverted result to suit screen space (where Y means "DOWN", as opposed to mathematical diagrams where Y typically means "UP"):

sin(0.25) // returns -1

If you want to use conventional radian-based function without the y inversion, use math.Sin.

func Spr

func Spr(n, x, y int)

Spr draws a sprite with specified number on the screen. Sprites are counted from left to right, top to bottom. Sprite 0 is on top-left corner, sprite 1 is to the right and so on.

func SprSize

func SprSize(n, x, y int, w, h float64)

SprSize draws a range of sprites on the screen.

n is a sprite number in the top-left corner.

Non-integer w or h may be used to draw partial sprites.

func SprSizeFlip

func SprSizeFlip(n, x, y int, w, h float64, flipX, flipY bool)

SprSizeFlip draws a range of sprites on the screen.

TODO Flipping is not implemented yet

func Sset

func Sset(x, y int, color byte)

Sset sets the pixel color on the sprite sheet. It does not update the global Color.

func Time

func Time() float64

Time returns the amount of time since game was run, as a (fractional) number of seconds.

Calling Time() multiple times in the same frame will always return the same result.