event

Documentation

Overview

Package event propagates events through entities with given caller IDs. It sets up a subscribe-publish model with the Bind and Trigger functions. In a slight change to the sub-pub model, event allows bindings to occur in an explicit order through assigning priority to individual bind calls.

Index

• Constants
• func DestroyEntity(i int)
• func GetEntity(i int) interface{}
• func GlobalBind(fn Bindable, name string)
• func HasEntity(i int) bool
• func ResetBus()
• func ResetEntities()
• func ResolvePending()
• func Trigger(eventName string, data interface{})
• func TriggerBack(eventName string, data interface{}) chan bool
• func UnbindAll(opt BindingOption)
• func UnbindAllAndRebind(bo BindingOption, binds []Bindable, cid int, events []string)
• func UnbindBindable(opt UnbindOption)
• type Bindable
• type BindingOption
• type BindingSet
  • func (b BindingSet) Set(setName string, mappingSets ...map[string]Bindable) BindingSet
• type Bus
  • func GetBus() *Bus
  • func (eb *Bus) Bind(fn Bindable, name string, callerID int)
  • func (eb *Bus) BindPriority(fn Bindable, opt BindingOption)
  • func (eb *Bus) Trigger(eventName string, data interface{})
  • func (eb *Bus) TriggerBack(eventName string, data interface{}) chan bool
• type CID
  • func NextID(e Entity) CID
  • func (cid CID) Bind(fn Bindable, name string)
  • func (cid CID) BindPriority(fn Bindable, name string, priority int)
  • func (cid CID) E() interface{}
  • func (cid CID) Parse(e Entity) CID
  • func (c CID) RebindMapping(mapping Mapping)
  • func (cid CID) String() string
  • func (id CID) Trigger(eventName string, data interface{})
  • func (id CID) TriggerAfter(d time.Duration, eventName string, data interface{})
  • func (cid *CID) UnbindAll()
  • func (cid *CID) UnbindAllAndRebind(binds []Bindable, events []string)
• type Entity
• type Event
• type Mapping
• type UnbindAllOption
• type UnbindOption

Constants

const (
	// NoResponse or 0, is returned by events that
	// don't want the event bus to do anything with
	// the event after they have been evaluated. This
	// is the usual behavior.
	NoResponse = iota
	// Error should be returned by events that in some way
	// caused an error to happen, but this does not do anything
	// in the engine right now.
	Error
	// UnbindEvent unbinds everything for a specific
	// event name from an entity at the bindable's
	// priority.
	UnbindEvent
	// UnbindSingle just unbinds the one binding that
	// it is returned from
	UnbindSingle
)

const (
	// Enter : the beginning of every logical frame.
	// Payload: (int) frames passed since this scene started
	Enter = "EnterFrame"
	//
	// Consider moving the below to different packages before 2.0 release
	//
	// AnimationEnd: Triggered on animations CIDs when they loop from the last to the first frame
	// Payload: nil
	AnimationEnd = "AnimationEnd"
	// ViewportUpdate: Triggered when the position fo of the viewport changes
	// Payload: []float64{viewportX, viewportY}
	ViewportUpdate = "ViewportUpdate"
)

Oak uses the following built in events:

• CollisionStart/Stop: when a PhaseCollision entity starts/stops touching some label. Payload: (collision.Label) the label the entity has started/stopped touching

• MouseCollisionStart/Stop: as above, for mouse collision Payload: (mouse.Event)

• Mouse events: MousePress, MouseRelease, MouseScrollDown, MouseScrollUp, MouseDrag Payload: (mouse.Event) details on the mouse event

• KeyDown, KeyDown$a: when any key is pressed down, when key $a is pressed down. Payload: (string) the key pressed

• KeyUp, KeyUp$a: when any key is released, when key $a is released. Payload: (string) the key released

And the following:

Functions

func DestroyEntity

func DestroyEntity(i int)

DestroyEntity sets the index within the caller list to nil. Note that this does not reduce the size of the caller list, a potential change in the future would be to A) use a map or B) reassign caller ids to not directly correspond to indices within callers

func GetEntity

func GetEntity(i int) interface{}

GetEntity either returns callers[i-1] or nil, if there is nothing at that index.

func GlobalBind

func GlobalBind(fn Bindable, name string)

GlobalBind binds to the cid 0, a non entity.

func HasEntity

func HasEntity(i int) bool

HasEntity returns whether the given caller id is an initialized entity

func ResetBus

func ResetBus()

ResetBus empties out all transient portions of the package global bus

func ResetEntities

func ResetEntities()

ResetEntities resets callers and highestID, effectively dropping the remaining entities from accessible memory.

func ResolvePending

func ResolvePending()

ResolvePending is a contant loop that tracks slices of bind or unbind calls and resolves them individually such that they don't break the bus Todo: this should be a function on the event bus itself, and should have a better name If you ask "Why does this not use select over channels, share memory by communicating", the answer is we tried, and it was cripplingly slow.

func Trigger

func Trigger(eventName string, data interface{})

Trigger is equivalent to bus.Trigger(...) Todo: move this to legacy.go, see mouse or collision

func TriggerBack

func TriggerBack(eventName string, data interface{}) chan bool

TriggerBack is equivalent to bus.TriggerBack(...)

func UnbindAll

func UnbindAll(opt BindingOption)

UnbindAll removes all events that match the given bindingOption from the event bus

func UnbindAllAndRebind

func UnbindAllAndRebind(bo BindingOption, binds []Bindable, cid int, events []string)

UnbindAllAndRebind is a way to reset the bindings on a CID efficiently, given a new set of equal length binding and event slices. This is equivalent to callign UnbindAll and then looping over Bind calls for the pairs of bindables and event names, but uses less mutex time.

func UnbindBindable

func UnbindBindable(opt UnbindOption)

UnbindBindable is a manual way to unbind a function Bindable. Use of this with closures will cause unexpected behavior.

Types

type Bindable

type Bindable func(int, interface{}) int

Bindable is a way of saying "Any function that takes a generic struct of data and returns an error can be bound".

type BindingOption

type BindingOption struct {
	Event
	Priority int
}

BindingOption is all the information required to bind something

type BindingSet

type BindingSet map[string]Mapping

BindingSet maps sets of bindings so that entitys can switch between sets of predefined EventMappings

func (BindingSet) Set

func (b BindingSet) Set(setName string, mappingSets ...map[string]Bindable) BindingSet

Set makes a new EventMapping for BindingSet

type Bus

type Bus struct {
	// contains filtered or unexported fields
}

A Bus stores bindables to be triggered by events

func GetBus

func GetBus() *Bus

GetBus exposes the package global event bus that probably shouldn't be package global

func (*Bus) Bind

func (eb *Bus) Bind(fn Bindable, name string, callerID int)

Bind adds a function to the event bus tied to the given callerID to be called when the event name is triggered.

func (*Bus) BindPriority

func (eb *Bus) BindPriority(fn Bindable, opt BindingOption)

BindPriority is called by entities. Entities pass in a bindable function, and a set of options which are parsed out. Returns a binding that can used to unbind this binding later.

func (*Bus) Trigger

func (eb *Bus) Trigger(eventName string, data interface{})

Trigger will scan through the event bus and call all bindables found attached to the given event, with the passed in data.

func (*Bus) TriggerBack

func (eb *Bus) TriggerBack(eventName string, data interface{}) chan bool

TriggerBack is a version of Trigger which returns a channel that informs on when all bindables have been called and returned from the input event. It is dangerous to use this unless you have a very good idea how things will synchronize, as if a triggered bindable itself makes a TriggerBack call, this will cause the engine to freeze, as the function will never end because the first TriggerBack has control of the lock for the event bus, and the first TriggerBack won't give up that lock until the function ends.

This inherently means that when you call Trigger, the event will almost almost never be immediately triggered but rather will be triggered sometime soon in the future.

TriggerBack is right now used by the primary logic loop to dictate logical framerate, so EnterFrame events are called through TriggerBack.

type CID

type CID int

A CID is a caller ID that entities use to trigger and bind functionality

func NextID

func NextID(e Entity) CID

NextID finds the next id (always incrementing) and returns it, after adding the given entity to the slice of callers at the returned index.

func (CID) Bind

func (cid CID) Bind(fn Bindable, name string)

Bind on a CID is shorthand for bus.Bind(fn, name, cid)

func (CID) BindPriority

func (cid CID) BindPriority(fn Bindable, name string, priority int)

BindPriority on a CID is shorthand for bus.BindPriority(fn, ...)

func (CID) E

func (cid CID) E() interface{}

E is shorthand for GetEntity(int(cid)) But we apparently forgot we added this shorthand, because this isn't used anywhere.

func (CID) Parse

func (cid CID) Parse(e Entity) CID

Parse returns the given cid, or the entity's cid if the given cid is 0. This way, multiple entities can be composed together by passing 0 down to lower tiered constructors, so that the topmost entity is stored once and bind functions will bind to the topmost entity.

func (CID) RebindMapping

func (c CID) RebindMapping(mapping Mapping)

RebindMapping resets the entity controlling this cid to only have the bindings in the passed in event mapping

func (CID) String

func (cid CID) String() string

func (CID) Trigger

func (id CID) Trigger(eventName string, data interface{})

Trigger an event, but only for one ID. Use case example: on onHit event

func (CID) TriggerAfter

func (id CID) TriggerAfter(d time.Duration, eventName string, data interface{})

TriggerAfter will trigger the given event after d time.

func (*CID) UnbindAll

func (cid *CID) UnbindAll()

UnbindAll removes all events with the given cid from the event bus

func (*CID) UnbindAllAndRebind

func (cid *CID) UnbindAllAndRebind(binds []Bindable, events []string)

UnbindAllAndRebind on a CID is equivalent to bus.UnbindAllAndRebind(..., cid)

type Entity

type Entity interface {
	Init() CID
}

An Entity is an element which can be bound to, in that it has a CID. All Entities need to implement is an Init function which should call NextID(e) and return that id.

type Event

type Event struct {
	Name     string
	CallerID int
}

An Event is an event name and an associated caller id

type Mapping

type Mapping struct {
	// contains filtered or unexported fields
}

Mapping stores a slice of event names and bindings

type UnbindAllOption

type UnbindAllOption struct {
	// contains filtered or unexported fields
}

UnbindAllOption stores information needed to unbind and rebind

type UnbindOption

type UnbindOption struct {
	BindingOption
	Fn Bindable
}

UnbindOption stores information necessary to unbind a bindable