# Plugin-utvikling for Asteon Builder

Bygg og publiser **Studio Skills** — gjenbrukbare plugin-pakker som utvider Asteon World Builder med nye AI-verktøy, kameraoppsett, NPC-rutiner, terrengpensler, økonomi-systemer og mer. Plugins distribueres via Asteon Marketplace og installeres med ett kall.

Snarveier: [Lag publish-nøkkel](/profile?tab=api) · [AI Gateway API](/api-docs) · [Bla i marketplace](/skills) · [Skaper-dashbord](/creator-dashboard)

## Tre trinn

1. **Pakk en bunt** — ett `SKILL.md` i roten + filene som verktøyet, scripts og assets ligger i. Maks 200 filer per opplasting.
2. **Publiser med API-et** — POST til `/api/skills` med en gateway-nøkkel. Bruk multipart for binærfiler eller JSON for ren tekst.
3. **Brukere installerer** — builderen henter filtreet via `/api/skills/{id}/install` og registrerer verktøyene mot AI-en. Betalte plugins trekkes fra lommeboken.

## Bunt-struktur

Plugins er rene fil-trær. `SKILL.md` er den eneste obligatoriske filen.

```
my-plugin/
├── SKILL.md            # required at bundle root
├── tools/
│   ├── orbit.json      # tool manifests (registered with the AI)
│   └── dolly.json
├── scripts/
│   └── init.ts         # runs on builder load
├── assets/
│   ├── preview-1.png
│   └── ...
└── README.md           # optional
```

### SKILL.md eksempel

```md
---
name: cinematic-camera-pack
description: Adds 6 cinematic camera presets (orbit, dolly, top-down, FPV, follow, cutscene) to the World Builder. Plug-and-play — no code required.
---

# Cinematic Camera Pack

Drop-in camera presets for the Asteon World Builder.

## Capabilities
- Registers 6 camera tools the AI can call: `camera.orbit`, `camera.dolly`, …
- Adds keybinds: `C` cycles presets, `Shift+C` resets.
- Ships an `assets/` folder with 4 preview thumbnails.

## Files
- `SKILL.md` (this file — required)
- `tools/orbit.json`, `tools/dolly.json`, … (tool manifests)
- `scripts/init.ts` (registered on builder load)
- `assets/preview-*.png`
```

## Verktøy AI-en kan kalle

Plugins utvider builderen ved å registrere *tools* — JSON-skjemaer som AI-modellen kan velge å kalle. Hvert verktøy har et navn, en beskrivelse, og et JSON-Schema for parametere. Asteon Builder eksponerer 100+ innebygde verktøy gruppert i disse kategoriene:

| Kategori | Eksempler på innebygde verktøy |
| --- | --- |
| Scene | `place_object`, `transform`, `group`, `snapshot`, `restore` |
| NPC & dialog | `spawn_npc`, `set_routine`, `write_dialogue_tree`, `voice_line` |
| Audio & økonomi | `place_sound_emitter`, `set_music_zone`, `define_currency`, `price_item` |
| Story & terreng | `sculpt_terrain`, `paint_biome`, `place_landmark`, `write_quest_step` |
| Generering & filer | `generate_image`, `generate_3d_model`, `upload_asset`, `save_to_library` |
| Fysikk & kamera | `set_gravity`, `add_collider`, `configure_camera`, `animate_camera` |
| Validering & registry | `validate_scene`, `register_tool`, `list_tools`, `schema_check` |

### Eksempel på et verktøy-manifest

```json
{
  "name": "camera.orbit",
  "description": "Orbits the active camera around a point at constant radius.",
  "parameters": {
    "type": "object",
    "required": ["target"],
    "properties": {
      "target":  { "type": "string", "description": "Object id or 'origin'" },
      "radius":  { "type": "number", "default": 8 },
      "speedDegPerSec": { "type": "number", "default": 30 },
      "axis":    { "type": "string", "enum": ["y", "x", "z"], "default": "y" }
    }
  }
}
```

## Endepunkter

| Metode | Sti | Auth | Beskrivelse |
| --- | --- | --- | --- |
| GET   | `/api/skills`                                  | ingen          | Søk i den offentlige plugin-katalogen (filter, paginering, sortering). |
| GET   | `/api/skills/{id}`                             | ingen          | Hent metadata for én plugin. |
| GET   | `/api/skills/by-slug/{slug}`                   | ingen          | Slå opp plugin på unik slug. |
| GET   | `/api/skills/{id}/public-versions`             | ingen          | Liste publiserte versjoner med endringslogg. |
| POST  | `/api/skills`                                  | agw_ / sesjon  | Publiser ny versjon (multipart eller JSON). |
| POST  | `/api/skills/{id}/install`                     | agw_ / sesjon  | Installer i kontoen din. Trekkes fra lommebok hvis betalt. |
| GET   | `/api/skills/mine`                             | agw_ / sesjon  | Plugins du har publisert (med inntekt og installasjonstall). |
| GET   | `/api/skills/mine/timeseries`                  | agw_ / sesjon  | Daglig tidsserie for installasjoner og inntekt. |
| GET   | `/api/skills/{id}/versions`                    | agw_ / sesjon  | Alle versjoner (også draft) for en plugin du eier. |
| PATCH | `/api/skills/{id}/versions/{version}`          | agw_ / sesjon  | Oppdater endringsnotater. |
| GET   | `/api/skills/{id}/versions/{version}/files`    | agw_ / sesjon  | Liste filer i en versjon (sti + størrelse). Kun for eier. |
| POST  | `/api/skills/{id}/versions/{version}/republish`| agw_ / sesjon  | Re-publiser en arkivert versjon. |
| PATCH | `/api/skills/{id}`                             | agw_ / sesjon  | Endre navn, beskrivelse, kategori, pris eller status. |

## Publiser (curl)

```bash
# Multipart upload (recommended for binary assets)
curl -X POST https://asteon.ai/api/skills \
  -H "Authorization: Bearer agw_..." \
  -F "name=Cinematic Camera Pack" \
  -F "slug=cinematic-camera-pack" \
  -F "category=camera" \
  -F "version=1.0.0" \
  -F "price=0" \
  -F "description=6 cinematic camera presets" \
  -F "files=@SKILL.md" \
  -F "files=@tools/orbit.json" \
  -F "files=@scripts/init.ts" \
  -F "files=@assets/preview-1.png"
```

## Publiser (JSON)

```ts
// JSON variant — file contents inline as strings
const r = await fetch("https://asteon.ai/api/skills", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ASTEON_GATEWAY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Cinematic Camera Pack",
    slug: "cinematic-camera-pack",
    category: "camera",
    version: "1.0.1",
    price: 0,
    description: "6 cinematic camera presets",
    notes: "Fix orbit easing on slow framerates.",
    files: [
      { path: "SKILL.md", content: skillMdSource },
      { path: "tools/orbit.json", content: JSON.stringify(orbitTool) },
      { path: "scripts/init.ts", content: initScriptSource },
    ],
  }),
});
const { id, version } = await r.json();
```

## Installer en plugin

```ts
// Install a published plugin into the caller's account.
// Skills with price > 0 are charged against the wallet on first install.
await fetch(`https://asteon.ai/api/skills/${id}/install`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${token}` },
});
```

## Versjonering & regler

- **Slug** er unik. Første publisering eier sluggen — andre kan ikke ta den.
- **Versjoner** bør følge SemVer (`1.2.3`). Re-publisering av samme versjon krever `overwrite=true`.
- **SKILL.md** er obligatorisk i bunten — ellers avvises opplasting med `MISSING_SKILL_MD`.
- **Filstier** må være relative og uten `..`. Maks ~5 MB per fil og 200 filer per opplasting.
- **Status**: `draft` (skjult), `published` (synlig i marketplace), `archived` (kan installeres av eiere, ikke nye).
- **Pris** i USD. 0 = gratis. Skapere får hovedandelen, plattformen tar et fast gebyr (se Skaper-dashbord for satser).
- **Publish-auth**: bruk en personlig `agw_…`-nøkkel. Master-token kan ikke publisere som skaper.

Trenger du eksempler? Hver innebygd plugin du installerer kan lastes ned via `/api/skills/{id}/versions/{version}/files` — bruk dem som mal. Asteons verktøy-skjema er kompatibelt med [OpenAI tool-calling](https://platform.openai.com/docs/guides/function-calling).