/**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */

// ---------------------------------------------------------------------------
// Component (generic base returned by entity.add() for untyped components)
// ---------------------------------------------------------------------------

/** Base component returned by entity.add() for component types without a specific module. */
interface Component {
  /** Entity ID this component belongs to. */
  readonly entity: number;
  /** Component slot ID. */
  readonly id: number;
  toString(): string;
}

interface ComponentConstructor {
  /** Sentinel value for an invalid component ID. */
  readonly INVALID: number;

  // Component type constants (generated from componentlist.h)
  readonly POSITION: number;
  readonly CAMERA: number;
  readonly RENDERABLE: number;
  readonly PHYSICS: number;
  readonly TRIGGER: number;
  readonly OVERWORLD: number;
  readonly PLAYER: number;
  readonly INTERACTABLE: number;
  readonly OVERWORLD_CAMERA: number;
  readonly OVERWORLD_TRIGGER: number;

  new(): never;
}

declare var Component: ComponentConstructor;

// ---------------------------------------------------------------------------
// Position
// ---------------------------------------------------------------------------

/** Position/rotation/scale transform component with optional parent hierarchy. */
interface Position extends Component {
  /**
   * Local-space position. Assigning a Vec3 writes to the C transform and
   * marks the world transform dirty. Reading returns a fresh Vec3 copy.
   */
  localPosition: Vec3;
  /** World-space position (accounts for all parent transforms). */
  worldPosition: Vec3;
  /** Local-space euler rotation in radians (XYZ). */
  localRotation: Vec3;
  /** World-space euler rotation in radians. */
  worldRotation: Vec3;
  /** Local-space scale. */
  localScale: Vec3;
  /** World-space scale. */
  worldScale: Vec3;
  /**
   * Orients the transform to look at a world-space target point.
   * Uses the current local position as the eye. Optionally specify an up
   * vector (defaults to Y-up).
   */
  lookAt(target: Vec3, up?: Vec3): void;
  /**
   * Sets this component's parent in the transform hierarchy.
   * Pass `null` or `undefined` to detach.
   */
  setParent(parent: Position | null | undefined): void;
  toString(): string;
}

interface PositionConstructor {
  new(): never;
}

declare var Position: PositionConstructor;

// ---------------------------------------------------------------------------
// Camera
// ---------------------------------------------------------------------------

/** Camera projection component. */
interface Camera extends Component {
  /** Field of view in radians (perspective projections only). */
  fov: number;
  /** Near clip plane distance. */
  nearClip: number;
  /** Far clip plane distance. */
  farClip: number;
  /** Projection type — one of the Camera.PERSPECTIVE / Camera.ORTHOGRAPHIC constants. */
  projType: number;
  toString(): string;
}

interface CameraConstructor {
  readonly PERSPECTIVE: number;
  readonly PERSPECTIVE_FLIPPED: number;
  readonly ORTHOGRAPHIC: number;
  new(): never;
}

declare var Camera: CameraConstructor;

// ---------------------------------------------------------------------------
// Entity
// ---------------------------------------------------------------------------

interface Entity {
  /** Add a component of the given type and return a typed instance. */
  add(type: CameraConstructor["PERSPECTIVE"] | number): Component;
  toString(): string;
}

interface EntityConstructor {
  /** Sentinel value for an invalid entity ID. */
  readonly INVALID: number;
  /** Creates a new entity and returns it. Returns Entity.INVALID slot if the pool is full. */
  create(): Entity;
  /** Disposes the entity and all its components. */
  dispose(entity: Entity): void;
  new(): never;
}

declare var Entity: EntityConstructor;