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