Skip to main content

Gamification: Idle Fighter System

Status: ✅ Complete
Last Updated: 2026-08-18

Related: Schema · Banking · Fighter profiles · House · Navigation hubs

Overview​

The Idle Fighter System is a core gamification feature that connects real-world ARC activities to character progression and battle mechanics. Your character fights automatically based on your activity inputs, creating a daily reason to log in and complete inputs.

User Guide​

What is the Idle Fighter System?​

Your character in ARC // OS grows stronger based on your real-world activities. Every action you log (training, reading, journaling, sleep, etc.) improves your character's stats, which directly affects battle performance and rewards.

The Loop:

  1. Log your day → Your character's stats increase
  2. Your character fights → Automatic battles based on your stats
  3. You earn rewards → Coins, XP, materials, gear
  4. You upgrade gear → Improve battle performance
  5. You want to log tomorrow → Keep your edge and progress

How Your Activities Build Your Character​

Strength - Built by:

  • Weight training sessions
  • Progressive overload (increasing weight/reps)
  • Consistency in training

Endurance - Built by:

  • Cardio sessions
  • Steps walked
  • Mobility streaks

Discipline - Built by:

  • Checklist completion
  • Perimeter task completion
  • Time blocks respected

Wisdom - Built by:

  • Reading sessions
  • Course progress
  • Quality journaling (structured entries)

Recovery/Resilience - Built by:

  • Sleep targets met
  • Low substance use streaks
  • Rest days respected

Balance - Built by:

  • Multi-domain completion (not just gym grind)
  • Completing activities across all areas

Daily Claim Loop​

Every day, you can:

  1. Claim today's fights - 1-3 daily matchups automatically generated
  2. Claim offline progress - If you were away, see what happened
  3. See your next unlock - Achievements close to completion, level milestones

Bonus Rewards:

  • Complete daily report: +50% coins and XP
  • Perfect day (all checklist + all perimeter): +100% coins and XP

Weekly Boss​

Every week:

  • A boss rotates with unique mechanics
  • Boss weakness tied to a stat domain (Strength, Recovery, Wisdom, Balance)
  • Boss prep hints guide you to log the relevant domain that week
  • Requires better preparation than daily monsters

Example: Recovery boss week → Focus on sleep and recovery logging

Weekly Ladder​

Compete weekly:

  • Rankings based on battle performance (wins, win rate, total battles)
  • Weekly reward tiers (Rank 1: 500 coins + 1000 XP, etc.)
  • Automatic weekly reset (Monday-based)

Background Fighting​

Continuous progression:

  • Your character automatically fights weak monsters in the background
  • Rewards accumulate over time (not daily reset)
  • Claim rewards when ready
  • Progression capped by real-world logging quality

World Selection:

  • Choose which "world" your character fights in each day
  • Each world has unique monster types, material drops, and bonuses
  • World selection persists for the day

Materials & Crafting​

Earn materials from:

  • ARC activities (focus shards, recovery cloth, knowledge ink)
  • Background fighting (world-specific materials)
  • Battle wins

Use materials for:

  • Crafting/upgrading gear
  • Building/upgrading rooms in your house
  • Crafting consumables (potions, buffs)
  • Trading/currency conversion

Skill Trees​

Unlock nodes by:

  • Meeting behavior milestones (e.g., "7 workouts logged")
  • Nodes automatically unlock when milestones are met
  • Nodes grant battle perks and cosmetic unlocks

Trees available:

  • Strength tree
  • Wisdom tree
  • Discipline tree
  • Recovery tree

Gear Sets​

Complete sets for bonuses:

  • Discipline Set, Iron Set, Scholar Set, Zen Set
  • Completing a set grants:
    • Small passive perk (5% stat boost)
    • Room decoration
    • Badge collection unlock

Core Philosophy​

Guiding Principles (for all gamification work)​

  • ARC loop first: rewards must reinforce the habit of logging inputs daily (planner, training, meals, sleep, journaling, etc.)
  • Meaningful progression: rewards reflect real consistency and improvement, not random grinding
  • Daily "hook": every day should have a small, satisfying "what did I earn / unlock today?" moment
  • Competition with dignity: friends/leaderboards should feel motivating, opt-in, and privacy-safe
  • Non-intrusive UX: feedback is crisp: toasts + small celebrations; no bloated popups
  • Deterministic + testable: battle logic must be reproducible and heavily tested

Player Fantasy: You log your day → your character grows → your character fights → you get rewards → you upgrade gear → you want to log tomorrow to keep your edge.

Key Feelings:

  • "My discipline builds my character."
  • "If I skip journaling/sleep/training logging, my fighter underperforms."
  • "I want to beat my friends this week."

1. Inputs → Stats Mapping​

Status: ✅ Complete

Stat Formulas​

Real behaviors map to battle-relevant stats:

  • Strength: weight training sessions, progressive overload, consistency
  • Endurance: cardio sessions, steps, mobility streaks
  • Discipline: checklist completion, perimeter completion, time blocks respected
  • Wisdom: reading sessions, course progress, journaling quality (structured entries)
  • Recovery / Resilience: sleep targets met, low substance use streaks, rest days respected
  • Balance: multi-domain completion (not just gym grind)

Implementation​

  • Database schema: CharacterStatIncrease table tracks daily increases
  • Service: CharacterService.calculateAndApplyStatIncrease() implements all features
  • Quality multipliers: CharacterService.calculateQualityMultiplier() handles quality assessment
  • Streak bonuses: CharacterService.calculateStreakBonus() calculates momentum bonuses

Features​

  • Daily caps: 50 points per stat per day
  • Diminishing returns: 100% → 75% → 50% → 25% for repeated identical actions
  • Anti-spam: Inputs must be valid (existing validation + ownership checks)
  • Streak bonuses: Daily login streak and reporting streak (1 point per 7 days, max 5 each) give "momentum" bonuses
  • Grace mechanic: Missing a day reduces momentum (2 point bonus for returning after 30+ day streak)
  • Quality multipliers:
    • Journaling: 2x for 3+ entries, 1.5x for 2 entries
    • Sleep: 1.5x for meeting bedtime targets
    • Training: 1.5x for RPE 8+, 1.25x for RPE 6-7
    • Reading: 1.5x for 50+ pages, 1.25x for 30+ pages

2. Battle Model​

Status: ✅ Complete

Architecture​

  • Turn-based system: Implemented in BattleService
  • Deterministic PRNG: BattleService.generateBattleSeed() creates seeds from userId + day + opponentId
  • SeededRandom class: Linear congruential generator for reproducible random numbers
  • Deterministic battles: Same seed = same result (verified in tests)

Combat Attributes​

Service: CharacterService.calculateCombatAttributes() calculates all combat attributes

Formulas:

  • Damage: Strength (70%) + Wisdom (30%)
  • Mitigation: Discipline (70%) + Balance (30%), capped at 75%
  • Speed: Balance (70%) + Discipline (30%)
  • Crit Chance: Wisdom (70%) + Strength (30%), capped at 50%
  • Crit Multiplier: Based on stat balance (1.5x to 3.0x)
  • Stamina: All stats combined (50-200 range)

Equipment Bonuses:

  • Based on rarity: COMMON +2%, RARE +5%, EPIC +10%, LEGENDARY +20%
  • Category bonuses: Different item categories boost different stats (swords→damage, armor→mitigation, etc.)

Battle Summary​

  • Service: BattleService.simulateBattle() implements deterministic turn-based battle system
  • Battle summary: Includes winner, duration, and key moments (critical hits, low stamina, etc.)
  • Expanded log: Detailed turn-by-turn breakdown with all combat details
  • Key moments tracking: Critical hits, low stamina warnings, victory/defeat
  • Test coverage: 10 comprehensive test cases covering all functionality

3. Scheduling & Cadence​

Status: ✅ Complete

Daily Fights​

  • 1-3 daily matchups: Generated automatically
  • Featured rival fight: Optionally includes one friend's character as an opponent (friends-only)
    • Only included when user has active friend links and numFights >= 2
    • Uses friend's actual character stats and combat attributes
    • Featured rival marked with star prefix (⭐) in opponent name
    • Randomly selected from active linked friends

Weekly Boss​

  • Boss rotates weekly: One boss per week (BossRotationService manages weekly rotations)
  • Unique mechanics: Tied to stat domains (Strength, Recovery, Wisdom, Balance)
  • Boss prep hints: Guide users to log relevant domain that week
  • Requires better preparation: Bosses are significantly harder than daily monsters

Weekly Ladder​

  • Database schema: LadderRank table tracks weekly rankings
  • Service: LadderService calculates weekly rankings based on battle performance
  • Composite scoring: Prioritizes win rate, then total battles, then coins earned
  • Weekly reward tiers: Rank-based rewards (Rank 1: 500 coins + 1000 XP, Rank 2: 300 coins + 600 XP, etc.)
  • Automatic weekly reset: Monday-based week boundaries

Battle Rewards & Bonuses​

Service: BattleService.getBattleStatus() returns battle availability and bonus information

Bonus System (not gating):

  • Battles are always available
  • Complete daily report: +50% coins and XP bonus
  • Perfect day (all checklist + all perimeter): +100% coins and XP bonus

Activity Rewards:

  • Checklist items: 10 XP + 1 coin per item
  • Training sessions: 100-500 XP + 5-10 coins
  • Reading sessions: 25 XP per 10 pages + 2 coins
  • Tasks: 15 XP + 1 coin
  • Journal entries: 50 XP + 3 coins
  • And more (see GamificationService for full list)

Late Logging Rule​

  • Allows claiming fights for past dates: Up to 7 days back
  • Diminishing rewards penalty: -10% per day late, minimum 50% of rewards
  • Prevents claiming future dates or dates beyond 7 days
  • Automatically generates fights for past dates when claiming

API Endpoints​

  • GET /gamification/ladder - Get weekly ladder rankings
  • GET /gamification/ladder/rank - Get user's current rank
  • POST /gamification/ladder/claim - Claim weekly ladder rewards
  • POST /gamification/ladder/calculate - Calculate weekly rankings

Test Coverage​

  • Comprehensive test coverage (28 test cases total)
  • Featured rival: 4 additional test cases
  • Late logging: 6 additional test cases
  • Weekly ladder: 10 service tests + 6 route tests

4. Rewards & Economy Integration​

Status: ✅ Complete

Reward Tables​

Service: RewardTableService centralizes reward definitions for all battle types

Reward Types:

  • Daily battle rewards: Win: 50 coins + 100 XP, Loss: 25 coins + 50 XP
  • Boss battle rewards: Win: 200-400 coins + 400-800 XP (with difficulty multipliers), Loss: 100-200 coins + 200-400 XP
  • Weekly ladder rewards: Rank-based tiers (Rank 1: 500 coins + 1000 XP, down to Rank 101+: 10 coins + 25 XP)

Integration:

  • BattleService.calculateBattleRewards() uses RewardTableService for base rewards
  • LadderService uses RewardTableService for weekly ladder rewards
  • Difficulty-based rewards for boss battles (easy: 0.5x, medium: 1.0x, hard: 1.5x, boss: 2.0x)

Test Coverage: 23 test cases for RewardTableService

Pity Timer System​

Database schema: PityTimer table tracks attempts without rare items per rarity tier

Service: PityTimerService manages pity timers with thresholds:

  • RARE: Guaranteed after 20 attempts
  • EPIC: Guaranteed after 50 attempts
  • LEGENDARY: Guaranteed after 100 attempts

Methods:

  • incrementPityTimer() - Increment timer for rarity tier
  • resetPityTimer() - Reset timer when rare item is obtained
  • isPityGuaranteed() - Check if pity is guaranteed
  • getGuaranteedRarity() - Get guaranteed rarity if any

API Route: GET /gamification/pity-timers - Get user's pity timer status

Test Coverage: 16 test cases

Duplicate Conversion System​

Database schema: DuplicateConversion table tracks conversion history

Service: DuplicateConversionService converts duplicate items to coins with rarity-based rates:

  • COMMON: 25% of original price
  • RARE: 50% of original price
  • EPIC: 75% of original price
  • LEGENDARY: 100% of original price

Features:

  • Prevents converting all items (must keep at least one)
  • Integrated with purchase system (duplicates are tracked when purchasing items you already own)

API Routes:

  • POST /gamification/inventory/:itemId/convert - Convert duplicates to coins
  • GET /gamification/inventory/:itemId/convert-value - Preview conversion value
  • GET /gamification/conversion-history - Get conversion history

Test Coverage: 13 test cases

Achievement Integration​

Service: BattleService.checkBattleAchievements() checks and unlocks battle-related achievements

Achievement Types:

  • Win streaks: Tracks consecutive wins and unlocks achievements at milestones (3, 5, 10, 20, 50, 100)
  • Boss kills: Tracks total boss kills and unlocks achievements at milestones (1, 5, 10, 25, 50, 100)
  • Rivalry wins: Tracks wins against friends (opponents with "⭐" prefix) and unlocks achievements at milestones (1, 5, 10, 25, 50, 100)
  • Seasonal champion: Unlocks when user achieves rank 1 on weekly ladder

Integration:

  • Achievement checking integrated into DailyClaimService.claimFight() and DailyClaimService.claimBossFight()
  • Achievement seed data: All battle achievements added to seed file (18 achievements total)

Test Coverage: 4 test cases covering all achievement types

Implementation Details​

Services​

  • CharacterService - Stat calculations, combat attributes
  • BattleService - Battle simulation, rewards, achievements
  • LadderService - Weekly ladder rankings and rewards
  • RewardTableService - Centralized reward definitions
  • PityTimerService - Pity timer management
  • DuplicateConversionService - Duplicate item conversion
  • DailyClaimService - Daily claim screen and fight claiming

Database Tables​

  • CharacterStatIncrease - Daily stat increases
  • LadderRank - Weekly ladder rankings
  • PityTimer - Pity timer tracking
  • DuplicateConversion - Conversion history

API Endpoints​

See individual sections above for specific endpoints.

Test Coverage​

  • Comprehensive test coverage across all services
  • All critical paths tested
  • Deterministic battle engine verified
  • Reward calculations verified
  • Achievement unlocking verified

5. Crafting Materials & Room Upgrades​

Status: ✅ Core Features Complete

Crafting Materials​

Materials from ARC Activities:

  • Focus shards: 1 per completed time block
  • Recovery cloth: 1 per quality sleep (7+ hours)
  • Knowledge ink: 1 per journal entry, 1 per 20 pages read

Database Schema:

  • MaterialLedger table tracks all material transactions (gains and losses)
  • MaterialService with methods to award, track, query, and consume materials

Material Usage:

  • Craft/upgrade gear: CraftingService implemented, craftables seeded (equipment, consumables, titles, auras, fun things, house upgrades)
  • Build/upgrade rooms: House upgrade craftables seeded, room upgrade functionality implemented (see House & Room System feature doc)
  • Craft consumables: Consumable craftables seeded (health potion, energy elixir, wisdom tonic, strength brew, discipline serum)
  • Trade/convert to currency: MaterialService.convertToCurrency() method converts materials to coins based on rarity (COMMON: 5, UNCOMMON: 10, RARE: 25, EPIC: 50, LEGENDARY: 100, SUPER_RARE: 200 coins per material)

API Routes:

  • GET /gamification/materials - Get user's material inventory
  • GET /gamification/materials/ledger - Get material transaction history
  • POST /gamification/materials/convert - Convert materials to coins

Test Coverage: 18 service tests (all passing), 7 test cases for currency conversion

Room Upgrades​

Implementation:

  • Room upgrade craftables (room_upgrade_basic, room_upgrade_advanced) consume materials and coins
  • applyRoomUpgrade method in HouseService consumes inventory items and upgrades rooms
  • Upgrade levels: 0 = basic, 1 = basic upgrade, 2 = advanced upgrade
  • Prevents downgrades (room must be below target upgrade level)

Frontend:

  • RoomDetailPage shows upgrade level, available upgrades, and apply functionality
  • Visual indicators for upgrade levels

Test Coverage: 9 test cases covering all scenarios

See docs/features/house-room-system.md for complete room system documentation.

Future Enhancements​

See docs/project/TODO.md for remaining work on:

  • Materials from background fighting (world-specific)
  • Social features (friends-only leaderboards, friend "ghosts")
  • Additional battle types and mechanics