// Picotron v0.2.1e Global API Type Definitions

// Userdata types
type UserdataType = "u8" | "i16" | "i32" | "i64" | "f64";

// Userdata interface
interface Userdata<T extends UserdataType = UserdataType> {
  // Dimension methods
  width(): number;
  height(): number | null;
  attribs(): LuaMultiReturn<[number, number, T, number]>;

  // Element access
  get(x: number, n?: number): LuaMultiReturn<number[]>;
  get(x: number, y: number, n?: number): LuaMultiReturn<number[]>;
  set(x: number, ...values: number[]): void;
  set(x: number, y: number, ...values: number[]): void;

  // Row/Column access (2d only)
  row(i: number): Userdata<T> | null;
  column(i: number): Userdata<T> | null;

  // Binary operations
  add(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;
  sub(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;
  mul(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;
  div(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;
  mod(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;
  pow(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;

  // Bitwise operations
  band(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;
  bor(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;
  bxor(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;

  // Min/Max operations
  max(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;
  min(
    src: Userdata<T> | number,
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;

  // Unary operations
  copy(
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;
  abs(
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;
  sgn(
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;
  sgn0(
    dest?: Userdata<T> | true,
    src_offset?: number,
    dest_offset?: number,
    len?: number,
    src_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;

  // Lookup table copy
  take(
    idx: Userdata<"i32">,
    dest?: Userdata<T>,
    idx_offset?: number,
    dest_offset?: number,
    span_len?: number,
    idx_stride?: number,
    dest_stride?: number,
    spans?: number
  ): Userdata<T>;

  // Blit operation
  blit(
    dest?: Userdata<T>,
    src_x?: number,
    src_y?: number,
    dest_x?: number,
    dest_y?: number,
    width?: number,
    height?: number
  ): void;

  // Mutation and conversion
  mutate(data_type: UserdataType, width?: number, height?: number): void;
  convert(data_type: UserdataType, dest?: Userdata): Userdata;

  // Interpolation
  lerp(offset?: number, len?: number, el_stride?: number, num_lerps?: number, lerp_stride?: number): Userdata<T>;

  // Sorting (2d only)
  sort(index?: number, descending?: boolean): void;

  // Memory operations
  peek(addr: number, offset?: number, elements?: number): void;
  poke(addr: number, offset?: number, elements?: number): void;

  // Matrix/Vector operations (f64 only)
  matmul(m: Userdata<"f64">, m_out?: Userdata<"f64">, batch_height?: number): Userdata<"f64">;
  matmul3d(m: Userdata<"f64">, m_out?: Userdata<"f64">, batch_height?: number): Userdata<"f64">;
  transpose(m_out?: Userdata<T> | true): Userdata<T>;

  // Vector operations (f64 only)
  magnitude(): number;
  distance(v: Userdata<"f64">): number;
  dot(v: Userdata<"f64">): number;
  cross(v: Userdata<"f64">, v_out?: Userdata<"f64"> | true): Userdata<"f64">;
}

// =====================
// Math Functions
// =====================
declare function abs(x: number): number;
declare function atan2(dx: number, dy: number): number;
declare function cos(x: number): number;
declare function flr(x: number): number;
declare function max(x: number, ...args: number[]): number;
declare function mid(x: number, y: number, z: number): number;
declare function min(x: number, ...args: number[]): number;
declare function rnd(x?: number): number;
declare function sgn(x: number): number;
declare function sin(x: number): number;
declare function sqrt(x: number): number;
declare function srand(seed: number): void;

// Bitwise operations
declare function band(x: number, ...args: number[]): number;
declare function bnot(x: number): number;
declare function bor(x: number, ...args: number[]): number;
declare function bxor(x: number, ...args: number[]): number;
declare function rotl(x: number, n: number): number;
declare function rotr(x: number, n: number): number;
declare function shl(x: number, n: number): number;
declare function shr(x: number, n: number): number;

// =====================
// Graphics API
// =====================
declare function cls(color?: number): void;
declare function camera(x?: number, y?: number): void;
declare function clip(x?: number, y?: number, w?: number, h?: number): void;
declare function color(c: number): void;
declare function pal(c0?: number, c1?: number, p?: number): void;
declare function palt(c?: number, t?: boolean): void;
declare function fillp(pattern?: number): void;
declare function pget(x: number, y: number): number;
declare function pset(x: number, y: number, c?: number): void;
declare function cursor(x?: number, y?: number, c?: number): void;
declare function print(text?: any, x?: number, y?: number, color?: number): number;
declare function line(x1: number, y1: number, x2?: number, y2?: number, color?: number): void;
declare function line(userdata: Userdata): void;
declare function rect(x0: number, y0: number, x1: number, y1: number, c?: number): void;
declare function rect(userdata: Userdata): void;
declare function rectfill(x0: number, y0: number, x1: number, y1: number, c?: number): void;
declare function rectfill(userdata: Userdata): void;
declare function circ(x: number, y: number, r: number, c?: number): void;
declare function circfill(x: number, y: number, r: number, c?: number): void;
declare function circfill(userdata: Userdata): void;
declare function oval(x: number, y: number, rx: number, ry: number, c?: number): void;
declare function ovalfill(x: number, y: number, rx: number, ry: number, c?: number): void;
declare function rrect(x: number, y: number, width: number, height: number, radius?: number, c?: number): void;
declare function rrectfill(x: number, y: number, width: number, height: number, radius?: number, c?: number): void;
declare function fget(n: number, f?: number): number | boolean;
declare function fset(n: number, f?: number, val?: boolean): void;
declare function get_spr(index: number): Userdata<"u8">;
declare function set_spr(index: number, ud: Userdata<"u8">): void;
declare function spr(sprite: number | Userdata, x: number, y: number, w?: number, h?: number, flip_x?: boolean, flip_y?: boolean): void;
declare function sspr(sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw?: number, dh?: number, flip_x?: boolean, flip_y?: boolean): void;

// =====================
// Map API
// =====================
declare function map(cel_x?: number, cel_y?: number, sx?: number, sy?: number, cel_w?: number, cel_h?: number, layer?: number): void;
declare function map(src: Userdata<"i16">, cel_x?: number, cel_y?: number, sx?: number, sy?: number, cel_w?: number, cel_h?: number, layer?: number, tile_w?: number, tile_h?: number): void;
declare function mget(cel_x: number, cel_y: number): number;
declare function mset(cel_x: number, cel_y: number, sprite_number: number): void;
declare function tline3d(src: number | Userdata<"u8"> | Userdata<"i16">, x0: number, y0: number, x1: number, y1: number, u0: number, v0: number, u1: number, v1: number, w0?: number, w1?: number, flags?: number): void;
declare function tline3d(x0: number, y0: number, x1: number, y1: number, u0: number, v0: number, u1: number, v1: number, w0?: number, w1?: number, flags?: number): void;

// =====================
// Audio API
// =====================
declare function sfx(id: number, channel?: number, offset?: number, length?: number, mix_volume?: number): void;
declare function music(id?: number, fade_len?: number, channel_mask?: number, base_addr?: number, tick_offset?: number): void;
declare function note(pitch?: number, inst?: number, vol?: number, effect?: number, effect_p?: number, channel?: number, retrig?: boolean, panning?: number): void;

// =====================
// Input API
// =====================
declare function btn(i?: number, player?: number): number | boolean;
declare function btnp(i?: number, player?: number): number | boolean;
declare function key(k?: string, raw?: boolean): boolean;
declare function keyp(k?: string, raw?: boolean): boolean;
declare function peektext(): boolean;
declare function readtext(clear?: boolean): string;
declare function mouse(): LuaMultiReturn<[number, number, number, number, number]>;
declare function mouselock(lock: boolean, event_sensitivity?: number, move_sensitivity?: number): LuaMultiReturn<[number, number]>;
declare function input(prompt?: string, flags?: number): string | null;

// =====================
// String API
// =====================
declare function chr(...values: number[]): string;
declare function ord(str: string, index?: number, num_results?: number): number | LuaMultiReturn<number[]>;
declare function sub(str: string, pos0: number, pos1?: number | boolean): string;
declare function split(str: string, delimiter?: string | number, convert_numbers?: boolean): string[];
declare function type(val: any): string;
declare function tostr(val: any, format?: string): string;
declare function tonum(str: string): number | null;
declare function create_delta(str0: string, str1: string): string;
declare function apply_delta(str0: string, delta: string): string | null;

// =====================
// Tables API
// =====================
declare function add(t: any[], item: any, index?: number): void;
declare function del(t: any[], item: any): void;
declare function deli(t: any[], index: number): any;
declare function count(t: any[]): number;
declare function all(t: any[]): () => any | undefined;
declare function foreach(t: any[], fn: (item: any) => void): void;
declare function pairs(t: any): LuaMultiReturn<[(t: any, k?: any) => LuaMultiReturn<[any, any]>, any, any]>;
declare function next(t: any, k?: any): LuaMultiReturn<[any, any]>;

// =====================
// PODs API
// =====================
declare function pod(val: any, flags?: number, metadata?: any): string;
declare function unpod(str: string): LuaMultiReturn<[any, any]>;
declare function store(path: string, val: any): void;
declare function fetch(path: string): any;

// =====================
// Files API
// =====================
declare function store(filename: string, obj: any, metadata?: any): void;
declare function fetch(filename: string, options?: any): LuaMultiReturn<[any, any]>;
declare function store_metadata(filename: string, metadata: any): void;
declare function fetch_metadata(filename: string): any;
declare function include(path: string): void;
declare function cd(path: string): void;
declare function ls(path?: string): string[];
declare function mkdir(path: string): void;
declare function rm(path: string): void;
declare function mv(src: string, dest: string): void;
declare function cp(src: string, dest: string): void;
declare function pwd(): string;
declare function fullpath(filename: string): string;
declare function fstat(path: string): LuaMultiReturn<[string, number, string]>;

// =====================
// System API
// =====================
declare function load(path: string): void;
declare function save(path: string): void;
declare function run(): void;
declare function stop(message?: string): void;
declare function resume(): void;
declare function reset(cart?: string): void;
declare function stat(v: number, ...args: any[]): any;
declare function env(): any;
declare function time(): number;
declare function t(): number;
declare function date(format?: string, t?: string | number, delta?: number): string;
declare function exit(): void;
declare function printh(text: any, file_path?: string, overwrite?: boolean, terminal?: boolean): void;
declare function error(description?: string): void;
declare function assert(condition: any, message?: string): void;
declare function get_clipboard(): string;
declare function set_clipboard(text: string): void;
declare function create_process(filename: string, ...args: any[]): number;
declare function pid(): number;
declare function signal(proc_id: number, signal: string): void;
declare function send_message(proc_id: number, msg: any, reply?: boolean | ((msg: any) => void)): any;
declare function on_event(event: string, func: (msg: any) => boolean | void): void;

// =====================
// Memory API
// =====================
declare function peek(addr: number, count?: number): number | LuaMultiReturn<number[]>;
declare function poke(addr: number, ...values: number[]): void;
declare function peek2(addr: number): number;
declare function poke2(addr: number, val: number): void;
declare function peek4(addr: number): number;
declare function poke4(addr: number, val: number): void;
declare function peek8(addr: number): number;
declare function poke8(addr: number, val: number): void;
declare function memcpy(dest_addr: number, src_addr: number, count: number): void;
declare function memset(addr: number, value: number, count: number): void;
declare function reload(dest_addr: number, src_addr: number, count: number, filename?: string): void;
declare function memmap(ud: Userdata, addr: number): void;

// =====================
// Userdata API
// =====================
declare function userdata(data_type: UserdataType, width: number, height?: number, data?: string): Userdata;
declare function userdata(gfx_string: string): Userdata<"u8">;
declare function vec(...values: number[]): Userdata<"f64">;
declare function get(u: Userdata | null | undefined, x: number, n?: number): LuaMultiReturn<number[]>;
declare function get(u: Userdata | null | undefined, x: number, y: number, n?: number): LuaMultiReturn<number[]>;
declare function set(u: Userdata | null | undefined, x: number, ...values: number[]): void;
declare function set(u: Userdata | null | undefined, x: number, y: number, ...values: number[]): void;
declare function blit(src?: Userdata, dest?: Userdata, src_x?: number, src_y?: number, dest_x?: number, dest_y?: number, width?: number, height?: number): void;
declare function matmul(m0: Userdata<"f64">, m1: Userdata<"f64">, m_out?: Userdata<"f64">, batch_height?: number): Userdata<"f64">;
declare function matmul3d(m0: Userdata<"f64">, m1: Userdata<"f64">, m_out?: Userdata<"f64">, batch_height?: number): Userdata<"f64">;

// =====================
// Window API
// =====================
declare function window(attributes?: Partial<{
  width: number
  height: number
  title: string
  pauseable: boolean
  tabbled: boolean
  has_frame: boolean
  resizeable: boolean
  wallpapier: boolean
  autoclose: boolean
  z: number
  cursor: 0 | 1 | Userdata
  squashable: boolean
  background_updates: boolean
  background_draws: boolean
}>): any;
declare function window(width: number, height: number): any;
declare function get_display(): Userdata<"u8">;
declare function set_draw_target(ud?: Userdata<"u8">): void;
declare function get_draw_target(): Userdata<"u8">;
declare function vid(mode: number): void;

// =====================
// Undo Stacks
// =====================
interface UndoStack {
  checkpoint(extra?: any): void;
  undo(peek?: boolean): any;
  redo(peek?: boolean): any;
}
declare function create_undo_stack(save: (item?: any) => any, load: (dat: any, item?: any) => void, pod_flags?: number, item?: any): UndoStack;

// =====================
// Sockets
// =====================
interface Socket {
  read(): string | LuaMultiReturn<[null, string]>;
  write(str: string): number | LuaMultiReturn<[null, string]>;
  close(): void;
  status(): "ready" | "listening" | "closed" | "closed by peer" | "disconnected";
  accept(): Socket | null;
}
declare function socket(addr: string): Socket | null;

// =====================
// Userdata Memory
// =====================
declare function unmap(ud: Userdata, addr?: number): void;

// =====================
// Main Loop Callbacks
// =====================
declare var _init: () => void;
declare var _draw: () => void;
declare var _update: () => void;
declare var _update60: () => void;