Grafiken automatisch in deinen Build holen
Mit einem API-Schlüssel holt dein Spiel-Repository die aktuellen Stände deiner Grafiken selbst aus deinem NoAliasTools-Konto, zum Beispiel bei jedem Build über GitHub Actions. Du änderst eine Grafik, und der nächste Build hat sie.
So funktioniert es
Deine Grafiken liegen als Dateien in deinen Cloud-Projekten. Deine Pipeline holt sie mit einem API-Schlüssel im Format deiner Engine ab, für Godot, Unity, Phaser, Aseprite oder TexturePacker, mit Atlas, Clips und Frame-Dauern. Hat sich nichts geändert, lädt sie nichts. Exportieren von Hand und veraltete Grafiken im Repository fallen weg.
API-Schlüssel gehören zum Tarif Studio. Tarife ansehen
Einrichtung
- Lege im Kontobereich unter „API-Schlüssel“ einen Schlüssel an. Gib ihm einen Namen, beschränke ihn bei Bedarf auf ein Projekt und setze ein Ablaufdatum.
- Kopiere den Schlüssel sofort. Er wird nur dieses eine Mal angezeigt.
- Hinterlege ihn in deiner Pipeline als Secret NOALIAS_API_KEY. Bei GitHub findest du das unter Settings → Secrets and variables → Actions.
- Lade im Build den Export deines Projekts im Format deiner Engine und pack ihn in den Asset-Ordner deines Spiels aus.
Formate
Wähle mit format= das Format deiner Engine. Jedes ZIP enthält außerdem SpriteForge/runtime.json und SpriteForge/export-manifest.json mit Clips, Frame-Dauern und Abspielmodus.
- format=godot
- Godot: SpriteFrames als .tres mit Atlas-PNG.
- format=unity
- Unity: Atlas-PNG mit JSON und Importer-Skript für den Editor.
- format=phaser
- Phaser: Atlas-PNG mit JSON zum Laden als Atlas.
- format=aseprite
- Aseprite-JSON mit Frame-Tags und Dauern; viele Engines und Werkzeuge lesen es.
- format=texturepacker-hash
- TexturePacker-JSON mit Frames als Objekt.
- format=texturepacker-array
- TexturePacker-JSON mit Frames als Liste.
- format=png
- Ein PNG-Spritesheet je Clip, ohne Metadaten außer dem Manifest.
- format=gif
- Ein animiertes GIF je Clip, etwa für Vorschauen.
Weitere Angaben: mode=atlas packt alle Clips auf gemeinsame Seiten, mode=batch liefert je Clip einen Satz; scales=1,2 exportiert in mehreren Größen (1 bis 4); trim, extrude, spacing, power_of_two und max_size steuern das Packen; normal_maps=1 und palette_variants=1 nehmen Normal Maps und Palettenvarianten mit.
Was du abrufen kannst
Alle Adressen beginnen mit https://api.noaliastools.com/api/v1/build und lassen sich mit GET oder HEAD abrufen.
- /projects/{project}/export?format=…
- Alle Grafiken eines Projekts im gewählten Format als ZIP, jede Datei in einem eigenen Ordner.
- /files/{file}/export?format=…
- Eine einzelne Grafik im gewählten Format als ZIP; mit clip= nur ein Clip.
- /projects
- Deine Projekte mit Namen und letzter Änderung.
- /files
- Deine aktuellen Dateien mit Größe, Prüfsumme und Download-Adresse. Mit ?project_id= nur die eines Projekts.
- /files/{file}/current
- Die bearbeitbare SpriteForge-Datei, falls du die Quelle brauchst.
- /assets
- Fertige Bilder aus PixelFoundry und deine SpriteForge-Dateien.
- /results
- Die abgeschlossenen Ergebnisse deines Assistenten, jeweils mit SpriteForge-Datei (/project) und PNG-Spritesheet des Hauptclips (/sheet.png).
Listen kommen seitenweise mit 50 Einträgen; mit page und per_page (bis 100) blätterst du weiter.
Beispiele
Alle Grafiken eines Projekts für Godot in zwei Größen holen; PROJECT_ID steht in der Liste unter /projects:
# sprites.etag und sprites.zip zwischen den Läufen aufbewahren.
curl --fail --silent --show-error \
--header "Authorization: Bearer $NOALIAS_API_KEY" \
--etag-compare sprites.etag --etag-save sprites.etag \
--output sprites.zip \
"https://api.noaliastools.com/api/v1/build/projects/$PROJECT_ID/export?format=godot&scales=1,2"
Nur laden, wenn sich etwas geändert hat. curl merkt sich dafür den ETag in sprites.etag; bei unverändertem Stand kommt HTTP 304 ohne Inhalt, und dein vorhandener Export bleibt gültig.
Für GitHub Actions hinterlegst du NOALIAS_API_KEY als Actions-Secret und die Projekt-ID als Variable NOALIAS_PROJECT_ID. Dieser Workflow holt die Grafiken für Godot und packt sie nach assets/sprites aus:
name: Sprites
on: [push, workflow_dispatch]
permissions:
contents: read
jobs:
sprites:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Download sprites
env:
NOALIAS_API_KEY: ${{ secrets.NOALIAS_API_KEY }}
PROJECT_ID: ${{ vars.NOALIAS_PROJECT_ID }}
run: |
curl --fail --silent --show-error \
--header "Authorization: Bearer $NOALIAS_API_KEY" \
--output sprites.zip \
"https://api.noaliastools.com/api/v1/build/projects/$PROJECT_ID/export?format=godot"
unzip -o sprites.zip -d assets/sprites
Grenzen und Sicherheit
- Ein Schlüssel kann nur lesen. Er ändert und löscht nichts und hat keinen Zugang zu deinem Assistenten, zu Freigaben oder zur Abrechnung.
- Er sieht nur deine eigenen Projekte, nicht die Teamprojekte anderer. Ist er auf ein Projekt beschränkt, sieht er nur dieses.
- Es gelten 60 Anfragen pro Minute für dein Konto und 120 pro IP-Adresse. Darüber antwortet die API mit 429 und sagt in Retry-After, wie viele Sekunden du warten sollst.
- Widerruf und Ablauf beenden den Zugriff sofort. Änderst du dein Passwort oder setzt es zurück, werden alle Schlüssel widerrufen, und du legst neue an.
- Endet dein Tarif, lesen die Schlüssel nichts mehr. Buchst du Studio wieder, funktionieren sie wieder, solange sie nicht abgelaufen oder widerrufen sind.
- Übergib den Schlüssel nur im Authorization-Header. Schreib ihn nie in Adressen, Dateien im Repository oder Logs, und lass in der Pipeline set -x und curl -v weg.
- Läuft dein Workflow öffentlich, veröffentliche die geladenen Grafiken nicht als öffentliches Artefakt.