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

simplify docs

Browse Source
This commit is contained in:
John Alanbrook
2025-12-10 15:17:50 -06:00
parent d0f5dc6951
commit 5a3e260821
101 changed files with 16 additions and 10064 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/actors.md
View File

@@ -1,77 +0,0 @@
# Programs: Programs and Modules
Prosperon organizes your code into two broad categories: **modules** and **programs**. Modules are used to extend programs with new functionality, while programs are used to spawn actors.
## Modules
A **module** is any file that returns a single value. This return value is commonly an object, but it can be any data type (string, number, function, etc.). Once a module returns its value, Prosperon **freezes** that value, preventing accidental modification. The module is then cached so that subsequent imports of the same module don’t re-run the file—they reuse the cached result.
### Importing a Module
Use the built-in `use` function to import a module by file path (or by name if resolvable via Prosperon’s path settings). For example:
```
var myModule = use('scripts/modules/myModule')
```
`use('module')` returns the **exact** same object if called multiple times, since modules are cached and not re-run.
Dull based modules are resolved by searching for them from the `prosperon.PATH` array. Engine modules are stored under `scripts/modules`, which is already added to the PATH for you.
Prosperon can also load C based modules. If two modules have the same path resolution, the C based library will be imported.
## Programs
An **program** is a file that **does not** return a value. Instead, the file’s contents run top to bottom as soon as the program is spawned. Programs are your game’s “live” scripts: each program can hold its own state and logic, spawn sub-programs, schedule timed tasks, and eventually **kill** itself (or be killed) when it’s done.
### Program Intrinsic Functions
Certain functions are intrinsic to the program and cannot be overridden. They’re assigned to each new program instance at spawn time:
1. **`spawn(script, config, callback)`**
Creates (spawns) a new program from another script file.
- **`script`**: Path to the program script (a file containing statements, not returning anything).
- **`config`**: Optional object of extra properties to assign to the new program.
- **`callback(underling, info)`**: Optional function invoked right after the program is instantiated but before it fully initializes.
The newly spawned program:
- Receives a reference to its parent (the `overling`) and can store child programs (the `underlings`).
- Automatically calls `awake()` if that function is defined, after basic setup completes.
- Registers any recognized event handlers (like `update`, `draw`, etc.) if they exist.
2. **`kill()`**
Destroys the program, all of its timers, and recursively kills any underling (child) programs. If the program has a parent, it is removed from the parent’s `underlings` set.
3. **`delay(fn, seconds)`**
Runs the given function `fn` after `seconds`. This is implemented under the hood with a timer that automatically clears itself once it fires.
- **Example**:
```js
this.delay(_ => {
log.console("3 seconds later!")
}, 3)
```
4. **`clear()`**
Recursively kills all child programs, clearing your immediate `underlings` set. This is not called automatically. You can use it to manually clean up all children without necessarily killing the program itself.
### The program Lifecycle
Specific hooks can be set on a program when it is initialized.
- **Awake**: If the new program defines `awake()`, Prosperon calls it after the script finishes its top-level execution. This is a common place to do initialization.
- **Garbage**: When the program is killed, if it has a `garbage()` function, Prosperon calls it before final removal.
- **Then**: If the program has a `then()` function, Prosperon calls it at the very end of the kill process, allowing any final statements after your `garbage()` logic completes.
- **Registration**: In addition, if the object has **any** function named the same thing as a hook created with **prosperon.on**, that function will be registered with it after initialization.
### Overlings and Underlings
Programs have access to its creator and other programs created underneath it, termed its overling and underlings.
- **`this.overling`** is the parent program that spawned the current one.
- **`this.underlings`** is a set of child programs that the current program has spawned.
Killing a parent automatically kills all of its underlings, which in turn can kill their own underlings, and so on.
## Program Documentation
Prosperon includes a module called `doc.js` which helps generate documentation for your modules and programs. Any function and value can be assigned a docstring, and prosperon will then be able to generate documentation for it via doc.js. Look under the module API for more info.