@web-engine-dev/serialization

Schema-based binary and JSON serialization for game engines. Supports versioning, upgrades, and circular reference handling.

Features

• Schema-Based: Define schemas matching ECS component types
• Binary Encoding: Efficient MessagePack-inspired format
• JSON Encoding: Human-readable with extended type support
• Versioning: Schema versions and automatic upgrades
• Circular References: Automatic reference handling
• TypedArray Support: Efficient numeric array encoding

Installation

npm install @web-engine-dev/serialization
# or
pnpm add @web-engine-dev/serialization

Quick Start

import {
  defineSchema,
  objectOf,
  arrayOf,
  toBinary,
  fromBinary,
  toJson,
  fromJson,
} from '@web-engine-dev/serialization';

// Define a schema
const PlayerSchema = defineSchema(
  'Player',
  objectOf({
    name: 'string',
    position: objectOf({ x: 'f32', y: 'f32', z: 'f32' }),
    health: 'i32',
    inventory: arrayOf('string'),
  })
);

// Create data
const player = {
  name: 'Hero',
  position: { x: 0, y: 1, z: 0 },
  health: 100,
  inventory: ['sword', 'shield'],
};

// Serialize to binary
const binary = toBinary(player, PlayerSchema);

// Serialize to JSON
const json = toJson(player, PlayerSchema, true);

// Deserialize
const restored = fromBinary(binary, PlayerSchema);
const restored2 = fromJson(json, PlayerSchema);

API Reference

Schema Definition

Function	Description
defineSchema	Define a named schema
objectOf()	Object type with properties
arrayOf()	Array of type
mapOf()	Map with key/value types
optional()	Optional property
refTo()	Reference to another schema
enumOf()	Enum type

Primitive Types

Type	Description
i8	Signed 8-bit integer
i16	Signed 16-bit
i32	Signed 32-bit
u8	Unsigned 8-bit
u16	Unsigned 16-bit
u32	Unsigned 32-bit
f32	32-bit float
f64	64-bit float
string	UTF-8 string
bool	Boolean

Serialization Functions

// Binary
const bytes = toBinary(data, schema);
const data = fromBinary(bytes, schema);

// JSON
const json = toJson(data, schema, pretty?);
const data = fromJson(json, schema);

Schema Registry

import { globalSchemaRegistry } from '@web-engine-dev/serialization';

globalSchemaRegistry.register(MySchema);
const schema = globalSchemaRegistry.get('MySchema');

Versioning

const SchemaV2 = defineSchema(
  'Player',
  objectOf({
    name: 'string',
    position: objectOf({ x: 'f32', y: 'f32', z: 'f32' }),
    health: 'i32',
    maxHealth: 'i32', // New field
  }),
  {
    version: 2,
    upgrades: {
      1: (data) => ({ ...data, maxHealth: 100 }),
    },
  }
);

Circular References

const NodeSchema = defineSchema(
  'Node',
  objectOf({
    name: 'string',
    parent: optional(refTo('Node')),
    children: arrayOf(refTo('Node')),
  })
);

// Circular references are automatically handled