Gamification & Tuna
Relevant source files
The following files were used as context for generating this wiki page:
Gamification within the Tuturuuu platform is primarily centered around Tuna, an intelligent, gamified AI companion designed to eliminate digital noise and act as a personal partner for work and life. The system integrates traditional productivity tools with RPG-like mechanics—such as experience points (XP), levels, achievements, and customizable accessories—to incentivize deep work and consistent platform engagement.
The "Tuna" system serves as the "soul" of the platform, linking user activities like focus sessions, task completion, and chat interactions to a persistent virtual pet state. This architecture transforms administrative work into a rewarding experience, fostering a "Third Era" partnership between human and AI.
Sources: README.md:15-18, conductor/product.md:3-6, apps/database/supabase/migrations/20260127090000_create_tuna_gamification_tables.sql:1-4
Core System Architecture
The Tuna ecosystem is built on a PostgreSQL/Supabase backend with specialized tables tracking pet states, user progress, and behavioral memories. The system uses a centralized XP awarding mechanism and level-up logic to drive progression.
Database Schema & Entity Relationships
The gamification engine relies on several interconnected tables to maintain the state of each user's companion.
The diagram above illustrates how user-specific data (pets, stats, memories) interacts with global catalogs (achievements, accessories).
Sources: apps/database/supabase/migrations/20260127090000_create_tuna_gamification_tables.sql:20-110
Key Data Structures
The following table outlines the primary fields within the tuna_pets table, which represents the core state of the gamified companion:
| Field | Type | Description |
|---|---|---|
level | INTEGER | Current level of the companion (starts at 1). |
xp | INTEGER | Current experience points toward the next level. |
xp_to_next_level | INTEGER | Threshold required for the next level up (defaults to 100). |
mood | tuna_mood | Enum: happy, neutral, tired, sad, excited, focused. |
health / hunger | INTEGER | Vitality metrics (0-100) affecting pet state. |
streak_days | INTEGER | Consecutive days of platform interaction. |
| Sources: apps/database/supabase/migrations/20260127090000_create_tuna_gamification_tables.sql:39-58 |
Progression Mechanics
Progression is driven by user activity across the Tuturuuu ecosystem. Actions such as completing tasks, participating in AI chats, and finishing focus sessions trigger XP rewards.
XP and Leveling Logic
The system implements an exponential growth curve where each level requires 20% more XP than the previous one. This is handled by the award_tuna_xp stored procedure.
-- Handle level ups (exponential curve: each level needs 20% more XP)
WHILE v_new_xp >= v_new_xp_to_next LOOP
v_new_xp := v_new_xp - v_new_xp_to_next;
v_new_level := v_new_level + 1;
v_new_xp_to_next := CEIL(v_new_xp_to_next * 1.2);
END LOOP;
Sources: apps/database/supabase/migrations/20260127090000_create_tuna_gamification_tables.sql:240-245
Productivity Integration: Focus Sessions
Focus sessions are a primary source of XP. Users set a planned duration for deep work, and the system calculates rewards based on actual performance.
- XP Calculation: 1 XP is awarded per minute of focus.
- Completion Bonus: A bonus of 50% of the planned duration is awarded if the user completes the full session.
- Stat Tracking: Completed sessions update
total_focus_minutesin thetuna_petstable and incrementfocus_sessions_completedin daily stats.
Sources: apps/database/supabase/migrations/20260127090000_create_tuna_gamification_tables.sql:315-335
AI Interaction & Personalization
Tuna's intelligence is powered by multi-model AI (Mira), which follows strict guidelines to provide a smart, easy-to-understand experience.
Mira AI Guidelines
The AI companion, Mira, is instructed to utilize specific components to enrich learning and engagement:
- Quizzes: Enclosed in
@<QUIZ>tags to test user knowledge. - Flashcards: Enclosed in
@<FLASHCARD>tags for active recall. - Diagrams: Generated via Mermaid syntax when requested to visualize complex concepts.
- Follow-ups: Predicative prompts to continue the conversation in a meaningful way.
Sources: packages/ai/src/chat/google/route.ts: systemInstruction, packages/ai/src/chat/google-vertex/route.ts: systemInstruction
Memory System
To enhance personalization, Tuna maintains a memory system categorized by preferences, facts, conversation topics, events, and people. This allows the companion to "remember" details about the user over time, increasing its relevance and emotional connection.
Sources: apps/database/supabase/migrations/20260127090000_create_tuna_gamification_tables.sql:30-34, 89-100
Achievement & Customization Catalogs
The platform features extensive catalogs for achievements and cosmetic items to sustain long-term engagement.
Achievement Categories
Achievements are classified into several categories, each targeting different user behaviors:
| Category | Example Codes | Reward (XP) |
|---|---|---|
| Milestones | first_conversation, level_10, week_streak | 10 - 200 |
| Productivity | first_focus, long_focus, total_focus_1000 | 15 - 200 |
| Social | share_story, remember_me, deep_talk | 15 - 30 |
| Special | fed_tuna, perfect_day | 5 - 40 |
| Sources: apps/database/supabase/migrations/20260127090000_create_tuna_gamification_tables.sql:360-385 |
Accessory Customization
Users can customize their Tuna companion with accessories unlocked through progression or specific achievements. Categories include:
- Hats: Party Hat (Level 1), Graduation Cap (50 Focus Sessions).
- Glasses: Round Glasses (Level 3), Star Glasses (Level 10).
- Backgrounds: Coral Reef (Level 1), Galaxy (Month Streak - Premium).
- Decorations: Extra Bubbles (Level 2), Fish Castle (Level 12).
Sources: apps/database/supabase/migrations/20260127090000_create_tuna_gamification_tables.sql:395-415
Conclusion
The Gamification & Tuna system is a critical component of Tuturuuu's strategy to reduce digital friction. By wrapping workspace management, focus sessions, and AI interactions in a gamified layer, the platform incentivizes the "work about work" while building a contextual, memory-capable partner (Mira) that grows alongside the user. This integration ensures that productivity is not just a utility, but an evolving journey tracked through XP, levels, and achievements.
Sources: README.md:15-20, conductor/product.md:10-15, apps/database/supabase/migrations/20260127090000_create_tuna_gamification_tables.sql:430-435