The first commit message says “Initial commit: Jellyfish Jam SFW Version”. I am going to leave that there and move on.
Jellyfish Jam is a ten-second game. You rub the jellyfish bell to generate score. You stroke the tentacles to fill the Biolume Meter. When the meter fills, the jellyfish pulses, the tentacles grow, and the fill rate increases. Pearl Bonus circles appear around the jellyfish during the run — some give you extra time or a score multiplier, some drain seconds off the clock. The game ends. You submit your name and score. The leaderboard records it.
That is the whole game. The interesting part is what it took to make it feel right.
Why Vite and Not Next.js
Every other project in this series uses Next.js. Jellyfish Jam uses Vite with React, served as a static site, with Vercel serverless functions in an /api directory for the leaderboard.
The reason is that there is no server-side rendering story here. The game is entirely client-side. A Next.js app router would add complexity — server components, hydration, the full framework — for a game that never needs any of it. Vite builds a static bundle. The API routes handle leaderboard reads and score submissions. That is enough.
The tradeoff is that vercel dev is required to test the API routes locally, since Vite’s dev server does not serve the /api directory. Worth knowing before you start.
The RAF Loop
The game runs in a requestAnimationFrame loop. At sixty frames per second, React re-renders would be expensive and unnecessary. So the loop does not trigger them.
Instead, the tentacle paths are written directly to DOM elements on every frame via element.setAttribute("d", path). Eight <path> elements are pre-mounted in the SVG. The RAF loop updates their d attributes each frame with new wave geometry. Zero React re-renders. The jellyfish moves continuously at whatever frame rate the device supports.
Score, energy, and Biolume values that drive the UI meters are split into two: a ref that the loop mutates directly, and a state setter called to sync React for display. The rule is: mutate the ref first, then call the setter. This keeps the loop from ever reading stale state while the UI stays up to date.
Frame rate independence is handled by normalising every calculation against a 16.67ms reference frame. A 240Hz display and a 60Hz one score identically.
The Tentacle Physics
The tentacle paths are sine waves rendered through Catmull-Rom cubic bezier smoothing. Each tentacle has between five and eight segments, growing as the jellyfish scale increases. At more than four tentacles, alternating paths become thinner and higher frequency — “gossamer” tentacles that add visual density without cluttering the bell.
The Biolume fill formula went through two versions. The first used a log base-10 curve: more tentacle scale, more fill rate, but the gains flattened quickly at higher scales. It was too conservative mid-run. The second uses a square root: sqrtBonus = pow(max(1, tentacleScale), 0.5). Faster growth, more satisfying payoff when the jellyfish is large, still well short of the linear cliff that caused an earlier “instant fill” bug where the meter could overflow in a single stroke.
Fill time at comfortable fast rubbing speed runs from about 2.5 seconds at base scale down to 1.4 seconds at maximum scale. The difference matters across a ten-second game.
The Pearl Pity Timer
Seven pearl types exist. Five are positive: extra time, a score multiplier, tentacle growth, more pearls, a scale boost. Two are hazards: a time drain and a drift effect that floats the jellyfish sideways and makes precise rubbing harder.
Pearls are weighted random. After a configurable number of consecutive hazard pearls, the pity timer fires and forces the next pearl to be positive. The time drain pearl is also blocked entirely when the clock has fewer than a set number of seconds left. These are small quality-of-life adjustments that make the game feel fair without removing the hazard mechanic.
A Golden Pearl spawns at a four percent chance outside the weighted pool. It adds five seconds and fills the Biolume meter instantly. It has its own visual treatment.
The Anti-Cheat
A ten-second rubbing game with a leaderboard will attract people who would prefer not to do the rubbing. The anti-cheat is probably overkill for this scale of game, and it was interesting to build anyway.
At run start, the client calls a /api/runs endpoint and receives a signed, single-use run token. The token is HMAC-signed with a server secret. When the player submits a score, they include the token. The server validates the signature, checks the token age (must be under ten minutes), checks the run duration (must be at least three seconds), and checks the score against a calculated ceiling.
The score ceiling is computed using the same constants file as the game itself. Max multiplier applied for the full duration, plus the maximum possible Pearl Bonus scores, plus fifteen percent slack. If the game’s scoring constants change, the ceiling updates automatically. Single-use token IDs are stored in the database and rejected on replay.
The Stack
React 19, Vite 6, Tailwind 4. Framer Motion for route transitions and UI animations; gameplay feedback is never eased. Neon Serverless Postgres for the leaderboard, accessed via the HTTP driver. Web Audio API for sound effects, initialised lazily after the first user gesture to satisfy iOS’s autoplay restrictions. Haptics via navigator.vibrate where available.
RESULT
It’s live at jellyfishjam.baudypositive.com. The leaderboard works. The tentacles wave. The pity timer prevents the game from handing you three time-drains in a row, most of the time.
The most time was spent on the Biolume formula and the tentacle wave feel. Getting a physics simulation to feel satisfying rather than merely correct is slower work than getting it correct. The square root curve was the third attempt. It is the one that made playtesting feel like playing rather than testing.
The first commit says SFW Version. There is no other version.