Motivated Technology Stack

Overview

RODENT uses this stack to support a researcher-facing platform, a deterministic virtual workspace, project access and later model integration. Some parts were project constraints, not inventions we selected from scratch.

The selected technologies are:

Technology	Purpose
Godot 4.7.1	3D simulator, deterministic kernel and graphical interface
GDScript	Simulation and Godot application logic
HTML, CSS and JS	Authenticated web portal and embedded simulator host
JSON	Versioned experiment configuration and result export
CSV	Tabular experiment data export
Python	Local web backend and headless simulation client
SQLite	Local development persistence
Supabase	Hosted authentication, Postgres and access control
Vercel	Hosted researcher portal
PyTorch	Possible future machine learning integration
Git and Gitea	Version control and team collaboration
Docusaurus	Project documentation
Cloudflare Pages	Public documentation hosting
Open-Meteo	External weather lookup for illustrative environment suggestions
Inter	Shared website and Godot interface font

Godot 4

Godot 4 is the primary framework used to develop the Virtual Rodent simulation.

Godot was treated as a project prerequisite. It still makes sense for this design because one engine can render the 3D arena, keep scene objects editable and run kernel tests or a Python-controlled process without rendering. Its scene and node architecture helps separate the application shell from simulation rules.

Godot supports the project's requirements for:

• Real-time simulation
• 3D environments with a two-dimensional floor movement model
• User interaction
• Rendering and visualisation
• Input handling
• Scene management
• Automated headless testing

The project uses Godot's plugin-oriented structure to separate major areas of functionality.

GDScript

GDScript is used as the primary programming language within the Godot project.

It was selected because it is tightly integrated with Godot and provides direct access to the engine's simulation, scene, rendering and input APIs.

Using GDScript also reduces the complexity of developing the simulation compared with introducing an additional programming language into the core Godot application.

The project uses GDScript for components including:

• Simulation control
• Simulation timing
• Arena behaviour
• Stimulus management
• Treatment events
• Recording
• Automated tests
• User interface logic

JSON

JSON is used for experiment presets and configuration data.

JSON was selected because it is human-readable, widely supported, easy to generate programmatically, and suitable for representing structured experimental parameters.

A preset can contain information such as:

• Simulation settings
• Random seed
• Fixed time step
• Arena configuration
• Stimuli
• Stimulus schedules
• Treatment conditions
• Experimental parameters

This allows experiments to be configured independently from the simulation code.

For example, the project uses experiment preset files such as:

presets/mcsf_sprint_one.json

Using external configuration also improves reproducibility because the parameters used for an experiment can be stored and reused.

CSV

CSV is used as a format for exporting recorded simulation data.

CSV was selected because it is simple, portable, and supported by common data-analysis tools. It allows simulation results to be inspected in spreadsheet software or processed by Python-based analysis tools.

Potential recorded information includes:

• Simulation step
• Simulation time
• Agent position
• Current region
• Active stimuli
• Treatment events
• Interventions

Web Portal, Python and Data Services

The browser portal uses HTML, CSS and JavaScript. It provides registration, login, project creation, project-lead-managed team access and a full-size host for the embedded Godot web export. The portal and Godot exchange same-origin postMessage commands and state updates.

Python is used in three implemented areas. The local development backend provides authentication, roles, experiments and replays using SQLite. The headless client can also reset, step, observe, act, load and close a Godot simulation over localhost TCP. Since Sprint 3, the Python SDK (rodent_sdk) builds on that client so researchers can create, run and save experiments from Google Colab without the 3D view. It talks to the same Supabase project as the website; see Python SDK and Headless API.

Hosted deployments use Supabase Auth and Postgres with Row Level Security. The browser receives only the project URL and publishable key. The service-role key is not placed in the client. The researcher portal is deployed through Vercel.

The implemented control and export paths are:

Web Portal -> embedded Godot simulator
Python client -> headless Godot simulator
Python SDK (Colab) -> headless Godot simulator -> Supabase -> website Review
Godot recorder -> JSON / CSV -> external analysis

PyTorch

PyTorch is planned as part of the project's machine learning integration.

PyTorch provides a mature ecosystem for developing and training machine learning models and is widely used in research environments.

The simulation can therefore act as a controlled source of behavioural data that can later be supplied to machine learning models.

PyTorch is considered a future integration rather than a dependency of the current core simulation.

Git

Git is used for version control.

Git provides:

• Feature branches
• Commit history
• Change tracking
• Branch merging
• Rollback capabilities
• Individual contribution history

The team follows a feature-based GitHub Flow methodology while using Gitea as the repository host.

Gitea

Gitea is used to host the project's Git repositories and support team collaboration.

The team uses Gitea for:

• Repository hosting
• Feature branches
• Pull requests
• Code review
• Collaboration
• Version history

Using Gitea also provides a central location from which the team's development history can be reviewed.

Docusaurus

Docusaurus is used to build the project's documentation website.

Docusaurus was selected because it provides a documentation-focused framework based on Markdown and supports:

• Structured documentation
• Sidebar navigation
• Version control through Git
• Custom React components
• Static site generation

This allows the documentation to remain within the project's version-controlled development workflow.

Cloudflare Pages

Cloudflare Pages hosts the generated Docusaurus documentation.

It provides static hosting suitable for a documentation website and allows the generated site to be made publicly accessible.

The deployment workflow is:

Docusaurus Markdown
        ↓
Docusaurus Build
        ↓
Static Website
        ↓
Cloudflare Pages
        ↓
Public Documentation

This satisfies the requirement for the project documentation to be publicly available without requiring visitors to have a Gitea account.

Third-party code and services

The detailed inventory, resolved versions, licences, attribution requirements and release checklist are maintained in Third-Party Code and Services.

We use external work for specific purposes rather than copying large parts into our source tree. Godot supplies the engine and web runtime; Supabase JS supplies browser access to hosted authentication and data; Open-Meteo supplies weather observations and forecasts; Docusaurus and its npm dependencies build this documentation; and Vercel and Cloudflare Pages host the two sites. The website currently loads Supabase JS from a major-version CDN path, so a reproducible release should pin and test an exact dependency version. CI separately pins the Python coverage tool.

The Inter font is bundled in the application, and its SIL Open Font License text is kept at assets/fonts/OFL.txt. The documentation site also uses the same font and keeps a copy of that notice. PyTorch is not bundled or used by the current simulator. The team should keep an inventory of third-party package versions, source URLs, licences and any attribution requirements with the final release; this paragraph is not a claim that every dependency has already completed a licence audit.

For the actual local and hosted data routes, see APIs and data. Weather-derived brightness and sound are illustrative configuration suggestions, not calibrated exposure models.

Overall Technology Architecture

The technologies work together as follows:

Browser Portal -> Supabase Auth/Postgres
       |
       v
Embedded Godot 4 Simulator -> JSON / CSV results

Python Client -> Headless Godot 4 Simulator

JSON / CSV -> Python analysis -> possible future PyTorch work


Development & Documentation
────────────────────────────────────────

Git → Gitea
       │
       ├── Source Code
       ├── Tests
       └── Documentation

Docusaurus
       │
       ▼
Cloudflare Pages
       │
       ▼
Public Documentation

Technology Selection Rationale

The overall stack was selected to minimise unnecessary complexity while keeping the system extensible.

Godot provides the simulation and visualisation layer, GDScript provides direct control over the simulation, JSON provides reproducible experiment configuration, and CSV provides portable data export.

Python currently supports the local backend, headless control and the Python SDK used from Google Colab. Python also provides a path toward statistical analysis, while PyTorch remains a possible future integration and is not a core simulator dependency.

Git and Gitea support collaborative development, while Docusaurus and Cloudflare Pages provide a maintainable and publicly accessible documentation solution.

---

AI Attribution: This document was drafted and edited with AI assistance, including ChatGPT and OpenAI Codex. The team reviewed it against the implemented project.