add the complete documentation for setting up the senseglove default classes

2024-08-10 19:42:15 +02:00
parent 52905c9fb5
commit 3df70c8c3c
34 changed files with 328 additions and 3 deletions
@@ -21,12 +21,13 @@ Welcom to the SenseGlove Unreal Engine Handbook!
    - [SenseCom on Microsoft Windows](getting-started/sensecom/microsoft-windows.md)
 - [Enabling XR_EXT_hand_tracking on VR Headsets](getting-started/enabling-xr-ext-hand-tracking-vr-headsets/README.md)
 - [Setup SenseGlove Default Classes](getting-started/setup-senseglove-default-classes/README.md)
+    - [SGGameModeBase](getting-started/setup-senseglove-default-classes/sggamemodebase.md)
    - [SGPawn](getting-started/setup-senseglove-default-classes/sgpawn.md)
    - [SGPlayerController](getting-started/setup-senseglove-default-classes/sgplayercontroller.md)
-    - [SGGameModeBase](getting-started/setup-senseglove-default-classes/sggamemodebase.md)
    - [SGGameInstance](getting-started/setup-senseglove-default-classes/sggameinstance.md)
    - [SGGameUserSettings](getting-started/setup-senseglove-default-classes/sggameusersettings.md)
- [Setup a Virtual Hand Mesh]()
+- [Setup the Virtual Hand Meshes](getting-started/setup-virtual-hand-meshes/README.md)
+- [Setup the Wrist Tracking Hardware](getting-started/setup-wrist-tracking-hardware/README.md)
 - [Setup the Grab System]()
 - [Setup the Touch System]()

@@ -4,9 +4,9 @@ Setting up the default SenseGlove classes is recommended if you want to take ful

 If you wish to extend the functionality of these classes, you can do so by subclassing them. The default SenseGlove classes, which are prefixed with `SG`, include:

+- [SGGameModeBase](ggamemodebase.md)
 - [SGPawn](sgpawn.md)
 - [SGPlayerController](sgplayercontroller.md)
- [SGGameModeBase](ggamemodebase.md)
 - [SGGameInstance](sggameinstance.md)
 - [SGGameUserSettings](sggameusersettings.md)

@@ -1 +1,44 @@
 # Setting Up SGGameInstance
+
+Setting `SGGameInstance` as the default `Game Instance Class` is very straightforward. You can do this by navigating to `Project Settings > Project > Maps & Modes > Game Instance > Game Instance Class`.
+
+![Setting Up SGGameInstance - Setting the default class SGGameInstance](set-default-class-sggameinstance.png "Setting Up SGGameInstance - Setting the default class SGGameInstance")
+
+> [!TIP]
+> For greater control and customization, consider
+> [extending the SGGameInstance](#extending-sggameinstance).
+
+> [!IMPORTANT]
+> Currently, setting `SGGameModeBase` or a subclass of it as the default
+> `Game Instance Class` is not a strict requirement. However, if you intend to
+> use any [SenseGlove console command](../../misc/console-commands/) it becomes
+> mandatory. If not set, SenseGlove console commands will not be recognized by
+> Unreal Engine.
+
+## Extending SGGameInstance
+
+Follow these steps to extend and set up your own version of `SGGameInstance`:
+
+1. In the Content Browser, click the `+ Add` button, then select `Blueprint Class from the menu`. Alternatively, right-click inside the Content Browser and choose `Blueprint Class` from the context menu.
+
+![Extending SGGameInstance - Adding a Blueprint Class](add-blueprint-class.png "Extending SGGameInstance - Adding a Blueprint Class")
+
+2. A dialog will appear asking you to choose a parent class. Click on the `ALL CLASSES` section to expand the list of available classes.
+
+![Extending SGGameInstance - Picking a Parent Class](pick-parent-class.png "Extending SGGameInstance - Picking a Parent Class")
+
+3. In the expanded `ALL CLASSES` section, start typing `SGGameInstance` in the Search box. When `SGGameInstance` appears, select it and click the `Select` button to create your new Blueprint class based on it.
+
+![Extending SGGameInstance - Picking SGGameInstance as the Parent Class](pick-parent-class-sggameinstance.png "Extending SGGameInstance - Picking SGGameInstance as the Parent Class")
+
+4. After returning to the Content Browser, the Unreal Editor will prompt you to rename `NewBlueprint` to your desired class name. You can rename the class at any time by pressing `F2` or by right-clicking on it and selecting `Rename` from the context menu.
+
+![Extending SGGameInstance - Renaming NewBlueprint](rename-new-blueprint.png "Extending SGGameInstance - Renaming NewBlueprint")
+
+5. Once you have renamed the `NewBlueprint` class to your desired name, click on `Save All` to save the new class to disk.
+
+![Extending SGGameInstance - Renamed NewBlueprint to BP_SGGameInstance](renamed-new-blueprint-sggameinstance.png "Extending SGGameInstance - Renamed NewBlueprint to BP_SGGameInstance")
+
+6. Finally, set your newly created subclass of `SGGameInstance` as the default `Game Instance Class`. You can do this by navigating to `Project Settings > Project > Maps & Modes > Game Instance > Game Instance Class`.
+
+![Extending SGGameInstance - Setting the default class BP_SGGameInstance](set-default-class-bpsggameinstance.png "Extending SGGameInstance - Setting the default class BP_SGGameInstance")
@@ -1 +1,58 @@
 # Setting Up SGGameModeBase
+
+After [installing](../installation/) and [enabling](../plugin-verify-version-enable/) the SenseGlove Unreal Engine Plugin, the easiest and most straightforward approach to get started is to just set the default GameMode to `SGGameModeBase` from `Edit > Project Settings... > Maps & Modes > Default Mode > Default GameMode`. By doing this, the `Default Pawn Class` is automatically set to [`SGPawn`](sgpawn.md), and the `Player Controller Class` is set to [`SGPlayerController`](sgplayercontroller.md). This setup ensures that a SenseGlove pawn will automatically spawn when you hit the play button in the editor.
+
+![Setting Up SGGameModeBase - Setting the default class SGGameModeBase](set-default-class-sggamemodebase.png "Setting Up SGGameModeBase - Setting the default class SGGameModeBase")
+
+> [!TIP]
+> For greater control and customization, consider
+> [extending the SGGameModeBase](#extending-sggamemodebase).
+
+> [!NOTE]
+> Currently, setting `SGGameModeBase` or a subclass of it as the
+> `Default GameMode` is not a strict requirement. Its primary function is to
+> ensure that a default `SGPawn` and `SGPlayerController` are set. However, this
+> might change in the future, and it could become a mandatory setting.
+
+> [!IMPORTANT]
+> While setting `SGGameModeBase` as the `Default GameMode` will automatically
+> spawn the default SGPawn at BeginPlay and initiate communication with the
+> SenseGlove devices, it will not display any virtual hands in your simulation
+> by default. You might still need to configure the
+> [Virtual Hand Meshes](../setup-virtual-hand-meshes/) and the
+> [Wrist Tracking Hardware](../setup-wrist-tracking-hardware/) separately.
+
+> [!IMPORTANT]
+> Before starting the simulation in the editor, make sure that
+> [SenseCom](../sensecom/) is running and
+> [XR_EXT_hand_tracking](../enabling-xr-ext-hand-tracking-vr-headsets/)
+> is enabled. Without these, your simulation will not receive hand pose data
+> from the SenseGlove devices.
+
+## Extending SGGameModeBase
+
+Follow these steps to extend and set up your own version of `SGGameModeBase`:
+
+1. In the Content Browser, click the `+ Add` button, then select `Blueprint Class from the menu`. Alternatively, right-click inside the Content Browser and choose `Blueprint Class` from the context menu.
+
+![Extending SGGameModeBase - Adding a Blueprint Class](add-blueprint-class.png "Extending SGGameModeBase - Adding a Blueprint Class")
+
+2. A dialog will appear asking you to choose a parent class. Click on the `ALL CLASSES` section to expand the list of available classes.
+
+![Extending SGGameModeBase - Picking a Parent Class](pick-parent-class.png "Extending SGGameModeBase - Picking a Parent Class")
+
+3. In the expanded `ALL CLASSES` section, start typing `SGGameModeBase` in the Search box. When `SGGameModeBase` appears, select it and click the `Select` button to create your new Blueprint class based on it.
+
+![Extending SGGameModeBase - Picking SGGameModeBase as the Parent Class](pick-parent-class-sggamemodebase.png "Extending SGGameModeBase - Picking SGGameModeBase as the Parent Class")
+
+4. After returning to the Content Browser, the Unreal Editor will prompt you to rename `NewBlueprint` to your desired class name. You can rename the class at any time by pressing `F2` or by right-clicking on it and selecting `Rename` from the context menu.
+
+![Extending SGGameModeBase - Renaming NewBlueprint](rename-new-blueprint.png "Extending SGGameModeBase - Renaming NewBlueprint")
+
+5. Once you have renamed the `NewBlueprint` class to your desired name, click on `Save All` to save the new class to disk.
+
+![Extending SGGameModeBase - Renamed NewBlueprint to BP_SGGameMode](renamed-new-blueprint-sggamemodebase.png "Extending SGGameModeBase - Renamed NewBlueprint to BP_SGGameMode")
+
+6. Finally, set your newly created subclass of `SGGameModeBase` as the `Default GameMode`. You can do this by navigating to `Project Settings > Project > Maps & Modes > Default Modes > Default GameMode`.
+
+![Extending SGGameModeBase - Setting the default class BP_SGGameMode](set-default-class-bpsggamemode.png "Extending SGGameModeBase - Setting the default class BP_SGGameMode")
@@ -1 +1,45 @@
 # Setting Up SGGameUserSettings
+
+Setting `SGGameUserSettings` as the default `Game User Settings Class` is very straightforward. You can do this by navigating to `Project Settings > Engine > General Settings > Default Classes > Advanced > Game User Settings Class`. Once you change the default `Game User Settings Class` the Unreal Editor will prompt you with `Restart required to apply new settings`. For the changes to take effect, click on the `Restart Now` button and wait for the editor to reopen.
+
+![Setting Up SGGameUserSettings - Setting the default class SGGameUserSettings](set-default-class-sggameusersettings.png "Setting Up SGGameUserSettings - Setting the default class SGGameUserSettings")
+
+> [!TIP]
+> For greater control and customization, consider
+> [extending the SGGameUserSettings](#extending-sggameusersettings).
+
+> [!IMPORTANT]
+> Currently, setting `SGGameUserSettings` or a subclass of it as the default
+> `Game User Settings Class` is not a strict requirement. However, if you intend
+> to use any
+> [SGGameUserSettings-related SenseGlove console command](../../misc/console-commands/)
+> it becomes mandatory. If not set, calling any SGGameUserSettings-related
+> SenseGlove console command will cause your simulation or editor to crash.
+
+## Extending SGGameUserSettings
+
+Follow these steps to extend and set up your own version of `SGGameUserSettings`:
+
+1. In the Content Browser, click the `+ Add` button, then select `Blueprint Class from the menu`. Alternatively, right-click inside the Content Browser and choose `Blueprint Class` from the context menu.
+
+![Extending SGGameUserSettings - Adding a Blueprint Class](add-blueprint-class.png "Extending SGGameUserSettings - Adding a Blueprint Class")
+
+2. A dialog will appear asking you to choose a parent class. Click on the `ALL CLASSES` section to expand the list of available classes.
+
+![Extending SGGameUserSettings - Picking a Parent Class](pick-parent-class.png "Extending SGGameUserSettings - Picking a Parent Class")
+
+3. In the expanded `ALL CLASSES` section, start typing `SGGameUserSettings` in the Search box. When `SGGameUserSettings` appears, select it and click the `Select` button to create your new Blueprint class based on it.
+
+![Extending SGGameUserSettings - Picking SGGameUserSettings as the Parent Class](pick-parent-class-sggameusersettings.png "Extending SGGameUserSettings - Picking SGGameUserSettings as the Parent Class")
+
+4. After returning to the Content Browser, the Unreal Editor will prompt you to rename `NewBlueprint` to your desired class name. You can rename the class at any time by pressing `F2` or by right-clicking on it and selecting `Rename` from the context menu.
+
+![Extending SGGameUserSettings - Renaming NewBlueprint](rename-new-blueprint.png "Extending SGGameUserSettings - Renaming NewBlueprint")
+
+5. Once you have renamed the `NewBlueprint` class to your desired name, click on `Save All` to save the new class to disk.
+
+![Extending SGGameUserSettings - Renamed NewBlueprint to BP_SGGameUserSettings](renamed-new-blueprint-sggameusersettings.png "Extending SGGameUserSettings - Renamed NewBlueprint to BP_SGGameUserSettings")
+
+6. Finally, set your newly created subclass of `SGGameUserSettings` as the default `Game User Settings Class`. You can do this by navigating to `Project Settings > Engine > General Settings > Default Classes > Advanced > Game User Settings Class`. Once you change the default `Game User Settings Class` the Unreal Editor will prompt you with `Restart required to apply new settings`. For the changes to take effect, click on the `Restart Now` button and wait for the editor to reopen.
+
+![Extending SGGameUserSettings - Setting the default class BP_SGGameUserSettings](set-default-class-bpsggameusersettings.png "Extending SGGameUserSettings - Setting the default class BP_SGGameUserSettings")
@@ -1 +1,62 @@
 # Setting Up SGPawn
+
+Depening on the Unreal Engine version and your project's type and configuration, you might be able to set `SGPawn` as the `Default Pawn Class` by navigating to `Project Settings > Project > Maps & Modes > Default Modes > Selected GameMode > Default Pawn Class`. However, regardless of the engine version or project type and configuration, you can always configure this by opening your [`Default GameMode`](sggamemodebase.md) and setting the `Default Pawn Class` directly from there. Once set, click on the `Compile` button and save your game mode Blueprint asset.
+
+![Setting Up SGPawn - Setting the default class SGPawn](set-default-class-sgpawn.png "Setting Up SGPawn - Setting the default class SGPawn")
+
+> [!TIP]
+> For greater control and customization, consider
+> [extending the SGPawn](#extending-sgpawn).
+
+> [!CAUTION]
+> Setting `SGPawn` or a subclass of it as the `Default Pawn Class` without
+> setting
+> [`SGPlayerController` or a subclass of it as the default `Player Controller Class`](sgplayercontroller.md)
+> will cause the `SGPawn` to not function properly. So, it's a strict
+> requirement.
+
+## Extending SGPawn
+
+Follow these steps to extend and set up your own version of `SGPawn`:
+
+1. In the Content Browser, click the `+ Add` button, then select `Blueprint Class from the menu`. Alternatively, right-click inside the Content Browser and choose `Blueprint Class` from the context menu.
+
+![Extending SGPawn - Adding a Blueprint Class](add-blueprint-class.png "Extending SGPawn - Adding a Blueprint Class")
+
+2. A dialog will appear asking you to choose a parent class. Click on the `ALL CLASSES` section to expand the list of available classes.
+
+![Extending SGPawn - Picking a Parent Class](pick-parent-class.png "Extending SGPawn - Picking a Parent Class")
+
+3. In the expanded `ALL CLASSES` section, start typing `SGPawn` in the Search box. When `SGPawn` appears, select it and click the `Select` button to create your new Blueprint class based on it.
+
+![Extending SGPawn - Picking SGPawn as the Parent Class](pick-parent-class-sgpawn.png "Extending SGPawn - Picking SGPawn as the Parent Class")
+
+4. After returning to the Content Browser, the Unreal Editor will prompt you to rename `NewBlueprint` to your desired class name. You can rename the class at any time by pressing `F2` or by right-clicking on it and selecting `Rename` from the context menu.
+
+![Extending SGPawn - Renaming NewBlueprint](rename-new-blueprint.png "Extending SGPawn - Renaming NewBlueprint")
+
+5. Once you have renamed the `NewBlueprint` class to your desired name, click on `Save All` to save the new class to disk.
+
+![Extending SGPawn - Renamed NewBlueprint to BP_SGPawn](renamed-new-blueprint-sgpawn.png "Extending SGPawn - Renamed NewBlueprint to BP_SGPawn")
+
+6. Finally, set your newly created subclass of `SGPawn` as the `Default Pawn Class`. Depening on the Unreal Engine version and your project's type and configuration, you might be able do this by navigating to `Project Settings > Project > Maps & Modes > Default Modes > Selected GameMode > Default Pawn Class`. However, regardless of the engine version or project type and configuration, you can always configure this by opening your [`Default GameMode`](sggamemodebase.md) and setting the `Default Pawn Class` directly from there. Once set, click on the `Compile` button and save your game mode Blueprint asset.
+
+![Extending SGPawn - Setting the default class BP_SGPawn](set-default-class-bpsgpawn.png "Extending SGPawn - Setting the default class BP_SGPawn")
+
+## Customizing SGPawn
+
+Customizing the `SGPawn` after subclassing is straightforward and flexible.
+
+The `SGPawn` class includes several key subcomponents:
+
+- `Wrist Tracker Left` and `Wrist Tracker Right` of type `SGWristTrackerComponent`.
+- `HandLeft` and `HandRight` of type `SGVirtualHandComponent` and represent the virtual hand models visible to the user in the simulation.
+- `RealHandLeft` and `RealHandRight` of type `SGVirtualHandComponent`. By default, these are hidden and represent the real hands within the simulation. These components are useful if you need to separate the rendering of the virtual hands from the real hands. For instance, the virtual hands typically have collisions and cannot pass through objects, while the real hands are not constrained in this way.
+
+![Customizing SGPawn - The SGPawn components](sgpawn-components.png "Customizing SGPawn - The SGPawn components")
+
+Also, it's possible to filter the properties for these SenseGlove components inside the `Details` panel inside the `SGPawn` Blueprint Editor by typing the work `SenseGlove` inside `Search` box of the `Details` panel.
+
+![Customizing SGPawn - Filtered SGPawn Details panel](sgpawn-filtered-details-panel.png "Customizing SGPawn - Filtered SGPawn Details panel")
+
+Please visit [how to setup the Virtual Hand Meshes](../../getting-started/setup-virtual-hand-meshes/) and [how to setup the Wrist Tracking Hardware](../../getting-started/setup-wrist-tracking-hardware/) for more information.
@@ -1 +1,43 @@
 # Setting Up SGPlayerController
+
+Depening on the Unreal Engine version and your project's type and configuration, you might be able to set `SGPlayerController` as the default `Player Controller Class` by navigating to `Project Settings > Project > Maps & Modes > Default Modes > Selected GameMode > Player Controller Class`. However, regardless of the engine version or project type and configuration, you can always configure this by opening your [`Default GameMode`](sggamemodebase.md) and setting the default `Player Controller Class` directly from there. Once set, click on the `Compile` button and save your game mode Blueprint asset.
+
+![Setting Up SGPlayerController - Setting the default class SGGameModeBase](set-default-class-sgplayercontroller.png "Setting Up SGPlayerController - Setting default the class SGGameModeBase")
+
+> [!TIP]
+> For greater control and customization, consider
+> [extending the SGPlayerController](#extending-sgplayercontroller).
+
+> [!CAUTION]
+> Setting `SGPlayerController` or a subclass of it as the default
+> `Player Controller Class` without setting
+> [`SGPawn` or a subclass of it as the `Default Pawn Class`](sgpawn.md) will
+> cause your simulation or editor to crash. So, it's a strict requirement.
+
+## Extending SGPlayerController
+
+Follow these steps to extend and set up your own version of `SGPlayerController`:
+
+1. In the Content Browser, click the `+ Add` button, then select `Blueprint Class from the menu`. Alternatively, right-click inside the Content Browser and choose `Blueprint Class` from the context menu.
+
+![Extending SGPlayerController - Adding a Blueprint Class](add-blueprint-class.png "Extending SGPlayerController - Adding a Blueprint Class")
+
+2. A dialog will appear asking you to choose a parent class. Click on the `ALL CLASSES` section to expand the list of available classes.
+
+![Extending SGPlayerController - Picking a Parent Class](pick-parent-class.png "Extending SGPlayerController - Picking a Parent Class")
+
+3. In the expanded `ALL CLASSES` section, start typing `SGPlayerController` in the Search box. When `SGPlayerController` appears, select it and click the `Select` button to create your new Blueprint class based on it.
+
+![Extending SGPlayerController - Picking SGPlayerController as the Parent Class](pick-parent-class-sgplayercontroller.png "Extending SGPlayerController - Picking SGPlayerController as the Parent Class")
+
+4. After returning to the Content Browser, the Unreal Editor will prompt you to rename `NewBlueprint` to your desired class name. You can rename the class at any time by pressing `F2` or by right-clicking on it and selecting `Rename` from the context menu.
+
+![Extending SGPlayerController - Renaming NewBlueprint](rename-new-blueprint.png "Extending SGPlayerController - Renaming NewBlueprint")
+
+5. Once you have renamed the `NewBlueprint` class to your desired name, click on `Save All` to save the new class to disk.
+
+![Extending SGPlayerController - Renamed NewBlueprint to BP_SGPlayerController](renamed-new-blueprint-sgplayercontroller.png "Extending SGPlayerController - Renamed NewBlueprint to BP_SGPlayerController")
+
+6. Finally, set your newly created subclass of `SGPlayerController` as the default `Player Controller Class`. Depening on the Unreal Engine version and your project's type and configuration, you might be able do this by navigating to `Project Settings > Project > Maps & Modes > Default Modes > Selected GameMode > Player Controller Class`. However, regardless of the engine version or project type and configuration, you can always configure this by opening your [`Default GameMode`](sggamemodebase.md) and setting the default `Player Controller Class` directly from there. Once set, click on the `Compile` button and save your game mode Blueprint asset.
+
+![Extending SGPlayerController - Setting the default class BP_SGGameMode](set-default-class-bpsgplayercontroller.png "Extending SGPlayerController - Setting the default class BP_SGGameMode")
@@ -0,0 +1 @@
+# Setting Up the Virtual Hand Meshes
@@ -0,0 +1 @@
+# Setting Up the Wrist Tracking Hardware