134 lines
3.8 KiB
Markdown
134 lines
3.8 KiB
Markdown
# 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/`
|