Your privacy choices

We use necessary cookies, and others only if you allow them. You can change your mind at any time.

Family · 2 packages, one product
FF

Fancy Fun Lab

PHP + React · 2 packages

Gamification from your own analytics: XP per gamed metric, levels, achievements, prizes and leaderboards in Laravel, and React surfaces for profiles, per-metric boards and live level-ups.

UI+ BackendPHP · React
440 downloads this month1.8k downloads all-time
Browse 5 previews
UI surfaces1
5 component previews across 1 package

one shared contract
Backend · renders no UI1
install, then call the API
Everything in this family ships against one shared contract — install only the pieces your stack needs. Language mirrors behave identically, so you pick your backend and get the same product.

Engine

1 package · headless — install and call it · Gamification: XP, levels, achievements, prizes and leaderboards

laravel-fun-labPHP Backend · renders no UI440 downloads/mo

Analytics-driven gamification — XP, achievements, prizes, and leaderboards. Powers the sandbox's engagement economy.

$composer require particle-academy/laravel-fun-lab

React UI

1 package · component previews inside

fancy-fun-lab-uiReact UI surface 5 components

React surfaces for laravel-fun-lab, built from react-fancy: a profile summary with per-metric levels, a leaderboard by XP, achievements or prizes (overall or for one gamed metric, over a period), an achievement grid, a live XP feed and a level-up announcement. Controlled, fed the Fun Lab REST API's own shapes, with rate-limited polite announcements and RTL. Pairs with particle-academy/laravel-fun-lab.

$npm install @particle-academy/fancy-fun-lab-ui
Why
Gamification frameworks are either toy-tier (single XP bucket, no analytics) or tied to heavyweight proprietary platforms (license costs, vendor lock). Without a proper system, apps repeat the same archetype work: building out multiple reward types, tracking user activity, and computing leaderboards from scratch. Laravel Fun Lab inverts the problem: it's built to capture the structured activity data lying beneath engagement mechanics — XP awards are observable events that feed behavioral insights, not just cosmetics.
What
The package ships two facades: LFL for setup and awards (fluent builders for award() and grant()), and the Awardable trait that grafts gamification onto any Eloquent model. Core primitives are GamedMetric (independent XP buckets), MetricLevel (thresholds), MetricLevelGroup (composite leveling via weighted metrics), Achievement, and Prize. Every mutation triggers observable events; Profile tracks totals and relationships. REST API and web routes surface profiles, leaderboards, and analytics queries. Broadcasting support (Laravel Echo) powers real-time updates.
How
composer require particle-academy/laravel-fun-lab then php artisan lfl:install. Add Awardable to your model, set up metrics and levels via LFL::setup(a: 'gamed-metric', with: ['slug' => 'combat-xp']), then award with LFL::award('combat-xp')->to($user)->amount(50)->because('defeated boss')->save(). Query via LFL::leaderboard() and LFL::analytics() or check a model's profile directly: $user->getXpFor('combat-xp'), $user->hasAchievement('first-login').
readmeShared model & API — README.md

Laravel Fun Lab

Fancified

Powered by Tynn Latest Version Total Downloads License Laravel

Analytics disguised as gamification — turn user activity into meaningful engagement insights.

Laravel Fun Lab (LFL) is an analytics-driven gamification layer for Laravel applications. Track user engagement through XP, achievements, and prizes while capturing structured activity data that apps normally never track.

For agents. This package is listed on the Fancy MCP catalog server at https://ui.particle.academy/mcp (streamable HTTP, no API key; MCP id fancy-ui), with install commands and docs, alongside the rest of the kit. How an agent installs and uses this package is in AGENTS.md.

Features

  • 🎯 Event-Driven Architecture - Every action, reward, or update is an observable event
  • 🎮 GamedMetrics XP System - Create independent XP buckets with automatic level progression
  • 📊 MetricLevelGroups - Combine multiple XP metrics with weights for composite leveling
  • 🏆 Achievements - Define and grant achievements with auto-unlock on level-up
  • 🎁 Prizes - Reward users with virtual or physical prizes
  • 📈 Built-in Analytics - Query aggregate engagement data for behavioral insights
  • 🔌 Extensible - Macros, hooks, and custom implementations
  • ⚡ Drop-In Simple - Install → Track → Award workflow

Installation

composer require particle-academy/laravel-fun-lab
php artisan lfl:install

Quick Start

1. Add the Awardable Trait

Add the Awardable trait to any model you want to gamify:

use LaravelFunLab\Traits\Awardable;

class User extends Authenticatable
{
    use Awardable;
}

// Works with any model!
class Team extends Model
{
    use Awardable;
}

The Awardable trait gives your model a Profile that tracks XP, achievements, and prizes.

2. Create GamedMetrics (XP Categories)

GamedMetrics are independent XP buckets. Each metric tracks its own XP and levels:

use LaravelFunLab\Facades\LFL;

// Create XP categories
LFL::setup(a: 'gamed-metric', with: ['slug' => 'combat-xp', 'name' => 'Combat XP']);
LFL::setup(a: 'gamed-metric', with: ['slug' => 'crafting-xp', 'name' => 'Crafting XP']);
LFL::setup(a: 'gamed-metric', with: ['slug' => 'social-xp', 'name' => 'Social XP']);

3. Define Levels for Metrics

Levels are XP thresholds that can auto-unlock achievements:

// Define levels for combat-xp
LFL::setup(a: 'metric-level', with: ['metric' => 'combat-xp', 'level' => 1, 'xp' => 0, 'name' => 'Novice']);
LFL::setup(a: 'metric-level', with: ['metric' => 'combat-xp', 'level' => 2, 'xp' => 100, 'name' => 'Apprentice']);
LFL::setup(a: 'metric-level', with: ['metric' => 'combat-xp', 'level' => 3, 'xp' => 500, 'name' => 'Warrior']);
LFL::setup(a: 'metric-level', with: ['metric' => 'combat-xp', 'level' => 4, 'xp' => 1000, 'name' => 'Champion']);

4. Award XP

Award XP using the fluent award() method:

// Award XP to a specific GamedMetric
LFL::award('combat-xp')
    ->to($user)
    ->amount(50)
    ->because('defeated boss')
    ->save();

// Check the profile
$profile = $user->getProfile();
echo $profile->total_xp; // Total XP across all metrics

5. Create and Grant Achievements

// Create an achievement
LFL::setup(a: 'achievement', with: ['slug' => 'first-login', 'name' => 'First Login', 'description' => 'Welcome!', 'icon' => 'star']);

// Grant the achievement
LFL::grant('first-login')
    ->to($user)
    ->because('completed onboarding')
    ->save();

// Check if user has an achievement
if ($user->hasAchievement('first-login')) {
    // ...
}

6. Create and Grant Prizes

// Create a prize
LFL::setup(
    a: 'prize',
    with: [
        'slug' => 'premium-access',
        'name' => '1 Month Premium Access',
        'type' => 'virtual',
        'inventory' => 100, // Limited quantity
    ]
);

// Grant the prize
LFL::grant('premium-access')
    ->to($user)
    ->because('won monthly contest')
    ->save();

7. Check Level Progress

// Check if user has reached a specific level in a metric
if (LFL::hasLevel($user, 3, metric: 'combat-xp')) {
    echo "You're a Warrior!";
}

// Check level in a metric group
if (LFL::hasLevel($user, 10, group: 'overall-power')) {
    echo "You've reached Overall Power Level 10!";
}

8. Create Metric Level Groups

Combine multiple metrics with weights for composite leveling:

// Create a group
LFL::setup(a: 'metric-level-group', with: ['slug' => 'overall-power', 'name' => 'Overall Power']);

// Add metrics to the group with weights
LFL::setup(a: 'metric-level-group-metric', with: ['group' => 'overall-power', 'metric' => 'combat-xp', 'weight' => 1.0]);
LFL::setup(a: 'metric-level-group-metric', with: ['group' => 'overall-power', 'metric' => 'crafting-xp', 'weight' => 0.5]);

// Define levels for the group
LFL::setup(a: 'metric-level-group-level', with: ['group' => 'overall-power', 'level' => 1, 'xp' => 0, 'name' => 'Beginner']);
LFL::setup(a: 'metric-level-group-level', with: ['group' => 'overall-power', 'level' => 10, 'xp' => 5000, 'name' => 'Expert']);

9. Leaderboards

// Get top users by XP
$leaders = LFL::leaderboard()
    ->for(User::class)
    ->by('xp')
    ->take(10);

API Summary

Method Purpose
LFL::setup() Create GamedMetrics, MetricLevels, MetricLevelGroups, Achievements, Prizes
LFL::award($metric) Award XP to a GamedMetric (fluent builder)
LFL::grant($slug) Grant an Achievement or Prize (fluent builder)
LFL::hasLevel($user, $level, metric: or group:) Check if user has reached a level
LFL::profile($user) Get the user's gamification profile
LFL::leaderboard() Build leaderboard queries
LFL::analytics() Build analytics queries

Documentation

Requirements

  • PHP 8.4+
  • Laravel 13.x

License

MIT License - see LICENSE for details.


⭐ Star Fancy Dev Kit

If this package is useful to you, a quick ⭐ on the repo really helps us build a better kit. Thank you!

What next
Open a surface and click any component for a live demo with source.