ecs-serialization

ECS Serialization

When to Use

Use this skill when:

• Implementing save/load functionality
• Creating entity prefabs/templates
• Network synchronization
• Level editor export/import
• Debugging and inspection
• Game state snapshots

Core Principles

1. Component-Based: Serialize components, not entities
2. Type-Safe: Preserve component types during deserialization
3. Efficient: Minimize serialized data size
4. Versioned: Handle schema changes gracefully
5. Selective: Serialize only what's needed
6. Deterministic: Same input produces same output

Serialization System Implementation

1. Component Serialization

// core/Serializable.ts
export interface ISerializable {
  serialize(): SerializedData;
  deserialize(data: SerializedData): void;
}

export type SerializedData = Record<string, any>;

// Base serializable component
export abstract class SerializableComponent implements ISerializable {
  abstract serialize(): SerializedData;
  abstract deserialize(data: SerializedData): void;

  getTypeName(): string {
    return this.constructor.name;
  }
}

// Example: Transform component
import { Vector3, Quaternion } from 'three';

export class Transform extends SerializableComponent {
  position = new Vector3();
  rotation = new Quaternion();
  scale = new Vector3(1, 1, 1);

  serialize(): SerializedData {
    return {
      position: this.position.toArray(),
      rotation: this.rotation.toArray(),
      scale: this.scale.toArray(),
    };
  }

  deserialize(data: SerializedData): void {
    if (data.position) this.position.fromArray(data.position);
    if (data.rotation) this.rotation.fromArray(data.rotation);
    if (data.scale) this.scale.fromArray(data.scale);
  }
}

// Example: Health component
export class Health extends SerializableComponent {
  current: number = 100;
  max: number = 100;
  regenRate: number = 0;

  serialize(): SerializedData {
    return {
      current: this.current,
      max: this.max,
      regenRate: this.regenRate,
    };
  }

  deserialize(data: SerializedData): void {
    this.current = data.current ?? this.current;
    this.max = data.max ?? this.max;
    this.regenRate = data.regenRate ?? this.regenRate;
  }
}