Category

30 Mai 2014 Posted by: Comments: 1 In: Allgemein, C#, PHP, Programming, Tutorial, Unity3D

In diesem Abschnitt des Tutorials zeige ich dir, wie du nun die Informationen der API in dein Spiel bekommst.
Natürlich zuerst Unity öffnen und ein neues Script mit dem Namen Slim.cs anlegen.
Dieses Script sieht folgendermaßen aus:

HttpMethod – ist ein enum mit den vier wichtigen Http-Methoden!

ServerUrl – erklärt sich von selbst.

endHelloWorld – hier wird es interessanter. wie bereits am Anfang des Tutorials erwähnt verarbeitet die API url´s.
Die Basis url ist die ServerUrl. An diese wird ein Endpunkt angesetzt. wie im bereits erwähnten Beispiel:

http://localhost/tutorialgameapi/game1/v1/character/Hans oder http://localhost/tutorialgameapi/game1/v1/hello/Hans

Wobei „character/Hans“ oder auch „hello/Hans“ der Endpunkt wäre.

GetHelloWorld(string s) – Testmethode, ruft die „Hello, <name>“-GET-Methode in der API auf.

NewHttpWebRequest –  führt die Request aus!

Der Rest sollte relativ gut lesbar sein!

 

So kannst du das Script testen:

auch dieses mal wird Folgendes zurückgeliefert:

„Hello, Hans“

und

{ “guid”: “1″, “name”: “Hans”, “health”: “100″, “score”: “1000″ }

 

Bis zum nächsten Teil!

Daniel

20 Apr 2014 Posted by: Comments: 1 In: C#, PHP, Programming, Tutorial, Unity3D

In Teil 3 werde ich dir zeigen wie du die Daten vom Character „Hans“ aus der Datenbank abrufen kannst.

Bevor das passiert, nochmal eine kurze Zusammenzufassung darüber was im Projekt aktuell funktionieren sollte:

  • Die Programme sind installiert und laufen
  • Das PHP Projekt ist angelegt
  • Slim ist an seinem Platz im libs Verzeichnis
  • Der erste Test hat ein „Hello, NAME“ zurückgeliefert
  • Die Datenbank tutorialslim ist angelegt
  • Die Tabelle characters ist angelegt
  • die Spalten in der Tabelle wurden angelegt
  • Character „Hans“ ist als Datensatz in der Datenbank angelegt

Das ist soweit schon ganz gut.

Im nächsten Schritt werden wir die Daten aus der Datenbank ziehen und im Browser als json string anzeigen lassen.

Dazu erstellst du nun ein PHP Script namen AbstractController.php und speicherst es in das controller Verzeichnis.
Dieses Script sieht nun so aus:

 

 

Von diesem Script erben alle Controller-Scripts später. Die Idee dahinter ist schlichte Vererbung von Funktionalitäten innerhalb der Klassen. Ein Beispiel dafür ist das Verbinden zur Datenbank, die nun durch alle erbenden Klassen ganz simpel erfolgen kann. Das zeige ich dir direkt am nächsten Script, denn dieses wird alle Aufgaben rund um die Character-Daten erledigen.

 

Das StatusController-Script kommt, wie alle Controller-Scripts, ebenfalls in das controller-Verzeichnis.  Dieses Script sorgt dafür, dass du einen String in Json Format vom Server zurück erhälst, der den Fehler-Code und eine Nachricht enthält.

 

Erstelle jetzt ein neues Script mit dem Namen CharacterController.php und speichere dieses ebenfalls im controller Verzeichnis.

Das CharacterController-Script:

 

 

Nun muss noch die index.php modifiziert werden und sollte so aussehen:

Wenn du nun alles richtig gemacht hast und du

http://localhost/tutorialgameapi/game1/v1/character/Hans

in die Adresszeile deines Browsers eingibst, sollte folgendes zurückkommen:

{ „guid“: „1“, „name“: „Hans“, „health“: „100“, „score“: „1000“ }

 

Das Repo zum Projekt: https://bitbucket.org/AgentCodeMonkey/tutorialslimapi

Cheers!

Daniel

Weiter mit Teil 4

20 Apr 2014 Posted by: Comments: 1 In: C#, PHP, Programming, Tutorial, Unity3D

Weiter geht´s mit Teil 2 des Tutorials!

Bis hierher brauchtest du noch keinen Zugriff auf die Datenbank. Da dies aber geplant ist, musst du zuerst deine Datenbank startklar machen.

Dabei gäbe es zwei Varianten:
Variante 1: Erzeugen der Datenbank durch Code.
Variante 2: HeidiSQL.
An dieser Stelle tendiere ich selber eher zu HeidiSQL, weil es komfortabler ist.
Aber vielleicht ist es für dich auch interessant zu sehen wie man diese Dinge mit Hilfe von eigenem Code bewerkstelligen kann. Für die spätere Administration des Daten nutze ich dann aber definitiv HeidiSQL.
Bevor ich zur ersten Variante komme, erzeugst du ein Script, welches du definitiv brauchen wirst!

Dieses Script heißt config.php. und kommt in den include Ordner.

Wozu dieses Script dient sollte sich recht schnell erschließen.
Variante 1

Wenn du Variante 1 nutzen willst, dann erstellst du ein PHP Script und nennst es dbconnect.php.
Auch dieses Script kommt in den include Ordner.

Variante 2
In dieser Variante erstellst du die dbconnect.php nur mit den folgenden Zeilen, speicherst es im include Ordner und folgst der Anleitung im Video unterhalb des Scripts:

 

Öffne HeidiSQL und verbinde dich mit der Datenbank. Wer nicht mit HeidiSQL arbeiten möchte und lieber PHPMyAdmin oä. nutzt, muss sich aus dem Video die einzelnen Schritte ableiten.

Richte dort eine Datenbank namen tutorialslim ein, dazu folge dem Video.

In der nächsten Runde geht es darum die Daten aus der Datenbank zu holen.

Das Repo zum Projekt: https://bitbucket.org/AgentCodeMonkey/tutorialslimapi

Cheers

Daniel

Weiter zu Teil 3

 

20 Apr 2014 Posted by: Comments: 0 In: C#, PHP, Programming, Tutorial, Unity3D

Hallo und willkommen zu meiner Tutorialreihe zum Thema Unity3D und Slim Framework.

In diesem Tutorial möchte ich dir zeigen wie du recht schnell mit Hilfe des Slim Frameworks eine API oder einen Web Service für dein Unity3D Spiel erstellen kannst.
Serverseitig benutze ich dabei PHP, denn das Slim Framework ist in PHP geschrieben.
Der Client, bzw. das Spiel nutzt C# .
Bevor ich begonnen habe dieses Tutorial zu schreiben, habe ich mich selbst durch ein Tutorial gearbeitet und daraus bestimmte Dinge für mich abgeleitet. Dieses Tutorial hat zwar nichts mit Unity zu tun, beleuchtet aber die Funktionsweise von Slim.  Falls es dich interessiert – zu finden ist dieses Tutorial hier:
http://www.androidhive.info/2014/01/how-to-create-rest-api-for-android-app-using-php-slim-and-mysql-day-12-2/

 

Was soll erreicht werden?

  • Zugriff auf eine Datenbank durch eine Unity App.
  • Erstellen/Abrufen/Modifizieren/Löschen von Daten in einer Datenbank über einen Web Service.
  • Die API soll auch für andere Plattformen funktionieren. (Android/iOS Apps)
  • …soll Daten im json Format zurückliefern.
  • …soll leicht erweiterbar sein.

 

Was wird benötigt?

  • Unity 3D
  • MonoDevelop oder Visual Studio
  • NetBeans – eine starke IDE für PHP – Würde ich an dieser Stelle empfehlen! Ein anderer Editor tut es natürlich auch.
  • XAMPP, WAMP oä – Apache Server, Datenbank etc.
  • HeidiSQL – kostenloses Tool zur Datenbankmodellierung – alternativ: PHPMyAdmin
  • Ein wenig Umgang mit Unity3D, C# und/oder PHP oder zumindest irgendeiner anderen Scriptsprache

Meine Wahl fällt übrigens auf XAMPP, bei WAMP kann ich leider keine Hilfe anbieten, sollte es dort Probleme geben.

Außerdem gehe ich davon aus, dass zumindest Unity3D und MonoDevelop oder Visual Studio installiert sind.

 

Das Tutorial ist grob in zwei Bereiche geteilt:

Die Erstellung des Web Service/API in PHP und die Erstellung des Clients in C#.

Ich beginne mit dem Web Service und dessen Vorbereitung.

 

1. XAMPP

Wenn du XAMPP bereits installiert hast, kannst du diesen Schritt überspringen und startest den Apache und das MySQL Modul.

Installiere die aktuelle Version von XAMPP auf deiner Maschine.
https://www.apachefriends.org/de/index.html

  1. Starte das Control Panel.
  2. Im Control Panel:
  3. Starte das Apache Modul
  4. Starte das MySQL Modul
  5. Schließe das Panel, es läuft im Tray weiter.
  6. Öffene im Browser die URL http://localhost oder einfach nur localhost
  7. Folge den Anweisungen – Sicherheitscheck etc.
  8. wenn alles ok ist, …ist alles ok 😉

 

2. HeidiSQL

Wenn du HeidiSQL bereits installiert hast, kannst du diesen Schritt überspringen und öffnest HeidiSQL oder deine Alternative.

Installiere die aktuelle Version von HeidiSQL auf deiner Maschine.
http://www.heidisql.com/

  1. Starte HeidiSQL
  2. HostName/IP ist: localhost oder 127.0.0.1
  3. trage Nutzer und Passwort in die vorgesehenen Felder ein. Diese Daten hast du bereits beim Absichern von XAMPP erstellen müssen!
  4. HeidiSQL offen lassen 😉

 

3. NetBeans

Wenn du NetBeans bereits installiert hast oder nicht nutzen willst, kannst du diesen Schritt überspringen und öffnest NetBeans oder deine Alternative.

Installiere die aktuelle Version von NetBeans auf deiner Maschine.
https://netbeans.org/downloads/index.html

…natürlich die Version für HTML 5 und PHP…oder gleich für alles. Das ist Geschmackssache. Ich nutze nur die PHP Version – das reicht mir.

 

4. Der Web Service

So sollte es am Ende aussehen:
tutorial_slim

libs – alle third party libraries kommen hier hinein. z.B. Slim
include – Helferklassen kommen hier hinein (config.php)
index.php – ist für die API Requests zuständig
htaccess – regelt die API Struktur
model – beinhaltet bestimmte Klassen, die als blue print, bzw. Model dienen
controller – beinhaltet später alle Scripte, die die Zugriffe auf die Datenbank ausführen
v1 – v1 ist die gängige Abkürzung für “Version 1” – hier drinnen liegt die index.php, die später aufgerufen wird!

Lade das Slim Framework herunter.
http://www.slimframework.com/

Gehe zum Verzeichnis /xampp/htdocs/.
Im Verzeichnis htdocs legst du ein neues Verzeichnis an: tutorialgameapi.

innerhalb von tutorialgameapi legst du 3 neue Ordner an:

  • libs
  • game1
  • game2

In den Ordner libs entpackst du das herunterladenen Slim Framework.
Das muss so aussehen:

libs

  • Slim
  • test
  • index.php
  • …das ganze andere Zeug was dort drinne ist.

Warum du es dort ablegen solltest liegt auf der Hand: falls noch andere Web Services (game2) auf dem gleichen Server können diese alle auf den gleichen Code zugreifen und die Wartung ist ebenfalls einfacher.

 

In NetBeans legst du nun ein neues PHP Projekt an, vergibst einen Namen und nutzt das tutorialgameapi als Projektordner, klar. Nimm gleich die höchste PHP Version, aktuell 5.5.

Das Default Encoding steht auf UTF-8.
Das Projekt läuft natürlich als “Local Web Site” und die Projekt URL sieht so aus: http://localhost/tutorialgameapi/

Soweit so gut.

Im game1 Ordner legst du nun vier neue Verzeichnisse an

  • controller
  • include
  • model
  • v1

5. Die index.php

Im v1-Verzeichnis erstellst du nun eine index.php
Der Inhalt des Scripts ist natürlich so ziemlich identisch zum Code des „Hello, World“-Beispiels in den Slim Docs. 😉

Bevor du das Script testen kannst komme ich direkt zur Besonderheit dieser API´s:
die index.php taucht in der angesprochenen url nicht auf! Damit können besser lesbare URL´s erstellt werden und damit das klappt brauchst du diese kleine .htaccess-Datei.
Diese liegt direkt neben der index.php im v1-Verzeichnis und macht ein wenig “black magic” 😉

Das reicht erstmal. Zum Testen öffne http://localhost/tutorialgameapi/game1/v1/hello/Hans im Browser.

Damit wäre bereits der erste und grundlegende Schritt im PHP Projekt getan! Alles was jetzt kommt, baut auf diesem Prinzip auf.

Das Repo zum Projekt: https://bitbucket.org/AgentCodeMonkey/tutorialslimapi

 

Cheers!

Daniel

Weiter zu Teil 2

25 Mrz 2014 Posted by: Comments: 0 In: C#, PHP, Programming, Unity3D

Auf der Suche nach einer Möglichkeit eine REST API für eigene Spiele zu erstellen, bin ich über das Slim Framework gestolpert.
Das Framework ist in PHP geschrieben und ermöglich einen recht schnellen Start um solche API´s oder auch andere web applications aufzubauen. Es gibt natürlich einige dieser Frameworks. Slim schien mir jedoch genau das Richtige zu sein – es ist schnell, der Einstieg ist recht leicht und außerdem ist es recht gut dokumentiert.

Zuerst stellt sich natürlich die Frage was ist eine REST API, bzw. REST. Hierbei handelt es sich um eine Architektur, die es ermöglicht API´s mit gut lesbaren URL´s zu erstellen.
Sowas sieht zum Beispiel so aus: http://us.battle.net/api/wow/achievement/485

Dahinter steht meistens eine Datenbankabfrage, die dann wie im Beispiel einen Datensatz im Json Format zurückliefert. Dieser Datensatz kann dann in der eigenen App geparst und anschließend verwendet werden.

Letztlich übernimmt das Framework „nur“ das Routing für diese URL´s, denn eigentlich wird eine index.php angesprochen, diese erscheint wie im Beispiel aber nicht in der URL.

Im Wesentlichen werden dabei vier Befehle benötigt:

  • POST
  • PUT
  • GET
  • DELETE

Es gibt zwar noch mehr dieser Befehle, diese sind aber relativ selten im Gebrauch und werden im Moment vernachlässigt. Einige öffentliche API´s lassen auch nur GET Befehle zu, da die Entwickler natürlich die Daten in der Datenbank nur durch das Spielen des Spiel geändert (POST, PUT, DELETE) werden sollen und nicht durch z.B. Anfragen im Browser. Wie im Beispiel oben dienen diese Schnittstellen dann dazu um z.B. bestimmte Daten anderen web applications zu visualisieren.

 

Der Aufbau

Die gesammte API besteht aus der bereits erwähnten index.php und vielen „Controllern“ für die verschiedenen Datenbankabfragen.

Das Projekt kann dann z.B. so aussehen:

Slim_api

 

Die index.php ist (noch) relativ einfach:

Der erste Test der API kann also so erfolgen während Slim nun anhand der url routet:
http://www.yourdomain.com/api/v1/hello/Hans

Rückgabe wäre dann: „Hello, Hans„! Natürlich ohne Anführungszeichen.

 

Wie sieht es aber aus, wenn ich Daten aus einer Datenbank holen oder in irgendeiner Form modifizieren will?

Gehen wir davon aus, dass wir den Character „Hans“ neu anlegen und seine Daten modifizieren, zurückgeben oder löschen wollen.
Dazu benötigt die index.php diese vier Funktionen BEVOR : $app->run(); ausgeführt wird!

Bei drei dieser Funktionen taucht nun authentication auf.
Slim bietet die Möglichkeit eine Middlelayer einzubauen! Das ist großartig um z.B. durch eine Authentifizierung sicherzustellen, dass der Nutzer diese Aktionen auch ausführen darf.
Der GET-Befehl darf immer ausgeführt werden, da dieser ja nur Daten abruft, aber nicht modifiziert. Kann man machen, muss man natürlich nicht.
Also soweit so gut, damit die API nun die Daten die via PUT über den Body gesendet werden „herausfischen“ kann, benötigt es noch eine Funktion namens verifyRequiredParams.
Diese wird mit den „Feldern“ füttert, die sie filtern soll.
In diesem Fall ist es das Feld „data“. Dahinter verbirgt sich ein json String.
Beide Funktionen werden weiter unten im Text beleuchtet!

Um Nun die Daten von Hans abzurufen sieht die url nun so aus:
http://www.yourdomain.com/api/v1/character/Hans

oder auch mit der id von Hans (angenommen Hans ist bereits eingetragen und hat die id 999):

http://www.yourdomain.com/api/v1/character/999

Gibt man das in die Adresszeile des Browser ein, wird standartmäßig der GET-Befehl ausgeführt und man erhält die Daten von Hans, wenn er in der Datenbank vorhanden ist.

Nicht vergessen: dahinter liegt die index.php!
Die eigentliche URL sieht nämlich so aus:
http://www.yourdomain.com/api/v1/index.php

Direkt neben der index.php liegt eine .htaccess-Datei, die dafür sorgt, dass index.php aus der URL entfernt wird. black magic! 😉

Die .htaccess-Datei sieht so aus:

Um nun die Daten vom Character „Hans“ zu bekommen, braucht es noch den „CharacterController“ und der sieht so aus:

Wie man sieht gibt es eine Klasse namens AbstractController, diese übernimmt den Aufbau der Datenbankverbindung:

und greift dabei auf das connect-Script zu:

die config.php sieht dann so aus:

Die verifyRequiredParams Funktion und die sieht so aus:

Da ich das Feld ‚data‘ übergebe, wird genau danach gesucht. $app->request()->getBody() holt den Body, danach wird geparst und ein paar Checks für das Errorhandling gemacht, für den Fall, dass das Feld ‚data‘ nicht vorhanden ist. Wenn irgendwas mit den Feldern nicht stimmt (nicht vorhanden oder falsch benannt), wird Slim gestoppt: app->stop();

Und was macht nun ‚authentication‘ ? Ein sehr tolles Feature von Slim ist die Möglichkeit Middlelayer einzufügen.
Die Funktion ‚authentication‘ soll überprüfen, ob denn überhaupt Daten verarbeitet werden dürfen, indem das Vorhanden sein von Usernamen und Passwort im Header überprüft wird.

Man sollte sich hier sowieso mit einem „ApiKey“ und Ähnlichem absichern und sowas im Vorfeld prüfen oder besser gleich https nutzen!
Für das Beispiel verzichte ich aber erstmal darauf.

Nun hat man so ziemlich alles zusammen was man benötigt und kann neue Controller erstellen (siehe Abb. oben), diese Controller erben natürlich vom AbstractController und werden automatisch in die index.php geladen.

Von dort aus muss, wie im Beispiel, nur eine Instanz erzeugt werden. Slim übernimmt im Hintergrund die „Magie“ beim Routen, während die Datenbankabfragen vom jeweiligen Controller erledigt wird.

So lässt es sich echt schnell entwicklen! 🙂

 

der Unity3D, bzw. C#-Teil

Jetzt muss das Ganze noch mit Unity verbunden werden. Hierfür nehme ich nicht die Unity-eigene WWW-Klasse. Ich persönlich finde, dass sich Coroutinen für solche Angelegenheiten einfach nur bedingt anbieten und sich dazu unter C# nicht als strings zurückgeben lassen. In diesem Fall heißt der unser Verbündeter „HttpWebRequest“. Der nächste Nachteil der Coroutinen von Unity besteht aus dem Fakt, dass sie nur mit POST und GET arbeiten. Ich benötige aber auch DELETE und PUT. Diese kann man in der „HttpWebRequest.methode“ mitschleifen! Um hier den ein oder anderen Workaround zu vermeiden ist in diesem Fall die „HttpWebRequest“-Klasse der klare Sieger! Auch die WebClient-Klasse tut sich hier schwer. Einziger Nachteil ist bis dato, dass ich System.IO nutzen muss. Dies bedeutet, dass der WebPlayer (vorerst) wegfällt, da dieser aus Sicherheitsgründen in einer Sandbox läuft. Das ist auch gut so. 😉

Holen wir die Daten in das Spiel:

 

 

 

Abschließend muss ich sagen, dass ich nicht einen einzigen Blick in die Slim.php werfen musste – die Doku und ein paar kleine Tests haben völlig ausgereicht um die API auf Slim aufzusetzen.

So soll es sein – funktioniert einfach out of the box! Unity3D, bzw. C# verhielt sich anfangs ein wenig sperriger. Hier war ein wenig die „trial and error“-Methode gefragt.

 

Cheers!

Daniel