Skip to content

Changes

Page history
Installationsanleitung hinzugefügt authored by Dominic Fehling's avatar Dominic Fehling
Hide whitespace changes
Inline Side-by-side
Development/Installation.md 0 → 100644
View page @ db5d85f4
# Einführung
Willkommen zur Installations- und Einrichtungshilfe für figments.nrw, einer Open-Source-Lernumgebung zur Erstellung immersiver 3D-Welten. Diese Anleitung richtet sich an technische Laien und führt Sie Schritt für Schritt durch die Installation und Konfiguration der benötigten Software, auch ohne Vorkenntnisse in Unity oder Git. Unser Ziel ist es, Sie schnell und sicher in die Lage zu versetzen, figments.nrw einsatzbereit zu machen.
### Voraussetzungen und Hinweise
Für die Nutzung von figments.nrw benötigen Sie einige spezielle Anwendungen und Versionen, um sicherzustellen, dass die Lernumgebung stabil und kompatibel funktioniert. Bitte beachten Sie die folgenden Anforderungen und Versionen, bevor Sie mit der Installation beginnen:
- **Benötigte Anwendungen:**
- Unity 3D (Version **2021.3.5f1**)
- GitHub Desktop mit Git LFS-Unterstützung
- **Systemanforderungen:**
- Mindestens 20 GB freier Speicherplatz auf der Festplatte
- Projektdateien **nicht** in Cloud-Ordnern speichern (z. B. Dropbox, Sciebo)
- Aktuelles Betriebssystem <sup>*</sup>
<sup>*</sup> idealerweise Windows. MacOS und Linux werden von Unity zwar ebenfalls unterstützt, wir können hierzu aber keinen Support anbieten.
### Inhaltsverzeichnis
1. [[#Empfohlene Softwarepakete]]
- [[#Github Desktop]]
- [[#Unity Hub und Unity]]
- [[#Installation von Unity Hub]]
- [[#Einrichtung eines Unity Accounts]]
- [[#Installation von Unity]]
2. [[#Figments.nrw]]
- [[#Download mit Github Desktop]]
- [[#Arbeiten mit Branches]]
- [[#Figments.nrw in Unity Hub einbinden]]
- [[#Figments.nrw starten]]
3. [[#Troubleshooting und Tipps]]
Bitte folgen Sie der Anleitung Schritt für Schritt und halten Sie sich an die empfohlenen Versionen und Einstellungen.
---
# Empfohlene Softwarepakete
In diesem Abschnitt wird die Installation und Einrichtung von GitHub Desktop sowie Git LFS (Large File Storage) erläutert. GitHub Desktop ist eine benutzerfreundliche, grafische Oberfläche, die das Verwalten und Synchronisieren von Git-Repositories erleichtert, ohne dass Befehle in der Kommandozeile erforderlich sind. Dies vereinfacht insbesondere die Zusammenarbeit und Versionskontrolle, was für figments.nrw und den Austausch von Lerninhalten, die damit erstellt wurden, hilfreich ist.
> [!danger]+ Hinweis
> Regelmäßige Sicherungen (Commits) Ihrer Arbeit sind essenziell, um Datenverlust zu vermeiden und bei Fehlern einfach auf vorherige Versionen zurückzugreifen. GitHub Desktop erleichtert dies, indem es Versionsstände übersichtlich anzeigt und sichert.
> [!tip]- Fortgeschrittene Anwender\*innen
> Sie können natürlich auch fortgeschrittenere Lösungen verwenden oder ganz auf die Versionierung verzichten.
---
## Github Desktop
| Betriebssystem | Link zur Installation |
|----------------|-----------------------|
| Windows | [GitHub Desktop für Windows](https://docs.github.com/en/desktop/installing-and-authenticating-to-github-desktop/installing-github-desktop?platform=windows) |
| macOS | [GitHub Desktop für macOS](https://docs.github.com/en/desktop/installing-and-authenticating-to-github-desktop/installing-github-desktop?platform=mac) |
Folgen Sie dem Link für Ihr Betriebssystem, laden Sie GitHub Desktop herunter und installieren Sie es. Sobald die Installation abgeschlossen ist, können Sie die Anwendung öffnen.
> **Hinweis**: Für die Nutzung von GitHub Desktop ist kein Account erforderlich. Falls Sie zur Anmeldung aufgefordert werden, können Sie den Schritt mit *"Skip this Step"* überspringen.
### Git LFS
Git LFS ist ein Tool für die Verwaltung und Speicherung großer Dateien, die bei figments.nrw vorkommen können. Viele Unity-Projekte enthalten große Dateien wie Texturen, Modelle und Audiodateien, die in Git LFS ausgelagert werden. Die Einrichtung von Git LFS erfolgt automatisch bei der Installation von GitHub Desktop.
Falls Sie gefragt werden, ob Git LFS initialisiert werden soll, bestätigen Sie dies bitte.
---
## Unity Hub und Unity
Unity ist eine plattformübergreifende Entwicklungsumgebung, die für figments.nrw als technischer Unterbau dient. In diesem Abschnitt wird die Installation und Konfiguration von Unity Hub sowie der benötigten Unity-Version **2021.3.5f1** erklärt. Unity Hub ist eine Verwaltungssoftware, die das Installieren und Verwalten verschiedener Unity-Versionen sowie die Verwaltung von Projekten und Benutzerkonten vereinfacht.
> **Hinweis:** Die Version 2021.3.5f1 ist erforderlich, um Kompatibilitätsprobleme mit figments.nrw zu vermeiden. Andere Versionen können zu Fehlern führen und das Projekt unbrauchbar machen.
### Installation von Unity Hub
1. Laden Sie Unity Hub über die offizielle Unity-Website herunter: [Unity Hub Download](https://unity.com/download).
2. Installieren Sie Unity Hub, indem Sie dem Installationsassistenten folgen.
3. Starten Sie Unity Hub nach der Installation.
> [!info]
> **Systemvoraussetzungen:** Stellen Sie sicher, dass Ihr Computer die Hardwareanforderungen für Unity erfüllt. Unity erfordert in der Regel mindestens 8 GB RAM und 20 GB freien Speicherplatz.
### Einrichtung eines Unity-Kontos
Für die Nutzung von Unity Hub ist ein Unity-Konto erforderlich. Dieses Konto kann kostenlos erstellt werden:
1. Starten Sie Unity Hub und wählen Sie die Option zur Anmeldung oder Registrierung.
2. Erstellen Sie einen Unity-Account und wählen Sie die **Personal License**, die für den nicht-kommerziellen Gebrauch kostenlos ist.
3. Nach der Erstellung Ihres Kontos und der Anmeldung in Unity Hub können Sie mit der Installation der erforderlichen Unity-Version fortfahren.
### Installation von Unity
![[img_installation_unity-version.png]]
1. Suchen Sie nach der Version **2021.3.5f1** im Unity-Archiv: [Unity Archive](https://unity.com/releases/editor/archive).
2. Klicken Sie auf **Install**
3. Wählen Sie die folgenden Add-on Module aus, damit diese ebenfalls installiert werden:
1. (notwendig) Um Figments.nrw im Desktop oder PC-VR Modus zu betreiben:
`Windows Build Support (IL2CPP)`
2. (optional) Falls Sie planen, Figments.nrw auf Standalone VR HMDs (z. B. Pico) zu betreiben:
`Android Build Support`, `OpenJDK`, `Android SDK & NDK Tools`
3. (optional) Falls Sie planen, eine Server-Version von Figments.nrw zu erstellen:
`Linux Build Support (IL2CPP)`, `Linux Dedicated Server Build Support`
> [!warning]
> **Installation nur über Unity Hub:** Laden Sie die Version 2021.3.5f1 nicht direkt von der Unity-Website herunter, sondern nutzen Sie den Install-Button im Unity-Archiv. Dies stellt sicher, dass die Version korrekt in Unity Hub integriert wird.
---
# Figments.nrw
Figments.nrw ist ein Open-Source-Framework für Unity zur Erstellung immersiver Lernumgebungen. Es bietet benutzerfreundliche Low-Code-Tools zum Design virtueller Welten und zur Erstellung interaktiver 3D-Objekte. Dieser Abschnitt führt durch den Download und die Einrichtung von Figments.nrw über GitHub Desktop.
## Download mit Github Desktop
![[img_installation_github-desktop_existing-installation.png]]
Wir empfehlen, Figments.nrw über GitHub Desktop herunterzuladen:
1. Öffnen Sie GitHub Desktop und klicken Sie auf **File > Clone Repository > URL**.
2. Geben Sie die Repository-URL ein:
`https://git.uni-wuppertal.de/tmdt-iel/figments.nrw.git`
3. Wählen Sie den Pfad aus, in dem das Projekt gespeichert werden soll.
> [!danger]+ Cloud-Ordner
> Der Pfad sollte sich **nicht** in einem Cloud-Ordner befinden, da dies zu Synchronisierungsproblemen führen kann.
4. Klicken Sie auf **Clone**. GitHub Desktop lädt das Repository nun in den angegebenen Ordner herunter.
> [!tip]
> Wenn Sie aufgefordert werden, Git LFS zu initialisieren, können Sie dies bestätigen. Git LFS verwaltet große Dateien effizient und verbessert die Leistung bei Unity-Projekten.
> [!info]- Direkt-Download
> Sie können Figments.nrw auch direkt herunterladen: [Download-Link](https://git.uni-wuppertal.de/tmdt-iel/figments.nrw/-/archive/main/figments.nrw-main.zip)
> Das Archiv müssen Sie anschließend nur noch entpacken und zu [[#Figments.nrw in Unity Hub einbinden|Unity Hub]] hinzufügen.
> **Wir empfehlen, trotz des Mehraufwands, mit Github Desktop zu arbeiten. Dies vereinfacht sowohl die Bereitstellung von Aktualisierungen, als auch die Sicherung Ihrer eigenen Arbeiten in Figments.nrw.**
## Arbeiten mit Branches
In den meisten Fällen können Sie direkt im `main` Branch arbeiten, vor allem, wenn Sie figments.nrw zuerst kennenlernen und grundlegende Tests durchführen möchten. Der `main` Branch enthält die stabile Version des Projekts und sollte stets durch einen **Pull** auf den neuesten Stand gebracht werden, bevor Sie das Projekt in Unity starten.
![[img_installation_branches.png]]
Falls Sie jedoch eigene Inhalte erstellen oder größere Änderungen planen, empfehlen wir, dafür einen eigenen Branch anzulegen. So bleibt der Hauptzweig stabil und Ihre Anpassungen sind getrennt, wodurch das Projekt für andere Nutzer*innen übersichtlich bleibt.
1. Öffnen Sie GitHub Desktop und wählen Sie den Branch `main` für allgemeine Tests und erste Einsätze aus, oder legen Sie bei individuellen Projekten einen eigenen Branch an.
2. Aktualisieren Sie Figments.nrw
1. Klicken Sie dazu zunächst auf `Fetch Origin`
2. Wenn eine neue Version vorliegt, können Sie diese mit `Pull` herunterladen
> [!info]+ Info
> Für den allgemeinen Einsatz und zum Erkunden von figments.nrw ist das Arbeiten im `main` Branch ausreichend. Sollten Sie jedoch planen, eigene Funktionen und Erweiterungen beizutragen, folgen Sie bitte den untenstehenden Empfehlungen zur Arbeit in Branches.
### Branching und Workflow
- **Arbeiten in eigenen Branches:** Da direkte Änderungen am `main` Branch nicht gestattet sind, legen Sie für eigenständige Arbeiten immer einen individuellen Branch an. Benennen Sie den Branch klar und aussagekräftig, z. B. `feature-anpassungen` oder `bugfix-bug123`, damit der Zweck erkennbar bleibt.
- **Pull für Updates:** Stellen Sie sicher, dass Ihr lokales Repository auf dem neuesten Stand ist, bevor Sie in Ihrem Branch arbeiten. Holen Sie regelmäßig Änderungen aus dem `main` Branch, um sicherzustellen, dass Ihre Version aktuell ist und Konflikte minimiert werden.
- **Regelmäßige Commits:** Speichern Sie Änderungen regelmäßig als Commits ab. Diese sollten kurze, präzise Beschreibungen enthalten, um die vorgenommenen Änderungen verständlich zu dokumentieren. So behalten Sie eine klare Versionshistorie, die bei der Fehlerbehebung und Nachverfolgung hilfreich ist.
- **Push und Pull Requests:** Sobald Sie Ihre Arbeit abgeschlossen haben, führen Sie einen **Push** aus, um die Änderungen in den Remote-Branch hochzuladen. Erstellen Sie dann einen **Pull Request** (PR), um die Änderungen zur Überprüfung und Integration in den `main` Branch vorzuschlagen. PRs stellen sicher, dass alle Anpassungen vor der Zusammenführung geprüft werden.
- **Synchronisation und Konfliktlösung:** Aktualisieren Sie Ihren Branch regelmäßig durch Merge oder Rebase vom `main` Branch, um Konflikte frühzeitig zu erkennen. Eine gute Kommunikation und klare Aufgabenverteilung helfen, Konflikte zu vermeiden.
## Figments.nrw in Unity Hub einbinden
![[img_installation_add-project-to-hub.png]]
Nachdem das Repository lokal gespeichert wurde, können Sie das Projekt nun in Unity öffnen:
1. Öffnen Sie Unity Hub und wechseln Sie zum Tab **Projects**.
2. Klicken Sie auf **Add > Add project from disk** und navigieren Sie zu dem [[#Download von Figments.nrw|Pfad]], in dem Sie Figments.nrw gespeichert haben. Wählen Sie dort den Ordner **FigmentsNRW** aus.
3. Wählen Sie den Ordner aus und klicken Sie auf **Add project**, um das Projekt zum Unity Hub hinzuzufügen.
> [!warning]+ Long Term Support
> Achten Sie darauf, dass hier die korrekte Editor Version 2021.3.5f1 ausgewählt ist.
## Figments.nrw starten
1. Öffnen Sie Unity Hub und klicken Sie auf den Projektnamen **FigmentsNRW**, um das Projekt zu starten.
> [!warning]+ Update-Warnungen
> Unity wird möglicherweise Updates für Komponenten wie unseren Avatar-Service ReadyPlayer.me vorschlagen.
> **Bitte lehnen Sie diese Updates ab, da sie zu Kompatibilitätsproblemen führen können!**
2. Nach dem Start sind Unity und figments.nrw einsatzbereit.
> [!failure]- Bei Fehlermeldungen und Problemen
> Falls Fehler oder Probleme auftreten, besuchen Sie bitte den Abschnitt [[#Troubleshooting]].
Um sich mit Figments.nrw vertraut zu machen, können Sie unser Einstiegstutorial nutzen. Diese finden Sie sowohl direkt in Figments.nrw (unter `Assets/Tutorials`) als auch auf unserer [Website](https://www.figments.nrw/tutorials).
Weitere Informationen und Hilfestellungen finden Sie in unserem [Wiki](https://git.uni-wuppertal.de/tmdt-iel/figments.nrw/-/wikis/home).
---
# Troubleshooting und Tipps
In diesem Abschnitt finden Sie Lösungen zu häufig auftretenden Problemen und Hinweise zur Vermeidung typischer Fehler beim Arbeiten mit figments.nrw in Unity.
## Häufige Probleme und Lösungen
> [!failure]- Projekt enthält Kompilerfehler
> ![[img_installation_compiler-error.png|300]]
>
> In seltenen Fällen können sich Fehler im Quellcode auch auf dem `main` Branch wiederfinden. Unity wird diese mit oben stehender Fehlermeldung quittieren, sie können das Projekt aber dennoch häufig regulär öffnen. Da der Code aber nicht ausgeführt werden kann, lässt sich Figments.nrw in diesen Fällen nicht starten.
>
> > [!success]- Lösung
> > - Bitte erstellen Sie einen möglichst detaillierten Fehlerbericht in unserem Ticketsystem:
> > https://git.uni-wuppertal.de/tmdt-iel/figments.nrw/-/issues
> [!failure]- Git Variable fehlt - Unity startet im Safe Mode
> ![[img_installation_error-git-path.png|300]]
>
> Wenn Unity beim Projektstart den Safe-Modus vorschlägt, könnte ein Problem mit den installierten Git- und Git LFS-Konfigurationen vorliegen.
>
> > [!success]- Lösung
> > - Prüfen Sie, ob Git und Git LFS korrekt installiert sind und im Systempfad verfügbar sind.
> > - Für Windows können Sie sich die Einrichtung von Git LFS in diesem [YouTube-Video](https://youtu.be/F-8A8mJwL_Y) ansehen.
> > - Auf macOS führen Sie folgende Schritte aus:
> > 1. Öffnen Sie das Terminal (`Command + Leertaste`, dann „Terminal“ eingeben).
> > 2. Installieren Sie [Homebrew](https://brew.sh/):
> > ```bash
> > /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
> > ```
> > 3. Installieren Sie Git LFS:
> > ```bash
> > brew install git-lfs
> > ```
> >
> > > [!warning]
> > > Nach der Installation von Git und Git LFS starten Sie das System neu, damit Unity die Änderungen erkennt.
> [!failure]- Fehlermeldungen zu fehlenden Komponenten
> Unity kann Fehlermeldungen zu fehlenden Komponenten oder Assets anzeigen, wenn bestimmte Komponenten nicht korrekt geladen wurden.
>
> > [!success]- Lösung
> > - Führen Sie im Unity Hub vor dem Start einen **Pull** im `main` Branch durch, um sicherzustellen, dass alle Dateien aktuell sind.
> > - Überprüfen Sie, ob Sie alle benötigten Unity-Pakete und Assets installiert haben. Falls Updates vorgeschlagen werden, lehnen Sie diese ab, um Kompatibilitätsprobleme zu vermeiden.
> [!failure]- Projekt lädt langsam oder stürzt ab
> Wenn das Projekt langsam lädt oder Unity unerwartet abstürzt, könnte dies an Hardware-Ressourcen oder an speicherintensiven Projektdateien liegen.
>
> > [!success]- Lösung
> > - Stellen Sie sicher, dass Ihr System mindestens 20 GB freien Speicher und ausreichenden Arbeitsspeicher für das Projekt hat.
> > - Vermeiden Sie es, das Projekt in einem Cloud-Ordner (z. B. OneDrive) zu speichern, da dies zu Synchronisationsproblemen und Ladeverzögerungen führen kann.
## Allgemeine Tipps zur Fehlervermeidung
- **Aktualität der Branches:** Führen Sie regelmäßig Pulls durch, um sicherzustellen, dass Ihre lokale Version mit der `main` Version synchron ist. So vermeiden Sie mögliche Konflikte und Inkompatibilitäten.
- **Keine direkten Änderungen am `main` Branch:** Arbeiten Sie bei eigenen Erweiterungen immer in einem individuellen Branch. Dies bewahrt die Stabilität des `main` Branch und vereinfacht die Fehlersuche.
- **Regelmäßiges Speichern und Committen:** Speichern Sie Fortschritte regelmäßig als Commits, um eine lückenlose Versionshistorie zu behalten. Falls ein Problem auftritt, können Sie so leicht auf eine funktionierende Version zurückkehren.
- **Dokumentation und Wiki:** Nutzen Sie das Wiki und die Dokumentation für zusätzliche Informationen und Antworten auf häufige Fragen.
Bei weiteren Problemen können Sie sich an das Entwicklerteam wenden oder eine Fehlermeldung im Wiki hinterlassen. Die Community unterstützt Sie ebenfalls gerne bei Fragen und Problemen.
\ No newline at end of file