Shark Guestbook

Overview

The Shark Guestbook is an interactive Unity simulation where fish generated from a Python pipeline are introduced into a dynamic ocean environment. AI-driven sharks, environmental cycles, and a raffle mode for special behaviors create a living ecosystem. This document outlines the technical structure, components, and runtime flow.

System Architecture

High-level interaction between major components:

+-------------------+      +----------------+
| TextureGenerator  | ---> | FishMetadata   |
| (Python)          |      | (Data)         |
+-------------------+      +----------------+
          |                        |
          v                        v
   +-----------------+     +------------------+
   | PreySpawner     | --> | FishAI.cs        |
   +-----------------+     +------------------+
          |
          v
   +-----------------+     +------------------+
   | SharkAI.cs      | --> | RaffleHungerMgr  |
   +-----------------+     +------------------+
          |
          v
   +-------------------+
   | DayNightRotator   |
   | WaterEnvironment  |
   +-------------------+
      

Core Components

🐟 FishAI.cs

Controls individual fish movement using spine-based animation. Implements wave motion, drag, and reactive steering. Fish are spawned with metadata (textures, IDs) generated externally.

🦈 SharkAI.cs

Governs shark behavior including roaming, prey detection, pursuit, and “suck” routine for consuming fish. Sharks pivot and move relative to a viewOrigin transform, simulating realistic swimming arcs.

🎣 PreySpawner.cs

Dynamically spawns fish and sharks at runtime. Sharks are assigned their own viewOrigin, while fish are instantiated as standalone GameObjects.

🍽️ RaffleHungerManager.cs

Introduces “raffle mode,” where sharks alter hunger levels and speed dynamics. Controls when sharks are in normal vs. event-driven states.

🌅 DayNightRotator.cs

Handles lighting and directional rotation for a natural day/night cycle. Synchronizes environmental visuals for realism.

🌊 WaterEnvironmentManager.cs

Manages HDRP water environment, visual effects, and integration with particle systems (e.g., glowing spores, ripples). Ensures sharks and fish interact believably with water surfaces.

🐠 FishMetadata.cs

Stores structured data for fish including texture IDs, names, and behavioral properties. Acts as the data layer connecting Python’s TextureGenerator to Unity.

Runtime Flow

1. Textures and fish metadata are generated via TextureGenerator.py.
2. PreySpawner reads metadata and spawns fish with unique appearances.
3. FishAI controls swimming and flocking movement.
4. SharkAI roams, detects prey, and engages feeding routines.
5. RaffleHungerManager adjusts shark behavior during special modes.
6. DayNightRotator updates environment lighting dynamically.
7. WaterEnvironmentManager ensures visual and physical water realism.

Challenges & Solutions

• Ensuring sharks pivot around viewOrigin → fixed via transform smoothing.
• Balancing fish swarm realism with performance → optimized SmoothDamp usage.
• Synchronizing raffle mode with normal AI → centralized hunger manager.