Dieses Repository enthält das Unity Projekt des Projekts CoLaB, der Universität Wuppertal.
Die Anwendung CoLaB gliedert sich in die folgenden Komponenten auf:
Für das Netzwerk wird die kostenlose Version des Plugins Mirror Networking verwendet. Zur Entwicklung wurde die Version 86.13.0 verwendet. Die Implementierung des Plugins im Projekt ist in den Scripts unter _Colab > Scripts > Network zu finden. Zur Konfiguration des Mirror Netzwerks siehe Konfiguration des Netzwerks.
Um eine objektübergreifende Kommunikation innerhalb der Anwendung zu ermöglich, wurde ein Event System implementiert. Dieses ermöglicht das Versenden von Events zu verschiedenen Zeitpunkten sowie das sogenannte Abonnieren bzw. "Subscriben" dieser Events. Damit lassen sich Funktionen ausführen, sobald ein ein Event eines bestimmten Typs versendet wird und empfangen wurde. Die Implementierung des Event Systems im Projekt ist in den Scripts unter _Colab > Scripts > EventHub zu finden.
Damit sich über das Netzwerk mittels Mikrofon miteinander verständigt werden kann, wurde das Plugin UniVoice verwendet. Dieses stellt eine Sammlung von Interfaces zur Verfügung, welche die Unity Audio Komponenten erweitern. Die Implementierung des Plugins im Projekt ist in den Scripts unter _Colab > Scripts > Audio zu finden.
Die Erstellung der Charaktere wurde über die Platform Ready Player Me realisiert. Hierbei handelt es sich um eine Plattform, welche
es ermöglicht einen personalisierten Avatar zu erstellen. Die Erstellung des Avatars erfolgt über eine Webanwendung, welche über eine REST API angesprochen werden kann.
Die Implementierung der REST API sowie der Darstellung der Charaktere im Projekt ist in den Scripts unter _Colab > Scripts > AvatarCreation zu finden.
Damit ReadyPlayerMe in der Anwendung verwendet werden kann, muss eine Subdomain und eine App ID in den Unity Editor Einstellungen unter ReadyPlayerMe > Settings eingetragen werden.
Siehe dazu auch ReadyPlayerMe Unity Itegration Guide.
Die Steuerung der Benutzeroberfläche geschieht in der Anwendung über den UIPanelManager. Dieser verwaltet die verschiedenen Panele der Anwendung. Sämtliche UI Komponenten sind in der Unity Scene unter UI zu finden. Die Implementierung des UIPanelManagers sowie aller zugrunde liegenden UI Komponenten ist in den Scripts unter _Colab > Scripts > UI zu finden.
Ähnlich zu dem AssetLibraryObjekt besteht das Whiteboard aus einem Überobjekt und mehreren Unterobjekten.
Auf dem Überobjekt befindet sich ein Box Collider, welcher dafür sorgt, dass der Spieler mit dem Objekt kollidieren kann.
Desweiteren befinden sich auf dem Überobjekt die Komponente Whiteboard Objekt welche das Herzstück des Whiteboards ist und die nachfolgenden
Komponenten miteinander verbindet.
Um Video, Bild, Audio oder Dokumente auf dem Whiteboard anzeigen zu können, muss dem Überobjekt die jeweilige Komponente hinzugefügt werden.
- Whiteboard Video Renderer
- Whiteboard Image Renderer
- Whiteboard Audio Renderer
Damit das Whiteboard die richtige URL anspricht, muss dem Whiteboard in der Whiteboard Objekt Komponente unter Whiteboard Object Settings noch eine Media ID zugewiesen werden. Diese Zuweisung muss in der Szene und nicht der Prefab Preview geschehen. Die ID steht hierbei für die ID des jeweiligen Whiteboards. Sollten sich mehrere Whiteboards in einer Szene befinden muss darauf geachtet werden, das jedes Whiteboard eine eindeutige ID besitzt z.B 1,2,3 usw. Andernfalls kann es dazuführen, dass mehrere Whiteboards die gleiche URL ansprechen und somit Medien auf mehreren Whiteboards gleichzeitig angezeigt werden.
Das WhiteboardObject funktioniert in der Szene zusammen mit dem Whiteboard Manager, welcher sämtliche Whiteboards in der Szene verwaltet und dem WhiteboardUIPanel welches die Benutzeroberfläche des Whiteboards darstellt. Wenn der Benutzer auf ein Whiteboard klickt, wird das Unterobjekt BrowserWindowParent zum Unterobjekt des WhiteboardUIPanels. Dadurch wird der Canvas aus dem WorldSpace in den 2D ScreenSpace umgewandelt. Wenn das WhiteboardUIPanel geschlossen wird, wird das Unterobjekt wieder zum Unterobjekt des WhiteboardObjects wodurch der Canvas wieder in den WorldSpace umgewandelt wird und wieder auf dem 3D Objekt des Whiteboards zu sehen ist.
Da das kostenlose Plugin Unity Web Browser nur unter Windows unterstüzt wird, können PDFS ebenfalls nur auf Windows angezeigt werden. Eine kostenpflichtige Alternative stellt das im Unity Asset Store erhältliche Plugin Embedded Browser dar. Falls dieses zu einem späteren Zeitpunkt integriert werden soll, kann dies folgendermaßen geschehen:
- Das Plugin muss im Unity Asset Store erworben und importiert werden.
- Anschließend muss im Script BrowserController sowie WhiteboardUIPanel die Verwendung des VoltstroStudios.UnityWebBrowser durch das neue Plugin ersetzt werden.
- Desweiteren muss noch die Web Browser Full Komponente des UnityWebBrowsers (siehe Bild) durch die Komponete des neuen Plugins ersetzt werden.
Die Konfiguration des Netzwerks erfolgt über den ColabNetworkingManager. Dieser befindet sich in der Unity Scene unter Managers>ColabNetworkingManager. Hier können unter Anderem folgende Einstellungen vorgenommen werden:
- Network Address: Hier kann die IP Adresse des Servers eingetragen werden. Diese wird benötigt um eine Verbindung zum Server aufzubauen.
- Max Connections: Hier kann die maximale Anzahl an Spielern eingestellt werden, welche sich gleichzeitig mit dem Server verbinden können.
- Player Prefab: Hier kann das Prefab ausgewählt werden, welches als Spieler in der Anwendung verwendet werden soll.
- Asset Library: Hier muss das ScriptableObject ausgewählt werden, welches die Objektbibliothek der Anwendung enthält damit die Objekte der Objektbibliothek vom Server verwendet werden können.
- Auto Start Server Build: Diese Einstellung sollte aktiviert werden damit der Mirror Server auf dem Server automatisch gestartet wird. Falls diese Einstellung nicht aktiv ist, können Benutzer sich möglicherweise nicht mit dem Mirror Server verbinden und sehen einen schwarzen Bildschirm.
Eine vollständige Liste aller Einstellung sowie weiterer Klassen und Komponenten des Mirror Netzwerks finden sie unter NetworkManager - mirror-api-docs.
Da die Domain über das Projekt hinweg an verschiedenen Stellen verwendet wird, wurde diese in ein Konfigurationsobjekt ausgelagert. Dieses befindet sich unter Assets > _Colab > Settings > NetworkSettings. Hier muss ebenfalls die Domain eingetragen werden, welche anschließend in der Anwendung verwendet wird.
Fall der Server eine SSL Verschlüsselung verwendet, muss der Common Name (CN) des Zertifikats mit der Domain übereinstimmen. In diesem Fall https://colab.uni-wuppertal.de anstelle https://132.195.xxx.xxx.
Das Netzwerk HUD ist ein Interface welches zu Testzwecken verwendet werden kann. Es bietet Schaltflächen für die folgenden Funktionen:
- Host (Server + Client): Startet einen lokalen Server und verbindet den Client mit dem Server.
- Client: Verbindet den Client zu der angegebenen IP-Adresse.
- Server Only: Startet einen lokalen Server ohne einen Client zu verbinden.
Um es an oder auszuschalten, kann die Komponente Network Manager HUD in der Unity Szene unter Managers>NetworkManager aktiviert oder deaktiviert werden. Vor einem Build sollte es idealerweise deaktiviert werden, damit die Benutzer nicht versehentlich auf die Schaltflächen klicken können.
Um weitere Whiteboards zu erstellen, kann ein Whiteboard Prefab aus dem Verzeichnis Assets>_Colab>Assets>Prefabs>3D der Szene hinzugefügt werden. Alternativ können Whiteboards in der Unity MainScene unter Environment > Props als Vorlage verwendet werden. Anschließend müssen folgende Einstellungen vorgenommen werden:
- Media ID: Hier muss die eindeutige ID für das Whiteboard aus dem im Backend erstellten Whiteboard Datei eingetragen werden. Diese wird benötigt um die Medien auf dem Whiteboard anzuzeigen.
Die maximale Dateigröße für den Upload von Medien auf die Whiteboards kann in der Unity Szene im Max File Size In Megabytes Attribut unter Managers > WhiteboardManager angepasst werden. Sollte eine Datei beim Hochladen auf einem Whiteboard die maximale Dateigröße überschreiten, wird eine Fehlermeldung angezeigt und die Datei nicht hochgeladen.
Um die Objektbibliothek um weitere 3D-Objekte zu erweiteren, kann in Unity ein bereits bestehendes Objekt im Verzeichnis Assets>_Colab>Assets>Prefabs>AssetLibrary kopiert und angepasst werden. Ein AssetLibraryObject besteht dabei im wesentlichen aus einem Überobjekt und mehreren Unterobjekten. Es muss darauf geachtet werden, dass sich das Überobjekt auf dem Layer "AssetLibraryPrefab" befindet, andernfalls kann das Objekt weder in der Welt platziert noch mit diesem interagiert werden. Desweiteren müssen auf dem Überobjekt 3 Komponenten vorhanden sein:
-
Box Collider Dieser erstellt eine Box um das Objekt welche dafür sorgt, dass Spieler mit dem Objekt kollidieren und nicht durch das Objekt hindurchlaufen können. Die Größe und Platzierung der Box kann in der Box Collider Komponente entsprechend der Form des 3D-Objekts angepasst werden. Desweiteren sorgt der Kollider dafür, dass das der Spieler mit dem Objekt mittels der Maus interagieren kann.
-
Network Identity Diese Komponente sorgt dafür, dass das Objekt mit dem Server synchronisiert werden kann und somit für alle Spieler sichtbar ist.
-
Asset Library Object Diese Komponente ist das Herzstück des AssetLibraryObjects. Es verbindet die oben genannten Komponentn und sorgt unter Anderem dafür, dass der Spieler mit diesem Objekt in der Welt interagieren kann um es beispielsweise zu entfernen.
In den Unterobjekten liegt die jeweilige Geometrie des Objekts mit einem Mesh Filter und Mesh Renderer. Hierbei sollte wie bereits oben erwähnt darauf geachtet werden, dass sich die Geometrie innerhalb der Box Collider Dimensionen des Überobjekts befindet.
Falls es sich bei dem Objekt um ein begehbares Objekt handeln soll, muss der Aufbau leicht abgewandelt werden. Ein Beispiel hierfür ist der Pavillion unter Assets>_Colab>Assets>Prefabs>AssetLibrary. Bei diesem wurde dem Überobjekt ein Mesh Collider hinzugefügt, welcher in diesem Fall dafür sorgt, dass der Spieler korrekt mit der Geometrie kollidieren kann. Hätte man hier einen normalen Box Collider verwendet, wäre der Spieler an den Grenzen des BoxColliders abgeprallt. Da dennoch ein Box Collider für die Interaktion und diesem Fall auch die AudioZone notwendig ist, wurde dieser ebenfalls hinzugefügt und die Eigenschaft "IsTrigger" gesetzt. Diese sorgt dafür, dass das Objekt nicht mehr mit dem Spieler kollidiert sondern ein Signal sendet, sobald ein Spieler die Grenzen des BoxColliders überschreitet.
Nachdem ein neues Asset Library Objekt erstellt wurde, muss dieses noch dem DefaultAssetLibrary unter Assets/_Colab/Assets/ScriptableObjects Objekt hinzugefügt werden, damit es überhaupt in der Anwendung verfügbar ist und platziert werden kann. Dafür wählt man die DefaultAssetLibrary aus und fügt mittels Klick auf das Plus eine neue Spalte hinzu. In diese kann anschließend das zuvor neu erstellte AssetLibraryObjekt gezogen werden.
Damit das neue AssetLibraryObjekt auch auf dem Server verfügbar ist, muss eine neue Server Version erstellt und auf dem Server installiert werden. Siehe hierfür Erstellung eines Builds und Installation auf dem Server.
Audio Zonen können entweder zuvor in Unity in die Umgebung integriert werden, wofür anschließend allerdings eine neue Version erstellt und auf dem Server installiert werden muss, oder es können die bereits bestehenden AudioZonen über die Objektbibliothek in die Umgebung platziert werden. Falls neue Audiozonen als AssetLibraryObjects erstellt werden, müssen diese wie oben beschrieben ebenfalls der DefaultAssetLibrary hinzugefügt werden.
Eine Audiozone ist dabei ähnlich dem Asset Library Objekt aufgebaut. Der Unterschied liegt darin, dass der Box Collider auf dem Überobjekt dafür sorgt, dass Spieler in eine AudioZone aufgenommen oder aus einer entfernt werden können, sobald sie die Grenzen des Box Colliders überschreiten. Hierfür wurde ebenfalls wieder die Funktion "Is Trigger" in der Box Collider Komponente gesetzt damit der Spieler nicht an den Grenzen des Colliders abprallt.
Damit das Objekt in der Anwendung überhaupt erst als AudioZone verwendet werden kann, muss dem Objekt noch die Audio Zone Komponente hinzugefügt werden. Hier sind keine weiteren Einstellungen notwendig.
Um die Lautstärke des Spatial Audios zu kalibrieren können im VoiceChatManager in der Szene unter Managers>VoiceChatManager zwei Parameter angepasst werden.
-
Die Max Player Audio Distance beschreibt die maximale Entfernung in Metern in der der Spieler die Audioquelle noch hören kann.
-
Die Player Audio Curve beschreibt den Verlauf der Lautstärke des Spatial Audios in Abhängigkeit zur Entfernung des Spielers zur Audioquelle. Die Entfernung auf der X-Achse und die Lautstärke auf der Y-Achse sind auf den Wertebereich 0-1 normalisiert. Die Kurve kann durch das Verschieben der Punkte angepasst werden. Bei einer Max Player Audio Distance von beispielsweise 15 Metern, würde der Wert 1 auf der X-Achse einer Entfernung von 15 Metern entsprechen und der Wert 1 auf der Y-Achse der maximalen Lautstärke.
Überprüft werden kann dies im Unity Editor zusammen mit einem zweiten Spieler. Dafür wählt man die Spielerkomponente in der Szene aus und wählt in ihren Unterobjekten die Audio Quelle aus. Anschließend bewegt man sich um die Audioquelle herum und beobachten wie sich die Lautstärke zur eigenen Position (in der Kurve als Listener gekennzeichnet) zur Audioquelle verhält.
Um die Emote Animationen auszutauschen müssen zunächst Animationen in Unity importiert werden. Auf folgenden Seiten sind Animationen und Beschreibung zur Integration in Unity erhältlich:
- https://github.com/readyplayerme/animation-library/tree/master
- https://docs.readyplayer.me/ready-player-me/integration-guides/unity/animations/loading-mixamo-animations
Die heruntergeladenen FBX Dateien können anschließend in den Ordner Assets_Colab\Assets\Animation\Animations importiert und die Animations Clips anschließend aus diesen extrahiert werden. Anschließend müssen die Animationen im AnimationLibrary ScriptableObject unter Assets_Colab\Assets\ScriptableObjects ersetzt werden.
Weitere Anpassungen der Keys oder eine neue Zuweisung der Emotes zu den Buttons können über das EmoteWheel Prefab geschehen. Hier kann in der Emote Wheel Button Komponente die ID angepasst werden.
Um eine Sitzfunktion zu einem Stuhl hinzuzufügen, muss die Sitzposition als Child-GameObject dem Stuhl-GameObject hinzugefügt werden. Die Sitzposition sollte sich vor dem Stuhl befinden. Der Stuhl muss mit dem Tag "Chair" versehen und das ChairClickHandler-Script zugewiesen werden.
Das SitOnChair-Script muss mit dem PlayerObject unter \Assets_Colab\Assets\Prefabs\3D\PlayerObject verknüpft sein. Dieses Script ist für die Erkennung und Interaktion mit dem Stuhl zuständig. Die Bewegung zum Stuhl sowie die Sitz-Animation werden im SimplePlayerMovement-Script ausgeführt.
Die jeweiligen Berechtigungen können im MainManager.cs angepasst werden. (Wird ebenfalls noch weiter ausformuliert).
Um aus Unity eine Anwendung zu erstellen, muss ein sogenannter Build erstellt werden. Dieser verpackt das Unity Projekt in eine ausführbare Anwendung. Dabei unterscheiden sich die Builds grundsätzlich in Client oder Server Build. Der Client Build ist die Anwendung die letzendlich vom Spieler auf dem eigenen PC ausgeführt wird und unterschiedet sich je nach Betriebssystem in Windows und Mac. Der Server Build ist die Anwendung welche auf dem Server installiert werden muss und sorgt dafür dass die verschiedenen Client Builds miteinander kommunizieren können.
Ein Client Build wird folgendermaßen erstellt:
- Das NetworkManagerHUD sollte ausgeschaltet sein (siehe Netzwerk HUD) damit Benutzer sich nicht ohne Benutzerdaten mit dem Server verbinden können.
- Unter File > Build Settings wird zunächst die Platform Windows, Mac, Linux ausgewählt
- Anschließend muss unter Zielplattform das jeweilige Zielbetriebssystem ausgewählt werden (Windows oder Mac)
- Anschließend kann der Build in einem Verzeichnis erstellt werden.
Ein Server Build wird folgendermaßen erstellt:
- Zunächst muss unter File > Build Settings die Platform auf Dedicated Server gewechselt werden.
- Anschließend muss die Zielplattform auf Linux geändert werden.
- Abschließend kann der Build in einem Verzeichnis erstellt werden
Nach Erstellung eines Serverbuilds sollte beachtet werden zum Testen der Anwendung im Unity Editor die Platform wieder auf Windows,Mac, Linux umzustellen. Andernfalls können Probleme mit fehlenden Bibliotheken auftreten.
Aufgrund der Sicherheitsbestimmung von Windows, muss dem Build eine Company Name und ein Product Name zugewiesen werden. Diese können in den Unity Player Settings unter Other Settings angepasst werden. Aufgrund von Spezifikationen unter Apple Mac, können Mac Builds nur auf einem Mac erstellt werden der über den Silicone Chip verfügt. Aufgrund Apples Sicherheitsbestimmungen muss die Awendung in Unity mit einer sogenannte "Code Signature" versehen werden, welche sicherstellt, dass die Anwendung und deren Inhalt nach Erstellung des Builds nicht verändert wurde. Für eine detaillierte Anleitung und weitere Informationen siehe Unity MacOS Code Signing und Apple Developer Documentation.
Zunächst müssen folgende Dateien auf den Linux Server in ein beliebiges Verzeichnis hochgeladen werden:
- Colab_Server_Client_Data
- Colab_Server_Client.x86_64
- UnityPlayer.so
Anschließend müssen dem Server Ausführungsberechtigungen (-rwxrwxr-x) für die Datei Buildname_Client.x86_64 erteilt werden.
Um den Server Build auf dem Server zu installieren, muss unter Linux ein sogenannter Service erstellt werden. Dieser ermöglicht unter Anderem, dass der Server im Hintergrund gestartet werden kann.
Um den Service auf dem Server zu erstellen muss im Verzeichnis /etc/systemd/system/ eine colabServer.service Datei mit folgendem Inhalt erstellt werden.
[Unit]
Description=Colab Multiplayer Server
After=network.target
StartLimitIntervalSec=0
[Service]
Type=simple
Restart=always
RestartSec=1
User=colab
ExecStart=/home/colab/ServerBuilds/Colab_Server_Client.x86_64
[Install]
WantedBy=multi-user.target
Das unter ExecStart angegebene Verzeichnis und der Name der Datei können hierbei natürlich abweichen und müssen dementsprechend angepasst werden. Es sollte darauf geachtet werden, dass der jeweilige Pfad keine Leerzeichen enthält.
Anschließend kann der Service mit folgendem Befehl kontrolliert werden:
| Befehl | Funktion |
|---|---|
sudo systemctl start colabServer.service |
Dieser Befehl startet den Service |
sudo systemctl stop colabServer.service |
Dieser Befehl stopt den Service |
sudo systemctl restart colabServer.service |
Dieser Befehl startet den Service neu |
sudo journalctl -f -u colabServer.service |
Dieser Befehl gibt die Server Ausgabe aus |
Um die TCP Kommunikation auf dem Server zu ermöglichen, muss noch der Port 7777 geöffnet werden. Dies kann unter Linux mittels folgender Befehle geschehen:
sudo ufw allow 7777
Jenachdem welches Packet installiert ist können mit den folgenden Befehlen die geöffneten Ports angezeigt werden:
ss -lntu
netstat -lntu
Änderungen der Server Sicherheitseinstellungen oder Portfreigaben sollten sicherheitshalber vor Änderung mit den jeweiligen Verantwortlichen abgeklärt werden.