# Quickstart

This quickstart walks through running Cell programs, exploring examples, and creating your first module and program. It assumes the `./cell` executable is present at the repo root (already built or downloaded).

## 1) Initialize a Project Shop (.cell)

Create the project structure used for module management and bytecode cache:

- `./cell init`

This creates `.cell/` with `cell.toml`, `lock.toml`, `modules/`, `build/`, and `patches/`.

## 2) Run Built‑in Examples

Examples under `examples/` are programs (`*.ce`) you can run directly:

- NAT portal server (introduction service):
  - `./cell examples/nat`
- NAT client (contacts a portal):
  - `./cell examples/nat_client`
- Non‑blocking HTTP download actor:
  - `./cell examples/http_download_actor`

Tip: Use these as references for portals, contacts, and non‑blocking I/O.

## 3) Run the Accio Game

Accio lives under `accio/`. The program is `accio/accio.ce` and supports modes via arguments:

- Start menu: `./cell accio start`
- Load a level: `./cell accio level game/1.json`
- Analyze assets: `./cell accio analyze`
- Clean level data: `./cell accio clean`

Arguments after the program path are available inside the program via `arg` (e.g., `arg[0] == 'start'`).

## 4) Your First Module (.cm) and Program (.ce)

Create a module that returns a frozen API object, and a program that uses it.

- File: `examples/hello.cm` (module)

```javascript
// Returns a value (frozen by the engine)
return {
  greet: function(name) {
    return `Hello, ${name}!`
  }
}
```

- File: `examples/hello.ce` (program)

```javascript
var hello = use('examples/hello')

log.console(hello.greet('Cell'))

$receiver(function(msg) {
  if (msg.type == 'ping') {
    send(msg, {type:'pong'})
  }
})

$delay(_ => $stop(), 0.1)
```

Run it:

- `./cell examples/hello`

Notes:
- Modules are `*.cm` and must return a value. The engine deep‑freezes return values, so mutate via new objects or closures rather than in‑place.
- Programs are `*.ce` and must not return a value. They run top‑to‑bottom when spawned and can register handlers via `$receiver()` and schedule work via `$delay()` or `$clock()`.

## 5) Spawning Child Programs (Actors)

Programs can spawn other programs and receive lifecycle events.

- File: `examples/spawner.ce`

```javascript
$receiver(function(e) {
  if (e.type == 'greet' && e.actor) {
    log.console('Child greeted me')
  }
})

$start(function(info) {
  if (info.type == 'greet') {
    log.console('Spawned child actor')
  }
}, 'examples/hello.ce')

$delay(_ => $stop(), 0.5)
```

Run it:

- `./cell examples/spawner`

## 6) Module Shop Basics

The module shop manages vendored dependencies under `.cell/modules/` and caches compiled bytecode under `.cell/build/`.

Common commands (all are programs under `scripts/`):

- Initialize (if you haven’t already):
  - `./cell init`
- See available commands:
  - `./cell help`
- Configure system/actor settings:
  - `./cell config list`
  - `./cell config set system.reply_timeout 60`
  - `./cell config actor prosperon/_sdl_video set resolution 1280x720`
- Download or vendor dependencies (from `.cell/cell.toml`):
  - `./cell mod download`

## 7) How Module Resolution Works

- `use('path')` checks:
  1) The current module’s directory for `path.cm` while loading.
  2) The mounted roots (the program’s directory is mounted) for `path.cm`.
  3) Embedded/native modules if no script file is found.
- Modules compile to `.cell/build/<canonical-path>.o` and reuse the cache if newer than the source.
- Scripted modules can extend embedded modules via prototype; if the script returns nothing, the embedded module is used as‑is.

## 8) Next Steps

- Language details: `docs/cell.md`
- Actors, programs, and messaging: `docs/actors.md`
- Rendering, input, and resources: `docs/rendering.md`, `docs/input.md`, `docs/resources.md`
- Full API reference: `docs/api/`