@web-engine-dev/reflection

Runtime type introspection and metadata system for game engines. Supports decorators, property inspection, and editor integration.

Features

• Type Registry: Central registry for type metadata
• Decorators: Annotate classes and properties
• Property Inspection: Query types, validation, editor hints
• Schema Generation: Generate serialization schemas
• Inheritance Support: Full class hierarchy support

Installation

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

Quick Start

import {
  Reflect,
  Property,
  Range,
  Label,
  globalTypeRegistry,
  generateSchema,
} from '@web-engine-dev/reflection';

@Reflect({ category: 'Component' })
class Transform {
  @Property('f32')
  @Label('X Position')
  x: number = 0;

  @Property('f32')
  @Label('Y Position')
  y: number = 0;

  @Property('f32')
  @Range(0, 360)
  @Label('Rotation')
  rotation: number = 0;
}

// Query type metadata
const metadata = globalTypeRegistry.getByConstructor(Transform);
console.log(metadata?.properties);

// Generate serialization schema
const schema = generateSchema(metadata!.id);

API Reference

Class Decorators

Decorator	Description
@Reflect	Register class with type registry
@ReflectWith	Register with custom options
@Component	Register as ECS component
@Resource	Register as resource type

Property Decorators

Decorator	Description
@Property()	Define property type
@Optional	Mark as optional
@Readonly	Mark as read-only
@Default(v)	Set default value
@Label(s)	Display name for editors
@Description	Property description
@Category(s)	Group in editor
@Editor(opts)	Editor widget hints
@Validate(fn)	Validation function
@Hidden	Hide from editor

Value Decorators

Decorator	Description
@Range(a, b)	Numeric range constraint
@Color	Color picker widget
@Vector2	2D vector editor
@Vector3	3D vector editor
@AssetRef	Asset reference picker
@EntityRef	Entity reference picker

Type Registry

import { globalTypeRegistry } from '@web-engine-dev/reflection';

// Get by constructor
const meta = globalTypeRegistry.getByConstructor(Transform);

// Get by type ID
const meta2 = globalTypeRegistry.get('Transform');

// Find by category
const components = globalTypeRegistry.getByCategory('Component');

// Iterate properties
for (const prop of meta.properties) {
  console.log(prop.name, prop.type);
}

Schema Generation

import { generateSchema, generateSchemaForCategory } from '@web-engine-dev/reflection';

// Single type
const schema = generateSchema('Transform');

// All components
const schemas = generateSchemaForCategory('Component');