diff --git a/Documentation~/images/tutorial/02-vr-generation-export-species-add.png b/Documentation~/images/tutorial/02-vr-generation-export-species-add.png new file mode 100644 index 0000000..f71ff6b Binary files /dev/null and b/Documentation~/images/tutorial/02-vr-generation-export-species-add.png differ diff --git a/Documentation~/images/tutorial/02-vr-generation-export-species-final.png b/Documentation~/images/tutorial/02-vr-generation-export-species-final.png new file mode 100644 index 0000000..3d985dc Binary files /dev/null and b/Documentation~/images/tutorial/02-vr-generation-export-species-final.png differ diff --git a/Documentation~/images/tutorial/02-vr-generation-general-parameters.png b/Documentation~/images/tutorial/02-vr-generation-general-parameters.png new file mode 100644 index 0000000..fe27591 Binary files /dev/null and b/Documentation~/images/tutorial/02-vr-generation-general-parameters.png differ diff --git a/Documentation~/images/tutorial/02-vr-generation-property-name.png b/Documentation~/images/tutorial/02-vr-generation-property-name.png new file mode 100644 index 0000000..fe40738 Binary files /dev/null and b/Documentation~/images/tutorial/02-vr-generation-property-name.png differ diff --git a/Documentation~/tutorial/00-gama-model-preparation.md b/Documentation~/tutorial/00-gama-model-preparation.md index f9a3c8b..2280c1d 100644 --- 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 index 6473974..9976390 100644 --- a/Documentation~/tutorial/02-first-experiment-launching.md +++ b/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 diff --git a/Documentation~/tutorial/05-dynamic-colors.md b/Documentation~/tutorial/05-dynamic-colors.md index 9a417f9..17073ed 100644 --- 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,7 +33,7 @@ map> 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