Skip to content
Cluaupp Cluaupp

Hive

Hive is a jecs-style ECS: entities, component columns, and iterators. A .hive file bakes u8 component ids. Snapshot writes a tagged buffer (nil / bool / number / string / table) for Flare — not JSON. Not a second Shift.

Header: #include <clpp/libs/hive.clh> or generated NpcWorld.clh. Runtime: CluauppLibs.Hive.

Why

Section titled “Why”
  • Packed columns. Query(Health, Target) yields entity, health, target for every row that has all components.
  • Snapshot is binary. u8 component id + u32 row count + per-row entity id and tagged values.
  • Server spawns entities. Clients consume snapshots; they do not create authoritative rows.

Schema (NpcWorld.hive)

Section titled “Schema (NpcWorld.hive)”
opt name = NpcWorld
component Health { i32 current, i32 max }
component Target { Player player }

Example

Section titled “Example”
#include "NpcWorld.clh"


void init() {
  HiveWorld world = NpcWorld.New();
  int e = world.Entity();
  world.Set(e, NpcWorld.Health, healthRow);
  buffer snap = world.Snapshot(NpcWorld.Health);
}

Full loop: NPC example.

API

Section titled “API”

Hive.World

Section titled “Hive.World”

Returns: HiveWorld (generated wrappers often expose NpcWorld.World() with schema baked in). Authoritative by default: Entity / Set / Remove / Despawn no-op on the client. Pass false as the second argument for a local prediction world.

When: One world per match or server realm; hold all NPC / pickup entities.

HiveWorld world = Hive.World();
HiveWorld localSim = Hive.World(schema, false);

Hive.AuthoritativeWorld

Section titled “Hive.AuthoritativeWorld”

Returns: HiveWorld with client writes refused.

When: Same as Hive.World when you want the flag explicit.

HiveWorld world = Hive.AuthoritativeWorld(schema);

HiveWorld.Entity

Section titled “HiveWorld.Entity”

Returns: int — new dense entity id.

When: Spawn NPCs, projectiles, or interactables on the server.

int e = world.Entity();

HiveWorld.Set

Section titled “HiveWorld.Set”

Returns: nothing.

When: Write or replace a component value on an entity.

world.Set(e, NpcWorld.Health, row);

HiveWorld.Get

Section titled “HiveWorld.Get”

Returns: auto — component value or nil if missing.

When: Read a single component for one entity.

auto hp = world.Get(e, NpcWorld.Health);

HiveWorld.Remove

Section titled “HiveWorld.Remove”

Returns: nothing.

When: Strip one component without despawning the entity.

world.Remove(e, NpcWorld.Target);

HiveWorld.Despawn

Section titled “HiveWorld.Despawn”

Returns: nothing.

When: Remove the entity and clear all its column entries.

world.Despawn(e);

HiveWorld.Has

Section titled “HiveWorld.Has”

Returns: bool — whether the entity has a non-nil value in that component column.

When: Cheap membership before Get or query-like branches.

if (world.Has(e, NpcWorld.Target)) { }

HiveWorld.Query

Section titled “HiveWorld.Query”

Returns: auto — iterator function; call repeatedly until it returns nil. With no component ids, yields entities only; with ids, yields entity, ...componentValues.

When: Systems that need every row with a given archetype (AI, regen, targeting).

auto next = world.Query(NpcWorld.Health, NpcWorld.Target);

HiveWorld.Snapshot

Section titled “HiveWorld.Snapshot”

Returns: buffer — packed column for one component id (all entities that have a value in that column).

When: Replicate or save one component column over Flare without JSON.

buffer snap = world.Snapshot(NpcWorld.Health);