simple.NSTDA.gama2

GAMA models for BiodiVRestorer VU#2 - User Documentation

Overview

About BiodiVRestorer VU#2

The BiodiVRestorer Virtual Universe version 2 (VU#2)

The Forest Monitoring model: simulates an interactive game in which players protect seedlings
from three major threats wildfires, alien species, and weeds over a 2-year period,
so that the seedlings collected from the Forest Trails model in VU#1 can grow according to the forest restoration plan.
This model is integrated with:
- Seedling Guardian Console (optional) : a web application that serves as a decision-support system. It helps players control the three threats and provides a dashboard displaying each team’s total score, number of coins, a tree growth stage overview, a stacked view of remaining trees by growth state per round, and the number of remaining trees by species.

Learning Objectives

Raising awareness about biodiversity loss, fostering an understanding of its causes and impacts.
Providing immersive VR experiences on best practices for forest restoration, specifically targeting youth as the future generation.

Target Audience

Age group: 15-18 Years old
Educational level: Secondary School
Language(s) available: Thai, English

System Requirements

Server

GAMA Platform [GAMA Platform - 2025.6.4]
- With the additional VR plugin from this link.
SIMPLE Webplatform
Seedling Guardian Console (optional)
- Python version 3.12
- Library Requirement
  - uvicorn
  - fastapi
  - websockets

VR Headsets

Meta Quest 3
BiodiVRestorer2.apk latest release

Installation Guide

Unity VR Application Installation

Download BiodiVRestorer2.apk from download location to your computer.
Connect the headset to your computer with a USB-C cable and allow data access.
Install the APK using SideQuest.
On the headset, go to Apps Unknown Sources and launch BiodiVRestorer2.

Web Platform Access

Open your web browser
Navigate to Web Platform URL

Getting Started

Starting the Virtual Universe (VU)

According to the flowchart above, these are the steps for preparing the system and equipment before starting the game.
The details for each step are as follows:

1. Open the Web platform

Open a terminal and run the command below to generate a URL for the web platform.
Then copy that URL and open it in your web browser.

 cd /path/to/simple.webplatform/
 npm start

Open the web platform and select Forest Monitoring

2. Accessing the game (VR)

2.1 Launch the VR application

After the player puts on the VR headset, make sure it is connected to the same Wi-Fi network as the computer.
Then, select the “BiodiVRestorer 2” application on the headset.
2.2 On the first screen, players can change the language (Thai or English), then select the Online version.
2.3 On the next screen, players must enter the IP and Port of the host machine running the Web Platform and GAMA.
2.4 The player is then taken into the game

3. Connecting the VR

3.1 Check VR connections from the web platform

Click the VR headset icon on the webplatform to check the connection status of each player.

3.2 Once you have confirmed that all players are connected, you can click the button to call the Forest Monitoring Simulation.

Game Play

The flowchart above summarizes the gameplay steps, which are described below.

Check that all players are ready, then press on the web platform to start the tutorial.

1. Strat the tutorial

1.1 Player watches a forest-change animation
1.2 Plant trees and apply fertillizer together
1.3 Practice managing three threats: Fire, Alien, Grass

Check that everyone is ready, then press on the web platform to start protecting seedlings

2. Strat protecting seedlings over 2 years, monitor them on smartphones and record the data

When players enter the main game, they walk around the forest and use tools to remove three threats: grass (weeds), alien species, and fire. Each plot lasts 4 minutes, and players have limited coins, spent via the web application to reset threats, so they must use them wisely. After each round, the VR headset is passed to the next player until everyone has played, with the number of rounds matching the number of players (up to six per group).

3. My Forest after 20 years

At the end of each game round, players can press the “Show Result” button to view their own outcomes from protecting the forest. The result screen presents one of three possible scenarios, depending on the player’s final score.

Basic Controls

For GAMA Models

Users interact with the GAMA interface mainly by left-clicking on the available control buttons:

Play / Pause experiment (keyboard shortcut: Command + P or Control + P)
Close experiment (keyboard shortcut: Shift + Command + X or Shift + Control + X)
Reset button — used when a player loses connection
Reload button — used when a player loses connection

For Unity VR Games

Movement:
- Use the left thumbstick to move forward and backward.
Interaction:
- Use the right trigger button (index finger) to fire the crossbow.
- Use the right grip button (middle finger) to pick up or grab objects.
Menu Access:
- Press the Meta / Oculus button on the right controller to open the main menu and exit the game.

For Web Platform

Play / Pause Button
Close Button
VR headset Status Checking
See the figure Check VR connections

For Web application

For Student

Re-Connect Button

If the web application disconnects from GAMA, click the “Re-connect” button to connect again.
Reset Threat coins

These buttons use coins to reset different threats. The coins in the system will be deducted according to the type of threat you reset:

2.1 Reset Grass: costs 1 coin
2.2 Reset Alien: costs 2 coins
2.3 Reset Fire: costs 3 coins

For Teacher

Numeric stepper
This field is used to set the number of coins for each team.
The teacher can either type a value directly or use the + and – buttons to increase or decrease the number.
Reset all to zero button
Click “Reset all to zero” to set the coin values of all teams back to 0.
Submit Button
Click “Submit” to confirm the updated values and send them to the system (this also unlocks the links for each team).
Links for each team After clicking Submit, the web application links for all teams will appear, including:

Link: a direct link for each team that can be opened immediately.
Copy button: copies the team’s link to the clipboard so it can be opened in a browser.
Open button: opens the team’s link in a new browser tab.
QR button: shows a QR code for the team’s link, which each team’s representative can scan to open their team page.

Using the Virtual Universe

Main Features

Learning Modules

Module 1: Forest Monitoring (With VR)
- Duration: approximately 40 - 60 minutes
- Objectives:
  - Help learners understand why the first few years of seedling growth are critical for forest restoration.
  - Practice making decisions under limited resources (coins) to manage threats.
- Activities:
  
  During the session, one student wears the VR headset and enters the Forest Protection mode,
  walking around the forest, using tools to remove three types of threats (grass, alien species, and fire),
  and managing a limited number of coins to protect the seedlings. In each round,
  the other team members observe the gameplay and record the round score and
  the number of remaining trees for each species using the web dashboard and a worksheet.
  At the end, the team reviews their notes together with the dashboard visualizations to
  reflect on their strategies and how their decisions affected forest restoration.

Interactive Elements

Environmental Indicators:

Time Indicator

1.1 Yearly indicator
- Rainy season: the rainy season is used as a visual and audio cue for the time of year.
  When the rainy season begins, players can hear rain, thunder, and lightning sounds, and see rainfall in the forest.
1.2 In-game time
- 4 minutes (2 years): the play time for one plot is 4 minutes,
  which represents 2 years of seedling monitoring and forest restoration in the simulation.
- 1 minute remaining (sound): when there is only 1 minute left in the round,
  a voice effect saying “1 minute remaining” is played to alert the player that the round is about to end.
  
  1min_remain.mp4
Score

Players can observe the surrounding forest environment, which appears in one of three conditions depending on their current score. In each round, the maximum score is 300 points, and the surrounding forest environment is divided into three levels based on score ranges as follows:

Level 1 of forest degradation:
This is the healthiest condition of the forest, with high biodiversity and lush vegetation.
The player’s current score is in the range [240–300].

Level 2 of forest degradation:
This represents a moderately healthy forest, but the forest is not as rich or dense as in Level 1.
The player’s current score is in the range [150–240).

Level 3 of forest degradation:
This is the most degraded condition. The forest is open and sparse,
with very low biodiversity, and players can see signs of disturbance such as smoke from fires.
The player’s current score is in the range [0–150).

Threat
- Fire
  - When a forest fire occurs, the player’s VR view shows floating fire particle effects around the edges of the screen, alerting them that a fire has started.
  - At the same time, a burning fire sound effect is played to further notify the player of the ongoing fire.
    
    fire_sound.mp4
  - In the game, forest fires can appear in three main forms:
    - a campfire
    - fireballs
    - flames burning on trees
  - When the player uses the water gun to extinguish the fire, a progress bar appears, indicating how close they are to successfully putting out the fire.
- Grass and Alien species
  - When a tree is exposed to more than 4 threats (including both grass and alien species),
    an icon of a “startled tree” appears to alert the player to come and protect that tree.
  - When a tree is exposed to more than 6 threats, the tree shows a “crying tree” icon
  - At the same time, a “help” voice effect is played, as illustrated in the clip below.
    This continues until the player removes the threats; if they do not arrive in time, the tree will die.
    
    icon_tree_cry.mp4
  - When the player removes weeds or alien species, a cutting sound effect is played to indicate that
    the grass or alien species has been successfully cleared.
    
    cut_alien.mp4

In-Game Activities:

Handling the three types of threats:
- Extinguishing fire
  Raise your left arm and look at it,
  and use your right middle finger to pick up the water gun. Then, use your left index finger to spray water and extinguish the fire.
- Removing alien species
  Raise your left arm and look at it. You will see two tools attached to your arm. Use your right middle finger to grab the harrow. Then, use the harrow to remove the alien species, being careful not to hit any seedlings.
- Removing grass (weeds)
  Use your left thumb to move towards the grass. Once you are close enough, use your right middle finger to pull out the grass.
Agents:

Map: It displays the playing area, showing the locations of trees and the positions of different threats (grass, alien species, and fire) around the seedlings.
Tree: Each tree (or seedling) is an agent with its own growth state. Trees can grow, survive, or die depending on how well players protect them from threats during the game. Trees are represented by different colors:
- Green: newly planted trees that can still grow.
- Yellow: large, existing trees in the plot that can no longer grow.
- Gray: a tree for which at least one team has caused the tree at that position to die; it turns black when all teams have caused the tree at that position to die.
Player: Represents the team member who is currently wearing the VR headset. Each player is shown as a colored circle (red, green, yellow, blue, black, or white). The cone shape extending from the player indicates the direction they are facing.

Data Visualization:
GAMA
- Graph
  - Total Scores: a horizontal bar chart showing the total score of each team.
- Map

Tutorial zone:
The area where players practice basic skills before the main game,
such as picking up tools to remove threats and pulling out grass by hand.
Playing area:
The main forest area where seedlings, existing trees,
and threats (grass, alien species, and fire) are located during the game.
Remaining time:
A timer showing how much time is left in the current round.
Threat icons:
Icons indicating the locations and types of threats (grass, alien species, and fire) on the map.
Reset button:
Used when a player is disconnected. It sends the current game state back to Unity,
for example to send the player to the tutorial again,to start the game, or to stop the game.
Typically, the Reset button is pressed after the Reload button.
Reload button:
Used when a player is disconnected to send them back to the IP input screen,
so they can reconnect and enter the game again.
Q1 – Pre-game questionnaire:
Used to check whether the player has completed the pre-game questionnaire.

Green circle = questionnaire completed
Red circle = questionnaire not yet completed

Q2 – Post-game questionnaire:
Used to check whether the player has completed the post-game questionnaire,
in the same way as Q1 (indicated by a green or red circle).
- Web application
  - For Student
    - Team Name:
      In the first section, the interface displays each team’s name and indicates which plot they are currently playing.
    - Team score:
      - Max score: is the highest total score that a player can achieve.
      - Current score: the score of the current round for each team, based on how well they protected the forest and seedlings from different threats.
    - Team coins: Displays the number of coins that each team has. Coins are used as a limited resource to remove threats.
      - Initial coins: the number of coins given to the team at the start of the game
      - remaining coins: the number of coins left after the team has spent them on actions such as resetting grass, alien species, or fire.
    - Number of remaining trees by species:
      A horizontal bar chart showing how many trees are still alive, grouped by species.
    - Tree Growths Stage Overview:
      A bar chart showing the number of trees in each growth stage (e.g., Stage 1, Stage 2, Stage 3).
      This helps students see the overall structure of the forest: how many trees are still young, how many are in the middle stage, and how many have reached the final growth stage.
    - Stack Remaining trees by growth state round:
      A stacked bar chart showing the proportion of remaining trees in each plot, separated by growth stage (Stage 1–3).
      This allows students to quickly see, for each plot, what percentage of trees are still alive and in which growth stages.
  - For Teacher
    1. Team score: (left)
      A summary view of the total scores for all teams. This allows the teacher to compare team performance, discuss strategies, and use the scores as a basis for reflection or debriefing.
    2. Team coins: (right)
      An overview of the initial and remaining coins for each team. This helps the teacher see how students used their resources, and how resource management affected their final outcomes.

Game Progression

Tree Growth Stages

The tree growth in this model is based on a logistic growth equation and is divided into three stages:

Stage 1 – Seedling
Young seedlings at an early growth stage.
Stage 2 – Intermediate growth
Trees in a medium growth stage.
Stage 3 Best 2-year growth
Trees that have reached their best possible growth within the 2-year simulation period.

Achievement System

Progress tracking
- GAMA
  A real-time graph displaying the total scores, as shown in the total score graph
- Web application
  - For student Other team members can track the game progress through the web application, which displays:
  - For teacher
    A leading board that displays each team’s total score and remaining coins.
Coin Spending
- Seedling Guardian Console (web appication)
  Within the Forest Monitoring session, each team walks around the forest to protect seedlings from all three types of threats.
  Sometimes, players may not be able to handle every threat in time, so the Seedling Guardian Console is provided
  as a support tool to reset threats in the forest at the cost of team coins. The number of coins spent depends on
  the type of threat—for example, resetting all fires in the forest costs 3 coins
  from that team’s total (as shown in the Reset Threat coins section above).

Educational Features

Learning Assessment

Pre-activity questionnaire
After completing the tutorial practice, a short in-game UI questionnaire with two questions is shown for students to answer.
In-activity checkpoints
During gameplay, the views shown in GAMA and the Seedling Guardian Console display how each team responds to the three threats wildfires, alien species, and weeds along with real-time team scores, remaining coins, tree growth stages, and other described in the Achievement System. These indicators act as in-activity checkpoints, helping teachers and students see, while the game is still running, how well players prioritize threats, manage resources, and protect the forest.
Post-activity evaluation
After playing, students complete a post-game questionnaire to reflect on their experience and what they have learned.
Progress reports for educators
At the end of the game, each player sees one of three possible forest outcomes, based on their final score and the level of forest degradation. These outcomes can be used by educators to discuss performance and learning results.
Shared scenarios
All teams experience the same forest scenario and identical threat settings, which not only makes it easy to compare strategies and outcomes across groups, but also allows the shared scenario to reveal how each team chooses to respond to fires or alien outbreaks, why some forests end up healthier than others, and how students might change their strategy if they played the same scenario again.

Collaborative Features

Group challenges
- Competetion
  During gameplay, both students and teachers can observe each team’s total score in GAMA.
  The teacher’s web application (Seedling Guardian Console) also shows each team’s score and remaining coins in real time,
  which can stimulate competition between teams. Even in this competitive environment,
  each team still needs to discuss internally how to respond to wildfires, grass, and alien species,
  turning competition into a driving force for collaboration within the group.
- Collaboration
  While playing, students practice teamwork by recording data after each round (e.g., scores and remaining trees by species) and making joint decisions on how to spend coins to remove threats. The coin system on the Seedling Guardian Console lets team members who are not wearing the VR headset actively help by managing coins and choosing when to reset threats. When the VR view is cast onto a shared screen, the whole team can watch the same scene, discuss what is happening in the forest, and adjust their strategy together in real time.

Educational Resources

Work sheets
- Activity worksheets are provided for students to record information during gameplay,
  including each player’s score for the current round and the number of remaining trees for each species.
External links to resources

Teacher's guide availability

Troubleshooting

Common Issues and Solutions

VR-Specific Issues

Problem: One headset turned-off during a game
Solution:

Turn it back on
Reopen the game
Auto-magically reconnecting

Problem: Unable to connect to GAMA during a game
Solution:

Reopen the game
Restart GAMA or Middleware

Frequently Asked Questions

General Questions

Q: Can I use this offline?
A: No.

Q: How do I save my progress?
A: No.

Q: Is this available in my language?
A: Available in Thai and English.

Technical Questions

Q: What VR headsets are supported?
A: Meta Quest 3 only.

Q: Can I run this on a tablet/mobile device?
A: No.

Educational Questions

Q: How long does each session take?
A: The forest monitoring session takes approximately 40–60 minutes.

Q: Can teachers monitor student progress?
A: Yes. Teachers can monitor progress in real time through the web application,
which shows each team’s scores, team’s coins

Bug Reporting

Please report bugs through: GitHub issues page

Name		Name	Last commit message	Last commit date
Latest commit History 60 Commits
Pictures		Pictures
forest_monitoring		forest_monitoring
gama_ws_python		gama_ws_python
gif		gif
.built_in_models_1754407967359		.built_in_models_1754407967359
.gama_application_workspace		.gama_application_workspace
.gitignore		.gitignore
README.md		README.md

project-SIMPLE/simple.NSTDA.gama2

Folders and files

Latest commit

History

Repository files navigation