oak

README

Oak

A Pure Go game engine

Table of Contents

1. Installation

2. Features

3. Support

4. Quick Start

5. Examples

6. Finished Games

---

Installation

go get -u github.com/oakmound/oak/v4

Features and Systems

1. Window Management
   • Windows and key events forked from shiny
   • Support for multiple windows running at the same time
2. Image Rendering
   • Manipulation
     • render.Modifiable interface
     • Integrated with optimized image manipulation via gift
   • Built in Renderable types covering common use cases
     • Sprite, Sequence, Switch, Composite
     • Primitive builders, ColorBox, Line, Bezier
     • History-tracking Reverting
   • Primarily 2D
3. Particle System
4. Mouse Handling
5. Joystick Support
6. Audio Support
7. Collision
   • Collision R-Tree forked from rtreego
   • 2D Raycasting
   • Collision Spaces
     • Attachable to Objects
     • Auto React to collisions through events
8. 2D Physics System
9. Event Handler

Support

For discussions not significant enough to be an Issue or PR, feel free to ping us in the #oak channel on the gophers slack. For insight into what is happening in oak see the blog.

Quick Start

This is an example of the most basic oak program:

package main

import (
    "github.com/oakmound/oak/v4"
    "github.com/oakmound/oak/v4/scene"
)

func main() {
    oak.AddScene("firstScene", scene.Scene{
        Start: func(*scene.Context) {
            // ... draw entities, bind callbacks ... 
        }, 
    })
    oak.Init("firstScene")
}

See below or navigate to the examples folder for demos. For more examples and documentation checkout godoc for reference documentation, the wiki, or our extended features in grove.

Examples

Platformer	Top down shooter	Flappy Bird
Bezier Curves	Joysticks	Piano
Screen Options	Multi Window	Particles

Games using Oak

To kick off a larger game project you can get started with game-template.

Agent Blue	Fantastic Doctor
Hiring Now: Looters	Jeremy The Clam
Diamond Deck Championship	SokoPic

On Pure Go

Oak has recently brought in dependencies that include C code, but we still describe the engine as a Pure Go engine, which at face value seems contradictory. Oak's goal is that, by default, a user can pull down the engine and create a fully functional game or GUI application on a machine with no C compiler installed, so when we say Pure Go we mean that, by default, the library is configured so no C compilation is required, and that no major features are locked behind C compliation.

We anticipate in the immediate future needing to introduce alternate drivers that include C dependencies for performance improvements in some scasenarios, and currently we have no OSX solution that lacks objective C code.

Documentation

Overview

Package oak is a game engine. It provides scene control, control over windows and what is drawn to them, propagates regular events to evaluate game logic, and so on.

A minimal oak app follows:

func main() {
	oak.AddScene("myApp", scene.Scene{Start: func(ctx *scene.Context) {
		// ... ctx.Draw(...), event.Bind(ctx, ...)
	}})
	oak.Init("myApp")
}

Index

• Variables
• func AddScene(name string, sc scene.Scene) error
• func Bounds() intgeom.Point2
• func GetCursorPosition() (x, y float64)
• func HideCursor() error
• func Init(scene string, configOptions ...ConfigOption) error
• func IsDown(k key.Code) bool
• func IsHeld(k key.Code) (bool, time.Duration)
• func MoveWindow(x, y, w, h int) error
• func ScreenShot() *image.RGBA
• func SetBackground(b Background)
• func SetBorderless(bs bool) error
• func SetColorBackground(img image.Image)
• func SetFS(filesystem fs.FS)
• func SetFullScreen(fs bool) error
• func SetIcon(icon image.Image) error
• func SetLoadingRenderable(r render.Renderable)
• func SetTitle(title string) error
• func SetTopMost(on bool) error
• func SetViewport(pt intgeom.Point2)
• func SetViewportBounds(rect intgeom.Rect2)
• func ShiftViewport(pt intgeom.Point2)
• func UpdateViewSize(w, h int) error
• type Assets
• type Background
• type BatchLoadOptions
• type Config
  • func NewConfig(opts ...ConfigOption) (Config, error)
• type ConfigOption
  • func FileConfig(filePath string) ConfigOption
  • func ReaderConfig(r io.Reader) ConfigOption
• type Debug
• type Driver
• type InputType
• type Screen
• type Viewport
• type Window
  • func NewWindow() *Window
  • func (w *Window) AddScene(name string, s scene.Scene) error
  • func (w *Window) Bounds() intgeom.Point2
  • func (w *Window) ChangeWindow(width, height int) error
  • func (w *Window) ClearScreenFilter()
  • func (w *Window) DoBetweenDraws(f func())
  • func (w *Window) EventHandler() event.Handler
  • func (w *Window) GetBackgroundImage() image.Image
  • func (w *Window) GoToScene(nextScene string)
  • func (w *Window) InFocus() bool
  • func (w *Window) Init(firstScene string, configOptions ...ConfigOption) error
  • func (w *Window) MostRecentInput() InputType
  • func (w *Window) NextScene()
  • func (w *Window) Propagate(ev event.EventID[*mouse.Event], me mouse.Event)
  • func (w *Window) Quit()
  • func (w *Window) RecordGIF(hundredths int) (stop func() *gif.GIF)
  • func (w *Window) RemoveViewportBounds()
  • func (w *Window) ScreenShot() *image.RGBA
  • func (w *Window) SetAspectRatio(xToY float64)
  • func (w *Window) SetBackground(b Background)
  • func (w *Window) SetColorBackground(img image.Image)
  • func (w *Window) SetDrawFilter(screenFilter mod.Filter)
  • func (w *Window) SetLoadingRenderable(r render.Renderable)
  • func (w *Window) SetLogicHandler(h event.Handler)
  • func (w *Window) SetPalette(palette color.Palette)
  • func (w *Window) SetViewport(pt intgeom.Point2)
  • func (w *Window) SetViewportBounds(rect intgeom.Rect2)
  • func (w *Window) ShiftViewport(delta intgeom.Point2)
  • func (w *Window) TriggerKeyDown(e okey.Event)
  • func (w *Window) TriggerKeyHeld(e okey.Event)
  • func (w *Window) TriggerKeyUp(e okey.Event)
  • func (w *Window) TriggerMouseEvent(mevent omouse.Event)
  • func (w *Window) UpdateViewSize(width, height int) error
  • func (w *Window) Viewport() intgeom.Point2
  • func (w *Window) ViewportBounds() (rect intgeom.Rect2, ok bool)

Variables

var (
	// ViewportUpdate is triggered when the position of of the viewport changes
	ViewportUpdate = event.RegisterEvent[intgeom.Point2]()
	// OnStop is triggered when the engine is stopped, e.g. when a window's close
	// button is clicked.
	OnStop = event.RegisterEvent[struct{}]()
	// FocusGain is triggered when a window gains focus
	FocusGain = event.RegisterEvent[struct{}]()
	// FocusLoss is triggered when a window loses focus
	FocusLoss = event.RegisterEvent[struct{}]()
	// InputChange is triggered when the most recent input device changes (e.g. keyboard to joystick or vice versa). It
	// is only sent if Config.TrackInputChanges is true when Init is called.
	InputChange = event.RegisterEvent[InputType]()
)

The following block defines events generated by oak during scene execution

Functions

func AddScene

func AddScene(name string, sc scene.Scene) error

AddScene calls AddScene on the default window.

func Bounds

func Bounds() intgeom.Point2

Bounds returns the default window's boundary.

func GetCursorPosition

func GetCursorPosition() (x, y float64)

GetCursorPosition calls GetCursorPosition on the default window.

func HideCursor

func HideCursor() error

HideCursor calls HideCursor on the default window.

func Init

func Init(scene string, configOptions ...ConfigOption) error

Init calls Init on the default window. The default window will be set to use render.GlobalDrawStack and event.DefaultBus.

func IsDown

func IsDown(k key.Code) bool

IsDown calls IsDown on the default window.

func IsHeld

func IsHeld(k key.Code) (bool, time.Duration)

IsHeld calls IsHeld on the default window.

func MoveWindow

func MoveWindow(x, y, w, h int) error

MoveWindow calls MoveWindow on the default window.

func ScreenShot

func ScreenShot() *image.RGBA

ScreenShot calls ScreenShot on the default window.

func SetBackground

func SetBackground(b Background)

SetBackground calls SetBackground on the default window.

func SetBorderless

func SetBorderless(bs bool) error

SetBorderless calls SetBorderless on the default window.

func SetColorBackground

func SetColorBackground(img image.Image)

SetColorBackground calls SetColorBackground on the default window.

func SetFS

func SetFS(filesystem fs.FS)

SetFS updates all calls oak or oak's subpackages will make to read from the given filesystem. By default, this is set to os.DirFS(".")

func SetFullScreen

func SetFullScreen(fs bool) error

SetFullScreen calls SetFullScreen on the default window.

func SetIcon

func SetIcon(icon image.Image) error

SetIcon calls SetIcon on the default window.

func SetLoadingRenderable

func SetLoadingRenderable(r render.Renderable)

SetLoadingRenderable calls SetLoadingRenderable on the default window.

func SetTitle

func SetTitle(title string) error

SetTitle calls SetTitle on the default window.

func SetTopMost

func SetTopMost(on bool) error

SetTopMost calls SetTopMost on the default window.

func SetViewport

func SetViewport(pt intgeom.Point2)

SetViewport calls SetViewport on the default window.

func SetViewportBounds

func SetViewportBounds(rect intgeom.Rect2)

SetViewportBounds calls SetViewportBounds on the default window.

func ShiftViewport

func ShiftViewport(pt intgeom.Point2)

ShiftViewport calls ShiftViewport on the default window.

func UpdateViewSize

func UpdateViewSize(w, h int) error

UpdateViewSize calls UpdateViewSize on the default window.

Types

type Assets

type Assets struct {
	AudioPath string `json:"audioPath"`
	ImagePath string `json:"imagePath"`
}

Assets is a json type storing paths to different asset folders

type Background

type Background interface {
	GetRGBA() *image.RGBA
}

A Background can be used as a background draw layer. Backgrounds will be drawn as the first element in each frame, and are expected to cover up data drawn on the previous frame.

type BatchLoadOptions

type BatchLoadOptions struct {
	BlankOutAudio    bool  `json:"blankOutAudio"`
	MaxImageFileSize int64 `json:"maxImageFileSize"`
}

BatchLoadOptions is a json type storing customizations for batch loading. These settings do not take effect unless Config.BatchLoad is true.

type Config

type Config struct {
	Driver Driver `json:"-"`
	// Assets defines where assets should be loaded from by default. Defaults to
	// 'assets/audio' and 'assets/images'.
	Assets           Assets           `json:"assets"`
	Debug            Debug            `json:"debug"`
	Screen           Screen           `json:"screen"`
	BatchLoadOptions BatchLoadOptions `json:"batchLoadOptions"`
	// FrameRate, representing the rate enter frame events are triggered, defaults to 60.
	FrameRate int `json:"frameRate"`
	// DrawFrameRate is ignored on JS. It defaults to 60.
	DrawFrameRate int `json:"drawFrameRate"`
	// IdleDrawFrameRate defaults to 60. When a window goes out of focus, this setting can be lowered to
	// reduce resource consumption by drawing.
	IdleDrawFrameRate int `json:"idleDrawFrameRate"`
	// Language defines the language oak logs are attempted to be translated to. Defaults to English.
	Language string `json:"language"`
	// Title defaults to 'Oak Window'.
	Title               string `json:"title"`
	BatchLoad           bool   `json:"batchLoad"`
	GestureSupport      bool   `json:"gestureSupport"`
	LoadBuiltinCommands bool   `json:"loadBuiltinCommands"`
	TrackInputChanges   bool   `json:"trackInputChanges"`
	// EnableDebugConsole is ignored on JS.
	EnableDebugConsole bool `json:"enableDebugConsole"`
	TopMost            bool `json:"topmost"`
	Borderless         bool `json:"borderless"`
	Fullscreen         bool `json:"fullscreen"`
	SkipRNGSeed        bool `json:"skip_rng_seed"`
	// UnlimitedDrawFrameRate is ignored on JS (it is effectively always true).
	UnlimitedDrawFrameRate bool `json:"unlimitedDrawFrameRate"`
}

A Config defines the settings oak accepts on initialization. Some of these settings may be ignored depending on the target platform.

func NewConfig

func NewConfig(opts ...ConfigOption) (Config, error)

NewConfig creates a config from a set of transformation options.

type ConfigOption

type ConfigOption func(Config) (Config, error)

A ConfigOption transforms a Config object.

func FileConfig

func FileConfig(filePath string) ConfigOption

FileConfig loads a config file, that could exist inside oak's binary data storage (see fileutil), to SetupConfig

func ReaderConfig

func ReaderConfig(r io.Reader) ConfigOption

ReaderConfig reads a Config as json from the given reader.

type Debug

type Debug struct {
	Filter string `json:"filter"`
	Level  string `json:"level"`
}

Debug is a json type storing the starting debug filter and level

type Driver

type Driver func(f func(screen.Screen))

A Driver is a function which can take in our lifecycle function and initialize oak with the OS interfaces it needs.

type InputType

type InputType int32

InputType expresses some form of input to the engine to represent a player

const (
	InputNone InputType = iota
	InputKeyboard
	InputMouse
	InputJoystick
)

The following constants define valid types of input sent via the InputChange event.

type Screen

type Screen struct {
	X      int     `json:"X"`
	Y      int     `json:"Y"`
	Height int     `json:"height"`
	Width  int     `json:"width"`
	Scale  float64 `json:"scale"`
}

Screen is a json type storing the starting screen width and height

type Viewport

type Viewport struct {
	Position       intgeom.Point2
	Bounds         intgeom.Rect2
	BoundsEnforced bool
}

type Window

type Window struct {
	// The keyboard state this window is aware of.
	key.State

	// the driver.Window embedded in this window exposes at compile time the OS level
	// options one has to manipulate this.
	*driver.Window

	// ScreenWidth is the width of the screen
	ScreenWidth int
	// ScreenHeight is the height of the screen
	ScreenHeight int

	// FrameRate is the current logical frame rate.
	// Changing this won't directly effect frame rate, that
	// requires changing the LogicTicker, but it will take
	// effect next scene
	FrameRate int

	// DrawFrameRate is the equivalent to FrameRate for
	// the rate at which the screen is drawn.
	DrawFrameRate int

	// IdleDrawFrameRate is how often the screen will be redrawn
	// when the window is out of focus.
	IdleDrawFrameRate int

	// DrawTicker is the parallel to LogicTicker to set the draw framerate
	DrawTicker *time.Ticker

	// SceneMap is a global map of scenes referred to when scenes advance to
	// determine what the next scene should be.
	// It can be replaced or modified so long as these modifications happen
	// during a scene or before the controller has started.
	SceneMap *scene.Map

	// Driver is the driver oak will call during initialization
	Driver Driver

	// LoadingR is a renderable that is displayed during loading screens.
	LoadingR render.Renderable

	// ErrorScene is a scene string that will be entered if the scene handler
	// fails to enter some other scene, for example, because it's name was
	// undefined in the scene map. If the scene map does not have ErrorScene
	// as well, it will fall back to panicking.
	ErrorScene string

	CallerMap     *event.CallerMap
	MouseTree     *collision.Tree
	CollisionTree *collision.Tree
	DrawStack     *render.DrawStack

	// LastMouseEvent is the last triggered mouse event,
	// tracked for continuous mouse responsiveness on events
	// that don't take in a mouse event
	LastMouseEvent         mouse.Event
	LastRelativeMouseEvent mouse.Event

	// LastPress is the last triggered mouse event,
	// where the mouse event was a press.
	// If TrackMouseClicks is set to false then this will not be tracked
	LastMousePress mouse.Event

	FirstSceneInput interface{}

	ControllerID int32

	ParentContext context.Context

	// UseAspectRatio determines whether new window changes will distort or
	// maintain the relative width to height ratio of the screen buffer.
	UseAspectRatio bool
	// contains filtered or unexported fields
}

func NewWindow

func NewWindow() *Window

NewWindow creates a window with default settings.

func (*Window) AddScene

func (w *Window) AddScene(name string, s scene.Scene) error

AddScene is shorthand for w.SceneMap.AddScene

func (*Window) Bounds

func (w *Window) Bounds() intgeom.Point2

Width returns the absolute bounds of a window in pixels. It does not include window elements outside of the client area (OS provided title bars).

func (*Window) ChangeWindow

func (w *Window) ChangeWindow(width, height int) error

ChangeWindow sets the width and height of the game window. Although exported, calling it without a size event will probably not act as expected.

func (*Window) ClearScreenFilter

func (w *Window) ClearScreenFilter()

ClearScreenFilter resets the draw function to no longer filter the screen before publishing it to the window.

func (*Window) DoBetweenDraws

func (w *Window) DoBetweenDraws(f func())

DoBetweenDraws will execute the given function in-between draw frames. It will prevent draws from happening until the provided function has terminated. DoBetweenDraws will block until the provided function is called within the draw loop's schedule, but will not wait for that function itself to terminate.

func (*Window) EventHandler

func (w *Window) EventHandler() event.Handler

EventHandler returns this window's event handler.

func (*Window) GetBackgroundImage

func (w *Window) GetBackgroundImage() image.Image

GetBackgroundImage returns the image this window will display as its background

func (*Window) GoToScene

func (w *Window) GoToScene(nextScene string)

GoToScene causes this window to skip directly to the given scene.

func (*Window) InFocus

func (w *Window) InFocus() bool

InFocus returns whether this window is currently in focus.

func (*Window) Init

func (w *Window) Init(firstScene string, configOptions ...ConfigOption) error

Init initializes the oak engine. After the configuration options have been parsed and validated, this will run concurrent routines drawing to an OS window or app, forwarding OS inputs to this window's configured event handler, and running scenes: first the predefined 'loading' scene, then firstScene as provided here, then scenes following commands sent to the window or returned by ending scenes.

func (*Window) MostRecentInput

func (w *Window) MostRecentInput() InputType

MostRecentInput returns the most recent input type (e.g keyboard/mouse or joystick) recognized by the window. This value will only change if the window is set to TrackInputChanges

func (*Window) NextScene

func (w *Window) NextScene()

NextScene causes this window to immediately end the current scene.

func (*Window) Propagate

func (w *Window) Propagate(ev event.EventID[*mouse.Event], me mouse.Event)

Propagate triggers direct mouse events on entities which are clicked

func (*Window) Quit

func (w *Window) Quit()

Quit sends a signal to the window to close itself, closing the window and any spun up resources. It should not be called before Init. After it is called, it must not be called again.

func (*Window) RecordGIF

func (w *Window) RecordGIF(hundredths int) (stop func() *gif.GIF)

RecordGIF will start recording frames via screen shots with the given time delay (in 1/100ths of a second) between frames. When the returned stop function is called, the frames will be compiled into a gif.

func (*Window) RemoveViewportBounds

func (w *Window) RemoveViewportBounds()

RemoveViewportBounds removes restrictions on the viewport's movement. It will not cause the viewport to update immediately.

func (*Window) ScreenShot

func (w *Window) ScreenShot() *image.RGBA

ScreenShot takes a snap shot of the window's image content. ScreenShot is not safe to call while an existing ScreenShot call has yet to finish executing. This could change in the future.

func (*Window) SetAspectRatio

func (w *Window) SetAspectRatio(xToY float64)

SetAspectRatio will enforce that the displayed window does not distort the input screen away from the given x:y ratio. The screen will not use these settings until a new size event is received from the OS.

func (*Window) SetBackground

func (w *Window) SetBackground(b Background)

SetBackground sets this window's background.

func (*Window) SetColorBackground

func (w *Window) SetColorBackground(img image.Image)

SetColorBackground sets this window's background to be a standard image.Image, commonly a uniform color.

func (*Window) SetDrawFilter

func (w *Window) SetDrawFilter(screenFilter mod.Filter)

SetDrawFilter will filter the screen by the given modification function prior to publishing the screen's rgba to be displayed.

func (*Window) SetLoadingRenderable

func (w *Window) SetLoadingRenderable(r render.Renderable)

SetLoadingRenderable sets what renderable should display between scenes during loading phases.

func (*Window) SetLogicHandler

func (w *Window) SetLogicHandler(h event.Handler)

SetLogicHandler swaps the logic system of the engine with some other implementation. If this is never called, it will use event.DefaultBus

func (*Window) SetPalette

func (w *Window) SetPalette(palette color.Palette)

SetPalette tells oak to conform the screen to the input color palette before drawing.

func (*Window) SetViewport

func (w *Window) SetViewport(pt intgeom.Point2)

SetViewport positions the viewport to be at x,y

func (*Window) SetViewportBounds

func (w *Window) SetViewportBounds(rect intgeom.Rect2)

SetViewportBounds sets the minimum and maximum position of the viewport, including screen dimensions

func (*Window) ShiftViewport

func (w *Window) ShiftViewport(delta intgeom.Point2)

ShiftViewport shifts the viewport by x,y

func (*Window) TriggerKeyDown

func (w *Window) TriggerKeyDown(e okey.Event)

TriggerKeyDown triggers a software-emulated keypress. This should be used cautiously when the keyboard is in use. From the perspective of the event handler this is indistinguishable from a real keypress.

func (*Window) TriggerKeyHeld

func (w *Window) TriggerKeyHeld(e okey.Event)

TriggerKeyHeld triggers a software-emulated key hold signal. This should be used cautiously when the keyboard is in use. From the perspective of the event handler this is indistinguishable from a real key hold signal.

func (*Window) TriggerKeyUp

func (w *Window) TriggerKeyUp(e okey.Event)

TriggerKeyUp triggers a software-emulated key release. This should be used cautiously when the keyboard is in use. From the perspective of the event handler this is indistinguishable from a real key release.

func (*Window) TriggerMouseEvent

func (w *Window) TriggerMouseEvent(mevent omouse.Event)

TriggerMouseEvent triggers a software-emulated mouse event. This should be used cautiously when the mouse is in use. From the perspective of the event handler this is indistinguishable from a real key mouse press or movement.

func (*Window) UpdateViewSize

func (w *Window) UpdateViewSize(width, height int) error

UpdateViewSize updates the size of this window's viewport. If the window has yet to be initialized, it will update ScreenWidth and ScreenHeight, and then exit.

func (*Window) Viewport

func (w *Window) Viewport() intgeom.Point2

Viewport returns the viewport's position. Its width and height are the window's width and height. This position plus width/height cannot exceed ViewportBounds.

func (*Window) ViewportBounds

func (w *Window) ViewportBounds() (rect intgeom.Rect2, ok bool)

ViewportBounds returns the boundary of this window's viewport, or the rectangle that the viewport is not allowed to exit as it moves around. It often represents the total size of the world within a given scene. If bounds are not enforced, ok will be false.