Picotron-TypeScript/_G.d.ts
2025-12-28 14:09:34 +01:00

771 lines
20 KiB
TypeScript

// Picotron v0.2.1e Global API Type Definitions
// Userdata types
type UserdataType = "u8" | "i16" | "i32" | "i64" | "f64";
type UserdataDim = "1d" | "2d";
// Userdata interface
interface Userdata<T = UserdataType, D = UserdataDim> {
// Dimension methods
width(): number;
height(): number | null;
/**
* Returns width, height, type, dimensionality
*/
attribs(): LuaMultiReturn<[number, number, T, number]>;
// Element access — 1D
get(x: number): D extends "1d" ? number : LuaMultiReturn<number[]>;
get(x: number, n: number): D extends "1d" ? LuaMultiReturn<number[]> : number;
// Element access — 2D
// No n specified (defaults to 1, returns single number)
get(x: number, y: number): D extends "2d" ? number : LuaMultiReturn<number[]>;
// n = 0 (fast path, returns single number)
get(
x: number,
y: number,
n: 0
): D extends "2d" ? number : LuaMultiReturn<number[]>;
// n specified (returns multiple values)
get(
x: number,
y: number,
n: number
): D extends "2d" ? LuaMultiReturn<number[]> : 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): number;
declare function fget(n: number, f: 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,
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
// =====================
// 1D creation (width only) — allow specifying only D; T is inferred from first argument
declare function userdata<
D extends "1d" = "1d",
T extends UserdataType = UserdataType,
>(data_type: T, width: number, ...data: number[]): Userdata<T, D>;
// 2D creation (width + height) — allow specifying only D; T is inferred from first argument
declare function userdata<
D extends "2d" = "2d",
T extends UserdataType = UserdataType,
>(
data_type: T,
width: number,
height: number,
...data: number[]
): Userdata<T, D>;
// GFX string always yields 2D u8
declare function userdata(gfx_string: string): Userdata<"u8", "2d">;
// Vector helper produces 1D f64
declare function vec(...values: number[]): Userdata<"f64", "1d">;
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;