Skip to content

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.
  2. script: Path to the program script (a file containing statements, not returning anything).
  3. config: Optional object of extra properties to assign to the new program.
  4. 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.

  1. 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.

  2. 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.

  3. Example:
    js this.delay(_ => { console.log("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.