PartitionedBuffer

A high-performance PartitionedBuffer implementation backed by Uint32Array for efficient memory usage and fast bitwise operations.

See jsr.io/@phughesmcr/partitionedbuffer for complete documentation.

Installation

Node

npx jsr add @phughesmcr/partitionedbuffer

import { PartitionedBuffer } from "@phughesmcr/partitionedbuffer";

Deno

deno add jsr:@phughesmcr/partitionedbuffer

import { PartitionedBuffer } from "@phughesmcr/partitionedbuffer";

Bun

bunx jsr add @phughesmcr/partitionedbuffer

import { PartitionedBuffer } from "@phughesmcr/partitionedbuffer";

Usage

deno task example will run a complete example.

// Create a buffer with 1024 bytes and 64 entities (slots) per partition
const buffer = new PartitionedBuffer(1024, 64);

type Vec2 = { x: number, y: number };
const schema: Schema<Vec2> = { x: Float32Array, y: Float32Array };

// Add a partition with a schema
const position = buffer.addPartition({ name: "position", schema });

// Set the first entity's x and y values
position.partitions.x[0] = 1;
position.partitions.y[0] = 2;

Dense and sparse partitions

By default, partition arrays are dense typed-array views. The index is the slot inside the partition, and each schema property has maxEntitiesPerPartition entries.

Set maxOwners when only some entity IDs can own a component and memory use is more important than direct dense indexing. In that mode, bracket access uses entity IDs while the backing storage remains dense:

const sparsePosition = buffer.addPartition({
  name: "sparsePosition",
  schema,
  maxOwners: 100,
  maxEntityId: 9999,
});

sparsePosition.set("x", 42, 1);
sparsePosition.set("y", 42, 2);

delete sparsePosition.partitions.x[42]; // removes entity 42 from every field

When maxEntityId is provided with maxOwners, sparse mappings are backed by pre-allocated arrays for bounded entity IDs. Without it, sparse mappings use a Map and support arbitrary non-negative entity IDs.

Calling buffer.clear() zeros the stored arrays and removes partition registrations from the buffer. Existing partition handles are no longer registered with the buffer; retrieve new handles after adding partitions again.

Sizing helpers

• getEntitySize(schema) — per-entity stride (sum of each property's BYTES_PER_ELEMENT). Use for logical component width; there is no inter-field padding between SoA columns.
• getPartitionByteSize(schema, rowCount) — total bytes one partition consumes in a PartitionedBuffer (SoA columns plus inter-column alignment). Use when budgeting buffer size: rowCount is maxEntitiesPerPartition for dense partitions or maxOwners for sparse partitions.

Contributing

Contributions are welcome. The aim of the project is performance - both in terms of speed and GC allocation pressure.

Please run deno test and deno task prep to run the tests before committing.

License

PartitionedBuffer is released under the MIT license. See LICENSE for further details.

© 2024 The PartitionedBuffer Authors. All rights reserved.

See AUTHORS.md for author details.