El-Fish Simulator - Project Documentation

Summary

A modern web-based aquarium simulator conceptually based on the 1993 aquarium simulator El-Fish. This browser-based implementation features procedurally generated fish with genetic algorithms controlling their appearance and behavior. Users can catch, breed, and evolve unique fish through selection and mutation, creating infinite variations from 56+ genetic traits. The simulator includes a fully customizable 3D aquarium environment with decorations, plants, and various backgrounds, all rendered in pure HTML5/CSS3/JavaScript without external dependencies. Fish genetics determine everything from body shape and fin types to colors, patterns, and swimming behaviors, making each fish truly unique.

Technical Architecture

Core Genetic System

The simulator implements a sophisticated genetic algorithm at its heart, built around the FishGenome class. Each fish carries a genome containing over 56 distinct genes that control various phenotypic expressions:

Genetic Traits Categories

1. Morphological Genes
   • bodyLength, bodyHeight, bodyWidth: Control the elliptical body proportions
   • bodyTaper: Determines how the body narrows toward the tail
   • dorsalFinSize, caudalFinSize, pectoralFinSize, analFinSize: Individual fin dimensions
   • dorsalFinShape (0-2): Round, pointed, or split dorsal fins
   • caudalFinShape (0-3): Round, forked, fan, or veil tail shapes
   • scale: Overall size multiplier (0.5x to 2x)
2. Pigmentation Genes
   • Body and fin colors stored as HSL values for infinite color possibilities
   • hasGradient: Boolean for gradient coloring
   • gradientIntensity: Strength of color transitions
   • hasShimmer: Rare iridescent effect gene
3. Pattern Genes
   • stripeCount, stripeWidth, stripeAngle: Vertical banding patterns
   • spotCount, spotSize: Circular markings
   • patternComplexity: Triggers scale patterns at high values (>0.7)
4. Behavioral Genes
   • speed: Base swimming velocity (0.5-2.5 units)
   • schooling: Boolean for flocking behavior
   • verticalPreference: Preferred depth in tank (0=bottom, 1=top)
   • curiosity: Food-seeking aggression multiplier
5. Animation Genes
   • tailWagSpeed: Frequency of tail oscillation
   • finWaveAmplitude: Pectoral fin movement range

Genetic Operations

Mutation

The mutation system uses Gaussian noise with configurable rates:

// Standard mutation adds ±30% noise
newValue = oldValue + (Math.random() - 0.5) * 0.3

Special handling ensures valid ranges: - Hue values wrap at 360° - Counts floor to integers - All percentages clamp to [0,1]

Crossover (Breeding)

Sexual reproduction implements: 1. Random inheritance: Each gene has 50% chance from either parent 2. Gene averaging: 20% chance of averaging continuous traits 3. Mutation on birth: Offspring receive 10% mutation rate

Rendering Pipeline

SVG Generation

Each fish is dynamically rendered as an SVG with: 1. Procedural body construction: Multiple ellipses create body segments 2. Fin path generation: Bézier curves and polygons based on fin genes 3. Pattern layering: Stripes, spots, and scales added as SVG elements 4. Gradient definitions: Dynamic <linearGradient> and <radialGradient> elements

Animation System

• CSS animations: Tail wagging via @keyframes with dynamic duration
• JavaScript physics: Position updates at 60 FPS using requestAnimationFrame
• Velocity vectors: Each fish maintains vx and vy with acceleration
• Boundary detection: Elastic collisions with tank walls
• Delta time scaling: Frame-independent movement

Behavioral Simulation

Movement Algorithm

// Core movement loop (simplified)
1. Apply food attraction vectors if food present
2. Add random walk: vx += (Math.random() - 0.5) * 0.1
3. Apply vertical preference force
4. Implement schooling alignment with nearby fish
5. Clamp to maximum speed
6. Update position: x += vx * deltaTime
7. Handle boundary collisions

Schooling Behavior

Fish with schooling=true genes: 1. Detect neighbors within 100px radius 2. Calculate average velocity vector of school 3. Adjust own velocity 5% toward group average 4. Creates emergent flocking patterns

Data Persistence

Storage Schema

{
  fishes: [{
    genome: { genes: {...}, id: "fish_timestamp_random" },
    name: "Generatedname"
  }],
  generation: number,
  background: string,
  sandVisible: boolean,
  decorations: [{
    type: string,
    left: string,
    bottom: string
  }]
}

Save/Load Operations

• Auto-save: Every 30 seconds via setInterval
• Manual saves: Named tank configurations
• Fish library: Separate storage for breeding stock
• Compression: JSON stringify with no formatting

Performance Optimizations

1. Single RAF loop: All fish updated in one animation frame
2. Event delegation: Single click handler with element detection
3. SVG caching: Fish SVG generated once at creation
4. Transform-only animations: GPU-accelerated CSS transforms
5. Visibility culling: Off-screen fish skip rendering (planned)

User Interface Architecture

Event Handling

• Selection system: Click events with visual feedback (yellow glow)
• Drag and drop: Decorations use mouse event state machine
• Modal dialogs: Fish library with dynamic content generation

Responsive Design

• Flexbox layout: Controls adapt to screen width
• Relative positioning: Percentage-based fish spawning
• Viewport units: Aquarium scales with browser window

Browser Compatibility

Required APIs

• localStorage: Persistence (4MB typical limit)
• requestAnimationFrame: Smooth animation
• CSS Custom Properties: Dynamic styling
• SVG 1.1: Fish rendering
• ES6 Classes: Object-oriented structure

Fallbacks

• Position detection uses getBoundingClientRect()
• Time measurement via Date.now() for wide support
• No WebGL requirement - pure DOM rendering

Extension Points

The architecture supports easy additions:

1. New genes: Add to FishGenome constructor
2. New patterns: Extend generateComplexPatterns()
3. New decorations: Add to decoration types object
4. New behaviors: Implement in update() method
5. Export formats: Add serialization methods

Known Limitations

1. Performance ceiling: ~50 fish before frame drops
2. Storage limits: Browser-dependent localStorage size
3. No sound: Audio API not implemented
4. No networking: Purely client-side application
5. Mobile touch: Click events not optimized for touch

Future Architecture Considerations

1. WebWorkers: Offload genetic calculations
2. IndexedDB: Larger storage for fish collections
3. WebGL: Hardware-accelerated fish rendering
4. WebAudio: Procedural bubble sounds
5. WebRTC: Multiplayer fish trading

File Structure

Currently a single monolithic HTML file (~2000 lines) containing: - CSS styles (300 lines) - JavaScript classes and logic (1600 lines) - HTML structure (100 lines)

Potential refactoring into modules: - genetics.js: Genome and genetic operations - fish.js: Fish class and rendering - aquarium.js: Environment management - ui.js: Interface and controls - storage.js: Persistence layer - styles.css: Separated styles - index.html: Minimal HTML shell