Project Mobius

Crowd dataset playback and analysis in Unreal Engine 5.5

5,000 pedestrian agents replayed in real time with MASS Entity and Niagara rendering

Project Mobius is an Unreal Engine 5.5 application for loading pedestrian trajectory datasets, replaying them in 3D, and analyzing crowd movement with heatmaps, flow counters, and in-engine charts. Windows is the primary target; macOS support is partial.

Left: transparent geometry reveals agents on every floor — Right: GPU-driven 2D density heatmap

What It Does

• Loads pedestrian trajectories from JSON and HDF5, including Mobius and Juelich HDF5 datasets
• Replays imported timesteps through Unreal's MASS framework with Niagara-based pedestrian rendering
• Visualizes crowd density with floor heatmaps, between-floor counts, and related analytics widgets
• Provides interactive playback controls for play/pause, stepping, scrubbing, and time dilation
• Displays in-engine charts and overlays through the ImPlot and Slate UI stack
• Imports environment geometry from common formats such as FBX, OBJ, UDatasmith, IFC, and WKT
• Supports flow counters, agent inspection, screenshots, and pedestrian appearance/scalability controls

Visualization Modes

Solid and transparent geometry modes — navigate interior spaces alongside simulated pedestrians

Ground-level 2D density heatmap with colour-coded congestion — configurable via the Heatmap Settings panel

Pedestrian appearance controls: uniform (left) and diverse (right) agent rendering

Why HDF5

For larger trajectory files, convert JSON to HDF5 with the bundled json_to_hdf5_converter.py script. In one 5,000-agent sample, HDF5 cut load time from 21.29 s to 3.18 s and reduced memory use from 317,555 KB to 55,283 KB.

Format	Load time	Memory use
JSON	21.29 s	317,555 KB
HDF5	3.18 s	55,283 KB

More on supported formats, the conversion command, and the benchmark: docs/DATA-PIPELINE.md

Quick Start

Prerequisites

Common:

• Git
• Unreal Engine 5.5
• CMake 3.21 or newer
• Internet access during the first superbuild so HDF5 can fetch zlib-1.3.1 for compression support
• Python if you plan to use the JSON-to-HDF5 conversion script

Windows

• Windows 10 or 11
• Visual Studio 2022 with C++ tooling

macOS (Apple Silicon)

• macOS 11 or newer on Apple Silicon
• Xcode Command Line Tools
• Ninja

Build

Windows

git clone https://github.com/sir306/ProjectMobius.git
cd ProjectMobius/UnrealFolder/ProjectMobius
cmake -S . -B _superbuild -G "Visual Studio 17 2022" -A x64
cmake --build _superbuild --config Release --parallel

macOS (Apple Silicon)

git clone https://github.com/sir306/ProjectMobius.git
cd ProjectMobius/UnrealFolder/ProjectMobius
cmake -S . -B _superbuild -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build _superbuild --parallel

The superbuild compiles the vendored Assimp and HDF5 dependencies into the locations expected by the Unreal project. No separate HDF5 install is required.

Then open UnrealFolder/ProjectMobius/ProjectMobius.uproject, generate IDE project files if needed for your platform, and build ProjectMobiusEditor in Development Editor.

Full build, packaging, and automation notes live in docs/BUILD-AND-RUN.md.

Repository Overview

• UnrealFolder/ProjectMobius/: the Unreal project, superbuild, config, content, and source
• UnrealFolder/ProjectMobius/Source/: runtime modules for playback, UI, analytics, and core systems
• UnrealFolder/ProjectMobius/Plugins/: bundled HDF5 and Assimp integrations; OpenCV runtime is provided by Unreal's built-in OpenCV engine plugin
• UnrealFolder/ProjectMobius/BuildDocs/: packaging/staging folder; the superbuild mirrors selected canonical repo docs into BuildDocs/Docs/ for packaged builds
• docs/: repo-level documentation and wiki seed pages

Documentation

• Docs Index
• Build and Run
• Controls
• Architecture
• Data Pipeline
• Agent Sample Data
• Research and Publications
• UE Automation Guide
• Contributing
• Third-Party Licenses

Funders & Sponsors

Project Mobius is made possible with the generous support of:

License

Project Mobius source code is released under the MIT License.

See LICENSE for the project license and THIRD-PARTY-LICENSES.md for bundled dependencies, assets, and other third-party notices.

AI-Assisted Development

All modules, systems, and plugin integrations in Project Mobius were designed and written by the project contributors. This includes the architecture, algorithms, engine integration, and creative direction across the entire codebase.

AI coding assistants (OpenAI Codex, Claude, GitHub Copilot) were used as productivity tools during development — primarily for refactoring, documentation formatting, code cleanup, and boilerplate generation. A subset of pull requests were drafted with AI assistance; these represent a small fraction of the project's commits and many required further revision or were superseded by human-written improvements. Every AI-suggested change was reviewed, tested, and accepted by a human contributor before merging.

Contributors using AI tools must follow the AI Tool Usage Policy.