90 lines
2.4 KiB
Markdown
90 lines
2.4 KiB
Markdown
# Bundle Format
|
|
|
|
Plugin bundles are zip files named after the plugin ID. `config.json` must be at the zip root.
|
|
|
|
## Plugin 2.0 Layout
|
|
|
|
```text
|
|
<pluginId>.zip
|
|
config.json
|
|
<pluginId>.html
|
|
<pluginId>.css
|
|
<pluginId>.js optional when src/ui.ts exists
|
|
<pluginId>.wasm optional agent-side WASM module
|
|
server.js optional server runtime
|
|
src/
|
|
ui.ts compiled to assets/<pluginId>.js
|
|
server.ts compiled to server.js
|
|
shared.ts optional local module
|
|
```
|
|
|
|
After extraction the server stores assets under `Overlord-Server/plugins/<pluginId>/assets/`, generated metadata in `manifest.json`, optional source in `src/`, and persistent plugin files in `data/`.
|
|
|
|
## Runtime Selection
|
|
|
|
```json
|
|
{
|
|
"apiVersion": 2,
|
|
"runtime": "wasm",
|
|
"wasm": "sample-wasm.wasm"
|
|
}
|
|
```
|
|
|
|
Use:
|
|
|
|
| Runtime | Use case |
|
|
|---------|----------|
|
|
| `server` | Server-only extension, build plugin, dashboard plugin, RPC-backed plugin. |
|
|
| `wasm` | Sandboxed agent-side Plugin 2.0 module. |
|
|
| `native` or omitted v1 fields | Legacy shared-library agent plugin. |
|
|
|
|
Server-only plugins are not sent to clients and do not use auto-load.
|
|
|
|
## Manifest Fields
|
|
|
|
`config.json` is merged into the generated `manifest.json`.
|
|
|
|
```json
|
|
{
|
|
"id": "sample",
|
|
"name": "Sample Plugin",
|
|
"apiVersion": 2,
|
|
"runtime": "server",
|
|
"version": "1.0.0",
|
|
"description": "An example plugin",
|
|
"entry": "sample.html",
|
|
"assets": {
|
|
"html": "sample.html",
|
|
"css": "sample.css",
|
|
"js": "sample.js"
|
|
},
|
|
"navbar": {
|
|
"label": "Sample",
|
|
"icon": "fa-cube"
|
|
}
|
|
}
|
|
```
|
|
|
|
`navbar.icon` accepts a Font Awesome 6 solid icon class such as `fa-cube`, `fa-key`, or `fa-network-wired`. If the plugin is enabled, navbar plugins appear in the Plugin Apps group and open at `/plugins/<id>`.
|
|
|
|
## TypeScript UI And Server Logic
|
|
|
|
Plugin bundles can ship source-oriented browser and server logic. The server compiles these during extraction:
|
|
|
|
```json
|
|
{
|
|
"apiVersion": 2,
|
|
"uiEntry": "src/browser/main.ts",
|
|
"serverEntry": "src/backend/index.ts"
|
|
}
|
|
```
|
|
|
|
Defaults:
|
|
|
|
| Source file | Output |
|
|
|-------------|--------|
|
|
| `src/ui.ts` | `assets/<pluginId>.js` |
|
|
| `src/server.ts` | `server.js` |
|
|
|
|
Only files under `src/` are copied for compilation. Extraction does not run `npm install`, download packages, or execute build scripts. Use relative imports and APIs already available in the browser or server plugin runtime.
|