Avokadoen / ecez

A WIP ecs API for Zig!
MIT License
17 stars 0 forks source link
data-oriented-programming ecs zig

Test Zig changes watch

ECEZ - An ECS API

This is a ECS (Entity Component System) API for Zig.

Try it yourself!

Requirements

The zig compiler 0.13.0

You can use zigup to easily get this specific version

Steps

Run the following commands

# Clone the repo
git clone https://github.com/Avokadoen/ecez.git
# Run tests
zig build test
# Run GOL example, use '-Denable-tracy=true' at the end to add tracy functionality
zig build run-game-of-life 

You should also checkout src/main.zig which has the public API. From there you can follow the deifinition to get more details.

Zig documentation

You can generate the ecez API documentation using zig build docs. This will produce some web resources in zig-out/doc/ecez. You will need a local server to serve the documentation since browsers will block resources loaded by the index.html.

The simplest solution to this is just using a basic python server:

python -m http.server 8000 -d ecez/zig-out/doc/ecez # you can then access the documentation at http://localhost:8000/#ecez.main 

Features

Compile time based and type safe API

Zig's comptime feature is utilized to perform static reflection on the usage of the API to validate usage and report useful messages to the user (in theory :)).

https://github.com/Avokadoen/ecez/blob/4c713bfb1a5a65922bab3bcaabee402bbabb7c85/examples/readme/main.zig#L1-L153

System arguments

Systems can take 3 argument types:

Implicit multithreading of systems

When you trigger a system dispatch or an event with multiple systems then ecez will schedule this work over multiple threads. Synchronization is handled by ecez although there are some caveats that you should be aware of:

Serialization through the ezby format

ecez uses a custom byte format to convert storages into a slice of bytes.

Example

https://github.com/Avokadoen/ecez/blob/4c713bfb1a5a65922bab3bcaabee402bbabb7c85/examples/readme/main.zig#L143-L153

Tracy integration using ztracy

ztracy

The codebase has integration with tracy to allow both the library itself, but also applications to profile using a tracy client. There is also a wrapper allocator called TracyAllocator which allows tracy to report on memory usage if the application opts in to it. The extra work done by tracy is of course NOPs in builds without tracy!

Demo/Examples

Currently the project has two simple examples in the example folder:

Test Driven Development

The codebase also utilize TDD to ensure a certain level of robustness, altough I can assure you that there are many bugs to find yet! ;)

Planned

Please see the issues for planned features.