From 7cffdab28aeb7048c738fb8483da26c1dde6a71b Mon Sep 17 00:00:00 2001 From: John Alanbrook Date: Sun, 9 Feb 2025 00:00:40 -0600 Subject: [PATCH] document c types --- docs/api/actor.md | 13 + docs/api/c_types/PHYSFS_File.md | 16 - docs/api/c_types/SDL_Camera.md | 7 - docs/api/c_types/SDL_Cursor.md | 1 - docs/api/c_types/SDL_GPUBuffer.md | 4 - docs/api/c_types/SDL_GPUCommandBuffer.md | 55 - docs/api/c_types/SDL_GPUComputePass.md | 19 - docs/api/c_types/SDL_GPUComputePipeline.md | 1 - docs/api/c_types/SDL_GPUCopyPass.md | 1 - docs/api/c_types/SDL_GPUDevice.md | 55 - docs/api/c_types/SDL_GPUFence.md | 1 - docs/api/c_types/SDL_GPUGraphicsPipeline.md | 1 - docs/api/c_types/SDL_GPURenderPass.md | 34 - docs/api/c_types/SDL_GPUSampler.md | 1 - docs/api/c_types/SDL_GPUShader.md | 1 - docs/api/c_types/SDL_GPUTexture.md | 4 - docs/api/c_types/SDL_GPUTransferBuffer.md | 1 - docs/api/c_types/SDL_Renderer.md | 76 -- docs/api/c_types/SDL_Surface.md | 16 - docs/api/c_types/SDL_Texture.md | 4 - docs/api/c_types/SDL_Thread.md | 4 - docs/api/c_types/SDL_Window.md | 40 - docs/api/c_types/datastream.md | 22 - docs/api/c_types/font.md | 19 - docs/api/c_types/rtree.md | 22 - docs/api/c_types/sprite.md | 22 - docs/api/c_types/timer.md | 13 - docs/api/c_types/transform.md | 67 -- docs/api/console.md | 37 + docs/api/index.md | 3 - docs/api/modules/actor.md | 56 +- docs/api/modules/cmd.md | 2 + docs/api/modules/color.md | 2 + docs/api/modules/doc.md | 8 +- docs/api/modules/draw2d.md | 66 +- docs/api/modules/event.md | 14 +- docs/api/modules/geometry.md | 122 +- docs/api/modules/graphics.md | 146 ++- docs/api/modules/imgui.md | 2 + docs/api/modules/input.md | 48 +- docs/api/modules/io.md | 111 +- docs/api/modules/js.md | 117 +- docs/api/modules/json.md | 6 +- docs/api/modules/loop.md | 4 +- docs/api/modules/math.md | 64 +- docs/api/modules/miniz.md | 2 + docs/api/modules/os.md | 52 +- docs/api/modules/packer.md | 45 + docs/api/modules/render.md | 55 +- docs/api/modules/resources.md | 32 +- docs/api/modules/sound.md | 10 +- docs/api/modules/spline.md | 6 +- docs/api/modules/time.md | 28 +- docs/api/modules/tween.md | 30 +- docs/api/modules/util.md | 113 +- docs/api/modules/video.md | 4 +- docs/api/prosperon.md | 51 + docs/api/types/PHYSFS_File.md | 55 + docs/api/types/SDL_Camera.md | 27 + docs/api/types/SDL_Cursor.md | 4 + docs/api/types/SDL_GPUBuffer.md | 5 + docs/api/types/SDL_GPUCommandBuffer.md | 231 ++++ docs/api/types/SDL_GPUComputePass.md | 83 ++ docs/api/types/SDL_GPUComputePipeline.md | 5 + docs/api/types/SDL_GPUCopyPass.md | 4 + docs/api/types/SDL_GPUDevice.md | 236 ++++ docs/api/types/SDL_GPUFence.md | 5 + docs/api/types/SDL_GPUGraphicsPipeline.md | 5 + docs/api/types/SDL_GPURenderPass.md | 159 +++ docs/api/types/SDL_GPUSampler.md | 4 + docs/api/types/SDL_GPUShader.md | 5 + docs/api/types/SDL_GPUTexture.md | 5 + docs/api/types/SDL_GPUTransferBuffer.md | 5 + docs/api/types/SDL_Renderer.md | 333 ++++++ docs/api/types/SDL_Surface.md | 68 ++ docs/api/types/SDL_Texture.md | 16 + docs/api/types/SDL_Thread.md | 15 + docs/api/types/SDL_Window.md | 126 ++ docs/api/types/datastream.md | 67 ++ docs/api/types/font.md | 66 ++ docs/api/types/rtree.md | 73 ++ docs/api/types/sprite.md | 68 ++ docs/api/types/timer.md | 29 + docs/api/types/transform.md | 214 ++++ docs/api/use.md | 3 + requirements.txt | 193 +-- scripts/core/engine.js | 1166 ++++++++++++++++++- scripts/modules/doc.js | 490 ++++---- source/jsffi.c | 2 +- 89 files changed, 4133 insertions(+), 1390 deletions(-) create mode 100644 docs/api/actor.md delete mode 100644 docs/api/c_types/PHYSFS_File.md delete mode 100644 docs/api/c_types/SDL_Camera.md delete mode 100644 docs/api/c_types/SDL_Cursor.md delete mode 100644 docs/api/c_types/SDL_GPUBuffer.md delete mode 100644 docs/api/c_types/SDL_GPUCommandBuffer.md delete mode 100644 docs/api/c_types/SDL_GPUComputePass.md delete mode 100644 docs/api/c_types/SDL_GPUComputePipeline.md delete mode 100644 docs/api/c_types/SDL_GPUCopyPass.md delete mode 100644 docs/api/c_types/SDL_GPUDevice.md delete mode 100644 docs/api/c_types/SDL_GPUFence.md delete mode 100644 docs/api/c_types/SDL_GPUGraphicsPipeline.md delete mode 100644 docs/api/c_types/SDL_GPURenderPass.md delete mode 100644 docs/api/c_types/SDL_GPUSampler.md delete mode 100644 docs/api/c_types/SDL_GPUShader.md delete mode 100644 docs/api/c_types/SDL_GPUTexture.md delete mode 100644 docs/api/c_types/SDL_GPUTransferBuffer.md delete mode 100644 docs/api/c_types/SDL_Renderer.md delete mode 100644 docs/api/c_types/SDL_Surface.md delete mode 100644 docs/api/c_types/SDL_Texture.md delete mode 100644 docs/api/c_types/SDL_Thread.md delete mode 100644 docs/api/c_types/SDL_Window.md delete mode 100644 docs/api/c_types/datastream.md delete mode 100644 docs/api/c_types/font.md delete mode 100644 docs/api/c_types/rtree.md delete mode 100644 docs/api/c_types/sprite.md delete mode 100644 docs/api/c_types/timer.md delete mode 100644 docs/api/c_types/transform.md create mode 100644 docs/api/console.md delete mode 100644 docs/api/index.md create mode 100644 docs/api/prosperon.md create mode 100644 docs/api/types/PHYSFS_File.md create mode 100644 docs/api/types/SDL_Camera.md create mode 100644 docs/api/types/SDL_Cursor.md create mode 100644 docs/api/types/SDL_GPUBuffer.md create mode 100644 docs/api/types/SDL_GPUCommandBuffer.md create mode 100644 docs/api/types/SDL_GPUComputePass.md create mode 100644 docs/api/types/SDL_GPUComputePipeline.md create mode 100644 docs/api/types/SDL_GPUCopyPass.md create mode 100644 docs/api/types/SDL_GPUDevice.md create mode 100644 docs/api/types/SDL_GPUFence.md create mode 100644 docs/api/types/SDL_GPUGraphicsPipeline.md create mode 100644 docs/api/types/SDL_GPURenderPass.md create mode 100644 docs/api/types/SDL_GPUSampler.md create mode 100644 docs/api/types/SDL_GPUShader.md create mode 100644 docs/api/types/SDL_GPUTexture.md create mode 100644 docs/api/types/SDL_GPUTransferBuffer.md create mode 100644 docs/api/types/SDL_Renderer.md create mode 100644 docs/api/types/SDL_Surface.md create mode 100644 docs/api/types/SDL_Texture.md create mode 100644 docs/api/types/SDL_Thread.md create mode 100644 docs/api/types/SDL_Window.md create mode 100644 docs/api/types/datastream.md create mode 100644 docs/api/types/font.md create mode 100644 docs/api/types/rtree.md create mode 100644 docs/api/types/sprite.md create mode 100644 docs/api/types/timer.md create mode 100644 docs/api/types/transform.md create mode 100644 docs/api/use.md diff --git a/docs/api/actor.md b/docs/api/actor.md new file mode 100644 index 00000000..faf6ca7e --- /dev/null +++ b/docs/api/actor.md @@ -0,0 +1,13 @@ +# actor + +## actor + +### toString + +### spawn(script, config, callback) + +### clear + +### kill + +### delay(fn, seconds) diff --git a/docs/api/c_types/PHYSFS_File.md b/docs/api/c_types/PHYSFS_File.md deleted file mode 100644 index d60a3107..00000000 --- a/docs/api/c_types/PHYSFS_File.md +++ /dev/null @@ -1,16 +0,0 @@ -# PHYSFS_File - -## close() - - -## write() - - -## buffer() - - -## tell() - - -## eof() - diff --git a/docs/api/c_types/SDL_Camera.md b/docs/api/c_types/SDL_Camera.md deleted file mode 100644 index 4a1a5fb1..00000000 --- a/docs/api/c_types/SDL_Camera.md +++ /dev/null @@ -1,7 +0,0 @@ -# SDL_Camera - -## frame() - - -## release_frame() - diff --git a/docs/api/c_types/SDL_Cursor.md b/docs/api/c_types/SDL_Cursor.md deleted file mode 100644 index a629e13f..00000000 --- a/docs/api/c_types/SDL_Cursor.md +++ /dev/null @@ -1 +0,0 @@ -# SDL_Cursor diff --git a/docs/api/c_types/SDL_GPUBuffer.md b/docs/api/c_types/SDL_GPUBuffer.md deleted file mode 100644 index a35dc4ef..00000000 --- a/docs/api/c_types/SDL_GPUBuffer.md +++ /dev/null @@ -1,4 +0,0 @@ -# SDL_GPUBuffer - -## name() - diff --git a/docs/api/c_types/SDL_GPUCommandBuffer.md b/docs/api/c_types/SDL_GPUCommandBuffer.md deleted file mode 100644 index 9184e958..00000000 --- a/docs/api/c_types/SDL_GPUCommandBuffer.md +++ /dev/null @@ -1,55 +0,0 @@ -# SDL_GPUCommandBuffer - -## render_pass() - - -## compute_pass() - - -## swapchain_pass() - - -## acquire_swapchain() - - -## bind_vertex_buffer() - - -## bind_index_buffer() - - -## bind_fragment_sampler() - - -## push_vertex_uniform_data() - - -## push_fragment_uniform_data() - - -## push_compute_uniform_data() - - -## submit() - - -## cancel() - - -## camera() - - -## hud() - - -## push_debug_group() - - -## pop_debug_group() - - -## debug_label() - - -## blit() - diff --git a/docs/api/c_types/SDL_GPUComputePass.md b/docs/api/c_types/SDL_GPUComputePass.md deleted file mode 100644 index 46544169..00000000 --- a/docs/api/c_types/SDL_GPUComputePass.md +++ /dev/null @@ -1,19 +0,0 @@ -# SDL_GPUComputePass - -## dispatch() - - -## end() - - -## pipeline() - - -## samplers() - - -## storage_buffers() - - -## storage_textures() - diff --git a/docs/api/c_types/SDL_GPUComputePipeline.md b/docs/api/c_types/SDL_GPUComputePipeline.md deleted file mode 100644 index 5ebe90ef..00000000 --- a/docs/api/c_types/SDL_GPUComputePipeline.md +++ /dev/null @@ -1 +0,0 @@ -# SDL_GPUComputePipeline diff --git a/docs/api/c_types/SDL_GPUCopyPass.md b/docs/api/c_types/SDL_GPUCopyPass.md deleted file mode 100644 index 8b9ee568..00000000 --- a/docs/api/c_types/SDL_GPUCopyPass.md +++ /dev/null @@ -1 +0,0 @@ -# SDL_GPUCopyPass diff --git a/docs/api/c_types/SDL_GPUDevice.md b/docs/api/c_types/SDL_GPUDevice.md deleted file mode 100644 index 6ad90954..00000000 --- a/docs/api/c_types/SDL_GPUDevice.md +++ /dev/null @@ -1,55 +0,0 @@ -# SDL_GPUDevice - -## claim_window() - - -## make_pipeline() - - -## compute_pipeline() - - -## set_swapchain() - - -## sort_sprite() - - -## make_sampler() - - -## load_texture() - - -## texture() - - -## make_quad() - - -## driver() - - -## make_shader() - - -## acquire_cmd_buffer() - - -## upload() - - -## wait_for_fences() - - -## query_fence() - - -## shader_format() - - -## slice9() - - -## tile() - diff --git a/docs/api/c_types/SDL_GPUFence.md b/docs/api/c_types/SDL_GPUFence.md deleted file mode 100644 index 3b3e9c17..00000000 --- a/docs/api/c_types/SDL_GPUFence.md +++ /dev/null @@ -1 +0,0 @@ -# SDL_GPUFence diff --git a/docs/api/c_types/SDL_GPUGraphicsPipeline.md b/docs/api/c_types/SDL_GPUGraphicsPipeline.md deleted file mode 100644 index 7e2cdf42..00000000 --- a/docs/api/c_types/SDL_GPUGraphicsPipeline.md +++ /dev/null @@ -1 +0,0 @@ -# SDL_GPUGraphicsPipeline diff --git a/docs/api/c_types/SDL_GPURenderPass.md b/docs/api/c_types/SDL_GPURenderPass.md deleted file mode 100644 index 46b1becd..00000000 --- a/docs/api/c_types/SDL_GPURenderPass.md +++ /dev/null @@ -1,34 +0,0 @@ -# SDL_GPURenderPass - -## bind_pipeline() - - -## viewport() - - -## scissor() - - -## draw() - - -## draw_indexed() - - -## end() - - -## bind_index_buffer() - - -## bind_buffers() - - -## bind_samplers() - - -## bind_storage_buffers() - - -## bind_storage_textures() - diff --git a/docs/api/c_types/SDL_GPUSampler.md b/docs/api/c_types/SDL_GPUSampler.md deleted file mode 100644 index 0beeb8ba..00000000 --- a/docs/api/c_types/SDL_GPUSampler.md +++ /dev/null @@ -1 +0,0 @@ -# SDL_GPUSampler diff --git a/docs/api/c_types/SDL_GPUShader.md b/docs/api/c_types/SDL_GPUShader.md deleted file mode 100644 index fc62b890..00000000 --- a/docs/api/c_types/SDL_GPUShader.md +++ /dev/null @@ -1 +0,0 @@ -# SDL_GPUShader diff --git a/docs/api/c_types/SDL_GPUTexture.md b/docs/api/c_types/SDL_GPUTexture.md deleted file mode 100644 index de17001e..00000000 --- a/docs/api/c_types/SDL_GPUTexture.md +++ /dev/null @@ -1,4 +0,0 @@ -# SDL_GPUTexture - -## name() - diff --git a/docs/api/c_types/SDL_GPUTransferBuffer.md b/docs/api/c_types/SDL_GPUTransferBuffer.md deleted file mode 100644 index 7f13732a..00000000 --- a/docs/api/c_types/SDL_GPUTransferBuffer.md +++ /dev/null @@ -1 +0,0 @@ -# SDL_GPUTransferBuffer diff --git a/docs/api/c_types/SDL_Renderer.md b/docs/api/c_types/SDL_Renderer.md deleted file mode 100644 index abdcdd33..00000000 --- a/docs/api/c_types/SDL_Renderer.md +++ /dev/null @@ -1,76 +0,0 @@ -# SDL_Renderer - -## draw_color() - - -## present() - - -## clear() - - -## rect() - - -## fillrect() - - -## line() - - -## point() - - -## load_texture() - - -## texture() - - -## slice9() - - -## tile() - - -## get_image() - - -## fasttext() - - -## geometry() - - -## scale() - - -## logical_size() - - -## viewport() - - -## clip() - - -## vsync() - - -## coords() - - -## camera() - - -## get_viewport() - - -## screen2world() - - -## target() - - -## make_sprite_mesh() - diff --git a/docs/api/c_types/SDL_Surface.md b/docs/api/c_types/SDL_Surface.md deleted file mode 100644 index 52095cb4..00000000 --- a/docs/api/c_types/SDL_Surface.md +++ /dev/null @@ -1,16 +0,0 @@ -# SDL_Surface - -## blit() - - -## scale() - - -## fill() - - -## rect() - - -## dup() - diff --git a/docs/api/c_types/SDL_Texture.md b/docs/api/c_types/SDL_Texture.md deleted file mode 100644 index 1a088e3d..00000000 --- a/docs/api/c_types/SDL_Texture.md +++ /dev/null @@ -1,4 +0,0 @@ -# SDL_Texture - -## mode() - diff --git a/docs/api/c_types/SDL_Thread.md b/docs/api/c_types/SDL_Thread.md deleted file mode 100644 index 2f95dee7..00000000 --- a/docs/api/c_types/SDL_Thread.md +++ /dev/null @@ -1,4 +0,0 @@ -# SDL_Thread - -## wait() - diff --git a/docs/api/c_types/SDL_Window.md b/docs/api/c_types/SDL_Window.md deleted file mode 100644 index f82a93db..00000000 --- a/docs/api/c_types/SDL_Window.md +++ /dev/null @@ -1,40 +0,0 @@ -# SDL_Window - -## fullscreen() - - -## make_renderer() - - -## make_gpu() - - -## keyboard_shown() - - -## theme() - - -## safe_area() - - -## bordered() - - -## set_icon() - - -## get title - - -## set title() - - -## get size - - -## set size() - - -## mouse_grab() - diff --git a/docs/api/c_types/datastream.md b/docs/api/c_types/datastream.md deleted file mode 100644 index 4ccbee95..00000000 --- a/docs/api/c_types/datastream.md +++ /dev/null @@ -1,22 +0,0 @@ -# datastream - -## time() - - -## seek() - - -## advance() - - -## duration() - - -## framerate() - - -## get callback - - -## set callback() - diff --git a/docs/api/c_types/font.md b/docs/api/c_types/font.md deleted file mode 100644 index 4e7c6c89..00000000 --- a/docs/api/c_types/font.md +++ /dev/null @@ -1,19 +0,0 @@ -# font - -## get linegap - - -## set linegap() - - -## get height - - -## get ascent - - -## get descent - - -## text_size() - diff --git a/docs/api/c_types/rtree.md b/docs/api/c_types/rtree.md deleted file mode 100644 index 22138c5a..00000000 --- a/docs/api/c_types/rtree.md +++ /dev/null @@ -1,22 +0,0 @@ -# rtree - -## add() - - -## delete() - - -## query() - - -## get size - - -## forEach() - - -## has() - - -## values() - diff --git a/docs/api/c_types/sprite.md b/docs/api/c_types/sprite.md deleted file mode 100644 index 4b1f7374..00000000 --- a/docs/api/c_types/sprite.md +++ /dev/null @@ -1,22 +0,0 @@ -# sprite - -## set_affine() - - -## set_rect() - - -## set_image() - - -## get layer - - -## set layer() - - -## get color - - -## set color() - diff --git a/docs/api/c_types/timer.md b/docs/api/c_types/timer.md deleted file mode 100644 index bff21b7e..00000000 --- a/docs/api/c_types/timer.md +++ /dev/null @@ -1,13 +0,0 @@ -# timer - -## get remain - - -## set remain() - - -## get fn - - -## set fn() - diff --git a/docs/api/c_types/transform.md b/docs/api/c_types/transform.md deleted file mode 100644 index 7b8ea4d3..00000000 --- a/docs/api/c_types/transform.md +++ /dev/null @@ -1,67 +0,0 @@ -# transform - -## get pos - - -## set pos() - - -## get scale - - -## set scale() - - -## get rotation - - -## set rotation() - - -## get parent - - -## set parent() - - -## get change_hook - - -## set change_hook() - - -## trs() - - -## phys2d() - - -## move() - - -## rotate() - - -## angle() - - -## lookat() - - -## direction() - - -## unit() - - -## rect() - - -## array() - - -## torect() - - -## children() - diff --git a/docs/api/console.md b/docs/api/console.md new file mode 100644 index 00000000..b39f919e --- /dev/null +++ b/docs/api/console.md @@ -0,0 +1,37 @@ +# console + +The console object provides various logging, debugging, and output methods. + +### print + +### spam(msg) + +Output a spam-level message for very verbose logging. + +### debug(msg) + +Output a debug-level message. + +### info(msg) + +Output info level message. + +### warn(msg) + +Output warn level message. + +### log(msg) + +Output directly to in game console. + +### error(e) + +Output error level message, and print stacktrace. + +### panic(e) + +Output a panic-level message and exit the program. + +### assert(op, str = `assertion failed [value '${op}']`) + +If the condition is false, print an error and panic. diff --git a/docs/api/index.md b/docs/api/index.md deleted file mode 100644 index eaa9c015..00000000 --- a/docs/api/index.md +++ /dev/null @@ -1,3 +0,0 @@ -# Prosperon builtin modules - -Here is the scripting guide for prosperon with dull. It is split into essentially two sections: modules, and types that may be created during the course of a running program. For example, \ No newline at end of file diff --git a/docs/api/modules/actor.md b/docs/api/modules/actor.md index 50332c8a..b05ba122 100644 --- a/docs/api/modules/actor.md +++ b/docs/api/modules/actor.md @@ -1,77 +1,87 @@ # actor -# actor - A set of utilities for iterating over a hierarchy of actor-like objects, as well as managing tag-based lookups. Objects are assumed to have a "objects" property, -pointing to children or sub-objects, forming a tree. +pointing to children or sub-objects, forming a tree. -## all_objects(fn, startobj) +### all_objects(fn, startobj) + + +Iterate over each object (and its sub-objects) in the hierarchy, calling fn for each one. **fn**: A callback function that receives each object. If it returns a truthy value, iteration stops and that value is returned. **startobj**: The root object at which iteration begins, default is the global "world". + **Returns**: The first truthy value returned by fn, or undefined if none. -Iterate over each object (and its sub-objects) in the hierarchy, calling fn for each one. + +### find_object(fn, startobj) -## find_object(fn, startobj) +Intended to find a matching object within the hierarchy. **fn**: A callback or criteria to locate a particular object. **startobj**: The root object at which search begins, default "world". -**Returns**: Not yet implemented. -Intended to find a matching object within the hierarchy. +**Returns**: Not yet implemented. -## tag_add(tag, obj) +### tag_add(tag, obj) + + +Associate the given object with the specified tag. Creates a new tag set if it does not exist. **tag**: A string tag to associate with the object. **obj**: The object to add under this tag. + **Returns**: None -Associate the given object with the specified tag. Creates a new tag set if it does not exist. + +### tag_rm(tag, obj) -## tag_rm(tag, obj) +Remove the given object from the specified tag’s set, if it exists. **tag**: The tag to remove the object from. **obj**: The object to remove from the tag set. -**Returns**: None - -Remove the given object from the specified tag’s set, if it exists. - - -## tag_clear_guid(obj) - - -**obj**: The object whose tags should be cleared. **Returns**: None + +### tag_clear_guid(obj) + + Remove the object from all tag sets. -## objects_with_tag(tag) +**obj**: The object whose tags should be cleared. + + +**Returns**: None + + +### objects_with_tag(tag) + + +Retrieve all objects currently tagged with the specified tag. **tag**: A string tag to look up. -**Returns**: An array of objects associated with the given tag. -Retrieve all objects currently tagged with the specified tag. +**Returns**: An array of objects associated with the given tag. diff --git a/docs/api/modules/cmd.md b/docs/api/modules/cmd.md index 7c1cb1c6..749dd8c0 100644 --- a/docs/api/modules/cmd.md +++ b/docs/api/modules/cmd.md @@ -1 +1,3 @@ # cmd + +## cmd diff --git a/docs/api/modules/color.md b/docs/api/modules/color.md index ba278664..b0a84fac 100644 --- a/docs/api/modules/color.md +++ b/docs/api/modules/color.md @@ -1 +1,3 @@ # color + +## color diff --git a/docs/api/modules/doc.md b/docs/api/modules/doc.md index c83e3164..bc7a3359 100644 --- a/docs/api/modules/doc.md +++ b/docs/api/modules/doc.md @@ -1,9 +1,7 @@ # doc -## print_api(obj) +## doc -## print_modules() +### writeDocFile(obj, title) -## write_modules() - -## write_c_types() +Return a markdown string for a given obj, with optional title. diff --git a/docs/api/modules/draw2d.md b/docs/api/modules/draw2d.md index e1dfe7c9..aa4fd624 100644 --- a/docs/api/modules/draw2d.md +++ b/docs/api/modules/draw2d.md @@ -1,13 +1,13 @@ # draw2d -# draw2d - A collection of 2D drawing functions that operate in screen space. Provides primitives for lines, rectangles, text, sprite drawing, etc. -## point(pos, size, color) +### point(pos, size, color) + + **pos**: A 2D position ([x, y]) where the point should be drawn. @@ -16,11 +16,13 @@ for lines, rectangles, text, sprite drawing, etc. **color**: The color of the point, defaults to Color.blue. + **Returns**: None +### line(points, color, thickness, pipeline) + -## line(points, color, thickness, pipeline) **points**: An array of 2D positions representing the line vertices. @@ -31,11 +33,13 @@ for lines, rectangles, text, sprite drawing, etc. **pipeline**: (Optional) A pipeline or rendering state object. + **Returns**: None +### cross(pos, size, color, thickness, pipe) + -## cross(pos, size, color, thickness, pipe) **pos**: The center of the cross as a 2D position ([x, y]). @@ -48,11 +52,13 @@ for lines, rectangles, text, sprite drawing, etc. **pipe**: (Optional) A pipeline or rendering state object. + **Returns**: None +### arrow(start, end, color, wingspan, wingangle, pipe) + -## arrow(start, end, color, wingspan, wingangle, pipe) **start**: The start position of the arrow ([x, y]). @@ -67,11 +73,13 @@ for lines, rectangles, text, sprite drawing, etc. **pipe**: (Optional) A pipeline or rendering state object. + **Returns**: None +### rectangle(rect, color, pipeline) + -## rectangle(rect, color, pipeline) **rect**: A rectangle object with {x, y, width, height}. @@ -80,11 +88,14 @@ for lines, rectangles, text, sprite drawing, etc. **pipeline**: (Optional) A pipeline or rendering state object. + **Returns**: None +### tile(image, rect, color, tile, pipeline) -## tile(image, rect, color, tile, pipeline) + +:raises Error: If no image is provided. **image**: An image object or string path to a texture. @@ -97,14 +108,16 @@ for lines, rectangles, text, sprite drawing, etc. **pipeline**: (Optional) A pipeline or rendering state object. + **Returns**: None + +### slice9(image, rect, slice, color, info, pipeline) + + :raises Error: If no image is provided. -## slice9(image, rect, slice, color, info, pipeline) - - **image**: An image object or string path to a texture. **rect**: A rectangle specifying draw location/size, default [0, 0]. @@ -117,14 +130,16 @@ for lines, rectangles, text, sprite drawing, etc. **pipeline**: (Optional) A pipeline or rendering state object. + **Returns**: None + +### image(image, rect, rotation, color, pipeline) + + :raises Error: If no image is provided. -## image(image, rect, rotation, color, pipeline) - - **image**: An image object or string path to a texture. **rect**: A rectangle specifying draw location/size, default [0,0]; width/height default to image size. @@ -135,26 +150,29 @@ for lines, rectangles, text, sprite drawing, etc. **pipeline**: (Optional) A pipeline or rendering state object. + **Returns**: A sprite object that was created for this draw call. + +### images(image, rects, config) + + :raises Error: If no image is provided. -## images(image, rects, config) - - **image**: An image object or string path to a texture. **rects**: An array of rectangle objects ({x, y, width, height}) to draw. **config**: (Unused) Additional config data if needed. + **Returns**: An array of sprite objects created and queued for rendering. -:raises Error: If no image is provided. + +### sprites(sprites, sort, pipeline) -## sprites(sprites, sort, pipeline) **sprites**: An array of sprite objects to draw. @@ -163,11 +181,13 @@ for lines, rectangles, text, sprite drawing, etc. **pipeline**: (Optional) A pipeline or rendering state object. + **Returns**: None +### circle(pos, radius, color, inner_radius, pipeline) + -## circle(pos, radius, color, inner_radius, pipeline) **pos**: Center of the circle ([x, y]). @@ -180,11 +200,13 @@ for lines, rectangles, text, sprite drawing, etc. **pipeline**: (Optional) A pipeline or rendering state object. + **Returns**: None +### text(text, rect, font, size, color, wrap, pipeline) + -## text(text, rect, font, size, color, wrap, pipeline) **text**: The string to draw. @@ -201,6 +223,6 @@ for lines, rectangles, text, sprite drawing, etc. **pipeline**: (Optional) A pipeline or rendering state object. + **Returns**: None - diff --git a/docs/api/modules/event.md b/docs/api/modules/event.md index f1207d21..4b8275c8 100644 --- a/docs/api/modules/event.md +++ b/docs/api/modules/event.md @@ -1,21 +1,27 @@ # event -## push_event(event) +## event + +### push_event(event) Push a custom user event into SDL's queue, passing a callback function. + + **event**: A function to call when this event is consumed. + **Returns**: None - -## engine_input(callback) +### engine_input(callback) Poll all system events (keyboard, mouse, etc.) and call the given function with each event object. + + **callback**: A function that executes on each event consumed from the poll. + **Returns**: None - diff --git a/docs/api/modules/geometry.md b/docs/api/modules/geometry.md index 13dd71d4..754904a1 100644 --- a/docs/api/modules/geometry.md +++ b/docs/api/modules/geometry.md @@ -1,123 +1,139 @@ # geometry -# geometry - -A collection of geometry-related functions for circles, spheres, boxes, polygons, +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) + + +Return the intersection of two rectangles. The result may be empty if no intersection. **a**: The first rectangle as {x, y, w, h}. **b**: The second rectangle as {x, y, w, h}. + **Returns**: A rectangle that is the intersection of the two. May have zero width/height if no overlap. -Return the intersection of two rectangles. The result may be empty if no intersection. + +### rect_intersects(a, b) -## rect_intersects(a, b) **a**: Rectangle {x,y,w,h}. **b**: Rectangle {x,y,w,h}. + **Returns**: A boolean indicating whether the two rectangles overlap. +### rect_expand(a, b) -## rect_expand(a, b) + +Merge or combine two rectangles, returning their bounding rectangle. **a**: Rectangle {x,y,w,h}. **b**: Rectangle {x,y,w,h}. + **Returns**: A new rectangle that covers the bounds of both input rectangles. -Merge or combine two rectangles, returning their bounding rectangle. + +### rect_inside(inner, outer) -## rect_inside(inner, outer) **inner**: A rectangle to test. **outer**: A rectangle that may contain 'inner'. + **Returns**: True if 'inner' is completely inside 'outer', otherwise false. +### rect_random(rect) + -## rect_random(rect) **rect**: A rectangle {x,y,w,h}. + **Returns**: A random point within the rectangle (uniform distribution). +### cwh2rect(center, wh) -## cwh2rect(center, wh) + +Helper: convert a center point and width/height vector to a rect object. **center**: A 2D point [cx, cy]. **wh**: A 2D size [width, height]. + **Returns**: A rectangle {x, y, w, h} with x,y set to center and w,h set to the given size. -Helper: convert a center point and width/height vector to a rect object. + +### rect_point_inside(rect, point) -## rect_point_inside(rect, point) **rect**: A rectangle {x,y,w,h}. **point**: A 2D point [px, py]. + **Returns**: True if the point lies inside the rectangle, otherwise false. +### rect_pos(rect) + -## rect_pos(rect) **rect**: A rectangle {x,y,w,h}. + **Returns**: A 2D vector [x,y] giving the rectangle's position. +### rect_move(rect, offset) + -## rect_move(rect, offset) **rect**: A rectangle {x,y,w,h}. **offset**: A 2D vector to add to the rectangle's position. + **Returns**: A new rectangle with updated x,y offset. +### box(w, h) -## box(w, h) + +Construct a box centered at the origin with the given width and height. This overrides the box object above. **w**: The width of the box. **h**: The height of the box. + **Returns**: An array of four 2D points representing the corners of a rectangle centered at [0,0]. -Construct a box centered at the origin with the given width and height. This overrides the box object above. - - -## sphere Sphere-related geometry functions: @@ -125,16 +141,21 @@ Sphere-related geometry functions: - random(r, theta, phi): Return a random point on or inside a sphere. -### volume(r) +#### volume(r) + + **r**: The sphere radius. + **Returns**: The volume of the sphere, calculated as (4/3) * pi * r^3. +#### random(r, theta, phi) -### 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]. @@ -143,12 +164,9 @@ Sphere-related geometry functions: **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. -Generate a random point inside a sphere of variable radius, distributing angles in the specified ranges. - - -## circle Circle-related geometry functions: @@ -156,51 +174,62 @@ 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) +#### area(r) + + **r**: Radius of the circle. + **Returns**: The area, pi * r^2. +#### random(r, theta) + -### 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) -### 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. -Shortcut for geometry.arc(radius, 360, n). + +### ngon(radius, n) -## ngon(radius, n) +Generates a regular n-gon by calling geometry.arc with full 360 degrees. **radius**: The radius of the n-gon from center to each vertex. **n**: Number of sides/vertices. + **Returns**: An array of 2D points forming a regular n-gon. -Generates a regular n-gon by calling geometry.arc with full 360 degrees. + +### arc(radius, angle, n, start) -## arc(radius, angle, n, start) +Generate an arc (or partial circle) of n points, each angle spread equally over 'angle' degrees from 'start'. **radius**: The distance from center to the arc points. @@ -211,38 +240,43 @@ Generates a regular n-gon by calling geometry.arc with full 360 degrees. **start**: Starting angle (in degrees), default 0. + **Returns**: An array of 2D points along the arc. -Generate an arc (or partial circle) of n points, each angle spread equally over 'angle' degrees from 'start'. + +### corners2points(ll, ur) -## corners2points(ll, ur) +Similar to box.points, but calculates differently. **ll**: Lower-left 2D coordinate. **ur**: Upper-right 2D coordinate (relative offset in x,y). + **Returns**: A four-point array of corners [ll, lower-right, upper-right, upper-left]. -Similar to box.points, but calculates differently. +### sortpointsccw(points) -## sortpointsccw(points) - - -**points**: An array of 2D points. - -**Returns**: A new array of the same points, sorted counterclockwise around their centroid. Sort an array of points in CCW order based on their angles from the centroid. -## points2cm(points) +**points**: An array of 2D points. + + +**Returns**: A new array of the same points, sorted counterclockwise around their centroid. + + +### points2cm(points) + + **points**: An array of 2D points. + **Returns**: The centroid (average x,y) of the given points. - diff --git a/docs/api/modules/graphics.md b/docs/api/modules/graphics.md index aaec336a..0b99ca6a 100644 --- a/docs/api/modules/graphics.md +++ b/docs/api/modules/graphics.md @@ -1,25 +1,29 @@ # graphics -# graphics - -Provides functionality for loading and managing images, fonts, textures, and sprite meshes. -Includes both JavaScript and C-implemented routines for creating geometry buffers, performing +Provides functionality for loading and managing images, fonts, textures, and sprite meshes. +Includes both JavaScript and C-implemented routines for creating geometry buffers, performing rectangle packing, etc. -## make_sprite_mesh(sprites) +### make_sprite_mesh(sprites) + + +:param oldMesh (optional): An existing mesh object to reuse/resize if possible. +Given an array of sprites, build a single geometry mesh for rendering them. **sprites**: An array of sprite objects, each containing .rect (or transform), .src (UV region), .color, etc. -:param oldMesh (optional): An existing mesh object to reuse/resize if possible. + **Returns**: A GPU mesh object with pos, uv, color, and indices buffers for all sprites. -Given an array of sprites, build a single geometry mesh for rendering them. + +### make_sprite_queue(sprites, camera, pipeline, sort) -## make_sprite_queue(sprites, camera, pipeline, sort) +Given an array of sprites, optionally sort them, then build a queue of pipeline commands. +Each group with a shared image becomes one command. **sprites**: An array of sprite objects. @@ -30,13 +34,14 @@ Given an array of sprites, build a single geometry mesh for rendering them. **sort**: An integer or boolean for whether to sort sprites; if truthy, sorts by layer & texture. + **Returns**: An array of pipeline commands: geometry with mesh references, grouped by image. -Given an array of sprites, optionally sort them, then build a queue of pipeline commands. -Each group with a shared image becomes one command. + +### make_text_buffer(text, rect, angle, color, wrap, font) -## make_text_buffer(text, rect, angle, color, wrap, font) +Generate a GPU buffer mesh of text quads for rendering with a font, etc. **text**: The string to render. @@ -51,12 +56,14 @@ Each group with a shared image becomes one command. **font**: A font object created by graphics.make_font or graphics.get_font. + **Returns**: A geometry buffer mesh (pos, uv, color, indices) for rendering text. -Generate a GPU buffer mesh of text quads for rendering with a font, etc. + +### rectpack(width, height, sizes) -## rectpack(width, height, sizes) +Perform a rectangle packing using the stbrp library. Return positions for each rect. **width**: The width of the area to pack into. @@ -65,113 +72,133 @@ Generate a GPU buffer mesh of text quads for rendering with a font, etc. **sizes**: An array of [w,h] pairs for the rectangles to pack. + **Returns**: An array of [x,y] coordinates placing each rect, or null if they don't fit. -Perform a rectangle packing using the stbrp library. Return positions for each rect. +### make_rtree -## make_rtree() - - -**Returns**: An R-Tree object for quickly querying many rectangles or sprite bounds. Create a new R-Tree for geometry queries. -## make_texture(data) +**Returns**: An R-Tree object for quickly querying many rectangles or sprite bounds. -**data**: Raw image bytes (PNG, JPG, etc.) as an ArrayBuffer. +### make_texture(data) -**Returns**: An SDL_Surface object representing the decoded image in RAM, for use with GPU or software rendering. Convert raw image bytes into an SDL_Surface object. -## make_gif(data) +**data**: Raw image bytes (PNG, JPG, etc.) as an ArrayBuffer. -**data**: An ArrayBuffer containing GIF data. +**Returns**: An SDL_Surface object representing the decoded image in RAM, for use with GPU or software rendering. + + +### make_gif(data) -**Returns**: An object with frames[], each frame having its own .surface. Some also have a .texture for GPU use. Load a GIF, returning its frames. If it's a single-frame GIF, the result may have .surface only. -## make_aseprite(data) +**data**: An ArrayBuffer containing GIF data. -**data**: An ArrayBuffer containing Aseprite (ASE) file data. +**Returns**: An object with frames[], each frame having its own .surface. Some also have a .texture for GPU use. + + +### make_aseprite(data) -**Returns**: An object containing frames or animations, each with .surface. May also have top-level .surface for a single-layer case. Load an Aseprite/ASE file from an array of bytes, returning frames or animations. -## cull_sprites(sprites, camera) +**data**: An ArrayBuffer containing Aseprite (ASE) file data. + + +**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) + + +Filter an array of sprites to only those visible in the provided camera’s view. **sprites**: An array of sprite objects (each has rect or transform). **camera**: A camera or bounding rectangle defining the view area. + **Returns**: A new array of sprites that are visible in the camera's view. -Filter an array of sprites to only those visible in the provided camera’s view. + +### rects_to_sprites(rects, image) -## rects_to_sprites(rects, image) +Convert an array of rect coords into sprite objects referencing a single image. **rects**: An array of rect coords or objects. **image**: An image object (with .texture). + **Returns**: An array of sprite objects referencing the 'image' and each rect for UV or position. -Convert an array of rect coords into sprite objects referencing a single image. + +### make_surface(dimensions) -## make_surface(dimensions) +Create a blank surface in RAM. **dimensions**: The size object {width, height}, or an array [w,h]. + **Returns**: A blank RGBA surface with the given dimensions, typically for software rendering or icons. -Create a blank surface in RAM. + +### make_cursor(opts) -## make_cursor(opts) **opts**: An object with {surface, hotx, hoty} or similar. + **Returns**: An SDL_Cursor object referencing the given surface for a custom mouse cursor. +### make_font(data, size) -## make_font(data, size) + +Load a font from TTF/OTF data at the given size. **data**: TTF/OTF file data as an ArrayBuffer. **size**: Pixel size for rendering glyphs. + **Returns**: A font object with surface, texture, and glyph data, for text rendering with make_text_buffer. -Load a font from TTF/OTF data at the given size. + +### make_sprite -## make_sprite() +Create a new sprite object, storing default properties. **Returns**: A new sprite object, which typically has .rect, .color, .layer, .image, etc. -Create a new sprite object, storing default properties. + +### make_line_prim(points, thickness, startCap, endCap, color) -## make_line_prim(points, thickness, startCap, endCap, color) +Build a GPU mesh representing a thick polyline from an array of points, using parsl or a similar library under the hood. **points**: An array of [x,y] points forming the line. @@ -184,59 +211,68 @@ Create a new sprite object, storing default properties. **color**: A color to apply to the line. + **Returns**: A geometry mesh object suitable for rendering the line via a pipeline command. -Build a GPU mesh representing a thick polyline from an array of points, using parsl or a similar library under the hood. + +### is_image(obj) -## is_image(obj) **obj**: An object to check. + **Returns**: True if 'obj' has a .texture and a .rect property, indicating it's an image object. +### texture(path) -## texture(path) - - -**path**: A string path to an image file or an already-loaded image object. - -**Returns**: An image object with {surface, texture, frames?, etc.} depending on the format. Load or retrieve a cached image, converting it into a GPU texture. If 'path' is already an object, it’s returned directly. -## tex_hotreload(file) +**path**: A string path to an image file or an already-loaded image object. + + +**Returns**: An image object with {surface, texture, frames?, etc.} depending on the format. + + +### tex_hotreload(file) + + +Reload the image for the given file, updating the cached copy in memory and GPU. **file**: The file path that was changed on disk. + **Returns**: None -Reload the image for the given file, updating the cached copy in memory and GPU. + +### get_font(path, size) -## get_font(path, size) +Load a font from file if not cached, or retrieve from cache if already loaded. **path**: A string path to a font file, optionally with ".size" appended. **size**: Pixel size of the font, if not included in 'path'. + **Returns**: A font object with .surface and .texture for rendering text. -Load a font from file if not cached, or retrieve from cache if already loaded. + +### queue_sprite_mesh(queue) -## queue_sprite_mesh(queue) +Builds a single geometry mesh for all sprite-type commands in the queue, storing first_index/num_indices +so they can be rendered in one draw call. **queue**: An array of draw commands, some of which are {type:'sprite'} objects. + **Returns**: An array of references to GPU buffers [pos,uv,color,indices]. -Builds a single geometry mesh for all sprite-type commands in the queue, storing first_index/num_indices -so they can be rendered in one draw call. - diff --git a/docs/api/modules/imgui.md b/docs/api/modules/imgui.md index b00474ac..7dab89df 100644 --- a/docs/api/modules/imgui.md +++ b/docs/api/modules/imgui.md @@ -1 +1,3 @@ # imgui + +## imgui diff --git a/docs/api/modules/input.md b/docs/api/modules/input.md index 0c2a27fa..b6947eac 100644 --- a/docs/api/modules/input.md +++ b/docs/api/modules/input.md @@ -1,70 +1,82 @@ # input -## mouse_show(show) +## input + +### mouse_show(show) Show or hide the mouse cursor. Pass true to show, false to hide. + + **show**: Boolean. True to show, false to hide. + **Returns**: None - -## mouse_lock(lock) +### mouse_lock(lock) Capture or release the mouse, confining it within the window if locked. + + **lock**: Boolean. True to lock, false to unlock. + **Returns**: None - -## cursor_set(cursor) +### cursor_set(cursor) Set the given cursor (created by os.make_cursor) as the active mouse cursor. + + **cursor**: The cursor to set. + **Returns**: None - -## keyname(keycode) +### keyname(keycode) Given a numeric keycode, return the corresponding key name (e.g., from SDL). + + **keycode**: A numeric SDL keycode. + **Returns**: A string with the key name. - -## keymod() +### keymod Return an object describing the current modifier keys, e.g. {shift:true, ctrl:true}. + + **Returns**: An object with boolean fields for each modifier key. - -## mousestate() +### mousestate Return an object describing the current mouse state, including x,y coordinates and booleans for pressed buttons (left, middle, right, x1, x2). + + **Returns**: Object { x, y, left, middle, right, x1, x2 } +### print_pawn_kbm(pawn) -## print_pawn_kbm(pawn) +### procdown -## procdown() +### print_md_kbm(pawn) -## print_md_kbm(pawn) +### has_bind(pawn, bind) -## has_bind(pawn, bind) +### tabcomplete(val, list) -## tabcomplete(val, list) - -## do_uncontrol(pawn) +### do_uncontrol(pawn) diff --git a/docs/api/modules/io.md b/docs/api/modules/io.md index 50bf1ef9..b2761e32 100644 --- a/docs/api/modules/io.md +++ b/docs/api/modules/io.md @@ -1,49 +1,59 @@ # io -## rm(path) +## io + +### rm(path) Remove the file or empty directory at the given path. + + **path**: The file or empty directory to remove. Must be empty if a directory. + **Returns**: None - -## mkdir(path) +### mkdir(path) Create a directory at the given path. + + **path**: The directory path to create. + **Returns**: None - -## stat(path) +### stat(path) 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. + + **path**: The file or directory to retrieve metadata for. + **Returns**: An object with metadata (filesize, modtime, createtime, accesstime). - -## globfs(patterns) +### globfs(patterns) 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 "ignore" rule, similar to .gitignore usage. + + **patterns**: An array of glob patterns to ignore. Any file matching one of these is skipped. + **Returns**: An array of matching file paths. - -## match(pattern, string) +### match(pattern, string) Return boolean indicating whether the given wildcard pattern matches the provided string. Dots must match dots. Case is not ignored. @@ -57,149 +67,174 @@ Patterns can incorporate: '\' - Backslash escapes the next character. '!' - If placed immediately inside brackets (like [!abc]), it negates the set. + + **pattern**: The wildcard pattern to compare. **string**: The string to test against the wildcard pattern. + **Returns**: True if matched, otherwise false. - -## exists(path) +### exists(path) Return a boolean indicating whether the file or directory at the given path exists. + + **path**: The file or directory path to check. + **Returns**: True if the path exists, otherwise false. - -## mount(archiveOrDir, mountPoint) +### mount(archiveOrDir, mountPoint) Mount a directory or archive at the specified mount point. An undefined mount point mounts to '/'. Throw on error. + + **archiveOrDir**: The directory or archive to mount. **mountPoint**: The path at which to mount. If omitted or undefined, '/' is used. + **Returns**: None - -## unmount(path) +### unmount(path) Unmount a previously mounted directory or archive. Throw on error. + + **path**: The directory or archive mount point to unmount. + **Returns**: None - -## slurp(path) +### slurp(path) Read the entire file at the given path as a string. Throw on error. + + **path**: The file path to read from. + **Returns**: A string with the file’s contents. - -## slurpbytes(path) +### slurpbytes(path) Read the entire file at the given path as a raw ArrayBuffer. Throw on error. + + **path**: The file path to read from. + **Returns**: An ArrayBuffer containing the file’s raw bytes. - -## slurpwrite(data, path) +### slurpwrite(data, path) Write data (string or ArrayBuffer) to the given file path. Overwrite if it exists. Throw on error. + + **data**: The data to write (string or ArrayBuffer). **path**: The file path to write to. + **Returns**: None - -## writepath(path) +### writepath(path) Set the write directory. Subsequent writes will go here by default. Throw on error. + + **path**: The directory path to set as writable. + **Returns**: None - -## basedir() +### basedir Return the application's base directory (where the executable is located). + + **Returns**: A string with the base directory path. - -## userdir() +### userdir Return the user's directory, often used for saving data. + + **Returns**: A string with the user's directory path. - -## realdir(path) +### realdir(path) Return the actual, real directory (on the host filesystem) that contains the given file path. Return undefined if not found. + + **path**: The file path whose real directory is requested. + **Returns**: A string with the real directory path, or undefined. - -## open(path) +### open(path) Open a file for writing, returning a file object that can be used for further operations. Throw on error. + + **path**: The file path to open for writing. + **Returns**: A file object for subsequent write operations. - -## searchpath() +### searchpath 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) Return an array of files within the given directory, optionally recursing into subdirectories. + + **path**: The directory to list. **recurse**: Whether to recursively include subdirectories (true or false). + **Returns**: An array of file (and directory) paths found. +### mount_core -## mount_core() - -## is_directory() +### is_directory diff --git a/docs/api/modules/js.md b/docs/api/modules/js.md index 3e5c2696..66039d6f 100644 --- a/docs/api/modules/js.md +++ b/docs/api/modules/js.md @@ -1,156 +1,175 @@ # js -# js - 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) -**callback**: A function to call each time QuickJS completes a "cycle" (internal VM loop), - - or undefined to remove the callback. -**Returns**: None - +or undefined to remove the callback. Register or remove a hook function that QuickJS calls once per execution cycle. If the callback is set, it receives a single argument (an optional object/value describing the cycle). If callback is undefined, the hook is removed. -## dump_shapes() +**callback**: A function to call each time QuickJS completes a "cycle" (internal VM loop), -**Returns**: A debug string describing the internal shape hierarchy used by QuickJS. +**Returns**: None + + +### dump_shapes + Use this for internal debugging of object shapes. -## dump_atoms() +**Returns**: A debug string describing the internal shape hierarchy used by QuickJS. -**Returns**: A debug string listing all currently registered atoms (internal property keys/symbols) +### dump_atoms + known by QuickJS. Helpful for diagnosing memory usage or potential key collisions. -## dump_class() +**Returns**: A debug string listing all currently registered atoms (internal property keys/symbols) -**Returns**: A debug string describing the distribution of JS object classes in the QuickJS runtime. +### dump_class + Shows how many objects of each class exist, useful for advanced memory or performance profiling. -## dump_objects() +**Returns**: A debug string describing the distribution of JS object classes in the QuickJS runtime. -**Returns**: A debug string listing certain internal QuickJS objects and their references, +### dump_objects + useful for debugging memory leaks or object lifetimes. -## dump_type_overheads() +**Returns**: A debug string listing certain internal QuickJS objects and their references, -**Returns**: A debug string describing the overheads for various JS object types in QuickJS. +### dump_type_overheads + Displays memory usage breakdown for different internal object types. -## stack_info() +**Returns**: A debug string describing the overheads for various JS object types in QuickJS. -**Returns**: An object or string describing the runtime's current stack usage and capacity. +### stack_info + Internal debugging utility to examine call stack details. -## calc_mem(value) +**Returns**: An object or string describing the runtime's current stack usage and capacity. -**value**: A JavaScript value to analyze. +### calc_mem(value) -**Returns**: Approximate memory usage (in bytes) of that single value. Compute the approximate size of a single JS value in memory. This is a best-effort estimate. -## mem() +**value**: A JavaScript value to analyze. -**Returns**: An object containing a comprehensive snapshot of memory usage for the current QuickJS runtime, +**Returns**: Approximate memory usage (in bytes) of that single value. - including total allocated bytes, object counts, and more. + +### mem + + +including total allocated bytes, object counts, and more. Retrieve an overview of the runtime’s memory usage. -## mem_limit(bytes) +**Returns**: An object containing a comprehensive snapshot of memory usage for the current QuickJS runtime, -**bytes**: The maximum memory (in bytes) QuickJS is allowed to use. +### mem_limit(bytes) -**Returns**: None Set the upper memory limit for the QuickJS runtime. Exceeding this limit may cause operations to fail or throw errors. -## gc_threshold(bytes) +**bytes**: The maximum memory (in bytes) QuickJS is allowed to use. -**bytes**: The threshold (in bytes) at which the engine triggers automatic garbage collection. - **Returns**: None +### gc_threshold(bytes) + + + Set the threshold (in bytes) for QuickJS to perform an automatic GC pass when memory usage surpasses it. -## max_stacksize(bytes) +**bytes**: The threshold (in bytes) at which the engine triggers automatic garbage collection. -**bytes**: The maximum allowed stack size (in bytes) for QuickJS. - **Returns**: None +### max_stacksize(bytes) + + + Set the maximum stack size for QuickJS. If exceeded, the runtime may throw a stack overflow error. -## memstate() - - -**Returns**: A simpler memory usage object (malloc sizes, etc.) for the QuickJS runtime. - - -Gives a quick overview of the memory usage, including malloc size and other allocations. - - -## gc() +**bytes**: The maximum allowed stack size (in bytes) for QuickJS. **Returns**: None +### memstate + + + +Gives a quick overview of the memory usage, including malloc size and other allocations. + + +**Returns**: A simpler memory usage object (malloc sizes, etc.) for the QuickJS runtime. + + +### gc + + + Force an immediate, full garbage collection pass, reclaiming unreachable memory. -## eval(src, filename) +**Returns**: None + + +### eval(src, filename) + + + +Execute a string of JavaScript code in the current QuickJS context. **src**: A string of JavaScript source code to evaluate. **filename**: (Optional) A string for the filename or label, used in debugging or stack traces. + **Returns**: The result of evaluating the given source code. - -Execute a string of JavaScript code in the current QuickJS context. - diff --git a/docs/api/modules/json.md b/docs/api/modules/json.md index 6718cf05..a825b701 100644 --- a/docs/api/modules/json.md +++ b/docs/api/modules/json.md @@ -1,6 +1,8 @@ # json -## encode(val,space,replacer,whitelist) +## json + +### encode(val,space,replacer,whitelist) 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. @@ -8,7 +10,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) The text text is parsed, and the resulting value (usually a record or an array) is returned. diff --git a/docs/api/modules/loop.md b/docs/api/modules/loop.md index 56ba3262..26c51f4f 100644 --- a/docs/api/modules/loop.md +++ b/docs/api/modules/loop.md @@ -1,3 +1,5 @@ # loop -## step() +## loop + +### step diff --git a/docs/api/modules/math.md b/docs/api/modules/math.md index e1093c7e..e248d112 100644 --- a/docs/api/modules/math.md +++ b/docs/api/modules/math.md @@ -1,113 +1,115 @@ # math -## dot() +## math + +### dot Compute the dot product between two numeric arrays, returning a scalar. Extra elements are ignored. -## project() +### project Project one vector onto another, returning a new array of the same dimension. -## rotate() +### rotate Rotate a 2D point (or array of length 2) by the given angle (in turns) around an optional pivot. -## midpoint() +### midpoint Compute the midpoint of two arrays of numbers. Only the first two entries are used if 2D is intended. -## reflect() +### reflect Reflect a vector across a plane normal. Both arguments must be numeric arrays. -## distance() +### distance Compute the Euclidean distance between two numeric arrays of matching length. -## direction() +### direction Compute the normalized direction vector from the first array to the second. -## angle() +### angle Given a 2D vector, return its angle from the X-axis in radians or some chosen units. -## norm() +### norm Return a normalized copy of the given numeric array. For 2D/3D/4D or arbitrary length. -## angle_between() +### angle_between Compute the angle between two vectors (2D/3D/4D). -## lerp() +### lerp Linear interpolation between two numbers: lerp(a, b, t). -## gcd() +### gcd Compute the greatest common divisor of two integers. -## lcm() +### lcm Compute the least common multiple of two integers. -## clamp() +### clamp Clamp a number between low and high. clamp(value, low, high). -## angledist() +### angledist Compute the signed distance between two angles in 'turn' units, e.g. 0..1 range. -## jitter() +### jitter Apply a random +/- percentage noise to a number. Example: jitter(100, 0.05) -> ~95..105. -## mean() +### mean Compute the arithmetic mean of an array of numbers. -## sum() +### sum Sum all elements of an array of numbers. -## sigma() +### sigma Compute standard deviation of an array of numbers. -## median() +### median Compute the median of an array of numbers. -## length() +### length Return the length of a vector (i.e. sqrt of sum of squares). -## from_to() +### from_to Return an array of points from a start to an end, spaced out by a certain distance. -## rand() +### rand Return a random float in [0,1). -## randi() +### randi Return a random 32-bit integer. -## srand() +### srand Seed the random number generator with the given integer, or with current time if none. -## deg2rad(deg) +### deg2rad(deg) -## rad2deg(rad) +### rad2deg(rad) -## turn2rad(x) +### turn2rad(x) -## rad2turn(x) +### rad2turn(x) -## turn2deg(x) +### turn2deg(x) -## deg2turn(x) +### deg2turn(x) diff --git a/docs/api/modules/miniz.md b/docs/api/modules/miniz.md index 0ef27b2b..31685e10 100644 --- a/docs/api/modules/miniz.md +++ b/docs/api/modules/miniz.md @@ -1 +1,3 @@ # miniz + +## miniz diff --git a/docs/api/modules/os.md b/docs/api/modules/os.md index 130306fa..06811325 100644 --- a/docs/api/modules/os.md +++ b/docs/api/modules/os.md @@ -1,101 +1,103 @@ # os -## make_transform() +## os + +### make_transform Create a new transform object that can be used for 2D/3D positioning, scaling, and rotation. -## clean_transforms() +### clean_transforms Force an update on all transforms to remove dangling references or perform house-keeping. -## platform() +### platform Return a string with the underlying platform name, like 'Windows', 'Linux', or 'macOS'. -## arch() +### arch Return the CPU architecture string for this system (e.g. 'x64', 'arm64'). -## totalmem() +### totalmem Return the total system RAM in bytes. -## freemem() +### freemem Return the amount of free system RAM in bytes, if known. -## hostname() +### hostname Return the system's hostname, or an empty string if not available. -## version() +### version Return the OS or kernel version string, if the platform provides it. -## kill() +### kill Send a signal (e.g., 'SIGINT', 'SIGTERM', etc.) to the current process. -## exit() +### exit Exit the application with the specified exit code. -## now() +### now Return current time (in seconds as a float) with high resolution. -## openurl() +### openurl Open the provided URL in the default web browser, if possible. -## make_timer() +### make_timer Create a new timer object that will call a specified function after a certain delay. -## update_timers() +### update_timers Advance all timers by the provided time delta (in seconds). -## sleep() +### sleep Block execution for the specified number of seconds. -## battery_pct() +### battery_pct Return the battery level (percentage) or negative if unknown. -## battery_voltage() +### battery_voltage Return the current battery voltage in volts, if available. -## battery_seconds() +### battery_seconds Return the estimated remaining battery time in seconds, or negative if unknown. -## power_state() +### power_state Return a string describing power status: 'on battery', 'charging', 'charged', etc. -## on() +### on Register a global callback for certain engine-wide or system-level events. -## rt_info() +### rt_info Return internal QuickJS runtime info, such as object counts. -## rusage() +### rusage Return resource usage stats for this process, if the platform supports it. -## mallinfo() +### mallinfo Return detailed memory allocation info (arena size, free blocks, etc.) on some platforms. -## env() +### env Fetch the value of a given environment variable, or undefined if it doesn't exist. -## system() +### system Execute a shell command using the system() call. Returns the command's exit code. diff --git a/docs/api/modules/packer.md b/docs/api/modules/packer.md index 6bf632a5..77c49bf9 100644 --- a/docs/api/modules/packer.md +++ b/docs/api/modules/packer.md @@ -1 +1,46 @@ # packer + +## packer + +### getAllFiles(dir) + + +Return a list of all files in the given directory that are not matched by .prosperonignore, +skipping directories. + + + +**dir**: The directory to search. + + +**Returns**: An array of file paths found. + + +### gatherStats(filePaths) + + +Analyze a list of files and categorize them as modules, programs, images, or other. + + + +**filePaths**: An array of file paths to analyze. + + +**Returns**: An object { modules, programs, images, other, total } with counts. + + +### pack(dir, outPath) + + +Create a ZIP archive of all files (skipping those matched by .prosperonignore) in the +specified directory and write it to outPath. This uses the miniz module. + + + +**dir**: The directory to zip. + +**outPath**: The path (including filename) for the resulting ZIP file. + + +**Returns**: None (synchronous). Throws an Error if the directory does not exist. + diff --git a/docs/api/modules/render.md b/docs/api/modules/render.md index a6f707af..abdc94ee 100644 --- a/docs/api/modules/render.md +++ b/docs/api/modules/render.md @@ -1,29 +1,42 @@ # render -### present() +## render + +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 +### stencil_writer(...args) -## stencil_writer(...args) - -## fillmask(ref) +### fillmask(ref) Draw a fullscreen shape using a 'screenfill' shader to populate the stencil buffer with a given reference. + + **ref**: The stencil reference value to write. + **Returns**: None - -## mask(image, pos, scale, rotation, ref) +### mask(image, pos, scale, rotation, ref) Draw an image to the stencil buffer, marking its area with a specified reference value. + + **image**: A texture or string path (which is converted to a texture). **pos**: The translation (x, y) for the image placement. @@ -34,52 +47,60 @@ Draw an image to the stencil buffer, marking its area with a specified reference **ref**: The stencil reference value to write. + **Returns**: None - -## viewport(rect) +### viewport(rect) Set the GPU viewport to the specified rectangle. + + **rect**: A rectangle [x, y, width, height]. + **Returns**: None - -## scissor(rect) +### scissor(rect) Set the GPU scissor region to the specified rectangle (alias of render.viewport). + + **rect**: A rectangle [x, y, width, height]. + **Returns**: None - -## queue(cmd) +### queue(cmd) Enqueue one or more draw commands. These commands are batched until render_camera is called. + + **cmd**: Either a single command object or an array of command objects. + **Returns**: None - -## setup_draw() +### setup_draw Switch the current queue to the primary scene render queue, then invoke 'prosperon.draw' if defined. + + **Returns**: None - -## setup_hud() +### setup_hud Switch the current queue to the HUD render queue, then invoke 'prosperon.hud' if defined. + + **Returns**: None - diff --git a/docs/api/modules/resources.md b/docs/api/modules/resources.md index e402537b..2cb3ce69 100644 --- a/docs/api/modules/resources.md +++ b/docs/api/modules/resources.md @@ -1,52 +1,60 @@ # resources -## canonical(file) +## resources -## find_image(...args) +### canonical(file) -## find_sound(...args) +### find_image(...args) -## find_script(...args) +### find_sound(...args) -## find_font(...args) +### find_script(...args) -## getAllFiles(dir) +### find_font(...args) + +### getAllFiles(dir) Return a list of recognized files in the given directory that are not matched by .prosperonignore, skipping directories. Recognized extensions include scripts, images, sounds, fonts, and libs. + + **dir**: The directory to search. + **Returns**: An array of recognized file paths. - -## gatherStats(filePaths) +### gatherStats(filePaths) Analyze a list of recognized files and categorize them by scripts, images, sounds, fonts, libs, or other. Return a stats object with these counts and the total. + + **filePaths**: An array of file paths to analyze. + **Returns**: { scripts, images, sounds, fonts, lib, other, total } - -## pack(dir, outPath) +### pack(dir, outPath) Create a ZIP archive of all recognized files (skipping those matched by .prosperonignore) in the specified directory and write it to outPath. Recognized extensions are scripts, images, sounds, fonts, or libs. +:raises Error: If the directory does not exist. + + **dir**: The directory to zip. **outPath**: The path (including filename) for the resulting ZIP file. + **Returns**: None -:raises Error: If the directory does not exist. - diff --git a/docs/api/modules/sound.md b/docs/api/modules/sound.md index b0e60db9..09344755 100644 --- a/docs/api/modules/sound.md +++ b/docs/api/modules/sound.md @@ -1,9 +1,11 @@ # sound -## pcm(file) +## sound -## play(file) +### pcm(file) -## cry(file) +### play(file) -## music(file, fade = 0.5) +### cry(file) + +### music(file, fade = 0.5) diff --git a/docs/api/modules/spline.md b/docs/api/modules/spline.md index 8a4553b5..9d3c069a 100644 --- a/docs/api/modules/spline.md +++ b/docs/api/modules/spline.md @@ -1,9 +1,11 @@ # spline -## catmull() +## spline + +### catmull Perform Catmull-Rom spline sampling on an array of 2D points, returning an array of samples. -## bezier() +### bezier Perform a Bezier spline (or catmull) sampling on 2D points, returning an array of sampled points. diff --git a/docs/api/modules/time.md b/docs/api/modules/time.md index 075f96fd..650adb6c 100644 --- a/docs/api/modules/time.md +++ b/docs/api/modules/time.md @@ -1,57 +1,55 @@ # time -# time - The main time object, handling date/time utilities in earth-seconds. -## now() +### now Return the current system time in seconds (implemented in C extension). -## computer_dst() +### computer_dst Return true if local system time is currently in DST (implemented in C extension). -## computer_zone() +### computer_zone Return local time zone offset from UTC in hours (implemented in C extension). -## hour2minute() +### hour2minute Return the ratio of hour to minute in seconds, e.g. 3600 / 60 => 60. -## day2hour() +### day2hour Return the ratio of day to hour in seconds, e.g. 86400 / 3600 => 24. -## minute2second() +### minute2second Return the ratio of minute to second in seconds, e.g. 60 / 1 => 60. -## week2day() +### week2day Return the ratio of week to day in seconds, e.g. 604800 / 86400 => 7. -## isleap(year) +### isleap(year) Return true if a given year is leap, based on whether it has 366 days. -## yearsize(y) +### yearsize(y) Given a year, return 365 or 366 depending on leap-year rules. -## timecode(t, fps = 24) +### timecode(t, fps = 24) Convert seconds into a "S:frames" timecode string, with optional FPS (default 24). -## record(num, zone = this.computer_zone() +### record(num, zone = this.computer_zone() Convert a timestamp (in seconds) into a record with fields like day, month, year, etc. -## number(rec) +### number(rec) Convert a record back into a numeric timestamp (seconds). -## text(num, fmt = this.fmt, zone) +### text(num, fmt = this.fmt, zone) Format a numeric or record time into a string using a format pattern, e.g. 'hh:nn:ss'. diff --git a/docs/api/modules/tween.md b/docs/api/modules/tween.md index b390d72c..967dc0a3 100644 --- a/docs/api/modules/tween.md +++ b/docs/api/modules/tween.md @@ -1,6 +1,6 @@ # tween -## Tween +## tween An object providing methods to create and control tweens with additional features @@ -13,20 +13,18 @@ Methods: - make: Alias of start. -### start(obj, target, tvals, options) +#### start(obj, target, tvals, options) Alias of Tween.start. See Tween.start for usage details. -### make(obj, target, tvals, options) +#### make(obj, target, tvals, options) Alias of Tween.start. See Tween.start for usage details. -## Ease - This object provides multiple easing functions that remap a 0..1 input to produce a smoothed or non-linear output. They can be used standalone or inside tweens. @@ -46,15 +44,21 @@ Available functions: All easing functions expect t in [0..1] and return a remapped value in [0..1]. -### linear(t) +#### linear(t) -### in(t) +#### in(t) -### out(t) +#### out(t) -### inout(t) +#### inout(t) -## tween(from, to, time, fn, cb) +### tween(from, to, time, fn, cb) + + + +Creates a simple tween that linearly interpolates from "from" to "to" over "time" +and calls "fn" with each interpolated value. Once finished, "fn" is called with "to", +then "cb" is invoked if provided, and the tween is cleaned up. **from**: The starting object or value to interpolate from. @@ -67,10 +71,6 @@ All easing functions expect t in [0..1] and return a remapped value in [0..1]. **cb**: (Optional) A callback invoked once the tween completes. + **Returns**: A function that, when called, cleans up and stops the tween. - -Creates a simple tween that linearly interpolates from "from" to "to" over "time" -and calls "fn" with each interpolated value. Once finished, "fn" is called with "to", -then "cb" is invoked if provided, and the tween is cleaned up. - diff --git a/docs/api/modules/util.md b/docs/api/modules/util.md index 68b3a27a..c0a363a6 100644 --- a/docs/api/modules/util.md +++ b/docs/api/modules/util.md @@ -1,56 +1,65 @@ # util -# util - A collection of general-purpose utility functions for object manipulation, merging, deep copying, safe property access, etc. -## guid() +### guid -**Returns**: A random 32-character string (hex). - Return a random 32-character hexadecimal UUID-like string (not guaranteed RFC4122-compliant). -## insertion_sort(arr, cmp) +**Returns**: A random 32-character string (hex). + + +### insertion_sort(arr, cmp) + + +In-place insertion sort of an array using cmp(a,b)->Number for ordering. **arr**: The array to be sorted in-place. **cmp**: Comparison function cmp(a,b)->Number. + **Returns**: The same array, sorted in-place. -In-place insertion sort of an array using cmp(a,b)->Number for ordering. +### deepfreeze(obj) -## deepfreeze(obj) - - -**obj**: The object to recursively freeze. - -**Returns**: None Recursively freeze an object and all of its nested objects so they cannot be modified. -## dainty_assign(target, source) +**obj**: The object to recursively freeze. + + +**Returns**: None + + +### dainty_assign(target, source) + + +Copy non-function properties from source into matching keys of target without overwriting +keys that don't exist in target. Arrays are deep-copied, and objects are recursively assigned. **target**: The target object whose keys may be updated. **source**: The source object containing new values. + **Returns**: None -Copy non-function properties from source into matching keys of target without overwriting -keys that don't exist in target. Arrays are deep-copied, and objects are recursively assigned. + +### get(obj, path, defValue) -## get(obj, path, defValue) +Safely retrieve a nested property from obj at path (array or dot-string). +Returns defValue if the property is undefined. **obj**: The object to traverse. @@ -59,23 +68,27 @@ keys that don't exist in target. Arrays are deep-copied, and objects are recursi **defValue**: The default value if the property is undefined. + **Returns**: The nested property or defValue. -Safely retrieve a nested property from obj at path (array or dot-string). -Returns defValue if the property is undefined. +### isEmpty(o) -## isEmpty(o) - - -**o**: The object to check. - -**Returns**: Boolean indicating if the object is empty. Return true if the object has no own properties, otherwise false. -## dig(obj, path, def) +**o**: The object to check. + + +**Returns**: Boolean indicating if the object is empty. + + +### dig(obj, path, def) + + +Ensure a nested path of objects exists inside obj; create objects if missing, and set +the final path component to def. **obj**: The root object to modify. @@ -84,26 +97,30 @@ Return true if the object has no own properties, otherwise false. **def**: The value to store in the final path component, default {}. + **Returns**: The assigned final value. -Ensure a nested path of objects exists inside obj; create objects if missing, and set -the final path component to def. + +### access(obj, name) -## access(obj, name) +Traverse obj by dot-separated path name, returning the final value or undefined +if any step is missing. **obj**: The object to traverse. **name**: A dot-string path (e.g. "foo.bar.baz"). + **Returns**: The value at that path, or undefined if missing. -Traverse obj by dot-separated path name, returning the final value or undefined -if any step is missing. + +### mergekey(o1, o2, k) -## mergekey(o1, o2, k) +Helper for merge, updating key k from o2 into o1. Arrays are deep-copied and objects are +recursively merged. **o1**: The target object. @@ -112,38 +129,44 @@ if any step is missing. **k**: The key to merge. + **Returns**: None -Helper for merge, updating key k from o2 into o1. Arrays are deep-copied and objects are -recursively merged. + +### merge(target, objs) -## merge(target, objs) +Merge all passed objects into target, copying or merging each key as needed. +Arrays are deep-copied, objects are recursively merged, etc. **target**: The target object. **objs**: One or more objects to merge into target. + **Returns**: The updated target object. -Merge all passed objects into target, copying or merging each key as needed. -Arrays are deep-copied, objects are recursively merged, etc. + +### copy(proto, objs) -## copy(proto, objs) +Create a new object with proto as its prototype, then mix in additional objects’ properties. **proto**: The prototype object for the new object. **objs**: One or more objects whose properties will be mixed in. + **Returns**: The newly created object. -Create a new object with proto as its prototype, then mix in additional objects’ properties. + +### obj_lerp(a, b, t) -## obj_lerp(a, b, t) +Linearly interpolate between two objects a and b by factor t, assuming each property +supports .lerp(). **a**: The start object (its properties must have .lerp()). @@ -152,18 +175,18 @@ Create a new object with proto as its prototype, then mix in additional objects **t**: Interpolation factor (0..1). + **Returns**: A new object with interpolated properties. -Linearly interpolate between two objects a and b by factor t, assuming each property -supports .lerp(). + +### normalizeSpacing(spacing) -## normalizeSpacing(spacing) +Normalize any spacing input into a {l, r, t, b} object. **spacing**: A number, an array of length 2 or 4, or an object with l/r/t/b. + **Returns**: An object {l, r, t, b}. -Normalize any spacing input into a {l, r, t, b} object. - diff --git a/docs/api/modules/video.md b/docs/api/modules/video.md index 602fdd65..58c228b0 100644 --- a/docs/api/modules/video.md +++ b/docs/api/modules/video.md @@ -1,5 +1,7 @@ # video -## make_video() +## video + +### make_video Decode a video file (MPEG, etc.) from an ArrayBuffer, returning a datastream object. diff --git a/docs/api/prosperon.md b/docs/api/prosperon.md new file mode 100644 index 00000000..dc3b25a2 --- /dev/null +++ b/docs/api/prosperon.md @@ -0,0 +1,51 @@ +# prosperon + +## prosperon + +### engine_start + +### on(type, callback) + +### dispatch(type, data) + +### appupdate(...args) + +### update(...args) + +### physupdate(...args) + +### gui(...args) + +### hud(...args) + +### draw(...args) + +### imgui(...args) + +### app(...args) + +### camera + +A hierarchical transform storing 3D or 2D position, rotation (as a quaternion), +and scale. Can have a parent transform. Freed automatically on GC. + + +An application window, created via prosperon.engine_start or SDL calls. Freed on GC. + + +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 diff --git a/docs/api/types/PHYSFS_File.md b/docs/api/types/PHYSFS_File.md new file mode 100644 index 00000000..3facc1b9 --- /dev/null +++ b/docs/api/types/PHYSFS_File.md @@ -0,0 +1,55 @@ +# PHYSFS_File + +A file handle opened via PhysFS for writing or reading. Freed automatically when references go away. + + +### close + +Close this file handle. Throws on error. + + + +**Returns**: None + + +### write(data) + +Write data (string or ArrayBuffer) to the file. Throws on error. + + + +**data**: The data to write (string or ArrayBuffer). + + +**Returns**: None + + +### buffer(size) + +Enable an internal write buffer of the given size on this file. + + + +**size**: Size in bytes of the buffer. + + +**Returns**: None + + +### tell + +Return the current position in the file. + + + +**Returns**: A numeric offset. + + +### eof + +Return whether the file pointer is at end-of-file. + + + +**Returns**: True if at EOF, false otherwise. + diff --git a/docs/api/types/SDL_Camera.md b/docs/api/types/SDL_Camera.md new file mode 100644 index 00000000..75b201f7 --- /dev/null +++ b/docs/api/types/SDL_Camera.md @@ -0,0 +1,27 @@ +# SDL_Camera + +A handle to a physical camera device. Freed when references drop or camera is closed. + + +### frame + +Acquire the latest camera frame (as an SDL_Surface). Returns undefined if no +new frame is available yet. Throws on error. + + + +**Returns**: SDL_Surface or undefined. + + +### release_frame(surface) + +Release a frame surface previously acquired via camera.frame(). Must be +done for each acquired frame. + + + +**surface**: The surface to release. + + +**Returns**: None + diff --git a/docs/api/types/SDL_Cursor.md b/docs/api/types/SDL_Cursor.md new file mode 100644 index 00000000..8731d8f4 --- /dev/null +++ b/docs/api/types/SDL_Cursor.md @@ -0,0 +1,4 @@ +# SDL_Cursor + +An SDL cursor handle. Freed automatically on GC. No direct methods. + diff --git a/docs/api/types/SDL_GPUBuffer.md b/docs/api/types/SDL_GPUBuffer.md new file mode 100644 index 00000000..17093b30 --- /dev/null +++ b/docs/api/types/SDL_GPUBuffer.md @@ -0,0 +1,5 @@ +# SDL_GPUBuffer + +## SDL_GPUBuffer + +### name diff --git a/docs/api/types/SDL_GPUCommandBuffer.md b/docs/api/types/SDL_GPUCommandBuffer.md new file mode 100644 index 00000000..5eb56b10 --- /dev/null +++ b/docs/api/types/SDL_GPUCommandBuffer.md @@ -0,0 +1,231 @@ +# SDL_GPUCommandBuffer + +A command buffer that accumulates rendering, copy, and compute operations. Freed after submission or GC. + + +### render_pass(passDesc) + +Begin a render pass with color/depth attachments. Provide an object with +'color_targets' and optional 'depth_stencil'. Returns an SDL_GPURenderPass handle. + + + +**passDesc**: {color_targets:[...], depth_stencil:...} + + +**Returns**: SDL_GPURenderPass + + +### compute_pass(storageTextures, storageBuffers) + +Begin a compute pass reading/writing given arrays of textures and buffers. + + + +**storageTextures**: array of read/write textures + +**storageBuffers**: array of read/write buffers + + +**Returns**: SDL_GPUComputePass + + +### swapchain_pass(clearColor) + +Begin a render pass that directly targets the swapchain (the window). Clears +with the specified color. + + + +**clearColor**: [r,g,b,a] + + +**Returns**: SDL_GPURenderPass + + +### acquire_swapchain + +Acquire the current swapchain texture from the window. Internal usage. + + + +**Returns**: SDL_GPUTexture handle + + +### bind_vertex_buffer(slot, buffer) + +Bind a GPU buffer as the vertex buffer at a given slot. + + + +**slot**: Integer slot index. + +**buffer**: The SDL_GPUBuffer. + + +**Returns**: None + + +### bind_index_buffer(buffer, offset) + +Bind a GPU buffer as the index buffer (16-bit or 32-bit). + + + +**buffer**: The SDL_GPUBuffer. + +**offset**: Optional offset in bytes. + + +**Returns**: None + + +### bind_fragment_sampler(slot, texture, sampler) + +Bind a texture+sampler pair to a particular fragment shader slot. + + + +**slot**: Index of the sampler binding. + +**texture**: The SDL_GPUTexture + +**sampler**: The SDL_GPUSampler + + +**Returns**: None + + +### push_vertex_uniform_data(slot, data) + +Push raw data to a vertex shader uniform block. + + + +**slot**: The uniform buffer slot. + +**data**: An ArrayBuffer with the data to upload. + + +**Returns**: None + + +### push_fragment_uniform_data(slot, data) + +Push raw data to a fragment shader uniform block. + + + +**slot**: The uniform buffer slot index. + +**data**: An ArrayBuffer with uniform data. + + +**Returns**: None + + +### push_compute_uniform_data(slot, data) + +Push raw data to a compute shader uniform buffer. + + + +**slot**: The uniform buffer slot. + +**data**: An ArrayBuffer with the data. + + +**Returns**: None + + +### submit + +Submit this command buffer to the GPU and return a fence for synchronization. + + + +**Returns**: An SDL_GPUFence + + +### cancel + +Cancel (discard) this command buffer without submitting. + + + +**Returns**: None + + +### camera(cameraTransform, uniformSlot) + +Write a camera transform (projection/view) to a uniform slot for 3D or 2D usage. + + + +**cameraTransform**: A camera object or transform with .pos, fov, etc. + +**uniformSlot**: The integer uniform buffer slot to which data is pushed. + + +**Returns**: None + + +### hud(sizeVec2, uniformSlot) + +Write an orthographic full-screen "HUD" matrix to a uniform slot. Typically used +for 2D overlays. + + + +**sizeVec2**: [width, height] of the viewport area. + +**uniformSlot**: The integer uniform buffer slot. + + +**Returns**: None + + +### push_debug_group(name) + +Push a named debug group marker onto the GPU command list (for debuggers/profilers). + + + +**name**: The debug label string. + + +**Returns**: None + + +### pop_debug_group + +Pop the most recent debug group marker. + + + +**Returns**: None + + +### debug_label(label) + +Insert a one-off debug label at the current spot in the command list. + + + +**label**: The debug label string + + +**Returns**: None + + +### blit(blitDesc) + +Blit one GPU texture to another with optional flip mode, filter, and clear operations. + + + +**blitDesc**: { src:{texture,mip_level, etc}, dst:{texture,...}, load_op, flip, filter, clear_color:[r,g,b,a] } + + +**Returns**: None + diff --git a/docs/api/types/SDL_GPUComputePass.md b/docs/api/types/SDL_GPUComputePass.md new file mode 100644 index 00000000..63997dc6 --- /dev/null +++ b/docs/api/types/SDL_GPUComputePass.md @@ -0,0 +1,83 @@ +# SDL_GPUComputePass + +A compute pass for dispatching compute pipelines. Freed after end() or GC. + + +### dispatch(x, y, z) + +Dispatch the compute pipeline with the specified threadgroup counts. + + + +**x**: Number of groups in X dimension + +**y**: Number of groups in Y dimension + +**z**: Number of groups in Z dimension + + +**Returns**: None + + +### end + +End this compute pass. + + + +**Returns**: None + + +### pipeline(computePipeline) + +Bind a compute pipeline in this pass. + + + +**computePipeline**: The SDL_GPUComputePipeline + + +**Returns**: None + + +### samplers(arrayOfSamplerBindings, firstSlot) + +Bind a set of texture/sampler pairs for compute usage. + + + +**arrayOfSamplerBindings**: e.g. [ {texture, sampler}, ...] + +**firstSlot**: The starting sampler slot. + + +**Returns**: None + + +### storage_buffers(arrayOfBuffers, firstSlot) + +Bind an array of storage buffers for the compute shader. + + + +**arrayOfBuffers**: The buffers + +**firstSlot**: Starting binding slot. + + +**Returns**: None + + +### storage_textures(arrayOfTextures, firstSlot) + +Bind an array of storage textures for the compute shader. + + + +**arrayOfTextures**: The textures + +**firstSlot**: Starting binding slot + + +**Returns**: None + diff --git a/docs/api/types/SDL_GPUComputePipeline.md b/docs/api/types/SDL_GPUComputePipeline.md new file mode 100644 index 00000000..4ae86226 --- /dev/null +++ b/docs/api/types/SDL_GPUComputePipeline.md @@ -0,0 +1,5 @@ +# SDL_GPUComputePipeline + +Encapsulates a compute shader program plus associated resource layouts. +Created via device.compute_pipeline(...). + diff --git a/docs/api/types/SDL_GPUCopyPass.md b/docs/api/types/SDL_GPUCopyPass.md new file mode 100644 index 00000000..10096344 --- /dev/null +++ b/docs/api/types/SDL_GPUCopyPass.md @@ -0,0 +1,4 @@ +# SDL_GPUCopyPass + +A pass for CPU<->GPU or GPU<->GPU copy operations. No direct JS API besides internal usage. + diff --git a/docs/api/types/SDL_GPUDevice.md b/docs/api/types/SDL_GPUDevice.md new file mode 100644 index 00000000..3e8968c0 --- /dev/null +++ b/docs/api/types/SDL_GPUDevice.md @@ -0,0 +1,236 @@ +# SDL_GPUDevice + +A handle for low-level GPU operations via SDL GPU. Freed on GC. + + +### claim_window(window) + +Claim an existing SDL_Window so this GPU device can render to it. + + + +**window**: The SDL_Window to attach. + + +**Returns**: None + + +### make_pipeline(pipelineDesc) + +Create a new graphics pipeline from a descriptor object specifying shaders, +blend states, vertex format, etc. + + + +**pipelineDesc**: An object containing pipeline fields (vertexShader, blend, etc.). + + +**Returns**: A SDL_GPUGraphicsPipeline handle. + + +### compute_pipeline(desc) + +Create a compute pipeline from a descriptor (shader code, threadgroup sizes, etc.). + + + +**desc**: An object with shader code, thread counts, etc. + + +**Returns**: SDL_GPUComputePipeline handle. + + +### set_swapchain(composition, presentMode) + +Specify how the swapchain (final rendered image) is composed, e.g. 'sdr', 'hdr', +and present mode like 'vsync' or 'immediate'. + + + +**composition**: E.g. 'sdr', 'linear', or 'hdr'. + +**presentMode**: E.g. 'vsync', 'immediate', 'mailbox'. + + +**Returns**: None + + +### sort_sprite(a, b) + +A comparator function used for sorting sprite objects by layer, y, and texture. +Usually used internally. + + + +**a**: A sprite object. + +**b**: Another sprite object. + + +**Returns**: <0, 0, or >0 for sort ordering. + + +### make_sampler(samplerDesc) + +Create a sampler object specifying filtering, wrapping, anisotropy, etc. + + + +**samplerDesc**: An object with min_filter, mag_filter, etc. + + +**Returns**: SDL_GPUSampler handle. + + +### load_texture(surface, compressionLevel) + +Upload an SDL_Surface into a GPU texture, optionally compressing with DXT. Freed automatically. + + + +**surface**: An SDL_Surface. + +**compressionLevel**: 0=none, 1=DXT1 or DXT5, 2=high quality, etc. + + +**Returns**: SDL_GPUTexture + + +### texture(desc) + +Create a GPU texture with the specified format usage. + + + +**desc**: Object with {width, height, layers, type, format, usage, etc.} + + +**Returns**: SDL_GPUTexture + + +### make_quad + +Return a simple 2-triangle quad geometry covering [0,1]x[0,1]. +Useful for post-processing passes. + + + +**Returns**: A mesh {pos, uv, color, indices}. + + +### driver + +Return the name of the underlying GPU driver in use (e.g. 'OpenGL'). + + + +**Returns**: A string with driver name. + + +### make_shader(desc) + +Compile raw shader code (vertex or fragment) in e.g. SPIR-V, MSL, or DXIL format. + + + +**desc**: {code:ArrayBuffer, stage:'vertex'|'fragment', format:'spv'|..., entrypoint:'main', ...} + + +**Returns**: SDL_GPUShader object + + +### acquire_cmd_buffer + +Obtain a new command buffer for recording GPU commands. Must be submitted or canceled. + + + +**Returns**: SDL_GPUCommandBuffer handle + + +### upload(cmdBuffer, buffers, transferBuffer) + +Upload CPU data into a list of GPU buffers, optionally reusing or returning a +transfer buffer. Typically you provide (cmdBuf, arrayOfTypedArrays, [transferBuffer]). + + + +**cmdBuffer**: The command buffer in which to record copy commands. + +**buffers**: An array of typed-array data to upload, each must have a 'gpu' property or so. + +**transferBuffer**: Optional existing GPU transfer buffer to reuse. + + +**Returns**: The transfer buffer used or newly created. + + +### wait_for_fences(fences, waitAll) + +Wait on an array of GPU fence objects, optionally requiring all or any. + + + +**fences**: An array of SDL_GPUFence objects. + +**waitAll**: Boolean, true to wait for all fences, false for any. + + +**Returns**: True if fences signaled, false on timeout or error. + + +### query_fence(fence) + +Check if the given fence has been signaled yet. Non-blocking. + + + +**fence**: SDL_GPUFence handle + + +**Returns**: True if signaled, false if still pending + + +### shader_format + +Return an array of supported GPU shader binary formats (like 'spv', 'dxbc', etc.). + + + +**Returns**: Array of strings naming supported formats. + + +### slice9(texture, dstRect, edges) + +Generate a 9-slice tiling geometry in one shot. For advanced usage with GPU pipeline. + + + +**texture**: An SDL_GPUTexture + +**dstRect**: The rectangle {x, y, w, h} + +**edges**: {l, r, t, b} edge sizes + + +**Returns**: A mesh object + + +### tile(texture, srcRect, dstRect, tileInfo) + +Generate geometry to tile a texture portion inside a dest rect. +Often used for repeating backgrounds. + + + +**texture**: The SDL_GPUTexture + +**srcRect**: The portion to tile in pixels + +**dstRect**: Where to fill + +**tileInfo**: e.g. {repeat_x:true, repeat_y:true} + + +**Returns**: A mesh object + diff --git a/docs/api/types/SDL_GPUFence.md b/docs/api/types/SDL_GPUFence.md new file mode 100644 index 00000000..d356e74d --- /dev/null +++ b/docs/api/types/SDL_GPUFence.md @@ -0,0 +1,5 @@ +# SDL_GPUFence + +A GPU fence for synchronization. Created upon commandBuffer.submit(). +Wait or query it with device.wait_for_fences or device.query_fence. + diff --git a/docs/api/types/SDL_GPUGraphicsPipeline.md b/docs/api/types/SDL_GPUGraphicsPipeline.md new file mode 100644 index 00000000..388e0ae8 --- /dev/null +++ b/docs/api/types/SDL_GPUGraphicsPipeline.md @@ -0,0 +1,5 @@ +# SDL_GPUGraphicsPipeline + +Encapsulates vertex+fragment shaders, blend/cull states, and vertex attribute layouts. +Created via device.make_pipeline(...). + diff --git a/docs/api/types/SDL_GPURenderPass.md b/docs/api/types/SDL_GPURenderPass.md new file mode 100644 index 00000000..787c3be6 --- /dev/null +++ b/docs/api/types/SDL_GPURenderPass.md @@ -0,0 +1,159 @@ +# SDL_GPURenderPass + +A single pass of drawing commands with color/depth attachments. Freed after end() or GC. + + +### bind_pipeline(pipeline) + +Bind a previously created graphics pipeline (shaders, states, vertex layouts, etc.). + + + +**pipeline**: The SDL_GPUGraphicsPipeline + + +**Returns**: None + + +### viewport(rect) + +Set the viewport for clipping or scaling draws, in pass-local coordinates. + + + +**rect**: {x,y,w,h} + + +**Returns**: None + + +### scissor(rect) + +Set a scissor rectangle for discarding pixels outside it. + + + +**rect**: {x,y,w,h} + + +**Returns**: None + + +### draw(primitiveType, baseVertex, firstVertex, vertexCount) + +Issue a non-indexed draw call. + + + +**primitiveType**: e.g. SDL_GPU_PRIMITIVETYPE_TRIANGLELIST + +**baseVertex**: Starting vertex offset. + +**firstVertex**: The first vertex to draw. + +**vertexCount**: How many vertices to draw. + + +**Returns**: None + + +### draw_indexed(primitiveType, baseVertex, firstIndex, indexCount, instanceCount) + +Issue an indexed draw call from the bound index buffer. + + + +**primitiveType**: The primitive type constant. + +**baseVertex**: Offset in the vertex buffer. + +**firstIndex**: Which index to start from. + +**indexCount**: Number of indices to draw. + +**instanceCount**: For instanced drawing, or 1 if normal. + + +**Returns**: None + + +### end + +End this render pass, finalizing the draw operations. + + + +**Returns**: None + + +### bind_index_buffer(buffer, elementSize16bit) + +Bind an index buffer inside this pass, possibly overriding the global one. + + + +**buffer**: The SDL_GPUBuffer + +**elementSize16bit**: If 2, uses 16-bit indices; if 4, uses 32-bit indices + + +**Returns**: None + + +### bind_buffers(firstSlot, arrayOfBuffers) + +Bind multiple vertex buffers at consecutive slots. + + + +**firstSlot**: The starting vertex buffer slot. + +**arrayOfBuffers**: An array of GPUBuffer objects + + +**Returns**: None + + +### bind_samplers(vertexOrFragment, firstSlot, samplerBindings) + +Bind multiple texture/sampler pairs to either vertex or fragment slots. + + + +**vertexOrFragment**: Boolean, true for vertex stage, false for fragment. + +**firstSlot**: The first sampler slot to bind. + +**samplerBindings**: An array of {texture, sampler}. + + +**Returns**: None + + +### bind_storage_buffers(firstSlot, buffers) + +Bind one or more storage buffers for read/write in the pipeline. + + + +**firstSlot**: Starting buffer slot index. + +**buffers**: An array of SDL_GPUBuffer objects. + + +**Returns**: None + + +### bind_storage_textures(firstSlot, textures) + +Bind one or more storage textures for read/write in the pipeline. + + + +**firstSlot**: Starting texture slot index. + +**textures**: An array of SDL_GPUTexture objects. + + +**Returns**: None + diff --git a/docs/api/types/SDL_GPUSampler.md b/docs/api/types/SDL_GPUSampler.md new file mode 100644 index 00000000..521e0080 --- /dev/null +++ b/docs/api/types/SDL_GPUSampler.md @@ -0,0 +1,4 @@ +# SDL_GPUSampler + +Defines how a texture is sampled (filter mode, address mode, anisotropy, compare op, etc.). + diff --git a/docs/api/types/SDL_GPUShader.md b/docs/api/types/SDL_GPUShader.md new file mode 100644 index 00000000..6aa5de6b --- /dev/null +++ b/docs/api/types/SDL_GPUShader.md @@ -0,0 +1,5 @@ +# SDL_GPUShader + +A single compiled shader (vertex or fragment) in a GPU-friendly format +(e.g., SPIR-V, MSL). Combined into a pipeline for drawing. + diff --git a/docs/api/types/SDL_GPUTexture.md b/docs/api/types/SDL_GPUTexture.md new file mode 100644 index 00000000..1fb0918a --- /dev/null +++ b/docs/api/types/SDL_GPUTexture.md @@ -0,0 +1,5 @@ +# SDL_GPUTexture + +## SDL_GPUTexture + +### name diff --git a/docs/api/types/SDL_GPUTransferBuffer.md b/docs/api/types/SDL_GPUTransferBuffer.md new file mode 100644 index 00000000..58124193 --- /dev/null +++ b/docs/api/types/SDL_GPUTransferBuffer.md @@ -0,0 +1,5 @@ +# SDL_GPUTransferBuffer + +A staging buffer used for copying data to or from GPU buffers/textures. Typically +allocated/used internally by device.upload(...). + diff --git a/docs/api/types/SDL_Renderer.md b/docs/api/types/SDL_Renderer.md new file mode 100644 index 00000000..8b8aa38c --- /dev/null +++ b/docs/api/types/SDL_Renderer.md @@ -0,0 +1,333 @@ +# SDL_Renderer + +A 2D rendering context using the SDL renderer API. Freed automatically. + + +### draw_color(color) + +Set the render draw color for subsequent primitive calls (rect, line, etc.). + + + +**color**: [r, g, b, a] in 0..1. + + +**Returns**: None + + +### present + +Display whatever has been rendered (swap buffers). Must be called each frame. + + + +**Returns**: None + + +### clear + +Clear the current render target with the renderer's draw color. + + + +**Returns**: None + + +### rect(rectOrArray, color) + +Draw one or more outlines of rectangles. + + + +**rectOrArray**: A single rect {x,y,w,h} or an array of rects. + +**color**: Optional [r,g,b,a]. If provided, overrides current draw color. + + +**Returns**: None + + +### fillrect(rectOrArray, color) + +Fill one or more rectangles with the renderer's current color or an optional override. + + + +**rectOrArray**: A single rect {x,y,w,h} or an array of rects. + +**color**: Optional [r,g,b,a]. + + +**Returns**: None + + +### line(points, color) + +Draw a sequence of lines connecting points in an array. + + + +**points**: An array of [x,y] points. Lines connect consecutive points. + +**color**: Optional [r,g,b,a]. + + +**Returns**: None + + +### point(points, color) + +Draw a list of points (pixels). + + + +**points**: An array of [x,y] positions. + +**color**: Optional [r,g,b,a]. + + +**Returns**: None + + +### load_texture(surface) + +Create an SDL_Texture from a given SDL_Surface for use with this renderer. + + + +**surface**: An SDL_Surface. + + +**Returns**: An SDL_Texture object. + + +### texture(tex, dstRect, srcRect, color) + +Draw a texture onto the render target. + + + +**tex**: The SDL_Texture to draw. + +**dstRect**: The destination rect {x, y, w, h}. + +**srcRect**: Optional portion of the texture to draw {x, y, w, h}. + +**color**: Optional color mod [r,g,b,a]. + + +**Returns**: None + + +### slice9(tex, dstRect, edges, srcRect) + +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. + + + +**tex**: The SDL_Texture. + +**dstRect**: Destination region {x, y, w, h}. + +**edges**: {l, r, t, b} for corner sizes in pixels. + +**srcRect**: Optional portion in the texture. + + +**Returns**: None + + +### tile(tex, dstRect, srcRect, scale) + +Tile a texture repeatedly within the specified region. Optionally use a srcRect. + + + +**tex**: The SDL_Texture to tile. + +**dstRect**: The region to fill {x, y, w, h}. + +**srcRect**: Optional portion of texture. + +**scale**: A float scale factor for each tile. + + +**Returns**: None + + +### get_image(rect) + +Read back the rendered pixels into a new SDL_Surface. If rect is undefined, capture entire output. + + + +**rect**: Optional {x,y,w,h}. + + +**Returns**: An SDL_Surface with the requested region's pixels. + + +### fasttext(text, pos, color) + +Draw debug text using an internal fast path. Typically used for quick debugging overlays. + + + +**text**: The string to draw. + +**pos**: The [x, y] position to draw text. + +**color**: Optional [r,g,b,a]. + + +**Returns**: None + + +### geometry(texture, meshObject) + +Render custom geometry from a mesh object {pos, uv, color, indices, count} with an optional texture. + + + +**texture**: The SDL_Texture or undefined. + +**meshObject**: The geometry data with typed arrays. + + +**Returns**: None + + +### scale(scaleVec2) + +Set a scaling factor for all subsequent rendering on this renderer. + + + +**scaleVec2**: [sx, sy] scaling factors. + + +**Returns**: None + + +### logical_size(size) + +Set a "logical" size that the renderer will scale to. +For example, (320, 240) can auto-scale up to the window resolution. + + + +**size**: [width, height]. + + +**Returns**: None + + +### viewport(rect) + +Set the clipping viewport for rendering. Pass undefined to use the full render target. + + + +**rect**: {x, y, w, h}, or undefined. + + +**Returns**: None + + +### clip(rect) + +Set or clear the clipping rectangle for drawing. Pass undefined to clear. + + + +**rect**: {x, y, w, h} or undefined. + + +**Returns**: None + + +### vsync(flag) + +Enable or disable vertical sync. This may have no effect depending on the driver. + + + +**flag**: True or false. + + +**Returns**: None + + +### coords(pos) + +Convert window coordinates to this renderer's coordinate space. + + + +**pos**: [x, y] in window space. + + +**Returns**: [x, y] in renderer coordinate space. + + +### camera(cameraTransform, centered) + +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. + + + +**cameraTransform**: The transform whose pos is used. + +**centered**: Boolean true or false. + + +**Returns**: None + + +### get_viewport + +Return the current viewport rect. + + + +**Returns**: {x, y, w, h} + + +### screen2world(pos) + +Convert a screen coordinate to world space based on the current camera transform. + + + +**pos**: [x, y] screen coords + + +**Returns**: [wx, wy] in world space + + +### target(texture) + +Set or clear the current render target texture. Pass undefined to reset to the default/window. + + + +**texture**: An SDL_Texture or undefined + + +**Returns**: None + + +### make_sprite_mesh(sprites) + +Generate a mesh from an array of sprite objects, combining their positions, UVs, +and colors into a single geometry block. + + + +**sprites**: An array of sprite-like objects. + + +**Returns**: A 'mesh' object with pos, uv, color, indices, etc. + diff --git a/docs/api/types/SDL_Surface.md b/docs/api/types/SDL_Surface.md new file mode 100644 index 00000000..69ddb312 --- /dev/null +++ b/docs/api/types/SDL_Surface.md @@ -0,0 +1,68 @@ +# SDL_Surface + +A software (CPU) image in memory. Freed when references vanish. Typically converted +to SDL_Texture for drawing, or used as raw pixel data. + + +### blit(dstRect, srcSurface, srcRect) + +Blit (copy) another surface onto this surface, scaling if needed. + + + +**dstRect**: Destination {x, y, w, h} + +**srcSurface**: The source SDL_Surface + +**srcRect**: {x, y, w, h} portion from source + + +**Returns**: None + + +### scale(newSize) + +Return a new SDL_Surface scaled to [width, height] using linear filtering. + + + +**newSize**: [width, height] + + +**Returns**: A new SDL_Surface with the scaled result. + + +### fill(color) + +Fill the entire surface with a single color. + + + +**color**: [r, g, b, a] in 0..1 + + +**Returns**: None + + +### rect(rect, color) + +Fill a sub-rectangle of the surface with a color. + + + +**rect**: {x, y, w, h} + +**color**: [r, g, b, a] + + +**Returns**: None + + +### dup + +Make a copy of this surface in RGBA format. + + + +**Returns**: A new SDL_Surface copy. + diff --git a/docs/api/types/SDL_Texture.md b/docs/api/types/SDL_Texture.md new file mode 100644 index 00000000..6cdf949a --- /dev/null +++ b/docs/api/types/SDL_Texture.md @@ -0,0 +1,16 @@ +# SDL_Texture + +A 2D GPU-accelerated texture for rendering with SDL_Renderer. Freed automatically. + + +### mode(mode) + +Set texture scale mode or filtering mode (nearest/linear). + + + +**mode**: A string or numeric mode to set (e.g., 'linear'). + + +**Returns**: None + diff --git a/docs/api/types/SDL_Thread.md b/docs/api/types/SDL_Thread.md new file mode 100644 index 00000000..fde026fd --- /dev/null +++ b/docs/api/types/SDL_Thread.md @@ -0,0 +1,15 @@ +# SDL_Thread + +A handle to an SDL-created thread. Freed on GC after join. + +Note: The engine generally doesn't expose custom usage for threads. + + +### wait + +Block until this thread terminates. + + + +**Returns**: None + diff --git a/docs/api/types/SDL_Window.md b/docs/api/types/SDL_Window.md new file mode 100644 index 00000000..2abc513d --- /dev/null +++ b/docs/api/types/SDL_Window.md @@ -0,0 +1,126 @@ +# SDL_Window + +An application window, created via prosperon.engine_start or SDL calls. Freed on GC. + + +### fullscreen + +Toggle fullscreen mode for this window (SDL_WINDOW_FULLSCREEN). + + + +**Returns**: None + + +### make_renderer(name) + +Create an SDL_Renderer for 2D rendering tied to this window. + + + +**name**: The renderer driver name, e.g. "opengl" (may be optional). + + +**Returns**: An SDL_Renderer object. + + +### make_gpu(debug, driverName) + +Create an SDL_GPUDevice for low-level GPU rendering on this window. + + + +**debug**: If true, enable debugging in the GPU device. + +**driverName**: The GPU back-end driver, e.g. "opengl". + + +**Returns**: An SDL_GPUDevice. + + +### keyboard_shown + +Return whether the on-screen keyboard is visible (mobile/tablet). + + + +**Returns**: True if shown, false otherwise. + + +### theme + +Currently returns undefined. Placeholder for retrieving OS window theme info. + + + +**Returns**: undefined + + +### safe_area + +Return a rect describing any OS-specific "safe" region for UI, e.g. on iPhone with a notch. + + + +**Returns**: A rect object {x, y, w, h}. + + +### bordered(flag) + +Enable or disable window borders. + + + +**flag**: True to show borders, false to hide. + + +**Returns**: None + + +### set_icon(surface) + +Set the window's icon from an SDL_Surface. + + + +**surface**: An SDL_Surface holding the icon. + + +**Returns**: None + + +### title + +Get or set the window's title text in the title bar. + + + +**newTitle**: (when setting) A string title. + + +**Returns**: The current title if getting, or None if setting. + + +### size + +Get or set the window's size as [width, height]. + + + +**newSize**: (when setting) e.g. [640, 480] + + +**Returns**: The current [width, height] or None if setting. + + +### mouse_grab(flag) + +Grab or ungrab the mouse for this window (so the pointer won't leave). + + + +**flag**: True to grab mouse input, false to release. + + +**Returns**: None + diff --git a/docs/api/types/datastream.md b/docs/api/types/datastream.md new file mode 100644 index 00000000..ed96aeb3 --- /dev/null +++ b/docs/api/types/datastream.md @@ -0,0 +1,67 @@ +# datastream + +A streaming media handle, typically for MPEG video. Freed automatically. + + +### time + +Return the current playback time in seconds. + + + +**Returns**: Current time as a float in seconds. + + +### seek(seconds) + +Seek to the specified time (in seconds). + + + +**seconds**: The time to jump to in the stream. + + +**Returns**: None + + +### advance(seconds) + +Advance by a certain number of seconds, decoding video as needed. + + + +**seconds**: The amount of time to skip forward. + + +**Returns**: None + + +### duration + +Return the total duration of the video stream, in seconds, if known. + + + +**Returns**: Float seconds duration, or 0 if unknown. + + +### framerate + +Return the framerate (FPS) of the stream if known. + + + +**Returns**: Float frames per second, or 0 if unknown. + + +### callback + +A function to call whenever a new frame is decoded. If not set, no callback is invoked. + + + +**fn**: (when setting) A function that receives (surface). + + +**Returns**: The existing function or undefined if none. + diff --git a/docs/api/types/font.md b/docs/api/types/font.md new file mode 100644 index 00000000..1dcd8d0f --- /dev/null +++ b/docs/api/types/font.md @@ -0,0 +1,66 @@ +# font + +A bitmap or TTF-based font object storing glyph data. +Used for measuring/drawing text. Freed when GC sees no references. + + +### linegap + +Get or set the font's additional line spacing above the built-in metrics. + + + +**value**: (when setting) The new line gap. + + +**Returns**: The current line gap (when getting), or None (when setting). + + +### height + +(read only) + +The baseline-to-baseline height in pixels. + + + +**Returns**: The font's total height in px. + + +### ascent + +(read only) + +How far above the baseline the font extends. + + + +**Returns**: A scalar float for ascent. + + +### descent + +(read only) + +How far below baseline the font extends. + + + +**Returns**: A scalar float for descent. + + +### text_size(text, letterSpacing, wrap) + +Measure a piece of text's width/height when rendered with this font. + + + +**text**: The string to measure. + +**letterSpacing**: Extra spacing between characters. + +**wrap**: If nonzero, word-wrap to this maximum width. + + +**Returns**: [width, height] as a float array. + diff --git a/docs/api/types/rtree.md b/docs/api/types/rtree.md new file mode 100644 index 00000000..63bb249b --- /dev/null +++ b/docs/api/types/rtree.md @@ -0,0 +1,73 @@ +# rtree + +An R-tree for spatial lookups. Insert bounding boxes, query by bounding box, etc. + + +### add(obj) + +Insert an object that has a 'rect' property {x, y, w, h} into the tree. + + + +**obj**: The object to add (must have rectAtom). + + +**Returns**: None + + +### delete(obj) + +Remove an object from the tree. Must match the same rect as used when adding. + + + +**obj**: The object to remove. + + +**Returns**: None + + +### query(rect) + +Return an array of objects whose bounding boxes intersect the given rect. + + + +**rect**: {x, y, w, h} bounding region to query. + + +**Returns**: Array of objects that overlap that region. + + +### forEach(callback) + +Call a function for every item in the rtree. + + + +**callback**: A function called with no arguments, or possibly (item). + + +**Returns**: None + + +### has(obj) + +Return true if the specified object is in the tree, false otherwise. + + + +**obj**: The object to check. + + +**Returns**: True if found, else false. + + +### values + +Return an array of all items currently in the rtree. + + + +**Returns**: Array of all stored objects. + diff --git a/docs/api/types/sprite.md b/docs/api/types/sprite.md new file mode 100644 index 00000000..ad042ef9 --- /dev/null +++ b/docs/api/types/sprite.md @@ -0,0 +1,68 @@ +# sprite + +A 'sprite' is a simple struct for 2D drawing. It stores a rectangle (pos + size), +UV coordinates, color, and layer, as well as an associated 'image' object. The sprite +can be drawn via GPU or SDL_Renderer. Freed when no JS references remain. + + +### set_affine(transform) + +Update this sprite's position and size from a transform's pos and scale. + + + +**transform**: The transform whose pos/scale will overwrite the sprite's rect. + + +**Returns**: None + + +### set_rect(rect) + +Set the sprite's rect (x, y, w, h) directly. + + + +**rect**: An object or array specifying x, y, width, and height. + + +**Returns**: None + + +### set_image(image) + +Assign or replace the sprite's underlying image. Automatically updates UV if +the image has a 'rect' property. + + + +**image**: A JS object representing the image (with .texture, .rect, etc.). + + +**Returns**: None + + +### layer + +Get or set the sprite's z-layer integer. Sprites with higher layers typically +draw on top of lower layers. + + + +**value**: (when setting) An integer specifying the layer. + + +**Returns**: The current layer (when getting), or None (when setting). + + +### color + +Get or set the sprite's color tint as [r, g, b, a]. + + + +**value**: (when setting) An array [r, g, b, a] in the 0.0..1.0 range. + + +**Returns**: The current color array (when getting), or None (when setting). + diff --git a/docs/api/types/timer.md b/docs/api/types/timer.md new file mode 100644 index 00000000..73209cac --- /dev/null +++ b/docs/api/types/timer.md @@ -0,0 +1,29 @@ +# timer + +A scheduled callback or countdown. Freed automatically once no longer referenced +or once it completes. + + +### remain + +Get or set how many seconds remain before the timer triggers. + + + +**value**: (when setting) A float specifying new time remaining. + + +**Returns**: The current time left (when getting), or None (when setting). + + +### fn + +Get or set the function called when the timer expires. + + + +**value**: (when setting) The function. + + +**Returns**: The function or undefined if none is set. + diff --git a/docs/api/types/transform.md b/docs/api/types/transform.md new file mode 100644 index 00000000..17e7c663 --- /dev/null +++ b/docs/api/types/transform.md @@ -0,0 +1,214 @@ +# transform + +A hierarchical transform storing 3D or 2D position, rotation (as a quaternion), +and scale. Can have a parent transform. Freed automatically on GC. + + +### pos + +Get or set the transform's position as a 3D vector [x, y, z]. + + + +**value**: (when setting) [x, y, z]. + + +**Returns**: The current position vector (when getting), or None (when setting). + + +### scale + +Get or set the transform's scale as a 3D vector [x, y, z]. +For 2D usage, z is often 1. + + + +**value**: (when setting) [sx, sy, sz]. + + +**Returns**: The current scale (when getting), or None (when setting). + + +### rotation + +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. + + + +**value**: (when setting) [qx, qy, qz, qw]. + + +**Returns**: The current quaternion (when getting), or None (when setting). + + +### parent + +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. + + + +**value**: (when setting) Another transform or undefined. + + +**Returns**: The current parent transform (when getting), or None (when setting). + + +### change_hook + +A user-supplied function that's called whenever the transform's local matrix changes. +If undefined, no hook is called. + + + +**value**: (when setting) A function. + + +**Returns**: The current function or undefined. + + +### trs(pos, quat, scale) + +Set the transform's position, rotation, and scale in one call. + + + +**pos**: [x,y,z] for position, or undefined to keep existing. + +**quat**: [qx,qy,qz,qw] for rotation, or undefined. + +**scale**: [sx,sy,sz] for scale, or undefined. + + +**Returns**: None + + +### phys2d(velocity, angularVel, dt) + +Apply simple 2D velocity and angular velocity to this transform. + + + +**velocity**: [vx, vy] added to 'pos' each frame. + +**angularVel**: A scalar for rotation in (radians/second). + +**dt**: The time delta in seconds. + + +**Returns**: None + + +### move(delta) + +Translate this transform by the specified vector. + + + +**delta**: [dx, dy, dz] to add to .pos + + +**Returns**: None + + +### rotate(axis, angle) + +Rotate this transform by an axis+angle. + + + +**axis**: [ax, ay, az] the axis of rotation. + +**angle**: The angle in turns or radians (depending on usage). + + +**Returns**: None + + +### angle(axis) + +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. + + + +**axis**: Which axis [1,0,0] or [0,1,0] or [0,0,1]. + + +**Returns**: The numeric angle in 'turns' or radians, depending on usage. + + +### lookat(target) + +Rotate this transform so it looks toward the given world position. + + + +**target**: [x, y, z] position in world coords. + + +**Returns**: None + + +### direction(localDir) + +Rotate a vector by this transform's rotation, effectively "transforming" +a direction from local space to world space. + + + +**localDir**: [dx, dy, dz] in local transform coordinates. + + +**Returns**: [dx', dy', dz'] direction in world space. + + +### unit + +Reset position, rotation, and scale to [0,0,0], identity rotation, and [1,1,1]. + + + +**Returns**: None + + +### rect(rect) + +Set this transform's pos and scale from a 2D rect object {x, y, w, h}. + + + +**rect**: Object with .x, .y, .w, .h + + +**Returns**: None + + +### array + +Return this transform's matrix as a 16-element float array in column-major order. + + + +**Returns**: An array of 16 floats. + + +### torect + +Convert transform's 2D position/scale to a rect {x, y, w, h}. +Rotation is currently ignored. + + + +**Returns**: A rect object {x, y, w, h}. + + +### children + +Return an array of child transforms belonging to this transform. + + + +**Returns**: An array of transform objects. + diff --git a/docs/api/use.md b/docs/api/use.md new file mode 100644 index 00000000..3fb56a66 --- /dev/null +++ b/docs/api/use.md @@ -0,0 +1,3 @@ +# use + +## use diff --git a/requirements.txt b/requirements.txt index 9dd3a3eb..cb3d0016 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,184 +1,17 @@ -aiohappyeyeballs==2.4.4 -aiohttp==3.11.11 -aiohttp-cors==0.7.0 -aiosignal==1.3.2 -airportsdata==20241001 -annotated-types==0.7.0 -anyio==4.8.0 -astor==0.8.1 -attrs==25.1.0 -babel==2.17.0 -blake3==1.0.4 -bracex==2.5.post1 -cachetools==5.5.1 -certifi==2024.12.14 -charset-normalizer==3.4.1 -click==8.1.8 -cloudpickle==3.1.0 -colorama==0.4.6 -coloredlogs==15.0.1 -colorful==0.5.6 -compressed-tensors==0.8.1 -contourpy==1.3.1 -cycler==0.12.1 -dbus-python==1.3.2 -depyf==0.18.0 -dill==0.3.9 -diskcache==5.6.3 -distlib==0.3.9 -distro==1.9.0 -dnf==4.22.0 -einops==0.8.0 -Farama-Notifications==0.0.4 -fastapi==0.115.7 -filelock==3.16.1 -flatbuffers==24.12.23 -fonttools==4.55.3 -frozenlist==1.5.0 -fsspec==2024.12.0 -gguf==0.10.0 -ghp-import==2.1.0 -gitdb==4.0.12 -GitPython==3.1.44 -google-api-core==2.24.0 -google-auth==2.38.0 -googleapis-common-protos==1.66.0 -grpcio==1.70.0 -gym==0.26.2 -gym-notices==0.0.8 -gymnasium==1.0.0 -h11==0.14.0 -httpcore==1.0.7 -httptools==0.6.4 -httpx==0.28.1 -huggingface-hub==0.27.1 -humanfriendly==10.0 -idna==3.10 -importlib_metadata==8.6.1 -iniconfig==2.0.0 -interegular==0.3.3 -Jinja2==3.1.5 -jiter==0.8.2 -jsonschema==4.23.0 -jsonschema-specifications==2024.10.1 -kiwisolver==1.4.8 -lark==1.2.2 -libcomps==0.1.20 -libdnf==0.73.4 -lm-format-enforcer==0.10.9 -Markdown==3.7 -MarkupSafe==3.0.2 -matplotlib==3.8.1 -mergedeep==1.3.4 -meson==1.4.1 -mistral_common==1.5.2 -mkdocs==1.6.1 +mkdocs==1.6.0 +mkdocs-material==9.5.28 mkdocs-awesome-pages-plugin==2.10.1 -mkdocs-get-deps==0.2.0 -mkdocs-git-revision-date-localized-plugin==1.3.0 -mkdocs-material==9.6.2 -mkdocs-material-extensions==1.3.1 -mpmath==1.3.0 -msgpack==1.1.0 -msgspec==0.19.0 -multidict==6.1.0 +pymdown-extensions==10.7 +Markdown==3.5.2 +mergedeep==1.3.4 +bracex==2.5.post1 +PyYAML==6.0.1 +click==8.1.7 +colorama==0.4.6 +Jinja2==3.1.3 natsort==8.4.0 -nest-asyncio==1.6.0 -networkx==3.4.2 -nftables==0.1 -numpy==1.26.4 -nvidia-cublas-cu12==12.4.5.8 -nvidia-cuda-cupti-cu12==12.4.127 -nvidia-cuda-nvrtc-cu12==12.4.127 -nvidia-cuda-runtime-cu12==12.4.127 -nvidia-cudnn-cu12==9.1.0.70 -nvidia-cufft-cu12==11.2.1.3 -nvidia-curand-cu12==10.3.5.147 -nvidia-cusolver-cu12==11.6.1.9 -nvidia-cusparse-cu12==12.3.1.170 -nvidia-ml-py==12.570.86 -nvidia-nccl-cu12==2.21.5 -nvidia-nvjitlink-cu12==12.4.127 -nvidia-nvtx-cu12==12.4.127 -onnxruntime==1.20.1 -openai==1.60.1 -opencensus==0.11.4 -opencensus-context==0.1.3 -opencv-python-headless==4.11.0.86 -outlines==0.1.11 -outlines_core==0.1.26 packaging==23.2 -paginate==0.5.7 -pandas==2.1.2 -partial-json-parser==0.2.1.1.post5 -pathspec==0.12.1 -pillow==10.4.0 -platformdirs==4.3.6 -pluggy==1.5.0 -prometheus-fastapi-instrumentator==7.0.2 -prometheus_client==0.21.1 -propcache==0.2.1 -proto-plus==1.25.0 -protobuf==5.29.2 -psutil==6.1.1 -py-cpuinfo==9.0.0 -py-spy==0.4.0 -pyasn1==0.6.1 -pyasn1_modules==0.4.1 -pybind11==2.13.6 -pycountry==24.6.1 -pydantic==2.10.6 -pydantic_core==2.27.2 -Pygments==2.19.1 -PyGObject==3.48.2 -pymdown-extensions==10.14.3 -pyparsing==3.2.0 -pytest==8.3.4 -python-dateutil==2.8.2 -python-dotenv==1.0.1 -pytz==2024.2 -PyYAML==6.0.2 -pyyaml_env_tag==0.1 -pyzmq==26.2.0 -ray==2.41.0 -referencing==0.36.2 -regex==2024.11.6 +Pygments==2.17.2 requests==2.32.3 -rpds-py==0.22.3 -rpm==4.19.1.1 -rsa==4.9 -safetensors==0.5.2 -seaborn==0.13.2 -sentencepiece==0.2.0 -setuptools==75.8.0 -six==1.16.0 -smart-open==7.1.0 -smmap==5.0.2 -sniffio==1.3.1 -stable_baselines3==2.4.0 -starlette==0.45.3 -sympy==1.13.1 -systemd-python==235 -tiktoken==0.7.0 -tokenizers==0.21.0 -torch==2.5.1 -torchvision==0.20.1 -tqdm==4.67.1 -transformers==4.48.1 -triton==3.1.0 -typing_extensions==4.12.2 -tzdata==2024.2 -urllib3==2.3.0 -uvicorn==0.34.0 -uvloop==0.21.0 -virtualenv==20.29.1 -vllm==0.6.6.post1 -watchdog==6.0.0 -watchfiles==1.0.4 -wcmatch==10.0 -websockets==14.2 -wrapt==1.17.2 -xformers==0.0.28.post3 -xgrammar==0.1.11 -yarl==1.18.3 -zipp==3.21.0 +ghp-import==2.1.0 +watchdog==4.0.0 diff --git a/scripts/core/engine.js b/scripts/core/engine.js index 30e9a784..f83f4538 100644 --- a/scripts/core/engine.js +++ b/scripts/core/engine.js @@ -1,5 +1,1141 @@ -(function engine() { +(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 +// +prosperon.c_types.sprite[prosperon.DOC] = {} +prosperon.c_types.sprite[prosperon.DOC][prosperon.DOC] = `A 'sprite' is a simple struct for 2D drawing. It stores a rectangle (pos + size), +UV coordinates, color, and layer, as well as an associated 'image' object. The sprite +can be drawn via GPU or SDL_Renderer. Freed when no JS references remain. +`; + +prosperon.c_types.sprite[prosperon.DOC].set_affine = `Update this sprite's position and size from a transform's pos and scale. + +:param transform: The transform whose pos/scale will overwrite the sprite's rect. +:return: None +`; + +prosperon.c_types.sprite[prosperon.DOC].set_rect = `Set the sprite's rect (x, y, w, h) directly. + +:param rect: An object or array specifying x, y, width, and height. +:return: None +`; + +prosperon.c_types.sprite[prosperon.DOC].set_image = `Assign or replace the sprite's underlying image. Automatically updates UV if +the image has a 'rect' property. + +:param image: A JS object representing the image (with .texture, .rect, etc.). +:return: None +`; + +prosperon.c_types.sprite[prosperon.DOC].layer = `Get or set the sprite's z-layer integer. Sprites with higher layers typically +draw on top of lower layers. + +:param value: (when setting) An integer specifying the layer. +:return: The current layer (when getting), or None (when setting). +`; + +prosperon.c_types.sprite[prosperon.DOC].color = `Get or set the sprite's color tint as [r, g, b, a]. + +:param value: (when setting) An array [r, g, b, a] in the 0.0..1.0 range. +:return: The current color array (when getting), or None (when setting). +`; + + +// +// transform +// +prosperon.c_types.transform[prosperon.DOC] = {} +prosperon.c_types.transform[prosperon.DOC][prosperon.DOC] = `A hierarchical transform storing 3D or 2D position, rotation (as a quaternion), +and scale. Can have a parent transform. Freed automatically on GC. +`; + +prosperon.c_types.transform[prosperon.DOC].pos = `Get or set the transform's position as a 3D vector [x, y, z]. + +:param value: (when setting) [x, y, z]. +:return: The current position vector (when getting), or None (when setting). +`; + +prosperon.c_types.transform[prosperon.DOC].scale = `Get or set the transform's scale as a 3D vector [x, y, z]. +For 2D usage, z is often 1. + +:param value: (when setting) [sx, sy, sz]. +:return: The current scale (when getting), or None (when setting). +`; + +prosperon.c_types.transform[prosperon.DOC].rotation = `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. + +:param value: (when setting) [qx, qy, qz, qw]. +:return: The current quaternion (when getting), or None (when setting). +`; + +prosperon.c_types.transform[prosperon.DOC].parent = `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. + +:param value: (when setting) Another transform or undefined. +:return: The current parent transform (when getting), or None (when setting). +`; + +prosperon.c_types.transform[prosperon.DOC].change_hook = `A user-supplied function that's called whenever the transform's local matrix changes. +If undefined, no hook is called. + +:param value: (when setting) A function. +:return: The current function or undefined. +`; + +prosperon.c_types.transform[prosperon.DOC].trs = `Set the transform's position, rotation, and scale in one call. + +:param pos: [x,y,z] for position, or undefined to keep existing. +:param quat: [qx,qy,qz,qw] for rotation, or undefined. +:param scale: [sx,sy,sz] for scale, or undefined. +:return: None +`; + +prosperon.c_types.transform[prosperon.DOC].phys2d = `Apply simple 2D velocity and angular velocity to this transform. + +:param velocity: [vx, vy] added to 'pos' each frame. +:param angularVel: A scalar for rotation in (radians/second). +:param dt: The time delta in seconds. +:return: None +`; + +prosperon.c_types.transform[prosperon.DOC].move = `Translate this transform by the specified vector. + +:param delta: [dx, dy, dz] to add to .pos +:return: None +`; + +prosperon.c_types.transform[prosperon.DOC].rotate = `Rotate this transform by an axis+angle. + +:param axis: [ax, ay, az] the axis of rotation. +:param angle: The angle in turns or radians (depending on usage). +:return: None +`; + +prosperon.c_types.transform[prosperon.DOC].angle = `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. + +:param axis: Which axis [1,0,0] or [0,1,0] or [0,0,1]. +:return: The numeric angle in 'turns' or radians, depending on usage. +`; + +prosperon.c_types.transform[prosperon.DOC].lookat = `Rotate this transform so it looks toward the given world position. + +:param target: [x, y, z] position in world coords. +:return: None +`; + +prosperon.c_types.transform[prosperon.DOC].direction = `Rotate a vector by this transform's rotation, effectively "transforming" +a direction from local space to world space. + +:param localDir: [dx, dy, dz] in local transform coordinates. +:return: [dx', dy', dz'] direction in world space. +`; + +prosperon.c_types.transform[prosperon.DOC].unit = `Reset position, rotation, and scale to [0,0,0], identity rotation, and [1,1,1]. + +:return: None +`; + +prosperon.c_types.transform[prosperon.DOC].rect = `Set this transform's pos and scale from a 2D rect object {x, y, w, h}. + +:param rect: Object with .x, .y, .w, .h +:return: None +`; + +prosperon.c_types.transform[prosperon.DOC].array = `Return this transform's matrix as a 16-element float array in column-major order. + +:return: An array of 16 floats. +`; + +prosperon.c_types.transform[prosperon.DOC].torect = `Convert transform's 2D position/scale to a rect {x, y, w, h}. +Rotation is currently ignored. + +:return: A rect object {x, y, w, h}. +`; + +prosperon.c_types.transform[prosperon.DOC].children = `Return an array of child transforms belonging to this transform. + +:return: An array of transform objects. +`; + + +// +// font +// +prosperon.c_types.font[prosperon.DOC] = {} +prosperon.c_types.font[prosperon.DOC][prosperon.DOC] = `A bitmap or TTF-based font object storing glyph data. +Used for measuring/drawing text. Freed when GC sees no references. +`; + +prosperon.c_types.font[prosperon.DOC].linegap = `Get or set the font's additional line spacing above the built-in metrics. + +:param value: (when setting) The new line gap. +:return: The current line gap (when getting), or None (when setting). +`; + +prosperon.c_types.font[prosperon.DOC].height = `The baseline-to-baseline height in pixels. + +:return: The font's total height in px. +`; + +prosperon.c_types.font[prosperon.DOC].ascent = `How far above the baseline the font extends. + +:return: A scalar float for ascent. +`; + +prosperon.c_types.font[prosperon.DOC].descent = `How far below baseline the font extends. + +:return: A scalar float for descent. +`; + +prosperon.c_types.font[prosperon.DOC].text_size = `Measure a piece of text's width/height when rendered with this font. + +:param text: The string to measure. +:param letterSpacing: Extra spacing between characters. +:param wrap: If nonzero, word-wrap to this maximum width. +:return: [width, height] as a float array. +`; + + +// +// datastream +// +prosperon.c_types.datastream[prosperon.DOC]= {} +prosperon.c_types.datastream[prosperon.DOC][prosperon.DOC] = `A streaming media handle, typically for MPEG video. Freed automatically. +`; + +prosperon.c_types.datastream[prosperon.DOC].time = `Return the current playback time in seconds. + +:return: Current time as a float in seconds. +`; + +prosperon.c_types.datastream[prosperon.DOC].seek = `Seek to the specified time (in seconds). + +:param seconds: The time to jump to in the stream. +:return: None +`; + +prosperon.c_types.datastream[prosperon.DOC].advance = `Advance by a certain number of seconds, decoding video as needed. + +:param seconds: The amount of time to skip forward. +:return: None +`; + +prosperon.c_types.datastream[prosperon.DOC].duration = `Return the total duration of the video stream, in seconds, if known. + +:return: Float seconds duration, or 0 if unknown. +`; + +prosperon.c_types.datastream[prosperon.DOC].framerate = `Return the framerate (FPS) of the stream if known. + +:return: Float frames per second, or 0 if unknown. +`; + +prosperon.c_types.datastream[prosperon.DOC].callback = `A function to call whenever a new frame is decoded. If not set, no callback is invoked. + +:param fn: (when setting) A function that receives (surface). +:return: The existing function or undefined if none. +`; + + +// +// timer +// +prosperon.c_types.timer[prosperon.DOC] = {} +prosperon.c_types.timer[prosperon.DOC][prosperon.DOC] = `A scheduled callback or countdown. Freed automatically once no longer referenced +or once it completes. +`; + +prosperon.c_types.timer[prosperon.DOC].remain = `Get or set how many seconds remain before the timer triggers. + +:param value: (when setting) A float specifying new time remaining. +:return: The current time left (when getting), or None (when setting). +`; + +prosperon.c_types.timer[prosperon.DOC].fn = `Get or set the function called when the timer expires. + +:param value: (when setting) The function. +:return: The function or undefined if none is set. +`; + + +// +// rtree +// +prosperon.c_types.rtree[prosperon.DOC] = {} +prosperon.c_types.rtree[prosperon.DOC][prosperon.DOC] = `An R-tree for spatial lookups. Insert bounding boxes, query by bounding box, etc. +`; + +prosperon.c_types.rtree[prosperon.DOC].add = `Insert an object that has a 'rect' property {x, y, w, h} into the tree. + +:param obj: The object to add (must have rectAtom). +:return: None +`; + +prosperon.c_types.rtree[prosperon.DOC].delete = `Remove an object from the tree. Must match the same rect as used when adding. + +:param obj: The object to remove. +:return: None +`; + +prosperon.c_types.rtree[prosperon.DOC].query = `Return an array of objects whose bounding boxes intersect the given rect. + +:param rect: {x, y, w, h} bounding region to query. +:return: Array of objects that overlap that region. +`; + +prosperon.c_types.rtree[prosperon.DOC].size = `Indicates how many items are stored in the rtree. + +:return: Integer count of items in the tree. +`; + +prosperon.c_types.rtree[prosperon.DOC].forEach = `Call a function for every item in the rtree. + +:param callback: A function called with no arguments, or possibly (item). +:return: None +`; + +prosperon.c_types.rtree[prosperon.DOC].has = `Return true if the specified object is in the tree, false otherwise. + +:param obj: The object to check. +:return: True if found, else false. +`; + +prosperon.c_types.rtree[prosperon.DOC].values = `Return an array of all items currently in the rtree. + +:return: Array of all stored objects. +`; + + +// +// PHYSFS_File +// +prosperon.c_types.PHYSFS_File[prosperon.DOC] = {} +prosperon.c_types.PHYSFS_File[prosperon.DOC][prosperon.DOC] = `A file handle opened via PhysFS for writing or reading. Freed automatically when references go away. +`; + +prosperon.c_types.PHYSFS_File[prosperon.DOC].close = `Close this file handle. Throws on error. + +:return: None +`; + +prosperon.c_types.PHYSFS_File[prosperon.DOC].write = `Write data (string or ArrayBuffer) to the file. Throws on error. + +:param data: The data to write (string or ArrayBuffer). +:return: None +`; + +prosperon.c_types.PHYSFS_File[prosperon.DOC].buffer = `Enable an internal write buffer of the given size on this file. + +:param size: Size in bytes of the buffer. +:return: None +`; + +prosperon.c_types.PHYSFS_File[prosperon.DOC].tell = `Return the current position in the file. + +:return: A numeric offset. +`; + +prosperon.c_types.PHYSFS_File[prosperon.DOC].eof = `Return whether the file pointer is at end-of-file. + +:return: True if at EOF, false otherwise. +`; + + +// +// SDL_Camera +// +prosperon.c_types.SDL_Camera[prosperon.DOC] = {} +prosperon.c_types.SDL_Camera[prosperon.DOC][prosperon.DOC] = `A handle to a physical camera device. Freed when references drop or camera is closed. +`; + +prosperon.c_types.SDL_Camera[prosperon.DOC].frame = `Acquire the latest camera frame (as an SDL_Surface). Returns undefined if no +new frame is available yet. Throws on error. + +:return: SDL_Surface or undefined. +`; + +prosperon.c_types.SDL_Camera[prosperon.DOC].release_frame = `Release a frame surface previously acquired via camera.frame(). Must be +done for each acquired frame. + +:param surface: The surface to release. +:return: None +`; + + +// +// SDL_Cursor +// +prosperon.c_types.SDL_Cursor[prosperon.DOC] = {} +prosperon.c_types.SDL_Cursor[prosperon.DOC][prosperon.DOC] = `An SDL cursor handle. Freed automatically on GC. No direct methods. +`; + + +// +// SDL_Thread +// +prosperon.c_types.SDL_Thread[prosperon.DOC] = {} +prosperon.c_types.SDL_Thread[prosperon.DOC][prosperon.DOC] = `A handle to an SDL-created thread. Freed on GC after join. + +Note: The engine generally doesn't expose custom usage for threads. +`; + +prosperon.c_types.SDL_Thread[prosperon.DOC].wait = `Block until this thread terminates. + +:return: None +`; + + +// +// SDL_Window +// +prosperon.c_types.SDL_Window[prosperon.DOC] = {} +prosperon.c_types.SDL_Window[prosperon.DOC][prosperon.DOC] = `An application window, created via prosperon.engine_start or SDL calls. Freed on GC. +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].fullscreen = `Toggle fullscreen mode for this window (SDL_WINDOW_FULLSCREEN). + +:return: None +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].make_renderer = `Create an SDL_Renderer for 2D rendering tied to this window. + +:param name: The renderer driver name, e.g. "opengl" (may be optional). +:return: An SDL_Renderer object. +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].make_gpu = `Create an SDL_GPUDevice for low-level GPU rendering on this window. + +:param debug: If true, enable debugging in the GPU device. +:param driverName: The GPU back-end driver, e.g. "opengl". +:return: An SDL_GPUDevice. +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].keyboard_shown = `Return whether the on-screen keyboard is visible (mobile/tablet). + +:return: True if shown, false otherwise. +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].theme = `Currently returns undefined. Placeholder for retrieving OS window theme info. + +:return: undefined +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].safe_area = `Return a rect describing any OS-specific "safe" region for UI, e.g. on iPhone with a notch. + +:return: A rect object {x, y, w, h}. +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].bordered = `Enable or disable window borders. + +:param flag: True to show borders, false to hide. +:return: None +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].set_icon = `Set the window's icon from an SDL_Surface. + +:param surface: An SDL_Surface holding the icon. +:return: None +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].mouse_grab = `Grab or ungrab the mouse for this window (so the pointer won't leave). + +:param flag: True to grab mouse input, false to release. +:return: None +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].title = `Get or set the window's title text in the title bar. + +:param newTitle: (when setting) A string title. +:return: The current title if getting, or None if setting. +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].size = `Get or set the window's size as [width, height]. + +:param newSize: (when setting) e.g. [640, 480] +:return: The current [width, height] or None if setting. +`; + + +// +// SDL_Renderer +// +prosperon.c_types.SDL_Renderer[prosperon.DOC] = {} +prosperon.c_types.SDL_Renderer[prosperon.DOC][prosperon.DOC] = `A 2D rendering context using the SDL renderer API. Freed automatically. +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].draw_color = `Set the render draw color for subsequent primitive calls (rect, line, etc.). + +:param color: [r, g, b, a] in 0..1. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].present = `Display whatever has been rendered (swap buffers). Must be called each frame. + +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].clear = `Clear the current render target with the renderer's draw color. + +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].rect = `Draw one or more outlines of rectangles. + +:param rectOrArray: A single rect {x,y,w,h} or an array of rects. +:param color: Optional [r,g,b,a]. If provided, overrides current draw color. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].fillrect = `Fill one or more rectangles with the renderer's current color or an optional override. + +:param rectOrArray: A single rect {x,y,w,h} or an array of rects. +:param color: Optional [r,g,b,a]. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].line = `Draw a sequence of lines connecting points in an array. + +:param points: An array of [x,y] points. Lines connect consecutive points. +:param color: Optional [r,g,b,a]. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].point = `Draw a list of points (pixels). + +:param points: An array of [x,y] positions. +:param color: Optional [r,g,b,a]. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].load_texture = `Create an SDL_Texture from a given SDL_Surface for use with this renderer. + +:param surface: An SDL_Surface. +:return: An SDL_Texture object. +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].texture = `Draw a texture onto the render target. + +:param tex: The SDL_Texture to draw. +:param dstRect: The destination rect {x, y, w, h}. +:param srcRect: Optional portion of the texture to draw {x, y, w, h}. +:param color: Optional color mod [r,g,b,a]. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].slice9 = `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. + +:param tex: The SDL_Texture. +:param dstRect: Destination region {x, y, w, h}. +:param edges: {l, r, t, b} for corner sizes in pixels. +:param srcRect: Optional portion in the texture. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].tile = `Tile a texture repeatedly within the specified region. Optionally use a srcRect. + +:param tex: The SDL_Texture to tile. +:param dstRect: The region to fill {x, y, w, h}. +:param srcRect: Optional portion of texture. +:param scale: A float scale factor for each tile. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].get_image = `Read back the rendered pixels into a new SDL_Surface. If rect is undefined, capture entire output. + +:param rect: Optional {x,y,w,h}. +:return: An SDL_Surface with the requested region's pixels. +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].fasttext = `Draw debug text using an internal fast path. Typically used for quick debugging overlays. + +:param text: The string to draw. +:param pos: The [x, y] position to draw text. +:param color: Optional [r,g,b,a]. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].geometry = `Render custom geometry from a mesh object {pos, uv, color, indices, count} with an optional texture. + +:param texture: The SDL_Texture or undefined. +:param meshObject: The geometry data with typed arrays. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].scale = `Set a scaling factor for all subsequent rendering on this renderer. + +:param scaleVec2: [sx, sy] scaling factors. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].logical_size = `Set a "logical" size that the renderer will scale to. +For example, (320, 240) can auto-scale up to the window resolution. + +:param size: [width, height]. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].viewport = `Set the clipping viewport for rendering. Pass undefined to use the full render target. + +:param rect: {x, y, w, h}, or undefined. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].clip = `Set or clear the clipping rectangle for drawing. Pass undefined to clear. + +:param rect: {x, y, w, h} or undefined. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].vsync = `Enable or disable vertical sync. This may have no effect depending on the driver. + +:param flag: True or false. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].coords = `Convert window coordinates to this renderer's coordinate space. + +:param pos: [x, y] in window space. +:return: [x, y] in renderer coordinate space. +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].camera = `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. + +:param cameraTransform: The transform whose pos is used. +:param centered: Boolean true or false. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].get_viewport = `Return the current viewport rect. + +:return: {x, y, w, h} +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].screen2world = `Convert a screen coordinate to world space based on the current camera transform. + +:param pos: [x, y] screen coords +:return: [wx, wy] in world space +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].target = `Set or clear the current render target texture. Pass undefined to reset to the default/window. + +:param texture: An SDL_Texture or undefined +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].make_sprite_mesh = `Generate a mesh from an array of sprite objects, combining their positions, UVs, +and colors into a single geometry block. + +:param sprites: An array of sprite-like objects. +:return: A 'mesh' object with pos, uv, color, indices, etc. +`; + + +// +// SDL_Texture +// +prosperon.c_types.SDL_Texture[prosperon.DOC] = {} +prosperon.c_types.SDL_Texture[prosperon.DOC][prosperon.DOC] = `A 2D GPU-accelerated texture for rendering with SDL_Renderer. Freed automatically. +`; + +prosperon.c_types.SDL_Texture[prosperon.DOC].mode = `Set texture scale mode or filtering mode (nearest/linear). + +:param mode: A string or numeric mode to set (e.g., 'linear'). +:return: None +`; + +// +// SDL_Surface +// +prosperon.c_types.SDL_Surface[prosperon.DOC] = {} +prosperon.c_types.SDL_Surface[prosperon.DOC][prosperon.DOC] = `A software (CPU) image in memory. Freed when references vanish. Typically converted +to SDL_Texture for drawing, or used as raw pixel data. +`; + +prosperon.c_types.SDL_Surface[prosperon.DOC].blit = `Blit (copy) another surface onto this surface, scaling if needed. + +:param dstRect: Destination {x, y, w, h} +:param srcSurface: The source SDL_Surface +:param srcRect: {x, y, w, h} portion from source +:return: None +`; + +prosperon.c_types.SDL_Surface[prosperon.DOC].scale = `Return a new SDL_Surface scaled to [width, height] using linear filtering. + +:param newSize: [width, height] +:return: A new SDL_Surface with the scaled result. +`; + +prosperon.c_types.SDL_Surface[prosperon.DOC].fill = `Fill the entire surface with a single color. + +:param color: [r, g, b, a] in 0..1 +:return: None +`; + +prosperon.c_types.SDL_Surface[prosperon.DOC].rect = `Fill a sub-rectangle of the surface with a color. + +:param rect: {x, y, w, h} +:param color: [r, g, b, a] +:return: None +`; + +prosperon.c_types.SDL_Surface[prosperon.DOC].dup = `Make a copy of this surface in RGBA format. + +:return: A new SDL_Surface copy. +`; + + +// +// SDL_GPUDevice +// +prosperon.c_types.SDL_GPUDevice[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUDevice[prosperon.DOC][prosperon.DOC] = `A handle for low-level GPU operations via SDL GPU. Freed on GC. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].claim_window = `Claim an existing SDL_Window so this GPU device can render to it. + +:param window: The SDL_Window to attach. +:return: None +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].make_pipeline = `Create a new graphics pipeline from a descriptor object specifying shaders, +blend states, vertex format, etc. + +:param pipelineDesc: An object containing pipeline fields (vertexShader, blend, etc.). +:return: A SDL_GPUGraphicsPipeline handle. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].compute_pipeline = `Create a compute pipeline from a descriptor (shader code, threadgroup sizes, etc.). + +:param desc: An object with shader code, thread counts, etc. +:return: SDL_GPUComputePipeline handle. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].set_swapchain = `Specify how the swapchain (final rendered image) is composed, e.g. 'sdr', 'hdr', +and present mode like 'vsync' or 'immediate'. + +:param composition: E.g. 'sdr', 'linear', or 'hdr'. +:param presentMode: E.g. 'vsync', 'immediate', 'mailbox'. +:return: None +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].sort_sprite = `A comparator function used for sorting sprite objects by layer, y, and texture. +Usually used internally. + +:param a: A sprite object. +:param b: Another sprite object. +:return: <0, 0, or >0 for sort ordering. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].make_sampler = `Create a sampler object specifying filtering, wrapping, anisotropy, etc. + +:param samplerDesc: An object with min_filter, mag_filter, etc. +:return: SDL_GPUSampler handle. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].load_texture = `Upload an SDL_Surface into a GPU texture, optionally compressing with DXT. Freed automatically. + +:param surface: An SDL_Surface. +:param compressionLevel: 0=none, 1=DXT1 or DXT5, 2=high quality, etc. +:return: SDL_GPUTexture +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].texture = `Create a GPU texture with the specified format usage. + +:param desc: Object with {width, height, layers, type, format, usage, etc.} +:return: SDL_GPUTexture +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].make_quad = `Return a simple 2-triangle quad geometry covering [0,1]x[0,1]. +Useful for post-processing passes. + +:return: A mesh {pos, uv, color, indices}. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].driver = `Return the name of the underlying GPU driver in use (e.g. 'OpenGL'). + +:return: A string with driver name. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].make_shader = `Compile raw shader code (vertex or fragment) in e.g. SPIR-V, MSL, or DXIL format. + +:param desc: {code:ArrayBuffer, stage:'vertex'|'fragment', format:'spv'|..., entrypoint:'main', ...} +:return: SDL_GPUShader object +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].acquire_cmd_buffer = `Obtain a new command buffer for recording GPU commands. Must be submitted or canceled. + +:return: SDL_GPUCommandBuffer handle +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].upload = `Upload CPU data into a list of GPU buffers, optionally reusing or returning a +transfer buffer. Typically you provide (cmdBuf, arrayOfTypedArrays, [transferBuffer]). + +:param cmdBuffer: The command buffer in which to record copy commands. +:param buffers: An array of typed-array data to upload, each must have a 'gpu' property or so. +:param transferBuffer: Optional existing GPU transfer buffer to reuse. +:return: The transfer buffer used or newly created. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].wait_for_fences = `Wait on an array of GPU fence objects, optionally requiring all or any. + +:param fences: An array of SDL_GPUFence objects. +:param waitAll: Boolean, true to wait for all fences, false for any. +:return: True if fences signaled, false on timeout or error. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].query_fence = `Check if the given fence has been signaled yet. Non-blocking. + +:param fence: SDL_GPUFence handle +:return: True if signaled, false if still pending +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].shader_format = `Return an array of supported GPU shader binary formats (like 'spv', 'dxbc', etc.). + +:return: Array of strings naming supported formats. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].slice9 = `Generate a 9-slice tiling geometry in one shot. For advanced usage with GPU pipeline. + +:param texture: An SDL_GPUTexture +:param dstRect: The rectangle {x, y, w, h} +:param edges: {l, r, t, b} edge sizes +:return: A mesh object +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].tile = `Generate geometry to tile a texture portion inside a dest rect. +Often used for repeating backgrounds. + +:param texture: The SDL_GPUTexture +:param srcRect: The portion to tile in pixels +:param dstRect: Where to fill +:param tileInfo: e.g. {repeat_x:true, repeat_y:true} +:return: A mesh object +`; + + +// +// SDL_GPUCommandBuffer +// +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC][prosperon.DOC] = `A command buffer that accumulates rendering, copy, and compute operations. Freed after submission or GC. +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].render_pass = `Begin a render pass with color/depth attachments. Provide an object with +'color_targets' and optional 'depth_stencil'. Returns an SDL_GPURenderPass handle. + +:param passDesc: {color_targets:[...], depth_stencil:...} +:return: SDL_GPURenderPass +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].compute_pass = `Begin a compute pass reading/writing given arrays of textures and buffers. + +:param storageTextures: array of read/write textures +:param storageBuffers: array of read/write buffers +:return: SDL_GPUComputePass +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].swapchain_pass = `Begin a render pass that directly targets the swapchain (the window). Clears +with the specified color. + +:param clearColor: [r,g,b,a] +:return: SDL_GPURenderPass +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].acquire_swapchain = `Acquire the current swapchain texture from the window. Internal usage. + +:return: SDL_GPUTexture handle +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].bind_vertex_buffer = `Bind a GPU buffer as the vertex buffer at a given slot. + +:param slot: Integer slot index. +:param buffer: The SDL_GPUBuffer. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].bind_index_buffer = `Bind a GPU buffer as the index buffer (16-bit or 32-bit). + +:param buffer: The SDL_GPUBuffer. +:param offset: Optional offset in bytes. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].bind_fragment_sampler = `Bind a texture+sampler pair to a particular fragment shader slot. + +:param slot: Index of the sampler binding. +:param texture: The SDL_GPUTexture +:param sampler: The SDL_GPUSampler +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].push_vertex_uniform_data = `Push raw data to a vertex shader uniform block. + +:param slot: The uniform buffer slot. +:param data: An ArrayBuffer with the data to upload. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].push_fragment_uniform_data = `Push raw data to a fragment shader uniform block. + +:param slot: The uniform buffer slot index. +:param data: An ArrayBuffer with uniform data. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].push_compute_uniform_data = `Push raw data to a compute shader uniform buffer. + +:param slot: The uniform buffer slot. +:param data: An ArrayBuffer with the data. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].submit = `Submit this command buffer to the GPU and return a fence for synchronization. + +:return: An SDL_GPUFence +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].cancel = `Cancel (discard) this command buffer without submitting. + +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].camera = `Write a camera transform (projection/view) to a uniform slot for 3D or 2D usage. + +:param cameraTransform: A camera object or transform with .pos, fov, etc. +:param uniformSlot: The integer uniform buffer slot to which data is pushed. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].hud = `Write an orthographic full-screen "HUD" matrix to a uniform slot. Typically used +for 2D overlays. + +:param sizeVec2: [width, height] of the viewport area. +:param uniformSlot: The integer uniform buffer slot. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].push_debug_group = `Push a named debug group marker onto the GPU command list (for debuggers/profilers). + +:param name: The debug label string. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].pop_debug_group = `Pop the most recent debug group marker. + +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].debug_label = `Insert a one-off debug label at the current spot in the command list. + +:param label: The debug label string +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].blit = `Blit one GPU texture to another with optional flip mode, filter, and clear operations. + +:param blitDesc: { src:{texture,mip_level, etc}, dst:{texture,...}, load_op, flip, filter, clear_color:[r,g,b,a] } +:return: None +`; + + +// +// SDL_GPURenderPass +// +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC] = {} +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC][prosperon.DOC] = `A single pass of drawing commands with color/depth attachments. Freed after end() or GC. +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_pipeline = `Bind a previously created graphics pipeline (shaders, states, vertex layouts, etc.). + +:param pipeline: The SDL_GPUGraphicsPipeline +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].viewport = `Set the viewport for clipping or scaling draws, in pass-local coordinates. + +:param rect: {x,y,w,h} +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].scissor = `Set a scissor rectangle for discarding pixels outside it. + +:param rect: {x,y,w,h} +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].draw = `Issue a non-indexed draw call. + +:param primitiveType: e.g. SDL_GPU_PRIMITIVETYPE_TRIANGLELIST +:param baseVertex: Starting vertex offset. +:param firstVertex: The first vertex to draw. +:param vertexCount: How many vertices to draw. +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].draw_indexed = `Issue an indexed draw call from the bound index buffer. + +:param primitiveType: The primitive type constant. +:param baseVertex: Offset in the vertex buffer. +:param firstIndex: Which index to start from. +:param indexCount: Number of indices to draw. +:param instanceCount: For instanced drawing, or 1 if normal. +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].end = `End this render pass, finalizing the draw operations. + +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_index_buffer = `Bind an index buffer inside this pass, possibly overriding the global one. + +:param buffer: The SDL_GPUBuffer +:param elementSize16bit: If 2, uses 16-bit indices; if 4, uses 32-bit indices +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_buffers = `Bind multiple vertex buffers at consecutive slots. + +:param firstSlot: The starting vertex buffer slot. +:param arrayOfBuffers: An array of GPUBuffer objects +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_samplers = `Bind multiple texture/sampler pairs to either vertex or fragment slots. + +:param vertexOrFragment: Boolean, true for vertex stage, false for fragment. +:param firstSlot: The first sampler slot to bind. +:param samplerBindings: An array of {texture, sampler}. +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_storage_buffers = `Bind one or more storage buffers for read/write in the pipeline. + +:param firstSlot: Starting buffer slot index. +:param buffers: An array of SDL_GPUBuffer objects. +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_storage_textures = `Bind one or more storage textures for read/write in the pipeline. + +:param firstSlot: Starting texture slot index. +:param textures: An array of SDL_GPUTexture objects. +:return: None +`; + +// +// SDL_GPUComputePass +// +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC][prosperon.DOC] = `A compute pass for dispatching compute pipelines. Freed after end() or GC. +`; + +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].dispatch = `Dispatch the compute pipeline with the specified threadgroup counts. + +:param x: Number of groups in X dimension +:param y: Number of groups in Y dimension +:param z: Number of groups in Z dimension +:return: None +`; + +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].end = `End this compute pass. + +:return: None +`; + +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].pipeline = `Bind a compute pipeline in this pass. + +:param computePipeline: The SDL_GPUComputePipeline +:return: None +`; + +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].samplers = `Bind a set of texture/sampler pairs for compute usage. + +:param arrayOfSamplerBindings: e.g. [ {texture, sampler}, ...] +:param firstSlot: The starting sampler slot. +:return: None +`; + +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].storage_buffers = `Bind an array of storage buffers for the compute shader. + +:param arrayOfBuffers: The buffers +:param firstSlot: Starting binding slot. +:return: None +`; + +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].storage_textures = `Bind an array of storage textures for the compute shader. + +:param arrayOfTextures: The textures +:param firstSlot: Starting binding slot +:return: None +`; + + +// +// SDL_GPUCopyPass +// +prosperon.c_types.SDL_GPUCopyPass[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUCopyPass[prosperon.DOC][prosperon.DOC] = `A pass for CPU<->GPU or GPU<->GPU copy operations. No direct JS API besides internal usage. +`; + +// +// SDL_GPUFence +// +prosperon.c_types.SDL_GPUFence[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUFence[prosperon.DOC][prosperon.DOC] = `A GPU fence for synchronization. Created upon commandBuffer.submit(). +Wait or query it with device.wait_for_fences or device.query_fence. +`; + +// +// SDL_GPUTransferBuffer +// +prosperon.c_types.SDL_GPUTransferBuffer[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUTransferBuffer[prosperon.DOC][prosperon.DOC] = `A staging buffer used for copying data to or from GPU buffers/textures. Typically +allocated/used internally by device.upload(...). +`; + +// +// SDL_GPUShader +// +prosperon.c_types.SDL_GPUShader[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUShader[prosperon.DOC][prosperon.DOC] = `A single compiled shader (vertex or fragment) in a GPU-friendly format +(e.g., SPIR-V, MSL). Combined into a pipeline for drawing. +`; + +// +// SDL_GPUSampler +// +prosperon.c_types.SDL_GPUSampler[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUSampler[prosperon.DOC][prosperon.DOC] = `Defines how a texture is sampled (filter mode, address mode, anisotropy, compare op, etc.). +`; + +// +// SDL_GPUGraphicsPipeline +// +prosperon.c_types.SDL_GPUGraphicsPipeline[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUGraphicsPipeline[prosperon.DOC][prosperon.DOC] = `Encapsulates vertex+fragment shaders, blend/cull states, and vertex attribute layouts. +Created via device.make_pipeline(...). +`; + +// +// SDL_GPUComputePipeline +// +prosperon.c_types.SDL_GPUComputePipeline[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUComputePipeline[prosperon.DOC][prosperon.DOC] = `Encapsulates a compute shader program plus associated resource layouts. +Created via device.compute_pipeline(...). +`; + + var listeners = new Map() prosperon.on = function(type, callback) { @@ -270,7 +1406,7 @@ globalThis.use = function use(file) { return use_cache[file] } -use[prosperon.DOC] = 'Return the value from the provided path to a module'. +//use[prosperon.DOC] = 'Return the value from the provided path to a module'. globalThis.json = use('json') @@ -297,7 +1433,7 @@ function parse_file(content) { ////////////////// // REGISTRANT ///////////////// -var Register = { +globalThis.Register = { registries: [], add_cb(name) { @@ -549,28 +1685,6 @@ Register[prosperon.DOC] = { check_registers: `Automatically register recognized events (like 'update', 'gui', etc.) on an object.`, } -// Document some engine-internal symbols and utility functions -var engineDoc = { - doc: `Misc. internal references and symbols used by Prosperon engine for actor lifecycle and script handling.`, - DEAD: `Symbol marking an actor as dead.`, - GARBAGE: `Symbol referencing an actor's optional garbage callback.`, - FILE: `Symbol storing the script filename for this actor.`, - TIMERS: `Symbol storing an array of active delayed calls (timers) on an actor.`, - REGGIES: `Symbol referencing the event registry list for an actor.`, - UNDERLINGS: `Symbol referencing a Set of child actors spawned by this actor.`, - OVERLING: `Symbol referencing this actor's parent (the actor that spawned it).`, - use: `Load or retrieve a module from cache, from either an embedded or dynamic library (.so/.dll).`, - script_fn: `Parse a script and return compiled module/program sections (if any).`, - bare_load: `Attempt to load a module either from embed or a native library. Returns the loaded module or undefined.`, - parse_file: `Split a script file content into module and program sections. Module must end with a 'return' statement.`, - print_api: `Debug utility that prints the properties (API) of an object.`, - pprint: `Internal printing helper that formats logs and sends them to console, file, and Tracy if present.`, - res_cache: `Cache object that may store loaded resources (scripts, data, etc.).`, - use_cache: `Cache object that stores previously loaded modules/scripts.`, - json: `Reference to the JSON module used globally for parse/stringify.`, - mixin_color: `Inject color-related mixin methods into globalThis.`, - so_ext: `Platform-specific extension for dynamic libraries ('.so' on Unix-like, '.dll' on Windows).` -} -prosperon.engineDoc = engineDoc + })() diff --git a/scripts/modules/doc.js b/scripts/modules/doc.js index 477ac1f5..c675c05b 100644 --- a/scripts/modules/doc.js +++ b/scripts/modules/doc.js @@ -1,285 +1,285 @@ -var ret = {} +function docOf(obj, prop) { + // Grab the top-level doc block on the object. + var block = obj[prosperon.DOC]; + if (!block) return ''; -var io = use('io') - -// Helper: Given an object `obj`, return either: -// - If there's no prosperon.DOC, return ''. -// - If obj[prosperon.DOC] is a string, return that (unless a sub-property was requested). -// - If obj[prosperon.DOC] is an object, return its .doc field if no prop, or doc for that prop if provided. -var docOf = function(obj, prop) { - var block = obj[prosperon.DOC] + // 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 ''. if (typeof block === 'string') { - if (prop) return '' - return block + return prop ? '' : block; } - if (!block || typeof block !== 'object') return '' - if (!prop) return block.doc || '' - return block[prop] || '' + + // 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. + if (typeof block === 'object') { + // 2a) If no property was requested, return block.doc or block[prosperon.DOC], if either is a string. + if (!prop) { + if (typeof block.doc === 'string') { + return block.doc; + } + if (typeof block[prosperon.DOC] === 'string') { + return block[prosperon.DOC]; + } + return ''; + } + + // 2b) If a property is requested, see if there's a doc for that property inside the block. + 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; + } + if (typeof subBlock[prosperon.DOC] === 'string') { + return subBlock[prosperon.DOC]; + } + return ''; + } + } + + // If nothing matched, return empty. + return ''; } -// Reusable doc parsing logic for rewriting :param and :return. + function parseDocStr(docStr) { - var out = [] - if (!docStr) return out + if (!docStr) return []; - var docLines = docStr.split('\n') - var paramRe = /^:param\s+([A-Za-z0-9_]+)\s*:\s*(.*)$/ - var returnRe = /^:return:\s*(.*)$/ + var lines = docStr.split('\n'); + var paramRe = /^:param\s+([A-Za-z0-9_]+)\s*:\s*(.*)$/; + var returnRe = /^:return:\s*(.*)$/; - for (var j = 0; j < docLines.length; j++) { - var line = docLines[j] - var pm = paramRe.exec(line) - var rm = returnRe.exec(line) + // 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 + + 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 + descLines.push(''); + continue; + } + + var pm = paramRe.exec(line); + var rm = returnRe.exec(line); if (pm) { - out.push('**' + pm[1] + '**: ' + pm[2]) - out.push('') + // param line → store in paramLines + paramLines.push('**' + pm[1] + '**: ' + pm[2]); + paramLines.push(''); } else if (rm) { - out.push('**Returns**: ' + rm[1]) - out.push('') + // return line → store in returnLines + returnLines.push('**Returns**: ' + rm[1]); + returnLines.push(''); } else { - out.push(line) + // Otherwise, it's a general description line + descLines.push(line); } } - return out + + // Now reassemble in the fixed order: + // 1) description lines, 2) param lines, 3) returns lines + var final = []; + + if (descLines.length) { + final.push.apply(final, descLines); + // Insert blank line if needed + if (paramLines.length || returnLines.length) { + final.push(''); + } + } + + if (paramLines.length) { + final.push.apply(final, paramLines); + } + + if (returnLines.length) { + // If there were param lines, ensure blank line before the returns + if (paramLines.length && returnLines[0] !== '') { + final.push(''); + } + final.push.apply(final, returnLines); + } + + return final; } -// Recursively write docs for an object and its sub-objects. -// level -> how many '#' in our markdown heading -// name -> the name of this object in the heading -function writeDocsForObject(obj, lines, level, name) { - var docStr = docOf(obj) - if (docStr) { - // Print heading for the object itself - var headingLine = Array(level + 1).join('#') + ' ' + name + '\n' - lines.push(headingLine) - var docOut = parseDocStr(docStr) - if (docOut.length > 0) lines.push(docOut.join('\n') + '\n') + +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) +} + +function walkObject(obj, lines, level, name) { + // See what doc string (if any) this object has + 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'); } - // Enumerate properties - for (var prop in obj) { - if (!obj.hasOwnProperty(prop)) continue - var val = obj[prop] - var valDoc = val && (val[prosperon.DOC] || docOf(obj, prop)) || '' + // Now enumerate this object's direct properties + var propNames = Object.keys(obj); + for (var i = 0; i < propNames.length; i++) { + var prop = propNames[i]; + if (prop === 'constructor') continue; - // If it's a function, print a heading like "## area(r)" - if (typeof val === 'function') { - var paramMatches = [] - var docLines = valDoc.split('\n') - var paramRe = /^:param\s+([A-Za-z0-9_]+)\s*:\s*(.*)$/ - for (var j = 0; j < docLines.length; j++) { - var pm = paramRe.exec(docLines[j]) - if (pm) paramMatches.push(pm[1]) - } + var desc = Object.getOwnPropertyDescriptor(obj, prop); + if (!desc) continue; - var fnHeading = Array(level + 2).join('#') + ' ' + prop - // If paramMatches is not empty, list them in the heading - if (paramMatches.length > 0) fnHeading += '(' + paramMatches.join(', ') + ')\n' - else { - // fallback: parse from function signature - var m = val.toString().match(/\(([^)]*)\)/) - if (m) fnHeading += '(' + m[1].trim() + ')\n' - else fnHeading += '\n' - } + // Check if this is an accessor property (getter/setter) + var hasGetter = typeof desc.get === 'function'; + var hasSetter = typeof desc.set === 'function'; - lines.push(fnHeading) - var parsed = parseDocStr(valDoc) - if (parsed.length > 0) lines.push(parsed.join('\n') + '\n') + if (hasGetter || hasSetter) { + // We handle them as a single "property" entry, + // not separate get/set headings. + writeProperty(lines, obj, prop, desc, level); + continue; } - // If it's a nested object, recursively write docs for it - else if (val && typeof val === 'object') { - // We only bother if the sub-object has any doc - // or if there's a good reason to drill deeper. - // If we want to always print sub-objects, remove the doc check. - var subObjDoc = docOf(val) - if (subObjDoc) { - writeDocsForObject(val, lines, level + 1, prop) - } - // If subObjDoc is empty but the object might contain sub-doc for - // its methods, you may want to call writeDocsForObject anyway. - else { - // We can still check if any child function has a doc: - var hasChildWithDoc = false - for (var sp in val) { - if (!val.hasOwnProperty(sp)) continue - var subVal = val[sp] - if (subVal && typeof subVal === 'function' && (subVal[prosperon.DOC] || docOf(val, sp))) { - hasChildWithDoc = true - break - } + // Otherwise, if there's a "value" (could be a function or an object) + if ('value' in desc) { + var val = desc.value; + 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 (hasChildWithDoc) writeDocsForObject(val, lines, level + 1, prop) } } - // else (if it's something else, e.g. number/string) you might skip it or do something special } } -var docs = io.enumerate("scripts/modules", 0) -docs = docs.filter(x => io.match("**/*.js", x)).map(x => x.name()) +/** + * 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). + */ +function writeProperty(lines, parentObj, prop, desc, level) { + var heading = '#'.repeat(level + 2) + ' ' + prop; + lines.push(heading + '\n'); -var APIPATH = '.src/docs/api/modules' + var hasGetter = typeof desc.get === 'function'; + var hasSetter = typeof desc.set === 'function'; -ret.print_api = function(obj) { - // Old console-based printing. We'll leave as-is or minimal changes if desired. - var topDoc = docOf(obj) - if (topDoc) console.log(' doc: ' + topDoc) + if (hasGetter && !hasSetter) { + lines.push('(read only)\n'); + } else if (!hasGetter && hasSetter) { + lines.push('(set only)\n'); + } + // If both, we do nothing extra - for (var prop in obj) { - if (!obj.hasOwnProperty(prop)) continue - var val = obj[prop] - console.log(prop) + // Collect doc from the property-level doc block + // If that's empty, see if either accessor function has doc + var docStr = docOf(parentObj, prop); + if (!docStr && hasGetter) { + docStr = docOf(desc.get) || docStr; + } + if (!docStr && hasSetter) { + docStr = docOf(desc.set) || docStr; + } - var docStr = val[prosperon.DOC] || docOf(obj, prop) - if (docStr) console.log(' doc: ' + docStr) - - if (typeof val === 'function') { - var m = val.toString().match(/\(([^)]*)\)/) - if (m) console.log(' function: ' + prop + '(' + m[1].trim() + ')') - } + var docOut = parseDocStr(docStr); + if (docOut.length > 0) { + lines.push(docOut.join('\n') + '\n'); } } -ret.print_modules = function() { - for (var i = 0; i < docs.length; i++) { - var name = docs[i] - var mod = use(name) - console.log('MODULE: ' + name) - var modDoc = docOf(mod) - if (modDoc) console.log(' doc: ' + modDoc) - ret.print_api(mod) - console.log('') +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) { + var docStr = fn[prosperon.DOC] || docOf(parentObj, prop) || ''; + // parse :param lines + var paramNames = []; + + if (docStr) { + var docLines = docStr.split('\n'); + var paramRe = /^:param\s+([A-Za-z0-9_]+)\s*:\s*(.*)$/; + for (var j = 0; j < docLines.length; j++) { + var pm = paramRe.exec(docLines[j]); + if (pm) paramNames.push(pm[1]); + } + } + + 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 + var m = fn.toString().match(/\(([^)]*)\)/); + if (m && m[1].trim()) { + heading += '(' + m[1].trim() + ')'; + } + } + lines.push(heading + '\n'); + + // parse doc lines + var docOut = parseDocStr(docStr); + if (docOut.length > 0) { + lines.push(docOut.join('\n') + '\n'); } } -ret.write_modules = function() { - // rm all in APIPATH - var old = io.enumerate(APIPATH, 0) - old = old.filter(x => !io.match("**/index.md", x)) - old = old.filter(x => !io.match("**/c_types", x)) - old.forEach(x => io.rm(x)) - if (!io.exists(APIPATH)) io.mkdir(APIPATH) +writeDocFile[prosperon.DOC] = `Return a markdown string for a given obj, with optional title.`; - for (var i = 0; i < docs.length; i++) { - var name = docs[i] - var mod = use(name) - var lines = [] - - // Top-level heading for module - lines.push('# ' + name + '\n') - - // Recursively write docs for the module at heading level 1 - writeDocsForObject(mod, lines, 1, name) - - var out = lines.join('\n') - io.slurpwrite(APIPATH + '/' + name + '.md', out) - } -} - -ret.write_c_types = function() { - var CTYPEPATH = '.src/docs/api/types' - - // Remove old ctype docs except index.md - var old = io.enumerate(CTYPEPATH, 0) - old = old.filter(x => !io.match("**/index.md", x)) - old.forEach(x => io.rm(x)) - if (!io.exists(CTYPEPATH)) io.mkdir(CTYPEPATH) - - var cTypeNames = Object.keys(prosperon.c_types) - for (var i = 0; i < cTypeNames.length; i++) { - var name = cTypeNames[i] - var ctype = prosperon.c_types[name] - var lines = [] - - // Title - lines.push('# ' + name + '\n') - - // If the ctype itself has a docstring (string or object.doc), include it - var ctypeDoc = docOf(ctype) - if (ctypeDoc) lines.push(ctypeDoc + '\n') - - // Enumerate all own properties on the prototype (so we don't trigger getters) - var props = Object.getOwnPropertyNames(ctype) - - for (var p = 0; p < props.length; p++) { - var propName = props[p] - if (propName === 'constructor') continue - - var desc = Object.getOwnPropertyDescriptor(ctype, propName) - if (!desc) continue - - if (typeof desc.value === 'function') writeMethod(lines, propName, desc.value, ctype) - if (typeof desc.get === 'function') writeGetter(lines, propName, desc.get, ctype) - if (typeof desc.set === 'function') writeSetter(lines, propName, desc.set, ctype) - } - - var out = lines.join('\n') - io.slurpwrite(CTYPEPATH + '/' + name + '.md', out) - } - - function writeMethod(lines, prop, fn, parent) { - var docStr = fn[prosperon.DOC] || docOf(parent, prop) || '' - var paramMatches = [] - - if (typeof fn === 'function') { - var docLines = docStr.split('\n') - var paramRe = /^:param\s+([A-Za-z0-9_]+)\s*:\s*(.*)$/ - for (var j = 0; j < docLines.length; j++) { - var pm = paramRe.exec(docLines[j]) - if (pm) paramMatches.push(pm[1]) - } - } - - var heading = '## ' + prop - if (paramMatches.length > 0) heading += '(' + paramMatches.join(', ') + ')\n' - else { - var m = fn.toString().match(/\(([^)]*)\)/) - if (m) heading += '(' + m[1].trim() + ')\n' - else heading += '\n' - } - - lines.push(heading) - var docOut = parseDocStr(docStr) - if (docOut.length > 0) lines.push(docOut.join('\n') + '\n') - lines.push('') - } - - function writeGetter(lines, prop, getterFn, parent) { - lines.push('## get ' + prop + '\n') - var docStr = getterFn[prosperon.DOC] || docOf(parent, prop) || '' - var docOut = parseDocStr(docStr) - if (docOut.length > 0) lines.push(docOut.join('\n') + '\n') - lines.push('') - } - - function writeSetter(lines, prop, setterFn, parent) { - var docStr = setterFn[prosperon.DOC] || docOf(parent, prop) || '' - var paramMatches = [] - - if (typeof setterFn === 'function') { - var docLines = docStr.split('\n') - var paramRe = /^:param\s+([A-Za-z0-9_]+)\s*:\s*(.*)$/ - for (var j = 0; j < docLines.length; j++) { - var pm = paramRe.exec(docLines[j]) - if (pm) paramMatches.push(pm[1]) - } - } - - var heading = '## set ' + prop - if (paramMatches.length > 0) heading += '(' + paramMatches.join(', ') + ')\n' - else { - var m = setterFn.toString().match(/\(([^)]*)\)/) - if (m) heading += '(' + m[1].trim() + ')\n' - else heading += '\n' - } - - lines.push(heading) - var docOut = parseDocStr(docStr) - if (docOut.length > 0) lines.push(docOut.join('\n') + '\n') - lines.push('') - } -} - -return ret +return { + writeDocFile: writeDocFile +}; diff --git a/source/jsffi.c b/source/jsffi.c index 2dd69eea..771a26c2 100644 --- a/source/jsffi.c +++ b/source/jsffi.c @@ -5933,7 +5933,7 @@ JSC_SCALL(io_slurp, JSC_SCALL(io_slurpwrite, PHYSFS_File *f = PHYSFS_openWrite(str); if (!f) { - ret = JS_ThrowReferenceError(js,"%s", PHYSFS_getErrorByCode(PHYSFS_getLastErrorCode())); + ret = JS_ThrowReferenceError(js,"could not write to %s: %s", str, PHYSFS_getErrorByCode(PHYSFS_getLastErrorCode())); goto END; } size_t len;