Wii-Image-Patcher (Tutorial)

Aus Wiiki
Wechseln zu: Navigation, Suche

Sobald die Benutzer Informationen über eine Konsole habe und wissen, wie man modifizierte Spiele nutzen kann, werden eigene Varianten der Spiele erstellt. Zum Verteilen der Spiele benötigt man dann einen Patcher, da man aus rechtlichen Gründen nicht das komplette modifizierte Spiel veröffentlichen darf.

Diese Artikel beschreibt nun, wie man einen Patcher für Wii-Spiele erstellt.


Einführung

Wii-Images

Ein Patcher muss für den Endkunden relativ einfach zu bedienen sein. Daher fangen wir mal mit eine Anleitung für Endkunden an, die wir dann versuchen, schrittweise umzusetzen:

  1. Lade den Patcher herunter und entpacke ihn in ein neues und leeres Arbeitsverzeichnis.
  2. Kopiere eine Sicherheitskopie des Originalspieles in das Arbeitsverzeichnis.
  3. Starte das Programm / die Batchdatei / das Script CREATE-IMAGE. Nach einer Wartezeit ist das neue Image fertig.
  4. Kontrolliere die Ausgabe auf Fehlermeldungen.
  5. Nimm das neue Image und teste es.
  6. Lösche das Arbeitsverzeichnis.

Um Punkt 3. muss sich der Erstellers des Patchers kümmern. Der Patcher muss dabei die folgenden Schritte ausführen:

  1. Setup
  2. Original-Image suchen und entpacken.
  3. Das entpackte Image untersuchen:
    • Image-Format und ID des Originales herausfinden
    • Verschiedene Versionen des Spieles durch Kontrolle von Dateien ermitteln.
  4. Optionen beim Benutzer anfragen. Die Optionen oder Voreinstellung hierfür können auch über eine Kommandozeile übergeben werden. Möglich udn sinnvoll sind:
    • Image-Format
    • Datei splitten
    • ID vorgeben
    • Eigenes Savegame
  5. Den Patch ausführen. Hierzu werden Dateien in der Verzeichnisstruktur des entpackten Images gelöscht, verändert und/oder hinzugefügt.
  6. Ein neues Image erstellen. Dabei die Vorgaben beachten.
  7. Bei Erfolg: Arbeitsverzeichnis aufräumen

Einige Schritte sind optional und eingie Optionen können auch fest vorgegeben werden. Am besten eignet sich ein Script bzw unter Windows eine Batchdatei, um den Patcher zu realisieren. Beim Entpacken und Erstellen des Images muss man Wiimms ISO Tools verwenden, da es keine anderen Programme gibt, die dieses leisten.

Vorbereitung

Verzeichnisstruktur

In der ersten Ebene, dem Arbeitsverzeichnis, sollten sich möglichst wenig Dateien befinden. Nur Dateien, die der Nutzer sehen soll, befinden sich hier. In dem hiesigen sind dieses:

  • Datei create-image.bat, welches das neue Image erstellt.
  • Datei LIESMICH.txt mit Informationen für den Benutzer.
  • Datei LIZENZ.txt mit Lizenz-Infos.
  • Verzeichnis bin/, welches die benötigten Programme enthält.
  • Verzeichnis data/, welches alle weiteren Dateien und evtl. weitere Unterverzeichnisse enthält.

Benötigte Software

Für dieses Beispiel wird nur das Tool wit aus Wiimms ISO Tools sowie die Scripte und Batchdateien benötigt. Das gesamte Paket steht als ZIP-Datei zum Download bereit:

  • example.zip mit allen Dateien inklusive wit v2.22b für Linux, Mac und Windows.

Windows Beispiel

Fangen wir mit einer Beispiel-Batch-Datei[1] an. Wegen der Internationalität ist die interne Dokumentationssprache englisch. Jedem einzelnen Abschnitt der Batch-Datei ist ein eigenes Kapitel gewidmet.

Setup

:: Define the binary path
set BIN=bin\windows

:: Define the data path
set DATADIR=data

:: Define the patch directory
set PATCHDIR=patch.tmp

:: Define an image comma separated list with accepted source ids.
:: A point means; any character
set SRC_ID=RTY.01,SMN.01

:: Define the output ID. A point means: Use original character
set DEST_ID=.....2

:: Define an ID4 for a new savegame
set SAVEGAME_ID=K...

:: Define a new game title
set TITLE=Wiimms Example

:: define a filename for the new image.
:: '$X' means: let wit select a name in the format "title [id].ext"
set DESTFILE=$X

Zuerst werden eineige Voreinstellungen vorgenommen. Diese werden in Form von Umgebungsvariablen gespeichert. Die Batchdateien greifen dann hierauf zurück:

BIN
In diesem Verzeichnis liegen die Programme, die für das Patchen benötigt werden. Am besten ist es, weder Leerzeichen noch Sonderzeichen für diesen Pfad zu verwenden.
DATADIR
In diesem Verzeichnis befinden sich die Daten, die für das Patchen benötigt werden. Am besten ist es, weder Leerzeichen noch Sonderzeichen für diesen Pfad zu verwenden.
PATCHDIR
In dieses Verzeichnis wird das Image entpackt, um dann die Veränderugnen vorzunehmen. Das Verzeichnis wird koplett zu beginn und, bei Erfolg, am Ende gelöscht. Daher auch die Endung ".tmp" für temporär. Am besten ist es, weder Leerzeichen noch Sonderzeichen für diesen Pfad zu verwenden.
SRC_ID
Eine Komma-separierte Liste mit ID6-Werten. Ein Punkt ('.') ist ein Platzhalter für beliebige Zeichen[2]. Als Quelle für den pacth sind nur Images erlaubt, die zu einer ID6 der Lsite passen.
DEST_ID
Eine ID6, die das neue Image erhalten soll. Ein Punkt ('.') bedeutet, dass hier das Zeichen vom Original-Image verwendet werden soll.
SAVEGAME_ID
Falls ein eigenes Savegame benutzt werden soll, dann muss die ID$ von TICKET und TMD geändert werden. Ein Punkt ('.') bedeutet, dass hier das Zeichen von DEST_ID verwendet werden soll. Für eigene Savegames wird üblicherweise das erste Zeichen auf 'K' wie Klone gesetzt.
TITLE
Name des Spieles, die in das Image eingetragen werden soll. Es sind maximal 63 Zeichen erlaubt, weitere Zeichen werden ignoriert. Außerdem sollten nur 7-Bit-ASCII-Zeichen[3], also keine Umlaute, verwendet werden.
DESTFILE
Dateiname des neuen Images. Die Vorgabe $X[4] bedeutet, dass der Dateiname aus dem Titel, der ID und dem Image-Typ im Format "title [id].ext" erstellt wird.

Dateien extrahieren

:: remove old patch directory if it exists for some reason
if exist "%PATCHDIR%" rmdir "%PATCHDIR%" /s /q

:: extract the image
"%BIN%\wit" extract . --ignore-fst -1 --include "%SRC_ID%" --dest "%PATCHDIR%" --psel data -vv
if errorlevel 1 goto error

:: get image info
call %PATCHDIR%\setup.bat

Das Extrahieren des Images besteht aus den folgenden Schritten:

  1. Zuerst wird das Patch-Verzeichnis komplett gelöscht.
  2. Dann wird das Image gesucht und entpackt. Die Kommandozeile Schritt für Schritt:
     %BIN%\wit[5]
    Aufruf des Programmes wit, es wird im BIN-Verzeichnis gesucht.
    extract[6]
    Das Kommando für das Extrahieren eines Images.
    . (Punkt)
    Als Quelle wird das aktuelle Verzeichnis angegeben. Dort werden dann alle Dateien untersucht, um ein passendes Original-Image zu finden.
    --ignore-fst[7]
    Ignoriere evtl. vorhandenen entpackte Images.
    -1[8]
    Es wird maximal ein Image bearbeitet (hier: entpackt).
    --include %SRC_ID%[9]
    Es werden nur Images gemäß der ID-Liste 'SRC_ID' akzeptiert.
    --dest %PATCHDIR%[10]
    Das entpackte Image wird unter PATCHDIR abgelegt.
    --psel data[11]
    Es wird nur die Datenpartition entpackt. Evtl. vorhandene andere Partitionen, wie z.B. die Update-Partition, werden ignoriert.
    -vv[12]
    Den Fortschritt beim Entpacken anzeigen.
  3. Bei einem Fehler wird die Ausführung mit einer Fehlerbehandlung fortgesetzt.
  4. Beim Entpacken wurde eine Batch-Datei erstellt, die Informationen über das gerade entpackte Image bereitstellt. Diese Informationen werden durch den CALL-Befehl abgerufen.

Konfigurations-Dialog

???

Hier kann sich der Patch-Ersteller austoben und z.B. über Dialoge weitere Parameter abfragen oder Vorgaben ändern.

Man kann den Konfigurations-Dialog auch vor das Extrahieren stellen. Der große Vorteil ist, dass der Benutzer nicht erst auf das erfolgreiche Entpacken warten muss und dass man Anweisungen zum Entpacken geben kann. Demgegenüber steht der Nachteil, dass der Konfigurations-Dialog nicht auf das entpackte Image reagieren kann.

Eine Zweiteilung des Konfigurations-Dialog ist natürlich auch möglich: Vor dem extrahieren werden alle Dinge abgefragt, die unabhängig vom Extrahierten Image sind. Im einem 2. Teil nach dem Extrahieren werden dann Fragen nachgeholt, die sich nun ergeben haben.

Patch ausführen

call "%PATCHDIR%\setup.bat"
if errorlevel 1 goto error

Hier wird im Daten-Verzeichnis die Batch-Datei patch.bat aufgerufen. Diese Batch-Datei muss durch den Patch-Ersteller erstellt werden. Minimum ist das Kopieren der neue Dateien aus dem Daten-Verzeichnis DATADIR ind das Patch-Verzeichnis PATCHDIR. Eigene Programme werden mit dem Prefix %BIN% aufgerufen.

Bei einem Fehler wird die Ausführung mit einer Fehlerbehandlung fortgesetzt.

Neues Image erstellen

:: Original savegame verwenden
::set ID=--id=%DEST_ID%

:: Eigenes savegame verwenden
set ID=--id=%DEST_ID% --tt-id=%SAVEGAME_ID%

"%BIN%\wit" copy -ovvE$ "%PATCHDIR%" "%DESTFILE%" %ID% -T0 --name "%TITLE%"
if errorlevel 1 goto error

Zuerst wird die neue ID festgelegt. In der ersten und auskommentierten Variante teilet sich die Spielvariante mir dem Original-Spiel ein Savegame. Damit sind frei gespielte Dinge des Originals auch in der neuen Variante verfügbar.

In der zweiten (aktivierten) Variante wird ein eigenes Savegame verwendet. Dazu erhalten TICKET und TMD eine eigene modifizierte ID. Man könnte diese Auswahl auch durch eine Abfrage beim Benutzer entscheiden lassen.

Zum Schluss wird dann das neue Image erstellt. Dazu wird einfach das Verzeichnis in ein Image kopiert. Das Zusammenstellen des Images erledigt wit dann transparent. Bei einem Fehler wird die Ausführung mit einer Fehlerbehandlung fortgesetzt. Die Kommandozeile Schritt für Schritt:

 %BIN%\wit[5]
Aufruf des Programmes wit, es wird im BIN-Verzeichnis gesucht.
copy[13]
Kommando für das Kopieren eines Images.
-o (Kurzform von --overwrite[14])
Ein bestehendes Image wird überschrieben.
-vv[12]
Den Fortschritt beim Kopieren anzeigen.
-E$ (Kurzform von --esc $[15])
Das Dollarzeichen als Escape-Zeichen für Platzhalter einstellen. Dieses ist für Windows wichtig, da das unter Unix verwendete %-Zeichen unter Windows eine Sonderbedeutung hat.
 %PATCHDIR%
Die Quelle beim Kopieren. Erkennt wit ein Verzeichnis mit einem zuvor entpackten Image, dann wird automatisch und transparent ein Image erzeugt, welches dann kopiert wird.
 %DESTFILE%
Der Dateiname des neuen Images. Er wird durch die Variable DESTFILE festgelegt.
 %ID%
Die weiter oben festgelegten neuen IDs des neuen Images verwenden.
--id=%DEST_ID%[16]
Festlegen der Basis-ID des neuen Images.
--tt-id=%SAVEGAME_ID%[17]
Festlegen der TICKET- und der TMD-ID. Beide zusammen legen den Wii-internen Dateinamen der Savegame-Datei fest.
-T0 (Kurzform von --titles 0[18])
Durch den Parameter 0 wird die Titel-Datenbank deaktiviert.
--name "%TITLE%"[19]
Festlegen des neuen Namens der Images. Bis zu 63 ASCII-Zeichen werden verwendet.

Aufräumen

rmdir "%PATCHDIR%" /s /q
goto exit

Da alles gut verlaufen ist, kann nun das Patch-Verzeichnis wieder gelöscht werden.

Fehlerbehandlung

:error
echo.
echo ----------------------------
echo    IMAGE CREATION FAILED!
echo     See messages above!
echo ----------------------------
echo.

Dieser Teil wird nur aufgerufen, wenn beim Entpacken, Patchen oder Erzeugen des neuen Images ein Fehler aufgetreten ist. Der Text fordert den Nutzer auf, sich die Fehlermeldungen anzusehen. Die sind natürlich wichtig, wenn Dritte in Foren helfen sollen.

Bei einem Fehler wird das Patch-Verzeichnis nicht gelöscht, da es wichtig für Analyse-Zwecke sein kann.

Abschluss

:exit
pause

Diese paar Zeilen bilden den Abschluss der Batch-Datei. Nach dem Label für die GOTO-Befehle folgt eine PAUSE-Anweisung. Die Sorgt dafür, dass der Ausgabebildschirm nicht automatisch entfernt wird und der Nutzer so die Möglichkeit hat, die Ausgabe zu kontrollieren.

Unix Beispiel

Es gibt auch ein Script[20] für Linux, Max und andere Unix-Betriebssystem, welches in der Scriptsprache bash[21] geschrieben ist. Im Prinzip hat es einen identischen Aufbau wie die Windows-Batch-Datei. Daher wird hier nur auf wesentliche Unterschiede eingegangen.

Setup

Fangen wir mit dem Shebang[22] an:

#!/usr/bin/env bash

Es sieht etwas ungewöhnlich aus. Es gibt Linux-Systeme, bei denen liegt bash unter /bin/bash, bei anderen unter /usr/bin/bash, und ganz ganz selten unter /usr/local/bin/bash. Dieses Shebang ruft das Programm env auf, dass dann das bash-Programm aus dem Pfad heraussucht und startet.

# Define the binary path
BIN=./bin/linux
uname -s | grep -iq darwin && BIN=./bin/mac
chmod a+x "$BIN"/*

Hier wird zuerst das Linux-Verzeichnis eingestellt. Das beiliegende wit ist ein i386/32-Bit Version, die ohne weiteres auch auch x86_64 läuft. Dann wird das System mittels uname untersucht. Falls ein Mac (System Darwin) entdeckt wird, wird das Programmverzeichnis umgeschaltet.

 # define a filename for the new image.
 # '%X' means: let wit select a name in the format "title [id].ext"
 DESTFILE="%X"
Unter Windows verwenden wir das Dollar-Zeichen als Platzhalter, da Windows das %-Zeichen zum ersetzen durch Variablen verwendet. Bei Uix ist es genau umgekehrt, da hier das $-Zeichen zum Ersetzen verwendet wird.

Funktion ERROREXIT

function ERROREXIT()
{
    cat <<- __EOT__

	----------------------------
	   IMAGE CREATION FAILED!
	    See messages above!
	----------------------------

	__EOT__
    exit 1
}

Für die Fehlerbehandlung definieren wir einfach eine Funktion. Zur Textausgabe verwenden wir das relativ unbekannte Here-Dokument, welches von vielen Programmier-Sprachen unterstützt wird. Aufgerufen wird es durch bedingte Ausführung:

irgend_ein_kommando_mit_fehlerstatus || ERROREXIT

Extract

# remove old patch directory if it exists for some reason
rm -rf "$PATCHDIR"

# extract the image
$BIN/wit extract . --ignore-fst -1 --include "$SRC_ID" \
	--dest "$PATCHDIR" --psel data -vv || ERROREXIT

# get image info
. "$PATCHDIR/setup.sh"

Das Extrahieren des Images unterscheidet sich nur geringfügig von der Windows-Version. Auffällig ist die Schreibweise des Fehlerabbruches und der Aufruf von $PATCHDIR/setup.sh als Quelltext-Include.

Web-Links

Referenzen

  1. Batch-Datei create-image.bat
  2. Wiimms ISO Tools: Selection and wildcards
  3. Wikipedia: ASCII-Zeichensatz
  4. Wiimms ISO Tools: Escape sequences
  5. 5,0 5,1 Wiimms ISO Tools: Tool wit
  6. Wiimms ISO Tools: Kommando EXTRACT
  7. Wiimms ISO Tools: Option --ignore-fst
  8. Wiimms ISO Tools: Option --one-job (-1)
  9. Wiimms ISO Tools: Option --include (-n)
  10. Wiimms ISO Tools: Option --dest (-d)
  11. Wiimms ISO Tools: Option --psel
  12. 12,0 12,1 Wiimms ISO Tools: Option --verbose (-v)
  13. Wiimms ISO Tools: Kommando COPY
  14. Wiimms ISO Tools: Option --overwrite (-o)
  15. Wiimms ISO Tools: Option --esc (-E)
  16. Wiimms ISO Tools: Option --id
  17. Wiimms ISO Tools: Option --tt-id
  18. Wiimms ISO Tools: Option --titles (-T)
  19. Wiimms ISO Tools: Option --name
  20. Batch-Datei create-image.sh
  21. Wikipedia: Scriptsprache bash
  22. Wikipedia: Shebang