README
¶
This is an ecs library I wrote for doing game development in Go. I'm actively using it and its pretty stable, but I do find bugs every once in a while. I might vary the APIs in the future if native iterators are added.
Overview
Conceptually you can imagine an ECS as one big table, where an Id column associates an Entity Id with various other component columns. Kind of like this:
| Id | Position | Rotation | Size |
|---|---|---|---|
| 0 | {1, 1} | 3.14 | 11 |
| 1 | {2, 2} | 6.28 | 22 |
We use an archetype-based storage mechanism. Which simply means we have a specific table for a specific component layout. This means that if you add or remove components it can be somewhat expensive, because we have to copy the entire entity to the new table.
Basic Usage
Import the library: import "github.com/unitoftime/ecs"
Create Components like you normally would:
type Position struct {
X, Y float64
}
type Rotation float64
Create a World to store all of your data
world := ecs.NewWorld()
Create an entity and add components to it
id := world.NewId()
ecs.Write(world, id,
ecs.C(Position{1, 1}),
ecs.C(Rotation(3.14)),
// Note: Try to reduce the number of write calls by packing as many components as you can in
)
// Side-Note: I'm trying to get rid of the `ecs.C(...)` boxing, but I couldn't figure out how when
// I first wrote the ECS. I'll try to get back to fixing that because ideally you
// shouldn't have to worry about it. For now though, you have to box your components
// to the `ecs.Component` interface type before passing them in, so `ecs.C(...)`
// does that for you.
Create a View, by calling QueryN:
query := ecs.Query2[Position, Rotation](world)
Iterate on the query. You basically pass in a lambda, and internally the library calls it for every entity in the world which has all of the components specified. Notably your lambda takes pointer values which represent a pointer to the internally stored component. So modifying these pointers will modify the entity's data.
query.MapId(func(id ecs.Id, pos *Position, rot *Rotation) {
pos.X += 1
pos.Y += 1
rot += 0.01
})
There are several map functions you can use, each with varying numbers of parameters. I support up to Map12. They all look like this:
ecs.MapN(world, func(id ecs.Id, a *ComponentA, /*... */, n *ComponentN) {
// Do your work
})
Advanced queries
You can also filter your queries for more advanced usage:
// Returns a view of Position and Velocity, but only if the entity also has the `Rotation` component.
query := ecs.Query2[Position, Velocity](world, ecs.With(Rotation))
// Returns a view of Position and Velocity, but if velocity is missing on the entity, will just return nil during the `MapId(...)`. You must do nil checks for all components included in the `Optional()`!
query := ecs.Query2[Position, Velocity](world, ecs.Optional(Velocity))
Commands
Commands will eventually replace ecs.Write(...) once I figure out how their usage will work. Commands essentially buffer some work on the ECS so that the work can be executed later on. You can use them in loop safe ways by calling Execute() after your loop has completed. Right now they work like this:
cmd := ecs.NewCommand(world)
WriteCmd(cmd, id, Position{1,1,1})
WriteCmd(cmd, id, Velocity{1,1,1})
cmd.Execute()
Still In Progress
- Improving iterator performance: See: https://github.com/golang/go/discussions/54245
- Automatic multithreading
- Without() filter
Videos
Hopefully, eventually I can have some automated test-bench that runs and measures performance, but for now you'll just have to refer to my second video and hopefully trust me. Of course, you can run the benchmark in the bench folder to measure how long frames take on your computer.
- How it works: https://youtu.be/71RSWVyOMEY
- Simulation Performance: https://youtu.be/i2gWDOgg50k
Documentation
¶
Index ¶
- func Delete(world *World, id Id) bool
- func Optional(comps ...any) optional
- func Read[T any](world *World, id Id) (T, bool)
- func ReadFromEntity[T any](ent *Entity) (T, bool)
- func ReadPtr[T any](world *World, id Id) *T
- func With(comps ...any) with
- func Write(world *World, id Id, comp ...Component)
- func WriteCmd[A any](c *Command, id Id, comp A)
- type Box
- type Command
- type Component
- type Entity
- type Filter
- type Id
- type RawEntity
- type Scheduler
- func (s *Scheduler) AppendInput(systems ...System)
- func (s *Scheduler) AppendPhysics(systems ...System)
- func (s *Scheduler) AppendRender(systems ...System)
- func (s *Scheduler) GetRenderInterp() float64
- func (s *Scheduler) PauseRender(value bool)
- func (s *Scheduler) Run()
- func (s *Scheduler) SetFixedTimeStep(t time.Duration)
- func (s *Scheduler) SetMaxPhysicsLoopCount(count int)
- func (s *Scheduler) SetQuit(value bool)
- func (s *Scheduler) Syslog() []SystemLog
- func (s *Scheduler) SyslogFixed() []SystemLog
- type System
- type SystemLog
- type View1
- type View10
- func (v *View10[A, B, C, D, E, F, G, H, I, J]) MapId(lambda func(id Id, a *A, b *B, c *C, d *D, e *E, f *F, g *G, h *H, i *I, j *J))
- func (v *View10[A, B, C, D, E, F, G, H, I, J]) MapSlices(...)deprecated
- func (v *View10[A, B, C, D, E, F, G, H, I, J]) Read(id Id) (*A, *B, *C, *D, *E, *F, *G, *H, *I, *J)
- type View11
- type View12
- type View2
- type View3
- type View4
- type View5
- type View6
- type View7
- func (v *View7[A, B, C, D, E, F, G]) MapId(lambda func(id Id, a *A, b *B, c *C, d *D, e *E, f *F, g *G))
- func (v *View7[A, B, C, D, E, F, G]) MapSlices(lambda func(id []Id, a []A, b []B, c []C, d []D, e []E, f []F, g []G))deprecated
- func (v *View7[A, B, C, D, E, F, G]) Read(id Id) (*A, *B, *C, *D, *E, *F, *G)
- type View8
- func (v *View8[A, B, C, D, E, F, G, H]) MapId(lambda func(id Id, a *A, b *B, c *C, d *D, e *E, f *F, g *G, h *H))
- func (v *View8[A, B, C, D, E, F, G, H]) MapSlices(lambda func(id []Id, a []A, b []B, c []C, d []D, e []E, f []F, g []G, h []H))deprecated
- func (v *View8[A, B, C, D, E, F, G, H]) Read(id Id) (*A, *B, *C, *D, *E, *F, *G, *H)
- type View9
- type World
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Delete ¶
Deletes the entire entity specified by the id This can be called inside maps and loops, it will delete the entity immediately. Returns true if the entity exists and was actually deleted, else returns false
func Optional ¶
func Optional(comps ...any) optional
Creates a filter to make the query still iterate even if a specific component is missing, in which case you'll get nil if the component isn't there when accessed
func Read ¶
Reads a specific component of the entity specified at id. Returns true if the entity was found and had that component, else returns false. Deprecated: This API is tentative, I'm trying to improve the QueryN construct so that it can capture this usecase.
func ReadFromEntity ¶
Reads a specific component from the entity, returns false if the component doesn't exist
func ReadPtr ¶
Reads a pointer to the component of the entity at the specified id. Returns true if the entity was found and had that component, else returns false. This pointer is short lived and can become invalid if any other entity changes in the world Deprecated: This API is tentative, I'm trying to improve the QueryN construct so that it can capture this usecase.
func With ¶
func With(comps ...any) with
Creates a filter to ensure that entities have the specified components
func Write ¶
Writes components to the entity specified at id. This API can potentially break if you call it inside of a loop. Specifically, if you cause the archetype of the entity to change by writing a new component, then the loop may act in mysterious ways. Deprecated: This API is tentative, I might replace it with something similar to bevy commands to alleviate the above concern
Types ¶
type Box ¶
type Box[T any] struct { Comp T // contains filtered or unexported fields }
This type is used to box a component with all of its type info so that it implements the component interface. I would like to get rid of this and simplify the APIs
type Command ¶
type Command struct {
// contains filtered or unexported fields
}
Represents a list of commands that need to be executed on the world
type Entity ¶
type Entity struct {
// contains filtered or unexported fields
}
An Entity is essentially a map of components that is held external to a world. Useful for pulling full entities in and out of the world. Deprecated: This type and its corresponding methods are tentative and might be replaced by something else.
func ReadEntity ¶
Reads the entire entity out of the world and into an *Entity object. Returns nil if the entity doesn't exist
type Filter ¶
type Filter interface {
Filter([]componentId) []componentId
}
TODO - Filter types: Optional - Lets you view even if component is missing (func will return nil) With - Lets you add additional components that must be present Without - Lets you add additional components that must not be present
type RawEntity ¶
type RawEntity struct {
// contains filtered or unexported fields
}
A RawEntity is like an Entity, but every component is actually a pointer to the underlying component. I mostly use this to build inspector UIs that can directly modify an entity Deprecated: This type and its corresponding methods are tentative and might be replaced by something else.
func NewRawEntity ¶
Creates a new entity with the specified components
func ReadRawEntity ¶
Reads the entire entity out of the world and into an *RawEntity object. Returns nil if the entity doesn't exist. RawEntity is lik
type Scheduler ¶
type Scheduler struct {
// contains filtered or unexported fields
}
Scheduler is a place to put your systems and have them run. There are two types of systems: Fixed time systems and dynamic time systems 1. Fixed time systems will execute on a fixed time step 2. Dynamic time systems will execute as quickly as they possibly can The scheduler may change in the future, but right now how it works is simple: Input: Execute input systems (Dynamic time systems) Physics: Execute physics systems (Fixed time systems) Render: Execute render systems (Dynamic time systems)
func (*Scheduler) AppendInput ¶
Adds a system to the list of input systems
func (*Scheduler) AppendPhysics ¶
Adds a system to the list of physics systems
func (*Scheduler) AppendRender ¶
Adds a system to the list of render systems
func (*Scheduler) GetRenderInterp ¶
Returns an interpolation value which represents how close we are to the next fixed time step execution. Can be useful for interpolating dynamic time systems to the fixed time systems. I might rename this
func (*Scheduler) PauseRender ¶
Pauses the set of render systems (ie they will be skipped). Deprecated: This API is tentatitive
func (*Scheduler) Run ¶
func (s *Scheduler) Run()
Note: Would be nice to sleep or something to prevent spinning while we wait for work to do Could also separate the render loop from the physics loop (requires some thread safety in ECS)
func (*Scheduler) SetFixedTimeStep ¶
Sets the amount of time required before the fixed time systems will execute
func (*Scheduler) SetMaxPhysicsLoopCount ¶
Sets the accumulator maximum point so that if the accumulator gets way to big, we will reset it and continue on, dropping all physics ticks that would have been executed. This is useful in a runtime like WASM where the browser may not let us run as frequently as we may need (for example, when the tab is hidden or minimized). Note: This must be set before you call scheduler.Run() Note: The default value is 0, which will force every physics tick to run. I highly recommend setting this to something if you plan to build for WASM!
func (*Scheduler) SetQuit ¶
Tells the scheduler to exit. Scheduler will finish executing its remaining tick before closing.
func (*Scheduler) Syslog ¶
Returns the front syslog so the user can analyze it. Note: This is only valid for the current frame, you should call this every frame if you use it!
func (*Scheduler) SyslogFixed ¶
Returns the front syslog for fixed-dt systems only. Note: This is only valid for the current frame, you should call this every frame if you use it!
type System ¶
Represents an individual system
type View1 ¶
type View1[A any] struct { // contains filtered or unexported fields }
Represents a view of data in a specific world. Provides access to the components specified in the generic block
func (*View1[A]) MapId ¶
Maps the lambda function across every entity which matched the specified filters.
func (*View1[A]) Read ¶
Reads a pointer to the underlying component at the specified id. Read will return even if the specified id doesn't match the filter list Read will return the value if it exists, else returns nil. If you execute any ecs.Write(...) or ecs.Delete(...) this pointer may become invalid.
type View10 ¶
type View10[A, B, C, D, E, F, G, H, I, J any] struct { // contains filtered or unexported fields }
Represents a view of data in a specific world. Provides access to the components specified in the generic block
func Query10 ¶
func Query10[A, B, C, D, E, F, G, H, I, J any](world *World, filters ...Filter) *View10[A, B, C, D, E, F, G, H, I, J]
Creates a View for the specified world with the specified component filters.
func (*View10[A, B, C, D, E, F, G, H, I, J]) MapId ¶
func (v *View10[A, B, C, D, E, F, G, H, I, J]) MapId(lambda func(id Id, a *A, b *B, c *C, d *D, e *E, f *F, g *G, h *H, i *I, j *J))
Maps the lambda function across every entity which matched the specified filters.
func (*View10[A, B, C, D, E, F, G, H, I, J]) Read ¶
Reads a pointer to the underlying component at the specified id. Read will return even if the specified id doesn't match the filter list Read will return the value if it exists, else returns nil. If you execute any ecs.Write(...) or ecs.Delete(...) this pointer may become invalid.
type View11 ¶
type View11[A, B, C, D, E, F, G, H, I, J, K any] struct { // contains filtered or unexported fields }
Represents a view of data in a specific world. Provides access to the components specified in the generic block
func Query11 ¶
func Query11[A, B, C, D, E, F, G, H, I, J, K any](world *World, filters ...Filter) *View11[A, B, C, D, E, F, G, H, I, J, K]
Creates a View for the specified world with the specified component filters.
func (*View11[A, B, C, D, E, F, G, H, I, J, K]) MapId ¶
func (v *View11[A, B, C, D, E, F, G, H, I, J, K]) MapId(lambda func(id Id, a *A, b *B, c *C, d *D, e *E, f *F, g *G, h *H, i *I, j *J, k *K))
Maps the lambda function across every entity which matched the specified filters.
func (*View11[A, B, C, D, E, F, G, H, I, J, K]) Read ¶
func (v *View11[A, B, C, D, E, F, G, H, I, J, K]) Read(id Id) (*A, *B, *C, *D, *E, *F, *G, *H, *I, *J, *K)
Reads a pointer to the underlying component at the specified id. Read will return even if the specified id doesn't match the filter list Read will return the value if it exists, else returns nil. If you execute any ecs.Write(...) or ecs.Delete(...) this pointer may become invalid.
type View12 ¶
type View12[A, B, C, D, E, F, G, H, I, J, K, L any] struct { // contains filtered or unexported fields }
Represents a view of data in a specific world. Provides access to the components specified in the generic block
func Query12 ¶
func Query12[A, B, C, D, E, F, G, H, I, J, K, L any](world *World, filters ...Filter) *View12[A, B, C, D, E, F, G, H, I, J, K, L]
Creates a View for the specified world with the specified component filters.
func (*View12[A, B, C, D, E, F, G, H, I, J, K, L]) MapId ¶
func (v *View12[A, B, C, D, E, F, G, H, I, J, K, L]) MapId(lambda func(id Id, a *A, b *B, c *C, d *D, e *E, f *F, g *G, h *H, i *I, j *J, k *K, l *L))
Maps the lambda function across every entity which matched the specified filters.
func (*View12[A, B, C, D, E, F, G, H, I, J, K, L]) Read ¶
func (v *View12[A, B, C, D, E, F, G, H, I, J, K, L]) Read(id Id) (*A, *B, *C, *D, *E, *F, *G, *H, *I, *J, *K, *L)
Reads a pointer to the underlying component at the specified id. Read will return even if the specified id doesn't match the filter list Read will return the value if it exists, else returns nil. If you execute any ecs.Write(...) or ecs.Delete(...) this pointer may become invalid.
type View2 ¶
type View2[A, B any] struct { // contains filtered or unexported fields }
Represents a view of data in a specific world. Provides access to the components specified in the generic block
func (*View2[A, B]) MapId ¶
Maps the lambda function across every entity which matched the specified filters.
func (*View2[A, B]) Read ¶
Reads a pointer to the underlying component at the specified id. Read will return even if the specified id doesn't match the filter list Read will return the value if it exists, else returns nil. If you execute any ecs.Write(...) or ecs.Delete(...) this pointer may become invalid.
type View3 ¶
type View3[A, B, C any] struct { // contains filtered or unexported fields }
Represents a view of data in a specific world. Provides access to the components specified in the generic block
func (*View3[A, B, C]) MapId ¶
Maps the lambda function across every entity which matched the specified filters.
func (*View3[A, B, C]) Read ¶
Reads a pointer to the underlying component at the specified id. Read will return even if the specified id doesn't match the filter list Read will return the value if it exists, else returns nil. If you execute any ecs.Write(...) or ecs.Delete(...) this pointer may become invalid.
type View4 ¶
type View4[A, B, C, D any] struct { // contains filtered or unexported fields }
Represents a view of data in a specific world. Provides access to the components specified in the generic block
func (*View4[A, B, C, D]) MapId ¶
Maps the lambda function across every entity which matched the specified filters.
func (*View4[A, B, C, D]) Read ¶
Reads a pointer to the underlying component at the specified id. Read will return even if the specified id doesn't match the filter list Read will return the value if it exists, else returns nil. If you execute any ecs.Write(...) or ecs.Delete(...) this pointer may become invalid.
type View5 ¶
type View5[A, B, C, D, E any] struct { // contains filtered or unexported fields }
Represents a view of data in a specific world. Provides access to the components specified in the generic block
func (*View5[A, B, C, D, E]) MapId ¶
Maps the lambda function across every entity which matched the specified filters.
func (*View5[A, B, C, D, E]) Read ¶
Reads a pointer to the underlying component at the specified id. Read will return even if the specified id doesn't match the filter list Read will return the value if it exists, else returns nil. If you execute any ecs.Write(...) or ecs.Delete(...) this pointer may become invalid.
type View6 ¶
type View6[A, B, C, D, E, F any] struct { // contains filtered or unexported fields }
Represents a view of data in a specific world. Provides access to the components specified in the generic block
func (*View6[A, B, C, D, E, F]) MapId ¶
Maps the lambda function across every entity which matched the specified filters.
func (*View6[A, B, C, D, E, F]) Read ¶
Reads a pointer to the underlying component at the specified id. Read will return even if the specified id doesn't match the filter list Read will return the value if it exists, else returns nil. If you execute any ecs.Write(...) or ecs.Delete(...) this pointer may become invalid.
type View7 ¶
type View7[A, B, C, D, E, F, G any] struct { // contains filtered or unexported fields }
Represents a view of data in a specific world. Provides access to the components specified in the generic block
func (*View7[A, B, C, D, E, F, G]) MapId ¶
func (v *View7[A, B, C, D, E, F, G]) MapId(lambda func(id Id, a *A, b *B, c *C, d *D, e *E, f *F, g *G))
Maps the lambda function across every entity which matched the specified filters.
func (*View7[A, B, C, D, E, F, G]) Read ¶
Reads a pointer to the underlying component at the specified id. Read will return even if the specified id doesn't match the filter list Read will return the value if it exists, else returns nil. If you execute any ecs.Write(...) or ecs.Delete(...) this pointer may become invalid.
type View8 ¶
type View8[A, B, C, D, E, F, G, H any] struct { // contains filtered or unexported fields }
Represents a view of data in a specific world. Provides access to the components specified in the generic block
func Query8 ¶
func Query8[A, B, C, D, E, F, G, H any](world *World, filters ...Filter) *View8[A, B, C, D, E, F, G, H]
Creates a View for the specified world with the specified component filters.
func (*View8[A, B, C, D, E, F, G, H]) MapId ¶
func (v *View8[A, B, C, D, E, F, G, H]) MapId(lambda func(id Id, a *A, b *B, c *C, d *D, e *E, f *F, g *G, h *H))
Maps the lambda function across every entity which matched the specified filters.
func (*View8[A, B, C, D, E, F, G, H]) Read ¶
Reads a pointer to the underlying component at the specified id. Read will return even if the specified id doesn't match the filter list Read will return the value if it exists, else returns nil. If you execute any ecs.Write(...) or ecs.Delete(...) this pointer may become invalid.
type View9 ¶
type View9[A, B, C, D, E, F, G, H, I any] struct { // contains filtered or unexported fields }
Represents a view of data in a specific world. Provides access to the components specified in the generic block
func Query9 ¶
func Query9[A, B, C, D, E, F, G, H, I any](world *World, filters ...Filter) *View9[A, B, C, D, E, F, G, H, I]
Creates a View for the specified world with the specified component filters.
func (*View9[A, B, C, D, E, F, G, H, I]) MapId ¶
func (v *View9[A, B, C, D, E, F, G, H, I]) MapId(lambda func(id Id, a *A, b *B, c *C, d *D, e *E, f *F, g *G, h *H, i *I))
Maps the lambda function across every entity which matched the specified filters.
func (*View9[A, B, C, D, E, F, G, H, I]) Read ¶
Reads a pointer to the underlying component at the specified id. Read will return even if the specified id doesn't match the filter list Read will return the value if it exists, else returns nil. If you execute any ecs.Write(...) or ecs.Delete(...) this pointer may become invalid.
type World ¶
type World struct {
// contains filtered or unexported fields
}
World is the main data-holder. You usually pass it to other functions to do things.
func (*World) SetIdRange ¶
Sets an range of Ids that the world will use when creating new Ids. Potentially helpful when you have multiple worlds and don't want their Id space to collide. Deprecated: This API is tentative. It may be better to just have the user create Ids as they see fit
Source Files
Directories