onigiri

README

Onigiri

Experimental ECS (Entity Component System) framework for Ebitengine.

DISCLAIMER: Onigiri is still in the early stages of development! The API is subject to breaking changes.

Rationale

When I got around to creating a demo game with Bento, I realised that it was difficult to separate scripting a game object from the concrete implementation. With this in mind, I decided to try an ECS approach with generics from scratch.

As with Bento, Ebitengine provides the foundation for efficient updating/drawing. Onigiri aims to provide niceties on top of that found in other game engine systems.

In future, some parts of Bento such as animations, fonts, and drawing utilities such as Vec may be moved into their own bento subdirectory. I recognize they are still useful to do common tasks when creating a game.

Credits

Hajime Hoshi for creating Ebiten.

License

Onigiri is licensed under the MIT License.

Documentation

Index

• type Component
  • func Query[T any](w *World) *Component[T]
  • func Register[T any](w *World, size int) *Component[T]
  • func (c *Component[T]) Delete(e Entity)
  • func (c *Component[T]) Get(e Entity) *T
  • func (c *Component[T]) Set(e Entity, com T)
• type ComponentKind
• type Entity
• type Event
  • func NewEvent[T any](size int) *Event[T]
  • func (e *Event[T]) Close()
  • func (e *Event[T]) Emit(value T)
  • func (e *Event[T]) Notify(f func(T))
  • func (e *Event[T]) Poll() (value T, ok bool)
• type Renderer
• type Scene
• type Signature
  • func (s *Signature) Clear(n uint8)
  • func (s *Signature) Contains(sig Signature) bool
  • func (s *Signature) Set(n uint8)
  • func (s *Signature) Test(n uint8) bool
• type System
• type Table
  • func NewTable[T any](size int) *Table[T]
  • func (t *Table[T]) Delete(e Entity)
  • func (t *Table[T]) Get(e Entity) *T
  • func (t *Table[T]) Set(e Entity, c T)
• type View
  • func NewView(w *World, components ...ComponentKind) *View
  • func (v *View) Each(f func(e Entity))
  • func (v *View) Filter(buf []Entity) []Entity
• type World
  • func NewWorld(size int) *World
  • func (w *World) Despawn(e Entity)
  • func (w *World) Draw(screen *ebiten.Image)
  • func (w *World) Register(systems ...System)
  • func (w *World) Spawn() Entity
  • func (w *World) Update() error

Types

type Component

type Component[T any] struct {
	// contains filtered or unexported fields
}

Component is a unique identifer for a component type.

func Query

func Query[T any](w *World) *Component[T]

Query returns the component by generic type in the world. The type must have already been registered with Register.

func Register

func Register[T any](w *World, size int) *Component[T]

Register allocates a table with capacity for (size) components in the world. Subsequent calls to Register will panic if it was already called once, or there are too many component types registered.

func (*Component[T]) Delete

func (c *Component[T]) Delete(e Entity)

Delete removes the component from the entity.

func (*Component[T]) Get

func (c *Component[T]) Get(e Entity) *T

Get gets the component associated with the entity.

func (*Component[T]) Set

func (c *Component[T]) Set(e Entity, com T)

Set adds the component to the entity.

type ComponentKind

type ComponentKind interface {
	// contains filtered or unexported methods
}

ComponentKind represents a specific kind of component in a world.

type Entity

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

Entity is a unique identifer for a game object, which zero or more components are associated with in a world.

type Event

type Event[T any] struct {
	// contains filtered or unexported fields
}

Event is a notification channel of T.

func NewEvent

func NewEvent[T any](size int) *Event[T]

NewEvent creates a new event with a buffer of (size) values.

func (*Event[T]) Close

func (e *Event[T]) Close()

Close closes the event channel. No event methods should be called after this.

func (*Event[T]) Emit

func (e *Event[T]) Emit(value T)

Emit sends the value to the event channel.

func (*Event[T]) Notify

func (e *Event[T]) Notify(f func(T))

Notify runs the callback function when a value is emitted.

func (*Event[T]) Poll

func (e *Event[T]) Poll() (value T, ok bool)

Poll checks if a value was emitted without blocking the current goroutine. If there is none, ok will be false.

type Renderer

type Renderer interface {
	Render(w *World, i *ebiten.Image)
}

Renderer is an opaque state that renders entities to the screen.

type Scene

type Scene interface {
	Setup() *World
}

Scene creates and initializes a world by spawning entities, registering components, and systems.

type Signature

type Signature uint8

Signature is a bitset with a fixed size of 64.

func (*Signature) Clear

func (s *Signature) Clear(n uint8)

func (*Signature) Contains

func (s *Signature) Contains(sig Signature) bool

func (*Signature) Set

func (s *Signature) Set(n uint8)

func (*Signature) Test

func (s *Signature) Test(n uint8) bool

type System

type System interface {
	Init(w *World)
	Update(w *World) error
}

System is an opaque state that updates entities.

type Table

type Table[T any] struct {
	// contains filtered or unexported fields
}

Table is a map of entities to indices into a dense slice of components of type T. It allows fast insertion and removal, but the order of components are not guaranteed.

func NewTable

func NewTable[T any](size int) *Table[T]

NewTable creates a new map with a capacity of (size) components.

func (*Table[T]) Delete

func (t *Table[T]) Delete(e Entity)

Delete removes the component by entity, swapping the index of the last element in place.

func (*Table[T]) Get

func (t *Table[T]) Get(e Entity) *T

Get returns a reference to the component indexed by the entity. If the entity is not in the table, nil is returned.

func (*Table[T]) Set

func (t *Table[T]) Set(e Entity, c T)

Set inserts a entity-component pair.

type View

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

View is a cached query that can be used by systems to search for entities with specific components.

func NewView

func NewView(w *World, components ...ComponentKind) *View

NewView creates a new view with the signatures of the components.

func (*View) Each

func (v *View) Each(f func(e Entity))

Each calls the function for each entity that matches the view's signature. Entities are not guaranteed to be in order; if you want to sort them before iteration use Filter.

func (*View) Filter

func (v *View) Filter(buf []Entity) []Entity

Filter appends all entities that match the view's signature to a buffer and returns it. The buffer may be nil, and can be reused across calls to Filter to reduce allocation.

type World

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

World is the container of all data related to entities, components and systems.

func NewWorld

func NewWorld(size int) *World

NewWorld creates a new world with an inital capacity of (size) entities.

func (*World) Despawn

func (w *World) Despawn(e Entity)

Despawn destroys the entity, removing it from the world.

func (*World) Draw

func (w *World) Draw(screen *ebiten.Image)

Draw renders all renderers to the screen in the order they were registered. This implements the ebiten.Game interface.

func (*World) Register

func (w *World) Register(systems ...System)

Register adds the systems to the world. A System may optionally implement Renderer, whose Render method is called when drawing to the screen.

func (*World) Spawn

func (w *World) Spawn() Entity

Spawn creates a new entity and adds it to the world. Entity IDs are guaranteed to be unique to seperate worlds, and not collide with any despawned entities.

func (*World) Update

func (w *World) Update() error

Update updates the state of the world's systems in the order they were registered. This implements the ebiten.Game interface.