complete game examples with bitecs to learn from?

[Somorovd]

Im wondering if there are any resources that show how to use bitecs to make a game that go beyond trivial examples such as basic movement. In an OOP architecture I would have some sort of game manager for handling game state, events getting passed around, interactive UI and menus, etc. I would love to see the ECS approach to building out a full game with similar features / solutions to the same problems.

BitECS is a little harder to use as a developer, but seems to stick to the pure ECS philosophy without muddling through OOP (I just read this series of blog posts: https://t-machine.org/index.php/2007/09/03/entity-systems-are-the-future-of-mmog-development-part-1/), so Im particularly interested in seeing it done with bitECS.

[reececomo]

This GDC talk Overwatch Gameplay Architecture and Netcode might provide some useful context, although it may not directly answer your question.

They key thing that tied everything together for us was Blizzard's call out to leverage "singleton components". This helped us integrate our physics and netcode systems a bit more cleanly.

Also for migrating an existing game, or integrating with existing libraries that use game objects, etc. you may consider some kind of wrapper utility if the data is going to be stored inside bitecs, but libraries expect "object-like" data:

Object-like wrappers

(for integrating third-party libraries):

// src/components/position.ts
export const Position = defineComponent({ x: "f32", y: "f32", z: "f32" });
export const pos = Vec3.Wrap( Position );

Usage:

update_model(
  model,
  pos( eid ),
  vel( eid ),
  quat( eid ),
);

myCameraInstance.applyTransform( quat( CAMERA_EID ));

See source code: Vec3.ts

// src/utils/vec3.ts

interface Vec3Component {
  x: Float32Array | Float64Array,
  y: Float32Array | Float64Array,
  z: Float32Array | Float64Array,
}

export class Vec3
{
  public constructor(
    private component: Vec3Component,
    private eid: number,
  ){}

  public get x(): number { return this.component.x[this.eid]!; }
  public get y(): number { return this.component.y[this.eid]!; }
  public get z(): number { return this.component.z[this.eid]!; }

  public set x( val: number ) { this.component.x[this.eid] = val; }
  public set y( val: number ) { this.component.y[this.eid] = val; }
  public set z( val: number ) { this.component.z[this.eid] = val; }

  public toString(): string {
    return `(${this.x.toFixed(1)}, ${this.y.toFixed(1)}, ${this.z.toFixed(1)})`;
  }

  // other 3D vector helpers here potentially ...

  // ----- Static: -----

  public static Wrap( component: Vec3Component ): ( eid: number ) => Vec3
  {
    const v: Vec3[] = []; // or use a map, etc.
    return ( eid: number ): Vec3 => v[eid] ?? ( v[eid] = new Vec3( component, eid ) );
  }
}

---

Singletons:

You can defer certain behaviors on components to a later system, or a specialty system, or even use them outside of systems altogether in some other event-driven part of your application (i.e. if your game client is streaming inputs to the server independently of your fixed tick rate - e.g. real-time upstream throttling in a game with rollback netcode).

Simple version:

The bitecs README recommends using "global" properties on the world object, which achieves basically the same thing:

// src/world.js
const world = createWorld()
world.tick = 0

// src/systems/tickSystem.js
const tickSystem = ( world ) => {
  world.tick++
}

---

Singleton Components:

From v0.4 onwards, it would probably be better to do this by allocating a global singleton entity (like blizzard suggests).

We're using v0.3 and just to keep components and systems organized nicely without stuffing everything into a giant god-object, we use these special const T = defineSingletonComponent() and world.getSingleton( T ) methods:

Usage:

// src/components/StatsSingletonComponent.ts

export const StatsSingletonComponent = defineSingletonComponent({
  factory: () => ({
      packetLossIn: new StatisticsBuffer<number>( BUFFER_SIZE ),
      packetLossOut: new StatisticsBuffer(<number> BUFFER_SIZE ),
      physicsFrames: new StatisticsBuffer<number>( BUFFER_SIZE ),
      recvBytes: new StatisticsBuffer<number>( BUFFER_SIZE ),
      sendBytes: new StatisticsBuffer<number>( BUFFER_SIZE ),
      // ...
    }),
  },

  destroy: ( instance ) => {
    // (i.e. release the buffers here)
  },
});

// src/systems/FlushStatsSystem.ts

export function FlushStatsSystem( timeStep: number, world: World )
{
  const sngl_Netcode = world.getSingleton( NetcodeSingletonComponent );

  if ( sngl_Netcode.isInRollback ) return; // skip during rollback

  const sngl_Stats = world.getSingleton( StatsSingletonComponent );
  sngl_Stats.packetLossIn.flush();
  sngl_Stats.packetLossOut.flush();
  sngl_Stats.physicsFrames.flush();
  sngl_Stats.recvBytes.flush();
  sngl_Stats.sendBytes.flush();
  // ...

  // then post it, render it to debug overlay, whatever...
}

See source code: getSingleton(), defineSingletonComponent()

// src/ecs/world.ts

export const worldFactory = ( config: GameConfig ) => {
  const world = createWorld() as EcsWorld;

  const EID_NOOP = addEntity( world ); // 0
  const EID_SNGL = addEntity( world ); // 1

  const _singletons = new Map<SingletonComponentFactory<any>, any>();

  world.getSingleton = <T>( sngl: SingletonComponentFactory<T> ): T => {
    if ( _singletons.has( sngl) ) return _singletons.get( sngl );

    const instance = sngl.factory();
    _singletons.set( sngl, instance );

    return instance;
  };

  world.destroySingletons = (): void => {
    for ( const snglof _singletons.keys() ) {
      if ( ! sngl.destroy ) continue;
      const instance = _singletons.get( sngl);
      if ( instance ) sngl.destroy( instance );
    }
    _singletons.clear();
  };

  return world;
}

// src/ecs/component.ts

export interface SingletonComponentFactory<TSingletonComponent> {
  factory: () => TSingletonComponent;
  destroy?: ( singleton: TSingletonComponent ) => void;
}

// e.g. syntactic sugar to keep things consistent with the bitecs stuff, and infer types
export const defineSingletonComponent = <T>( factory: SingletonComponentFactory<T> ) => factory;

---

Final mentions:

Probably just aim to keep it simple, its not quite as hard as you probably think - and for many games the benefits are enormous.

p.s. check out this talk too: 8 Frames in 16ms: Rollback Networking in Mortal Kombat and Injustice 2 - especially the Q&A, talks a lot about the benefits of a data-oriented, serializable data model.

[Somorovd]

Thanks. Theres a lot of useful stuff here in the snippets I will need to look over. I'll be working on a bitecs implementation of this book I found for development of a roguelike using ECS in rust (not bevy or amethyst) which is the best non trivial game implementation example I found so far. http://bfnightly.bracketproductions.com/rustbook/chapter_0.html

[reececomo]

Bonus screenshot: You can see Overwatch stuffs a bunch of complex and shared system components into these singleton components:

Obviously for many javascript-based games you just really won't need to do this, but from bitecs v0.4 onward, its much easier to do in BitEcs, and it might make serializing / replaying your game state simpler 👍