HARAPEKO SHIROHEBI

01Einstieg

Dieser Leitfaden erklärt HARAPEKO SHIROHEBI von der Controllereingabe bis zur Bildschirmausgabe. Das Spiel stammt von DAISUKE OBA. Die weiße Schlange frisst Granatäpfel und wächst dabei; Minen und der eigene Körper müssen vermieden werden. Das mitgelieferte Programm, die selbst erstellten Ressourcen und dieser Leitfaden stehen unter der MIT-Lizenz.

Der Bildschirm hat 160 × 144 Pixel. Eine ROM unterstützt sowohl den ursprünglichen Game Boy (DMG) als auch den Game Boy Color (CGB); die Farbdarstellung wird zur Laufzeit gewählt. Das Modul verwendet MBC5, 64 KiB ROM und 8 KiB batteriegepufferten RAM. Die spielbare Fassung ist auf der itch.io-Seite des Spiels erhältlich.

Empfohlene Lesereihenfolge: Beginnen Sie mit dem Ablaufdiagramm und lesen Sie dann die Abschnitte zur Kopfbewegung und zum Körper gemeinsam. Die Bibliothekstabelle verweist zu jeder Technik auf den passenden Quellcode. Apple und Block in Bezeichnern stehen für den Granatapfel beziehungsweise die Mine auf dem Bildschirm.

↑ Zum Inhaltsverzeichnis

02Build und Dateiaufbau

Mit Rust 1.85 oder neuer lassen sich Compiler und sämtliche Hilfswerkzeuge für Windows, Linux, macOS ARM und macOS Intel bauen. Die nativen Programme benötigen kein .NET; die Werkzeuge für Grafikdaten benötigen auch weder Python noch Pillow.

Die PowerShell-Skripte verwenden das Windows-Programm im Stammverzeichnis. Unter Linux/macOS übergeben Sie dieselben C-Eingaben und Optionen an den nativen Compiler oder verwenden PowerShell 7. CHR-Grafik und C-Quellen sind getrennte Eingaben; font.chr bewahrt die Schrift der Beispiele.

powershell -NoProfile -ExecutionPolicy Bypass -File .\apps\harapeko_shirohebi\build.ps1

Das Build-Skript fügt 17 C-Quelldateifragmente in einer festgelegten Reihenfolge zusammen. Musik, exportierte Ressourcen und die Wrapper zur Bankauswahl sind separate Compilereingaben. Der Build bindet lib/ aus dem Repository ein und benötigt weder ein privates Grafikprojekt noch ein Exportwerkzeug. Fügen Sie die Fragmente nicht einzeln zu einem gewöhnlichen C-Projekt hinzu: Sie teilen sich Deklarationen innerhalb der zusammengefügten Übersetzungseinheit.

Warum der Build eine Nachbearbeitung braucht

Der VBlank-Musikinterrupt muss bei jeder ausgewählten umschaltbaren ROM-Bank auf seinen Code zugreifen können. Das Skript prüft, ob vier interruptbezogene Symbole in der festen Bank 0 liegen, installiert einen JP bei $0040 und berechnet beide Modulprüfsummen neu. Ein unerwarteter Interruptvektor führt zum Abbruch. Eine temporäre Kopie des Audiocodes deaktiviert den gewöhnlichen Musikdienst, damit Hauptschleife und Interrupt die Musik nicht doppelt weiterschalten. Eine weitere temporäre Kopie platziert die Audiohilfsfunktionen und verwendet einen absoluten Sprung mit erreichbarem Ziel. Die Bibliotheksdateien im Repository bleiben unverändert.

Die vollständige Eingabereihenfolge und alle Compileroptionen stehen in build.ps1. Die wichtigsten Optionen sind --profile=release --stack-bank=fixed --rst-disable --cgb=cgb --cart=mbc5_ram_battery --romsize=64k --ramsize=8k.

↑ Zum Inhaltsverzeichnis

03Programmablauf und Zustände

Die Freigabesperre verwirft Eingaben, bis alle Tasten losgelassen wurden, einschließlich des Durchlaufs, in dem das Loslassen erkannt wird. So bestätigt eine Taste, die einen Bildschirm geöffnet hat, nicht sofort dessen nächste Aktion. Der Demomodus ersetzt die Lenkeingaben und nutzt denselben Bewegungs- und Kollisionscode. Die Wartezeit auf dem Titel wird in 900 Hauptschleifendurchläufen gezählt, die Demodauer in 1.800 VBlank-Ereignissen. Keiner der beiden Zähler garantiert eine genaue reale Zeitspanne.

↑ Zum Inhaltsverzeichnis

04Kopfbewegung: Festkomma und Lenkung

Nur der Kopf ist ein KQBody2D. Seine KQWorld2D enthält einen aktiven Körper, keine Schwerkraft und null Iterationen der Kontaktauflösung. Das Spiel prüft Kollisionen selbst nach der Bewegung. Q4-Koordinaten verwenden 16 ganzzahlige Einheiten pro Pixel: 160 steht für 10 Pixel. Dadurch bleiben Bewegungen unterhalb eines Pixels ohne Gleitkommarechnung erhalten.

base = 8 + 2 * min(score / 5, 10)     // Q4 component limit
first UP update: limit = base + (base >> 2)
held UP:        limit += max(base >> 2, 1), capped at 2 * base
released UP:    limit -= max(base >> 2, 1), floored at base
pixel_center = (q4_position + 8) >> 4

Die Grundgrenze für eine Geschwindigkeitskomponente reicht von 0,5 bis 1,75 Pixel pro Update. Die 16 Richtungen laufen im Uhrzeigersinn: rechts (0), unten (4), links (8), oben (12). LEFT und RIGHT ändern die Zielrichtung jeweils um einen Sektor. Bei gehaltener Taste wird zunächst ein Countdown von 8, dann wiederholt einer von 4 verwendet. Gleichzeitiges LEFT und RIGHT hebt die Drehung auf.

Die Zielgeschwindigkeit verwendet Komponenten mit dem vollen Wert, drei Vierteln, einem Viertel oder null. Jede tatsächliche Komponente nähert sich ihrem Ziel um höchstens 3 Q4-Einheiten pro Update. Das sind günstige ganzzahlige Näherungen, keine trigonometrisch normierten Vektoren. Daher kann sich die angezeigte Blickrichtung ändern, bevor sich die Geschwindigkeit vollständig angepasst hat.

Nach kq2d_step springt der Kopf an den gegenüberliegenden Rand, wenn sein Mittelpunkt die Grenzen überschreitet: X unter 4 wird zu 156, X über 156 zu 4; für Y gelten entsprechend 4 und 140. Anschließend wird einmal auf Pixelkoordinaten gerundet, die sowohl Darstellung als auch Kollisionsprüfung verwenden. Diese Kopfregel unterscheidet sich vom Umlauf modulo 160/144 für den Körper.

Siehe shirohebi_snake.c / shirohebi_flow.c.

↑ Zum Inhaltsverzeichnis

05Wie der Körper dem Kopf folgt

ChainBody verweist direkt auf SND_TraceX, SND_TraceY und SND_TraceDir. Diese Arrays speichern die aktuelle Position und Richtung jedes Segments, nicht den bisherigen Weg des Kopfes. Kollisionsprüfung und Darstellung lesen dieselben Arrays. Die Schlange beginnt mit einem Kopf und drei Körpersegmenten und wächst auf höchstens 31 Segmente einschließlich Kopf.

1. Pixelposition und Richtung des Kopfes an Index 0 ablegen; pull auf diese Richtung setzen.
2. Für Segment i zunächst die alte Richtung sichern. Von der bereits aktualisierten Position des Vorgängers einen kleinen richtungsabhängigen Versatz abziehen, um die Zielposition zu erhalten.
3. Den kürzesten X/Y-Versatz zum Ziel unter Berücksichtigung des umlaufenden Feldes ermitteln. Jede Achse gemäß der folgenden Tabelle um 0, 1 oder 2 Pixel bewegen.
4. Die Segmentrichtung auf pull setzen, die neue Position in das umlaufende Feld zurückführen und die gesicherte alte Richtung an Segment i + 1 weitergeben.

Die X-Versätze für die Richtungen 0 bis 15 lauten [4,4,3,1,0,-1,-3,-4,-4,-4,-3,-1,0,1,3,4]; Y verwendet dieselben Werte mit einem um 12 Sektoren verschobenen Index. Koordinaten laufen innerhalb eines Feldes von 160 × 144 Pixeln um. Bei einer Achsenlänge W wird von einem Versatz über W/2 der Wert W abgezogen und bei einem Versatz unter −W/2 addiert. Ein Versatz von genau einer halben Feldlänge behält sein Vorzeichen.

Rechenbeispiel am Bildschirmrand

Ein nach rechts gerichtetes Vorgängersegment bei (2, 50) setzt das Ziel des folgenden Segments vier Pixel hinter sich: Ziel-X = (2 − 4) mod 160 = 158. Steht der Nachfolger bei X=156, beträgt der Versatz +2; er bewegt sich um +1 nach X=157. Bei X=0 ist der kürzeste Versatz dagegen −2, sodass er nach X=159 gelangt. Er folgt also über den Rand, statt den gesamten Bildschirm zu durchqueren.

Beim Wachsen werden Position und Richtung der Schwanzspitze kopiert und die Zahl aktiver Segmente erhöht. Bei den folgenden Updates entfernt sich das neue Segment allmählich von der bisherigen Schwanzspitze. Diese wird 20 Updates lang hervorgehoben. Der Bibliothekswrapper hält die Nachführungsfunktion und ihre Hilfsfunktionen gemeinsam in Bank 2; dadurch entfällt ein Bankwechsel pro Segment.

/* Excerpt: the game owns these arrays for the entire run. */
chain_body_init(&SND_ChainBody, SND_TraceX, SND_TraceY, SND_TraceDir,
                SND_MAX_SEGMENTS, SND_SCREEN_W, SND_SCREEN_H);
chain_body_reset(&SND_ChainBody, SND_Length,
                 SND_HeadX, SND_HeadY, SND_Facing);

/* Once per PLAY update, after integrating and rounding the head. */
SND_ChainBody.count = SND_Length;
chain_body_step(&SND_ChainBody, SND_HeadX, SND_HeadY, SND_Facing);

/* On fruit collection, within capacity. */
chain_body_grow(&SND_ChainBody);
SND_Length = SND_ChainBody.count;

Dieser Ausschnitt zeigt die Lebensdauer der Arrays und die Aufrufreihenfolge. Das vollständige Spiel prüft außerdem, ob das Wachstum erfolgreich war, und setzt die Hervorhebung. Quellen: shirohebi_snake.c / shirohebi_chain.c / chain.c.

↑ Zum Inhaltsverzeichnis

06Früchte, Kollisionen und Verlustanimationen

Ein PLAY-Update verarbeitet Beschleunigung → Lenkung → Kopfphysik → Randsprung und Rundung des Kopfes → Körpernachführung → Minen → Selbstkollision → Frucht → Ende der Hervorhebung. Innerhalb eines Updates haben tödliche Treffer Vorrang vor dem Einsammeln einer Frucht.

Die Tests vergleichen getrennte Achsenabstände, keine kreisförmige Entfernung. 16 feste Fruchtpositionen werden in einer vorgegebenen Reihenfolge geprüft. Der Mindestabstand zu Minen in Kacheln sinkt mit der Punktzahl: 4, 3, 2, 1 bei 0, 10, 20, 30 Punkten. Eine Position auf derselben Kachel wie eine Mine wird immer verworfen. Eine Suche prüft höchstens 16 Kandidaten. Die Punktzahl ist ein 8-Bit-Wert und kann daher nicht unbegrenzt wachsen.

Bei einer Selbstkollision bleibt die Körperhaltung stehen und wird ausgeblendet. Ein Minentreffer verteilt die Segmente mit Festkommageschwindigkeiten, verzögert einsetzender Schwerkraft und zeitlich versetzten Explosionen; zuletzt erscheint ein Krater. Nach Ablauf des Verlusttimers führt ein geeigneter Punktestand zur Namenseingabe, jeder andere zur Abfrage für eine neue Runde. CGB verwendet Farben für die Effekte, DMG seine Graustufenpaletten.

shirohebi_collision.c / shirohebi_apples.c

↑ Zum Inhaltsverzeichnis

07Darstellung: Kacheln und Sprite-Reihenfolge

Die Initialisierung wartet auf eine sichere Anzeigephase, schaltet das LCD aus, löscht den VRAM, lädt Kachel-, Schrift- und Palettendaten und aktiviert die Anzeige. Der CGB-Pfad setzt Hintergrundattribute und Farbpaletten, der DMG-Pfad Graustufenregister. Der exportierte Hintergrund ist 20 Kacheln breit, während die Hardwarekarte einen Zeilenabstand von 32 Kacheln hat. Die Indizes sind daher nicht austauschbar.

In jedem Schleifendurchlauf erstellt das Spiel einen Schatten-OAM-Puffer im RAM. Die Sprite-Koordinaten werden mit den Hardwareversätzen X+8 und Y+16 geschrieben. Nach system_wait_vblank() werden die OAM-Daten übertragen. Die Schlange belegt die Plätze 0 bis 30, Text nutzt die übrigen. Nicht verwendete Einträge werden gelöscht.

Die ersten sechs Segmente behalten eine feste OAM-Priorität. Die Reihenfolge der übrigen rotiert mit einer Phase, die pro Darstellung um vier steigt. Dadurch verteilt sich die Wirkung der Hardwaregrenze von zehn Sprites pro Bildschirmzeile auf die hinteren Segmente. Weder die Grenze noch Körpersegmente werden dadurch entfernt. Bei Änderungen an der Maximallänge müssen sowohl die Arraykapazität als auch die Belegung aller 40 OAM-Plätze geprüft werden.

START- und PAUSE-Einblendungen führen getrennt den gewünschten und den angezeigten Zustand sowie einen Änderungsmerker. Beim Entfernen des Textes wird jede Zelle zunächst anhand der aktuellen Fruchtposition und erst dann bei Bedarf aus der Hintergrundkarte wiederhergestellt. Eine einheitliche leere Kachel würde eine darunterliegende Frucht löschen. Zeichenmasken werden aus acht Zeilen mit einem Bit pro Pixel in sechzehn Byte Kacheldaten mit zwei Bit pro Pixel umgewandelt; Zeichenpixel haben Vorrang vor dem Hintergrundmuster.

shirohebi_render.c / shirohebi_display.c / shirohebi_pause.c

↑ Zum Inhaltsverzeichnis

08Musik und VBlank

audio_vblank.c liest den Musikstrom aus der festen Bank. Normale Datensätze folgen der Reihenfolge Wartezeit, CH1, CH2, CH3, CH4: Puls mit Frequenz-Sweep, Puls, Wellenform, Rauschen. Die Kanalzuordnung entspricht damit der Hardware. Die Musik wird mit AudioVBlank_PlayMusic, AudioVBlank_Stop und AudioVBlank_SetEnabled gesteuert.

Der gewöhnliche Treiber audio.c verarbeitet die Soundeffekte des Spiels. Sein Musikdienst wird durch eine temporäre Präprozessordefinition beim Build ausgeschlossen. Effekte bestimmen die Bank ihrer Daten mit __bankof und verwenden Prioritäten; der Mineneffekt nutzt zusätzlich direkt CH4-Rauschen. Die Pause stimmt Musik und Effekte aufeinander ab. Die Aufrufe von SND_AudioServiceWork in der Hauptschleife sind absichtlich wirkungslos: Zusätzliche Körpersegmente dürfen den Musiktakt nicht beschleunigen.

AudioVBlank_FrameHook ruft SND_DemoVBlankHook aus der festen Bank des Spiels auf. Der Hook erhöht einen 8-Bit-Demozähler und liest die Systemtastengruppe unter Beibehaltung der P1-Auswahl. Bei aktivierter Funktion merkt er sich SELECT+START im Titel und SELECT während der Pause, damit kurze Tastendrücke bei ausgelasteter Hauptschleife nicht verloren gehen. Er zeichnet nichts und ruft keine Funktionen aus umschaltbaren Banken auf.

/* Excerpt from initialization, after shared state has been set up. */
SND_AudioInit();
AudioVBlank_FrameHook = SND_DemoVBlankHook;
AudioVBlank_EnableIrq();

shirohebi_audio.c / shirohebi_lib_bank0.c / music.c

↑ Zum Inhaltsverzeichnis

09Punktestand speichern und Namen eingeben

Speicherplatz 0 enthält 42 Byte Anwendungsdaten: Kennung 0x53, Version 2, zehn Punktzahlen von je einem Byte und dreißig Namenszeichen. Die Speicherbibliothek prüft die umschließende Länge und Prüfsumme. Der Leser erkennt außerdem Punktedaten von 5 und 15 Byte; geschrieben wird im 42-Byte-Format.

Eine von null verschiedene, für die Bestenliste geeignete Punktzahl wird absteigend einsortiert. Der Vergleich ist strikt größer, weshalb gleiche Punktzahlen hinter vorhandenen Einträgen stehen. Namen werden zusammen mit ihren Punktzahlen verschoben. Ein neuer Eintrag beginnt im RAM mit AAA; erst nach Bestätigung des dreistelligen Namens schreibt das Spiel in den SRAM. Wird ein noch nicht bestätigtes Ergebnis verworfen, lädt es die gespeicherte Bestenliste erneut.

UP und DOWN wählen A–Z oder einen Punkt. RIGHT und SELECT wechseln zyklisch zum nächsten Zeichen, LEFT zum vorigen. B geht nur zurück, wenn der Cursor nicht auf dem ersten Zeichen steht. A wechselt weiter oder bestätigt beim letzten Zeichen; START bestätigt von jeder Position aus. Die Freigabesperre verhindert, dass diese Bestätigung gleichzeitig die nächste Runde auswählt.

shirohebi_save.c / shirohebi_flow.c

↑ Zum Inhaltsverzeichnis

10KITAQGB-Bibliotheken verwenden

Verwenden Sie Bibliothek und Header aus dem Repository gemeinsam. Die spielbezogenen Wrapper und Einstellungen gehören zum Beispiel, insbesondere die Bankplatzierung und die Abstimmung der Audiotreiber.

Compiler-Intrinsics im Zusammenspiel mit den Bibliotheken

__readpadex(previous) liefert gehaltene Tasten im niederwertigen Byte und neu gedrückte im höherwertigen Byte. __cgb_is_cgb() dient zur Auswahl des Farbpfads. Kachel- und Attribut-Intrinsics wie __settile und __settileattr ändern Hintergrundzellen; __bankof liefert die ROM-Bank der Effektdaten. Diese Funktionen stellt der Compiler bereit. Zusätzliche C-Implementierungen müssen dafür nicht ins Spiel kopiert werden.

↑ Zum Inhaltsverzeichnis

11Wegweiser durch den Quellcode und Hinweise zu Änderungen

Bei Änderungen am Spiel prüfen

• Geschwindigkeit und Lenkung: Nach Änderungen an den Q4-Konstanten langsame Kurven und die Beschleunigung mit UP prüfen. Der Blickrichtungssektor des Kopfes ist nicht seine exakte Geschwindigkeitsrichtung.
• Länge: Arraykapazität, Kettenkapazität und OAM-Reservierung gemeinsam ändern. Minen- und Selbstkollisionen an der Schwanzspitze sowie die Sprite-Grenze pro Zeile prüfen.
• Grafik: Kachelnummern, Zeilenabstand der Karte und CGB-Attribute beibehalten. Beim Entfernen von Einblendungen den aktuellen Inhalt der darunterliegenden Zelle wiederherstellen.
• Audio: Interruptcode in der festen Bank halten und genau eine Quelle für das Fortschalten des Musiktakts sicherstellen. Neben normaler Wiedergabe auch Pause und Fortsetzung testen.
• Speichern: Bei geändertem Datenaufbau die Formatversion ändern. Vor indizierten Zugriffen die Länge prüfen und frischen sowie ungültigen SRAM testen.

Verwenden Sie nach dem Neubau die zu diesem Build gehörende Adressdatei. Prüfen Sie Titel, START-Einleitung, Bewegung, Lenkung, Früchte, Selbst- und Minentreffer, Pause und Fortsetzung, Rückkehrbestätigung und Bestenliste in beiden Hardwaremodi. Ein erfolgreicher Build allein belegt weder diese Abläufe noch korrektes Verhalten auf echter Hardware.

↑ Zum Inhaltsverzeichnis