import type { ENTITY_HANDLE } from '../core/graph/NodeContext';
import type { AnimationPlayer } from '../core/model/animation';
import type { AssetType } from '../core/model/AssetTypes';
import type { CompositionPlayer } from '../core/model/composition';
import type { FrameOutline } from '../core/model/frameOutline';
import type { TileEdits } from '../core/model/liveTilemap';
import type { PropertyBag } from '../core/model/Properties';

/** A live instance of a scene object; its resolved props are mutable runtime state the world mirrors back. */
export interface Entity {
  /** What tells a graph this object is a live entity and not a struct value. */
  readonly [ENTITY_HANDLE]: true;
  id: string;
  /** Scene object this entity was instantiated from (for selection highlighting). */
  objectId: string;
  assetId: string;
  type: AssetType;
  name: string;
  /** Position local to `parent` (world position for top-level entities). */
  x: number;
  y: number;
  /** Draw order, relative to the parent as well; higher is drawn on top. */
  z: number;
  /** For behaviors: the resolved variables (mutable state). For others: resolved properties. */
  props: PropertyBag;
  /** Parent entity (mirrors `SceneObject.parentId`); children move and die with it. */
  parent: Entity | null;
  /** The animations playing on this object; kept out of `props`, which the world writes back. */
  animations?: AnimationPlayer[];
  /** For a placed composition: what `Play composition` started (#417), out of `props` like `animations`. */
  composition?: CompositionPlayer;
  /** How often an `Emit` node has restarted this particle source; out of `props` for the same reason. */
  emits?: number;
  /**
   * The frame a collider of the shape "Frame collision" wears (#193), looked up in the world's project on every
   * call, so a changed `frame` prop or a redrawn outline counts at once. Absent outside a world.
   */
  wornFrame?: () => FrameOutline | null;
  /** For a placed tilemap: the cells a behavior set during the run (#135), never written back. */
  tileEdits?: TileEdits;
}