[BlitzDelta] #3: Eigene Tutorials zum SampleBrowser hinzufügen

Hallo Leute,

willkommen zum dritten Teil von BlitzDelta. Auch heute habe ich wieder etwas für euch, was sich leicht und schnell umsetzen lässt.

Im letzten Teil hatten wir gelernt, wie sich mit Hilfe der Klassen Rect und Circle schnell und einfach BoundingVolumes visualisieren lassen können, die einem dann bei der Suche nach Fehlern helfen sollen, falls es mal mit der Kollision nicht so klappen will oder man andersweitig Rechtecke oder Kreise schnell und einfach mal eben anzeigen lassen will.

In diesem Teil lernen wir, wie wir eigene Inhalte zum SampleBrowser hinzufügen können. Der SampleBrowser ist das Tool, das standardmäßig schon bei Delta dabei ist und auch schon von mir in einem Tutorial aus meiner Hauptserie erläutert wurde.

Und nun wünsche ich euch viel Spaß beim folgenden Artikel.

 

Das Problem

Für alle, die dieses Tutorial lesen werden, wird es sicherlich nicht zutreffen (zumindest noch nicht), was ich gleich als Problem äußern werde, daher komme ich um eine Annahme nicht herum.

Folgende Problemstellung haben wir: Nehmen wir an, ihr habt ein tolles Stück Software erstellt, aus Gründen der Verträglichkeit mit diesem Tutorial ist es aber kein Spiel, denn sonst wäre dieses Tutorial ja sinnlos (wieso sollte man zu einem Spiel ja immerhin was zum SampleBrowser adden wollen? Es wäre zwar möglich, aber käme auf das Spiel an).
Nehmen wir an, es handelt sich um irgendeine tolle Library, z.B. eine, die Level darstellen kann oder so. Das Projekt ist ja insofern egal, solange man dazu gut Tutorials erstellen kann. Nun habt ihr auch soweit eine Dokumentation dabei, wollt aber auch ein paar Tutorials zur Verfügung stellen, damit die Nutzer eures Werkes sich auch zurechtfinden.

Dann kommt euch die Idee, das alles für Delta freizugeben zur Aufnahme ins Repository, so dass jeder, der sich Delta dann per Nightly runterlädt, auch euer Werk bekommt. In welcher Form euer Werk eingebunden wird, also ob OpenSource oder evtl. nur die Binaries oder so, das ist nicht weiter relevant.
Jedenfalls wollt ihr, dass die Tutorials, die ihr erstellt habt, auch im SampleBrowser auftauchen. Nur wie soll man das bewerkstelligen, schließlich ist ja nicht bekannt, wie genau das geht.

Die Analyse

Was wir schon eben herausgefunden haben ist, dass wir unsere Tutorials irgendwie in den SampleBrowser eingliedern müssen. Wie das geht, ist uns zurzeit nicht bekannt. Startet man den SampleBrowser, so präsentiert sich einem ja in etwa folgendes Bild:

Scrollt man die Liste durch, so sieht man, dass neben den Sample Games auch Tutorials sowie Tests in der Liste auftauchen. All diese Dinge werden vom SampleBrowser erkannt und hinzugefügt. Es muss also definitiv einen Weg geben, da auch unsere Tutorials einzugliedern. Es gibt auch einen, wie dieser funktioniert, werden wir nun erfahren.

Die Lösung

Im Grunde ist die Lösung ziemlich simpel, sobald man die Mechanik hinter allem etwas verstanden hat. Hier mal eine Methode aus der Datei Tutorials.cs, die dem Ordner Scenes/Tests in eurem Deltaverzeichnis entstammt.

Fällt euch was auf? Ich meine dabei nicht das [Test, Ignore(„Visual“)], denn diese Dinge entstammen der Tatsache, dass damit gewisse Unit Tests durchgeführt werden können und für uns ist das auch nicht wirklich relevant.
Was ich meine, ist der <summary> Tag. Betrachten wir diesen doch nochmals genauer:

Normalerweise werden <summary> Tags dafür genutzt, die XML-Dokumentation generieren zu lassen und weisen daher auch einen anderen Inhalt auf. Hier wurden sie allerdings etwas „zweckentfremdet“ und für eigene Zwecke genutzt.
Wie man sehen kann, weißt der Tag gewisse Merkmale auf und in der Tat ist er dafür da, dem SampleBrowser Instruktionen zu geben. Wer genau hinsieht, erkennt Sachen wie „Tutorial:“ oder „Diffuculty:“. Hier kurz die Auflistung der Instruktionen und was sie bewirken:

  • Tutorial:Dies ist der Name, des Tutorials, der später auch im SampleBrowser auftaucht.
  • Difficulty: Sollte normalerweise selbsterklärend sein, da Difficulty ja einfach nur englisch für Schwierigkeit ist.
  • Description: Ebenso selbsterklärend im Normalfall, hier gebt ihr einfach eine kurze Beschreibung eures Tutorials an
  • Image: Hier könnt ihr, wie in dem o.g. Beispiel, eine URL angeben zu einem Bild, das dann im SampleBrowser bei eurem Tutorial erscheint.

Wer denkt, dass dies nun alles war, den muss ich leider enttäuschen. In der derzeitigen Version des SampleBrowsers ist noch etwas mehr Arbeit notwendig. Es gibt noch ein paar Voraussetzungen mehr.

Hier sind die weiteren Voraussetzungen, um das Tutorial erfolgreich einzugliedern:

  • Das Projekt muss im Deltaverzeichnis liegen, also da, wo ihr Delta installiert habt.
  • Es muss sich um ein komplettes Projekt handeln, d.h es muss eine .csproj vorhanden sein, da nach dieser gesucht wird.
  • Der Name der .csproj setzt sich wie folgt zusammen:Delta.X.Y. X und Y stehen für Platzhalter uns benennen sich nach dem Pfad, der zur .csproj führt. Nehmen wir an, euer Projekt heißt SampleBrowserTest und liegt im Pfad $DeltaRoot/Engine/SampleBrowserTest, dann muss die .csproj folglich Delta.Engine.SampleBrowserTest heißen.
  • In dem Projekt muss eine Datei enthalten sein, deren Name Tutorials.cs lautet, anders wird es nicht erkannt.

Dies sind eigentlich alle Voraussetzungen, die man erfüllen muss. Wie schon eben gesagt, gilt dies für die aktuelle Version des SampleBrowsers. Mir liegt eine Aussage eines Entwicklers von Delta vor, in der mir gesagt wurde, dass die aktuelle Version des SampleBrowsers schon über ein Jahr alt ist. Daher schließe ich es nicht aus, dass sich da in näherer Zukunft noch was ändern wird. Sollte es Änderungen geben, so werde ich entweder dieses Tutorial anpassen oder in einem neuen Artikel darauf hinweisen, dies kommt aber ganz darauf an, wann sich was ändert und in welchem Umfang.

 

Das war es dann eigentlich auch schon mit diesem Teil von BlitzDelta. Ich hoffe, es hat euch gefallen und ihr könnt eure eigenen Inhalte zum SampleBrowser hinzufügen. Sollte etwas unklar sein oder nicht funktionieren, so zögert nicht, nachzufragen.

Ansonsten wünsche ich euch viel Spaß beim Ausprobieren. Bis zum nächsten Teil.

 

~internetfreak

 

P.S: Wie auch beim letzten Teil hier auch nochmals als Anmerkung: Solltet ihr eigene Ideen/Wünsche zu einem Thema haben, welches gut passt, so könnt ihr mir dies gerne mitteilen und ich schaue, was ich machen kann. Es muss dabei nicht unbedingt in die Kategorie BlitzDelta fallen, ich nehme auch andere Vorschläge gerne an.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.