Zum Inhalt springen

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

  1. 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.
  2. Kopiere den Schlüssel sofort. Er wird nur dieses eine Mal angezeigt.
  3. Hinterlege ihn in deiner Pipeline als Secret NOALIAS_API_KEY. Bei GitHub findest du das unter Settings → Secrets and variables → Actions.
  4. Lade im Build den Export deines Projekts im Format deiner Engine und pack ihn in den Asset-Ordner deines Spiels aus.
Tarife ansehen →

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.