Java Ecosystem Simulation App

An interactive 2D artificial ecosystem simulation built with Java and Processing. It models predator-prey dynamics, autonomous agent steering behaviors, genetic evolution, and cellular automata terrain generation.

Explore the Documentation »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
   • Features & Key Highlights
2. Lessons Learned
3. Getting Started
   • Prerequisites
   • Installation & Running Locally
4. Usage
5. Contact
6. Acknowledgments

---

About The Project

ecosystemDemo.mp4

Ecosystem Simulation Demo — Showing cellular automata terrain generation, autonomous agent navigation, and predator-prey dynamics.
If the embedded video above is not displaying correctly, click here to watch/download the video demo »

This repository contains Java Ecosystem Simulation App, an academic project developed from scratch in 2024 for the Modelação e Simulação de Sistemas Naturais course at ISEL (Instituto Superior de Engenharia de Lisboa), in collaboration with Martim Ramos.

The primary goal of this project is to simulate the life cycle and emergent population balance of predator and prey species in a mixed terrestrial and aquatic environment. The simulation combines cellular automata to generate biomes and renewable food sources with autonomous agents that use sensory vision, physics integration, and genetic mutation to evolve their steering strategies over successive generations.

For a comprehensive academic explanation of the mathematical models, algorithms, and simulation results, please refer to the detailed Portuguese report available in the repository: PROJ_FINAL_MSSN_A51736_A51827.pdf.

(back to top)

---

Built With

• 
• 
• 

(back to top)

---

Features & Key Highlights

• Cellular Automata Biomes: Uses five iterations of a Moore neighborhood majority rule to group cells into realistic biomes of desert, fertile ground, food, and water obstacles.
• Autonomous Steering Behaviors: Prey use wander and obstacle avoidance to explore safely, while predators use pursuit steering to intercept the closest prey within their field of vision.
• Genetic Behavior Mutation: Offspring inherit survival strategies from parents with slight weight mutations, capping predator pursuit weight to maintain ecological balance.
• Metabolism and Resource Cycle: Animals expend energy based on movement speed and obstacle penalties, requiring food patches that regenerate every ten seconds or prey capture to reproduce.
• Interactive Terrain Control: Users can click the bottom bar to draw water lakes, food, or empty space directly onto the grid to test population isolation and survival.

(back to top)

---

Lessons Learned

• Cellular Automata: Applying discrete grid states and neighborhood rules to simulate emergent natural landscapes and renewable environmental resources.
• Autonomous Agent Perception: Implementing sensory vision cones and steering force vectors so artificial animals detect targets and navigate autonomously.
• Evolutionary Adaptation: Modeling genetic inheritance and behavior weight mutation to demonstrate how natural selection favors efficient survival strategies over time.
• Kinematics and Metabolism: Integrating physical forces, velocity, and mass with metabolic energy consumption to link mechanical movement directly to survival.
• Complex Systems Modeling: Structuring multi-agent interactions and feedback loops to observe emergent population balance between predators and prey.

(back to top)

---

Getting Started

Follow these instructions to set up a local copy of the project on your machine.

Prerequisites

• Java Development Kit 17 or higher
• IntelliJ IDEA or any compatible Java IDE
• Processing 4 library included in the repository root as core.jar

Installation & Running Locally

1. Clone the repository:

   git clone https://github.com/GuilhermeGraca/java-ecosystem-processing.git

2. Open the project:
   • Open the cloned directory in IntelliJ IDEA.
3. Verify Dependencies:
   • Ensure core.jar from the project root is added to your Java module classpath.
4. Run the Simulation:
   • Execute the ProcessingSetup main class located in the setup package to launch the simulation window.

(back to top)

---

Usage

• Start Simulation: Run ProcessingSetup.java to start the graphical interface.
• Edit Terrain: Click a state button at the bottom of the window for empty space, obstacle, or food, then click on the grid to change cell types.
• Reset World: Press the spacebar at any time to regenerate the terrain and reset agent populations.
• Monitor Statistics: Check the console output to view real-time data on population size, average speeds, and behavior weights.

(back to top)

---

Contact

Guilherme Graça — LinkedIn — GitHub

Project Link: https://github.com/GuilhermeGraca/java-ecosystem-processing

(back to top)

---

Acknowledgments

• ISEL (Instituto Superior de Engenharia de Lisboa) — For the academic environment and resources provided during the Computer Science and Engineering program.
• Modelação e Simulação de Sistemas Naturais — Course unit that motivated the development of this simulation project.
• Martim Ramos — Co-developer and collaborator on this academic project in 2024.
• Processing Foundation — For the Processing library used for rendering and visual simulation.

(back to top)