TerraBot - Ecosystem Simulation

1. Project Structure & Class Hierarchy

The code is organized into logical packages to separate data, logic, and user input:

• main.entities: Represents the core data model.

  • Entity: The abstract base class defining the contract (name, mass, scan status) for all environmental objects.
  • Sub-packages (air, animals, plants, soil, water): Contain abstract extensions (e.g., Soil) and concrete implementations (e.g., ForestSoil, Carnivore). These classes encapsulate specific attributes like toxicity, nutritional value, or blocking probability.

• main.commands: Handles user commands using the Command Pattern.

  • Command: Abstract base class defining the execution template.
  • CommandFactory: Instantiates specific commands based on input strings, separating parsing from logic.
  • Concrete Commands (e.g., MoveCommand, ScanCommand, ImproveCommand): Encapsulate specific robot actions.

• main.map: Manages the simulation grid.

  • MatrixMap (Singleton): Holds the grid of cells.
  • Cell: Represents one coordinate that holds references to various Entities inside it(Soil, Air, Plant, Animal).

• main.robot: Contains TerraBot (Singleton), managing the robot's internal state (coordinates, energy, inventory, knowledge base).

• main.simulation: The execution engine (SimulationManager, Simulation) that runs the main loop and handles changes in the environment.

2. Implementation & Entity Interactions

The system relies on polymorphism to handle interactions between the robot and diverse environmental entities efficiently.

A. Robot Movement & Risk Evaluation

The MoveCommand determines the optimal path by evaluating the risk of nearby cells. Instead of checking for specific classes, the system uses one standard way to interact with every entity:

• The command iterates through entities within a Cell.
• It invokes the polymorphic getRiskScore() method defined in Entity.
• Each subclass provides its specific risk metric (e.g., Soil returns blocking probability, Air returns toxicity, Animal returns attack chance).
• The robot aggregates these scores to make a navigation decision.

B. Ecosystem Dynamics & Lifecycle

The simulation is not static; entities interact dynamically during the update phase managed by the Simulation class. This logic maintains the separation between data (Entity) and behavior (Simulation):

• Growth Cycle: Plants interact with Soil properties (like water retention) to increase their maturity level.
• Feeding Chain: Animals scan their current Cell for specific food sources (Plants or Water) based on their dietary requirements.
• Feedback Loop: When Animals feed effectively, they return organic matter to the Soil, improving its quality for future plant growth.

3. Design Patterns

• Singleton: Applied to TerraBot and MatrixMap to ensure a single source of truth for the robot's status and the map layout throughout the simulation lifecycle.
• Command: Encapsulates user requests as objects, allowing the SimulationManager to execute actions uniformly and enabling easy extension of the robot's capabilities.
• Factory: The CommandFactory and EntityFactory centralize object creation, keeping the main execution logic clean and separated from instantiation details.