Orange Engine Hub

Guida agente e API

Guida agente — Orange Engine Hub API v1

L'API è sotto `https://orangeengine.layoutdiprova.it/wp-json/orangeengine/v1`. Le operazioni seguenti richiedono il plugin installato e attivo, URL HTTPS funzionante e storage configurato. Usa un client dedicato con lo scope minimo, creato dall'amministratore in **Orange Engine → Client API**. Conserva il token in un secret manager; non inserirlo nei repository, negli URL, nei log o nell'output di comandi. Il token è visibile una sola volta, scade e può essere revocato. Gli esempi assumono che `OE_TOKEN` sia già disponibile nell'ambiente protetto.

OE_API='https://orangeengine.layoutdiprova.it/wp-json/orangeengine/v1'
curl --fail-with-body -H "Authorization: Bearer $OE_TOKEN" "$OE_API/system/info"

Scope

`assets:write` crea e modifica asset, categorie asset e versioni; `projects:write` gestisce progetti e relative categorie; `roadmap:write` gestisce roadmap e tag; `releases:write` pubblica release. `admin` comprende gli scope, incluse le tassonomie della documentazione. Le operazioni di lettura pubbliche non richiedono token. L'upload di immagini richiede `assets:write` o `projects:write`. I token non impersonano un utente WordPress e non forniscono accesso generale alle API native di WordPress.

Categorie e immagini

Le tassonomie disponibili sono `asset-types`, `project-tags`, `roadmap-tags`, `doc-sections`, `doc-versions`. GET e POST `/taxonomies/{nome}` elencano e creano termini; PATCH e DELETE `/taxonomies/{nome}/{id}` modificano o eliminano un termine. La cancellazione può rimuovere associazioni esistenti: verificare prima l'impatto.

curl --fail-with-body -X POST -H "Authorization: Bearer $OE_TOKEN" -H 'Content-Type: application/json' 
  -d '{"name":"Environments","slug":"environments"}' "$OE_API/taxonomies/asset-types"
curl --fail-with-body -H "Authorization: Bearer $OE_TOKEN" 
  -F 'image=@cover.webp' -F 'alt=Anteprima ambiente' "$OE_API/media"

L'immagine deve essere JPEG, PNG, WebP o AVIF supportato dal server, al massimo 20 MB e 40 milioni di pixel. La risposta contiene l'ID dell'allegato da usare nei metadati. Non vengono scaricati URL remoti.

Asset

POST `/assets` crea un asset; PATCH `/assets/{uuid}` aggiorna i campi; DELETE lo ritira in bozza senza cancellarne file e cronologia. GET restituisce normalmente solo asset pubblicati e pubblici. Un client con `assets:write` può leggere anche bozze e asset privati usando `?context=edit` su `/assets`, `/assets/{uuid}` e `/assets/{uuid}/versions`; le risposte sono private e non memorizzabili in cache. I download degli asset privati non sono ancora disponibili. Usa `GET /assets?asset_type=textures` (o `animations`, `3d-models`) per filtrare per tipo; `GET /taxonomies/asset-types` elenca le categorie modificabili.

curl --fail-with-body -X POST -H "Authorization: Bearer $OE_TOKEN" -H 'Content-Type: application/json' 
  -d '{"name":"Castle","author":"Studio","asset_type":"environments","license":"MIT","description":"Ambiente modulare","status":"published","metadata":{"thumbnail_id":123,"gallery":[124,125],"requirements":"Orange Engine 0.53 o superiore","platforms":"Windows, Linux","documentation_url":"https://example.org/docs"}}' "$OE_API/assets"
# Sostituisci UUID con quello restituito.
curl --fail-with-body -H "Authorization: Bearer $OE_TOKEN" -F 'version=1.0.0' -F 'engine_min=0.53.0' -F 'platforms=windows,linux' 
  -F 'package=@castle.zip;type=application/zip' "$OE_API/assets/UUID/versions"

La pubblicazione della versione richiede ZIP valido e storage privato. I metadata parziali aggiornati via PATCH si uniscono ai precedenti; `gallery` sostituisce l'elenco precedente. I file dell'asset non possono contenere eseguibili o script vietati. Ottieni il manifest con GET `/assets/{uuid}/manifest` e un URL temporaneo con GET `/assets/{uuid}/versions/{version}/download`. Il manifest elenca percorsi e dimensioni dei file nello ZIP locale senza estrarli. Verifica dimensione e SHA-256 prima dell'installazione e valida nuovamente i percorsi prima di estrarli.

Progetti e roadmap

POST `/projects` e `/roadmap`; PATCH/DELETE `/{id}`; GET per elenco e dettaglio pubblici. Con `?context=edit` e lo scope `projects:write` o `roadmap:write` pertinente si possono leggere anche bozze e contenuti privati. I termini si assegnano con `term_ids` e l'immagine con `thumbnail_id`. Il contenuto HTML è sanitizzato.

curl --fail-with-body -X POST -H "Authorization: Bearer $OE_TOKEN" -H 'Content-Type: application/json' 
  -d '{"title":"My Game","status":"publish","content":"<p>Descrizione</p>","thumbnail_id":123,"term_ids":[7],"meta":{"oe_developer":"Studio","oe_engine_version":"0.53.0","oe_platforms":"Windows, Linux","oe_requirements":"8 GB RAM","oe_gallery":"124,125","oe_website":"https://example.org"}}' "$OE_API/projects"

Un progetto pubblicato può avere pacchetti ZIP versionati. Con `projects:write`, usa POST multipart `/projects/{id}/packages` con `version` e `package`; GET sullo stesso percorso elenca i pacchetti pubblici e GET `/projects/{id}/packages/{version}/download` restituisce un URL temporaneo. DELETE `/projects/{id}/packages/{version}` ritira il pacchetto senza cancellare il file. Il server non estrae o esegue i pacchetti.

Per roadmap sono disponibili `oe_roadmap_status` (`planned`, `research`, `development`, `testing`, `completed`, `paused`), `oe_target_version`, `oe_milestone`, `oe_priority`, `oe_progress` da 0 a 100 e `oe_issue_url`.

Release

curl --fail-with-body -H "Authorization: Bearer $OE_TOKEN" -F 'version=1.2.0' -F 'channel=stable' 
  -F 'platform=linux' -F 'architecture=x86_64' -F 'launcher_min=1.0.0' 
  -F 'notes=Release notes' -F 'package=@engine.zip;type=application/zip' "$OE_API/engine/releases"

PATCH e DELETE `/engine/releases/{version}` richiedono `channel`, `platform` e `architecture`: PATCH aggiorna note, changelog, problemi noti o `deprecated`; DELETE ritira la release senza cancellare il file. DELETE `/assets/{uuid}/versions/{version}` ritira una versione asset; PATCH sullo stesso endpoint aggiorna `engine_min`, `engine_max`, `platforms`, `changelog` o `deprecated`. Imposta `deprecated` a `false` per ripristinare la versione senza modificare il pacchetto.

GET `/engine/releases`, `/engine/releases/latest`, `/engine/releases/{version}` e `/engine/update-check` espongono dati pubblici. Il download usa GET `/engine/releases/{version}/download?channel=stable&platform=linux&architecture=x86_64`. Segui l'URL solo via HTTPS e controlla SHA-256; per le richieste successive può servire un nuovo URL firmato.

Errori e limiti

Gli errori hanno `code`, `message`, `details`; 401/403 indicano credenziali o scope insufficienti, 404 risorse non disponibili, 409 conflitti e 429 limite richieste. Usa backoff su 429. L'attuale upload è una singola richiesta, non multipart resumable, ed è limitato anche dalla configurazione PHP/proxy. Per pacchetti molto grandi, S3, OAuth e workflow di importazione asincroni servono ulteriori sviluppi. `openapi.yaml` descrive il contratto disponibile; `manifest.schema.json` descrive il manifest.

Connettore Claude MCP

Per usare gli strumenti dell’hub direttamente da Claude senza dipendere dalla rete del terminale, configura il connettore descritto in `claude-mcp.md`. L’endpoint è `https://orangeengine.layoutdiprova.it/wp-json/orangeengine/v1/mcp` e accetta lo stesso token Bearer.

Pacchetti grandi tramite MCP

Un client MCP programmatico può usare `start_package_upload`, `upload_package_chunk`, `package_upload_status`, `finish_package_upload` e `cancel_package_upload` per inviare uno ZIP direttamente nello storage privato senza passare dalla libreria Media. La procedura, i limiti e il comportamento di ripresa sono documentati in `claude-mcp.md`.

Download quando il sito è in sola consultazione

Se il download pubblico degli asset è disattivato nelle impostazioni, chiama l'endpoint di download o lo strumento MCP asset_download con un token avente scope assets:download oppure admin. La risposta contiene un URL temporaneo: usalo entro la scadenza indicata. L'URL è una credenziale temporanea e non va pubblicato o registrato nei log. Lettura del catalogo e gestione degli asset conservano gli endpoint e gli UUID esistenti.