Sân Chơi

Inspiration

My 3-year-old nephew loves hearing Vietnamese folk tales and watching water puppet shows during Tết. But these centuries-old traditions — Ô ăn quan (Mancala), Múa rối nước (water puppet theatre), Rồng rắn lên mây (dragon snake chase), Bầu cua tôm cá (Lunar New Year dice), and the legend of Thánh Gióng riding an iron horse — are vanishing from children's daily lives. I wanted to build a digital "sân chơi" (playground) where an AI agent acts as the Game Master (Người Xướng Trò), hosting these folk games for kids, in Vietnamese, with full cultural authenticity.

The OpenAI WebMCP Challenge was the perfect catalyst: what if the AI doesn't just talk about folk games, but actually runs them — managing game boards, rolling dice, directing puppet shows, chanting call-and-response, and feeding Gióng's iron horse?

How I built it

Tech stack: Vite + TypeScript, Three.js (3D water puppet stage), GSAP (animations), Web Audio API (synthesized Đàn Bầu, festive drums, gongs), zero backend — fully client-side with localStorage persistence.

Architecture: Each game follows a strict split: rules.ts (pure deterministic game logic, no DOM) and scene.ts (Three.js/GSAP visuals). Agent tools live in tools.ts and call rules directly, returning JSON state instantly — animations fire as fire-and-forget side effects.

The WebMCP integration registers 32 tools via document.modelContext.registerTool following the standard JSON Schema spec with inputSchema, annotations, and AbortController-based cleanup. A fallback mode exposes tools at window.__debugTools for DevTools testing outside ChatGPT.

For audio, I synthesized traditional folk instrument sounds using the Web Audio API — no external audio files needed for the core experience, just procedural Đàn Bầu melodies and percussion.

Challenges

1. The hang bug. The first version of Ô ăn quan awaited GSAP animations inside agent tool handlers. In headless/backgrounded browser contexts, requestAnimationFrame is throttled, so the agent hung forever waiting for an animation that never fires. The fix: agent-facing tools (isAgent: true) return game state immediately; animations run as void animate().catch(...) fire-and-forget promises. This pattern was then retrofitted to all 5 games.

2. Bầu cua's async dice. The dice-roll scene awaited animateDiceRoll before resolving bets. Same class of hang. Refactored to split roll logic from animation, applied the fire-and-forget pattern.

3. Zero-backend persistence. With no server, game state survives refreshes through localStorage — but only the last active game is saved. I built a save_progress tool and a "flustered game master" easter egg: if the agent does 5+ actions without saving, Chú Tễu pops up with "Người xướng trò bị rối!" (The Game Master is flustered!).

4. Cultural authenticity in code. Every game had to feel Vietnamese, not just reskinned Western games. Ô ăn quan uses relay-sowing rules unique to Vietnam (when your last seed lands in a small pit with >1 seed, you scoop and keep sowing). Water puppetry required understanding the 11th-century thủy đình stage and iconic tales like Cóc kiện trời (The Toad Sued Heaven). Gióng's Iron Garage is rooted in the legend of Thánh Gióng — a folk hero who grew instantly, rode an iron horse, and defeated invaders.

What I learned

Building agent-native web apps requires a fundamentally different mental model from human-facing UIs. The agent needs instant, structured feedback — it can't "see" animations. This means:

• Game logic must be pure and synchronous.
• The DOM is for humans; JSON is for agents.
• Tool descriptions must be precise enough for an LLM to understand the game's mechanics and cultural context without ever seeing the screen.
• Easter eggs and "funny hooks" keep the experience playful even when the agent is driving: zero-capture moves in Ô ăn quan make the pit shake indignantly, matching dice in Bầu cua trigger a "XỐC! BA CON!" celebration, and the water puppet applause meter rewards dramatic timing.

The result is a new kind of interactive cultural preservation — not a video about Vietnamese folk games, but an AI that can host them.

Built With

• cloudflare
• css3
• gsap
• html5
• localstorage
• three.js
• typescript
• vite
• webaudioapi
• webmcp