cozely

README

Cozely

Cozely aims to be a simple, all-in-one framework for making games in Go. It focuses on pixel art for 2D, and polygonal art (aka low-poly) for 3D.

THIS IS A WORK IN PROGRESS, not usable yet: the framework is very incomplete, and the API is subject to frequent changes.

Platforms

The framework currently supports windows and linux.

Dependencies

The only dependancies are SDL 2 and OpenGL 4.6.

License

The code is under a simplified BSD license (see LICENSE file). When a sub-package is derived from another source, the directory contain the appropriate LICENSE file.

Credits

The Perlin and Simplex noise functions are adapted from "Simplex Noise Demystified" by Stefan Gustavson (code in the public domain).

The pixel font was originally based on "Pixel Operator Mono" by Jayvee Enayas, but has been so modified that it's now a completely different font. It is still licensed under the SIL OFL.

Some implementations of the single-precision math functions are derived from the Go source code (BSD-style license).

Documentation

Overview

Package cozely is the starting point of the Cozely framework, a simple, all-in-one set of packages for making games in Go.

It focuses on pixel art for 2D, and polygonal art (aka low-poly) for 3D, supports windows and linux, and has only two dependencies (SDL2 and Opengl 4.6).

**THIS IS A WORK IN PROGRESS**, not usable yet: the framework is *very* incomplete, and the API is subject to frequent changes.

Hello World example:

package main

import (
	"github.com/cozely/cozely"
	"github.com/cozely/cozely/pixel"
)

func main() {
	cozely.Run(loop{})
}

type loop struct{}

func (loop) Enter()  {
	// Enter the game loop
}

func (loop) React()  {
	// React to user inputs
}

func (loop) Update() {
	// Update the game state
}

func (loop) Render() {
	// Render the game state
	pixel.Clear(1)
	cur := pixel.Cursor{}
	cur.Print("Hello, World!")
}

func (loop) Leave()  {
	// Leave the game loop
}

Example

package main

import (
	"math/rand"

	"github.com/cozely/cozely"
	"github.com/cozely/cozely/color"
	"github.com/cozely/cozely/input"
	"github.com/cozely/cozely/pixel"
)

// Declarations ////////////////////////////////////////////////////////////////

var (
	play = input.Button("Play")
)

type loop struct {
	logo       pixel.PictureID
	monochrome color.Palette
	colorful   color.Palette

	playing bool
}

// Initialization //////////////////////////////////////////////////////////////

func main() {
	defer cozely.Recover()

	l := loop{}
	l.setup()

	cozely.Configure(cozely.UpdateStep(1.0 / 3))
	err := cozely.Run(&l)
	if err != nil {
		panic(err)
	}
}

func (l *loop) setup() {
	pixel.SetResolution(pixel.XY{160, 100})
	l.logo = pixel.Picture("graphics/cozely")
	l.monochrome = color.PaletteFrom("graphics/cozely")
	l.colorful = color.PaletteFrom("")
}

func (l *loop) Enter() {
	pixel.SetPalette(l.monochrome)
}

func (loop) Leave() {
}

// Game Loop ///////////////////////////////////////////////////////////////////

func (l *loop) React() {
	if play.Pressed() {
		l.playing = !l.playing
		if l.playing {
			pixel.SetPalette(l.colorful)
			l.shufflecolors()
		} else {
			pixel.SetPalette(l.monochrome)
		}
	}
	if input.Close.Pressed() {
		cozely.Stop(nil)
	}
}

func (l *loop) Update() {
	if l.playing {
		l.shufflecolors()
	}
}

func (l *loop) shufflecolors() {
	for i := 2; i < 14; i++ {
		g := 0.2 + 0.7*rand.Float32()
		r := 0.2 + 0.7*rand.Float32()
		b := 0.2 + 0.7*rand.Float32()
		pixel.SetColor(color.Index(i), color.SRGB{r, g, b})
	}
}

func (l *loop) Render() {
	pixel.Clear(0)

	o := pixel.Resolution().Minus(l.logo.Size()).Slash(2)
	l.logo.Paint(0, o)
}

Index

• func Configure(c ...Option) error
• func Error() bool
• func GameTime() float64
• func Goto(l GameLoop)
• func Path() string
• func Recover()
• func RenderDelta() float64
• func RenderStats() (t float64, overruns int)
• func Run(loop GameLoop) (err error)
• func Stop(err error)
• func UpdateDelta() float64
• func UpdateLag() float64
• func Wrap(context string, err error) error
• type GameLoop
• type Option
  • func Multisample(s int32) Option
  • func Title(t string) Option
  • func UpdateStep(t float64) Option

Examples

• Package

Functions

func Configure

func Configure(c ...Option) error

Configure the framework.

func Error

func Error() bool

Error returns true if there is an unchecked error in one of Cozely's packages.

func GameTime

func GameTime() float64

GameTime returns the time elapsed in the game. It is updated before each call to Update and before each call to Render.

func Goto

func Goto(l GameLoop)

Goto replaces the current running loop with l. The change take place at next frame.

func Path

func Path() string

Path returns the (slash-separated) path of the executable, with a trailing slash.

func Recover

func Recover()

Recover is a convenience function. When called with defer at the start of the main function, it will intercept any panic, log the stack trace, and finally log any unchecked errors in Cozely's packages.

This function exists because many errors in the framework, in addition to setting the package's sticky error, also returns an invalid ID; if the error is unchecked and the ID used, this will trigger an "index out of range" panic.

func RenderDelta

func RenderDelta() float64

RenderDelta returns the time elapsed between the previous frame and the one being rendered.

See also UpdateDelta and UpdateLag.

func RenderStats

func RenderStats() (t float64, overruns int)

RenderStats returns the average durations of frames; it is updated 4 times per second. It also returns the number of overruns (i.e. frame time longer than the threshold) during the last measurment interval.

func Run

func Run(loop GameLoop) (err error)

Run initializes the framework, creates the ressources and loads all assets, and finally starts the game loop. The loop will run until Stop is called.

Important: Run must be called from main.main, or at least from a function that is known to run on the main OS thread.

func Stop

func Stop(err error)

Stop request the game loop to stop.

func UpdateDelta

func UpdateDelta() float64

UpdateDelta returns the time between previous update and current one. It is a fixed value, that only changes when configured with UpdateStep.

See also UpdateLag.

func UpdateLag

func UpdateLag() float64

UpdateLag returns the time elapsed between the last Update and the frame being rendered. It should be used during Render to extrapolate (or interpolate) the game state.

See also UpdateTime and RenderDelta.

func Wrap

func Wrap(context string, err error) error

Wrap returns nil if err is nil, or a wrapped error otherwise.

Types

type GameLoop

type GameLoop interface {
	// Enter is called once, after the framework initialization, but before the
	// loop is started.
	Enter()

	// Leave is called when the loop is stopped.
	Leave()

	// React is called as often as possible, before Update and Render, to react to
	// the player's actions. This is the only method that is guaranteed to run at
	// least once per frame.
	React()

	// Update is called at fixed intervals, to update the game state (e.g. logic,
	// physics, AI...).
	Update()

	// Render is called to display the game state to the player.
	//
	// Note that the framerate of Update and Render is independent, so the game
	// state might need to be interpolated (see UpdateLag).
	Render()
}

GameLoop methods are called in a loop to React to player actions, Update the game state, and Render it.

type Option

type Option = func() error

An Option represents a configuration option used to change some parameters of the framework: see Configure.

func Multisample

func Multisample(s int32) Option

Multisample activate multisampling for the game window. Note that this is currently incompatible with the pixel package.

func Title

func Title(t string) Option

Title sets the title of the game.

func UpdateStep

func UpdateStep(t float64) Option

UpdateStep sets the time step between calls to Update.