MiSTer FPGA – achievements.cpp Dev Guide

Voraussetzungen – Diese Programme müssen laufen

Visual Studio Code

Editor

Zum Bearbeiten der achievements.cpp

Geöffnet & bereit

PowerShell / WSL

Terminal

Für alle bash-Befehle. WSL muss gestartet sein (wsl in PS eingeben).

WSL-Prompt aktiv

Docker Desktop

Build-Umgebung

Muss im Hintergrund laufen. Icon in der Taskleiste muss grün sein.

Im Hintergrund aktiv

MiSTer FPGA

192.168.178.80

Eingeschaltet und im Heimnetz erreichbar. Nur für den Deploy-Schritt nötig.

Eingeschaltet & im Netz

Einmalige Einrichtung

WSL & Cross-Compiler installieren

In Windows Terminal oder PowerShell: WSL öffnen, dann Compiler und Tools installieren.

WSL starten

# In PowerShell / Windows Terminal
wsl
# Danach im Ubuntu-Terminal:
cd ~

Pakete installieren

sudo apt install build-essential gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf make git

Symlinks anlegen (einmalig – Compiler-Name-Fix)

sudo ln -s /usr/bin/arm-linux-gnueabihf-gcc    /usr/bin/arm-none-linux-gnueabihf-gcc
sudo ln -s /usr/bin/arm-linux-gnueabihf-g++    /usr/bin/arm-none-linux-gnueabihf-g++
sudo ln -s /usr/bin/arm-linux-gnueabihf-ld     /usr/bin/arm-none-linux-gnueabihf-ld
sudo ln -s /usr/bin/arm-linux-gnueabihf-objcopy /usr/bin/arm-none-linux-gnueabihf-objcopy
sudo ln -s /usr/bin/arm-linux-gnueabihf-objdump /usr/bin/arm-none-linux-gnueabihf-objdump
sudo ln -s /usr/bin/arm-linux-gnueabihf-strip   /usr/bin/arm-none-linux-gnueabihf-strip

Die Symlinks sind nötig, weil das Makefile arm-none-linux-gnueabihf-gcc erwartet, Ubuntu aber nur arm-linux-gnueabihf-gcc mitliefert.

Docker Desktop installieren

Docker wird für den MiSTer-kompatiblen Build benötigt (glibc 2.31 – passt zum MiSTer Linux).

Installation (PowerShell als Admin)

winget install Docker.DockerDesktop

Nach der Installation: Docker Desktop starten → Settings → Resources → WSL Integration → Ubuntu aktivieren → Apply & Restart.

Warum Docker? Der MiSTer läuft auf glibc 2.31. Ubuntu 24.04 nutzt eine neuere glibc – Binaries starten dann nicht. Docker mit Ubuntu 20.04 liefert die korrekte Version.

Repository klonen

Odelots Fork des Main_MiSTer mit RetroAchievements-Integration.

cd ~
git clone https://github.com/odelot/Main_MiSTer.git
cd Main_MiSTer
code .    # VS Code mit WSL-Integration öffnen

Wichtig: immer im Heimverzeichnis ~/Main_MiSTer arbeiten, nicht in /mnt/c/...!

Wiederholender Workflow

achievements.cpp bearbeiten

Datei in VS Code öffnen, Änderungen vornehmen, speichern.

# Im Main_MiSTer-Ordner in WSL:
code achievements.cpp    # oder: code .

VS Code öffnet sich auf Windows, greift aber direkt auf das WSL-Dateisystem zu. Speichern mit Strg+S.

Kompilieren mit Docker

Einziger Build-Befehl – Ubuntu 20.04 Container mit glibc 2.31.

docker run --rm \
  -v "$(pwd)":/work \
  -w /work ubuntu:20.04 bash -c \
  "apt-get update -qq && \
  apt-get install -y gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf make && \
  ln -s /usr/bin/arm-linux-gnueabihf-gcc /usr/bin/arm-none-linux-gnueabihf-gcc && \
  ln -s /usr/bin/arm-linux-gnueabihf-g++ /usr/bin/arm-none-linux-gnueabihf-g++ && \
  ln -s /usr/bin/arm-linux-gnueabihf-ld /usr/bin/arm-none-linux-gnueabihf-ld && \
  ln -s /usr/bin/arm-linux-gnueabihf-objcopy /usr/bin/arm-none-linux-gnueabihf-objcopy && \
  ln -s /usr/bin/arm-linux-gnueabihf-objdump /usr/bin/arm-none-linux-gnueabihf-objdump && \
  ln -s /usr/bin/arm-linux-gnueabihf-strip /usr/bin/arm-none-linux-gnueabihf-strip && \
  rm -rf bin/ && make"

Erfolgreich wenn am Ende bin/MiSTer erscheint. Warnungen sind ok – nur Errors stoppen den Build.

Bekannte Fixes im Repo: scaler.cpp – limit → 0 und errcode statt errno; input.cpp – .time-Felder entfernt.

Binary auf MiSTer deployen

MiSTer-IP: 192.168.178.80 · Passwort: 1

Upload + Neustart (ein Befehl)

scp bin/MiSTer root@192.168.178.80:/tmp/MiSTer && \
ssh root@192.168.178.80 "killall MiSTer; sleep 1; cp /tmp/MiSTer /media/fat/MiSTer && reboot"

Direkt nach /media/fat/MiSTer überschreiben schlägt fehl, weil der Prozess läuft. Daher erst nach /tmp/, dann killall + cp.

Immer zuerst ein Backup anlegen: ssh root@192.168.178.80 "cp /media/fat/MiSTer /media/fat/MiSTer.bak"

achievements.cpp – Unsere Änderungen

Implementierte Änderungen

Alle Modifikationen am Achievement-Popup gegenüber dem Original.

Header entfernt ✓ aktiv

„Achievement Unlocked!" Header-Zeile entfernt – mehr Platz für echten Inhalt.

Word-Wrap Hilfsfunktion ✓ aktiv

Neue Funktion word_wrap_split() bricht Text am letzten Leerzeichen um statt mitten im Wort.

Titel: bis zu 2 Zeilen ✓ aktiv

Lange Titel werden per Word-Wrap auf 2 Zeilen à 30 Zeichen aufgeteilt statt abgehackt.

Beschreibung: bis zu 3 Zeilen ✓ aktiv

Bei 1-zeiligem Titel stehen 3 Zeilen für die Beschreibung zur Verfügung, bei 2-zeiligem Titel 2 Zeilen.

Punkte-Anzeige am Zeilenende ✓ aktiv

Format: [Punkte +X] – wird platzsparend ans Ende der letzten Beschreibungszeile angehängt. Platz wird beim Word-Wrap automatisch reserviert.

Dynamische Popup-Dauer ✓ aktiv

Anzeigedauer basiert auf dem Punktewert des Achievements.

Punkte	Dauer	Beispiel
< 10 Punkte	5 Sek.	Einfache Achievements
10–24 Punkte	6 Sek.	Mittlere Achievements
25–49 Punkte	7 Sek.	Schwere Achievements
50+ Punkte	8 Sek.	Seltene Achievements

OSD-Popup Vorschau

Kurzer Titel + lange Beschreibung

TOP OF THE FLAGPOLE EARN A 5000 POINT BONUS BY TOUCHING THE TOP OF THE FLAGPOLE [Punkte +3]

Langer Titel + kurze Beschreibung

MASTER OF THE DRAGON REALM AND BEYOND COLLECT ALL COINS [Punkte +50]

Schnellreferenz

Täglicher Workflow auf einen Blick

Die 3 Befehle die du immer wieder brauchst.

1 · In den Projektordner wechseln

cd ~/Main_MiSTer

2 · Bauen (Docker)

docker run --rm -v "$(pwd)":/work -w /work ubuntu:20.04 bash -c "apt-get update -qq && apt-get install -y gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf make && ln -s /usr/bin/arm-linux-gnueabihf-gcc /usr/bin/arm-none-linux-gnueabihf-gcc && ln -s /usr/bin/arm-linux-gnueabihf-g++ /usr/bin/arm-none-linux-gnueabihf-g++ && ln -s /usr/bin/arm-linux-gnueabihf-ld /usr/bin/arm-none-linux-gnueabihf-ld && ln -s /usr/bin/arm-linux-gnueabihf-objcopy /usr/bin/arm-none-linux-gnueabihf-objcopy && ln -s /usr/bin/arm-linux-gnueabihf-objdump /usr/bin/arm-none-linux-gnueabihf-objdump && ln -s /usr/bin/arm-linux-gnueabihf-strip /usr/bin/arm-none-linux-gnueabihf-strip && rm -rf bin/ && make"

3 · Deployen + Neustart

scp bin/MiSTer root@192.168.178.80:/tmp/MiSTer && ssh root@192.168.178.80 "killall MiSTer; sleep 1; cp /tmp/MiSTer /media/fat/MiSTer && reboot"