Three Species Architecture
PolyFish simulates three distinct creatures, each with its own behavior, speed, and decision-making cadence. This creates an ecosystem with layered complexity: fish are skittish prey, dolphins are intelligent predators that manage air, and manatees are slow browsers. No creature type dominates - all three coexist dynamically.
Thrust & Locomotion
Unlike traditional rigid-body physics that applies instantaneous impulses, PolyFish creatures use continuous force - constant acceleration in a chosen direction. Each frame, if the creature is moving, its velocity vector is pushed toward a target velocity based on the desired heading and throttle. This creates smooth, realistic acceleration/deceleration curves without sudden snaps.
The Thrust Model
Each creature has a thrust multiplier that scales global acceleration:
- Fish: 8.36× (nimble, responsive)
- Dolphin: 10× (powerful, accelerates fastest)
- Manatee: 6.69× (sluggish, takes time to reach speed)
Target velocity is computed as heading * baseSpeed * throttleScale, where throttleScale is 0 (idling), 1.0 (cruise), or 2.5 (dashing). The current velocity is then lerped toward target velocity at a per-creature acceleration rate (roughly 60ms per 10% of top speed). This soft acceleration prevents overshooting and makes creatures feel heavy and inertial.
Deceleration is slower than acceleration - when throttle drops to 0, the creature coasts for a moment before stopping. This is physically unrealistic but feels great: creatures have momentum, they don't snap to idle. Per-species drag values (fish 2.27, dolphin 2.0, manatee 1.65) create natural friction that eventually brings them to rest. Lighter drag on manatees means they coast longer and feel heavier.
Engine Burn Cycles
Instead of creatures swimming at constant speed, they cycle through "engine burns": a species-specific burn time at full throttle (0.43s for fish, 1.0s for dolphins, 0.9s for manatees), followed by a randomized coasting period before the next burn. This on-off pattern emerges naturally from hunting and foraging behavior, but it also serves to break up animation repetition. No two creatures sync their burn cycles because each has a randomized phase offset.
Dash Mechanic
When a fish spots a dolphin, or a dolphin locks onto a meal, something changes. A creature can trigger a dash - a brief 2.5x speed boost lasting 0.4 seconds. It's not guaranteed (15% chance per brain tick), so hunts become moments of chance. A fish might break free. A dolphin might strike. The unpredictability is what makes chases feel alive.
Oxygen System (Dolphins)
Dolphins are mammals - they must breathe. This adds a strategic layer: a dolphin can hunt indefinitely underwater, but it must surface every 60 seconds or it dies. The oxygen system is simple but creates interesting emergent behavior: dolphins hunt in bursts, surface to breathe, then hunt again.
Tank Mechanics
Each dolphin has an oxygen tank stored as a 0-1 gauge. While submerged, the tank depletes at 0.0167 per second, draining completely in about 60 seconds. At the surface, the tank refills at 0.25/second, taking about 4 seconds to fill from empty. In practice, dolphins surface well before hitting zero (the urgent threshold kicks in at 30%), so refills are quicker.
Emergent Behavior
The oxygen system creates a natural hunting cycle. A dolphin hunts a school of fish, drives them into a corner, and just as it's about to catch one, the oxygen alarm triggers. It must surface, losing the prey. By the time it returns, the fish have scattered. This makes dolphins feel mortal and prey feel hopeful - the ocean isn't a guaranteed predation grounds.