Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
D

donburi-ecs

> 编程语言
Open source

Just another ECS library for Go/Ebitengine

375 stars0 likes0 views
WebsiteGitHub

About

Just another ECS library for Go/Ebitengine

Donburi Donburi is an Entity Component System library for Go / Ebitengine inspired by legion.

It aims to be a feature rich and high-performance ECS Library.

Contents

  • Contents
  • Summary
  • Examples
  • Installation
  • Getting Started
    • Worlds
    • Queries
  • Ordered Queries
    • Tags
    • Systems (Experimental)
    • Debug
  • Features
    • Math
    • Transform
    • Events
  • Projects Using Donburi
    • Games
    • Libraries
  • Architecture
  • How to contribute?
  • Contributors

Summary

  • It introduces the concept of Archetype, which allows us to query entities very efficiently based on the components layout.
  • It is possible to combine And, Or, and Not conditions to perform complex queries for components.
  • It avoids reflection for performance.
  • Ability to dynamically add or remove components from an entity.
  • Type-safe APIs powered by Generics
  • Zero dependencies
  • Provides Features that are common in game dev (e.g., math, transform, hieralchy, events, etc) built on top of the ECS architecture.

Examples

To check all examples, visit this page.

The bunnymark example was adapted from mizu's code, which is made by sedyh.

Installation

go get github.com/yohamta/donburi

Getting Started

Worlds

go
import "github.com/yohamta/donburi"

world := donburi.NewWorld()

Entities can be created via either Create (for a single entity) or CreateMany (for a collection of entities with the same component types). The world will create a unique ID for each entity upon insertion that we can use to refer to that entity later.

…

Components can be added and removed through Entry objects.

go
// Fetch the first entity with PlayerTag component
query := donburi.NewQuery(filter.Contains(PlayerTag))
// Query.First() returns only the first entity that 
// matches the query.
if entry, ok := query.First(world); ok {
  donburi.Add(entry, Position, &PositionData{
    X: 100,
    Y: 100,
  })
  donburi.Remove(entry, Velocity)
}

Entities can be removed from World with the World.Remove() as follows:

go
if SomeLogic.IsDead(world, someEntity) {
  // World.Remove() removes the entity from the world.
  world.Remove(someEntity)
  // Deleted entities become invalid immediately.
  if world.Valid(someEntity) == false {
    println("this entity is invalid")
  }
}

Entities can be retrieved using the First and Iter methods of Components as follows:

…

Queries

Queries allow for high performance and expressive iteration through the entities in a world, to get component references, test if an entity has a component or to add and remove components.

go
// Define a query by declaring what componet you want to find.
query := donburi.NewQuery(filter.Contains(Position, Velocity))

// Iterate through the entities found in the world
for entry := range query.Iter(world) {
  // An entry is an accessor to entity and its components.
  position := Position.Get(entry)
  velocity := Velocity.Get(entry)
  
  position.X += velocity.X
  position.Y += velocity.Y
}

There are other types of filters such as And, Or, Exact and Not. Filters can be combined wth to find the target entities.

For example:

go
// This query retrieves entities that have an NpcTag and no Position component.
query := donburi.NewQuery(filter.And(
  filter.Contains(NpcTag),
  filter.Not(filter.Contains(Position))))

If you need to determine if an entity has a component, there is entry.HasComponent

For example:

…

Ordered Queries

Sometimes you may need to iterate a query in a specific order. Donburi supports this through the OrderedQuery[T] type. In order to use this, the component must implement the IOrderable interface:

go
type IOrderable interface {
	Order() int
}

Example: Here we assume the spatial.TransformComponent implements Order().

go
q := donburi.NewOrderedQuery[spatial.Transform](
filter.Contains(sprite.Component, spatial.TransformComponent))

for entry := range q.IterOrdered(w) {
  // This will be iterated according to the spatial.TransformComponent's Order() function.
}

Tags

One or multiple "Tag" components can be attached to an entity. "Tag"s are just components with a single name string as data.

Here is the utility function to create a tag component.

go
// This is the utility function to make tag component
func NewTag(name string) *ComponentType {
  return NewComponentType(Tag(name))
}

Since "Tags" are components, they can be used in queries in the same way as components as follows:

go
var EnemyTag = donburi.NewTag("Enemy")
world.CreateMany(100, EnemyTag, Position, Velocity)

// Search entities with EnemyTag
for entry := range EnemyTag.Iter(world) {
  // Perform some operation on the Entities with the EnemyTag component.
}

Systems (Experimental)

⚠ this feature is currently experimental, the API can be changed in the future.

The ECS package provides so-called System feature in ECS which can be used together with a World instance.

See the GoDoc and Example.

How to create an ECS instance:

go
import (
  "github.com/yohamta/donburi"
  ecslib "github.com/yohamta/donburi/ecs"
)

world := donburi.NewWorld()
ecs := ecslib.NewECS(world)

A System is created from just a function that receives an argument (ecs *ecs.ECS).

go
// Some System's function
func SomeFunction(ecs *ecs.ECS) {
  // ...
}

ecs.AddSystem(SomeFunction)

We can provide Renderer for certain system.

go
ecs.AddRenderer(ecs.LayerDefault, DrawBackground)

// Draw all systems
ecs.Draw(screen)

The Layer parameter allows us to control the order of rendering systems and to which screen to render. A Layer is just an int value. The default value is just 0.

For example:

go

const (
  LayerBackground ecslib.LayerID = iota
  LayerActors
)

// ...

ecs.
  AddSystem(UpdateBackground).
  AddSystem(UpdateActors).
  AddRenderer(LayerBackground, DrawBackground).
  AddRenderer(LayerActors, DrawActors)

// ...

func (g *Game) Draw(screen *ebiten.Image) {
  screen.Clear()
  g.ecs.DrawLayer(LayerBackground, screen)
  g.ecs.DrawLayer(LayerActors, screen)
}

The ecs.Create() and ecs.NewQuery() wrapper-functions allow to create and query entities on a certain Layer:

For example:

go
var layer0 ecs.LayerID = 0

// Create an entity on layer0
ecslib.Create(layer0, someComponents...)

// Create a query to iterate entities on layer0
queryForLayer0 := ecslib.NewQuery(layer0, filter.Contains(someComponent))

Debug

The debug package provides some debug utilities for World.

For example:

go
debug.PrintEntityCounts(world)

// [Example Output]
// Entity Counts:
// Archetype Layout: {TransformData, Size, SpriteData, EffectData } has 61 entities
// Archetype Layout: {TransformData, Size, SpriteData, ColliderData } has 59 entities
// Archetype Layout: {TransformData, Size, SpriteData, WeaponData} has 49 entities
// ...

Features

Under the features directory, we develop common functions for game dev. Any kind of Issues or PRs will be very appreciated.

Math

The math package provides the basic types (Vec2 etc) and helpers.

See the GoDoc for more details.

Transform

The transform package provides the Tranform Component and helpers.

It allows us to handle position, rotation, scale data relative to the parent.

This package was adapted from ariplane's code, which is created by m110.

For example:

…

How to remove chidren (= destroy entities):

go
// Remove children
transform.RemoveChildrenRecursive(parent)

// Remove children and the parent
transform.RemoveRecursive(parent)

Events

The events package allows us to send arbitrary data between systems in a Type-safe manner.

This package was adapted from ariplane's code, which is created by m110.

For example:

…

Projects Using Donburi

Games

  • airplanes - A 2D shoot 'em up game by m110
  • goingo - Go game implemented in the Go language by joelschutz
  • revdriller - An action puzzle game by yohamta

Libraries

  • necs - Networked Entity Component System; a networking layer for donburi by gin
  • tamago - CLI Runtime editor for donburi ECS Worlds by thefishhat

Architecture

How to contribute?

Feel free to contribute in any way you want. Share ideas, questions, submit issues, and create pull requests. Thanks!

Contributors

Made with contrib.rocks.

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Goebitengineecsentity-component-systemgame-engine

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言