Referenz zum Paketmanifest
Jedes Feld von aigd-package.json: IDs, Versionen, engines.aigd, Activation Events, Dependencies und alle Beitragspunkte mit Form und Regeln.
aigd-package.json ist das Manifest eines AI Game Dev-Pakets: seine ID, seine Version, die App-Versionen, mit denen es zusammenarbeitet, und alles, was es beiträgt. Die App liest es, ohne Paketcode auszuführen, sodass jeder Menüeintrag, jeder Slash-Befehl, jeder Tools-Schalter und jede View schon sichtbar ist, bevor das Paket aktiviert wird. Diese Seite listet jedes Feld und jeden Beitragspunkt mit seinen Regeln auf. Ein neues Paket aus gamedev pkg init hat bereits ein gültiges Manifest und sein JSON-Schema (benannt über $schema) für die Vervollständigung in deinem Editor.
Felder auf oberster Ebene
| Feld | Erforderlich | Was es ist |
|---|---|---|
publisher | Ja | Deine Publisher-ID: 2 bis 40 Zeichen, beginnend mit einem Buchstaben, dann Kleinbuchstaben, Ziffern und einzelne Bindestriche, keine Punkte |
name | Ja | Der Paketname: 2 bis 64 Zeichen, Kleinbuchstaben, beginnend mit einem Buchstaben |
version | Ja | Semver MAJOR.MINOR.PATCH (ein Prerelease-Suffix wie 1.3.0-beta.2 ist erlaubt) |
engines.aigd | Ja | Die älteste Version von AI Game Dev, die das Paket benötigt, zum Beispiel ">=0.18.0" |
displayName, description | Nein | Wird im Packages-Fenster und im Katalog angezeigt (displayName bis zu 60 Zeichen, description bis zu 400) |
icon, avatarText | Nein | Ein paketrelatives Bild oder bis zu 4 Zeichen, die als Avatar gezeichnet werden |
license | Nein | Eine SPDX-ID (MIT, Apache-2.0) oder SEE LICENSE IN <file> |
homepage, repository, keywords | Nein | Links und bis zu 20 Keywords |
main | Nein | Der Code-Einstiegspunkt (CommonJS oder ESM), der activate exportiert; ohne ihn ist das Paket contributions-only |
activationEvents | Nein | Zusätzliche Events, die den Code starten (unten) |
hosts | Nein | ["desktop"], ["cli"] oder beides (der Standard); ein desktop-only-Paket wird von der CLI übersprungen |
dependencies | Nein | Andere Pakete, { "<publisher.name>": "<range>" } |
claudePlugins, claudeMarketplaces | Nein | Claude Code-Plugins, die das Paket benötigt, und wo ihre Marketplaces zu finden sind |
enabledApiProposals | Nein | Vorgeschlagene API, die das Paket nutzt; die Registry lehnt jeden Eintrag hier ab |
dataVersion | Nein | Die Version der Daten, die dein Code speichert (informativ) |
contributes | Nein | Alles, was das Paket hinzufügt (unten) |
Die Paket-ID ist publisher.name: acme.level-tools. Sie muss mit dem Schlüssel übereinstimmen, unter dem das Paket installiert ist, sonst läuft nichts (id-mismatch). Der Publisher aigd gehört zu AI Game Dev, und die Engine-Namen unity, godot, unreal, brutal, bevy und threejs sind reserviert.
Die App-Version: engines.aigd
engines.aigd ist ein Minimum, etwa ">=0.18.0". Eine App, die älter ist, lehnt das Paket ab und nennt die Version, die sie braucht. Eine Beta der App zählt als das Release, das sie vorab zeigt: 0.32.0-beta.1 erfüllt ">=0.32.0". Die älteste Untergrenze, die die App noch lädt, ist 0.18.0; setze deine auf die älteste App, mit der du getestet hast. Ein Game-Engine-Paket benötigt ">=0.32.0".
Installationen werden nach ID und Version zwischengespeichert: Jede Änderung, die du veröffentlichst, braucht eine höhere version.
IDs, die dein Paket besitzt
Alles, was ein Paket beiträgt, ist innerhalb seiner eigenen ID benannt, sodass zwei Pakete nie kollidieren:
- Befehle, Panels, Views, View-Container, Untermenüs, Statusleisten-Einträge, Tutorials und benutzerdefinierte Editoren:
<package id>.<local>, zum Beispielacme.level-tools.export. - Capabilities: die Paket-ID selbst oder
<package id>.<local>. Eine Capability-ID wird pro Chat gespeichert, benenne sie also niemals um. - MCP-Servernamen:
<publisher>--<name>oder<publisher>--<name>-<suffix>, höchstens 96 Zeichen:acme.level-toolsbesitztacme--level-toolsundacme--level-tools-preview. Das Modell sieht diesen Namen in jedem Tool-Namen, deshalb wird--statt eines Punkts verwendet. Ein nicht qualifizierter Name ist ein Fehler. - Kontextschlüssel, die du mit
aigd.commands.setContextsetzt:<package id>.<key>.
gamedev pkg validate nennt jede ID, die nicht dir gehört, mit ihrem Feld.
Beitragspunkte
| Punkt | Form | Hinweise |
|---|---|---|
commands | {command, title, shortTitle?, category?, icon?, palette?, hosts?, enablement?} | Palette-Einträge; enablement ist eine when-Klausel |
slashCommands | {name, description, argumentHint?, hosts?} | name wie eingegeben, /export; bei einem Namenskonflikt gewinnt ein integrierter Befehl, dann das erste Paket nach ID |
capabilities | {id, label, description, defaultEnabled?, mcpServer?, gatesClaudePlugin?, statusful?, hidden?, icon?} | Ein Schalter in der Tools-Zeile eines Chats; mcpServer benennt den Server, den er einschaltet |
mcpServers | { "<server name>": {command, args?, env?} or {type: "http" or "sse", url, headers?} } | Stdio-Server dürfen ${node}, ${packageDir}, ${projectDir}, ${globalStorage} verwenden |
agentProviders | {id, serverName, capabilityId, sessionToolViewId?} | Tools, die dein Code über aigd.agent.registerProvider im Speicher bereitstellt |
settings | { "<key>": {type, default?, description, enum?, scope?, …} } | Typen string, number, boolean, string[], path |
menus | { "<menu id>": [{command or submenu, group?, when?, alt?}] } | Feste Menü-IDs (siehe unten) |
submenus | {id, label, icon?} | Eine Submenü-ID ist zugleich ein Menüschlüssel |
keybindings | {command, key, mac?, win?, linux?, when?, args?} | Desktop; ctrl bedeutet Cmd auf macOS, sofern mac nicht angegeben ist |
statusBar | {id, text, tooltip?, command?, alignment?, priority?, when?} | Desktop |
panels | {viewType, title, icon?} | Webview-Panels, die dein Code öffnet |
viewsContainers | {left?: [{id, title, icon}], right?: [...]} | Neue Tabs in den Seitenleisten |
views | { "left" or "right" or "<container id>": [{id, name, type: "tree" or "webview", icon?, when?, welcome?, titleBar?}] } | Tree-Views und Webview-Views in den Seitenleisten |
customEditors | {viewType, displayName, selector: [{filenamePattern}], priority?} | priority default (der Standard) ersetzt die integrierte Vorschau für passende Dateien; option erscheint in Open With |
tutorials | {id, title, anchor, markdown? and media? or webview?, size?, trigger?, when?, after?, priority?} | Kurze In-App-Tipps, die jedem Nutzer einmal angezeigt werden |
claudePlugin | ein paketrelativer Ordner | Ein Claude Code-Plugin, das im Paket mitgeliefert wird |
mediaProviders | {id, capabilityId, execution: "local"} | Ein lokaler Medien-Generator, den dein Code mit aigd.media.registerProvider registriert |
sessionTools | {id, capabilityId, title, modules?} | Eine Konfigurationsoberfläche für eine Capability in den Tools eines Chats (eine Webview-Ansicht, die dein Code auflöst) |
gameEngines | siehe Game-Engine-Pakete | Eine Engine pro Paket |
runtimes, imageModels, videoModels, model3dModels, mediaModels | deklarativ, kein Code | Lokale Generierungs-Runtimes und die Modelle, die sie ausführen, sowie Cloud-Modellfamilien |
Icons sind entweder $(name), ein Icon aus dem Icon-Set der App, oder ein Pfad innerhalb des Pakets. composerButtons wird noch geladen, ist aber veraltet: Verwende einen Menüeintrag in composer/toolbar.
Menü-IDs
| Menü-ID | Der Befehl erhält | Kontextschlüssel für when |
|---|---|---|
commandPalette | nichts | — |
composer/toolbar | {sessionId} | sessionId |
session/title | {sessionId} | sessionId |
session/tool | {sessionId, capabilityId} | sessionId, capability, capabilityPackage, sessionToolModule |
session/context | {sessionId} | sessionId, sessionState |
chat/message/context | {sessionId, messageId, role} | sessionId, messageRole |
explorer/context | {path, isDirectory} | resourcePath, resourceFilename, resourceExtname, resourceDirname, resourceRelativePath, explorerResourceIsFolder |
editor/title | {path, viewType} | die Ressourcen-Schlüssel, activeCustomEditor, previewKind |
preview/<kind>/toolbar | {path} | die Ressourcen-Schlüssel, previewKind |
view/title | {viewId} | view |
view/item/context | {viewId, itemId} | view, viewItem |
packages/item/context | {packageId} | packageId, packageLevel, packageState |
statusBar/item/context | {itemId} | statusBarItem |
Die Gruppe navigation erzeugt eine Inline-Schaltfläche in der Symbolleiste; andere Gruppen landen im Überlaufmenü „…“, und group@order sortiert innerhalb einer Gruppe. Vorschau-Arten sind code diff image svg texture audio video model font markdown table binary. Eine unbekannte Menü-ID ist eine Warnung, kein Fehler, sodass ein für eine neuere App geschriebenes Paket trotzdem lädt.
when-Klauseln
Menüs, enablement, Tastenbelegungen, Ansichten, Statusleisten-Einträge und Tutorials akzeptieren eine when-Klausel in der VS-Code-Syntax: ! && || == != < <= > >= =~ /regex/ in und not in, mit Klammern. Globale Schlüssel umfassen host, platform, projectOpen, projectEngine, activePane, activeFilePath, activeFileExtname, sessionActive, sessionRunning, attachedCapabilities, activePackages, installedPackages, workspaceEngines und ein workspaceHasEngine:<engine> pro Engine im geöffneten Ordner. Deine Einstellungen sind als config.<package id>.<key> lesbar und deine eigenen Schlüssel als <package id>.<key>.
{
"contributes": {
"commands": [{ "command": "acme.level-tools.export", "title": "Export level", "enablement": "projectEngine == 'godot'" }],
"menus": {
"explorer/context": [{ "command": "acme.level-tools.export", "when": "resourceExtname == '.tscn'", "group": "navigation" }]
}
}
}Eine nicht parsbare Klausel ist ein Manifest-Fehler und lässt diesen Beitrag entfallen.
Einstellungen
{
"contributes": {
"settings": {
"outputDir": { "type": "path", "description": "Where exports go", "scope": "project", "mustBeWritable": true },
"quality": { "type": "string", "enum": ["draft", "final"], "default": "draft", "description": "Export quality" },
"cachePath": { "type": "path", "description": "A cache on this computer", "userLevelOnly": true }
}
}
}scope: "machine"(der Standard) schreibt auf Benutzerebene;scope: "project"schreibt auf Projektebene, die eingecheckt und mit dem Team geteilt wird.- Ein Wert wird von der lokalen Ebene gelesen, dann vom Projekt, dann von der Benutzerebene, dann der Manifest-Standardwert.
type: "path"erwartet einen absoluten Pfad;directories: falsefragt nach einer Datei,mustBeWritableundshowFreeSpacefügen dem Formular Prüfungen hinzu.userLevelOnly: true(zusammen mitscope: "machine") macht einen Schlüssel maschinenweit: Projekt- und lokale Werte werden ignoriert.enumgibt feste Auswahlmöglichkeiten;options: { "provider": "<id>" }bezieht sie zur Laufzeit von einem Provider (vorerst nur die Provider der App selbst).
Aktivierungsereignisse
Die meisten Pakete brauchen keine: jeder beigesteuerte Befehl, Slash-Befehl, jede View, jeder Custom Editor, jede zustandsbehaftete Capability, jedes Webview-Tutorial und jede Game Engine startet den Code von selbst. Liste zusätzliche Ereignisse in activationEvents auf, wenn der Code zu einem anderen Zeitpunkt laufen muss:
| Ereignis | Wann |
|---|---|
onStartupFinished | Nach dem ersten Rendern der App oder dem ersten Prompt der CLI (der Standard für ein Paket mit main und ohne weiteres Ereignis) |
onCommand:<id>, onSlashCommand:/<name> | Bevor der Befehl ausgeführt wird |
onView:<viewId>, onCustomEditor:<viewType> | Wenn die View zum ersten Mal angezeigt wird, wenn eine passende Datei geöffnet wird |
onFileType:.<ext> | Wenn eine Datei mit dieser Erweiterung in einem beliebigen Bereich geöffnet wird |
onCapability:<id>, onAgentProvider:<id> | Wenn eine Capability oder ein Provider zum ersten Mal benötigt wird |
onTutorial:<id>, onWebviewPanel:<viewType> | Bevor ein Webview-Tutorial angezeigt wird, wenn ein gespeichertes Panel wiederhergestellt wird |
onGameEngine:<id> | Wenn der geöffnete Ordner ein Projekt dieser Engine enthält |
* | Beim Start des Hosts (nicht empfohlen) |
Abhängigkeiten und Claude-Plugins
{
"dependencies": { "acme.core-3d": "^1.0.0" },
"claudePlugins": { "level-design@acme-marketplace": "*" },
"claudeMarketplaces": { "acme-marketplace": { "source": "github", "repo": "acme/claude-plugins" } }
}- Ein Projekt verwendet eine Version jedes Pakets: die höchste Version, die alle Versionsbereiche erfüllt und von der App akzeptiert wird. Abhängigkeiten werden vor den Paketen aktiviert, die von ihnen abhängen. Ein Konflikt, ein Zyklus oder eine ausgeschlossene Abhängigkeit wird bei dem Paket angezeigt, das sie benötigt.
- Claude-Plugins werden pro Projekt in den eigenen Cache der App installiert, an einen Commit in der Lock-Datei des Projekts gebunden und an die Chats dieses Projekts übergeben. Sie berühren nie dein eigenes
~/.claude. Marketplace-Quellen sindgithub,git,git-subdirundurl.
Verwandte Seiten
- Package API für den Code hinter diesen Beiträgen.
- Lebenszyklus, Hosts und Berechtigungen für Aktivierung, Zustand und Versionierung.
- Registry-Regeln und -Prüfungen dafür, was die Registry akzeptiert.