pixel-mascot

Erstellen eines Pixel-Maskottchens

Ein Maskottchen ist eine einzelne SVG-Datei mit Pixel-Art und CSS-Schritt-Animation. Es kann mehrere Zustände haben (Leerlauf, glücklich, schlafen, laufen, Angriff …), jeder als Klasse auf dem Wurzelelement: <svg class="happy"> spielt happy ab. Baue Maskottchen mit Code, niemals durch händisches Bearbeiten von Hunderten von <rect>s: Der scripts/-Ordner dieses Skills (<kit> unten) enthält ein kleines Kit und ein Arbeitsbeispiel. Alles ist Python-Standardbibliothek; nichts muss installiert werden.

Lies LESSONS.md neben dieser Datei, bevor du etwas zeichnest. Es listet mit Symptom, Ursache und Lösung auf, was beim Erstellen der ersten Maskottchen schiefgegangen ist, und das meiste wird wieder schiefgehen, wenn man es überspringt.

Wo die Dateien hingehen

Frage den Benutzer, wo das Maskottchen aufbewahrt werden soll. Wenn er keine Präferenz hat, verwende ~/pixel-mascots/<name>/ (unter Windows %USERPROFILE%\pixel-mascots\<name>\):

Datei	Was es ist
make_<name>.py	der Builder: jede Änderung erfolgt als Bearbeitung hier und ein erneuter Durchlauf
<name>.svg	das Bauausgabe, das Maskottchen selbst
<name>_overrides.json	die manuellen Bearbeitungen des Benutzers aus dem Studio, die der Builder zuletzt anwendet
sheet.png	die Vorschau, ein Standbild pro Zustand

<name> besteht aus Kleinbuchstaben, Ziffern und Bindestrichen. Lege niemals Benutzerdateien in <kit> ab: es gehört zum installierten Plugin und wird bei Updates ersetzt.

Ausführen der Skripte

Verwende das Python, das die Maschine hat: python3 (macOS, Linux), python (Windows) oder uv run python, wenn ein Shim bloßes python blockiert. Builder importieren das Kit, also setze <kit> auf PYTHONPATH, wenn du eines ausführst:

PYTHONPATH="<kit>" python3 make_<name>.py <name>.svg

$env:PYTHONPATH = "<kit>"; python make_<name>.py <name>.svg

preview.py und das Studio benötigen keinen PYTHONPATH; das Studio setzt ihn für die Builder, die es ausführt.

Was das SVG tun muss

1. Ein Zustand pro Wurzelklasse. Gestalte jeden Zustand mit .<state> .part{...}-Selektoren; die Klassennamen sind die Zustandsnamen des Benutzers (Kleinbuchstaben, Bindestriche). Der Builder schreibt einen Standardzustand auf die Wurzel (s.svg(..., state="idle")), damit die Datei von selbst in einem Browser oder <img> animiert; eine App zeigt einen anderen Zustand, indem sie die Klasse der Wurzel ändert. Wenn keine Zustände benannt sind, erstelle einen: idle.
2. Setze jede Farbe in eine CSS-Klasse innerhalb ihres eigenen <style>. Eine CSS-Variable (var(--accent,#hex)) funktioniert nur dort, niemals als fill=-Attribut.
3. Animieren mit steps(1)-Keyframes, die ganze Zellen bewegen (translateY(-1px) in einem ViewBox aus Zellen) oder die Deckkraft blinken lassen.
4. Einen <title> (Alternativtext) und kein <script>, kein on…=, keine externen Bilder, Schriften oder Links, damit es überall sicher angezeigt werden kann.
5. Setze seine gezeichnete Größe mit width/height auf der Wurzel, ein ganzes Vielfaches des Rasters: 32 Zellen bei 128 px (4 px pro Zelle), 20 Zellen bei 80 px.
6. Respektiere reduzierte Bewegung, es sei denn, der Benutzer sagt etwas anderes: @media (prefers-reduced-motion:reduce){*{animation:none!important}}.

Der Arbeitsablauf

1. Lege fest, was das Maskottchen ist, seine Zustände und seine 3-5 Identitätsmerkmale. Frage, was es bei 128 px erkennbar macht, übertreibe genau diese und lasse alles andere weg. Frage, welche Zustände es braucht; bei keiner Antwort erstelle eine Leerlauf-Schleife. Die Idee des Benutzers entscheidet, nicht das Beispiel hier. Wenn der Benutzer Kunst anderer Künstler teilt, verwende sie nur zur Orientierung (Proportionen, Linienstil, wie ein Merkmal gezeichnet wird): kopiere niemals ihre Pixel und lege niemals einen urheberrechtlich geschützten Charakter in einen Bau, der geteilt oder veröffentlicht wird.

2. Finde seinen Typ in dieser Tabelle. Sie sagt, welche Teile aufgeteilt werden sollen (jedes Teil animiert unabhängig) und was sekundäre Bewegung tragen kann, was ein Maskottchen lebendig wirken lässt, statt wie ein Aufkleber, der hüpft.

   Typ	Typische Identitätsmerkmale	Teile, von hinten nach vorne	Sekundäre Bewegung
   Humanoider Charakter	Haarform und -farbe, Augen, ein Accessoire, Outfit, ein gehaltener Gegenstand	hair-back, body, head (Gesicht, Pony, vordere Strähnen), prop	Kopfnicken/Kopfwippen, Haar-Durchschwung, Prop-Schwung
   Tier	Ohren, Musterungen, Schwanz, Schnauze, Augenfarbe	tail, body, ears (im Kopf verschachtelt), head	Ohren schlackern, Schwanz wedeln, Kopf neigen
   Objekt (Lampe, Tasse, Pflanze, Staubsaugerroboter)	Silhouette, ein signifikantes Detail	back (Kabel, Ständer), body, face (ein Gesicht darauf gezeichnet), moving bits	Dampf- oder Blattwackeln, Licht blinken, Räder schrittweise
   Kreatur / Klecks / Roboter	Silhouette, ein ausgefallenes Merkmal (Horn, Antenne, Visier, Leuchten)	back, body, head, appendage	Stauchen und Strecken, Antennenwackeln, Leuchten blinken

   Maskottchen ohne Gesicht benötigen dennoch lesbare Zustände: ändere Haltung, Effekte und Geschwindigkeit anstelle des Ausdrucks.

3. Wähle die Leinwand. 20×20 für eine einfache Form mit wenigen Merkmalen; 32×32 für alles mit mehreren Merkmalen oder einem Gesicht, das Emotionen zeigen muss. Bei Charakteren auf Brust- oder Sitzhöhe beschneiden: Das Gesicht und die Identitätsmerkmale brauchen den Platz mehr als die Beine. Zeichne mit 4 px pro Zelle.

4. Kopiere die Vorlage, <kit>/example_mascot.py (Miso, eine Katze mit drei Zuständen), nach make_<name>.py in den Ordner des Maskottchens, setze NAME und ersetze die Formen und Zustände. Behalte den Builder: Das SVG ist ein Bauausgabe. Behalte den letzten Schritt der Vorlage, apply_overrides(...): er wendet die manuellen Bearbeitungen des Benutzers aus dem Studio (Schritt 10) an, sodass ein Neubau diese nie verliert.

5. Zeichne von hinten nach vorne, ein Teil pro Ding, das sich von selbst bewegt. Verschachtele ein Anhängsel in dem, woran es befestigt ist (Ohren im Kopf), damit es der Bewegung dieses Teils folgt und sich dennoch selbst bewegen kann. Kit-Werkzeuge: rect, ellipse, polygon (Ohren, Flossen, Hörner), path (Schwänze, Kabel, Stiele), line, zigzag_bottom (Haar- oder Fransenkanten), paint(..., only=...), um Details auf vorhandene Formen zu zeichnen, shade_edges für Schatten und Kanten. Rufe s.outline() einmal am Ende auf, damit jedes Teil seine eigene Kontur trägt. Bei Charakteren mit Haaren folge „Charaktere mit Haaren“ in LESSONS.md.

6. Ein Gesicht (oder eine Haltung) pro Zustand, als Gruppen, die mit Deckkraftregeln umgeschaltet werden: f-open standardmäßig, plus was immer zu jedem Zustand passt. Reaktionen lesen sich am besten, wenn sie sich in der Form unterscheiden, nicht nur in der Farbe: geschlossene ^ ^-Augen, halb geschlossene Augen, ein offener Mund, ein Schattenband. Gesichter, die auf einen Charakter mit Pony gezeichnet werden, überspringen die Haar-Zellen.

   • Passe jeden Zustand an den Charakter an. Wenn ein Zustand nicht zu ihm passt, frage nach und biete Momente aus seiner eigenen Geschichte an: eine charakteristische Geste oder Szene. Große Silhouettenänderungen lesen sich bei 128 px; kleine Details (ein 2-Pixel-Edelstein, ein Mund, der sich öffnet und schließt) nicht.
   • Ein Zustand kann ganze Teile austauschen, nicht nur Gesichter: ein Accessoire an oder aus, ein Hut zum Schlafen heruntergezogen. Mache jedes austauschbare Stück zu einem eigenen Teil und verstecke oder zeige es mit .<state> .part{opacity:…}. Beschränke jede solche Regel auf einen Zustand, damit die anderen Zustände ihre Teile behalten.
   • Wenn der Benutzer unsicher ist, baue Alternativen, anstatt für eine zu argumentieren: Lasse den Builder einen Variantennamen als Argument annehmen, baue jede in eine eigene Datei und zeige sie nebeneinander. Behalte die Variante, die der Benutzer mochte, bevor: Ein Zurücksetzen sollte ein Argument sein.

7. Effekte mit s.fx(name, cls, frames): Glitzer, Geschwindigkeitslinien, Z's, Wackelmarkierungen, Schweißtropfen. Frames werden zu s1, s2 …, um aus dem Takt zu animieren.

8. Bewegung: steps(1)-Keyframes und Ganzzellen-Bewegungen (Pixel-Art sollte schrittweise gehen, nicht gleiten). Die gesamte Figur sitzt in einer .rig-Gruppe, die hüpft oder schwankt; darüber:

   • der Kopf wippt, neigt oder nickt von selbst (bis zu 2 Zellen);
   • Anhängsel (Haare, Ohren, Schwanz, Antenne) folgen höchstens einen Viertelzyklus später; ein halber Zyklus bringt sie auf die gegenüberliegende Seite und wirkt wie eine Spur;
   • Requisiten und bewegliche Teile laufen leicht aus dem Takt. Eine Leerlauf-Schleife ist langsam und klein: Atmen, ein Blinzeln, ein Schwanz.

9. Baue und schaue es dir an, bevor du es jemandem zeigst (Befehle wie unter „Ausführen der Skripte“):

   PYTHONPATH="<kit>" python3 make_<name>.py <name>.svg
   python3 <kit>/preview.py <name>.svg sheet.png
   

   lies dann sheet.png: ein Standbild pro Zustand, von links nach rechts. Die Vorschau zeigt nur Ruheposen. Um die Bewegung zu sehen, starte das Studio im Hintergrund und öffne http://127.0.0.1:8765/ in einem Browser (den integrierten Browserbereich, falls vorhanden):

   python3 <kit>/studio/server.py --svg <name>.svg --build make_<name>.py
   

   Es zeigt jeden Zustand in seinem eigenen Frame animiert. --states a,b wählt aus und ordnet die Zustände (Standard: jeder Zustand, den das CSS verwendet, in der Reihenfolge ihres ersten Auftretens); --port ändert den Port. Benutzer überprüfen anhand von Screenshots und markieren Probleme oft in Rot: Ordne die Markierungen den Zellen zu, indem du sie an Merkmalen ausrichtest, die du kennst (die Augenreihe, der Mund), und zeichne dann entlang ihnen neu. Nach einem Refactoring, das nichts Sichtbares ändern sollte, baue die alte und die neue Version und vergleiche die Dateien Byte für Byte (cmp oder fc /b).

10. Manuelle Bearbeitungen. Wenn der Benutzer Pixel selbst reparieren möchte, schicke ihn zum /editor.html des Studios: male, radiere und wähle Farben pro Zustand, mache rückgängig, speichere dann, was <name>_overrides.json schreibt und neu baut. Jeder Pixel gehört zu einem Teil und bewegt sich mit ihm; der Editor sagt, welches Teil und welche Zustände ihn zeigen. Ein Maskottchen ohne Builder funktioniert auch (lasse --build weg): Das Studio behält eine unberührte Kopie und die Bearbeitungen in <name>_studio/ neben dem SVG und schreibt das Ergebnis in das SVG. Nachdem der Benutzer bearbeitet hat, lies seine Overrides-Datei und die neu erstellte Vorschau, bevor du etwas anderes änderst, und sage, ob eine Bearbeitung versehentlich aussieht (ein einzelner Pixel weit weg vom Rest).

11. Übergib es: Sage, wo das SVG ist, welchen Zustand es standardmäßig abspielt und wie man einen anderen anzeigt (setze die Klasse der Wurzel; ein <img> kann das nicht, also eine App, die Zustände wechselt, bindet das SVG ein oder lädt es in einem <object> oder <iframe>).

profile.json (für eine App, die das Maskottchen anzeigt)

Eine App benötigt möglicherweise mehr als Wurzelklassen: CSS-Variablen auf der Wurzel, zusätzliche Klassen, feste Zustandsbezeichnungen. Eine profile.json im <kit> neben preview.py teilt der Vorschau und dem Studio mit. Jeder Schlüssel ist optional:

{
  "states": [{ "class": "happy", "name": "happy", "label": "happy · bei Erfolg", "style": "--speed:.5s" }],
  "rootClass": "always-animate",
  "swatches": { "var": "--accent", "label": „Akzent“, "colors": ["#8FA8E8", "#ED93B1"] },
  "workdir": "~/my-app/studio"
}

states legt die Reihenfolge, die Schaltflächennamen, die Beschriftungen und einen Wurzelstil pro Zustand fest; rootClass wird in jedem Frame zur Wurzel hinzugefügt; swatches fügt Farbtasten hinzu, die eine CSS-Variable setzen; workdir ersetzt <name>_studio/ für Maskottchen ohne Builder. Dieses Plugin liefert keine mit.

Dateien in diesem Skill

Datei	Was es ist
LESSONS.md	Was funktioniert hat und was nicht, mit Ursachen und Lösungen. Zuerst lesen.
scripts/pixelkit.py	Formen (rect, ellipse, polygon, path, line), Teile, Schattierung, Teile-Konturen, SVG-Ausgabe.
scripts/example_mascot.py	Miso: eine 32×32 Katze mit Leerlauf, glücklich und schlafen; die Vorlage zum Kopieren.
scripts/preview.py	PNG-Blatt, ein Standbild pro Zustand, nur Standardbibliothek.
scripts/pixel_overrides.py	Wendet manuelle Bearbeitungen auf ein fertiges SVG an; Builder rufen es zuletzt auf.
scripts/studio/	server.py + site/: jeden Zustand animiert, und einen Pixel-Editor, für jedes Maskottchen. Nur lokal (127.0.0.1).