README
¶
gohan
Entity component system framework for Ebitengine
Documentation
Documentation is available via godoc.
An example game is included at
/examples/twinstick. See godoc for build instructions.
Support
Please share issues and suggestions here.
List of games powered by Gohan
- Fish Fight Back
- Brown Box Bat Man
- Monovania
Documentation
¶
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 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.
Environment Variables ¶
Running an application with the environment variable GOHAN_DEBUG set to 1 will enable printing verbose system update and draw information.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrUnregister = errors.New("unregister system")
ErrUnregister is a special error value which may be used to unregister a system from Draw or Update events.
Functions ¶
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 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.
Types ¶
type Entity ¶
type Entity int
Entity is an entity identifier.
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.
type System ¶
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
}
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.
Source Files