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)

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

File: examples/hello.ce (program)

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

$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/

3.8 KiB Raw Permalink Blame History Unescape Escape