🕹️ Agent Arcade — Mini-Games & Leaderboards Guide

Overview

Agent Arcade is a between-call entertainment module. Each game is a self-contained HTML file that runs in a sandboxed iframe inside the CRM. Sessions are 30-90 seconds. Scores post to the leaderboard automatically on session end. Personal stats track total points, daily streak, today rank, and per-game personal bests.

Three sub-tabs: Arcade (game grid), Leaderboards (per-game + combined ranking with day/week/month/all-time toggles), and My Stats (personal totals + per-game best score history). Hero region surfaces the week's top combined player.

What's new in V2

The five games

Leaderboards

Two leaderboard types, four time windows.

Per-game leaderboards

For each game, every player's best score in the period is the entry. Each player appears once per leaderboard. Top 10 by default (engine supports up to 50). Ties break by earliest-first-play in the period.

Combined cross-game leaderboard

For each game, your best score is normalized to a percentile of the top score in that game (100 = you're the top scorer, 50 = you're at half the top score, 0 = no plays). Your combined score is the average percentile across games you've played in the period.

Why percentile-of-best instead of raw score? Different games have wildly different score scales — Tile Stack hits 4-digit cumulative scores, Reflex Pop tops out around 1000. A raw-score combined would be dominated by whichever game scores highest. Percentile-of-best normalizes the playing field.

Why average instead of sum? Sum penalizes new players who haven't played all five games. Average means "of the games you played, how good are you compared to the field?" New players still see themselves on the board after their first game.

Time windows

• Today — sessions where DATE(start_time) = CURDATE()
• This Week — YEARWEEK(start_time, 1) = YEARWEEK(CURDATE(), 1) (ISO week, Monday start)
• This Month — DATE_FORMAT(start_time, '%Y-%m') = CURDATE() month
• All Time — every completed session, no date filter

Personal stats

The My Stats tab shows everything tracked on arcade_player_stats for the current user, plus computed fields:

• Total points — cumulative score across every completed session, all-time
• Games played — total completed sessions, all-time
• High score — best single-session score across any game
• Daily streak — consecutive days with at least one play
• Today rank — your position on the combined leaderboard for today
• This week rank — your position on the combined leaderboard for this week
• Per-game best — your top score for each of the five games (all-time)

What's not included (by design)

Arcade stays focused. Here's what's deliberately out of scope, and why each call keeps the module simple to run:

Quick start ≈ 5 minutes

1. Activate the module at RubiMine. $49.99 / mo, flat — no per-seat fees.
2. Sysadmin verifies schema at /admin/run-arcade-v2-migration.php. All 3 tables (arcade_games, arcade_game_sessions, arcade_player_stats) should show ✅.
3. Seed the V2 catalog from the same page (or view-arcade-state.php). Picks tenant, clicks Seed catalog. Five games inserted. Idempotent.
4. Open the Arcade tab in the CRM as any agent. Five game cards appear with category-colored art.
5. Play a game. Click any card. Game launches in a modal iframe. Play your 30-90 seconds. Score posts on session end.
6. Check the leaderboard. Switch to Leaderboards. Toggle per-game vs combined. Pick a period.

API endpoints

All on /crm/api/arcade.php. Session-authenticated, tenant-scoped. JSON request + response.

POST action=list_games
POST action=start_session       (game_code)                      → { session_code }
POST action=end_session         (session_code, score, meta?)      → { ok, score, rank_today, is_new_highscore, previous_best }
POST action=leaderboard         (game_code, period?, limit?)      → top players for one game
POST action=combined_leaderboard (period?, limit?)                → cross-game percentile ranking
POST action=weekly_highlight                                       → top combined player this week
POST action=personal_stats                                         → caller's full stats bundle

Period values: day, week, month, all. meta on end_session accepts level / accuracy / combo / duration_seconds for replay analysis (stored on the session row).

Building custom games

Each game is a standalone HTML file in /crm/modules/arcade/games/. The Arcade SDK gives you a postMessage bridge to the parent CRM.

Minimal game template

<!DOCTYPE html>
<html><head>
<link rel="stylesheet" href="/crm/modules/arcade/games/_shared/arcade.css">
<script src="/crm/modules/arcade/games/_shared/arcade-sdk.js"></script>
</head><body>
<script>
async function start() {
  const { sessionCode } = await ArcadeSDK.start('my-game-code');
  // ... game runs ...
  let finalScore = 1234;
  ArcadeSDK.live(finalScore);            // updates parent ticker mid-round
  const result = await ArcadeSDK.end(finalScore, { level: 5, duration_seconds: 60 });
  // result = { ok, score, rank_today, is_new_highscore, previous_best }
}
start();
</script>
</body></html>

Registering the game

Insert a row in arcade_games for the tenant:

INSERT INTO arcade_games
    (tenant_id, game_name, game_code, description, category, icon,
     scoring_type, time_limit_seconds, display_order, is_active, is_new)
VALUES
    (?, 'My Game', 'my-game-code', '...', 'arcade', 'fa-star',
     'points', 60, 99, 1, 1);

The module's game grid will pick up the new row on next load. V2.1 will add a tenant-admin custom-game registration UI — for now, raw SQL or a one-off engine call from a sysadmin script.

Known limitations (V2)

• No anti-cheat — the score on end_session is whatever the client sends. A motivated agent could DevTools-edit their submission. Acceptable trade-off for a break-room module; not appropriate for high-stakes competition.
• No multiplayer — every game is single-player. Leaderboards are the social layer. Real-time multiplayer is not on the V2.1 roadmap.
• No mobile-app integration — games are browser-only, designed for desktop work. They render on mobile but small touch targets in Reflex Pop and the on-screen keyboard for Word Rush are not optimized.
• No sound effects — by-design for a work environment. Adding optional in-game audio is V2.1.
• Custom games via SQL — no UI to add a custom game without raw INSERT. V2.1 ships a tenant-admin form.
• No replay system — meta fields on session row store level / accuracy / combo / duration but there's no UI to scrub past sessions.

Frequently asked questions