Predator-Prey Ecosystem Simulator

A JavaFX predator-prey simulation built in BlueJ — featuring genetics, disease, and multi-species ecosystems

This is a grid-based ecosystem simulation developed as a team coursework project (CW3) at King's College London. A 100×80 field is populated with three predator species (Lion, Tiger, Leopard) and two prey species (Flamingo, Sheep), all living alongside regrowable Plants. Each animal carries a 14-digit genetic code encoding traits such as breeding age, lifespan, metabolism, and disease resistance. Genes are inherited and mutate across generations, driving emergent population dynamics. The simulation is built in Java using JavaFX for rendering and was developed in BlueJ.

Demo

Project Context

Type	Coursework project (CW3)
Institution	King's College London
Original repository	Private / institution-hosted (GitHub KCL)
This repository	Public portfolio version
Version	2.0 — March 2025

My Contribution

Class	Role
Predator.java	Sole author — hunting logic, competition, gene-driven metabolism, priority-based acting
Prey.java	Sole author — plant foraging, movement, gene-driven metabolism
Simulator.java	Co-author (led) — simulation loop, population initialisation, species priority ordering
SimulatorView.java	Co-author (led) — JavaFX GUI: grid rendering, legend, step counter, population stats panel
FieldStats.java	Co-author (led) — real-time population stats with per-species colour-coded TextFlow
Animal.java	Co-author — gender system, DeathReason enum, 14-digit gene encoding, disease logic
Field.java	Co-author — dual-layer grid (animals + plants), adjacency queries
FieldCanvas.java	Co-author — JavaFX Canvas wrapper for drawing grid cells
Counter.java	Co-author — per-species count accumulator used by FieldStats
Location.java	Co-author — grid coordinate model
Randomizer.java	Co-author — seeded RNG for reproducible runs

This was a collaborative team project. The above reflects the areas where I had primary responsibility.

Features

• Three predator species (Lion, Tiger, Leopard) with priority-based acting order — stronger predators act first each step
• Predator competition — predators of different types compete on adjacent cells; higher-ranked species can displace lower-ranked ones
• Two prey species (Flamingo, Sheep) that forage plants and flee from predators
• Plants grow on empty cells; prey eat them when moving into a cell; animals that die naturally regrow plants at their location
• Genetic system: each animal carries a 14-digit gene encoding:
  • Breeding age (12–90)
  • Maximum lifespan (up to 120)
  • Breeding probability (0–50%)
  • Litter size (1–12)
  • Disease probability (0–50%)
  • Metabolism rate (0.25–1.00×)
• Genetic inheritance: offspring receive the first half of one parent's gene and the second half of the other's, with a 20% chance of a single-digit mutation per birth
• Disease system: animals can contract and spread disease to same-species neighbours; sick animals die after a countdown
• Animal tracking (Monitor): call trackAnimalAt(row, col) in BlueJ to highlight a specific animal in black and display its live stats (age, food level, gene, sickness, death cause)
• Live population bar showing per-species counts, colour-coded to match each species
• 100×80 simulation grid rendered at 600×600px via JavaFX Canvas

Interaction (BlueJ Method Calls)

Method	Description
simulateOneStep()	Advance the simulation by one step
simulate(n)	Run n steps with a 500 ms delay between each
reset()	Reset the field to a fresh random population
trackAnimalAt(row, col)	Highlight and monitor an animal at the given grid coordinates
getAnimalList()	Print all animals and their positions to the terminal

Tech Stack

• Language: Java
• GUI / Rendering: JavaFX (Canvas, TextFlow, Application, Platform.runLater)
• IDE: BlueJ
• Build: BlueJ project (no external build tool)

Setup

Prerequisites

• Java 17+ with JavaFX bundled, or a separate JavaFX SDK (11+)
• BlueJ 5.x (recommended) — download from bluej.org
  • BlueJ 5.x includes a bundled JDK with JavaFX; no extra configuration needed
• Alternatively, any IDE with JavaFX configured (IntelliJ, VS Code, etc.)

Opening in BlueJ

1. Download or clone this repository:

git clone <your-repo-url>

2. Open BlueJ.

3. Go to Project → Open Project and select the cloned folder.

4. BlueJ will display all classes in the class diagram. Click Compile in the toolbar to compile the project.

5. See Running the Simulation below.

JavaFX Note (if not using BlueJ 5.x)

If you are using a JDK without bundled JavaFX, add the JavaFX SDK to BlueJ via Tools → Preferences → Libraries (add the lib folder of your JavaFX SDK). Then add the following to BlueJ's VM options:

--module-path /path/to/javafx-sdk/lib --add-modules javafx.controls,javafx.fxml,javafx.media

Running the Simulation

In BlueJ

1. After compiling, right-click the SimulatorView class in the class diagram.
2. Select void main(String[] args).
3. Click OK on the dialog (no arguments needed).
4. The simulation window will open at 650×650.
5. Right-click the SimulatorView object on the object bench to call simulate(n), simulateOneStep(), reset(), or trackAnimalAt(row, col).

From the terminal (with JavaFX on the module path)

javac --module-path /path/to/javafx-sdk/lib --add-modules javafx.controls,javafx.media *.java
java --module-path /path/to/javafx-sdk/lib --add-modules javafx.controls,javafx.media SimulatorView

Project Structure

ppbcw3-main/
├── SimulatorView.java   — JavaFX Application entry point; renders the grid and population stats
├── Simulator.java       — Simulation engine; populates the field and drives per-step logic
├── Animal.java          — Abstract base class; genetic system, disease, gender, death tracking
├── Predator.java        — Predator logic: hunting, metabolism, priority-based acting
├── Prey.java            — Prey logic: plant foraging and metabolism
├── Breeding.java        — Gene inheritance, mutation, and mate-finding logic
├── Plant.java           — Regrowable plant; eaten by prey, regrows on natural animal death
├── Field.java           — 2D grid managing animal and plant placement and adjacency
├── FieldCanvas.java     — JavaFX Canvas wrapper for drawing grid cells
├── FieldStats.java      — Per-species population counter and viability check
├── Monitor.java         — Animal tracking: highlights a selected animal and reports live stats
├── Location.java        — (row, col) coordinate pair
├── Counter.java         — Per-species count accumulator used by FieldStats
├── Randomizer.java      — Shared Random instance
└── package.bluej        — BlueJ project file (class diagram layout)

Team

Developed as a team coursework project at King's College London. Two members contributed across simulation logic, genetics, UI, and animal tracking.

Academic Note

This repository is provided for portfolio and demonstration purposes only. It should not be copied, reused, or submitted as academic work.