Skip to main content

Comprehensive Development Plan

Overview​

The Virtual Rodent project is being developed incrementally through feature-based development. Each major area of functionality is assigned to a dedicated feature branch so that team members can develop and test their work independently before integration.

The Sprint 1 development plan focuses on four major areas:

  1. Experiment interface and application controls
  2. 3D arena and environment
  3. Rat simulation and behaviour
  4. Stimuli, treatments, recording and data export

The completed features will be integrated into a single application for demonstration and further development.

Sprint 1 Development Structure​

                         Sprint 1
                            │
          ┌─────────────────┼─────────────────┐
          │                 │                 │
          ▼                 ▼                 ▼
   Experiment UI       3D Arena        Rat Simulation
   feature/experiment  feature/3d-     feature/rat-
   -ui                 arena            simulation
          │                 │                 │
          └─────────────────┼─────────────────┘
                            │
                            ▼
                    Stimuli & Recording
                    feature/stimuli-
                    recording
                            │
                            ▼
                     Integration
                            │
                            ▼
                    Sprint 1 Demo

The branches allow the team to work independently while maintaining a clear relationship between each feature and its responsibilities.

Muhammed — Experiment UI​

Branch: feature/experiment-ui

Objective​

Muhammed is responsible for the main application layout and the user interface used to configure and control experiments.

Planned Work​

The feature includes:

  • Main application layout
  • Experiment settings screen
  • Start simulation control
  • Pause simulation control
  • Reset simulation control
  • Simulation speed control
  • Experiment selection
  • Experiment editing
  • Experiment saving
  • Experiment loading
  • Integration of completed team features into the main application
  • Maintaining application stability after merges
  • Preparation of the Sprint 1 demonstration

Expected Outcome​

Users should be able to interact with the simulation through the application interface without needing to manually open or edit JSON configuration files.

The interface should provide a single location from which users can configure experiments and control the simulation.

Acceptance Criteria​

The feature is considered complete when:

  • The main application layout is functional.
  • Users can start, pause and reset the simulation.
  • Simulation speed can be changed.
  • Experiments can be selected and edited through the interface.
  • Experiments can be saved and loaded without manually editing JSON files.
  • Completed team features can be accessed through the main application.
  • The application continues to function after feature merges.
  • The Sprint 1 demonstration can be performed using the integrated application.

Huzaifa — 3D Arena​

Branch: feature/3d-arena

Objective​

Huzaifa is responsible for converting the current arena display into a simple three-dimensional environment.

Planned Work​

The feature includes:

  • 3D arena floor
  • Walls
  • Corridors
  • Shelter
  • Bridge
  • Named regions
  • Solid floor material
  • Rubber material
  • Wire mesh material
  • Wood chip material
  • Changeable material colours
  • Camera controls
  • Collision shapes
  • Openable and closable barriers
  • Arena boundary enforcement

Expected Outcome​

The simulation should provide a navigable 3D environment representing the experimental arena.

The arena should contain physical boundaries and barriers that interact with the simulated rat.

Acceptance Criteria​

The feature is considered complete when:

  • The arena is represented in 3D.
  • Required structural elements are present.
  • Regions can be identified by name.
  • Required materials can be applied to arena surfaces.
  • Material colours can be changed.
  • The camera can be controlled.
  • Collision shapes prevent invalid movement.
  • Barriers can open and close.
  • The rat cannot leave the arena.
  • The rat cannot pass through a closed barrier.

Ahmed — Rat Simulation​

Branch: feature/rat-simulation

Objective​

Ahmed is responsible for adapting the rat simulation to the 3D environment and implementing configurable behavioural characteristics.

Planned Work​

The feature includes:

  • Conversion of rat position from Vector2 to Vector3
  • Simple rat model
  • Rat size setting
  • Rat weight setting
  • Rat speed setting
  • Rat activity setting
  • Rat risk tolerance setting
  • Movement
  • Turning
  • Wall collision
  • Explorer behaviour preset
  • Balanced behaviour preset
  • Shelter Seeker behaviour preset
  • Deterministic movement based on simulation settings and random seed

Vector2 to Vector3 Conversion​

The existing two-dimensional position representation uses Vector2, which stores two coordinates:

Vector2
(x, y)

The 3D environment requires Vector3, which provides three coordinates:

Vector3
(x, y, z)

The conversion allows the rat to move within the 3D arena while maintaining a representation of its height and position.

Behaviour Presets​

The simulation will provide three predefined behavioural profiles:

  • Explorer — represents a rat with a stronger tendency to explore the environment.
  • Balanced — represents an intermediate behavioural strategy.
  • Shelter Seeker — represents a stronger preference for shelter and safer areas.

Determinism​

The rat simulation must remain reproducible.

Given the same configuration and random seed, the simulation should produce the same movement sequence even if the visual display speed is changed.

This ensures that simulation results depend on the experiment configuration rather than the rendering speed of the application.

Acceptance Criteria​

The feature is considered complete when:

  • The rat operates correctly in the 3D environment.
  • Position is represented using Vector3.
  • Rat characteristics can be configured.
  • Movement and turning operate correctly.
  • Collision with walls is handled.
  • Behaviour presets produce distinguishable behavioural strategies.
  • The same settings and random seed produce reproducible movement.
  • Changing display speed does not change the underlying simulation result.

Zidan — Stimuli and Recording​

Branch: feature/stimuli-recording

Objective​

Zidan is responsible for environmental stimuli, treatment conditions, experiment event recording and result export.

Stimulus System​

The system will support configurable:

  • Light sources
  • Odour sources
  • Sound sources

Each stimulus can have configurable properties including its location, range and intensity.

Stimuli can also be scheduled to activate at specific simulation steps.

This allows experiments to define controlled changes in the environment without manually interacting with the simulation during execution.

Treatment Conditions​

The experiment will support three treatment conditions:

  • No treatment
  • Placebo
  • Medicine

Treatment configuration includes:

  • Treatment type
  • Dose
  • Administration timing

Treatment events are recorded as part of the experiment results.

Recording​

The recorder captures relevant information about the simulation, including:

  • Rat position
  • Current region
  • Active stimuli
  • Treatment events
  • User interventions

Recording state changes at simulation steps allows the resulting data to be analysed after an experiment has completed.

Data Export​

Recorded results can be exported to:

  • JSON
  • CSV

JSON provides a structured representation of the complete experiment results, while CSV provides a convenient tabular format for external analysis.

Testing​

Automated tests are included for important recording and reproducibility requirements.

Tests verify that:

  • Stimuli activate at the expected simulation step.
  • State changes are recorded.
  • Treatment events are recorded.
  • Experiment results can be exported.
  • Repeated simulations using the same configuration and seed are reproducible.

Acceptance Criteria​

The feature is considered complete when:

  • Light, odour and sound sources can be configured.
  • Stimuli activate according to their schedules.
  • Treatment conditions can be distinguished.
  • Dose and administration timing are recorded.
  • Rat position and region information are recorded.
  • Active stimuli are recorded.
  • Treatment events are recorded.
  • User interventions are recorded.
  • Results can be exported to JSON and CSV.
  • Automated recording tests pass.
  • Determinism tests continue to pass.

Integration Plan​

The individual features are designed to work together as a single simulation.

Integration will follow the dependency relationships between the components.

3D Arena
   │
   ├──────────────► Rat Simulation
   │                       │
   │                       ▼
   │                Behaviour & Movement
   │
   └──────────────► Stimuli
                           │
                           ▼
                    Experiment State
                           │
                           ▼
                       Recorder
                           │
                           ▼
                     JSON / CSV


Experiment UI
      │
      ├── Controls simulation
      ├── Configures experiments
      ├── Loads/saves experiments
      └── Presents integrated features

The application interface will provide access to the functionality developed by the other team members.

Integration and Testing Process​

After a feature has been completed:

  1. The feature is tested independently.
  2. The feature branch is pushed to Gitea.
  3. A pull request is created.
  4. The implementation is reviewed.
  5. Existing automated tests are executed.
  6. The feature is merged into the main project.
  7. The integrated application is tested again.
  8. Any integration problems are resolved before continuing.

This process reduces the risk of a feature working independently but failing when combined with the rest of the simulation.

Reproducibility​

Reproducibility is an important development objective.

The simulation uses a defined random seed and fixed simulation time steps so that experiments can be repeated consistently.

The development plan therefore treats deterministic behaviour as a cross-cutting requirement rather than a feature belonging to only one component.

Changes to simulation logic should be tested to ensure they do not unintentionally alter deterministic behaviour.

Sprint 1 Demonstration​

The Sprint 1 demonstration will present the integrated application rather than individual features in isolation.

The demonstration should show:

  1. Launching the application.
  2. Viewing and interacting with the 3D arena.
  3. Configuring an experiment.
  4. Selecting behavioural settings.
  5. Configuring stimuli and treatment conditions.
  6. Starting and controlling the simulation.
  7. Observing the simulated rat.
  8. Recording experiment data.
  9. Exporting results.
  10. Demonstrating reproducibility through the automated tests.

Development Completion Criteria​

Sprint 1 development is considered successful when the individual features have been implemented, tested and integrated into a functioning application.

The integrated system should provide:

  • A functional 3D arena
  • A configurable simulated rat
  • Behaviour presets
  • Configurable environmental stimuli
  • Treatment conditions
  • Simulation controls
  • Experiment configuration
  • Experiment saving and loading
  • Behavioural recording
  • Data export
  • Automated testing
  • Deterministic simulation behaviour

The final Sprint 1 demonstration will verify that these components operate together as a coherent system.

AI Attribution: The preceding document was generated and edited with assistance from ChatGPT Web (GPT-5.6 Luna).