...

Package gohan

Overview ▾

Package gohan provides an Entity Component System framework for Ebitengine.

An example game is available at /examples/twinstick, which may be built by executing the following command (in /examples/twinstick):

go build -tags example .

Entity

A general-purpose object, which consists of a unique ID, starting with 1.

Component

The raw data for one aspect of an object, and how it interacts with the world. Each component is assigned a unique ID, starting with 1.

type ExampleComponent struct {
  X, Y float64
}

System

Each system runs continuously, performing actions on every entity that fits each systems' set of required matching components.

type ExampleSystem struct {
  Position *component.PositionComponent // Required component.
  Velocity *component.VelocityComponent // Required component.

  Sprite *component.SpriteComponent `gohan:"?"` // Optional component.

  Enabled bool `gohan:"-"` // Not a component.
}

Component Design Guidelines

Components are located in a separate package, typically named component. They should be public (start with an uppercase letter) and may be of any type. Using only struct types (with zero or more public fields) and accessing the structs via pointer is recommended. Components should not have any logic (i.e. game code) within them, as all logic should be implemented within a system.

System Design Guidelines

Systems are located in a separate package, typically named system. They should be public (start with an uppercase letter) and offer an instantiation function named as follows: NewSystemNameHere(). Data should be stored within components attached to one or more entities, rather than within the systems themselves. References to components must not be maintained outside each Update and Draw call, or else the application will encounter race conditions.

Environment Variables

Running an application with the environment variable GOHAN_DEBUG set to 1 will enable printing verbose system update and draw information.

Variables

ErrUnregister is a special error value which may be used to unregister a system from Draw or Update events.

var ErrUnregister = errors.New("unregister system")

func AddSystem

func AddSystem(system System)

AddSystem registers a system to start receiving Update and Draw calls.

func CurrentDraws

func CurrentDraws() int

CurrentDraws returns the number of System Draw calls required to draw the game on to the screen. Because entities may be handled by more than one System, this number may be higher than the number of active entities.

func CurrentEntities

func CurrentEntities() int

CurrentEntities returns the number of currently active entities.

func CurrentUpdates

func CurrentUpdates() int

CurrentUpdates returns the number of System Update calls required to update the game state. Because entities may be handled by more than one System, this number may be higher than the number of active entities.

func Draw

func Draw(screen *ebiten.Image) error

Draw draws the game on to the screen.

func Preallocate

func Preallocate(entities int)

Preallocate creates and then immediately removes the specified number of entities. Because Gohan reuses removed entities, this has the effect of pre-allocating the memory used later to create entities normally. Pre-allocating enough entities to run your application after its systems has been added, but before any entities are created, will provide the greatest performance boost.

func Reset

func Reset()

Reset removes all entities, components and systems.

func Update

func Update() error

Update updates the game state.

type Entity

Entity is an entity identifier.

type Entity int

func AllEntities

func AllEntities() []Entity

AllEntities returns a slice of all active entities. To retrieve only the number of currently active entities, use CurrentEntities.

func NewEntity

func NewEntity() Entity

NewEntity returns a new (or previously removed and cleared) Entity. Because Gohan reuses removed Entity IDs, a previously removed ID may be returned.

func (Entity) AddComponent

func (e Entity) AddComponent(component interface{})

AddComponent adds a Component to an Entity.

func (Entity) Remove

func (e Entity) Remove() bool

Remove removes the provided Entity's components, causing it to no longer be handled by any system. Because Gohan reuses removed EntityIDs, applications must also remove any internal references to the removed Entity.

func (Entity) With

func (e Entity) With(f interface{})

With accepts any function which takes one or more components as arguments. This function will block until the provided function returns.

type System

System represents a system that runs continuously.

Systems may specify any number of required components by adding public fields to their struct. When no required components are specified, the system will run for every active entity.

While systems must implement the Update and Draw methods, the special error value ErrUnregister may be returned at any time by systems to indicate the method returning the error should not be called again.

Systems do not need to implement locking to prevent race conditions between Update and Draw methods. Ebitengine calls only one of these methods at a time.

type System interface {
    // Update is called once for each matching Entity each time the game state is updated.
    Update(e Entity) error

    // Draw is called once for each matching Entity each time the game is drawn to the screen.
    Draw(e Entity, screen *ebiten.Image) error
}

Subdirectories