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/v3

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.

Quick Start

This is an example of the most basic oak program:

package main

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

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

See below or the examples folder for longer demos, godoc for reference documentation, and the wiki for more guided tutorials and walkthroughs.

Examples

Platformer	Top down shooter	Radar
Slideshow	Bezier Curves	Joysticks
Collision Demo	Custom Mouse Cursor	Fallback Fonts
Screen Options	Multi Window	Particle Demo

Games using Oak

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

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 scenarios, 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.

Example

Use oak to display a scene with a single movable character

AddScene("basicScene", scene.Scene{Start: func(*scene.Context) {
	char := entities.NewMoving(100, 100, 16, 32,
		render.NewColorBox(16, 32, color.RGBA{255, 0, 0, 255}),
		nil, 0, 0)
	render.Draw(char.R)
}})
Init("basicScene")

Index

• func AddScene(name string, sc scene.Scene) error
• func GetBackgroundImage() image.Image
• func GetCursorPosition() (x, y float64, err error)
• func Height() int
• func HideCursor() error
• func Init(scene string, configOptions ...ConfigOption) error
• func IsDown(key string) bool
• func IsHeld(key string) (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 SetDown(key string)
• func SetFS(filesystem fs.FS)
• func SetFullScreen(fs bool) error
• func SetLoadingRenderable(r render.Renderable)
• func SetScreen(x, y int)
• func SetTitle(title string) error
• func SetTopMost(on bool) error
• func SetTrayIcon(icon string) error
• func SetUp(key string)
• func SetViewportBounds(rect intgeom.Rect2)
• func ShiftScreen(x, y int)
• func ShowNotification(title, msg string, icon bool) error
• func UpdateViewSize(w, h int) error
• func Width() int
• 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 Duration
  • func (d Duration) MarshalJSON() ([]byte, error)
  • func (d *Duration) UnmarshalJSON(b []byte) error
• type InputType
• type Screen
• type Window
  • func NewWindow() *Window
  • func (w *Window) AddScene(name string, s scene.Scene) error
  • func (w *Window) ChangeWindow(width, height int) error
  • func (w *Window) ClearScreenFilter()
  • func (w *Window) CollisionTrees() (mouseTree, collisionTree *collision.Tree)
  • func (w *Window) DoBetweenDraws(f func())
  • func (w *Window) EventHandler() event.Handler
  • func (w *Window) GetBackgroundImage() image.Image
  • func (w *Window) GetCursorPosition() (x, y float64, err error)
  • func (w *Window) GetViewportBounds() (rect intgeom.Rect2, ok bool)
  • func (w *Window) GoToScene(nextScene string)
  • func (w *Window) Height() int
  • func (w *Window) HideCursor() error
  • func (w *Window) InFocus() bool
  • func (w *Window) Init(firstScene string, configOptions ...ConfigOption) error
  • func (w *Window) MostRecentInput() InputType
  • func (w *Window) MoveWindow(x, y, wd, h int) error
  • func (w *Window) NextScene()
  • func (w *Window) Propagate(eventName string, 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) SetBorderless(on bool) error
  • func (w *Window) SetColorBackground(img image.Image)
  • func (w *Window) SetFullScreen(on bool) error
  • func (w *Window) SetLoadingRenderable(r render.Renderable)
  • func (w *Window) SetLogicHandler(h event.Handler)
  • func (w *Window) SetPalette(palette color.Palette)
  • func (w *Window) SetScreen(x, y int)
  • func (w *Window) SetScreenFilter(screenFilter mod.Filter)
  • func (w *Window) SetTitle(title string) error
  • func (w *Window) SetTopMost(on bool) error
  • func (w *Window) SetTrayIcon(icon string) error
  • func (w *Window) SetViewportBounds(rect intgeom.Rect2)
  • func (w *Window) ShiftScreen(x, y int)
  • func (w *Window) ShowNotification(title, msg string, icon bool) error
  • 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() intgeom.Rect2
  • func (w *Window) Width() int

Examples

• Package

Functions

func AddScene

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

AddScene calls AddScene on the default window.

func GetBackgroundImage

func GetBackgroundImage() image.Image

GetBackgroundImage calls GetBackgroundImage on the default window.

func GetCursorPosition

func GetCursorPosition() (x, y float64, err error)

GetCursorPosition calls GetCursorPosition on the default window.

func Height

func Height() int

Height calls Height 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(key string) bool

IsDown calls IsDown on the default window.

func IsHeld

func IsHeld(key string) (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 SetDown

func SetDown(key string)

SetDown calls SetDown 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 SetLoadingRenderable

func SetLoadingRenderable(r render.Renderable)

SetLoadingRenderable calls SetLoadingRenderable on the default window.

func SetScreen

func SetScreen(x, y int)

SetScreen calls SetScreen 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 SetTrayIcon

func SetTrayIcon(icon string) error

SetTrayIcon calls SetTrayIcon on the default window.

func SetUp

func SetUp(key string)

SetUp calls SetUp on the default window.

func SetViewportBounds

func SetViewportBounds(rect intgeom.Rect2)

SetViewportBounds calls SetViewportBounds on the default window.

func ShiftScreen

func ShiftScreen(x, y int)

ShiftScreen calls ShiftScreen on the default window.

func ShowNotification

func ShowNotification(title, msg string, icon bool) error

ShowNotification calls ShowNotification on the default window.

func UpdateViewSize

func UpdateViewSize(w, h int) error

UpdateViewSize calls UpdateViewSize on the default window.

func Width

func Width() int

Width calls Width 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 batch load is true.

type Config

type Config struct {
	Assets              Assets           `json:"assets"`
	Debug               Debug            `json:"debug"`
	Screen              Screen           `json:"screen"`
	BatchLoadOptions    BatchLoadOptions `json:"batchLoadOptions"`
	FrameRate           int              `json:"frameRate"`
	DrawFrameRate       int              `json:"drawFrameRate"`
	IdleDrawFrameRate   int              `json:"idleDrawFrameRate"`
	Language            string           `json:"language"`
	Title               string           `json:"title"`
	EventRefreshRate    Duration         `json:"refreshRate"`
	BatchLoad           bool             `json:"batchLoad"`
	GestureSupport      bool             `json:"gestureSupport"`
	LoadBuiltinCommands bool             `json:"loadBuiltinCommands"`
	TrackInputChanges   bool             `json:"trackInputChanges"`
	EnableDebugConsole  bool             `json:"enableDebugConsole"`
	TopMost             bool             `json:"topmost"`
	Borderless          bool             `json:"borderless"`
	Fullscreen          bool             `json:"fullscreen"`
	SkipRNGSeed         bool             `json:"skip_rng_seed"`
}

Config stores initialization settings for oak.

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 Duration

type Duration time.Duration

A Duration is a wrapper around time.Duration that allows for easier json formatting.

func (Duration) MarshalJSON

func (d Duration) MarshalJSON() ([]byte, error)

MarshalJSON writes a duration as json.

func (*Duration) UnmarshalJSON

func (d *Duration) UnmarshalJSON(b []byte) error

UnmarshalJSON extracts a duration from a json byte slice.

type InputType

type InputType = int32

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

const (
	InputKeyboardMouse InputType = iota
	InputJoystick      InputType = iota
)

Supported Input Types

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"`
	// Target sets the expected dimensions of the monitor the game will be opened on, in pixels.
	// If Fullscreen is false, then a scaling will be applied to correct the game screen size to be
	// appropriate for the Target size. If no TargetWidth or Height is provided, scaling will not
	// be adjusted.
	TargetWidth  int `json:"targetHeight"`
	TargetHeight int `json:"targetWidth"`
}

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

type Window

type Window struct {
	key.State

	// 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

	// 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

	TrackMouseClicks bool

	// 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 defauklt settings.

func (*Window) AddScene

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

AddScene is shorthand for c.SceneMap.AddScene

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) CollisionTrees

func (w *Window) CollisionTrees() (mouseTree, collisionTree *collision.Tree)

CollisionTrees helps access the mouse and collision trees from the controller. These trees together detail how a controller can drive mouse and entity interactions.

func (*Window) DoBetweenDraws

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

DoBetweenDraws will execute the given function in-between draw frames

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) GetCursorPosition

func (w *Window) GetCursorPosition() (x, y float64, err error)

GetCursorPosition returns the cusor position relative to the top left corner of this window.

func (*Window) GetViewportBounds

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

GetViewportBounds reports what bounds the viewport has been set to, if any.

func (*Window) GoToScene

func (w *Window) GoToScene(nextScene string)

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

func (*Window) Height

func (w *Window) Height() int

Height returns the absolute height of the window in pixels.

func (*Window) HideCursor

func (w *Window) HideCursor() error

HideCursor disables showing the cursor when it is over this window.

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. It spawns off an event loop of several goroutines and loops through scenes after initialization.

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 controller's Config is set to TrackInputChanges

func (*Window) MoveWindow

func (w *Window) MoveWindow(x, y, wd, h int) error

MoveWindow sets the position of a window to be x,y and it's dimensions to w,h If the window does not support being positioned, it will report as such.

func (*Window) NextScene

func (w *Window) NextScene()

NextScene causes this window to immediately end the current scene.

func (*Window) Propagate

func (w *Window) Propagate(eventName string, 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) SetBorderless

func (w *Window) SetBorderless(on bool) error

SetBorderless attempts to set the local oak window to have no border. If the window does not support this functionaltiy, it will report as such.

func (*Window) SetColorBackground

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

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

func (*Window) SetFullScreen

func (w *Window) SetFullScreen(on bool) error

SetFullScreen attempts to set the local oak window to be full screen. If the window does not support this functionality, it will report as such.

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) SetScreen

func (w *Window) SetScreen(x, y int)

SetScreen positions the viewport to be at x,y

func (*Window) SetScreenFilter

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

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

func (*Window) SetTitle

func (w *Window) SetTitle(title string) error

SetTitle sets this window's title.

func (*Window) SetTopMost

func (w *Window) SetTopMost(on bool) error

SetTopMost attempts to set the local oak window to stay on top of other windows. If the window does not support this functionality, it will report as such.

func (*Window) SetTrayIcon

func (w *Window) SetTrayIcon(icon string) error

SetTrayIcon sets a application tray icon for this program.

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) ShiftScreen

func (w *Window) ShiftScreen(x, y int)

ShiftScreen shifts the viewport by x,y

func (*Window) ShowNotification

func (w *Window) ShowNotification(title, msg string, icon bool) error

ShowNotification shows a text notification, optionally using a previously set tray icon.

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.

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() intgeom.Rect2

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.

func (*Window) Width

func (w *Window) Width() int

Width returns the absolute width of the window in pixels.