An immersive VR application for visualizing real-time flood simulations in urban environments. Built with Unreal Engine 5.3 and optimized for Meta Quest headsets, featuring AI-powered flood analysis and geospatial data integration.
- Overview
- Features
- Screenshots
- Requirements
- Getting Started
- Configuration
- Project Structure
- Core Components
- Supported Platforms
- Dependencies
- Development
- Contributing
- License
- Acknowledgements
VR-Flood-Sandbox is an Unreal Engine 5.3 project that provides an immersive virtual reality experience for flood simulation and visualization. The platform enables users to:
- Explore realistic 3D recreations of urban environments (e.g., Iowa City)
- Visualize real-time fluid dynamics and flood propagation
- Interact with flood scenarios using VR controllers
- Analyze flood impacts with AI-powered insights via OpenAI GPT-4
- Immersive VR Experience – Full VR support with hand tracking and eye tracking via OpenXR
- Real-Time Fluid Simulation – Dynamic water rendering using FluidFlux integration
- GeoJSON Flood Maps – Load and visualize flood extent data from geospatial sources
- AI-Powered Analysis – Screenshot capture with GPT-4 Vision integration for flood mitigation recommendations
- Dynamic Weather – SkyCreator plugin for realistic atmospheric conditions
- Vehicle Simulation – Chaos Vehicles plugin for flood evacuation scenarios
- Cross-Platform – Deploy to Meta Quest, Windows VR, and desktop
- VR Headset: Meta Quest 2/3/Pro (standalone or PC VR)
- PC (for development): Windows 10/11, 16GB+ RAM, RTX 2070+ GPU
- Unreal Engine 5.3
- Visual Studio 2022 with C++ game development workload
- Android Studio (for Quest deployment)
Important
Asset Availability: This repository does not include the .umap level assets (Iowa City environment and configuration screen). For the complete version with all map assets, please contact the authors.
Why?
- Legal & Compliance: Flood maps and city models may have licensing restrictions or institutional data-use agreements
- Repository Size:
.umapfiles can be hundreds of MB, making cloning slow and Git diffs impractical
git clone https://github.com/uihilab/VR-Flood-Sandbox.git
cd VR-Flood-Sandbox- Launch Unreal Engine 5.3
- Open
VR_VIS.uproject - Allow shader compilation to complete
Before using AI analysis features, add your OpenAI API key:
- Open
Source/VR_VIS/DataAnalysis.cpp - Replace
YOUR_OPENAI_API_KEY_HEREwith your actual API key - Rebuild the project
- Editor: Press Play in the Unreal Editor
- VR Preview: Use VR Preview mode with a connected headset
- Quest Standalone: Package for Android and deploy via Meta Quest Developer Hub
The project uses OpenAI's GPT-4 Vision API for flood analysis. To enable:
- Obtain an API key from OpenAI Platform
- Update the key in
DataAnalysis.cpp - The system captures screenshots and sends them for AI-powered flood mitigation recommendations
Configure signing in Config/DefaultEngine.ini:
[/Script/AndroidRuntimeSettings.AndroidRuntimeSettings]
KeyStore=UE.keystore
KeyAlias=DistroKey
KeyStorePassword=YOUR_PASSWORDVR-Flood-Sandbox/
├── Config/ # Engine and platform configuration
├── Content/
│ ├── Assets/ # 3D models, materials, textures
│ ├── Blueprints/ # Blueprint classes and logic
│ ├── FluidFlux/ # Fluid simulation assets
│ ├── Levels/ # Map files (Iowa City, Config Screen)
│ ├── UI/ # User interface widgets
│ ├── VFX/ # Visual effects
│ └── VRTemplate/ # VR interaction framework
├── Plugins/
│ ├── MetaXR/ # Meta Quest integration
│ └── MetaXRPlatform/ # Oculus platform services
├── Source/VR_VIS/ # C++ source code
│ ├── DataAnalysis.cpp # AI screenshot analysis
│ ├── Floodmap.cpp # GeoJSON flood visualization
│ ├── SimConfiguration.cpp # Simulation settings
│ └── PlayerChar.cpp # VR player controller
└── VR_VIS.uproject # Project file
Captures in-game screenshots and sends them to OpenAI GPT-4 Vision for flood mitigation analysis.
Loads GeoJSON polygon data and renders animated flood extents in the 3D environment.
Manages simulation parameters including flood levels, weather conditions, and time of day.
VR player pawn with motion controller support, teleportation, and interaction capabilities.
| Platform | Status |
|---|---|
| Windows (Desktop) | ✅ Supported |
| Windows (VR - SteamVR/OpenXR) | ✅ Supported |
| Meta Quest 2/3/Pro | ✅ Supported |
| Android | ✅ Supported |
| Linux | 🔧 Experimental |
- Unreal Engine 5.3
- OpenXR – VR runtime
- Meta XR SDK – Quest integration
- FluidFlux – Fluid simulation
- SkyCreator – Dynamic weather
- OpenAI API – AI analysis (optional)
# Generate project files (Windows)
"C:\Program Files\Epic Games\UE_5.3\Engine\Build\BatchFiles\GenerateProjectFiles.bat" VR_VIS.uproject
# Open in Visual Studio
start VR_VIS.sln- File → Package Project → Android
- Select ASTC texture compression
- Deploy APK via
adb installor Meta Quest Developer Hub
Contributions are welcome! Please open an issue or pull request. For major changes, please open an issue first to discuss what you would like to change.
This project is licensed under the MIT License - see the LICENSE file for details.
For questions, or suggestions, please contact the authors or open an issue on the GitHub repository. You can also reach out to the Tulane Hydroinformatics Lab at https://hydroinformatics.tulane.edu/.
This project is developed by the Tulane's Hydroinformatics Lab: https://hydroinformatics.tulane.edu/.
Gonzalez, E., Sajja, R., Sermet, Y., & Demir, I. (2025). FloodSim Sandbox: An Immersive Interactive Simulation Framework for Urban Flood Risk Management.