scene

README

scene

The scene package handles distinct re-loadable sections of application or game flow.

Start

A scene itself has two fields: Start and End, functions called when a scene starts and ends respectively. Start is provided a Context object, which both serves as a standard Go context in persisting cancellations and arbitrary data, and ensures the operations within the scene operate on the correct data structures for the current logic and display.

Context

A Context has fields to enable accessing the window, render, key, collision, mouse, and event packages directly and succinctly. These helpers are embedded into the context when possible, enabling calls like:

render.Draw(...) // implied to run on the draw stack relevant for the current scene, fails in a multi-window context
// vs 
ctx.Draw(...) // explicitly runs on the draw stack for the current scene


mouse.DefaultTree.Hits(...) // ^
//vs
ctx.MouseTree.Hits(...) // ^

oak.SetFullScreen(true) 
// vs
ctx.Window.SetFullScreen(true)

The Window field on a Context will have different functionality based on the platform being compiled; e.g. window position manipulation is not possible when targeting Android or JS. These methods will fail to exist at compile time if used, preventing runtime errors.

End

When Context.Window.GoToScene or Context.Window.NextScene is called, the End function will be triggered. End enables a scene to define which other scene follow it and how it should transition to the next scene, if applicable.

• When GoToScene is used, the next scene output from End is ignored.
• It is valid to have a scene end and return to itself.
• It is valid to never define any End functions and solely rely on GoToScene.
• With the exception of persistent event bindings and the structure of the draw stack (not the elements on the draw stack), every entity is destroyed, undrawn, and unbound on scene end.

Helpers

Scene has other utilities:

• ctx.DoAfter and ctx.DoAfterContext will safely register a time based callback which will not be called if the scene ends early
• ctx.DrawForTime will render an element for a specified duration (using DoAfter)
• The Map type serves as the underlying data structure for the currently registered scenes, available via oak.Window.SceneMap
• GoTo and GoToPtr offer shorthand for End functions.

Documentation

Overview

Package scene provides definitions for interacting with game loop scenes.

Index

• func GoTo(nextScene string) func() (nextScene string, result *Result)
• func GoToPtr(nextScene *string) func() (nextScene string, result *Result)
• type Context
  • func (c *Context) DoAfter(d time.Duration, f func())
  • func (c *Context) DoAfterContext(ctx context.Context, f func())
  • func (ctx *Context) DoEachFrame(f func())
  • func (c *Context) DrawForTime(r render.Renderable, d time.Duration, layers ...int) error
• type Map
  • func NewMap() *Map
  • func (m *Map) AddScene(name string, s Scene) error
  • func (m *Map) Get(name string) (Scene, bool)
  • func (m *Map) GetCurrent() (Scene, bool)
• type Result
• type Scene
• type Transition
  • func Fade(rate float32, frames int) Transition
  • func Zoom(xPerc, yPerc float64, frames int, zoomRate float64) Transition
• type Window

Examples

• Map.GetCurrent

Functions

func GoTo

func GoTo(nextScene string) func() (nextScene string, result *Result)

GoTo returns an End function that, without any other customization possible, will change to the input next scene.

func GoToPtr

func GoToPtr(nextScene *string) func() (nextScene string, result *Result)

GoToPtr returns an End function that, without any other customization possible, will change to the input next scene. It takes a pointer so the scene can be changed after this function is called.

Types

type Context

type Context struct {
	// This context will be canceled when the scene ends
	context.Context

	PreviousScene string
	SceneInput    interface{}
	Window        Window

	*event.CallerMap
	event.Handler
	*render.DrawStack
	*key.State

	MouseTree     *collision.Tree
	CollisionTree *collision.Tree
}

A Context contains all transient engine components used in a scene, including the draw stack, event bus, known event callers, collision trees, keyboard state, and a reference to the OS window itself. When a scene ends, modifications made to these structures will be reset, excluding window modifications.

func (*Context) DoAfter

func (c *Context) DoAfter(d time.Duration, f func())

DoAfter will execute the given function after some duration. When the scene ends, DoAfter will exit without calling f. This call blocks until one of those conditions is reached.

func (*Context) DoAfterContext

func (c *Context) DoAfterContext(ctx context.Context, f func())

DoAfterContext will execute the given function once the passed in context is closed. When the scene ends, DoAfterContext will exit without calling f. This call blocks until one of those conditions is reached.

func (*Context) DoEachFrame

func (ctx *Context) DoEachFrame(f func())

DoEachFrame is a helper method to call a function on each frame for the duration of this scene.

func (*Context) DrawForTime

func (c *Context) DrawForTime(r render.Renderable, d time.Duration, layers ...int) error

DrawForTime draws, and after d, undraws an element

type Map

type Map struct {
	CurrentScene string
	// contains filtered or unexported fields
}

A Map lets scenes be accessed via associated names.

func NewMap

func NewMap() *Map

NewMap creates a scene map

func (*Map) AddScene

func (m *Map) AddScene(name string, s Scene) error

AddScene takes a scene struct, checks that its assigned name does not conflict with an existing name in the map, and then adds it to the map. If a conflict occurs, the scene will not be overwritten. Checks if the Scene's start is nil, sets to noop if so. Checks if the Scene's end is nil, sets to loop to this scene if so.

func (*Map) Get

func (m *Map) Get(name string) (Scene, bool)

Get returns the scene associated with the given name, if it exists. If it does not exist, it returns a zero value and false.

func (*Map) GetCurrent

func (m *Map) GetCurrent() (Scene, bool)

GetCurrent returns the current scene, as defined by map.CurrentScene

Example

package main

import (
	"fmt"

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

func main() {
	m := scene.NewMap()
	sc := scene.Scene{
		Start: func(*scene.Context) {
			fmt.Println("Starting screen one")
		},
	}
	m.AddScene("screen1", sc)
	m.CurrentScene = "screen2"
	_, ok := m.GetCurrent()
	if !ok {
		fmt.Println("Screen two did not exist")
	}
	m.CurrentScene = "screen1"
	sc, ok = m.GetCurrent()
	if !ok {
		fmt.Println("Screen one did not exist")
	} else {
		sc.Start(&scene.Context{
			PreviousScene: "scene0",
		})
	}
}

Output:

Screen two did not exist
Starting screen one

type Result

type Result struct {
	NextSceneInput interface{}
	Transition
}

A Result is a set of options for what should be passed into the next scene and how the next scene should be transitioned to.

type Scene

type Scene struct {
	// Start is called when a scene begins, including contextual information like
	// what scene came before this one and a direct reference to clean data structures
	// for event handling and rendering
	Start func(ctx *Context)
	// End is a function returning the next scene and a SceneResult of
	// input settings for the next scene.
	End func() (nextScene string, result *Result)
}

A Scene is a set of functions defining what needs to happen when a scene starts and ends.

type Transition

type Transition func(*image.RGBA, int) bool

Transition functions can be set to occur at the end of a scene.

func Fade

func Fade(rate float32, frames int) Transition

Fade is a scene transition that fades to black at a given rate for a total of 'frames' frames

func Zoom

func Zoom(xPerc, yPerc float64, frames int, zoomRate float64) Transition

Zoom transitions by performing a simplistic zoom each frame towards some percentage-based part of the screen.

type Window

type Window = window.Window