EcoSim-AI

UI of the app, with the toolbar and islands visible.
Close up of Island, with the markers illustrating the producers, herbivores, etc.

Inspiration

Traditional ecosystem simulators rely on hardcoded mathematical formulas and pre-programmed rules to calculate population dynamics. While these approaches work, they require deep domain expertise in ecology and extensive programming for each species interaction. We wondered: what if we could leverage Gemini 3's reasoning capabilities to replace those rigid formulas entirely? Instead of executing equations like Lotka-Volterra by hand, could an AI understand ecological principles and reason through what should happen next? This project explores whether large language models can serve as dynamic simulation engines rather than just conversational interfaces.

The Hawaiian island setting was chosen deliberately. Islands are self-contained ecosystems with clear boundaries, making them perfect for studying how interventions ripple through food webs. Real Hawaiian ecosystems have been dramatically affected by invasive species, providing a compelling narrative backdrop for a simulator where user actions have consequences.

What it does

EcoSim AI creates and simulates a living Hawaiian island ecosystem in real-time 3D. Users start with a balanced ecosystem containing eight native species across four trophic levels: producers (Grass, Oak Trees), herbivores (Rabbits, Deer), carnivores (Foxes, Wolves, Hawks), and omnivores (Frogs). The simulation models a diverse terrain with forests, grasslands, wetlands, and mountains, each with distinct elevation, vegetation, and water levels.

Every turn, Gemini 3 analyzes the complete ecosystem state and calculates what happens next. The AI considers:

Predator-prey relationships: Do foxes have enough rabbits to eat? Are deer overgrazing the oak forests?
Carrying capacity: Can the terrain support this many wolves, or will competition force population decline?
Seasonal cycles: How does winter affect plant reproduction and herbivore survival?
Food chain cascades: If wolves are removed, fox populations might explode, then crash when they deplete their prey
Random ecological events: Droughts, disease outbreaks, migrations, and natural disasters

Users can actively intervene by:

Introducing new species (native or invasive)
Adjusting population numbers manually
Triggering calamities like meteor strikes, volcanic eruptions, zombie outbreaks, or alien abductions
Chatting with Gemini to understand ecosystem dynamics or get suggestions

After each turn, Gemini provides a natural language narration explaining what happened and why. The 3D visualization updates in real-time, showing color-coded species markers across the terrain, seasonal vegetation changes, and the beautiful Hawaiian island landscape with realistic water effects.

Users can save ecosystem snapshots and load them later to continue simulations or explore alternate timelines ("What if I hadn't introduced those invasive snakes?").

How we built it

Architecture

We designed a clean separation between simulation logic (backend) and visualization (frontend), connected via REST API.

Backend (Python/FastAPI)

FastAPI server (backend/main.py) provides REST endpoints for creating, advancing, and querying ecosystem state
Simulation engine (backend/simulation.py) orchestrates all Gemini interactions using the Google Generative AI SDK
Pydantic schemas (backend/schemas.py) define strict types for ecosystem state, species, tiles, and simulation results
Gemini 3 Flash Preview (gemini-3-flash-preview) is called with structured output mode, receiving Pydantic schemas as JSON Schema constraints
A sophisticated system prompt instructs Gemini on ecological principles, predator-prey dynamics (Lotka-Volterra relationships), carrying capacity, and seasonal effects
Each turn sends the complete ecosystem state (species populations, prey/predator relationships, biome distribution, current season) to Gemini
Gemini returns a SimulationResult containing the new state, events that occurred, natural language narration, and warnings about potential extinctions
We implemented retry logic with exponential backoff (3 attempts, 2-second delays) to handle API reliability issues
Tile vegetation and species distribution are derived from Gemini's population decisions to keep visuals in sync with the simulation

Frontend (React/TypeScript/Three.js)

React 19 with TypeScript for type-safe state management and UI components
Three.js + React Three Fiber for declarative 3D scene composition
Custom GLSL shaders for realistic terrain rendering with elevation maps, normal maps, and color textures
Water shader effects using @funtech-inc/use-shader-fx for ripples and reflections on the ocean surrounding the island
Species markers rendered as instanced meshes for performance (each species type rendered with one draw call regardless of population)
Post-processing pipeline with bloom effects for visual polish
Auto-rotating camera with OrbitControls for exploration
Responsive UI with sidebar panels for controls, species stats, and event logs
Save/load system using JSON exports with ecosystem state snapshots

Integration

Frontend polls backend for ecosystem state changes
User actions (advance turn, interventions, chat) trigger API calls to FastAPI endpoints
Gemini responses are unpacked and synchronized across visualization and UI
Environment variables manage API keys securely (.env file for development)

Key Gemini API Implementation

Located in backend/simulation.py lines 230-238 and 341-347, we use:

response = await client.aio.models.generate_content(
    model="gemini-3-flash-preview",
    contents=prompt,
    config=types.GenerateContentConfig(
        system_instruction=SYSTEM_PROMPT,
        response_mime_type="application/json",
        response_schema=SimulationResult,
    ),
)

Challenges we ran into

Ecological plausibility

Our biggest challenge was preventing runaway population growth or instant collapse. Early iterations had populations exploding to millions or going extinct within three turns. We solved this by:

Crafting a detailed system prompt with explicit ecological constraints and principles
Providing Gemini with species-specific reproduction rates and territory sizes as guardrails
Sending complete predator-prey relationship graphs so Gemini understands food web dependencies
Adding explicit warnings in prompts about maintaining ecological balance and realistic population dynamics
Iteratively refining the prompt based on simulation outcomes to achieve stable ecosystems

API reliability

Gemini occasionally returned empty responses (especially under load or with complex state), causing simulations to fail mid-turn. We implemented retry logic with 3 attempts and 2-second delays between retries, plus comprehensive error handling that preserves ecosystem state when failures occur so users don't lose progress.

Performance optimization

Rendering hundreds of individual species markers on terrain threatened frame rates, especially with 10,000+ grass plants and hundreds of animals. We switched to instanced rendering where each species type uses a single draw call regardless of population, and implemented frustum culling to skip markers outside camera view. This took us from ~20fps to smooth 60fps.

Structured output schemas

Gemini sometimes omitted optional fields or returned slightly malformed JSON that broke our TypeScript frontend. We tightened Pydantic schemas with explicit defaults and validators, then configured Gemini's response_mime_type="application/json" with strict schema enforcement to guarantee valid outputs every time.

Visualization coherence

Synchronizing Gemini's abstract population numbers with spatial 3D representations was tricky. Species don't have individual coordinates, just biome preferences and population counts. We distribute markers across tiles matching preferred biomes, weighted by population density, to create the illusion of spatial distribution without micromanaging individual entities.

Seasonal transitions

Making seasons feel impactful without manual weather systems or climate modeling required careful prompting. We send the current season to Gemini and trust it to apply seasonal effects (winter reduces reproduction, spring boosts plant growth, summer affects water availability), then reflect this in vegetation colors and density on tiles client-side.

State synchronization

Ensuring the frontend 3D view, species panels, and event logs all stayed perfectly in sync with backend state required careful React state management and avoiding race conditions when multiple API calls were in flight.

Accomplishments that we're proud of

Zero hardcoded ecology

Every population calculation, predation event, and ecological consequence comes from Gemini's reasoning. There's no if (wolves > rabbits) { wolves -= 10 } or Lotka-Volterra equations anywhere in our code. This proves LLMs can serve as general-purpose simulation engines when properly orchestrated, not just text generators.

Cascading effects work

Introduce too many wolves, and they'll overhunt deer over 2-3 turns. Deer scarcity means wolves starve by turn 5. Reduced wolf predation lets rabbit populations explode by turn 7. Rabbits overgraze grass, causing vegetation collapse by turn 10. The entire ecosystem enters collapse without any of these interactions being explicitly programmed. Gemini traces these multi-step consequences across turns through pure reasoning.

Natural language narration

Each turn produces contextual, engaging explanations like "Harsh winter reduced Oak Tree reproduction, while Wolves struggled to find prey as Deer populations declined from overhunting. Fox populations surged in the absence of Wolf competition, threatening Rabbit populations." This makes complex simulations accessible and understandable to non-ecologists.

Beautiful, performant 3D

The Hawaiian island looks stunning with realistic water reflections, terrain shading based on actual elevation data, dynamic vegetation, and smooth animations, all running at 60fps even with hundreds of species markers and complex shaders.

Structured output reliability

By using Pydantic schemas with Gemini's structured output mode, we eliminated prompt injection risks and got type-safe, validated responses that integrate seamlessly with our TypeScript frontend. No more parsing nightmares or malformed JSON errors.

Real-time interactivity

Users can chat with Gemini about the ecosystem without advancing time, asking questions like "Why are the rabbits dying?" and getting informed answers based on current state analysis.

Hackathon timeline

We built this entire full-stack application—backend API, AI orchestration, 3D rendering engine, UI components, and complete integration—in a hackathon timeframe, showcasing how quickly developers can prototype sophisticated AI applications with Gemini 3.

What we learned

LLMs as reasoning engines

The biggest insight is that Gemini 3 excels at rule-based reasoning over state spaces. It's not just generating creative text; it's applying ecological principles consistently across turns, maintaining causal relationships, and predicting multi-step consequences. The structured output feature transforms LLMs from conversational agents into programmable reasoning modules that can replace entire simulation engines.

Prompt engineering vs. system design

The value isn't in clever prompting tricks or magic phrases. It's in the orchestration layer that maintains state, structures inputs/outputs with schemas, handles failures gracefully, implements retry logic, and derives visual representations from abstract AI decisions. The system architecture around Gemini matters far more than the prompt itself.

Schemas as contracts

Defining Pydantic schemas forced us to think clearly about data structures before writing any code. These schemas then served triple duty: backend validation, Gemini output constraints (via JSON Schema), and frontend TypeScript types (after conversion). Strong typing across the entire stack prevented entire classes of bugs and made refactoring safe.

AI reliability patterns

Treating AI calls like any other external API (with retries, timeouts, fallbacks, circuit breakers) is essential for production-quality apps. We learned to design for partial failures and maintain system state when AI requests fail, rather than treating the AI as an infallible oracle.

User trust through transparency

Showing Gemini's natural language narration builds trust in the simulation. Users understand why populations changed, which makes unexpected outcomes feel legitimate and scientifically grounded rather than buggy or random. Transparency is key for AI-driven applications.

Performance matters for immersion

No matter how smart the AI reasoning is, if the visualization stutters, loads slowly, or feels unresponsive, the experience breaks down. Optimization—instanced rendering, frustum culling, efficient state updates—isn't optional for real-time interactive AI applications.

State management complexity

Keeping frontend and backend in sync while AI calls are asynchronous and potentially slow taught us the importance of loading states, optimistic updates, and clear error boundaries.

What's next for EcoSim-AI

Multi-island archipelagos

Expand to multiple interconnected islands with species migration between them. Watch invasive species spread across an island chain via natural dispersal or human transport, or see how isolated populations diverge evolutionarily due to genetic drift and different selection pressures.

Climate modeling

Add persistent climate variables (temperature, rainfall, CO2 levels, ocean acidity) that users can manipulate to simulate climate change impacts on ecosystems. See how coral reefs bleach, forests migrate to higher elevations, or desertification spreads.

Evolutionary adaptation

Allow species to evolve traits over generations based on selection pressure. Prey could develop speed, camouflage, or defensive toxins; predators could evolve pack hunting behaviors, better tracking abilities, or dietary flexibility. Let Gemini reason about evolutionary arms races.

Real-world data integration

Load actual elevation data, satellite imagery, and species inventories from real Hawaiian islands (or other ecosystems) to simulate conservation scenarios with real-world accuracy. Partner with conservation organizations to model intervention strategies.

Multiplayer ecological management

Multiple users simultaneously control different aspects of the same ecosystem (one manages predators, another manages climate, a third controls human interventions) and must cooperate to prevent ecosystem collapse. Add competitive modes where users manage rival islands.

Educational mode

Structured challenges, guided lessons, and interactive tutorials about ecology, biodiversity, trophic cascades, keystone species, and conservation biology for classroom use. Align with AP Environmental Science and college ecology curricula.

Generative species

Let Gemini invent entirely new fictional species with plausible traits, behaviors, and ecological niches, expanding beyond Earth-like ecosystems into alien biospheres or speculative evolution scenarios.

Longer time scales

Simulate hundreds or thousands of years with time-lapse features to observe evolutionary change, continental drift effects, or recovery from mass extinction events.

Genetic diversity tracking

Model within-species genetic variation, inbreeding depression in small populations, and the genetic consequences of bottleneck events to add another layer of biological realism.

Disease modeling

Add pathogens and parasites that spread between species, with Gemini reasoning about epidemiology, host-parasite coevolution, and zoonotic disease risks.