# DeskOS SDK — build apps outside DeskOS

Build native DeskOS apps and games with any editor on any machine, package them
as a single **`.dapp`** file, and **drag the file onto a running DeskOS** — an
install popup shows the app's details with one-click *Install* (and *Publish to
Software Center* on machines allowed to publish).

Requires [Node.js](https://nodejs.org) (any recent version, no npm installs needed).

## Quick start

```sh
node cli.js init my-app          # scaffold an app (or:  init my-game --game)
cd my-app                        # edit main.js with any editor
node ../cli.js pack .            # → my-app.dapp
```

Drag `my-app.dapp` onto the DeskOS desktop. Done.

## What's in an app

An app is a folder with a manifest and an ES module:

```
my-app/
  deskos-app.json     { id, name, icon, version, type: "module", entry: "main.js" }
  main.js             export default { id, name, icon, open(args, api) { ... } }
  ...assets           anything else gets packed too (api.asset('file.png') reads it)
```

`open(args, api)` builds DOM (use `api.ui.*`) and returns
`api.createWindow({ content })`. Manifest `type` can also be `widget`
(desktop widget), `web` (wraps a URL) or `plugin` (CSS/JS injected into another
app).

## The `api` surface (highlights)

- **Windows** — `api.createWindow({ title, width, height, content })` →
  `win.shortcut('space', fn)`, `win.onResize`, `win.interval`, `win.timeout`
- **UI toolkit** — `api.ui.row/column/grid/stack`, `button/input/toggle/slider/
  select/list/tabs/card/modal`, dialogs `alert/confirm/prompt`
- **Graphics** — `await api.graphics.createPipeline(canvas, { api: 'auto' })`
  picks **WebGPU → WebGL** (or `'canvas2d'`); 3D scene API: `box/sphere/plane/
  cylinder/torus`, materials (`emissive`, `opacity`), fog, `grid()`,
  `camera.orbit()`. 2D: `rect/circle/line/poly/text/sprite`, pan/zoom camera.
- **Input pipeline** — `api.input.bind({ jump: ['space', 'pad:0'] })`,
  `active/pressed/axis/vector/stick/pointer/gamepads`
- **Audio pipeline** — `api.audio.bus('sfx', { gain: .7 })` → `tone()`, `play(url)`,
  `lowpass()`, `mute()`; quick SFX via `api.sound.play('coin'|'jump'|'hit'|…)`
- **Multiplayer** — `api.mp.create()` → room code, `api.mp.join(code)`,
  `send(data)`, `on('data'|'peers', fn)` — relayed through the DeskOS server
- **Game loop** — `api.loop(fn, { fixed: 1/60 })`
- **Storage / files** — `api.storage.get/set` (per app, per user),
  `api.fs.*` (the user's virtual disk), `api.asset(rel)` (bundled files)
- **System** — `api.notify`, `api.launch`, `api.clipboard`, `api.http`,
  `api.media` (Now Playing), `api.battery`, `api.network`

The full reference lives inside DeskOS: **Studio → Docs**.

## Publishing

Drop the `.dapp` on a DeskOS machine that has publishing configured and choose
**Publish to Software Center** — it lands in the repository and every DeskOS
can install it from the Software Center.