Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/EvWilson/2jz

An archetype-based entity-component-system library written in Zig.
https://github.com/EvWilson/2jz

Last synced: 3 months ago
JSON representation

An archetype-based entity-component-system library written in Zig.

Awesome Lists containing this project

README 

        
# 2JZ



## Hey!

Thanks for coming through and taking a look at this repo. As you might be able to tell, it's a good bit out of date and I don't really have any plans to maintain or update it at any point, so this is likely the last note I'll leave here. For those wanting to potentially make use of this in the future for whatever reason (likely me, wanting to demo to someone) the 0.7.0 release from https://ziglang.org/download/ seems to work for the Pong demo.



An archetype-based entity-component-system(ECS) library in Zig, inspired by

[hecs](https://github.com/Ralith/hecs) and the many other delightful ECS

libraries of the world. I'd highly recommend reading the README there for more

background on ECS in general.



### Example



```zig

const allocator = std.testing.allocator;

const expect = std.testing.expect;



const Position = struct { x: u32, y: u32 };

const HP = struct { points: u8, alive: bool };



// Create a world from your component types

var world = try World.init(allocator, .{ Position, HP });

defer world.deinit();



// Create entries with any combination of types

var entity = try world.spawn(.{Position{ .x = 5, .y = 7 }});

var entity2 = try world.spawn(.{ Position{ .x = 1, .y = 2 }, HP{ .points = 100, .alive = true } });



// Query for all entries containing a Position

var query = try world.query(.{Position});



while (query.next()) {

    var position = query.dataMut(Position);

    position.x *= 2;



    const ent = query.entity();



    // Prints both entities' Position information

    if (world.remove(ent)) {

        std.debug.print("removed entity: {}, with position: {}\n", .{ ent, position });

    }

}

```



### ECS in a Breath

ECS architecture is designed to make it easy to maintain loosely-coupled state

and behavior for complex systems, while ideally not sacrificing in performance

or developer ergonomics. Basically, entities are things, components are

descriptions of those things, and systems are ways to use and modify those

descriptions.



### What's this archetype bit about?

The naive approach to this architecture might have you arrange your components

in separate arrays of some kind, as seen in

[this easy to follow jumping off point](https://austinmorlan.com/posts/entity_component_system/).

However, this approach effectively kills your chances of pulling in all the

information you need for a given system's operation in a minimal number of cache

lines. The archetype helps to group your heterogeneous data together as densely

as possible, allowing for efficient memory access and minimal need for the

cross-referencing data structures you get otherwise.



### Examples

Check out the examples directory to get a feel for what usage might look like in

practice. At the time of writing, this includes a Pong game written with SDL,

and is a great example of Zig's fantastic C integration story.



### Acknowledgements

I'd love to be able to take a moment to give a huge thank you to the Zig

community for being such an awesome bunch of helpful hackers and tinkerers.

Tuning into the many showcases and demos from that scene is what convinced me to

keep pushing with this project, and the Discord is an amazing place to pick up

on all sorts of systems programming tidbits and adventures.



Of course, I also owe a good amount to the other open source ECS libraries of

the world, most notably hecs above, for providing helpful design pillars for me

to see, ignore, and then realize later was in fact a much better way of doing

things.