john/cell
1
0
Fork 0
Code Issues 31 Pull Requests Packages Projects Releases 2 Wiki Activity

add core docs

Browse Source
This commit is contained in:
John Alanbrook
2025-02-10 09:48:59 -06:00
parent 7283ced1ca
commit 375a6ad3a4
74 changed files with 5148 additions and 643 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/.pages
View File

@@ -6,7 +6,7 @@ nav:
- resources.md
- input.md
- exporting.md
- dull.md
- ...
- Appendix A - dull: dull
- Appendix B - api: api

12
docs/api/actor.md
View File

@@ -1,13 +1,11 @@
# actor
## actor
### toString() <sub>function</sub>
### toString
### spawn(script, config, callback) <sub>function</sub>
### spawn(script, config, callback)
### clear() <sub>function</sub>
### clear
### kill() <sub>function</sub>
### kill
### delay(fn, seconds)
### delay(fn, seconds) <sub>function</sub>

18
docs/api/console.md
View File

@@ -2,36 +2,36 @@
The console object provides various logging, debugging, and output methods.
### print
### print() <sub>function</sub>
### spam(msg)
### spam(msg) <sub>function</sub>
Output a spam-level message for very verbose logging.
### debug(msg)
### debug(msg) <sub>function</sub>
Output a debug-level message.
### info(msg)
### info(msg) <sub>function</sub>
Output info level message.
### warn(msg)
### warn(msg) <sub>function</sub>
Output warn level message.
### log(msg)
### log(msg) <sub>function</sub>
Output directly to in game console.
### error(e)
### error(e) <sub>function</sub>
Output error level message, and print stacktrace.
### panic(e)
### panic(e) <sub>function</sub>
Output a panic-level message and exit the program.
### assert(op, str = `assertion failed [value '${op}']`)
### assert(op, str = `assertion failed [value '${op}']`) <sub>function</sub>
If the condition is false, print an error and panic.

12
docs/api/modules/actor.md
View File

@@ -6,7 +6,7 @@ as managing tag-based lookups. Objects are assumed to have a "objects" property,
pointing to children or sub-objects, forming a tree.
### all_objects(fn, startobj)
### all_objects(fn, startobj) <sub>function</sub>
Iterate over each object (and its sub-objects) in the hierarchy, calling fn for each one.
@@ -20,7 +20,7 @@ Iterate over each object (and its sub-objects) in the hierarchy, calling fn for
**Returns**: The first truthy value returned by fn, or undefined if none.
### find_object(fn, startobj)
### find_object(fn, startobj) <sub>function</sub>
Intended to find a matching object within the hierarchy.
@@ -34,7 +34,7 @@ Intended to find a matching object within the hierarchy.
**Returns**: Not yet implemented.
### tag_add(tag, obj)
### tag_add(tag, obj) <sub>function</sub>
Associate the given object with the specified tag. Creates a new tag set if it does not exist.
@@ -48,7 +48,7 @@ Associate the given object with the specified tag. Creates a new tag set if it d
**Returns**: None
### tag_rm(tag, obj)
### tag_rm(tag, obj) <sub>function</sub>
Remove the given object from the specified tag’s set, if it exists.
@@ -62,7 +62,7 @@ Remove the given object from the specified tag’s set, if it exists.
**Returns**: None
### tag_clear_guid(obj)
### tag_clear_guid(obj) <sub>function</sub>
Remove the object from all tag sets.
@@ -74,7 +74,7 @@ Remove the object from all tag sets.
**Returns**: None
### objects_with_tag(tag)
### objects_with_tag(tag) <sub>function</sub>
Retrieve all objects currently tagged with the specified tag.

6
docs/api/modules/cmd.md
View File

@@ -1,3 +1,7 @@
# cmd
## cmd
### length <sub>number</sub>
### name <sub>string</sub>
### prototype <sub>object</sub>

6
docs/api/modules/color.md
View File

@@ -1,3 +1,7 @@
# color
## color
### Color <sub>object</sub>
### esc <sub>object</sub>
### ColorMap <sub>object</sub>

6
docs/api/modules/doc.md
View File

@@ -1,7 +1,5 @@
# doc
## doc
### writeDocFile(obj, title) <sub>function</sub>
### writeDocFile(obj, title)
Return a markdown string for a given obj, with optional title.
Return a markdown string for a given obj, with an optional title.

24
docs/api/modules/draw2d.md
View File

@@ -5,7 +5,7 @@ A collection of 2D drawing functions that operate in screen space. Provides prim
for lines, rectangles, text, sprite drawing, etc.
### point(pos, size, color)
### point(pos, size, color) <sub>function</sub>
@@ -20,7 +20,7 @@ for lines, rectangles, text, sprite drawing, etc.
**Returns**: None
### line(points, color, thickness, pipeline)
### line(points, color, thickness, pipeline) <sub>function</sub>
@@ -37,7 +37,7 @@ for lines, rectangles, text, sprite drawing, etc.
**Returns**: None
### cross(pos, size, color, thickness, pipe)
### cross(pos, size, color, thickness, pipe) <sub>function</sub>
@@ -56,7 +56,7 @@ for lines, rectangles, text, sprite drawing, etc.
**Returns**: None
### arrow(start, end, color, wingspan, wingangle, pipe)
### arrow(start, end, color, wingspan, wingangle, pipe) <sub>function</sub>
@@ -77,7 +77,7 @@ for lines, rectangles, text, sprite drawing, etc.
**Returns**: None
### rectangle(rect, color, pipeline)
### rectangle(rect, color, pipeline) <sub>function</sub>
@@ -92,7 +92,7 @@ for lines, rectangles, text, sprite drawing, etc.
**Returns**: None
### tile(image, rect, color, tile, pipeline)
### tile(image, rect, color, tile, pipeline) <sub>function</sub>
:raises Error: If no image is provided.
@@ -112,7 +112,7 @@ for lines, rectangles, text, sprite drawing, etc.
**Returns**: None
### slice9(image, rect, slice, color, info, pipeline)
### slice9(image, rect, slice, color, info, pipeline) <sub>function</sub>
:raises Error: If no image is provided.
@@ -134,7 +134,7 @@ for lines, rectangles, text, sprite drawing, etc.
**Returns**: None
### image(image, rect, rotation, color, pipeline)
### image(image, rect, rotation, color, pipeline) <sub>function</sub>
:raises Error: If no image is provided.
@@ -154,7 +154,7 @@ for lines, rectangles, text, sprite drawing, etc.
**Returns**: A sprite object that was created for this draw call.
### images(image, rects, config)
### images(image, rects, config) <sub>function</sub>
:raises Error: If no image is provided.
@@ -170,7 +170,7 @@ for lines, rectangles, text, sprite drawing, etc.
**Returns**: An array of sprite objects created and queued for rendering.
### sprites(sprites, sort, pipeline)
### sprites(sprites, sort, pipeline) <sub>function</sub>
@@ -185,7 +185,7 @@ for lines, rectangles, text, sprite drawing, etc.
**Returns**: None
### circle(pos, radius, color, inner_radius, pipeline)
### circle(pos, radius, color, inner_radius, pipeline) <sub>function</sub>
@@ -204,7 +204,7 @@ for lines, rectangles, text, sprite drawing, etc.
**Returns**: None
### text(text, rect, font, size, color, wrap, pipeline)
### text(text, rect, font, size, color, wrap, pipeline) <sub>function</sub>

6
docs/api/modules/event.md
View File

@@ -1,8 +1,6 @@
# event
## event
### push_event(event)
### push_event(event) <sub>function</sub>
Push a custom user event into SDL's queue, passing a callback function.
@@ -14,7 +12,7 @@ Push a custom user event into SDL's queue, passing a callback function.
**Returns**: None
### engine_input(callback)
### engine_input(callback) <sub>function</sub>
Poll all system events (keyboard, mouse, etc.) and call the given function with each event object.

97
docs/api/modules/geometry.md
View File

@@ -5,7 +5,7 @@ A collection of geometry-related functions for circles, spheres, boxes, polygons
and rectangle utilities. Some functionality is implemented in C and exposed here.
### rect_intersection(a, b)
### rect_intersection(a, b) <sub>function</sub>
Return the intersection of two rectangles. The result may be empty if no intersection.
@@ -19,7 +19,7 @@ Return the intersection of two rectangles. The result may be empty if no interse
**Returns**: A rectangle that is the intersection of the two. May have zero width/height if no overlap.
### rect_intersects(a, b)
### rect_intersects(a, b) <sub>function</sub>
@@ -32,7 +32,7 @@ Return the intersection of two rectangles. The result may be empty if no interse
**Returns**: A boolean indicating whether the two rectangles overlap.
### rect_expand(a, b)
### rect_expand(a, b) <sub>function</sub>
Merge or combine two rectangles, returning their bounding rectangle.
@@ -46,7 +46,7 @@ Merge or combine two rectangles, returning their bounding rectangle.
**Returns**: A new rectangle that covers the bounds of both input rectangles.
### rect_inside(inner, outer)
### rect_inside(inner, outer) <sub>function</sub>
@@ -59,7 +59,7 @@ Merge or combine two rectangles, returning their bounding rectangle.
**Returns**: True if 'inner' is completely inside 'outer', otherwise false.
### rect_random(rect)
### rect_random(rect) <sub>function</sub>
@@ -70,7 +70,7 @@ Merge or combine two rectangles, returning their bounding rectangle.
**Returns**: A random point within the rectangle (uniform distribution).
### cwh2rect(center, wh)
### cwh2rect(center, wh) <sub>function</sub>
Helper: convert a center point and width/height vector to a rect object.
@@ -84,7 +84,7 @@ Helper: convert a center point and width/height vector to a rect object.
**Returns**: A rectangle {x, y, w, h} with x,y set to center and w,h set to the given size.
### rect_point_inside(rect, point)
### rect_point_inside(rect, point) <sub>function</sub>
@@ -97,7 +97,7 @@ Helper: convert a center point and width/height vector to a rect object.
**Returns**: True if the point lies inside the rectangle, otherwise false.
### rect_pos(rect)
### rect_pos(rect) <sub>function</sub>
@@ -108,7 +108,7 @@ Helper: convert a center point and width/height vector to a rect object.
**Returns**: A 2D vector [x,y] giving the rectangle's position.
### rect_move(rect, offset)
### rect_move(rect, offset) <sub>function</sub>
@@ -121,7 +121,7 @@ Helper: convert a center point and width/height vector to a rect object.
**Returns**: A new rectangle with updated x,y offset.
### box(w, h)
### box(w, h) <sub>function</sub>
Construct a box centered at the origin with the given width and height. This overrides the box object above.
@@ -135,38 +135,15 @@ Construct a box centered at the origin with the given width and height. This ove
**Returns**: An array of four 2D points representing the corners of a rectangle centered at [0,0].
### sphere <sub>object</sub>
Sphere-related geometry functions:
- volume(r): Return the volume of a sphere with radius r.
- random(r, theta, phi): Return a random point on or inside a sphere.
#### volume(r)
**r**: The sphere radius.
**Returns**: The volume of the sphere, calculated as (4/3) * pi * r^3.
#### random(r, theta, phi)
Generate a random point inside a sphere of variable radius, distributing angles in the specified ranges.
**r**: A single number (radius) or a 2-element array [minRadius, maxRadius].
**theta**: A single number or 2-element array defining the range in turns for the theta angle, default [0,1].
**phi**: A single number or 2-element array defining the range in turns for the phi angle, default [-0.5,0.5].
**Returns**: A 3D point (x,y,z) randomly placed within a sphere.
### circle <sub>object</sub>
Circle-related geometry functions:
@@ -174,45 +151,7 @@ Circle-related geometry functions:
- random(r, theta): Return a random 2D point on a circle; uses sphere.random internally and extracts x,z.
#### area(r)
**r**: Radius of the circle.
**Returns**: The area, pi * r^2.
#### random(r, theta)
**r**: A radius or [minRadius, maxRadius].
**theta**: Angle range in turns (single number or [min,max]).
**Returns**: A 2D point (x,z) in the circle, using the sphere random generator and ignoring y.
#### points(radius, n)
Shortcut for geometry.arc(radius, 360, n).
**radius**: The circle's radius.
**n**: Number of points around the circle.
**Returns**: An array of 2D points equally spaced around a full 360-degree circle.
### ngon(radius, n)
### ngon(radius, n) <sub>function</sub>
Generates a regular n-gon by calling geometry.arc with full 360 degrees.
@@ -226,7 +165,7 @@ Generates a regular n-gon by calling geometry.arc with full 360 degrees.
**Returns**: An array of 2D points forming a regular n-gon.
### arc(radius, angle, n, start)
### arc(radius, angle, n, start) <sub>function</sub>
Generate an arc (or partial circle) of n points, each angle spread equally over 'angle' degrees from 'start'.
@@ -244,7 +183,7 @@ Generate an arc (or partial circle) of n points, each angle spread equally over
**Returns**: An array of 2D points along the arc.
### corners2points(ll, ur)
### corners2points(ll, ur) <sub>function</sub>
Similar to box.points, but calculates differently.
@@ -258,7 +197,7 @@ Similar to box.points, but calculates differently.
**Returns**: A four-point array of corners [ll, lower-right, upper-right, upper-left].
### sortpointsccw(points)
### sortpointsccw(points) <sub>function</sub>
Sort an array of points in CCW order based on their angles from the centroid.
@@ -270,7 +209,7 @@ Sort an array of points in CCW order based on their angles from the centroid.
**Returns**: A new array of the same points, sorted counterclockwise around their centroid.
### points2cm(points)
### points2cm(points) <sub>function</sub>

40
docs/api/modules/graphics.md
View File

@@ -6,7 +6,7 @@ Includes both JavaScript and C-implemented routines for creating geometry buffer
rectangle packing, etc.
### make_sprite_mesh(sprites)
### make_sprite_mesh(sprites) <sub>function</sub>
:param oldMesh (optional): An existing mesh object to reuse/resize if possible.
@@ -19,7 +19,7 @@ Given an array of sprites, build a single geometry mesh for rendering them.
**Returns**: A GPU mesh object with pos, uv, color, and indices buffers for all sprites.
### make_sprite_queue(sprites, camera, pipeline, sort)
### make_sprite_queue(sprites, camera, pipeline, sort) <sub>function</sub>
Given an array of sprites, optionally sort them, then build a queue of pipeline commands.
@@ -38,7 +38,7 @@ Each group with a shared image becomes one command.
**Returns**: An array of pipeline commands: geometry with mesh references, grouped by image.
### make_text_buffer(text, rect, angle, color, wrap, font)
### make_text_buffer(text, rect, angle, color, wrap, font) <sub>function</sub>
Generate a GPU buffer mesh of text quads for rendering with a font, etc.
@@ -60,7 +60,7 @@ Generate a GPU buffer mesh of text quads for rendering with a font, etc.
**Returns**: A geometry buffer mesh (pos, uv, color, indices) for rendering text.
### rectpack(width, height, sizes)
### rectpack(width, height, sizes) <sub>function</sub>
Perform a rectangle packing using the stbrp library. Return positions for each rect.
@@ -76,7 +76,7 @@ Perform a rectangle packing using the stbrp library. Return positions for each r
**Returns**: An array of [x,y] coordinates placing each rect, or null if they don't fit.
### make_rtree
### make_rtree() <sub>function</sub>
Create a new R-Tree for geometry queries.
@@ -85,7 +85,7 @@ Create a new R-Tree for geometry queries.
**Returns**: An R-Tree object for quickly querying many rectangles or sprite bounds.
### make_texture(data)
### make_texture(data) <sub>function</sub>
Convert raw image bytes into an SDL_Surface object.
@@ -97,7 +97,7 @@ Convert raw image bytes into an SDL_Surface object.
**Returns**: An SDL_Surface object representing the decoded image in RAM, for use with GPU or software rendering.
### make_gif(data)
### make_gif(data) <sub>function</sub>
Load a GIF, returning its frames. If it's a single-frame GIF, the result may have .surface only.
@@ -109,7 +109,7 @@ Load a GIF, returning its frames. If it's a single-frame GIF, the result may hav
**Returns**: An object with frames[], each frame having its own .surface. Some also have a .texture for GPU use.
### make_aseprite(data)
### make_aseprite(data) <sub>function</sub>
Load an Aseprite/ASE file from an array of bytes, returning frames or animations.
@@ -121,7 +121,7 @@ Load an Aseprite/ASE file from an array of bytes, returning frames or animations
**Returns**: An object containing frames or animations, each with .surface. May also have top-level .surface for a single-layer case.
### cull_sprites(sprites, camera)
### cull_sprites(sprites, camera) <sub>function</sub>
Filter an array of sprites to only those visible in the provided camera’s view.
@@ -135,7 +135,7 @@ Filter an array of sprites to only those visible in the provided camera’s view
**Returns**: A new array of sprites that are visible in the camera's view.
### rects_to_sprites(rects, image)
### rects_to_sprites(rects, image) <sub>function</sub>
Convert an array of rect coords into sprite objects referencing a single image.
@@ -149,7 +149,7 @@ Convert an array of rect coords into sprite objects referencing a single image.
**Returns**: An array of sprite objects referencing the 'image' and each rect for UV or position.
### make_surface(dimensions)
### make_surface(dimensions) <sub>function</sub>
Create a blank surface in RAM.
@@ -161,7 +161,7 @@ Create a blank surface in RAM.
**Returns**: A blank RGBA surface with the given dimensions, typically for software rendering or icons.
### make_cursor(opts)
### make_cursor(opts) <sub>function</sub>
@@ -172,7 +172,7 @@ Create a blank surface in RAM.
**Returns**: An SDL_Cursor object referencing the given surface for a custom mouse cursor.
### make_font(data, size)
### make_font(data, size) <sub>function</sub>
Load a font from TTF/OTF data at the given size.
@@ -186,7 +186,7 @@ Load a font from TTF/OTF data at the given size.
**Returns**: A font object with surface, texture, and glyph data, for text rendering with make_text_buffer.
### make_sprite
### make_sprite() <sub>function</sub>
Create a new sprite object, storing default properties.
@@ -195,7 +195,7 @@ Create a new sprite object, storing default properties.
**Returns**: A new sprite object, which typically has .rect, .color, .layer, .image, etc.
### make_line_prim(points, thickness, startCap, endCap, color)
### make_line_prim(points, thickness, startCap, endCap, color) <sub>function</sub>
Build a GPU mesh representing a thick polyline from an array of points, using parsl or a similar library under the hood.
@@ -215,7 +215,7 @@ Build a GPU mesh representing a thick polyline from an array of points, using pa
**Returns**: A geometry mesh object suitable for rendering the line via a pipeline command.
### is_image(obj)
### is_image(obj) <sub>function</sub>
@@ -226,7 +226,7 @@ Build a GPU mesh representing a thick polyline from an array of points, using pa
**Returns**: True if 'obj' has a .texture and a .rect property, indicating it's an image object.
### texture(path)
### texture(path) <sub>function</sub>
Load or retrieve a cached image, converting it into a GPU texture. If 'path' is already an object, it’s returned directly.
@@ -238,7 +238,7 @@ Load or retrieve a cached image, converting it into a GPU texture. If 'path' is
**Returns**: An image object with {surface, texture, frames?, etc.} depending on the format.
### tex_hotreload(file)
### tex_hotreload(file) <sub>function</sub>
Reload the image for the given file, updating the cached copy in memory and GPU.
@@ -250,7 +250,7 @@ Reload the image for the given file, updating the cached copy in memory and GPU.
**Returns**: None
### get_font(path, size)
### get_font(path, size) <sub>function</sub>
Load a font from file if not cached, or retrieve from cache if already loaded.
@@ -264,7 +264,7 @@ Load a font from file if not cached, or retrieve from cache if already loaded.
**Returns**: A font object with .surface and .texture for rendering text.
### queue_sprite_mesh(queue)
### queue_sprite_mesh(queue) <sub>function</sub>
Builds a single geometry mesh for all sprite-type commands in the queue, storing first_index/num_indices

2
docs/api/modules/imgui.md
View File

@@ -1,3 +1 @@
# imgui
## imgui

34
docs/api/modules/input.md
View File

@@ -1,8 +1,6 @@
# input
## input
### mouse_show(show)
### mouse_show(show) <sub>function</sub>
Show or hide the mouse cursor. Pass true to show, false to hide.
@@ -14,7 +12,7 @@ Show or hide the mouse cursor. Pass true to show, false to hide.
**Returns**: None
### mouse_lock(lock)
### mouse_lock(lock) <sub>function</sub>
Capture or release the mouse, confining it within the window if locked.
@@ -26,7 +24,7 @@ Capture or release the mouse, confining it within the window if locked.
**Returns**: None
### cursor_set(cursor)
### cursor_set(cursor) <sub>function</sub>
Set the given cursor (created by os.make_cursor) as the active mouse cursor.
@@ -38,7 +36,7 @@ Set the given cursor (created by os.make_cursor) as the active mouse cursor.
**Returns**: None
### keyname(keycode)
### keyname(keycode) <sub>function</sub>
Given a numeric keycode, return the corresponding key name (e.g., from SDL).
@@ -50,7 +48,7 @@ Given a numeric keycode, return the corresponding key name (e.g., from SDL).
**Returns**: A string with the key name.
### keymod
### keymod() <sub>function</sub>
Return an object describing the current modifier keys, e.g. {shift:true, ctrl:true}.
@@ -59,7 +57,7 @@ Return an object describing the current modifier keys, e.g. {shift:true, ctrl:tr
**Returns**: An object with boolean fields for each modifier key.
### mousestate
### mousestate() <sub>function</sub>
Return an object describing the current mouse state, including x,y coordinates
and booleans for pressed buttons (left, middle, right, x1, x2).
@@ -69,14 +67,22 @@ and booleans for pressed buttons (left, middle, right, x1, x2).
**Returns**: Object { x, y, left, middle, right, x1, x2 }
### print_pawn_kbm(pawn)
### mouse <sub>object</sub>
### procdown
### keyboard <sub>object</sub>
### print_md_kbm(pawn)
### print_pawn_kbm(pawn) <sub>function</sub>
### has_bind(pawn, bind)
### procdown() <sub>function</sub>
### tabcomplete(val, list)
### print_md_kbm(pawn) <sub>function</sub>
### do_uncontrol(pawn)
### has_bind(pawn, bind) <sub>function</sub>
### action <sub>object</sub>
### tabcomplete(val, list) <sub>function</sub>
### do_uncontrol(pawn) <sub>function</sub>
### player <sub>object</sub>

42
docs/api/modules/io.md
View File

@@ -1,8 +1,6 @@
# io
## io
### rm(path)
### rm(path) <sub>function</sub>
Remove the file or empty directory at the given path.
@@ -14,7 +12,7 @@ Remove the file or empty directory at the given path.
**Returns**: None
### mkdir(path)
### mkdir(path) <sub>function</sub>
Create a directory at the given path.
@@ -26,7 +24,7 @@ Create a directory at the given path.
**Returns**: None
### stat(path)
### stat(path) <sub>function</sub>
Return an object describing file metadata for the given path. The object includes
filesize, modtime, createtime, and accesstime. Throw an error if the path does not exist.
@@ -39,7 +37,7 @@ filesize, modtime, createtime, and accesstime. Throw an error if the path does n
**Returns**: An object with metadata (filesize, modtime, createtime, accesstime).
### globfs(patterns)
### globfs(patterns) <sub>function</sub>
Return an array of files that do not match any of the provided glob patterns. It
recursively enumerates the filesystem within PHYSFS. Each pattern is treated as an
@@ -53,7 +51,7 @@ recursively enumerates the filesystem within PHYSFS. Each pattern is treated as
**Returns**: An array of matching file paths.
### match(pattern, string)
### match(pattern, string) <sub>function</sub>
Return boolean indicating whether the given wildcard pattern matches the provided
string. Dots must match dots. Case is not ignored.
@@ -77,7 +75,7 @@ Patterns can incorporate:
**Returns**: True if matched, otherwise false.
### exists(path)
### exists(path) <sub>function</sub>
Return a boolean indicating whether the file or directory at the given path exists.
@@ -89,7 +87,7 @@ Return a boolean indicating whether the file or directory at the given path exis
**Returns**: True if the path exists, otherwise false.
### mount(archiveOrDir, mountPoint)
### mount(archiveOrDir, mountPoint) <sub>function</sub>
Mount a directory or archive at the specified mount point. An undefined mount
point mounts to '/'. Throw on error.
@@ -104,7 +102,7 @@ point mounts to '/'. Throw on error.
**Returns**: None
### unmount(path)
### unmount(path) <sub>function</sub>
Unmount a previously mounted directory or archive. Throw on error.
@@ -116,7 +114,7 @@ Unmount a previously mounted directory or archive. Throw on error.
**Returns**: None
### slurp(path)
### slurp(path) <sub>function</sub>
Read the entire file at the given path as a string. Throw on error.
@@ -128,7 +126,7 @@ Read the entire file at the given path as a string. Throw on error.
**Returns**: A string with the file’s contents.
### slurpbytes(path)
### slurpbytes(path) <sub>function</sub>
Read the entire file at the given path as a raw ArrayBuffer. Throw on error.
@@ -140,7 +138,7 @@ Read the entire file at the given path as a raw ArrayBuffer. Throw on error.
**Returns**: An ArrayBuffer containing the file’s raw bytes.
### slurpwrite(data, path)
### slurpwrite(data, path) <sub>function</sub>
Write data (string or ArrayBuffer) to the given file path. Overwrite if it exists.
Throw on error.
@@ -155,7 +153,7 @@ Throw on error.
**Returns**: None
### writepath(path)
### writepath(path) <sub>function</sub>
Set the write directory. Subsequent writes will go here by default. Throw on error.
@@ -167,7 +165,7 @@ Set the write directory. Subsequent writes will go here by default. Throw on err
**Returns**: None
### basedir
### basedir() <sub>function</sub>
Return the application's base directory (where the executable is located).
@@ -176,7 +174,7 @@ Return the application's base directory (where the executable is located).
**Returns**: A string with the base directory path.
### userdir
### userdir() <sub>function</sub>
Return the user's directory, often used for saving data.
@@ -185,7 +183,7 @@ Return the user's directory, often used for saving data.
**Returns**: A string with the user's directory path.
### realdir(path)
### realdir(path) <sub>function</sub>
Return the actual, real directory (on the host filesystem) that contains the given
file path. Return undefined if not found.
@@ -198,7 +196,7 @@ file path. Return undefined if not found.
**Returns**: A string with the real directory path, or undefined.
### open(path)
### open(path) <sub>function</sub>
Open a file for writing, returning a file object that can be used for further
operations. Throw on error.
@@ -211,7 +209,7 @@ operations. Throw on error.
**Returns**: A file object for subsequent write operations.
### searchpath
### searchpath() <sub>function</sub>
Return an array of all directories in the current paths.
@@ -220,7 +218,7 @@ Return an array of all directories in the current paths.
**Returns**: An array of directory paths in the search path.
### enumerate(path, recurse)
### enumerate(path, recurse) <sub>function</sub>
Return an array of files within the given directory, optionally recursing into
subdirectories.
@@ -235,6 +233,6 @@ subdirectories.
**Returns**: An array of file (and directory) paths found.
### mount_core
### mount_core() <sub>function</sub>
### is_directory
### is_directory() <sub>function</sub>

30
docs/api/modules/js.md
View File

@@ -5,7 +5,7 @@ Provides functions for introspecting and configuring the QuickJS runtime engine.
Includes debug info, memory usage, GC controls, code evaluation, etc.
### cycle_hook(callback)
### cycle_hook(callback) <sub>function</sub>
or undefined to remove the callback.
@@ -21,7 +21,7 @@ is undefined, the hook is removed.
**Returns**: None
### dump_shapes
### dump_shapes() <sub>function</sub>
Use this for internal debugging of object shapes.
@@ -30,7 +30,7 @@ Use this for internal debugging of object shapes.
**Returns**: A debug string describing the internal shape hierarchy used by QuickJS.
### dump_atoms
### dump_atoms() <sub>function</sub>
known by QuickJS. Helpful for diagnosing memory usage or potential key collisions.
@@ -39,7 +39,7 @@ known by QuickJS. Helpful for diagnosing memory usage or potential key collision
**Returns**: A debug string listing all currently registered atoms (internal property keys/symbols)
### dump_class
### dump_class() <sub>function</sub>
Shows how many objects of each class exist, useful for advanced memory or performance profiling.
@@ -48,7 +48,7 @@ Shows how many objects of each class exist, useful for advanced memory or perfor
**Returns**: A debug string describing the distribution of JS object classes in the QuickJS runtime.
### dump_objects
### dump_objects() <sub>function</sub>
useful for debugging memory leaks or object lifetimes.
@@ -57,7 +57,7 @@ useful for debugging memory leaks or object lifetimes.
**Returns**: A debug string listing certain internal QuickJS objects and their references,
### dump_type_overheads
### dump_type_overheads() <sub>function</sub>
Displays memory usage breakdown for different internal object types.
@@ -66,7 +66,7 @@ Displays memory usage breakdown for different internal object types.
**Returns**: A debug string describing the overheads for various JS object types in QuickJS.
### stack_info
### stack_info() <sub>function</sub>
Internal debugging utility to examine call stack details.
@@ -75,7 +75,7 @@ Internal debugging utility to examine call stack details.
**Returns**: An object or string describing the runtime's current stack usage and capacity.
### calc_mem(value)
### calc_mem(value) <sub>function</sub>
@@ -88,7 +88,7 @@ Compute the approximate size of a single JS value in memory. This is a best-effo
**Returns**: Approximate memory usage (in bytes) of that single value.
### mem
### mem() <sub>function</sub>
including total allocated bytes, object counts, and more.
@@ -99,7 +99,7 @@ Retrieve an overview of the runtime’s memory usage.
**Returns**: An object containing a comprehensive snapshot of memory usage for the current QuickJS runtime,
### mem_limit(bytes)
### mem_limit(bytes) <sub>function</sub>
@@ -113,7 +113,7 @@ fail or throw errors.
**Returns**: None
### gc_threshold(bytes)
### gc_threshold(bytes) <sub>function</sub>
@@ -126,7 +126,7 @@ Set the threshold (in bytes) for QuickJS to perform an automatic GC pass when me
**Returns**: None
### max_stacksize(bytes)
### max_stacksize(bytes) <sub>function</sub>
@@ -139,7 +139,7 @@ Set the maximum stack size for QuickJS. If exceeded, the runtime may throw a sta
**Returns**: None
### memstate
### memstate() <sub>function</sub>
@@ -149,7 +149,7 @@ Gives a quick overview of the memory usage, including malloc size and other allo
**Returns**: A simpler memory usage object (malloc sizes, etc.) for the QuickJS runtime.
### gc
### gc() <sub>function</sub>
@@ -159,7 +159,7 @@ Force an immediate, full garbage collection pass, reclaiming unreachable memory.
**Returns**: None
### eval(src, filename)
### eval(src, filename) <sub>function</sub>

6
docs/api/modules/json.md
View File

@@ -1,8 +1,6 @@
# json
## json
### encode(val,space,replacer,whitelist)
### encode(val,space,replacer,whitelist) <sub>function</sub>
Produce a JSON text from a Javascript object. If a record value, at any level, contains a json() method, it will be called, and the value it returns (usually a simpler record) will be JSONified.
@@ -10,7 +8,7 @@ If the record does not have a json() method, and if whitelist is a record, then
If the space input is true, then line breaks and extra whitespace will be included in the text.
### decode(text,reviver)
### decode(text,reviver) <sub>function</sub>
The text text is parsed, and the resulting value (usually a record or an array) is returned.

4
docs/api/modules/loop.md
View File

@@ -1,5 +1,3 @@
# loop
## loop
### step
### step() <sub>function</sub>

66
docs/api/modules/math.md
View File

@@ -1,115 +1,115 @@
# math
## math
### dot
### dot() <sub>function</sub>
Compute the dot product between two numeric arrays, returning a scalar. Extra elements are ignored.
### project
### project() <sub>function</sub>
Project one vector onto another, returning a new array of the same dimension.
### rotate
### rotate() <sub>function</sub>
Rotate a 2D point (or array of length 2) by the given angle (in turns) around an optional pivot.
### midpoint
### midpoint() <sub>function</sub>
Compute the midpoint of two arrays of numbers. Only the first two entries are used if 2D is intended.
### reflect
### reflect() <sub>function</sub>
Reflect a vector across a plane normal. Both arguments must be numeric arrays.
### distance
### distance() <sub>function</sub>
Compute the Euclidean distance between two numeric arrays of matching length.
### direction
### direction() <sub>function</sub>
Compute the normalized direction vector from the first array to the second.
### angle
### angle() <sub>function</sub>
Given a 2D vector, return its angle from the X-axis in radians or some chosen units.
### norm
### norm() <sub>function</sub>
Return a normalized copy of the given numeric array. For 2D/3D/4D or arbitrary length.
### angle_between
### angle_between() <sub>function</sub>
Compute the angle between two vectors (2D/3D/4D).
### lerp
### lerp() <sub>function</sub>
Linear interpolation between two numbers: lerp(a, b, t).
### gcd
### gcd() <sub>function</sub>
Compute the greatest common divisor of two integers.
### lcm
### lcm() <sub>function</sub>
Compute the least common multiple of two integers.
### clamp
### clamp() <sub>function</sub>
Clamp a number between low and high. clamp(value, low, high).
### angledist
### angledist() <sub>function</sub>
Compute the signed distance between two angles in 'turn' units, e.g. 0..1 range.
### jitter
### jitter() <sub>function</sub>
Apply a random +/- percentage noise to a number. Example: jitter(100, 0.05) -> ~95..105.
### mean
### mean() <sub>function</sub>
Compute the arithmetic mean of an array of numbers.
### sum
### sum() <sub>function</sub>
Sum all elements of an array of numbers.
### sigma
### sigma() <sub>function</sub>
Compute standard deviation of an array of numbers.
### median
### median() <sub>function</sub>
Compute the median of an array of numbers.
### length
### length() <sub>function</sub>
Return the length of a vector (i.e. sqrt of sum of squares).
### from_to
### from_to() <sub>function</sub>
Return an array of points from a start to an end, spaced out by a certain distance.
### rand
### rand() <sub>function</sub>
Return a random float in [0,1).
### randi
### randi() <sub>function</sub>
Return a random 32-bit integer.
### srand
### srand() <sub>function</sub>
Seed the random number generator with the given integer, or with current time if none.
### deg2rad(deg)
### TAU <sub>number</sub>
### rad2deg(rad)
### deg2rad(deg) <sub>function</sub>
### turn2rad(x)
### rad2deg(rad) <sub>function</sub>
### rad2turn(x)
### turn2rad(x) <sub>function</sub>
### turn2deg(x)
### rad2turn(x) <sub>function</sub>
### deg2turn(x)
### turn2deg(x) <sub>function</sub>
### deg2turn(x) <sub>function</sub>

26
docs/api/modules/miniz.md
View File

@@ -1,3 +1,27 @@
# miniz
## miniz
### read(data) <sub>function</sub>
Create a zip reader from the given ArrayBuffer containing an entire ZIP archive.
Return undefined if the data is invalid.
**data**: An ArrayBuffer with the entire ZIP file.
**Returns**: A 'zip reader' object with methods for reading from the archive (mod, exists, slurp).
### write(path) <sub>function</sub>
Create a zip writer that writes to the specified file path. Overwrites the file if
it already exists. Return undefined on error.
**path**: The file path where the ZIP archive will be written.
**Returns**: A 'zip writer' object with methods for adding files to the archive (add_file).

52
docs/api/modules/os.md
View File

@@ -1,103 +1,101 @@
# os
## os
### make_transform
### make_transform() <sub>function</sub>
Create a new transform object that can be used for 2D/3D positioning, scaling, and rotation.
### clean_transforms
### clean_transforms() <sub>function</sub>
Force an update on all transforms to remove dangling references or perform house-keeping.
### platform
### platform() <sub>function</sub>
Return a string with the underlying platform name, like 'Windows', 'Linux', or 'macOS'.
### arch
### arch() <sub>function</sub>
Return the CPU architecture string for this system (e.g. 'x64', 'arm64').
### totalmem
### totalmem() <sub>function</sub>
Return the total system RAM in bytes.
### freemem
### freemem() <sub>function</sub>
Return the amount of free system RAM in bytes, if known.
### hostname
### hostname() <sub>function</sub>
Return the system's hostname, or an empty string if not available.
### version
### version() <sub>function</sub>
Return the OS or kernel version string, if the platform provides it.
### kill
### kill() <sub>function</sub>
Send a signal (e.g., 'SIGINT', 'SIGTERM', etc.) to the current process.
### exit
### exit() <sub>function</sub>
Exit the application with the specified exit code.
### now
### now() <sub>function</sub>
Return current time (in seconds as a float) with high resolution.
### openurl
### openurl() <sub>function</sub>
Open the provided URL in the default web browser, if possible.
### make_timer
### make_timer() <sub>function</sub>
Create a new timer object that will call a specified function after a certain delay.
### update_timers
### update_timers() <sub>function</sub>
Advance all timers by the provided time delta (in seconds).
### sleep
### sleep() <sub>function</sub>
Block execution for the specified number of seconds.
### battery_pct
### battery_pct() <sub>function</sub>
Return the battery level (percentage) or negative if unknown.
### battery_voltage
### battery_voltage() <sub>function</sub>
Return the current battery voltage in volts, if available.
### battery_seconds
### battery_seconds() <sub>function</sub>
Return the estimated remaining battery time in seconds, or negative if unknown.
### power_state
### power_state() <sub>function</sub>
Return a string describing power status: 'on battery', 'charging', 'charged', etc.
### on
### on() <sub>function</sub>
Register a global callback for certain engine-wide or system-level events.
### rt_info
### rt_info() <sub>function</sub>
Return internal QuickJS runtime info, such as object counts.
### rusage
### rusage() <sub>function</sub>
Return resource usage stats for this process, if the platform supports it.
### mallinfo
### mallinfo() <sub>function</sub>
Return detailed memory allocation info (arena size, free blocks, etc.) on some platforms.
### env
### env() <sub>function</sub>
Fetch the value of a given environment variable, or undefined if it doesn't exist.
### system
### system() <sub>function</sub>
Execute a shell command using the system() call. Returns the command's exit code.

8
docs/api/modules/packer.md
View File

@@ -1,8 +1,6 @@
# packer
## packer
### getAllFiles(dir)
### getAllFiles(dir) <sub>function</sub>
Return a list of all files in the given directory that are not matched by .prosperonignore,
@@ -16,7 +14,7 @@ skipping directories.
**Returns**: An array of file paths found.
### gatherStats(filePaths)
### gatherStats(filePaths) <sub>function</sub>
Analyze a list of files and categorize them as modules, programs, images, or other.
@@ -29,7 +27,7 @@ Analyze a list of files and categorize them as modules, programs, images, or oth
**Returns**: An object { modules, programs, images, other, total } with counts.
### pack(dir, outPath)
### pack(dir, outPath) <sub>function</sub>
Create a ZIP archive of all files (skipping those matched by .prosperonignore) in the

30
docs/api/modules/render.md
View File

@@ -1,25 +1,15 @@
# render
## render
### _main <sub>object</sub>
A handle for low-level GPU operations via SDL GPU. Freed on GC.
An application window, created via prosperon.engine_start or SDL calls. Freed on GC.
### device <sub>object</sub>
### stencil_writer(...args) <sub>function</sub>
#### present
Perform the per-frame rendering and present the final swapchain image, including imgui pass if available.
**Returns**: None
### stencil_writer(...args)
### fillmask(ref)
### fillmask(ref) <sub>function</sub>
Draw a fullscreen shape using a 'screenfill' shader to populate the stencil buffer with a given reference.
@@ -31,7 +21,7 @@ Draw a fullscreen shape using a 'screenfill' shader to populate the stencil buff
**Returns**: None
### mask(image, pos, scale, rotation, ref)
### mask(image, pos, scale, rotation, ref) <sub>function</sub>
Draw an image to the stencil buffer, marking its area with a specified reference value.
@@ -51,7 +41,7 @@ Draw an image to the stencil buffer, marking its area with a specified reference
**Returns**: None
### viewport(rect)
### viewport(rect) <sub>function</sub>
Set the GPU viewport to the specified rectangle.
@@ -63,7 +53,7 @@ Set the GPU viewport to the specified rectangle.
**Returns**: None
### scissor(rect)
### scissor(rect) <sub>function</sub>
Set the GPU scissor region to the specified rectangle (alias of render.viewport).
@@ -75,7 +65,7 @@ Set the GPU scissor region to the specified rectangle (alias of render.viewport)
**Returns**: None
### queue(cmd)
### queue(cmd) <sub>function</sub>
Enqueue one or more draw commands. These commands are batched until render_camera is called.
@@ -87,7 +77,7 @@ Enqueue one or more draw commands. These commands are batched until render_camer
**Returns**: None
### setup_draw
### setup_draw() <sub>function</sub>
Switch the current queue to the primary scene render queue, then invoke 'prosperon.draw' if defined.
@@ -96,7 +86,7 @@ Switch the current queue to the primary scene render queue, then invoke 'prosper
**Returns**: None
### setup_hud
### setup_hud() <sub>function</sub>
Switch the current queue to the HUD render queue, then invoke 'prosperon.hud' if defined.

26
docs/api/modules/resources.md
View File

@@ -1,18 +1,26 @@
# resources
## resources
### scripts <sub>object</sub>
### canonical(file)
### images <sub>object</sub>
### find_image(...args)
### sounds <sub>object</sub>
### find_sound(...args)
### fonts <sub>object</sub>
### find_script(...args)
### lib <sub>object</sub>
### find_font(...args)
### canonical(file) <sub>function</sub>
### getAllFiles(dir)
### find_image(...args) <sub>function</sub>
### find_sound(...args) <sub>function</sub>
### find_script(...args) <sub>function</sub>
### find_font(...args) <sub>function</sub>
### getAllFiles(dir) <sub>function</sub>
Return a list of recognized files in the given directory that are not matched by
@@ -27,7 +35,7 @@ images, sounds, fonts, and libs.
**Returns**: An array of recognized file paths.
### gatherStats(filePaths)
### gatherStats(filePaths) <sub>function</sub>
Analyze a list of recognized files and categorize them by scripts, images, sounds,
@@ -41,7 +49,7 @@ fonts, libs, or other. Return a stats object with these counts and the total.
**Returns**: { scripts, images, sounds, fonts, lib, other, total }
### pack(dir, outPath)
### pack(dir, outPath) <sub>function</sub>
Create a ZIP archive of all recognized files (skipping those matched by .prosperonignore)

10
docs/api/modules/sound.md
View File

@@ -1,11 +1,11 @@
# sound
## sound
### undefined <sub>string</sub>
### pcm(file)
### pcm(file) <sub>function</sub>
### play(file)
### play(file) <sub>function</sub>
### cry(file)
### cry(file) <sub>function</sub>
### music(file, fade = 0.5)
### music(file, fade = 0.5) <sub>function</sub>

6
docs/api/modules/spline.md
View File

@@ -1,11 +1,9 @@
# spline
## spline
### catmull
### catmull() <sub>function</sub>
Perform Catmull-Rom spline sampling on an array of 2D points, returning an array of samples.
### bezier
### bezier() <sub>function</sub>
Perform a Bezier spline (or catmull) sampling on 2D points, returning an array of sampled points.

74
docs/api/modules/time.md
View File

@@ -2,54 +2,102 @@
The main time object, handling date/time utilities in earth-seconds.
### now
### now() <sub>function</sub>
Return the current system time in seconds (implemented in C extension).
### computer_dst
### computer_dst() <sub>function</sub>
Return true if local system time is currently in DST (implemented in C extension).
### computer_zone
### computer_zone() <sub>function</sub>
Return local time zone offset from UTC in hours (implemented in C extension).
### hour2minute
### second <sub>number</sub>
Number of seconds in a (real) second (always 1).
### minute <sub>number</sub>
Number of seconds in a minute (60).
### hour <sub>number</sub>
Number of seconds in an hour (3600).
### day <sub>number</sub>
Number of seconds in a day (86400).
### week <sub>number</sub>
Number of seconds in a week (604800).
### weekdays <sub>object</sub>
Names of the days of the week, Sunday through Saturday.
### monthstr <sub>object</sub>
Full names of the months of the year, January through December.
### epoch <sub>number</sub>
Base epoch year, from which day 0 is calculated (default 1970).
### hour2minute() <sub>function</sub>
Return the ratio of hour to minute in seconds, e.g. 3600 / 60 => 60.
### day2hour
### day2hour() <sub>function</sub>
Return the ratio of day to hour in seconds, e.g. 86400 / 3600 => 24.
### minute2second
### minute2second() <sub>function</sub>
Return the ratio of minute to second in seconds, e.g. 60 / 1 => 60.
### week2day
### week2day() <sub>function</sub>
Return the ratio of week to day in seconds, e.g. 604800 / 86400 => 7.
### isleap(year)
### strparse <sub>object</sub>
Mapping of format tokens (yyyy, mm, dd, etc.) to time fields (year, month, day...).
### isleap(year) <sub>function</sub>
Return true if a given year is leap, based on whether it has 366 days.
### yearsize(y)
### yearsize(y) <sub>function</sub>
Given a year, return 365 or 366 depending on leap-year rules.
### timecode(t, fps = 24)
### timecode(t, fps = 24) <sub>function</sub>
Convert seconds into a "S:frames" timecode string, with optional FPS (default 24).
### record(num, zone = this.computer_zone()
### monthdays <sub>object</sub>
An array of days in each month for a non-leap year.
### zones <sub>object</sub>
Table of recognized time zone abbreviations, with offsets (e.g., "-12" -> "IDLW").
### record(num, zone = this.computer_zone() <sub>function</sub>
Convert a timestamp (in seconds) into a record with fields like day, month, year, etc.
### number(rec)
### number(rec) <sub>function</sub>
Convert a record back into a numeric timestamp (seconds).
### text(num, fmt = this.fmt, zone)
### fmt <sub>string</sub>
Default format string for time.text(), containing tokens like 'yyyy', 'dd', 'hh', etc.
### text(num, fmt = this.fmt, zone) <sub>function</sub>
Format a numeric or record time into a string using a format pattern, e.g. 'hh:nn:ss'.

24
docs/api/modules/tween.md
View File

@@ -1,6 +1,6 @@
# tween
## tween
### Tween <sub>object</sub>
An object providing methods to create and control tweens with additional features
@@ -13,17 +13,7 @@ Methods:
- make: Alias of start.
#### start(obj, target, tvals, options)
Alias of Tween.start. See Tween.start for usage details.
#### make(obj, target, tvals, options)
Alias of Tween.start. See Tween.start for usage details.
### Ease <sub>object</sub>
This object provides multiple easing functions that remap a 0..1 input to produce
@@ -44,15 +34,7 @@ Available functions:
All easing functions expect t in [0..1] and return a remapped value in [0..1].
#### linear(t)
#### in(t)
#### out(t)
#### inout(t)
### tween(from, to, time, fn, cb)
### tween(from, to, time, fn, cb) <sub>function</sub>

26
docs/api/modules/util.md
View File

@@ -5,7 +5,7 @@ A collection of general-purpose utility functions for object manipulation, mergi
deep copying, safe property access, etc.
### guid
### guid() <sub>function</sub>
Return a random 32-character hexadecimal UUID-like string (not guaranteed RFC4122-compliant).
@@ -14,7 +14,7 @@ Return a random 32-character hexadecimal UUID-like string (not guaranteed RFC412
**Returns**: A random 32-character string (hex).
### insertion_sort(arr, cmp)
### insertion_sort(arr, cmp) <sub>function</sub>
In-place insertion sort of an array using cmp(a,b)->Number for ordering.
@@ -28,7 +28,7 @@ In-place insertion sort of an array using cmp(a,b)->Number for ordering.
**Returns**: The same array, sorted in-place.
### deepfreeze(obj)
### deepfreeze(obj) <sub>function</sub>
Recursively freeze an object and all of its nested objects so they cannot be modified.
@@ -40,7 +40,7 @@ Recursively freeze an object and all of its nested objects so they cannot be mod
**Returns**: None
### dainty_assign(target, source)
### dainty_assign(target, source) <sub>function</sub>
Copy non-function properties from source into matching keys of target without overwriting
@@ -55,7 +55,7 @@ keys that don't exist in target. Arrays are deep-copied, and objects are recursi
**Returns**: None
### get(obj, path, defValue)
### get(obj, path, defValue) <sub>function</sub>
Safely retrieve a nested property from obj at path (array or dot-string).
@@ -72,7 +72,7 @@ Returns defValue if the property is undefined.
**Returns**: The nested property or defValue.
### isEmpty(o)
### isEmpty(o) <sub>function</sub>
Return true if the object has no own properties, otherwise false.
@@ -84,7 +84,7 @@ Return true if the object has no own properties, otherwise false.
**Returns**: Boolean indicating if the object is empty.
### dig(obj, path, def)
### dig(obj, path, def) <sub>function</sub>
Ensure a nested path of objects exists inside obj; create objects if missing, and set
@@ -101,7 +101,7 @@ the final path component to def.
**Returns**: The assigned final value.
### access(obj, name)
### access(obj, name) <sub>function</sub>
Traverse obj by dot-separated path name, returning the final value or undefined
@@ -116,7 +116,7 @@ if any step is missing.
**Returns**: The value at that path, or undefined if missing.
### mergekey(o1, o2, k)
### mergekey(o1, o2, k) <sub>function</sub>
Helper for merge, updating key k from o2 into o1. Arrays are deep-copied and objects are
@@ -133,7 +133,7 @@ recursively merged.
**Returns**: None
### merge(target, objs)
### merge(target, objs) <sub>function</sub>
Merge all passed objects into target, copying or merging each key as needed.
@@ -148,7 +148,7 @@ Arrays are deep-copied, objects are recursively merged, etc.
**Returns**: The updated target object.
### copy(proto, objs)
### copy(proto, objs) <sub>function</sub>
Create a new object with proto as its prototype, then mix in additional objects’ properties.
@@ -162,7 +162,7 @@ Create a new object with proto as its prototype, then mix in additional objects
**Returns**: The newly created object.
### obj_lerp(a, b, t)
### obj_lerp(a, b, t) <sub>function</sub>
Linearly interpolate between two objects a and b by factor t, assuming each property
@@ -179,7 +179,7 @@ supports .lerp().
**Returns**: A new object with interpolated properties.
### normalizeSpacing(spacing)
### normalizeSpacing(spacing) <sub>function</sub>
Normalize any spacing input into a {l, r, t, b} object.

4
docs/api/modules/video.md
View File

@@ -1,7 +1,5 @@
# video
## video
### make_video
### make_video() <sub>function</sub>
Decode a video file (MPEG, etc.) from an ArrayBuffer, returning a datastream object.

108
docs/api/prosperon.md
View File

@@ -1,51 +1,103 @@
# prosperon
## prosperon
### c_types <sub>object</sub>
### engine_start
### argv <sub>object</sub>
### on(type, callback)
### version <sub>string</sub>
### dispatch(type, data)
### revision <sub>string</sub>
### appupdate(...args)
### engine_start() <sub>function</sub>
### update(...args)
### DOC <sub>symbol</sub>
### physupdate(...args)
### on(type, callback) <sub>function</sub>
### gui(...args)
### dispatch(type, data) <sub>function</sub>
### hud(...args)
### PATH <sub>object</sub>
### draw(...args)
### appupdate(...args) <sub>function</sub>
### imgui(...args)
### update(...args) <sub>function</sub>
### app(...args)
### physupdate(...args) <sub>function</sub>
### camera
### gui(...args) <sub>function</sub>
A hierarchical transform storing 3D or 2D position, rotation (as a quaternion),
and scale. Can have a parent transform. Freed automatically on GC.
### hud(...args) <sub>function</sub>
### draw(...args) <sub>function</sub>
### imgui(...args) <sub>function</sub>
### app(...args) <sub>function</sub>
### date <sub>string</sub>
### camera <sub>object</sub>
### debug <sub>boolean</sub>
### semver <sub>object</sub>
### title <sub>string</sub>
### width <sub>number</sub>
### height <sub>number</sub>
### size <sub>object</sub>
### icon <sub>object</sub>
### high_dpi <sub>number</sub>
### alpha <sub>number</sub>
### fullscreen <sub>number</sub>
### sample_count <sub>number</sub>
### enable_clipboard <sub>boolean</sub>
### enable_dragndrop <sub>boolean</sub>
### max_dropped_files <sub>number</sub>
### swap_interval <sub>number</sub>
### name <sub>string</sub>
### identifier <sub>string</sub>
### creator <sub>string</sub>
### copyright <sub>string</sub>
### type <sub>string</sub>
### url <sub>string</sub>
### postvals <sub>object</sub>
### hudcam <sub>object</sub>
### appcam <sub>object</sub>
### screencolor <sub>object</sub>
### window <sub>object</sub>
An application window, created via prosperon.engine_start or SDL calls. Freed on GC.
### font <sub>object</sub>
### gpu <sub>object</sub>
A handle for low-level GPU operations via SDL GPU. Freed on GC.
An application window, created via prosperon.engine_start or SDL calls. Freed on GC.
#### present
Perform the per-frame rendering and present the final swapchain image, including imgui pass if available.
**Returns**: None
### exit
### exit() <sub>function</sub>

10
docs/api/types/PHYSFS_File.md
View File

@@ -3,7 +3,7 @@
A file handle opened via PhysFS for writing or reading. Freed automatically when references go away.
### close
### close() <sub>function</sub>
Close this file handle. Throws on error.
@@ -12,7 +12,7 @@ Close this file handle. Throws on error.
**Returns**: None
### write(data)
### write(data) <sub>function</sub>
Write data (string or ArrayBuffer) to the file. Throws on error.
@@ -24,7 +24,7 @@ Write data (string or ArrayBuffer) to the file. Throws on error.
**Returns**: None
### buffer(size)
### buffer(size) <sub>function</sub>
Enable an internal write buffer of the given size on this file.
@@ -36,7 +36,7 @@ Enable an internal write buffer of the given size on this file.
**Returns**: None
### tell
### tell() <sub>function</sub>
Return the current position in the file.
@@ -45,7 +45,7 @@ Return the current position in the file.
**Returns**: A numeric offset.
### eof
### eof() <sub>function</sub>
Return whether the file pointer is at end-of-file.

4
docs/api/types/SDL_Camera.md
View File

@@ -3,7 +3,7 @@
A handle to a physical camera device. Freed when references drop or camera is closed.
### frame
### frame() <sub>function</sub>
Acquire the latest camera frame (as an SDL_Surface). Returns undefined if no
new frame is available yet. Throws on error.
@@ -13,7 +13,7 @@ new frame is available yet. Throws on error.
**Returns**: SDL_Surface or undefined.
### release_frame(surface)
### release_frame(surface) <sub>function</sub>
Release a frame surface previously acquired via camera.frame(). Must be
done for each acquired frame.

4
docs/api/types/SDL_GPUBuffer.md
View File

@@ -1,5 +1,3 @@
# SDL_GPUBuffer
## SDL_GPUBuffer
### name
### name() <sub>function</sub>

36
docs/api/types/SDL_GPUCommandBuffer.md
View File

@@ -3,7 +3,7 @@
A command buffer that accumulates rendering, copy, and compute operations. Freed after submission or GC.
### render_pass(passDesc)
### render_pass(passDesc) <sub>function</sub>
Begin a render pass with color/depth attachments. Provide an object with
'color_targets' and optional 'depth_stencil'. Returns an SDL_GPURenderPass handle.
@@ -16,7 +16,7 @@ Begin a render pass with color/depth attachments. Provide an object with
**Returns**: SDL_GPURenderPass
### compute_pass(storageTextures, storageBuffers)
### compute_pass(storageTextures, storageBuffers) <sub>function</sub>
Begin a compute pass reading/writing given arrays of textures and buffers.
@@ -30,7 +30,7 @@ Begin a compute pass reading/writing given arrays of textures and buffers.
**Returns**: SDL_GPUComputePass
### swapchain_pass(clearColor)
### swapchain_pass(clearColor) <sub>function</sub>
Begin a render pass that directly targets the swapchain (the window). Clears
with the specified color.
@@ -43,7 +43,7 @@ with the specified color.
**Returns**: SDL_GPURenderPass
### acquire_swapchain
### acquire_swapchain() <sub>function</sub>
Acquire the current swapchain texture from the window. Internal usage.
@@ -52,7 +52,7 @@ Acquire the current swapchain texture from the window. Internal usage.
**Returns**: SDL_GPUTexture handle
### bind_vertex_buffer(slot, buffer)
### bind_vertex_buffer(slot, buffer) <sub>function</sub>
Bind a GPU buffer as the vertex buffer at a given slot.
@@ -66,7 +66,7 @@ Bind a GPU buffer as the vertex buffer at a given slot.
**Returns**: None
### bind_index_buffer(buffer, offset)
### bind_index_buffer(buffer, offset) <sub>function</sub>
Bind a GPU buffer as the index buffer (16-bit or 32-bit).
@@ -80,7 +80,7 @@ Bind a GPU buffer as the index buffer (16-bit or 32-bit).
**Returns**: None
### bind_fragment_sampler(slot, texture, sampler)
### bind_fragment_sampler(slot, texture, sampler) <sub>function</sub>
Bind a texture+sampler pair to a particular fragment shader slot.
@@ -96,7 +96,7 @@ Bind a texture+sampler pair to a particular fragment shader slot.
**Returns**: None
### push_vertex_uniform_data(slot, data)
### push_vertex_uniform_data(slot, data) <sub>function</sub>
Push raw data to a vertex shader uniform block.
@@ -110,7 +110,7 @@ Push raw data to a vertex shader uniform block.
**Returns**: None
### push_fragment_uniform_data(slot, data)
### push_fragment_uniform_data(slot, data) <sub>function</sub>
Push raw data to a fragment shader uniform block.
@@ -124,7 +124,7 @@ Push raw data to a fragment shader uniform block.
**Returns**: None
### push_compute_uniform_data(slot, data)
### push_compute_uniform_data(slot, data) <sub>function</sub>
Push raw data to a compute shader uniform buffer.
@@ -138,7 +138,7 @@ Push raw data to a compute shader uniform buffer.
**Returns**: None
### submit
### submit() <sub>function</sub>
Submit this command buffer to the GPU and return a fence for synchronization.
@@ -147,7 +147,7 @@ Submit this command buffer to the GPU and return a fence for synchronization.
**Returns**: An SDL_GPUFence
### cancel
### cancel() <sub>function</sub>
Cancel (discard) this command buffer without submitting.
@@ -156,7 +156,7 @@ Cancel (discard) this command buffer without submitting.
**Returns**: None
### camera(cameraTransform, uniformSlot)
### camera(cameraTransform, uniformSlot) <sub>function</sub>
Write a camera transform (projection/view) to a uniform slot for 3D or 2D usage.
@@ -170,7 +170,7 @@ Write a camera transform (projection/view) to a uniform slot for 3D or 2D usage.
**Returns**: None
### hud(sizeVec2, uniformSlot)
### hud(sizeVec2, uniformSlot) <sub>function</sub>
Write an orthographic full-screen "HUD" matrix to a uniform slot. Typically used
for 2D overlays.
@@ -185,7 +185,7 @@ for 2D overlays.
**Returns**: None
### push_debug_group(name)
### push_debug_group(name) <sub>function</sub>
Push a named debug group marker onto the GPU command list (for debuggers/profilers).
@@ -197,7 +197,7 @@ Push a named debug group marker onto the GPU command list (for debuggers/profile
**Returns**: None
### pop_debug_group
### pop_debug_group() <sub>function</sub>
Pop the most recent debug group marker.
@@ -206,7 +206,7 @@ Pop the most recent debug group marker.
**Returns**: None
### debug_label(label)
### debug_label(label) <sub>function</sub>
Insert a one-off debug label at the current spot in the command list.
@@ -218,7 +218,7 @@ Insert a one-off debug label at the current spot in the command list.
**Returns**: None
### blit(blitDesc)
### blit(blitDesc) <sub>function</sub>
Blit one GPU texture to another with optional flip mode, filter, and clear operations.

12
docs/api/types/SDL_GPUComputePass.md
View File

@@ -3,7 +3,7 @@
A compute pass for dispatching compute pipelines. Freed after end() or GC.
### dispatch(x, y, z)
### dispatch(x, y, z) <sub>function</sub>
Dispatch the compute pipeline with the specified threadgroup counts.
@@ -19,7 +19,7 @@ Dispatch the compute pipeline with the specified threadgroup counts.
**Returns**: None
### end
### end() <sub>function</sub>
End this compute pass.
@@ -28,7 +28,7 @@ End this compute pass.
**Returns**: None
### pipeline(computePipeline)
### pipeline(computePipeline) <sub>function</sub>
Bind a compute pipeline in this pass.
@@ -40,7 +40,7 @@ Bind a compute pipeline in this pass.
**Returns**: None
### samplers(arrayOfSamplerBindings, firstSlot)
### samplers(arrayOfSamplerBindings, firstSlot) <sub>function</sub>
Bind a set of texture/sampler pairs for compute usage.
@@ -54,7 +54,7 @@ Bind a set of texture/sampler pairs for compute usage.
**Returns**: None
### storage_buffers(arrayOfBuffers, firstSlot)
### storage_buffers(arrayOfBuffers, firstSlot) <sub>function</sub>
Bind an array of storage buffers for the compute shader.
@@ -68,7 +68,7 @@ Bind an array of storage buffers for the compute shader.
**Returns**: None
### storage_textures(arrayOfTextures, firstSlot)
### storage_textures(arrayOfTextures, firstSlot) <sub>function</sub>
Bind an array of storage textures for the compute shader.

36
docs/api/types/SDL_GPUDevice.md
View File

@@ -3,7 +3,7 @@
A handle for low-level GPU operations via SDL GPU. Freed on GC.
### claim_window(window)
### claim_window(window) <sub>function</sub>
Claim an existing SDL_Window so this GPU device can render to it.
@@ -15,7 +15,7 @@ Claim an existing SDL_Window so this GPU device can render to it.
**Returns**: None
### make_pipeline(pipelineDesc)
### make_pipeline(pipelineDesc) <sub>function</sub>
Create a new graphics pipeline from a descriptor object specifying shaders,
blend states, vertex format, etc.
@@ -28,7 +28,7 @@ blend states, vertex format, etc.
**Returns**: A SDL_GPUGraphicsPipeline handle.
### compute_pipeline(desc)
### compute_pipeline(desc) <sub>function</sub>
Create a compute pipeline from a descriptor (shader code, threadgroup sizes, etc.).
@@ -40,7 +40,7 @@ Create a compute pipeline from a descriptor (shader code, threadgroup sizes, etc
**Returns**: SDL_GPUComputePipeline handle.
### set_swapchain(composition, presentMode)
### set_swapchain(composition, presentMode) <sub>function</sub>
Specify how the swapchain (final rendered image) is composed, e.g. 'sdr', 'hdr',
and present mode like 'vsync' or 'immediate'.
@@ -55,7 +55,7 @@ and present mode like 'vsync' or 'immediate'.
**Returns**: None
### sort_sprite(a, b)
### sort_sprite(a, b) <sub>function</sub>
A comparator function used for sorting sprite objects by layer, y, and texture.
Usually used internally.
@@ -70,7 +70,7 @@ Usually used internally.
**Returns**: <0, 0, or >0 for sort ordering.
### make_sampler(samplerDesc)
### make_sampler(samplerDesc) <sub>function</sub>
Create a sampler object specifying filtering, wrapping, anisotropy, etc.
@@ -82,7 +82,7 @@ Create a sampler object specifying filtering, wrapping, anisotropy, etc.
**Returns**: SDL_GPUSampler handle.
### load_texture(surface, compressionLevel)
### load_texture(surface, compressionLevel) <sub>function</sub>
Upload an SDL_Surface into a GPU texture, optionally compressing with DXT. Freed automatically.
@@ -96,7 +96,7 @@ Upload an SDL_Surface into a GPU texture, optionally compressing with DXT. Freed
**Returns**: SDL_GPUTexture
### texture(desc)
### texture(desc) <sub>function</sub>
Create a GPU texture with the specified format usage.
@@ -108,7 +108,7 @@ Create a GPU texture with the specified format usage.
**Returns**: SDL_GPUTexture
### make_quad
### make_quad() <sub>function</sub>
Return a simple 2-triangle quad geometry covering [0,1]x[0,1].
Useful for post-processing passes.
@@ -118,7 +118,7 @@ Useful for post-processing passes.
**Returns**: A mesh {pos, uv, color, indices}.
### driver
### driver() <sub>function</sub>
Return the name of the underlying GPU driver in use (e.g. 'OpenGL').
@@ -127,7 +127,7 @@ Return the name of the underlying GPU driver in use (e.g. 'OpenGL').
**Returns**: A string with driver name.
### make_shader(desc)
### make_shader(desc) <sub>function</sub>
Compile raw shader code (vertex or fragment) in e.g. SPIR-V, MSL, or DXIL format.
@@ -139,7 +139,7 @@ Compile raw shader code (vertex or fragment) in e.g. SPIR-V, MSL, or DXIL format
**Returns**: SDL_GPUShader object
### acquire_cmd_buffer
### acquire_cmd_buffer() <sub>function</sub>
Obtain a new command buffer for recording GPU commands. Must be submitted or canceled.
@@ -148,7 +148,7 @@ Obtain a new command buffer for recording GPU commands. Must be submitted or can
**Returns**: SDL_GPUCommandBuffer handle
### upload(cmdBuffer, buffers, transferBuffer)
### upload(cmdBuffer, buffers, transferBuffer) <sub>function</sub>
Upload CPU data into a list of GPU buffers, optionally reusing or returning a
transfer buffer. Typically you provide (cmdBuf, arrayOfTypedArrays, [transferBuffer]).
@@ -165,7 +165,7 @@ transfer buffer. Typically you provide (cmdBuf, arrayOfTypedArrays, [transferBuf
**Returns**: The transfer buffer used or newly created.
### wait_for_fences(fences, waitAll)
### wait_for_fences(fences, waitAll) <sub>function</sub>
Wait on an array of GPU fence objects, optionally requiring all or any.
@@ -179,7 +179,7 @@ Wait on an array of GPU fence objects, optionally requiring all or any.
**Returns**: True if fences signaled, false on timeout or error.
### query_fence(fence)
### query_fence(fence) <sub>function</sub>
Check if the given fence has been signaled yet. Non-blocking.
@@ -191,7 +191,7 @@ Check if the given fence has been signaled yet. Non-blocking.
**Returns**: True if signaled, false if still pending
### shader_format
### shader_format() <sub>function</sub>
Return an array of supported GPU shader binary formats (like 'spv', 'dxbc', etc.).
@@ -200,7 +200,7 @@ Return an array of supported GPU shader binary formats (like 'spv', 'dxbc', etc.
**Returns**: Array of strings naming supported formats.
### slice9(texture, dstRect, edges)
### slice9(texture, dstRect, edges) <sub>function</sub>
Generate a 9-slice tiling geometry in one shot. For advanced usage with GPU pipeline.
@@ -216,7 +216,7 @@ Generate a 9-slice tiling geometry in one shot. For advanced usage with GPU pipe
**Returns**: A mesh object
### tile(texture, srcRect, dstRect, tileInfo)
### tile(texture, srcRect, dstRect, tileInfo) <sub>function</sub>
Generate geometry to tile a texture portion inside a dest rect.
Often used for repeating backgrounds.

22
docs/api/types/SDL_GPURenderPass.md
View File

@@ -3,7 +3,7 @@
A single pass of drawing commands with color/depth attachments. Freed after end() or GC.
### bind_pipeline(pipeline)
### bind_pipeline(pipeline) <sub>function</sub>
Bind a previously created graphics pipeline (shaders, states, vertex layouts, etc.).
@@ -15,7 +15,7 @@ Bind a previously created graphics pipeline (shaders, states, vertex layouts, et
**Returns**: None
### viewport(rect)
### viewport(rect) <sub>function</sub>
Set the viewport for clipping or scaling draws, in pass-local coordinates.
@@ -27,7 +27,7 @@ Set the viewport for clipping or scaling draws, in pass-local coordinates.
**Returns**: None
### scissor(rect)
### scissor(rect) <sub>function</sub>
Set a scissor rectangle for discarding pixels outside it.
@@ -39,7 +39,7 @@ Set a scissor rectangle for discarding pixels outside it.
**Returns**: None
### draw(primitiveType, baseVertex, firstVertex, vertexCount)
### draw(primitiveType, baseVertex, firstVertex, vertexCount) <sub>function</sub>
Issue a non-indexed draw call.
@@ -57,7 +57,7 @@ Issue a non-indexed draw call.
**Returns**: None
### draw_indexed(primitiveType, baseVertex, firstIndex, indexCount, instanceCount)
### draw_indexed(primitiveType, baseVertex, firstIndex, indexCount, instanceCount) <sub>function</sub>
Issue an indexed draw call from the bound index buffer.
@@ -77,7 +77,7 @@ Issue an indexed draw call from the bound index buffer.
**Returns**: None
### end
### end() <sub>function</sub>
End this render pass, finalizing the draw operations.
@@ -86,7 +86,7 @@ End this render pass, finalizing the draw operations.
**Returns**: None
### bind_index_buffer(buffer, elementSize16bit)
### bind_index_buffer(buffer, elementSize16bit) <sub>function</sub>
Bind an index buffer inside this pass, possibly overriding the global one.
@@ -100,7 +100,7 @@ Bind an index buffer inside this pass, possibly overriding the global one.
**Returns**: None
### bind_buffers(firstSlot, arrayOfBuffers)
### bind_buffers(firstSlot, arrayOfBuffers) <sub>function</sub>
Bind multiple vertex buffers at consecutive slots.
@@ -114,7 +114,7 @@ Bind multiple vertex buffers at consecutive slots.
**Returns**: None
### bind_samplers(vertexOrFragment, firstSlot, samplerBindings)
### bind_samplers(vertexOrFragment, firstSlot, samplerBindings) <sub>function</sub>
Bind multiple texture/sampler pairs to either vertex or fragment slots.
@@ -130,7 +130,7 @@ Bind multiple texture/sampler pairs to either vertex or fragment slots.
**Returns**: None
### bind_storage_buffers(firstSlot, buffers)
### bind_storage_buffers(firstSlot, buffers) <sub>function</sub>
Bind one or more storage buffers for read/write in the pipeline.
@@ -144,7 +144,7 @@ Bind one or more storage buffers for read/write in the pipeline.
**Returns**: None
### bind_storage_textures(firstSlot, textures)
### bind_storage_textures(firstSlot, textures) <sub>function</sub>
Bind one or more storage textures for read/write in the pipeline.

4
docs/api/types/SDL_GPUTexture.md
View File

@@ -1,5 +1,3 @@
# SDL_GPUTexture
## SDL_GPUTexture
### name
### name() <sub>function</sub>

50
docs/api/types/SDL_Renderer.md
View File

@@ -3,7 +3,7 @@
A 2D rendering context using the SDL renderer API. Freed automatically.
### draw_color(color)
### draw_color(color) <sub>function</sub>
Set the render draw color for subsequent primitive calls (rect, line, etc.).
@@ -15,7 +15,7 @@ Set the render draw color for subsequent primitive calls (rect, line, etc.).
**Returns**: None
### present
### present() <sub>function</sub>
Display whatever has been rendered (swap buffers). Must be called each frame.
@@ -24,7 +24,7 @@ Display whatever has been rendered (swap buffers). Must be called each frame.
**Returns**: None
### clear
### clear() <sub>function</sub>
Clear the current render target with the renderer's draw color.
@@ -33,7 +33,7 @@ Clear the current render target with the renderer's draw color.
**Returns**: None
### rect(rectOrArray, color)
### rect(rectOrArray, color) <sub>function</sub>
Draw one or more outlines of rectangles.
@@ -47,7 +47,7 @@ Draw one or more outlines of rectangles.
**Returns**: None
### fillrect(rectOrArray, color)
### fillrect(rectOrArray, color) <sub>function</sub>
Fill one or more rectangles with the renderer's current color or an optional override.
@@ -61,7 +61,7 @@ Fill one or more rectangles with the renderer's current color or an optional ove
**Returns**: None
### line(points, color)
### line(points, color) <sub>function</sub>
Draw a sequence of lines connecting points in an array.
@@ -75,7 +75,7 @@ Draw a sequence of lines connecting points in an array.
**Returns**: None
### point(points, color)
### point(points, color) <sub>function</sub>
Draw a list of points (pixels).
@@ -89,7 +89,7 @@ Draw a list of points (pixels).
**Returns**: None
### load_texture(surface)
### load_texture(surface) <sub>function</sub>
Create an SDL_Texture from a given SDL_Surface for use with this renderer.
@@ -101,7 +101,7 @@ Create an SDL_Texture from a given SDL_Surface for use with this renderer.
**Returns**: An SDL_Texture object.
### texture(tex, dstRect, srcRect, color)
### texture(tex, dstRect, srcRect, color) <sub>function</sub>
Draw a texture onto the render target.
@@ -119,7 +119,7 @@ Draw a texture onto the render target.
**Returns**: None
### slice9(tex, dstRect, edges, srcRect)
### slice9(tex, dstRect, edges, srcRect) <sub>function</sub>
Draw a texture with 9-slice scaling. The argument includes edges {l, r, t, b}
for the corners/borders that remain unscaled. The rest is tiled or stretched.
@@ -138,7 +138,7 @@ for the corners/borders that remain unscaled. The rest is tiled or stretched.
**Returns**: None
### tile(tex, dstRect, srcRect, scale)
### tile(tex, dstRect, srcRect, scale) <sub>function</sub>
Tile a texture repeatedly within the specified region. Optionally use a srcRect.
@@ -156,7 +156,7 @@ Tile a texture repeatedly within the specified region. Optionally use a srcRect.
**Returns**: None
### get_image(rect)
### get_image(rect) <sub>function</sub>
Read back the rendered pixels into a new SDL_Surface. If rect is undefined, capture entire output.
@@ -168,7 +168,7 @@ Read back the rendered pixels into a new SDL_Surface. If rect is undefined, capt
**Returns**: An SDL_Surface with the requested region's pixels.
### fasttext(text, pos, color)
### fasttext(text, pos, color) <sub>function</sub>
Draw debug text using an internal fast path. Typically used for quick debugging overlays.
@@ -184,7 +184,7 @@ Draw debug text using an internal fast path. Typically used for quick debugging
**Returns**: None
### geometry(texture, meshObject)
### geometry(texture, meshObject) <sub>function</sub>
Render custom geometry from a mesh object {pos, uv, color, indices, count} with an optional texture.
@@ -198,7 +198,7 @@ Render custom geometry from a mesh object {pos, uv, color, indices, count} with
**Returns**: None
### scale(scaleVec2)
### scale(scaleVec2) <sub>function</sub>
Set a scaling factor for all subsequent rendering on this renderer.
@@ -210,7 +210,7 @@ Set a scaling factor for all subsequent rendering on this renderer.
**Returns**: None
### logical_size(size)
### logical_size(size) <sub>function</sub>
Set a "logical" size that the renderer will scale to.
For example, (320, 240) can auto-scale up to the window resolution.
@@ -223,7 +223,7 @@ For example, (320, 240) can auto-scale up to the window resolution.
**Returns**: None
### viewport(rect)
### viewport(rect) <sub>function</sub>
Set the clipping viewport for rendering. Pass undefined to use the full render target.
@@ -235,7 +235,7 @@ Set the clipping viewport for rendering. Pass undefined to use the full render t
**Returns**: None
### clip(rect)
### clip(rect) <sub>function</sub>
Set or clear the clipping rectangle for drawing. Pass undefined to clear.
@@ -247,7 +247,7 @@ Set or clear the clipping rectangle for drawing. Pass undefined to clear.
**Returns**: None
### vsync(flag)
### vsync(flag) <sub>function</sub>
Enable or disable vertical sync. This may have no effect depending on the driver.
@@ -259,7 +259,7 @@ Enable or disable vertical sync. This may have no effect depending on the driver
**Returns**: None
### coords(pos)
### coords(pos) <sub>function</sub>
Convert window coordinates to this renderer's coordinate space.
@@ -271,7 +271,7 @@ Convert window coordinates to this renderer's coordinate space.
**Returns**: [x, y] in renderer coordinate space.
### camera(cameraTransform, centered)
### camera(cameraTransform, centered) <sub>function</sub>
Set up a basic 2D camera matrix from a given transform. If 'centered' is true,
the origin is the center of the viewport, else top-left.
@@ -286,7 +286,7 @@ the origin is the center of the viewport, else top-left.
**Returns**: None
### get_viewport
### get_viewport() <sub>function</sub>
Return the current viewport rect.
@@ -295,7 +295,7 @@ Return the current viewport rect.
**Returns**: {x, y, w, h}
### screen2world(pos)
### screen2world(pos) <sub>function</sub>
Convert a screen coordinate to world space based on the current camera transform.
@@ -307,7 +307,7 @@ Convert a screen coordinate to world space based on the current camera transform
**Returns**: [wx, wy] in world space
### target(texture)
### target(texture) <sub>function</sub>
Set or clear the current render target texture. Pass undefined to reset to the default/window.
@@ -319,7 +319,7 @@ Set or clear the current render target texture. Pass undefined to reset to the d
**Returns**: None
### make_sprite_mesh(sprites)
### make_sprite_mesh(sprites) <sub>function</sub>
Generate a mesh from an array of sprite objects, combining their positions, UVs,
and colors into a single geometry block.

10
docs/api/types/SDL_Surface.md
View File

@@ -4,7 +4,7 @@ A software (CPU) image in memory. Freed when references vanish. Typically conver
to SDL_Texture for drawing, or used as raw pixel data.
### blit(dstRect, srcSurface, srcRect)
### blit(dstRect, srcSurface, srcRect) <sub>function</sub>
Blit (copy) another surface onto this surface, scaling if needed.
@@ -20,7 +20,7 @@ Blit (copy) another surface onto this surface, scaling if needed.
**Returns**: None
### scale(newSize)
### scale(newSize) <sub>function</sub>
Return a new SDL_Surface scaled to [width, height] using linear filtering.
@@ -32,7 +32,7 @@ Return a new SDL_Surface scaled to [width, height] using linear filtering.
**Returns**: A new SDL_Surface with the scaled result.
### fill(color)
### fill(color) <sub>function</sub>
Fill the entire surface with a single color.
@@ -44,7 +44,7 @@ Fill the entire surface with a single color.
**Returns**: None
### rect(rect, color)
### rect(rect, color) <sub>function</sub>
Fill a sub-rectangle of the surface with a color.
@@ -58,7 +58,7 @@ Fill a sub-rectangle of the surface with a color.
**Returns**: None
### dup
### dup() <sub>function</sub>
Make a copy of this surface in RGBA format.

2
docs/api/types/SDL_Texture.md
View File

@@ -3,7 +3,7 @@
A 2D GPU-accelerated texture for rendering with SDL_Renderer. Freed automatically.
### mode(mode)
### mode(mode) <sub>function</sub>
Set texture scale mode or filtering mode (nearest/linear).

2
docs/api/types/SDL_Thread.md
View File

@@ -5,7 +5,7 @@ A handle to an SDL-created thread. Freed on GC after join.
Note: The engine generally doesn't expose custom usage for threads.
### wait
### wait() <sub>function</sub>
Block until this thread terminates.

22
docs/api/types/SDL_Window.md
View File

@@ -3,7 +3,7 @@
An application window, created via prosperon.engine_start or SDL calls. Freed on GC.
### fullscreen
### fullscreen() <sub>function</sub>
Toggle fullscreen mode for this window (SDL_WINDOW_FULLSCREEN).
@@ -12,7 +12,7 @@ Toggle fullscreen mode for this window (SDL_WINDOW_FULLSCREEN).
**Returns**: None
### make_renderer(name)
### make_renderer(name) <sub>function</sub>
Create an SDL_Renderer for 2D rendering tied to this window.
@@ -24,7 +24,7 @@ Create an SDL_Renderer for 2D rendering tied to this window.
**Returns**: An SDL_Renderer object.
### make_gpu(debug, driverName)
### make_gpu(debug, driverName) <sub>function</sub>
Create an SDL_GPUDevice for low-level GPU rendering on this window.
@@ -38,7 +38,7 @@ Create an SDL_GPUDevice for low-level GPU rendering on this window.
**Returns**: An SDL_GPUDevice.
### keyboard_shown
### keyboard_shown() <sub>function</sub>
Return whether the on-screen keyboard is visible (mobile/tablet).
@@ -47,7 +47,7 @@ Return whether the on-screen keyboard is visible (mobile/tablet).
**Returns**: True if shown, false otherwise.
### theme
### theme() <sub>function</sub>
Currently returns undefined. Placeholder for retrieving OS window theme info.
@@ -56,7 +56,7 @@ Currently returns undefined. Placeholder for retrieving OS window theme info.
**Returns**: undefined
### safe_area
### safe_area() <sub>function</sub>
Return a rect describing any OS-specific "safe" region for UI, e.g. on iPhone with a notch.
@@ -65,7 +65,7 @@ Return a rect describing any OS-specific "safe" region for UI, e.g. on iPhone wi
**Returns**: A rect object {x, y, w, h}.
### bordered(flag)
### bordered(flag) <sub>function</sub>
Enable or disable window borders.
@@ -77,7 +77,7 @@ Enable or disable window borders.
**Returns**: None
### set_icon(surface)
### set_icon(surface) <sub>function</sub>
Set the window's icon from an SDL_Surface.
@@ -89,7 +89,7 @@ Set the window's icon from an SDL_Surface.
**Returns**: None
### title
### title <sub>accessor</sub>
Get or set the window's title text in the title bar.
@@ -101,7 +101,7 @@ Get or set the window's title text in the title bar.
**Returns**: The current title if getting, or None if setting.
### size
### size <sub>accessor</sub>
Get or set the window's size as [width, height].
@@ -113,7 +113,7 @@ Get or set the window's size as [width, height].
**Returns**: The current [width, height] or None if setting.
### mouse_grab(flag)
### mouse_grab(flag) <sub>function</sub>
Grab or ungrab the mouse for this window (so the pointer won't leave).

12
docs/api/types/datastream.md
View File

@@ -3,7 +3,7 @@
A streaming media handle, typically for MPEG video. Freed automatically.
### time
### time() <sub>function</sub>
Return the current playback time in seconds.
@@ -12,7 +12,7 @@ Return the current playback time in seconds.
**Returns**: Current time as a float in seconds.
### seek(seconds)
### seek(seconds) <sub>function</sub>
Seek to the specified time (in seconds).
@@ -24,7 +24,7 @@ Seek to the specified time (in seconds).
**Returns**: None
### advance(seconds)
### advance(seconds) <sub>function</sub>
Advance by a certain number of seconds, decoding video as needed.
@@ -36,7 +36,7 @@ Advance by a certain number of seconds, decoding video as needed.
**Returns**: None
### duration
### duration() <sub>function</sub>
Return the total duration of the video stream, in seconds, if known.
@@ -45,7 +45,7 @@ Return the total duration of the video stream, in seconds, if known.
**Returns**: Float seconds duration, or 0 if unknown.
### framerate
### framerate() <sub>function</sub>
Return the framerate (FPS) of the stream if known.
@@ -54,7 +54,7 @@ Return the framerate (FPS) of the stream if known.
**Returns**: Float frames per second, or 0 if unknown.
### callback
### callback <sub>accessor</sub>
A function to call whenever a new frame is decoded. If not set, no callback is invoked.

10
docs/api/types/font.md
View File

@@ -4,7 +4,7 @@ A bitmap or TTF-based font object storing glyph data.
Used for measuring/drawing text. Freed when GC sees no references.
### linegap
### linegap <sub>accessor</sub>
Get or set the font's additional line spacing above the built-in metrics.
@@ -16,7 +16,7 @@ Get or set the font's additional line spacing above the built-in metrics.
**Returns**: The current line gap (when getting), or None (when setting).
### height
### height <sub>accessor</sub>
(read only)
@@ -27,7 +27,7 @@ The baseline-to-baseline height in pixels.
**Returns**: The font's total height in px.
### ascent
### ascent <sub>accessor</sub>
(read only)
@@ -38,7 +38,7 @@ How far above the baseline the font extends.
**Returns**: A scalar float for ascent.
### descent
### descent <sub>accessor</sub>
(read only)
@@ -49,7 +49,7 @@ How far below baseline the font extends.
**Returns**: A scalar float for descent.
### text_size(text, letterSpacing, wrap)
### text_size(text, letterSpacing, wrap) <sub>function</sub>
Measure a piece of text's width/height when rendered with this font.

23
docs/api/types/rtree.md
View File

@@ -3,7 +3,7 @@
An R-tree for spatial lookups. Insert bounding boxes, query by bounding box, etc.
### add(obj)
### add(obj) <sub>function</sub>
Insert an object that has a 'rect' property {x, y, w, h} into the tree.
@@ -15,7 +15,7 @@ Insert an object that has a 'rect' property {x, y, w, h} into the tree.
**Returns**: None
### delete(obj)
### delete(obj) <sub>function</sub>
Remove an object from the tree. Must match the same rect as used when adding.
@@ -27,7 +27,7 @@ Remove an object from the tree. Must match the same rect as used when adding.
**Returns**: None
### query(rect)
### query(rect) <sub>function</sub>
Return an array of objects whose bounding boxes intersect the given rect.
@@ -39,7 +39,18 @@ Return an array of objects whose bounding boxes intersect the given rect.
**Returns**: Array of objects that overlap that region.
### forEach(callback)
### size <sub>accessor</sub>
(read only)
Indicates how many items are stored in the rtree.
**Returns**: Integer count of items in the tree.
### forEach(callback) <sub>function</sub>
Call a function for every item in the rtree.
@@ -51,7 +62,7 @@ Call a function for every item in the rtree.
**Returns**: None
### has(obj)
### has(obj) <sub>function</sub>
Return true if the specified object is in the tree, false otherwise.
@@ -63,7 +74,7 @@ Return true if the specified object is in the tree, false otherwise.
**Returns**: True if found, else false.
### values
### values() <sub>function</sub>
Return an array of all items currently in the rtree.

10
docs/api/types/sprite.md
View File

@@ -5,7 +5,7 @@ UV coordinates, color, and layer, as well as an associated 'image' object. The s
can be drawn via GPU or SDL_Renderer. Freed when no JS references remain.
### set_affine(transform)
### set_affine(transform) <sub>function</sub>
Update this sprite's position and size from a transform's pos and scale.
@@ -17,7 +17,7 @@ Update this sprite's position and size from a transform's pos and scale.
**Returns**: None
### set_rect(rect)
### set_rect(rect) <sub>function</sub>
Set the sprite's rect (x, y, w, h) directly.
@@ -29,7 +29,7 @@ Set the sprite's rect (x, y, w, h) directly.
**Returns**: None
### set_image(image)
### set_image(image) <sub>function</sub>
Assign or replace the sprite's underlying image. Automatically updates UV if
the image has a 'rect' property.
@@ -42,7 +42,7 @@ the image has a 'rect' property.
**Returns**: None
### layer
### layer <sub>accessor</sub>
Get or set the sprite's z-layer integer. Sprites with higher layers typically
draw on top of lower layers.
@@ -55,7 +55,7 @@ draw on top of lower layers.
**Returns**: The current layer (when getting), or None (when setting).
### color
### color <sub>accessor</sub>
Get or set the sprite's color tint as [r, g, b, a].

4
docs/api/types/timer.md
View File

@@ -4,7 +4,7 @@ A scheduled callback or countdown. Freed automatically once no longer referenced
or once it completes.
### remain
### remain <sub>accessor</sub>
Get or set how many seconds remain before the timer triggers.
@@ -16,7 +16,7 @@ Get or set how many seconds remain before the timer triggers.
**Returns**: The current time left (when getting), or None (when setting).
### fn
### fn <sub>accessor</sub>
Get or set the function called when the timer expires.

34
docs/api/types/transform.md
View File

@@ -4,7 +4,7 @@ A hierarchical transform storing 3D or 2D position, rotation (as a quaternion),
and scale. Can have a parent transform. Freed automatically on GC.
### pos
### pos <sub>accessor</sub>
Get or set the transform's position as a 3D vector [x, y, z].
@@ -16,7 +16,7 @@ Get or set the transform's position as a 3D vector [x, y, z].
**Returns**: The current position vector (when getting), or None (when setting).
### scale
### scale <sub>accessor</sub>
Get or set the transform's scale as a 3D vector [x, y, z].
For 2D usage, z is often 1.
@@ -29,7 +29,7 @@ For 2D usage, z is often 1.
**Returns**: The current scale (when getting), or None (when setting).
### rotation
### rotation <sub>accessor</sub>
Get or set the transform's rotation as a quaternion [x, y, z, w].
Angles in degrees or radians must first be converted prior to making a quaternion.
@@ -42,7 +42,7 @@ Angles in degrees or radians must first be converted prior to making a quaternio
**Returns**: The current quaternion (when getting), or None (when setting).
### parent
### parent <sub>accessor</sub>
Get or set the transform's parent. If set, this transform becomes a child of
the parent (re-parenting). Must be another transform object or undefined.
@@ -55,7 +55,7 @@ the parent (re-parenting). Must be another transform object or undefined.
**Returns**: The current parent transform (when getting), or None (when setting).
### change_hook
### change_hook <sub>accessor</sub>
A user-supplied function that's called whenever the transform's local matrix changes.
If undefined, no hook is called.
@@ -68,7 +68,7 @@ If undefined, no hook is called.
**Returns**: The current function or undefined.
### trs(pos, quat, scale)
### trs(pos, quat, scale) <sub>function</sub>
Set the transform's position, rotation, and scale in one call.
@@ -84,7 +84,7 @@ Set the transform's position, rotation, and scale in one call.
**Returns**: None
### phys2d(velocity, angularVel, dt)
### phys2d(velocity, angularVel, dt) <sub>function</sub>
Apply simple 2D velocity and angular velocity to this transform.
@@ -100,7 +100,7 @@ Apply simple 2D velocity and angular velocity to this transform.
**Returns**: None
### move(delta)
### move(delta) <sub>function</sub>
Translate this transform by the specified vector.
@@ -112,7 +112,7 @@ Translate this transform by the specified vector.
**Returns**: None
### rotate(axis, angle)
### rotate(axis, angle) <sub>function</sub>
Rotate this transform by an axis+angle.
@@ -126,7 +126,7 @@ Rotate this transform by an axis+angle.
**Returns**: None
### angle(axis)
### angle(axis) <sub>function</sub>
Return the transform's rotation about a specified axis (x, y, or z).
For example, angle([1,0,0]) returns the roll about the X-axis.
@@ -139,7 +139,7 @@ For example, angle([1,0,0]) returns the roll about the X-axis.
**Returns**: The numeric angle in 'turns' or radians, depending on usage.
### lookat(target)
### lookat(target) <sub>function</sub>
Rotate this transform so it looks toward the given world position.
@@ -151,7 +151,7 @@ Rotate this transform so it looks toward the given world position.
**Returns**: None
### direction(localDir)
### direction(localDir) <sub>function</sub>
Rotate a vector by this transform's rotation, effectively "transforming"
a direction from local space to world space.
@@ -164,7 +164,7 @@ a direction from local space to world space.
**Returns**: [dx', dy', dz'] direction in world space.
### unit
### unit() <sub>function</sub>
Reset position, rotation, and scale to [0,0,0], identity rotation, and [1,1,1].
@@ -173,7 +173,7 @@ Reset position, rotation, and scale to [0,0,0], identity rotation, and [1,1,1].
**Returns**: None
### rect(rect)
### rect(rect) <sub>function</sub>
Set this transform's pos and scale from a 2D rect object {x, y, w, h}.
@@ -185,7 +185,7 @@ Set this transform's pos and scale from a 2D rect object {x, y, w, h}.
**Returns**: None
### array
### array() <sub>function</sub>
Return this transform's matrix as a 16-element float array in column-major order.
@@ -194,7 +194,7 @@ Return this transform's matrix as a 16-element float array in column-major order
**Returns**: An array of 16 floats.
### torect
### torect() <sub>function</sub>
Convert transform's 2D position/scale to a rect {x, y, w, h}.
Rotation is currently ignored.
@@ -204,7 +204,7 @@ Rotation is currently ignored.
**Returns**: A rect object {x, y, w, h}.
### children
### children() <sub>function</sub>
Return an array of child transforms belonging to this transform.

6
docs/api/use.md
View File

@@ -1,3 +1,7 @@
# use
## use
### length <sub>number</sub>
### name <sub>string</sub>
### prototype <sub>object</sub>

BIN
docs/crab.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 MiB

7
docs/dull/ArrayBuffer.md Normal file
View File

@@ -0,0 +1,7 @@
# ArrayBuffer
### byteLength <sub>accessor</sub>
(read only)
### slice() <sub>function</sub>

27
docs/dull/Function.md Normal file
View File

@@ -0,0 +1,27 @@
# Function
### length <sub>number</sub>
### name <sub>string</sub>
### caller <sub>accessor</sub>
### arguments <sub>accessor</sub>
### call() <sub>function</sub>
### apply() <sub>function</sub>
### bind() <sub>function</sub>
### toString() <sub>function</sub>
### fileName <sub>accessor</sub>
(read only)
### lineNumber <sub>accessor</sub>
(read only)
### hashify() <sub>function</sub>

120
docs/dull/Map.md Normal file
View File

@@ -0,0 +1,120 @@
# Map
A Map object holds key-value pairs, where any value (both objects and primitive values) may be used as either a key or a value. Insertion order is remembered, which allows iteration in that order.
### set(key, value) <sub>function</sub>
Add or update an entry in the Map with the specified key and value.
**key**: The key of the element to add or update.
**value**: The value associated with the key.
**Returns**: The Map object (for chaining).
### get(key) <sub>function</sub>
Return the value associated with the specified key, or undefined if no
such key exists.
**key**: The key of the element to retrieve.
**Returns**: The value associated with the key, or undefined if not found.
### has(key) <sub>function</sub>
Return a boolean indicating whether the Map contains an element with the
specified key.
**key**: The key to test for presence in the Map.
**Returns**: True if the key is found, otherwise false.
### delete(key) <sub>function</sub>
Remove the specified key and its associated value from the Map, if it exists.
**key**: The key to remove.
**Returns**: True if an element was removed, otherwise false.
### clear() <sub>function</sub>
Remove all entries from the Map, leaving it empty.
**Returns**: None
### size <sub>accessor</sub>
(read only)
A read-only property returning the number of key-value pairs in the Map.
**Returns**: The number of entries in the Map.
### forEach(callbackFn, thisArg) <sub>function</sub>
Execute a provided callback function once per each key-value pair in the Map,
in insertion order.
**callbackFn**: A function(value, key, map) to execute on each entry.
**thisArg**: Optional. A value to use as 'this' when executing callbackFn.
**Returns**: None
### values() <sub>function</sub>
Return a new Iterator object that contains the values for each element
in the Map, in insertion order.
**Returns**: An iterator of the Map's values.
### keys() <sub>function</sub>
Return a new Iterator object that contains the keys for each element in
the Map, in insertion order.
**Returns**: An iterator of the Map's keys.
### entries() <sub>function</sub>
Return a new Iterator object that contains the [key, value] pairs for
each element in the Map, in insertion order.
**Returns**: An iterator of [key, value] pairs.

87
docs/dull/Object.md Normal file
View File

@@ -0,0 +1,87 @@
# Object
### toString() <sub>function</sub>
Return a string representing this object. By default, it returns a string of the form '[object <className>]', where <className> is the object's class.
**Returns**: A string that describes the object.
### toLocaleString() <sub>function</sub>
Return a localized string representation of this object, calling toString() by default or a locale-specific override if defined.
**Returns**: A locale-sensitive string representation of the object.
### valueOf() <sub>function</sub>
Return the primitive value of this object if one exists. Typically, an object returns itself, while a wrapped type (e.g. Number, String) may return the underlying primitive value.
**Returns**: The primitive value of the object, or the object itself.
### hasOwnProperty(prop) <sub>function</sub>
Return a boolean indicating whether the object has a property with the specified name (key) as its own direct property, as opposed to inheriting it. It does not check the prototype chain.
**prop**: The name or Symbol of the property to test.
**Returns**: True if the property is found directly on the object, otherwise false.
### isPrototypeOf(obj) <sub>function</sub>
Return true if the object appears anywhere in the prototype chain of the specified object, otherwise false.
**obj**: The object whose prototype chain will be checked.
**Returns**: True if this object is in 'obj's prototype chain, otherwise false.
### propertyIsEnumerable(prop) <sub>function</sub>
Return a boolean indicating whether the specified property is enumerable, i.e., whether it shows up in a for...in loop or Object.keys() on the object.
**prop**: The name or Symbol of the property to test.
**Returns**: True if the property is found and enumerable, otherwise false.
### __proto__ <sub>accessor</sub>
### __defineGetter__() <sub>function</sub>
### __defineSetter__() <sub>function</sub>
### __lookupGetter__() <sub>function</sub>
### __lookupSetter__() <sub>function</sub>
### mixin(obj) <sub>function</sub>
Mix properties from 'obj' into the current object. If 'obj' is a string,
it first calls 'use(obj)' to retrieve the object.
**obj**: The object (or string reference to an object) to mix in.
**Returns**: None

104
docs/dull/Set.md Normal file
View File

@@ -0,0 +1,104 @@
# Set
A Set object lets you store unique values of any type, whether primitive values or object references. It remembers insertion order for iteration.
### add(value) <sub>function</sub>
Add a new element with the given value to the Set, if it’s not already present.
**value**: The value to add.
**Returns**: The Set object (for chaining).
### has(value) <sub>function</sub>
Return a boolean indicating whether the Set contains the specified value.
**value**: The value to check for presence in the Set.
**Returns**: True if the value is found, otherwise false.
### delete(value) <sub>function</sub>
Remove the specified value from the Set if it exists.
**value**: The value to remove.
**Returns**: True if the value was present and removed, otherwise false.
### clear() <sub>function</sub>
Remove all elements from the Set, leaving it empty.
**Returns**: None
### size <sub>accessor</sub>
(read only)
A read-only property returning the number of elements in the Set.
**Returns**: The number of unique values in the Set.
### forEach(callbackFn, thisArg) <sub>function</sub>
Execute a provided callback function once for each value in the Set,
in insertion order.
**callbackFn**: A function(value, valueAgain, set) to execute on each element.
**thisArg**: Optional. A value to use as 'this' when executing callbackFn.
**Returns**: None
### values() <sub>function</sub>
Alias for values() in a Set. Return a new Iterator object containing all
the values (as keys) in the Set, in insertion order.
**Returns**: An iterator of the Set's values.
### keys() <sub>function</sub>
Alias for values() in a Set. Return a new Iterator object containing all
the values (as keys) in the Set, in insertion order.
**Returns**: An iterator of the Set's values.
### entries() <sub>function</sub>
Return a new Iterator object containing [value, value] pairs for each value
in the Set, in insertion order. This maintains API consistency with Map objects.
**Returns**: An iterator of [value, value] pairs.

793
docs/dull/String.md Normal file
View File

@@ -0,0 +1,793 @@
# String
### length <sub>number</sub>
### at(index) <sub>function</sub>
Return the character (or surrogate pair) at the specified index, with support
for negative indices (counting from the end). If the index is out of range,
returns undefined.
**index**: The position of the character to return (can be negative).
**Returns**: A string of length 1 representing the character, or undefined if out of range.
### charCodeAt(index) <sub>function</sub>
Return a number indicating the UTF-16 code unit value at the given index.
If the index is out of range, returns NaN.
**index**: An integer between 0 and string length - 1.
**Returns**: An integer in the range [0, 65535] or NaN if out of range.
### charAt(index) <sub>function</sub>
Return a string consisting of the single UTF-16 code unit at the given index.
If the index is out of range, returns an empty string.
**index**: The zero-based index of the desired character.
**Returns**: The single-character string at the specified index, or '' if out of range.
### concat(stringN) <sub>function</sub>
Concatenate the provided string arguments to the current string and return a
new string.
**stringN**: One or more strings to concatenate.
**Returns**: A new string formed by joining the caller with the provided arguments.
### codePointAt(position) <sub>function</sub>
Return a non-negative integer that is the Unicode code point value at the
given position. Supports code points above 0xFFFF. Returns undefined if index
is out of range.
**position**: The index in the string (can be surrogate pairs).
**Returns**: The code point value, or undefined if out of range.
### isWellFormed() <sub>function</sub>
Return a boolean indicating whether the string is valid Unicode.
If it contains unpaired surrogate code points, return false.
**Returns**: True if the string is well-formed UTF-16, otherwise false.
### toWellFormed() <sub>function</sub>
Return a new string in which any unpaired surrogate code points have been
replaced by the Unicode replacement character U+FFFD.
**Returns**: A well-formed UTF-16 version of the string.
### indexOf(searchValue, fromIndex) <sub>function</sub>
Return the zero-based index of the first occurrence of 'searchValue' in the
string, starting at 'fromIndex'. If not found, return -1.
**searchValue**: The substring to search for.
**fromIndex**: The index at which to begin searching (default 0).
**Returns**: The index of the first match, or -1 if not found.
### lastIndexOf(searchValue, fromIndex) <sub>function</sub>
Return the zero-based index of the last occurrence of 'searchValue' in the
string, searching backwards from 'fromIndex'. If not found, return -1.
**searchValue**: The substring to search for.
**fromIndex**: The index at which to begin the backward search (defaults to string length - 1).
**Returns**: The index of the last match, or -1 if not found.
### includes(searchString, position) <sub>function</sub>
Return a boolean indicating whether 'searchString' appears within this string.
An optional position can be provided to start searching.
**searchString**: The substring to search for.
**position**: The position from which to begin searching (default 0).
**Returns**: True if the substring is found, otherwise false.
### endsWith(searchString, length) <sub>function</sub>
Return a boolean indicating whether the string ends with 'searchString'.
An optional 'length' can be provided to treat the string as if it were only
that long.
**searchString**: The substring to search for at the end.
**length**: An optional length to truncate the string before testing.
**Returns**: True if the string ends with 'searchString', otherwise false.
### startsWith(searchString, position) <sub>function</sub>
Return a boolean indicating whether the string begins with 'searchString'.
An optional position can be provided to start checking at that index.
**searchString**: The substring to search for at the start.
**position**: The index in the string to start searching (default 0).
**Returns**: True if the string starts with 'searchString', otherwise false.
### match(regexp) <sub>function</sub>
Use a regular expression to match the string. If 'regexp' is not a RegExp, it
is converted to one. Return an array of matches or null if none found.
**regexp**: The pattern to match (RegExp or string).
**Returns**: An array of matches or null.
### matchAll(regexp) <sub>function</sub>
Return an iterator of all RegExp match objects found within the string.
If 'regexp' is not a global or sticky RegExp, a TypeError is thrown.
**regexp**: The global/sticky RegExp to match over this string.
**Returns**: An iterator of match arrays.
### search(regexp) <sub>function</sub>
Use a regular expression to search for a match within the string. Return the
index of the first match, or -1 if no match is found.
**regexp**: A RegExp or string. If a string, it is converted to RegExp.
**Returns**: The index of the first match, or -1 if not found.
### split(separator, limit) <sub>function</sub>
Split the string into an array of substrings using 'separator' (RegExp or
string). An optional 'limit' can be provided to limit the number of splits.
**separator**: A string or RegExp used to divide the string.
**limit**: Maximum number of splits to include in the result array.
**Returns**: An array of the split substrings.
### substring(start, end) <sub>function</sub>
Return the substring between 'start' and 'end'. Indices outside the range
are clamped. If 'end' < 'start', they swap.
**start**: The starting index (0-based).
**end**: The ending index (exclusive).
**Returns**: The extracted substring.
### substr(start, length) <sub>function</sub>
Return the substring from 'start' for 'length' characters. Negative 'start'
counts from the end. This method is deprecated but still supported in many
engines.
**start**: The starting index.
**length**: The number of characters to extract.
**Returns**: The extracted substring.
### slice(start, end) <sub>function</sub>
Extract a section of the string from 'start' up to (but not including) 'end',
and return it as a new string. Supports negative indices.
**start**: The starting index. Negative values count from the end.
**end**: The ending index (exclusive). Negative values count from the end.
**Returns**: The extracted slice.
### repeat(count) <sub>function</sub>
Construct and return a new string which contains the specified number of copies
of the calling string, concatenated together.
**count**: The number of times to repeat the string (must be >= 0).
**Returns**: A new repeated string.
### replace(searchValue, replaceValue) <sub>function</sub>
Return a new string where the first match (or all matches if 'searchValue'
is a global RegExp) of 'searchValue' is replaced by 'replaceValue'.
If 'searchValue' is a string, only the first occurrence is replaced.
**searchValue**: A string or RegExp to match.
**replaceValue**: The replacement string or function.
**Returns**: A new string with the matched substring(s) replaced.
### replaceAll(searchValue, replaceValue) <sub>function</sub>
Return a new string where all (non-overlapping) occurrences of 'searchValue'
are replaced by 'replaceValue'. If 'searchValue' is a string, each exact match
is replaced.
**searchValue**: A string or RegExp with the 'g' flag.
**replaceValue**: The replacement string or function.
**Returns**: A new string with all matches replaced.
### padEnd(maxLength, padString) <sub>function</sub>
Pad the string from the end with the given 'padString' so its length reaches
'maxLength'. The result is a new string.
**maxLength**: The desired length of the resulting string.
**padString**: The string to pad with (default ' ').
**Returns**: A new string padded at the end.
### padStart(maxLength, padString) <sub>function</sub>
Pad the string from the start with the given 'padString' so its length reaches
'maxLength'. The result is a new string.
**maxLength**: The desired length of the resulting string.
**padString**: The string to pad with (default ' ').
**Returns**: A new string padded at the start.
### trim() <sub>function</sub>
Return a new string with whitespace trimmed from the start and end of this
string.
**Returns**: The trimmed string.
### trimEnd() <sub>function</sub>
Alias for trimEnd(). Remove trailing whitespace from the string.
**Returns**: The string without trailing whitespace.
### trimRight() <sub>function</sub>
Alias for trimEnd(). Remove trailing whitespace from the string.
**Returns**: The string without trailing whitespace.
### trimStart() <sub>function</sub>
Alias for trimStart(). Remove leading whitespace from the string.
**Returns**: The string without leading whitespace.
### trimLeft() <sub>function</sub>
Alias for trimStart(). Remove leading whitespace from the string.
**Returns**: The string without leading whitespace.
### toString() <sub>function</sub>
Return a string representing the specified object (itself). Usually called
implicitly. Overrides Object.prototype.toString.
**Returns**: The string itself.
### valueOf() <sub>function</sub>
Return the primitive string value of this String object.
**Returns**: The primitive string value.
### __quote() <sub>function</sub>
(Non-standard) Return a quoted representation of the string, typically for
debug or serialization. Implementation details may vary.
**Returns**: A quoted version of the string.
### localeCompare(compareString) <sub>function</sub>
Return a number indicating whether this string is less than, equal to, or
greater than 'compareString' in sort order, according to the current locale.
**compareString**: The string to compare against.
**Returns**: A negative number if less, 0 if the same, or a positive number if greater.
### toLowerCase() <sub>function</sub>
Return a new string with all alphabetic characters converted to lowercase.
**Returns**: The lowercase version of this string.
### toUpperCase() <sub>function</sub>
Return a new string with all alphabetic characters converted to uppercase.
**Returns**: The uppercase version of this string.
### toLocaleLowerCase() <sub>function</sub>
Return a locale-aware lowercase version of this string, using the host's
current locale or the specified locale if supported.
**Returns**: The locale-sensitive lowercase string.
### toLocaleUpperCase() <sub>function</sub>
Return a locale-aware uppercase version of this string, using the host's
current locale or the specified locale if supported.
**Returns**: The locale-sensitive uppercase string.
### anchor(name) <sub>function</sub>
Return a string representing an HTML <a> element with a 'name' attribute
set to the current string.
**name**: The name attribute for the anchor.
**Returns**: An HTML <a name="...">...</a> string.
### big() <sub>function</sub>
Return a string representing an HTML <big> element containing the current
string.
**Returns**: An HTML <big>...</big> string.
### blink() <sub>function</sub>
Return a string representing an HTML <blink> element containing the current
string (historical, not recommended).
**Returns**: An HTML <blink>...</blink> string.
### bold() <sub>function</sub>
Return a string representing an HTML <b> element containing the current
string in bold.
**Returns**: An HTML <b>...</b> string.
### fixed() <sub>function</sub>
Return a string representing an HTML <tt> element containing the current
string in fixed-width font.
**Returns**: An HTML <tt>...</tt> string.
### fontcolor(color) <sub>function</sub>
Return a string representing an HTML <font> element with a 'color' attribute,
containing the current string.
**color**: The color value for the 'font' element.
**Returns**: An HTML <font color="...">...</font> string.
### fontsize(size) <sub>function</sub>
Return a string representing an HTML <font> element with a 'size' attribute,
containing the current string.
**size**: The size value for the 'font' element.
**Returns**: An HTML <font size="...">...</font> string.
### italics() <sub>function</sub>
Return a string representing an HTML <i> element containing the current
string in italics.
**Returns**: An HTML <i>...</i> string.
### link(url) <sub>function</sub>
Return a string representing an HTML <a> element with an 'href' attribute set
to the current string.
**url**: The URL for the 'href' attribute.
**Returns**: An HTML <a href="...">...</a> string.
### small() <sub>function</sub>
Return a string representing an HTML <small> element containing the current
string.
**Returns**: An HTML <small>...</small> string.
### strike() <sub>function</sub>
Return a string representing an HTML <strike> element containing the current
string with strike-through.
**Returns**: An HTML <strike>...</strike> string.
### sub() <sub>function</sub>
Return a string representing an HTML <sub> element containing the current
string as subscript.
**Returns**: An HTML <sub>...</sub> string.
### sup() <sub>function</sub>
Return a string representing an HTML <sup> element containing the current
string as superscript.
**Returns**: An HTML <sup>...</sup> string.
### rm(index, endidx) <sub>function</sub>
Remove characters from this string between 'index' (inclusive)
and 'endidx' (exclusive). If 'endidx' is omitted, it defaults to 'index + 1'.
**index**: The starting index to remove.
**endidx**: The ending index (exclusive).
**Returns**: A new string with the specified characters removed.
### tolast(val) <sub>function</sub>
Return the substring of this string up to the last occurrence of 'val'.
If 'val' is not found, the entire string is returned.
**val**: The substring to locate from the end.
**Returns**: A substring up to the last occurrence of 'val'.
### dir() <sub>function</sub>
Return everything before the last slash ('/') in the string.
If no slash is found, return an empty string.
**Returns**: The directory portion of the path.
### next(char, from) <sub>function</sub>
Search for the next occurrence of 'char' in this string, starting at 'from'.
If 'char' is an array, any of those characters qualifies. Return the matching index,
or -1 if none is found.
**char**: A character (or array of characters) to locate.
**from**: The index to start from.
**Returns**: The index of the next occurrence, or -1 if not found.
### prev(char, from, count) <sub>function</sub>
Search for the previous occurrence of 'char' before index 'from'.
If 'count' is greater than 1, skip multiple occurrences going backward.
Return the found index or 0 if not found.
**char**: The character to locate.
**from**: The index to start from (defaults to the end of the string).
**count**: How many occurrences to skip backward (default 0).
**Returns**: The index of the previous occurrence, or 0 if not found.
### strip_ext() <sub>function</sub>
Return the string up to (but not including) the last '.' character.
If '.' is not found, the entire string is returned.
**Returns**: The string without its last extension.
### ext() <sub>function</sub>
Return the substring after the last '.' in this string.
If '.' is not found, return an empty string.
**Returns**: The file extension or an empty string.
### up_path() <sub>function</sub>
Go up one directory level from the current path, preserving the file name at the end.
**Returns**: A new path string one directory up, with the base filename preserved.
### fromlast(val) <sub>function</sub>
Return the substring that appears after the last occurrence of 'val'.
If 'val' is not found, an empty string is returned.
**val**: The substring to locate.
**Returns**: The substring after the last occurrence of 'val'.
### tofirst(val) <sub>function</sub>
Return the substring from the start of this string up to the first occurrence
of 'val' (excluded). If 'val' is not found, the entire string is returned.
**val**: The substring to locate.
**Returns**: A substring up to the first occurrence of 'val'.
### fromfirst(val) <sub>function</sub>
Return the substring after the first occurrence of 'val'.
If 'val' is not found, the entire string is returned.
**val**: The substring to locate.
**Returns**: The substring after 'val', or the entire string if 'val' not found.
### name() <sub>function</sub>
Return the "name" portion of the path without extension.
If no slash is found, it's up to the last '.' in the entire string.
If there is a slash, it's from the last slash up to (but not including) the last '.'.
**Returns**: The name portion of the path without extension.
### set_name(name) <sub>function</sub>
Set the base name (excluding extension) of the path to 'name', preserving
the original directory and extension.
**name**: The new name to use.
**Returns**: A new path string with the updated name.
### base() <sub>function</sub>
Return the portion of this string after the last '/' character.
If no '/' is present, the entire string is returned.
**Returns**: The base name of the path.
### updir() <sub>function</sub>
Go up one directory from the current path, removing the last directory name.
If the path ends with a slash, remove it first. Then remove the final directory.
**Returns**: A new string representing one directory level up.

9
docs/dull/Symbol.md Normal file
View File

@@ -0,0 +1,9 @@
# Symbol
### toString() <sub>function</sub>
### valueOf() <sub>function</sub>
### description <sub>accessor</sub>
(read only)

59
docs/dull/WeakMap.md Normal file
View File

@@ -0,0 +1,59 @@
# WeakMap
A WeakMap object is a collection of key/value pairs in which keys must be
objects. References to key objects in a WeakMap are held weakly, meaning
they do not prevent garbage collection if there are no other references
to the object. WeakMap keys are not iterable.
### set(key, value) <sub>function</sub>
Set the value for the specified key in the WeakMap. The key must be an object.
**key**: The object key.
**value**: The value associated with the key.
**Returns**: The WeakMap object (for chaining).
### get(key) <sub>function</sub>
Return the value associated with 'key' in the WeakMap, or undefined if
no such key exists. The key must be an object.
**key**: The object key.
**Returns**: The value associated with the key, or undefined if not present.
### has(key) <sub>function</sub>
Return a boolean indicating whether an element with the specified key
exists in the WeakMap. The key must be an object.
**key**: The object key to check.
**Returns**: True if the key is found, otherwise false.
### delete(key) <sub>function</sub>
Remove the specified key and its associated value from the WeakMap,
if it exists.
**key**: The object key to remove.
**Returns**: True if an element was removed, otherwise false.

43
docs/dull/WeakSet.md Normal file
View File

@@ -0,0 +1,43 @@
# WeakSet
A WeakSet object is a collection of unique objects (no primitive values).
References to objects in a WeakSet are held weakly, so they do not prevent
garbage collection if there are no other references to the object. WeakSet
elements are not iterable.
### add(value) <sub>function</sub>
Add a new object to the WeakSet if it is not already present. The value
must be an object.
**value**: The object to add.
**Returns**: The WeakSet object (for chaining).
### has(value) <sub>function</sub>
Return a boolean indicating whether an object is present in the WeakSet.
**value**: The object to check.
**Returns**: True if the object is in the WeakSet, otherwise false.
### delete(value) <sub>function</sub>
Remove the specified object from the WeakSet, if it exists.
**value**: The object to remove.
**Returns**: True if the object was present and removed, otherwise false.

661
docs/dull/array.md Normal file
View File

@@ -0,0 +1,661 @@
# Array
### length <sub>number</sub>
### at(index) <sub>function</sub>
Return the item at index 'index', supporting negative indices to count from
the end. If 'index' is out of range, returns undefined.
**index**: The index of the element to return (can be negative).
**Returns**: The element at the given index, or undefined.
### with(index, value) <sub>function</sub>
Return a shallow copy of the array, but with the element at 'index' replaced
by 'value'. If 'index' is negative, it counts from the end. Throws if out of range.
**index**: The zero-based index (can be negative) to replace.
**value**: The new value for the specified position.
**Returns**: A new array with the updated element.
### concat(items) <sub>function</sub>
Return a new array that is the result of concatenating this array with
any additional arrays or values provided.
**items**: One or more arrays or values to concatenate.
**Returns**: A new array with the items appended.
### every(callback, thisArg) <sub>function</sub>
Return true if the provided callback function returns a truthy value for
every element in the array; otherwise false.
**callback**: A function(element, index, array) => boolean.
**thisArg**: Optional. A value to use as 'this' within the callback.
**Returns**: True if all elements pass the test, otherwise false.
### some(callback, thisArg) <sub>function</sub>
Return true if the provided callback function returns a truthy value for at
least one element in the array; otherwise false.
**callback**: A function(element, index, array) => boolean.
**thisArg**: Optional. A value to use as 'this' within the callback.
**Returns**: True if at least one element passes the test, otherwise false.
### forEach(callback, thisArg) <sub>function</sub>
Call the provided callback function once for each element in the array.
Does not produce a return value.
**callback**: A function(element, index, array).
**thisArg**: Optional. A value to use as 'this' within the callback.
**Returns**: None
### map(callback, thisArg) <sub>function</sub>
Create a new array with the results of calling a provided callback function
on every element in this array.
**callback**: A function(element, index, array) => newElement.
**thisArg**: Optional. A value to use as 'this' within the callback.
**Returns**: A new array of transformed elements.
### filter(callback, thisArg) <sub>function</sub>
Create a new array containing all elements for which the provided callback
function returns a truthy value.
**callback**: A function(element, index, array) => boolean.
**thisArg**: Optional. A value to use as 'this' within the callback.
**Returns**: A new array of elements that passed the test.
### reduce(callback, initialValue) <sub>function</sub>
Apply a callback function against an accumulator and each element in the
array (from left to right) to reduce it to a single value.
**callback**: A function(accumulator, element, index, array) => newAccumulator.
**initialValue**: Optional. The initial value for the accumulator.
**Returns**: The single resulting value.
### reduceRight(callback, initialValue) <sub>function</sub>
Similar to reduce(), except it processes elements from right to left.
**callback**: A function(accumulator, element, index, array) => newAccumulator.
**initialValue**: Optional. The initial value for the accumulator.
**Returns**: The single resulting value.
### fill(value, start, end) <sub>function</sub>
Fill the array with a static value from 'start' index up to (but not including)
'end' index. Modifies the original array.
**value**: The value to fill.
**start**: The starting index (default 0).
**end**: The ending index (default array.length).
**Returns**: The modified array (with filled values).
### find(callback, thisArg) <sub>function</sub>
Return the first element in the array that satisfies the provided callback
function. If none is found, return undefined.
**callback**: A function(element, index, array) => boolean.
**thisArg**: Optional. A value to use as 'this' within the callback.
**Returns**: The first matching element, or undefined if not found.
### findIndex(callback, thisArg) <sub>function</sub>
Return the index of the first element in the array that satisfies the
provided callback function. If none is found, return -1.
**callback**: A function(element, index, array) => boolean.
**thisArg**: Optional. A value to use as 'this' within the callback.
**Returns**: The index of the first matching element, or -1 if not found.
### findLast(callback, thisArg) <sub>function</sub>
Return the last element in the array that satisfies the provided callback
function, searching from right to left. If none is found, return undefined.
**callback**: A function(element, index, array) => boolean.
**thisArg**: Optional. A value to use as 'this' within the callback.
**Returns**: The last matching element, or undefined if not found.
### findLastIndex(callback, thisArg) <sub>function</sub>
Return the index of the last element in the array that satisfies the
provided callback function, searching from right to left. If none is found,
return -1.
**callback**: A function(element, index, array) => boolean.
**thisArg**: Optional. A value to use as 'this' within the callback.
**Returns**: The index of the last matching element, or -1 if not found.
### indexOf(searchElement, fromIndex) <sub>function</sub>
Return the first index at which a given element can be found. If not present,
return -1.
**searchElement**: The item to locate in the array.
**fromIndex**: The index at which to start searching (default 0).
**Returns**: The index of the found element, or -1 if not found.
### lastIndexOf(searchElement, fromIndex) <sub>function</sub>
Return the last index at which a given element can be found, or -1 if not
present. Searches backward from 'fromIndex'.
**searchElement**: The item to locate in the array.
**fromIndex**: The index at which to start searching backward (default array.length - 1).
**Returns**: The last index of the found element, or -1 if not found.
### includes(searchElement, fromIndex) <sub>function</sub>
Return a boolean indicating whether the array contains the given element,
comparing elements using the SameValueZero algorithm.
**searchElement**: The value to search for.
**fromIndex**: The position in the array to start searching (default 0).
**Returns**: True if the element is found, otherwise false.
### join(separator) <sub>function</sub>
Join all elements of the array into a string, separated by 'separator'.
**separator**: The delimiter string to separate elements (default ',').
**Returns**: A string of array elements joined by the separator.
### toString() <sub>function</sub>
Return a string representing the elements of the array, separated by commas.
Overrides Object.prototype.toString.
**Returns**: A comma-separated string of array elements.
### toLocaleString() <sub>function</sub>
Return a localized string representing the array and its elements, calling
each element's toLocaleString if available.
**Returns**: A locale-sensitive, comma-separated string of array elements.
### pop() <sub>function</sub>
Remove the last element from the array and return it. This changes the length
of the array.
**Returns**: The removed element, or undefined if the array is empty.
### push(items) <sub>function</sub>
Append one or more elements to the end of the array and return the new length
of the array.
**items**: One or more items to append.
**Returns**: The new length of the array.
### shift() <sub>function</sub>
Remove the first element from the array and return it. This changes the length
of the array.
**Returns**: The removed element, or undefined if the array is empty.
### unshift(items) <sub>function</sub>
Insert one or more elements at the start of the array and return the new
length of the array.
**items**: One or more elements to insert at the start.
**Returns**: The new length of the array.
### reverse() <sub>function</sub>
Reverse the elements of the array in place and return the modified array.
**Returns**: The reversed array.
### toReversed() <sub>function</sub>
Return a shallow copy of the array in reverse order, without modifying the original array.
**Returns**: A new reversed array.
### sort(compareFunction) <sub>function</sub>
Sort the array in place, returning it. By default, sorts elements as strings in ascending order. An optional compareFunction may be used for custom sorting.
**compareFunction**: A function(a, b) => number, defining sort order.
**Returns**: The sorted array.
### toSorted(compareFunction) <sub>function</sub>
Return a shallow copy of the array, sorted according to the optional compare
function, without modifying the original array.
**compareFunction**: A function(a, b) => number, defining sort order.
**Returns**: A new sorted array.
### slice(start, end) <sub>function</sub>
Return a shallow copy of a portion of the array into a new array object, selected from 'start' to 'end' (end not included).
**start**: The beginning index (0-based). Negative values count from the end.
**end**: The end index (exclusive). Negative values count from the end.
**Returns**: A new array containing the extracted elements.
### splice(start, deleteCount, items) <sub>function</sub>
Change the contents of the array by removing or replacing existing elements and/or adding new elements in place. Returns an array of removed elements.
**start**: The index at which to start changing the array.
**deleteCount**: Number of elements to remove.
**items**: Elements to add in place of the removed elements.
**Returns**: An array containing the removed elements (if any).
### toSpliced(start, deleteCount, items) <sub>function</sub>
Return a shallow copy of the array, with a splice-like operation applied at 'start' removing 'deleteCount' elements and adding 'items'. Does not mutate the original array.
**start**: The index at which to start the splice operation.
**deleteCount**: Number of elements to remove.
**items**: Elements to add in place of the removed elements.
**Returns**: A new array with the splice applied.
### copyWithin(target, start, end) <sub>function</sub>
Copy a sequence of array elements within the array, overwriting existing values. This operation is performed in place and returns the modified array.
**target**: The index at which to copy the sequence to.
**start**: The beginning index of the sequence to copy.
**end**: The end index (exclusive) of the sequence to copy (default array.length).
**Returns**: The modified array.
### flatMap(callback, thisArg) <sub>function</sub>
Return a new array formed by applying a callback function to each element and then flattening the result by one level.
**callback**: A function(element, index, array) => array or value.
**thisArg**: Optional. A value to use as 'this' within the callback.
**Returns**: A new array with the flattened results.
### flat(depth) <sub>function</sub>
Return a new array with all sub-array elements concatenated into it recursively up to the specified depth.
**depth**: The maximum depth to flatten (default 1).
**Returns**: A new flattened array.
### values() <sub>function</sub>
Return a new Array Iterator object that contains the values for each index in the array.
**Returns**: An iterator over the array's elements.
### keys() <sub>function</sub>
Return a new Array Iterator object that contains the keys (indexes) for each index in the array.
**Returns**: An iterator over the array's indices.
### entries() <sub>function</sub>
Return a new Array Iterator object that contains key/value pairs for each index in the array. Each entry is [index, value].
**Returns**: An iterator over [index, value] pairs.
### add(other) <sub>function</sub>
Non-standard. Add corresponding elements of the current array and 'other' element-wise, returning a new array. Behavior depends on data types.
**other**: Another array or scalar to add to each element.
**Returns**: A new array with element-wise sum results.
### sub(other) <sub>function</sub>
Non-standard. Subtract corresponding elements of 'other' from the current array element-wise, returning a new array. Behavior depends on data types.
**other**: Another array or scalar to subtract from each element.
**Returns**: A new array with element-wise difference results.
### div(other) <sub>function</sub>
Non-standard. Divide each element of the current array by the corresponding element of 'other' (or a scalar) element-wise, returning a new array. Behavior depends on data types.
**other**: Another array or scalar for the division.
**Returns**: A new array with element-wise division results.
### scale() <sub>function</sub>
### lerp() <sub>function</sub>
### x <sub>accessor</sub>
### y <sub>accessor</sub>
### xy <sub>accessor</sub>
### r <sub>accessor</sub>
### g <sub>accessor</sub>
### b <sub>accessor</sub>
### a <sub>accessor</sub>
### rgb <sub>accessor</sub>
### rgba <sub>accessor</sub>
### filter!(fn) <sub>function</sub>
Perform an in-place filter of this array using the provided callback 'fn'.
Any element for which 'fn' returns a falsy value is removed. The array is modified
and then returned.
**fn**: A callback function(element, index, array) => boolean.
**Returns**: The filtered (modified) array.
### delete(item) <sub>function</sub>
Remove the first occurrence of 'item' from the array, if it exists.
Returns undefined.
**item**: The item to remove.
**Returns**: undefined
### copy() <sub>function</sub>
Return a deep copy of this array by applying 'deep_copy' to each element.
The resulting array is entirely new.
**Returns**: A new array that is a deep copy of the original.
### equal(b) <sub>function</sub>
Check if this array and array 'b' have the same elements in the same order.
If they are of different lengths, return false. Otherwise compare them via JSON.
**b**: Another array to compare against.
**Returns**: True if they match, false otherwise.
### last() <sub>function</sub>
Return the last element of this array. If the array is empty, returns undefined.
**Returns**: The last element of the array, or undefined if empty.
### wrapped(x) <sub>function</sub>
Return a copy of the array with the first 'x' elements appended to the end.
Does not modify the original array.
**x**: The number of leading elements to re-append.
**Returns**: A new array with the leading elements wrapped to the end.
### wrap_idx(x) <sub>function</sub>
Wrap the integer 'x' around this array's length, ensuring the resulting index
lies within [0, this.length - 1].
**x**: The index to wrap.
**Returns**: A wrapped index within this array's bounds.
### mirrored(x) <sub>function</sub>
Return a new array that appends a reversed copy (excluding the last element)
of itself to the end. For example, [1,2,3] -> [1,2,3,2,1]. If the array has length
<= 1, a copy of it is returned directly.
**Returns**: A new "mirrored" array.

0
docs/dull.png → docs/dull/dull.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 219 KiB

After

Width:  |  Height:  |  Size: 219 KiB

47
docs/dull/globals/Array.md Normal file
View File

@@ -0,0 +1,47 @@
# Array
### length <sub>number</sub>
### name <sub>string</sub>
### prototype <sub>object</sub>
### isArray(value) <sub>function</sub>
Determine if the given value is an Array. Returns true if the argument is an array, otherwise false.
**value**: The value to be checked.
**Returns**: True if 'value' is an array, otherwise false.
### from(arrayLike, mapFn, thisArg) <sub>function</sub>
Create a new array from an array-like or iterable object. An optional map function can be invoked on each element before it is added to the new array.
**arrayLike**: An array-like or iterable object to convert.
**mapFn**: Optional. A function to call on every element of the new array.
**thisArg**: Optional. A value to use as 'this' within the map function.
**Returns**: A new array populated with elements processed from arrayLike.
### of(elements) <sub>function</sub>
Create a new array with a variable number of arguments, regardless of the number or type of the arguments. Unlike the Array constructor, there is no special treatment for a single numeric argument.
**elements**: A variable number of arguments which become array elements.
**Returns**: A new array containing the provided arguments.

7
docs/dull/globals/Error.md Normal file
View File

@@ -0,0 +1,7 @@
# Error
### length <sub>number</sub>
### name <sub>string</sub>
### prototype <sub>object</sub>

7
docs/dull/globals/Function.md Normal file
View File

@@ -0,0 +1,7 @@
# Function
### length <sub>number</sub>
### name <sub>string</sub>
### prototype() <sub>function</sub>

458
docs/dull/globals/Math.md Normal file
View File

@@ -0,0 +1,458 @@
# Math
### min(values) <sub>function</sub>
Return the smallest of the zero or more given numbers. If no arguments are provided, the result is Infinity. If any value is NaN, the result is NaN.
**values**: One or more numeric values.
**Returns**: The smallest numeric value, Infinity if no arguments, or NaN if any argument cannot be converted to a number.
### max(values) <sub>function</sub>
Return the largest of the zero or more given numbers. If no arguments are provided, the result is -Infinity. If any value is NaN, the result is NaN.
**values**: One or more numeric values.
**Returns**: The largest numeric value, -Infinity if no arguments, or NaN if any argument cannot be converted to a number.
### abs(x) <sub>function</sub>
Return the absolute value of the given number. For example, -5 becomes 5.
**x**: A numeric value.
**Returns**: The absolute value of x.
### floor(x) <sub>function</sub>
Return the greatest integer less than or equal to x, effectively rounding down to the nearest integer.
**x**: A numeric value.
**Returns**: The largest integer <= x.
### ceil(x) <sub>function</sub>
Return the smallest integer greater than or equal to x, effectively rounding up to the nearest integer.
**x**: A numeric value.
**Returns**: The smallest integer >= x.
### round(x) <sub>function</sub>
Return x rounded to the nearest integer. If the fractional portion is 0.5 or
greater, rounds up; otherwise, rounds down. Ties away from zero in modern ECMAScript.
**x**: A numeric value.
**Returns**: x rounded to the nearest integer.
### sqrt(x) <sub>function</sub>
Return the positive square root of x. If x is negative, the result is NaN.
**x**: A non-negative numeric value.
**Returns**: The positive square root of x, or NaN if x is negative.
### acos(x) <sub>function</sub>
Return the arccosine (in radians) of x, in the range [0, π]. If x is outside
the range [-1, 1], the result is NaN.
**x**: A numeric value in [-1, 1].
**Returns**: The arccosine of x in radians, or NaN if out of range.
### asin(x) <sub>function</sub>
Return the arcsine (in radians) of x, in the range [-π/2, π/2]. If x is
outside [-1, 1], the result is NaN.
**x**: A numeric value in [-1, 1].
**Returns**: The arcsine of x in radians, or NaN if out of range.
### atan(x) <sub>function</sub>
Return the arctangent (in radians) of x, in the range [-π/2, π/2].
**x**: A numeric value.
**Returns**: The arctangent of x in radians.
### atan2(y, x) <sub>function</sub>
Return the arctangent of the quotient of its arguments (y / x), in the range
(-π, π]. This takes into account the signs of both x and y to determine
the correct quadrant.
**y**: The y coordinate.
**x**: The x coordinate.
**Returns**: The angle in radians between the positive x-axis and the point (x, y).
### cos(x) <sub>function</sub>
Return the cosine of x, where x is in radians.
**x**: A numeric value in radians.
**Returns**: The cosine of x, in the range [-1, 1].
### exp(x) <sub>function</sub>
Return e^x, where e is Euler's number (approximately 2.71828).
**x**: A numeric exponent.
**Returns**: The value of e raised to x.
### log(x) <sub>function</sub>
Return the natural logarithm (base e) of x. If x is <= 0, the result is NaN.
**x**: A positive numeric value.
**Returns**: The natural logarithm of x.
### pow(base, exponent) <sub>function</sub>
Return base raised to the power exponent, i.e. base^exponent. If base is
negative and exponent is not an integer, result is NaN.
**base**: The base number.
**exponent**: The exponent number.
**Returns**: base raised to exponent.
### sin(x) <sub>function</sub>
Return the sine of x, where x is in radians.
**x**: A numeric value in radians.
**Returns**: The sine of x, in the range [-1, 1].
### tan(x) <sub>function</sub>
Return the tangent of x, where x is in radians. If x is (π/2 + nπ), the
result is ±Infinity or NaN.
**x**: A numeric value in radians.
**Returns**: The tangent of x.
### trunc(x) <sub>function</sub>
Return the integer part of x by removing any fractional digits. Does not
round, just truncates.
**x**: A numeric value.
**Returns**: x truncated toward zero.
### sign(x) <sub>function</sub>
Return the sign of x, indicating whether x is positive, negative, or zero.
Returns 1 if x > 0, -1 if x < 0, 0 if x is 0, and NaN if x is NaN.
**x**: A numeric value.
**Returns**: 1, -1, 0, -0, or NaN, depending on x.
### cosh(x) <sub>function</sub>
Return the hyperbolic cosine of x, (e^x + e^-x) / 2.
**x**: A numeric value.
**Returns**: The hyperbolic cosine of x.
### sinh(x) <sub>function</sub>
Return the hyperbolic sine of x, (e^x - e^-x) / 2.
**x**: A numeric value.
**Returns**: The hyperbolic sine of x.
### tanh(x) <sub>function</sub>
Return the hyperbolic tangent of x, (e^x - e^-x) / (e^x + e^-x).
**x**: A numeric value.
**Returns**: The hyperbolic tangent of x.
### acosh(x) <sub>function</sub>
Return the inverse hyperbolic cosine of x, defined as ln(x + sqrt(x^2 - 1)).
If x < 1, the result is NaN.
**x**: A numeric value >= 1.
**Returns**: The inverse hyperbolic cosine of x.
### asinh(x) <sub>function</sub>
Return the inverse hyperbolic sine of x, defined as ln(x + sqrt(x^2 + 1)).
**x**: A numeric value.
**Returns**: The inverse hyperbolic sine of x.
### atanh(x) <sub>function</sub>
Return the inverse hyperbolic tangent of x, defined as 1/2 * ln((1 + x) / (1 - x)).
If |x| >= 1, the result is NaN.
**x**: A numeric value in the range (-1, 1).
**Returns**: The inverse hyperbolic tangent of x.
### expm1(x) <sub>function</sub>
Return e^x - 1, for small values of x this provides higher precision than
Math.exp(x) - 1.
**x**: A numeric exponent.
**Returns**: e^x - 1.
### log1p(x) <sub>function</sub>
Return the natural logarithm of (1 + x). More accurate than Math.log(1 + x)
for small x.
**x**: A numeric value > -1.
**Returns**: ln(1 + x).
### log2(x) <sub>function</sub>
Return the base-2 logarithm of x. If x <= 0, the result is NaN.
**x**: A positive numeric value.
**Returns**: The base-2 logarithm of x.
### log10(x) <sub>function</sub>
Return the base-10 logarithm of x. If x <= 0, the result is NaN.
**x**: A positive numeric value.
**Returns**: The base-10 logarithm of x.
### cbrt(x) <sub>function</sub>
Return the cube root of x, including negative values.
**x**: A numeric value (can be negative).
**Returns**: The cube root of x.
### hypot(values) <sub>function</sub>
Return the square root of the sum of squares of its arguments, i.e.
sqrt(x1^2 + x2^2 + ...). If any value is ±Infinity, returns Infinity. If
any value is NaN, returns NaN.
**values**: One or more numeric values.
**Returns**: The square root of the sum of squares of the arguments.
### random() <sub>function</sub>
Return a pseudo-random floating-point number in the range [0, 1).
The result is usually seeded by an engine-defined source of randomness.
**Returns**: A number >= 0 and < 1.
### fround(x) <sub>function</sub>
Return the nearest 32-bit single-precision float representation of x.
**x**: A numeric value.
**Returns**: The 32-bit float representation of x.
### imul(a, b) <sub>function</sub>
Return the result of a 32-bit integer multiplication of two values.
Effectively (a * b) | 0 in many implementations.
**a**: A numeric value.
**b**: A numeric value.
**Returns**: The 32-bit integer result of multiplying a by b.
### clz32(x) <sub>function</sub>
Return the number of leading zero bits in the 32-bit binary representation
of x. If x is 0, returns 32.
**x**: A numeric value, treated as a 32-bit unsigned integer.
**Returns**: The count of leading zero bits, in the range [0, 32].
### E <sub>number</sub>
### LN10 <sub>number</sub>
### LN2 <sub>number</sub>
### LOG2E <sub>number</sub>
### LOG10E <sub>number</sub>
### PI <sub>number</sub>
### SQRT1_2 <sub>number</sub>
### SQRT2 <sub>number</sub>

99
docs/dull/globals/Number.md Normal file
View File

@@ -0,0 +1,99 @@
# Number
### length <sub>number</sub>
### name <sub>string</sub>
### prototype <sub>object</sub>
### parseInt(string, radix) <sub>function</sub>
Parse a string argument and return an integer of the specified radix (base).
If the string does not start with a valid integer, return NaN. Leading
whitespace is ignored.
**string**: The string to parse as an integer.
**radix**: An integer between 2 and 36 indicating the base of the number in the string.
**Returns**: The parsed integer, or NaN if the input is not a valid integer.
### parseFloat(string) <sub>function</sub>
Parse a string argument and return a floating-point number. If the string does not represent a valid number, return NaN. Leading whitespace is ignored, and the string can include a decimal point or exponent.
**string**: The string to parse as a floating-point number.
**Returns**: The parsed number, or NaN if invalid.
### isNaN(value) <sub>function</sub>
Determine if a value is the special numeric value NaN, without converting the argument. Unlike the global isNaN(), this returns false for non-numeric values.
**value**: The value to test.
**Returns**: True if the value is NaN, otherwise false.
### isFinite(value) <sub>function</sub>
Determine if a value is a finite number. Unlike the global isFinite(), this returns false for non-numeric values without attempting to convert them.
**value**: The value to test.
**Returns**: True if the value is a finite number, otherwise false.
### isInteger(value) <sub>function</sub>
Check if the given value is a finite number and also an integer (no fractional part). Returns false for non-numeric values or NaN.
**value**: The value to test.
**Returns**: True if value is an integer, otherwise false.
### isSafeInteger(value) <sub>function</sub>
Check if the given value is a safe integer. A safe integer is one that can be exactly represented as an IEEE-754 double-precision number (i.e., between -9007199254740991 and 9007199254740991 inclusive).
**value**: The value to test.
**Returns**: True if value is an integer within the safe range, otherwise false.
### MAX_VALUE <sub>number</sub>
### MIN_VALUE <sub>number</sub>
### NaN <sub>number</sub>
### NEGATIVE_INFINITY <sub>number</sub>
### POSITIVE_INFINITY <sub>number</sub>
### EPSILON <sub>number</sub>
### MAX_SAFE_INTEGER <sub>number</sub>
### MIN_SAFE_INTEGER <sub>number</sub>

331
docs/dull/globals/Object.md Normal file
View File

@@ -0,0 +1,331 @@
# Object
### length <sub>number</sub>
### name <sub>string</sub>
### prototype <sub>object</sub>
### create(proto, propertiesObject) <sub>function</sub>
Create a new object, using the specified prototype object and optional property descriptors.
**proto**: The object to be used as the prototype.
**propertiesObject**: Optional. An object specifying properties to be added.
**Returns**: A new object with the given prototype and properties.
### getPrototypeOf(obj) <sub>function</sub>
Return the prototype of the specified object. If no prototype is found (e.g. the object has null as its prototype), return null.
**obj**: The object whose prototype is to be returned.
**Returns**: The prototype of 'obj', or null.
### setPrototypeOf(obj, proto) <sub>function</sub>
Set the prototype of the specified object to the provided value. Throws a TypeError if the object is non-extensible and the prototype is changed.
**obj**: The object whose prototype is set.
**proto**: The new prototype or null.
**Returns**: The object 'obj' after setting its prototype.
### defineProperty(obj, prop, descriptor) <sub>function</sub>
Define or modify a property on an object using a property descriptor, returning the object. Throws a TypeError if the descriptor is invalid.
**obj**: The object on which to define or modify a property.
**prop**: The name or Symbol of the property.
**descriptor**: A property descriptor object (e.g., {value, writable, get, set, ...}).
**Returns**: The object with the newly defined or updated property.
### defineProperties(obj, props) <sub>function</sub>
Define new or modify existing properties on an object, given an object of property descriptors. Returns the modified object.
**obj**: The object on which to define or modify properties.
**props**: An object mapping property names to property descriptors.
**Returns**: The modified object.
### getOwnPropertyNames(obj) <sub>function</sub>
Return an array of all own (non-Symbol) property names found directly on the given object, in the same order as a for...in loop would return.
**obj**: The object whose own property names are returned.
**Returns**: An array of strings that correspond to the properties.
### getOwnPropertySymbols(obj) <sub>function</sub>
Return an array of all own Symbol properties found directly on the given object.
**obj**: The object to retrieve Symbol keys from.
**Returns**: An array of Symbol keys.
### groupBy(obj, fn) <sub>function</sub>
Non-standard / Proposed. Group the own properties of an object according to the return value of a grouping function. Typically returns a new object whose keys are the group identifiers.
**obj**: The object to group.
**fn**: A function(key, value) => groupingKey, applied to each property.
**Returns**: An object where properties are grouped by the returned keys.
### keys(obj) <sub>function</sub>
Return an array of the object's own enumerable (non-Symbol) property names, in the same order that a normal loop would.
**obj**: The object whose property names are to be returned.
**Returns**: An array of property names.
### values(obj) <sub>function</sub>
Return an array of the object's own enumerable (non-Symbol) property values, in the same order as Object.keys().
**obj**: The object whose property values are to be returned.
**Returns**: An array of property values.
### entries(obj) <sub>function</sub>
Return an array of [key, value] pairs for the object's own enumerable (non-Symbol) properties, in the same order as Object.keys().
**obj**: The object whose [key, value] pairs are to be returned.
**Returns**: An array of [key, value] pairs.
### isExtensible(obj) <sub>function</sub>
Return a boolean indicating whether new properties can be added to the specified object.
**obj**: The object to test.
**Returns**: True if the object is extensible, otherwise false.
### preventExtensions(obj) <sub>function</sub>
Prevent new properties from ever being added to an object. Existing properties are not affected.
**obj**: The object to mark as non-extensible.
**Returns**: The non-extensible object.
### getOwnPropertyDescriptor(obj, prop) <sub>function</sub>
Return the property descriptor for a named property on the specified object, if it exists, otherwise undefined.
**obj**: The object in which to look for the property.
**prop**: The name or Symbol of the property.
**Returns**: The property descriptor, or undefined if not found.
### getOwnPropertyDescriptors(obj) <sub>function</sub>
Return an object containing all own property descriptors for the given object, keyed by property names (and Symbols).
**obj**: The object to retrieve property descriptors from.
**Returns**: An object mapping property keys to property descriptors.
### is(value1, value2) <sub>function</sub>
Compare two values for strict equality, like '===' but without special treatment for +0 and -0, and treating NaN as equal to NaN.
**value1**: A value to compare.
**value2**: Another value to compare.
**Returns**: True if both values are the same, otherwise false.
### assign(target, sources) <sub>function</sub>
Copy all enumerable own properties from one or more source objects to a target object, returning the modified target.
**target**: The object to receive properties.
**sources**: One or more objects containing properties to copy.
**Returns**: The updated target object.
### seal(obj) <sub>function</sub>
Seal an object, preventing new properties from being added and marking all existing properties as non-configurable. Values of present properties can still be changed if they are writable.
**obj**: The object to seal.
**Returns**: The sealed object.
### freeze(obj) <sub>function</sub>
Freeze an object, preventing new properties from being added, existing properties from being removed, or current properties from being changed (to the extent permitted by property descriptors).
**obj**: The object to freeze.
**Returns**: The frozen object.
### isSealed(obj) <sub>function</sub>
Check if an object is sealed. A sealed object has no configurable properties and is non-extensible.
**obj**: The object to test.
**Returns**: True if the object is sealed, otherwise false.
### isFrozen(obj) <sub>function</sub>
Check if an object is frozen. A frozen object is sealed and all data properties are non-writable.
**obj**: The object to test.
**Returns**: True if the object is frozen, otherwise false.
### __getClass() <sub>function</sub>
### fromEntries(entries) <sub>function</sub>
Transform a list of key-value pairs into an object. The iterable argument should yield pairs [key, value], which become properties on the resulting object.
**entries**: An iterable of [key, value] pairs.
**Returns**: A new object formed from the given entries.
### hasOwn(obj, prop) <sub>function</sub>
Return a boolean indicating whether the specified property exists on the object as a direct own property (similar to hasOwnProperty, but directly on Object).
**obj**: The object on which to check the property.
**prop**: The name or Symbol of the property to check.
**Returns**: True if the property is found on 'obj', otherwise false.
### id(obj) <sub>function</sub>
Non-standard. Return a unique identifier for the given object, assigning one if necessary. The same object will always yield the same ID.
**obj**: The object to retrieve or assign a unique ID.
**Returns**: A unique identifier (string or number) associated with the object.
### mixin(target, source) <sub>function</sub>
Copy all property descriptors from 'source' into 'target'.
**target**: The object that will receive properties.
**source**: The object whose properties are to be copied.
**Returns**: The updated 'target' object.

49
docs/dull/globals/String.md Normal file
View File

@@ -0,0 +1,49 @@
# String
### length <sub>number</sub>
### name <sub>string</sub>
### prototype <sub>object</sub>
### fromCharCode(codeUnits) <sub>function</sub>
Return a string created from the specified sequence of UTF-16 code units.
Each argument is treated as a code unit in the range [0, 65535].
**codeUnits**: A series of numbers representing UTF-16 code units.
**Returns**: A string constructed by mapping each code unit to a character.
### fromCodePoint(codePoints) <sub>function</sub>
Return a string created from the specified sequence of code points,
including those above U+FFFF (which will become surrogate pairs).
Throws a RangeError for invalid code points.
**codePoints**: A series of numbers representing Unicode code points.
**Returns**: A string constructed from the given code points.
### raw(template, substitutions) <sub>function</sub>
A tag function of template literals that returns a raw where escape sequences (e.g., '\n', '\u00A9') are not processed.
Commonly used to retrieve the unprocessed text of a template.
**template**: A template literal, or an object with a 'raw' property.
**substitutions**: Additional values to substitute (if any).
**Returns**: The combined raw string from the template.

59
docs/dull/globals/Symbol.md Normal file
View File

@@ -0,0 +1,59 @@
# Symbol
### length <sub>number</sub>
### name <sub>string</sub>
### prototype <sub>object</sub>
### for(key) <sub>function</sub>
Search the global symbol registry for a symbol with the given key. If found, return that symbol; otherwise, create a new symbol with that key and add it to the registry, then return the new symbol.
**key**: A string key used to identify the symbol in the global registry.
**Returns**: A symbol associated with the given key in the global registry.
### keyFor(sym) <sub>function</sub>
Retrieve a shared symbol’s key from the global symbol registry. If the symbol is not in the global registry, return undefined.
**sym**: The symbol to find the key for.
**Returns**: The string key if 'sym' is a global symbol, otherwise undefined.
### toPrimitive <sub>symbol</sub>
### iterator <sub>symbol</sub>
### match <sub>symbol</sub>
### matchAll <sub>symbol</sub>
### replace <sub>symbol</sub>
### search <sub>symbol</sub>
### split <sub>symbol</sub>
### toStringTag <sub>symbol</sub>
### isConcatSpreadable <sub>symbol</sub>
### hasInstance <sub>symbol</sub>
### species <sub>symbol</sub>
### unscopables <sub>symbol</sub>
### asyncIterator <sub>symbol</sub>
### operatorSet <sub>symbol</sub>

0
docs/dull.md → docs/dull/index.md
View File

1527
scripts/core/base.js
View File

File diff suppressed because it is too large Load Diff

7
scripts/core/engine.js
View File

@@ -1,10 +1,6 @@
(function engine() {
prosperon.DOC = Symbol('+documentation+') // Symbol for documentation references
var pd = Object.getOwnPropertyDescriptor(prosperon, 'c_types')
pd.enumerable = false
Object.defineProperty(prosperon,'c_types', pd)
//
// sprite
//
@@ -1656,7 +1652,8 @@ prosperon[prosperon.DOC] = {
DOC: `Symbol used to store documentation references on objects.`,
on: `Register a callback function for a given event type. Returns a function to remove the callback.`,
dispatch: `Dispatch an event of the given type, calling all registered callbacks with the provided data.`,
PATH: `Array of directory paths that Prosperon will search to find scripts or modules.`
PATH: `Array of directory paths that Prosperon will search to find scripts or modules.`,
c_types: `Prototype objects for all present defined c-types (like sprite, transform, etc)`
}
// Document the actor object/prototype

170
scripts/modules/doc.js
View File

@@ -1,19 +1,19 @@
// doc.js
function docOf(obj, prop) {
// Grab the top-level doc block on the object.
var block = obj[prosperon.DOC];
if (!block) return '';
// 1) If `block` is directly a string, that’s the entire doc for the object.
// If a sub-property was requested, we have nowhere to look that up → return ''.
// 1) If `block` is a string, that's the entire doc for `obj`.
// If a sub-property is requested, we have nowhere to look → return ''.
if (typeof block === 'string') {
return prop ? '' : block;
}
// 2) Otherwise, `block` is (hopefully) an object. We handle two scenarios:
// (a) No `prop` asked for → return block.doc or block[prosperon.DOC].
// (b) If a `prop` is asked for → check if block[prop] is a string or object with its own doc.
// 2) Otherwise, if `block` is an object:
// (a) With no `prop`, return block.doc or block[prosperon.DOC].
// (b) If `prop` is given, look for doc specifically for that property (just one level).
if (typeof block === 'object') {
// 2a) If no property was requested, return block.doc or block[prosperon.DOC], if either is a string.
// 2a) No property → top-level doc
if (!prop) {
if (typeof block.doc === 'string') {
return block.doc;
@@ -24,16 +24,12 @@ function docOf(obj, prop) {
return '';
}
// 2b) If a property is requested, see if there's a doc for that property inside the block.
// 2b) If a prop is requested → see if there's a doc string or object for that property
var subBlock = block[prop];
if (!subBlock) return '';
// If subBlock is a string → return it as the doc
if (typeof subBlock === 'string') {
return subBlock;
}
// If subBlock is an object, see if it has .doc or [prosperon.DOC]
if (typeof subBlock === 'object') {
if (typeof subBlock.doc === 'string') {
return subBlock.doc;
@@ -49,7 +45,6 @@ function docOf(obj, prop) {
return '';
}
function parseDocStr(docStr) {
if (!docStr) return [];
@@ -57,15 +52,14 @@ function parseDocStr(docStr) {
var paramRe = /^:param\s+([A-Za-z0-9_]+)\s*:\s*(.*)$/;
var returnRe = /^:return:\s*(.*)$/;
// We'll collect three categories of lines, then reassemble:
var descLines = []; // For plain description lines
var paramLines = []; // For :param: lines
var returnLines = []; // For :return: lines
var descLines = [];
var paramLines = [];
var returnLines = [];
for (var i = 0; i < lines.length; i++) {
var line = lines[i].trim();
if (!line) {
// Keep empty lines with the "desc" section to maintain spacing
// Keep empty lines in the desc section
descLines.push('');
continue;
}
@@ -74,26 +68,21 @@ function parseDocStr(docStr) {
var rm = returnRe.exec(line);
if (pm) {
// param line → store in paramLines
paramLines.push('**' + pm[1] + '**: ' + pm[2]);
paramLines.push('');
} else if (rm) {
// return line → store in returnLines
returnLines.push('**Returns**: ' + rm[1]);
returnLines.push('');
} else {
// Otherwise, it's a general description line
descLines.push(line);
}
}
// Now reassemble in the fixed order:
// 1) description lines, 2) param lines, 3) returns lines
var final = [];
// Reassemble: description → params → returns
if (descLines.length) {
final.push.apply(final, descLines);
// Insert blank line if needed
if (paramLines.length || returnLines.length) {
final.push('');
}
@@ -114,40 +103,32 @@ function parseDocStr(docStr) {
return final;
}
function writeDocFile(obj, title) {
var lines = [];
var docTitle = title || "Documentation";
lines.push('# ' + docTitle + '\n');
walkObject(obj, lines, 1, docTitle);
return lines.join('\n');
// If you had I/O, you'd write to file here
// io.slurpwrite(outputPath, finalStr)
}
/**
* Documents the top-level object and each of its immediate properties,
* but does NOT recurse deeper than that.
*/
function walkObject(obj, lines, level, name) {
// See what doc string (if any) this object has
// Print top-level doc or fallback heading
var topDocStr = docOf(obj);
// If there's an actual docstring for the object, don't output another heading
if (topDocStr) {
// parseDocStr is your existing function that handles :param etc.
var docOut = parseDocStr(topDocStr);
if (docOut.length > 0) {
lines.push(docOut.join('\n') + '\n');
}
}
// Otherwise, if there's no docstring, insert an auto-generated heading
else {
var heading = '#'.repeat(level + 1) + ' ' + name;
lines.push(heading + '\n');
}
// Now enumerate this object's direct properties
var propNames = Object.keys(obj);
var propNames = Object.getOwnPropertyNames(obj);
for (var i = 0; i < propNames.length; i++) {
var prop = propNames[i];
if (prop === 'constructor') continue;
@@ -155,40 +136,60 @@ function walkObject(obj, lines, level, name) {
var desc = Object.getOwnPropertyDescriptor(obj, prop);
if (!desc) continue;
// Check if this is an accessor property (getter/setter)
// Check if accessor property (getter/setter)
var hasGetter = typeof desc.get === 'function';
var hasSetter = typeof desc.set === 'function';
if (hasGetter || hasSetter) {
// We handle them as a single "property" entry,
// not separate get/set headings.
writeProperty(lines, obj, prop, desc, level);
continue;
}
// Otherwise, if there's a "value" (could be a function or an object)
// If it's a normal data property
if ('value' in desc) {
var val = desc.value;
// If it's a function, treat it like a method
if (typeof val === 'function') {
writeMethod(lines, obj, prop, val, level);
} else if (val && typeof val === 'object') {
// Possibly a nested object; check if it or its children have doc
if (hasAnyDoc(val)) {
walkObject(val, lines, level + 1, prop);
}
}
// If it's an object, just print doc for that object (no deep recursion)
else if (val && typeof val === 'object') {
writeSubObject(lines, obj, prop, val, level);
}
// Otherwise, it's a primitive or something else
else {
writeDataProperty(lines, obj, prop, val, level);
}
}
}
}
/**
* Writes out a single property entry for an accessor (getter/setter).
* - If only a getter, adds "(read only)" just below the property name.
* - If only a setter, adds "(set only)" just below the property name.
* - If both, no extra text is added (but we do a single heading).
* Write out a heading and doc for an object property
* (but do NOT recurse into that object's subproperties).
*/
function writeSubObject(lines, parentObj, prop, val, level) {
// E.g. "## someObject <sub>object</sub>"
var heading = '#'.repeat(level + 2) + ' ' + prop + ' <sub>object</sub>';
lines.push(heading + '\n');
// 1) If there's doc assigned specifically to the parent's doc block for `prop`
var docStr = docOf(parentObj, prop);
// 2) If no doc there, see if the object itself has top-level doc
if (!docStr) {
docStr = docOf(val);
}
var docOut = parseDocStr(docStr);
if (docOut.length > 0) {
lines.push(docOut.join('\n') + '\n');
}
}
function writeProperty(lines, parentObj, prop, desc, level) {
var heading = '#'.repeat(level + 2) + ' ' + prop;
// E.g. "## myProp <sub>accessor</sub>"
var heading = '#'.repeat(level + 2) + ' ' + prop + ' <sub>accessor</sub>';
lines.push(heading + '\n');
var hasGetter = typeof desc.get === 'function';
@@ -199,10 +200,8 @@ function writeProperty(lines, parentObj, prop, desc, level) {
} else if (!hasGetter && hasSetter) {
lines.push('(set only)\n');
}
// If both, we do nothing extra
// Collect doc from the property-level doc block
// If that's empty, see if either accessor function has doc
// Look up doc in parent's doc block first, or in the accessor functions
var docStr = docOf(parentObj, prop);
if (!docStr && hasGetter) {
docStr = docOf(desc.get) || docStr;
@@ -217,38 +216,12 @@ function writeProperty(lines, parentObj, prop, desc, level) {
}
}
function hasAnyDoc(o) {
if (!o) return false;
// If the object itself has a docOf
if (docOf(o)) return true;
// Or if any property is a function that has doc
var names = Object.getOwnPropertyNames(o);
for (var i = 0; i < names.length; i++) {
var desc = Object.getOwnPropertyDescriptor(o, names[i]);
if (!desc) continue;
// check if accessor doc
if (typeof desc.get === 'function' && docOf(desc.get)) return true;
if (typeof desc.set === 'function' && docOf(desc.set)) return true;
// check function doc
if (desc.value && typeof desc.value === 'function') {
if (docOf(desc.value) || docOf(o, names[i])) return true;
}
// or check nested object
if (desc.value && typeof desc.value === 'object') {
if (hasAnyDoc(desc.value)) return true;
}
}
return false;
}
function writeMethod(lines, parentObj, prop, fn, level) {
// Pull doc from the function or from the parent's doc block
var docStr = fn[prosperon.DOC] || docOf(parentObj, prop) || '';
// parse :param lines
var paramNames = [];
// Try to extract param names from the doc
if (docStr) {
var docLines = docStr.split('\n');
var paramRe = /^:param\s+([A-Za-z0-9_]+)\s*:\s*(.*)$/;
@@ -258,27 +231,50 @@ function writeMethod(lines, parentObj, prop, fn, level) {
}
}
// E.g. "## myFunction(param1, param2) <sub>function</sub>"
var heading = '#'.repeat(level + 2) + ' ' + prop;
// if we found param names in the doc, show them in the heading
if (paramNames.length > 0) {
heading += '(' + paramNames.join(', ') + ')';
} else {
// fallback: parse the function signature
// As a fallback, parse function signature
var m = fn.toString().match(/\(([^)]*)\)/);
if (m && m[1].trim()) {
heading += '(' + m[1].trim() + ')';
} else {
// If no params at all (or we cannot detect them), still add ()
heading += '()';
}
}
heading += ' <sub>function</sub>';
lines.push(heading + '\n');
// parse doc lines
var docOut = parseDocStr(docStr);
if (docOut.length > 0) {
lines.push(docOut.join('\n') + '\n');
}
}
writeDocFile[prosperon.DOC] = `Return a markdown string for a given obj, with optional title.`;
/**
* Write out a heading and doc for a primitive (string, number, boolean, etc).
*/
function writeDataProperty(lines, parentObj, prop, val, level) {
// E.g. "## someString <sub>string</sub>"
var typeStr = typeof val;
var heading = '#'.repeat(level + 2) + ' ' + prop + ' <sub>' + typeStr + '</sub>';
lines.push(heading + '\n');
// Look up doc in parent's doc block
var docStr = docOf(parentObj, prop);
var docOut = parseDocStr(docStr);
if (docOut.length > 0) {
lines.push(docOut.join('\n') + '\n');
}
}
// Provide a doc string for writeDocFile
writeDocFile[prosperon.DOC] = `Return a markdown string for a given obj, with an optional title.`;
return {
writeDocFile: writeDocFile