// Gizlo scripting API — type definitions (TypeScript). Save as gizlo.d.ts.
//
// Every Gizlo script is JavaScript (TypeScript type annotations are fine).
// In Gizlo Studio a script is nodes and code at once: the </> Code tab shows
// the same script as code, and edits there turn back into nodes.
// Docs and every node: https://gizlo.dev/scripting.html
//
// Server scripts run the shared game world on the game server.
// Local scripts run on one player's own computer; there `player` is them.

/** A position, size or rotation: [x, y, z] (rotation in degrees). */
type Vec3 = [number, number, number];

// ── Events ──────────────────────────────────────────────────────────────────

/** When the game starts (Server: when the first player joins; Local: when the player's game opens). */
declare function onStart(fn: () => void | Promise<void>): void;
/** Every server tick (about 20 times a second); `dt` is the seconds since the last one. */
declare function onTick(fn: (dt: number) => void | Promise<void>): void;
/** A player joined. */
declare function onPlayerAdded(fn: (player: Player) => void | Promise<void>): void;
/** A player left. */
declare function onPlayerRemoved(fn: (player: Player) => void | Promise<void>): void;
/** A player died. */
declare function onDied(fn: (player: Player) => void | Promise<void>): void;
/** Something touched `part`. `hit` is the name of the body part that touched it; `player` is whose body it is. */
declare function onTouch(part: Part, fn: (hit: string, player: Player | undefined) => void | Promise<void>): void;
/** Something stopped touching `part`. */
declare function onTouchEnded(part: Part, fn: (hit: string, player: Player | undefined) => void | Promise<void>): void;
/** A player's Local script sent this event with fireServer(name, data). */
declare function onRemoteEvent(name: string, fn: (data: any, player: Player) => void | Promise<void>): void;

/** Local scripts: the GUI button this script is on was clicked. */
declare function onClick(fn: () => void | Promise<void>): void;
/** Local scripts: this player pressed a key: a letter ("E"), a number ("1"), "Space", "Enter", "Shift", "Tab", "Up", "Down", "Left" or "Right". */
declare function onKeyPress(key: string, fn: () => void | Promise<void>): void;
/** Local scripts: a Server script sent this event to this player (player.send / sendAll). */
declare function onClientEvent(name: string, fn: (data: any) => void | Promise<void>): void;

// ── The world ───────────────────────────────────────────────────────────────

/** A part, folder or GUI element. Parts inside it are its members: World.Folder.Door. */
interface Part {
  readonly path: string;
  readonly name: string;
  /** The folder it's in. */
  readonly parent: Part | undefined;

  Position: Vec3;
  Size: Vec3;
  Rotation: Vec3;
  /** "red", "#ff8800"... */
  Color: string;
  /** 0 (solid) to 1 (invisible). */
  Transparency: number;
  Collidable: boolean;
  Material: string;

  // GUI elements (player.gui.Label)
  Text: string;
  Visible: boolean;
  TextColor: string;
  FontSize: number;
  ZIndex: number;
  BackgroundTransparency: number;

  /**
   * Move or turn it smoothly. Players standing on it ride along.
   * `await` it to wait until a one-off tween finishes.
   * @example await World.Platform.tween({ position: [0, 10, 0], duration: 2 });
   * @example World.Fan.tween({ rotation: [0, 360, 0], by: true, duration: 3, repeat: "Loop" });
   */
  tween(options: {
    /** Where to move to (or how far, with `by: true`). */
    position?: Vec3;
    /** How to turn (degrees). */
    rotation?: Vec3;
    /** Move/turn by this much instead of to it. */
    by?: boolean;
    /** Seconds (default 1). */
    duration?: number;
    easing?: "Smooth" | "Linear" | "EaseIn" | "EaseOut" | "Bounce" | "Elastic";
    repeat?: "Once" | "Loop" | "PingPong";
  }): Promise<void>;
  /** Stop its tweens where they are. */
  stopTween(which?: "All" | "Position" | "Rotation"): void;
  destroy(): void;
  /** A copy, put in the World. Things in Storage are made to be cloned. */
  clone(): Part | undefined;
  /** What's inside it. */
  children(): Part[];
  /** The part inside it with this name. */
  find(name: string): Part | undefined;
  distanceTo(other: Part): number;
  exists(): boolean;

  /** A part inside this one. */
  readonly [child: string]: any;
}

interface WorldFolder extends Part {
  /** Hour of the day, 0–24. */
  TimeOfDay: number;
  /** "None", "Rain", "Snow", "Ash" or "Auto" (whatever the sky preset brings). */
  Weather: string;
  /** Sun & sky: SunSize, Glow, Haze, Preset, Eclipse, Lightning, Transition. */
  Sky: Record<string, any>;
  /** Clouds: Enabled, Quality, Coverage, Density, Altitude, Thickness, WindSpeed, WindDirection, Detail, Brightness. */
  Clouds: Record<string, any>;
  /** Fog: Enabled, Color, Start, End. */
  Fog: Record<string, any>;
}

/** Everything in the game world: World.Door, World.Folder.Coin. */
declare const World: WorldFolder;
/** Things kept out of the world, to clone: Storage.Coin.clone(). */
declare const Storage: Part;
/** A part by its path: find("World.Folder.Door"). */
declare function find(path: string): Part;
/** Is this (the `hit` from onTouch) part of a player's body? */
declare function isCharacter(hit: string | Part): boolean;

// ── Players ─────────────────────────────────────────────────────────────────

interface Player {
  readonly id: number;
  readonly name: string;
  /** This player's own values, kept between events. Node scripts see the same ones as variables. */
  readonly vars: Record<string, any>;
  /** This player's GUI elements: player.gui.Label.Text = "Hi". */
  readonly gui: Record<string, Part>;
  health: number;
  maxHealth: number;
  walkSpeed: number;
  jumpPower: number;
  readonly position: Vec3;
  readonly online: boolean;

  /** To a part or to [x, y, z]. */
  teleport(to: Part | Vec3): void;
  kill(): void;
  damage(amount: number): void;
  heal(amount: number): void;
  respawn(): void;
  /** Where they come back after dying: on top of `part` (none = the game's normal spawn). A Spawn Point with Checkpoint ticked (Insert → Spawn Point in Studio) does this by itself when touched. */
  setSpawnPoint(part?: Part): void;

  /** Leaderboard stats (the creator adds them in Studio): "Coins", "Wins"... */
  getStat(stat: string): number;
  setStat(stat: string, value: number): void;
  addStat(stat: string, amount?: number): void;

  /** Saved for this player in this game, kept between visits (50 keys, 1000 characters each). */
  save(key: string, value: any): void;
  load<T extends string | number | boolean>(key: string, fallback?: T): T;

  /** Send an event to this player's Local scripts (onClientEvent). */
  send(event: string, data?: any): void;
  print(...values: any[]): void;
}

/** Everyone in the game (in a Local script: just this player). */
declare function players(): Player[];
declare function getPlayer(nameOrId: string | number): Player | undefined;
/** Send an event to every player's Local scripts (onClientEvent). */
declare function sendAll(event: string, data?: any): void;

/** Local scripts: the player whose computer this runs on. */
declare const player: Player;
/** Local scripts: send an event to the server (Server scripts hear it with onRemoteEvent). */
declare function fireServer(event: string, data?: any): void;

// ── Time and values ─────────────────────────────────────────────────────────

/** Pause this code for some seconds: `await wait(1)`. Other code keeps running. */
declare function wait(seconds?: number): Promise<void>;
/** Run something alongside, without waiting for it to finish. */
declare function spawn(fn: (...args: any[]) => any, ...args: any[]): void;
/** Seconds since the game started. */
declare function time(): number;
/** A whole number from min to max (both included); random(6) is 0–6. */
declare function random(min: number, max?: number): number;
/** Write to the Output window. */
declare function print(...values: any[]): void;

/**
 * Run any node by name with its settings (see the node list on the docs
 * page). Returns what it writes to its `output` setting, if you name one.
 * @example const c = runNode("GetPlayerStat", { stat: "Coins" }, "result");
 */
declare function runNode(kind: string, settings?: Record<string, any>, output?: string, player?: Player): any;