
Where it came from
In Porto de Galinhas, getting from the hotel to the water is a negotiation: every few meters someone offers you an umbrella, a tour or "mas tem WiFi!". The situation already had game mechanics —distance, line of sight, fatigue— it just needed to be programmed.
The problem
Turning a travel anecdote into a game you understand in ten seconds and that stays fair: vendors who see you, remember you and chase you, without the difficulty depending on luck.
The solution
A 3D browser game built with Three.js and TypeScript. Three levels to the sea, the natural pools and boarding. Vendors have line of sight, suspicion and memory; the player has sprint and energy, and can hide behind cover. There is a single-player mode, local co-op for couples and a three-chapter story mode with the reais earned along the way.
What's solved
- Vendor AI with line of sight, cover that blocks their view, and suspicion and memory configurable by difficulty.
- Two versioned difficulty profiles ("sin emoción" and "con emoción") with separate high scores and measurement of the observed win rate.
- Local co-op: shared camera, a common wallet and a maximum distance between the two players.
- Three-chapter story mode that carries over the money earned and remembers the couple's names.
- Proximity voices with Web Audio: volume by distance, stereo panning relative to the camera and at most two voices at a time.
- Verbal defense by double tap ("Ya tenemos sombrilla, gracias") with a cooldown and a different effect per difficulty.
- Optional global arcade leaderboard; the game works just the same if the service doesn't respond.
Evidence
- Game published on GitHub Pages with automatic deploys via GitHub Actions.
- 14 tests with Node's native runner covering the pure logic: vision, conversation, energy, difficulty, couple and story.
- Game logic lives in DOM-free modules (
core,difficulty,couple,story,verbal), separate from the Three.js rendering.
The hard parts
- Making losing feel fair: difficulty comes from explicit parameters (speed, vision radius, memory), not random events.
- In co-op, two players share one camera. The distance between them had to be capped, and we had to work out which vendor targets whom.
- Audio can't break the game: if Web Audio is missing or a clip fails to decode, the speech bubbles remain and the match goes on.
What I learned
- Splitting the logic into pure functions made it possible to test gameplay without opening a browser.
- Versioning the difficulty profiles makes high scores and win rates comparable across changes.
- A small game is a good test bench for agent AI, spatial audio and shared state.
Next steps
- Replace the provisional synthetic voices with real recordings.
- Tune mix and pacing with tests in players' browsers.