Game Data Generation

A CLI code generator that creates Javascript (Typescript) data structures with zeroing functions.

The problems

If you're making a game in Javascript then you might:

• hit the garbage collector (GC) a bunch causing frame drops because you're creating/destroying objects every frame (particles, for example)
• read a book about Data Oriented Design
• notice the performance implications of OOP (especially classes and calling their methods) versus using something like Structure of Arrays
• want to implement Structure of Arrays instead of Array of Structures (which is a list of class instances, see previous point)
• notice that Javascript can not simply zero out data structures (resetting all data back to initial values) like languages such as C and Rust

The solution

This tool:

• creates data structures based on Markdown file (see example below)
• each data structure gets associated functions to zero out its memory so it can be reused

Installation

npm i -D game-data-gen

Usage

npx game-data-gen <input-file-path> <optional-output-file-path>

Types

Each block in the Markdown file starts with a heading that defines the type, followed by a list of fields.

Group

# <name> group

A set of module-level variables with individual setter and zero functions, plus a combined zero function.

| Field type | Description | | --------------- | --------------------------------------------------- | | string | A string primitive | | number | A number primitive | | boolean | A boolean primitive | | string[] | A dynamic array of strings | | number[] | A dynamic array of numbers | | boolean[] | A dynamic array of booleans | | string[] <n> | A fixed-length array of n strings | | number[] <n> | A fixed-length array of n numbers | | boolean[] <n> | A fixed-length array of n booleans | | <name> | A nested struct (must be defined before this group) | | <name>[] | A dynamic array of structs | | <name>[] <n> | A fixed-length array of n structs |

Fixed-length arrays are pre-populated on creation and their length is preserved when zeroed.

Structure of Arrays (SOA)

# <name> soa <capacity>

A set of typed arrays of fixed capacity, ideal for cache-friendly iteration over many elements.

| Field type | Typed array | | ---------- | -------------- | | int8 | Int8Array | | int16 | Int16Array | | int32 | Int32Array | | uint8 | Uint8Array | | uint16 | Uint16Array | | uint32 | Uint32Array | | float32 | Float32Array | | float64 | Float64Array |

Struct

# <name> struct

A TypeScript type with create and zero functions. Fields can be primitives, arrays, or other structs.

| Field type | Description | | --------------- | ---------------------------------------------------- | | string | A string primitive | | number | A number primitive | | boolean | A boolean primitive | | string[] | A dynamic array of strings | | number[] | A dynamic array of numbers | | boolean[] | A dynamic array of booleans | | string[] <n> | A fixed-length array of n strings | | number[] <n> | A fixed-length array of n numbers | | boolean[] <n> | A fixed-length array of n booleans | | <name> | A nested struct (must be defined before this struct) | | <name>[] | A dynamic array of structs | | <name>[] <n> | A fixed-length array of n structs |

Fixed-length arrays are pre-populated on creation and their length is preserved when zeroed.

Array of Structures (AOS)

# <name> aos <capacity> <struct>

A pre-allocated fixed-length array of struct objects.

Example

Create a Markdown file somewhere in your source code, for example src/data.md:

# game group

- score number
- isPaused boolean

# Vector struct

- x number
- y number

# Rectangle struct

- x number
- y number
- w number
- h number

# Entity struct

- name string
- health number
- position Vector
- hitbox Rectangle
- tags string[]
- isDestroyed boolean

# entities aos 64 Entity

Run the package with (consider making this a script in your package.json):

npx game-data-gen src/data.md

This will create or update the src/data.ts file. The data and functions can then be imported from this file into your code:

import { entities, zeroEntity } from "./data.ts";

for (const id in entities) {
  const e = entities[id];

  if (e.isDestroyed) {
    zeroEntity(e);
    continue;
  }
}