...

Package gohan

Overview ▾

Package gohan provides an Entity Component System framework for Ebiten.

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.

System

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

Component Design Guidelines

Components are located in a separate package, typically named component. They should be public (start with an uppercase letter) and may have any number of publicly accessible data fields. They 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 private (start with a lowercase 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.

Variables

Special error values.

var (
    // ErrSystemWithoutUpdate is the error returned when a System does not implement Update.
    ErrSystemWithoutUpdate = errors.New("system does not implement update")

    // ErrSystemWithoutDraw is the error returned when a System does not implement Draw.
    ErrSystemWithoutDraw = errors.New("system does not implement draw")
)

func ActiveEntities

func ActiveEntities() int

ActiveEntities returns the number of currently active entities.

func AddSystem

func AddSystem(system System)

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

func Draw

func Draw(screen *ebiten.Image) error

Draw draws the game on to the screen.

func DrawnEntities

func DrawnEntities() int

DrawnEntities returns the total number of Entities handled by System Draw calls. Because each Entity may be handled by more than one System, this number may be higher than the number of active entities.

func Update

func Update() error

Update updates the game state.

func UpdatedEntities

func UpdatedEntities() int

UpdatedEntities returns the total number of Entities handled by System Update calls. Because each Entity may be handled by more than one System, this number may be higher than the number of active entities.

type Component

Component represents data for an entity, and how it interacts with the world.

type Component interface {
    ComponentID() ComponentID
}

type ComponentID

ComponentID is a component identifier. Each Component is assigned a unique ID via NewComponentID, and implements a ComponentID method returning its ID.

type ComponentID int

func NewComponentID

func NewComponentID() ComponentID

NewComponentID returns the next available ComponentID.

type Entity

Entity is an entity identifier.

type Entity int

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 (entity Entity) AddComponent(component Component)

AddComponent adds a Component to an Entity.

func (Entity) Component

func (entity Entity) Component(componentID ComponentID) interface{}

Component gets a Component of an Entity.

func (Entity) Remove

func (entity Entity) Remove()

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.

type System

System represents a system that runs continuously. While the system must implement the Update and Draw methods, a special error value may be returned indicating that the system does not utilize one of the methods. System methods which return one of these special error values will not be called again.

See ErrSystemWithoutUpdate and ErrSystemWithoutDraw.

type System interface {
    // Matches returns whether the provided entity is handled by this system.
    Matches(entity Entity) bool

    // Update is called once for each matching entity each time the game state is updated.
    Update(entity Entity) error

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

Subdirectories