EN /HU | Belépés

WarpEngine Toolbox

A WarpEngine Toolbox egy VS Code-bővítmény, amellyel egy játék az üres mappától eljut egy WarpEngine-katalógusban élő, kiadott, játszható bejegyzésig — és ott is tartható —, a szerkesztőből ki sem lépve. Saját platformtudása nincs: amit egy platformról tudni kell (mit publikál, hol van a metaadata és a verziója, hogyan játszható a weben, melyik a builder-image-e és a projektsablonja), azt a hoszt mondja meg. Egy új platform a hoszton így még aznap működik a szerkesztőben is.

A WarpEngine Toolbox VS Code-ban, megnyitott C64 demóval: balra a WarpEngine-panel, jobbra a hoszt sémájából épített metadata-űrlap

Képernyőkép: a C64 demo VS Code-ban, a bővítménnyel, belépés előtt. Az űrlap abból a sémából készül, amit a teletypegames.org a C64-hez kiszolgál.

Telepítés három lépésben

1. Telepítés a Marketplace-ről

A bővítmény fent van a Visual Studio Marketplace-en. A VS Code-ban nyisd meg az Extensions panelt (⇧⌘X / Ctrl+Shift+X), keress rá a WarpEngine Toolbox-ra, és kattints az Install-ra — vagy parancssorból:

SH
code --install-extension TeletypeGames.warpengine-toolbox

Innentől a VS Code frissen tartja.

2. Vagy VSIX-ből

Minden verzió .vsix-e ott van a kiadások oldalán is: Extensions ▸ ⋯ ▸ Install from VSIX…, vagy code --install-extension warpengine-toolbox-1.0.0.vsix. A legfrissebb forrásból:

SH
git clone ssh://git@git.teletypegames.org:2222/tools/warp-engine-toolbox.git
cd warp-engine-toolbox
make localinstall

A make localinstall az első futáskor telepíti a build-eszközöket (Node 22 vagy újabb), becsomagolja a bővítményt, és a korábbi verzió helyére telepíti. Utána a nyitott ablakokban futtasd a Developer: Reload Window parancsot.

A tevékenységsávon megjelenik a W, a bővítmények között pedig a toolbox:

A WarpEngine Toolbox az Extensions nézetben, 1.0.0-s verzió

3. Hoszt és belépés

A bővítmény nem hoz magával hosztot: meg kell mondani neki, melyik oldal futtatja a WarpEngine-edet. Vagy futtasd a parancspalettáról a WarpEngine: Set Host… parancsot, vagy írd a beállításokba:

JSON
{
  "warpengine.url": "https://teletypegames.org"
}

Innentől működik minden, ami csak olvas: sablonok, metadata-ellenőrzés, build, Play, pipeline-előnézet.

A többihez — Connect, katalógus, pipeline-státusz, kiadás — futtasd a WarpEngine: Sign In parancsot:

  1. a szerkesztő kiír egy rövid kódot, és a böngészőben megnyitja a hoszt Tool Sign In oldalát (/admin/tool_sign_in);
  2. a hoszt egy adminisztrátora ott belép, ellenőrzi, hogy a kód egyezik, és az Approve gombra kattint;
  3. a szerkesztő megkapja a kért scope-okra (admin:read, admin:write) szóló Admin API-tokent, a jóváhagyó adminisztrátor nevére. A VS Code titoktárában tárolódik; a WarpEngine: Sign Out elfelejti.

Jelszó sosem jut el a szerkesztőhöz, és a belépéshez a hoszttól csak a WarpEngine saját Admin API-ja kell.

Az üres mappától a kiadásig

MERMAID
flowchart TB
  subgraph start[" "]
    direction LR
    A["New Game…<br/>platform, név, cím"] --> B["projekt a hoszt<br/>sablonjából"] --> C["Play<br/>helyi build a<br/>webes runtime-ban"] --> D["Metaadat<br/>mentéskor ellenőrizve"]
  end
  subgraph ship[" "]
    direction LR
    E["Connect<br/>repó, CI,<br/>katalógusrekord"] --> F["push<br/>pipeline a<br/>státuszsorban"] --> G["Release…<br/>verzió, changelog,<br/>tag"] --> H["kiadva:<br/>web, kliens,<br/>store-kimenetek"]
  end
  start --> ship
  1. WarpEngine: New Game… — válassz platformot, adj nevet a játéknak (kisbetű, számjegy és kötőjel: ez lesz a repó és a feltöltések neve is), címet, egysoros leírást, szerzőt, licencet, kategóriát és mappát. A projekt a hoszt sablonjából készül — és ahol a hosztnak van, egy már futó demóból: Makefile, .vscode/tasks.json, az egysoros pipeline-jelölő (.woodpecker.yaml), metadata.json (TIC-80-on a Lua-fejléc), README és egy első git-commit.
  2. Play (▶ a projektpanelen) lefordítja és egy panelen lejátssza a játékot — pontosan abban a runtime-ban, amelyben a kiadása a weben futni fog (EmulatorJS, TIC-80 …), a helyi builddel. Indításhoz kattints egyszer a panelbe: a böngésző a játék hangját csak kattintás után engedi elindulni, az emulátor pedig a hangjára vár. Az Open in browser ugyanezt egy teljes böngészőlapon nyitja meg.

A Play panel VS Code-ban: a helyben fordított C64 demó fut a hoszt EmulatorJS-runtime-jában

Képernyőkép: a fejlesztő gépén make build-del fordított C64 demó a teletypegames.org webes runtime-jában, VS Code-ban, az első kattintás után.

  1. Metaadat. A metadata.json-t gépelés közben ellenőrzi a hoszt platformhoz tartozó sémája, és minden mentéskor megkérdezi a hosztot, mit utasítana el a publikálás — hiányzó cím, más játék által foglalt polcnév, a kiadottnál régebbi verzió. Az Edit Metadata űrlapot nyit a fájl fölött.
  2. WarpEngine: Connect — létrehozza a repót a hoszt forge-án, bekapcsolja hozzá a CI-t, a titkai közé tesz egy CI-tokent, és felvesz egy draft katalógusrekordot; utána a munkapéldányt az új repóra állítja, és pushol. Elindul az első build.
  3. A státuszsor minden push után követi az aktuális commit pipeline-ját: forog, amíg fut, pipa vagy kereszt, ha végzett; kattintásra megnyílik a futás.
  4. WarpEngine: Release… — előbb csatornát kérdez: stable mindenkinek, vagy beta: előzetes kiadás (1.3.0-beta.1), amely látszik a listában, de csak annak ajánlja a katalógus, aki bétát kér — aztán megemeli a verziót ott, ahonnan a platform olvassa, megírja a CHANGELOG.md-t az utolsó kiadás óta érkezett commitokból, vX.Y.Z taget tesz és pushol. A pipeline lefordítja és publikálja, a kiadás pedig az asset-checklistjével együtt megjelenik a projektpanelen.

New Game: a platformlista a hoszttól jön, azzal együtt, mit publikál az adott platform, és játszható-e a weben

Képernyőkép: a New Game első lépése; a lista az, amit a teletypegames.org a /build/platforms végponton leír.

Az alapértelmezettől eltérő branchen minden push fejlesztői buildet készít: ez nem kerül a katalógus listájába, de a saját linkjén játszható és letölthető. A projektpanel This branch eleme ezt mutatja a linkjével (Copy Link a tesztelőknek), és értesítés jön, amikor egy push után elkészült.

Meglévő játéknál nyisd meg a mappát, és futtasd a WarpEngine: Add WarpEngine to This Project parancsot: hozzáadja a jelölőt, a metaadatot és a sablon fájljait, a meglévő fájljaidhoz pedig nem nyúl.

Mi van a panelen

Rész Mit mutat és mit tud
This Project platform, név és verzió, metaadat, Play, Check publish, Connect vagy Release, a pipeline az utolsó futásaival, a kiadások asset-checklisttel ([x] megépült, [ ] hiányzik, [-] kézi feltöltés)
Catalog a hoszt, kinek a nevében vagy belépve, minden szoftver platform szerint — cím, státusz, kategória és kiemelés helyben módosítható — kiadásokkal, linkekkel és letöltési statisztikával; a pipeline-ok
Státuszsor az aktuális commit pipeline-ja
Taskok a Makefile targetjei warpengine taskként, hibafelismeréssel ACME-hoz, cc65-höz, gcc-szerű fordítókhoz és Luához; a Build Like CI a platform saját builder-image-ében, Dockerben fordít
.woodpecker.yaml kiegészítés és súgó a platform: értékéhez, és egy link, amely megnyitja a teljes pipeline-t, amit a hoszt a jelölőből generál
AI a hoszt Admin API-ja MCP-szerverként van bejegyezve, így a szerkesztőben a Copilot vagy a Claude látja a katalógust, a kiadásokat és a pipeline-okat

A C64 demo pipeline-jelölője azzal a súgóval, amit a toolbox a platform: c64 sorra mutat

Képernyőkép: a .woodpecker.yaml-ban a platform: c64 fölé víve az egeret látszik, mit tud a hoszt a platformról.

Parancsok

Parancs Mit csinál
WarpEngine: New Game… új projekt a hoszt sablonjából (és demójából)
WarpEngine: Add WarpEngine to This Project jelölő, metaadat és sablonfájlok egy meglévő projekthez
WarpEngine: Connect repó, CI, CI-token és katalógusrekord egy lépésben, utána push
WarpEngine: Play in the Web Runtime a helyi build lefordítása és lejátszása
WarpEngine: Check Publish mit utasítana el a publikálás, hibaként a szerkesztőben
WarpEngine: Build Like CI (Docker) build a pipeline builder-image-ében
WarpEngine: Preview Pipeline a pipeline, amit a hoszt ennek a repónak kiszolgál
WarpEngine: Release… verzió, changelog, tag, push
WarpEngine: Edit Metadata űrlap a metadata.json fölött
WarpEngine: Set Host… a WarpEngine-hoszt kiválasztása vagy felvétele
WarpEngine: Sign In / Sign Out belépés és kilépés

Beállítások

Beállítás Alapérték Jelentés
warpengine.url üres a használt WarpEngine-hoszt címe
warpengine.hosts üres további hosztok, amelyek között a Set Host… váltani enged (name, url)
warpengine.checkOnSave true a metaadat minden mentésekor kérdezze meg a hosztot
warpengine.docker docker a parancs, amit a Build Like CI futtat
warpengine.defaultLocation a saját mappád ahová a New Game… az új projekteket ajánlja

Mi kell a hoszton

  • WarpEngine 4.0 vagy újabb, bekapcsolt Admin API-val — a bővítmény a GET /build/platforms-ot, a metadata-sémát, a POST /build/check-et, a tool sign-int és az Admin API-t használja.
  • Sablonok: a hoszt a platform_tooling-gal nevez meg platformonként egy sablont (és demót); enélkül a New Game csak a jelölőt, a metaadatot és egy README-t ír.
  • A Connecthez forge kell a hoszton (forge :gitea …), olyan tokennel, amely repót hozhat létre; enélkül a Connect azt válaszolja, hogy nincs forge.
  • A Play a hoszt /play-preview/ oldalát és a runtime-fájljait (/file/_runtimes/…) a bővítmény saját helyi szerverén át tölti be, a buildet pedig az oldalon belül adja át; a hoszt oldala semmit nem tölt le a fejlesztő gépéről.

A teletypegames.org-on a sablonok a build/*-tools repók, demóval az Ebitengine, a LÖVE, a Plus/4, a Godot (Pong), a Bevy és a Phaser.

Ha valami nem stimmel

Tünet Ok
A Catalog panel hosztot kér nincs beállítva a warpengine.url: Set Host…
A Play fekete marad kattints egyszer a panelbe; ha így is fekete, a hoszt régebbi a WarpEngine 3.8.2-nél
A Connect szerint nincs forge a hoszton nincs forge beállítva, vagy hiányzik a tokenje
Nincs pipeline a státuszsorban nem vagy belépve, vagy a projekt még nincs összekötve
A belépési oldal bejelentkezést kér az a hoszt adminfelülete: előbb lépj be ott adminisztrátorként

Forrás

A bővítmény a tools/warp-engine-toolbox repóban van. A make check a típusellenőrzést, a lintert és a unit teszteket futtatja; az npm run test:integration egy valódi VS Code-ot indít egy minta C64-projekttel, és a bővítményt egy hoszt ellen futtatja (WARPENGINE_TEST_URL, alapból a teletypegames.org).