project-SIMPLE · FlorianBarbe · Jul 3, 2026 · Jul 3, 2026 · Jul 3, 2026 · Jul 3, 2026
diff --git a/Documentation~/09-troubleshooting.md b/Documentation~/09-troubleshooting.md
diff --git a/Documentation~/README.md b/Documentation~/README.md
@@ -15,12 +15,14 @@ documentation.
 - [4. Generate and configure the Unity preview](tutorial/04-generate-preview.md)
 - [5. Dynamic colors from GAMA attributes](tutorial/05-dynamic-colors.md)
 
+## Troubleshooting
+- [Troubleshooting](09-troubleshooting.md)
+
 ## Work in Progress
 - [Work in progress overview](work-in-progress/README.md)
 - [6. Configure species appearance](work-in-progress/06-configure-species.md)
 - [7. Apply preview settings in Play Mode](work-in-progress/07-apply-preview-settings.md)
 - [8. Optimize large simulations](work-in-progress/08-large-models-performance.md)
-- [9. Troubleshooting](work-in-progress/09-troubleshooting.md)
 - [User guide](user-guide/README.md)
 - [Technical documentation](technical/README.md)
 - [Runtime architecture notes](gama-unity.md)
diff --git a/Documentation~/images/tutorial/02-vr-generation-export-species-add.png b/Documentation~/images/tutorial/02-vr-generation-export-species-add.png
diff --git a/Documentation~/images/tutorial/02-vr-generation-export-species-final.png b/Documentation~/images/tutorial/02-vr-generation-export-species-final.png
diff --git a/Documentation~/images/tutorial/02-vr-generation-general-parameters.png b/Documentation~/images/tutorial/02-vr-generation-general-parameters.png
diff --git a/Documentation~/images/tutorial/02-vr-generation-property-name.png b/Documentation~/images/tutorial/02-vr-generation-property-name.png
diff --git a/Documentation~/tutorial/00-gama-model-preparation.md b/Documentation~/tutorial/00-gama-model-preparation.md
@@ -5,14 +5,16 @@ render the experiment.
 
 ## 0.1 GAMA Requirements
 
-Open your target VR-model in GAMA in the configuration of the screenshot below (ready to run). For explanations on how to install the Simple Unity Plugin, follow [this link](https://doc.project-simple.eu/gama/installation). 
+This tutorial requires a GAMA experiment converted into a Unity-compatible **vr_xp** experiment. This conversion is done with the **SIMPLE plugin**.
+
+Before continuing, make sure the **SIMPLE plugin** is installed in GAMA. Installation instructions are available [here](https://doc.project-simple.eu/gama/installation).
+
 > [!WARNING]
-> Don't forget to convert the experiment in "vr_xp", otherwise it will not work!!!
->
-> This step is explained [in this tutorial](https://doc.project-simple.eu/tutorials/Tutorial-Step-1)
+> Without the SIMPLE Unity plugin, you will not be able to convert the experiment to **vr_xp**, and Unity will not receive the simulation data correctly.
+
 
 ![Open a GAMA experiment](../images/tutorial/02-open-gama-experiment.png)
-_Exemple of an opened experiment in "Library models\Tutorials\Predator Prey\models"_
+_Example of the experiment that will be used throughout this tutorial_
 
 ## 0.2 Middleware Requirements
 

diff --git a/Documentation~/tutorial/02-first-experiment-launching.md b/Documentation~/tutorial/02-first-experiment-launching.md
@@ -1,9 +1,9 @@
 # 2. Run the GAMA Experiment in Play Mode
 
-It is time to run the first GAMA experiment in Unity with this package. In this
-tutorial, use the 6th **Prey Predator** model located in the following hierarchy from GAMA.
+It is time to run the first GAMA experiment in Unity with this package. For this
+tutorial, use the **6th prey Predator** model located in the following hierarchy from GAMA.
 
-![Prey Predator 7 model location](../images/tutorial/02-prey-predator-7-location.png)
+![Prey Predator 6 model location](../images/tutorial/02-prey-predator-7-location.png)
 
 This experiment is used throughout the rest of the tutorial because it covers the
 main features provided by the package: static background species, dynamic agents,
@@ -13,11 +13,53 @@ This chapter validates the baseline live workflow: Unity enters Play Mode,
 connects to `simple.webplatform`, receives the running GAMA simulation, and
 creates Unity objects from the GAMA agents.
 
-## 2.1 Steps
+> [!WARNING]
+> The original GAMA experiment cannot be used directly in Unity. It must first be converted into a `vr_xp` experiment with the SIMPLE Unity plugin.
+
+## 2.1 Convert the GAMA Experiment to `vr_xp`
+
+Before running the model in Unity, convert the GAMA experiment with the SIMPLE Unity plugin. During this conversion, each species that should appear in Unity must be explicitly exported.
+
+On the first **Definition of the VR experiment** screen, keep the default values and click **Next**.
+
+![VR experiment general parameters](../images/tutorial/02-vr-generation-general-parameters.png)
+
+On the **Export species** screen, do not immediately click **Next**. Select a species on the left, then click the **+** button under **Aspect in Unity**.
+
+![Export species add one by one](../images/tutorial/02-vr-generation-export-species-add.png)
+
+Keep the default property name and click **OK**.
+
+![Keep default Unity property name](../images/tutorial/02-vr-generation-property-name.png)
+
+Repeat this for each species that must be visible in Unity, for example:
+
+- `prey`
+- `predator`
+- `vegetation_cell`
+
+At the end, these species should be marked as exported.
+
+![Final exported species selection](../images/tutorial/02-vr-generation-export-species-final.png)
+
+The `generic_species` entry is abstract and is not required for the visual result. Exporting it is harmless, but it can also be ignored.
+
+> [!IMPORTANT]
+> If the species are not added on the **Export species** screen, the experiment may still start in GAMA and the Unity player may be created, but no simulation agents will appear in Unity.
+
+After this, click **Next**, keep the default values, set the number of players between `0` and `1`, then click **Finish**.
+
+For more details, this step is explained [in this tutorial](https://doc.project-simple.eu/tutorials/Tutorial-Step-1)
+
+## 2.2 Steps
+
+> [!WARNING]
+> These steps must be followed **exactly in the order shown below**.  
+> If you change the order, the Unity connection may fail!!!
 
 1. Make sure the scene was prepared with **GAMA > GAMA Panel > Setup Scene**.
 2. Start `simple.webplatform` with  `npm start`
-3. Open and run the **Prey Predator 7** experiment in GAMA.
+3. Open and run the **vr_xp** version of **Prey Predator 6** in GAMA.
 
 ![Windows Overview](../images/tutorial/02-windows-overview-gama-unity.png)
 4. Press **Play** in Unity.
@@ -35,10 +77,10 @@ while the experiment is running.
 
 ![Runtime live overview](../images/tutorial/02-runtime-live-overview.png)
 
-## 2.2 Expected Result
+## 2.3 Expected Result
 
 During Play Mode, Unity should connect to `simple.webplatform` and create live
-Unity objects from the agents received from the **Prey Predator 7** model.
+Unity objects from the agents received from the **Prey Predator 6** model.
 
 The imported agents are grouped by species in the Unity hierarchy.
 
@@ -47,7 +89,7 @@ The imported agents are grouped by species in the Unity hierarchy.
 At this stage, the important result is that the connection works and that GAMA
 agents are imported into Unity while the experiment is running.
 
-## 2.3 Into the Next Step
+## 2.4 Into the Next Step
 
 This is already useful: we now have a functional connection between GAMA,
 `simple.webplatform`, and Unity. The preys, predators and vegetation cells agents are imported and

diff --git a/Documentation~/tutorial/05-dynamic-colors.md b/Documentation~/tutorial/05-dynamic-colors.md
@@ -9,7 +9,7 @@ the `food` attribute of each `vegetation_cell`: instead of showing every grass
 cell with the same green, Unity can use a more or less intense green depending
 on the `food` value, like in the GAMA display.
 
-## Attribute Requirements
+## 5.1 Attribute Requirements
 
 The GAMA model must send the attribute in `add_geometries_to_send(...)`.
 
@@ -33,20 +33,40 @@ map<string, list<float>> prey_atts <- ["energy":: prey_energy];
 do add_geometries_to_send(prey, up_prey, prey_atts);
 ```
 
-## Continuous Example: Vegetation Food
+## 5.2 Continuous Example: Vegetation Food
 
-Use this mode when an attribute is numeric and should produce a gradual visual
-change.
+### 5.2.1 Attributes Sent By GAMA
+Unity can only use dynamic color attributes that are sent by GAMA through the websocket.
+In this experiment, the `send_geometries` reflex sends the agents and geometries to Unity. By default, `vegetation_cell` is sent without its `food` attribute:
+```gaml
+do add_geometries_to_send(vegetation_cell, up_vegetation_cell);
+```
+To make `food` available in Unity, collect the `food` values and pass them as the third argument of `add_geometries_to_send`:
+```gaml
+list<float> grass_food <- vegetation_cell collect each.food;
+map<string, list<float>> grass_atts <- ["food":: grass_food];
+do add_geometries_to_send(vegetation_cell, up_vegetation_cell, grass_atts);
+```
+The complete reflex should look like this:
+```gaml
+reflex send_geometries {
+	list<float> grass_food <- vegetation_cell collect each.food;
+	map<string, list<float>> grass_atts <- ["food":: grass_food];
+	do add_geometries_to_send(prey, up_prey);
+	do add_geometries_to_send(predator, up_predator);
+	do add_geometries_to_send(vegetation_cell, up_vegetation_cell, grass_atts);
+	do add_geometries_to_send(generic_species, up_generic_species);
+}
+```
+> [!NOTE]
+> The key `food` is the attribute name that will be used later in Unity. This attribute must already exist on the GAMA `vegetation_cell` agents.
 
-In this example, the `vegetation_cell` species receives a numeric `food`
-attribute. The goal is:
 
-```text
-low food  -> lighter/darker green
-high food -> stronger green
-```
+### 5.2.2 Using The Attribute In Unity
+
+After generating the preview, Unity can use the `food` attribute sent by GAMA through the websocket.
 
-Steps:
+In this tutorial, to display the numeric attribute `food`, you should follow the next steps in the Edit mode of a preview :
 
 1. Select the `Game Manager`.
 2. In the Inspector, find `vegetation_cell`.
@@ -62,6 +82,16 @@ The numbered close-up below shows the important controls:
 
 ![Dynamic food color settings legend](../images/tutorial/05-dynamic-color-food-settings-legend.png)
 
+In this example, the `vegetation_cell` species receives a numeric `food` attribute. The goal is:
+
+```text
+low food  -> lighter/darker green
+high food -> stronger green
+```
+
+> [!NOTE]
+> Unity can only use attributes that were explicitly sent by GAMA. If `food` is not included in `add_geometries_to_send`, it will not be available in the Unity dynamic color settings.
+
 1. Open the **Dynamic Color** foldout.
 2. Enable the override.
 3. Choose **Continuous** mode.
@@ -85,7 +115,7 @@ stronger than high values.
 
 ![Food dynamic color with invert enabled](../images/tutorial/05-dynamic-color-preview-food-result.png)
 
-## Discrete Colors For States
+## 5.3 Discrete Colors For States
 
 For attributes that represent a small set of states, use **Discrete** mode
 instead. This is useful for experiments with states such as:
@@ -102,7 +132,7 @@ state = recovered    -> green
 state = dead         -> black
 ```
 
-## Runtime Behavior
+## 5.4 Runtime Behavior
 
 Dynamic colors are applied per agent when Unity receives GAMA attributes.
 
@@ -113,7 +143,7 @@ They do not replace the static preview workflow:
 - if the attribute is missing or cannot be parsed, Unity keeps the static/GAMA
   color instead of crashing.
 
-## Result
+## 5.4 Result
 
 At the end of this chapter, Unity should be able to show both static species
 settings and per-agent attribute variations, such as vegetation cells becoming

diff --git a/Documentation~/work-in-progress/09-troubleshooting.md b/Documentation~/work-in-progress/09-troubleshooting.md
diff --git a/Documentation~/work-in-progress/README.md b/Documentation~/work-in-progress/README.md
@@ -5,4 +5,3 @@ These tutorial chapters are not part of the stable tutorial flow yet.
 - [6. Configure species appearance](06-configure-species.md)
 - [7. Apply preview settings in Play Mode](07-apply-preview-settings.md)
 - [8. Optimize large simulations](08-large-models-performance.md)
-- [9. Troubleshooting](09-troubleshooting.md)