Added some documentation
Yan Wittmann
parent
b688b5c8f5
commit
7ac9bf90e1
|
|
@ -0,0 +1,218 @@
|
|||
# GAI/CA1 - Yan Wittmann
|
||||
|
||||
## 1.1 Part 1: State Machines
|
||||
|
||||
<!-- TOC -->
|
||||
* [Einleitung](#einleitung)
|
||||
* [Szenen und States-Implementierung](#szenen-und-states-implementierung)
|
||||
* [Konfiguration der Transitionen](#konfiguration-der-transitionen)
|
||||
* [Bedingungen (`conditions`)](#bedingungen-conditions)
|
||||
* [Transfer (`transfer`)](#transfer-transfer)
|
||||
* [Dynamische Zielzustände](#dynamische-zielzustände)
|
||||
<!-- TOC -->
|
||||
|
||||
### Einleitung
|
||||
|
||||
Dieses Projekt stellt eine State Machine dar, die in der Lage ist, zwischen unterschiedlichen Zuständen aufgrund von
|
||||
komplexen Bedingungen zu wechseln.
|
||||
Hier wird diese für einen Character Controller eingesetzt, sie ist aber generisch genug, um auch für andere Anwendungen
|
||||
verwendet zu werden.
|
||||
Die Konfiguration der States und Transitions erfolgt über eine JSON-Datei
|
||||
[character_state_machine.json](assets/character_state_machine.json), die zur Laufzeit eingelesen wird.
|
||||
|
||||
Konkret wird hier ein Reinigungsroboter simuliert, der Müllsäcke einsammelt und zu einem Müllcontainer bringt.
|
||||
Regelmäßig muss er auch seine Batterie aufladen und dafür zu einer Ladestation fahren.
|
||||
|
||||
Eine Video-Demo ist hier verfügbar: [state-machine-demo.mp4](res/state-machine-demo.mp4)
|
||||
|
||||
Alle bewertungsrelevanten Punkte sind erfüllt:
|
||||
|
||||
- Das Projekt implementiert eine State Machine, die einen nicht-Spieler-Charakter steuert.
|
||||
- Der aktuelle Zustand ist mit "b" einblendbar.
|
||||
- Weitere Informationen über den aktuellen Zustand und die Transitionen sind zur Laufzeit mit "b" einblendbar.
|
||||
Weitere Contrubutors können im Code einfach hinzugefügt werden.
|
||||
- Ein Node-Graph zeigt die Transitionen und deren Bedingungen, sowie den aktuellen Zustand an. Mit "a" einblendbar.
|
||||
- Die Visualisierung der Zusatzinformationen kann über "a" und "b" aktiviert und deaktiviert werden.
|
||||
|
||||
### Szenen und States-Implementierung
|
||||
|
||||
Die Haupt-Szene ist [StateMachineWorld.tscn](scenes/state/StateMachineWorld.tscn).
|
||||
Diese verwaltet unter anderem diese Insatanzen:
|
||||
|
||||
- [SMCharacter.gd](scenes/state/SMCharacter.gd): Der Character, auf den die State Machine angewendet wird.
|
||||
- [StateMachine.gd](scenes/state/StateMachine.gd): Als child node des Characters hat die state machine die States als
|
||||
ihre child nodes.
|
||||
- Weitere Instanzen wie ein [TrashBin.tscn](scenes/state/TrashBin.tscn) oder [Battery.tscn](scenes/state/Battery.tscn).
|
||||
|
||||
States implementieren die [State.gd](scenes/state/State.gd)-Klassenschnittstelle, die die folgenden Methoden definiert:
|
||||
|
||||
```gdscript
|
||||
func state_enter() -> void
|
||||
func state_process(delta: float) -> void
|
||||
func state_exit(new_state: State) -> void
|
||||
```
|
||||
|
||||
Da die Transitionen ausschließlich über die JSON-Datei konfiguriert werden, sind die States selbst nur für die
|
||||
Implementierung der Logik zuständig.
|
||||
Ein Beispiel von [state_PickupTrash.gd](scenes/state/state_PickupTrash.gd), der sich auf den Müllsack zubewegt:
|
||||
|
||||
```gdscript
|
||||
extends State
|
||||
|
||||
var pickup_trash_target: Vector2 = Vector2.ZERO
|
||||
|
||||
|
||||
func state_enter():
|
||||
var waste = state_machine.state_transfer_variables["waste"]
|
||||
pickup_trash_target = waste.position
|
||||
print(waste, " ", pickup_trash_target)
|
||||
|
||||
|
||||
func state_process(delta: float) -> void:
|
||||
character.move_towards(pickup_trash_target, delta)
|
||||
character.move_and_slide()
|
||||
```
|
||||
|
||||
Es wird hier bereits viel auf den Charakter ausgelagert, um die States möglichst einfach zu halten.
|
||||
Das viel interresantere ist jedoch die Konfiguration der Transitionen, was im folgenden Kapitel beschrieben wird.
|
||||
|
||||
### Konfiguration der Transitionen
|
||||
|
||||
In der JSON-Datei [character_state_machine.json](assets/character_state_machine.json) werden die States und Transitions
|
||||
konfiguriert.
|
||||
Hierbeit ist das Format möglichst offen gehalten, um auch komplexere Bedingungen zu ermöglichen.
|
||||
|
||||
Auf den obersten Ebenen werden allgemein die folgenden Keys verlangt:
|
||||
|
||||
```json
|
||||
{
|
||||
"start": {
|
||||
"state": "<state_name>"
|
||||
},
|
||||
"template_transitions": {
|
||||
"<transition_name>": {}
|
||||
},
|
||||
"states": {
|
||||
"<state_name>": {
|
||||
"transitions": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `start`: Bestimmt initiale Eigenschaften der State Machine. Eine Property `state` gibt den Startzustand an.
|
||||
- `template_transitions`: Definieren Transitionen, die in `states` referenziert werden können, falls sie mehrfach
|
||||
verwendet werden.
|
||||
- `states`: Definieren die States und über `transitions` deren Transitionen.
|
||||
|
||||
Transitionen sind das Kernstück der Konfiguration und haben folgende Struktur:
|
||||
|
||||
```json
|
||||
{
|
||||
"target": "<state_name>" | { "type": "<selector_type>" },
|
||||
"signal": "<signal_name>",
|
||||
"conditions": [],
|
||||
"transfer": {}
|
||||
}
|
||||
```
|
||||
|
||||
- `target`: Der Name des Zielzustands, zu dem die State Machine wechseln soll. Kann auch ein Objekt sein, das dynamisch
|
||||
einen Zielzustand bestimmt.
|
||||
- `signal`: (Optional) Ein Signalname, der von der State Machine seit dem letzten Tick empfangen werden muss, damit die Transition
|
||||
berücksichtigt wird.
|
||||
- `conditions`: Ein Array von Bedingungen, die alle erfüllt sein müssen, damit die Transition durchgeführt wird.
|
||||
- `transfer`: Ein Objekt, das definiert, welche Daten beim Übergang in den neuen Zustand übergeben werden sollen.
|
||||
|
||||
```json
|
||||
{
|
||||
"template": "<template_transition_name>",
|
||||
}
|
||||
```
|
||||
|
||||
- Oder einfach eine Referenz auf eine `template_transition`.
|
||||
|
||||
#### Bedingungen (`conditions`)
|
||||
|
||||
Bedingungen sind ein Array von Objekten, die alle erfüllt sein müssen, damit eine Transition ausgeführt wird. Jede
|
||||
Bedingung hat folgende Struktur:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "<condition_type>",
|
||||
"left": {},
|
||||
"right": {}
|
||||
}
|
||||
```
|
||||
|
||||
- `type`: Der Typ der Bedingung ("=", "!=", ">", "<", ">=", "<=").
|
||||
- `left`: Der linke Operand der Bedingung.
|
||||
- `right`: Der rechte Operand der Bedingung.
|
||||
|
||||
Die Operanden können entweder eine `value` Property (direkter Wert), einen `accessor` (Pfad zu einer Variable) oder eine
|
||||
`function` (Aufruf einer Funktion) verwenden.
|
||||
|
||||
- `value`: Ein direkter Wert (z.B. `{"value": 100}`).
|
||||
- `accessor`: Ein Array von Strings, das einen Pfad zu einer Variable in der Szene oder der State Machine angibt (z.B.
|
||||
`{"accessor": ["character", "battery_charge"]}`).
|
||||
- `function`: Ein Objekt, das eine Funktion mit Argumenten aufruft (z.B. `{"function": "distance", "args": [...]}`).
|
||||
|
||||
Diese können beliebig verschachtelt werden.
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "<=",
|
||||
"left": {
|
||||
"value": 100
|
||||
},
|
||||
"right": {
|
||||
"accessor": [
|
||||
"character",
|
||||
"battery_charge"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Transfer (`transfer`)
|
||||
|
||||
Das `transfer`-Objekt ermöglicht es, Daten zwischen Zuständen zu übertragen. Es ist ein Objekt, bei dem der Key der Name
|
||||
der Variable ist, und der Wert ein Accessor, der die Datenquelle angibt.
|
||||
|
||||
```json
|
||||
"transfer": {
|
||||
"waste": {
|
||||
"accessor": [
|
||||
"signals",
|
||||
"waste_detected",
|
||||
"args",
|
||||
"waste"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In diesem Beispiel wird die Variable `waste` des Zielzustands mit dem Wert des Arguments `waste` des Signals `waste_detected` befüllt.
|
||||
|
||||
#### Dynamische Zielzustände
|
||||
|
||||
Der `target` einer Transition kann auch ein Objekt sein, das dynamisch einen Zielzustand bestimmt.
|
||||
Das folgende Beispiel zeigt, wie man in der Historie der Zustände zu einem vorherigen Zustand zurückkehrt,
|
||||
aber gewisse Zustände dabei ignoriert:
|
||||
|
||||
```json
|
||||
{
|
||||
"target": {
|
||||
"type": "history_first",
|
||||
"ignore": [
|
||||
"RechargeBattery",
|
||||
"GoToBattery"
|
||||
],
|
||||
"restore_transfer_variables": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `type`: Der Typ des dynamischen Ziels (hier: `history_first`).
|
||||
- `ignore`: Eine Liste von Zuständen, die bei der Suche nach dem vorherigen Zustand ignoriert werden sollen.
|
||||
- `restore_transfer_variables`: Ein Boolean, der angibt, ob die Transfervariablen dieses vorherigen Zustands ebenfalls
|
||||
wiederhergestellt werden sollen.
|
||||
Binary file not shown.
Loading…
Reference in New Issue