Develop

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
 

Documentation~/tutorial/02-first-experiment-launching.md

@@ -1,9 +1,51 @@
 # 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)
+
+> [!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**.
 
 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 +55,11 @@ 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
+## 2.2 Steps
 
 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

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,7 +33,7 @@ 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.
@@ -85,7 +85,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 +102,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 +113,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