Games API

The Games API manages game sessions, scoring, progression, and the demo system in PadawanForge.

Base Paths

  • /api/game-sessions/ - Game session management
  • /api/sessions/ - Session lifecycle operations
  • /api/demo/ - Demo system for anonymous users

Game Sessions

List Game Sessions

GET /api/game-sessions

Authentication: Required

Query Parameters:

  • page (optional) - Page number (default: 1)
  • limit (optional) - Items per page (default: 20)
  • status (optional) - Filter by status: active, completed, abandoned
  • difficulty (optional) - Filter by difficulty: easy, medium, hard

Response:

{
  "items": [
    {
      "id": "session_uuid",
      "playerId": "player_uuid",
      "status": "completed",
      "difficulty": "medium",
      "startTime": "2024-01-20T15:00:00Z",
      "endTime": "2024-01-20T15:07:00Z",
      "duration": 420,
      "score": 850,
      "correctAnswers": 12,
      "totalQuestions": 15,
      "accuracy": 0.8,
      "bestStreak": 8,
      "experienceGained": 75
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}

Get Game Session

GET /api/game-sessions/[id]

Authentication: Required

Parameters:

  • id - Game session UUID

Response:

{
  "id": "session_uuid",
  "playerId": "player_uuid",
  "status": "completed",
  "difficulty": "medium",
  "startTime": "2024-01-20T15:00:00Z",
  "endTime": "2024-01-20T15:07:00Z",
  "duration": 420,
  "score": 850,
  "correctAnswers": 12,
  "totalQuestions": 15,
  "accuracy": 0.8,
  "bestStreak": 8,
  "streakMultiplier": 1.6,
  "experienceGained": 75,
  "statements": [
    {
      "id": "stmt_1",
      "text": "The Great Wall of China is visible from space.",
      "correctAnswer": false,
      "playerAnswer": false,
      "isCorrect": true,
      "timeSpent": 3.2,
      "difficulty": "medium",
      "category": "history",
      "points": 100
    }
  ],
  "progressData": {
    "questionsAnswered": 15,
    "timeRemaining": 0,
    "currentStreak": 0,
    "hotStreakActive": false,
    "coldStreakActive": false
  }
}

Session Management

Create Session

POST /api/sessions/create

Authentication: Required

Request Body:

{
  "difficulty": "easy" | "medium" | "hard",
  "duration": 420,
  "categories": ["history", "science", "literature"],
  "customSettings": {
    "enableHints": true,
    "timerVisible": true,
    "streakBonuses": true
  }
}

Response:

{
  "success": true,
  "data": {
    "sessionId": "session_uuid",
    "duration": 420,
    "difficulty": "medium",
    "startTime": "2024-01-20T15:00:00Z",
    "statements": [
      {
        "id": "stmt_1",
        "text": "Water boils at 100°C at sea level.",
        "difficulty": "easy",
        "category": "science"
      }
    ]
  }
}

Complete Session

POST /api/sessions/[id]/complete

Authentication: Required

Parameters:

  • id - Session UUID

Request Body:

{
  "answers": [
    {
      "statementId": "stmt_1",
      "answer": true,
      "timeSpent": 3.2
    },
    {
      "statementId": "stmt_2", 
      "answer": false,
      "timeSpent": 2.8
    }
  ],
  "endTime": "2024-01-20T15:07:00Z",
  "finalScore": 850
}

Response:

{
  "success": true,
  "data": {
    "sessionId": "session_uuid",
    "finalScore": 850,
    "accuracy": 0.8,
    "correctAnswers": 12,
    "totalQuestions": 15,
    "bestStreak": 8,
    "experienceGained": 75,
    "levelUp": false,
    "achievements": [
      {
        "id": "accuracy_master",
        "name": "Accuracy Master",
        "description": "Achieve 80% accuracy in a session"
      }
    ],
    "leaderboardPosition": 15
  }
}

Restore Session

POST /api/sessions/[id]/restore

Authentication: Required

Parameters:

  • id - Session UUID

Response:

{
  "success": true,
  "data": {
    "sessionId": "session_uuid",
    "progress": {
      "questionsAnswered": 8,
      "timeRemaining": 200,
      "currentScore": 560,
      "currentStreak": 4
    },
    "nextStatements": [
      {
        "id": "stmt_9",
        "text": "Shakespeare wrote Romeo and Juliet.",
        "difficulty": "medium",
        "category": "literature"
      }
    ]
  }
}

Cleanup Sessions

POST /api/sessions/cleanup

Authentication: Admin required

Response:

{
  "success": true,
  "data": {
    "cleanedSessions": 150,
    "cleanupType": "abandoned_sessions",
    "olderThan": "2024-01-15T00:00:00Z"
  }
}

Demo System

Create Demo Session

POST /api/demo/session

No authentication required

Request Body:

{
  "difficulty": "easy" | "medium" | "hard",
  "preferredCategories": ["science", "history"]
}

Response:

{
  "success": true,
  "data": {
    "sessionId": "demo_session_uuid",
    "guestToken": "guest_token",
    "expiresAt": "2024-01-21T15:00:00Z",
    "difficulty": "medium",
    "maxDuration": 420,
    "remainingDemoTime": 3600,
    "canConvert": true
  }
}

Get Demo Session

GET /api/demo/[sessionId]

Authentication: Guest token required

Parameters:

  • sessionId - Demo session UUID

Response:

{
  "sessionId": "demo_session_uuid",
  "status": "active",
  "progress": {
    "gamesPlayed": 3,
    "bestScore": 720,
    "totalExperience": 125,
    "timeRemaining": 3200
  },
  "stats": {
    "accuracy": 0.75,
    "averageTime": 2.5,
    "bestStreak": 6
  },
  "expiresAt": "2024-01-21T15:00:00Z",
  "canConvert": true
}

Generate Demo Content

POST /api/demo/[sessionId]/generate

Authentication: Guest token required

Request Body:

{
  "category": "science",
  "difficulty": "medium",
  "count": 10
}

Response:

{
  "success": true,
  "data": {
    "statements": [
      {
        "id": "demo_stmt_1",
        "text": "Light travels faster than sound.",
        "category": "science",
        "difficulty": "easy"
      }
    ],
    "sessionUpdated": "2024-01-20T15:15:00Z"
  }
}

Complete Demo Session

POST /api/demo/[sessionId]/complete

Authentication: Guest token required

Request Body:

{
  "answers": [
    {
      "statementId": "demo_stmt_1",
      "answer": true,
      "timeSpent": 2.5
    }
  ],
  "finalScore": 650
}

Response:

{
  "success": true,
  "data": {
    "score": 650,
    "accuracy": 0.8,
    "experienceGained": 45,
    "newBestScore": true,
    "conversionOffer": {
      "available": true,
      "benefitsPreserved": ["experience", "best_scores", "achievements"],
      "additionalBenefits": ["permanent_progress", "social_features", "advanced_customization"]
    }
  }
}

Convert Demo to Account

POST /api/demo/convert

Authentication: Guest token required

Request Body:

{
  "username": "NewPlayer",
  "email": "player@example.com",
  "oauthProvider": "google",
  "oauthCode": "oauth_authorization_code"
}

Response:

{
  "success": true,
  "data": {
    "playerId": "new_player_uuid",
    "preservedData": {
      "experience": 125,
      "bestScore": 720,
      "gamesPlayed": 3,
      "achievements": ["first_game", "accuracy_novice"]
    },
    "sessionToken": "full_account_session_token",
    "redirectTo": "/dashboard"
  }
}

Demo Analytics

GET /api/demo/analytics

Authentication: Admin required

Query Parameters:

  • startDate (optional) - Start date for analytics
  • endDate (optional) - End date for analytics
  • groupBy (optional) - Group by: day, week, month

Response:

{
  "summary": {
    "totalDemoSessions": 1250,
    "conversionRate": 0.15,
    "averageSessionDuration": 380,
    "popularCategories": ["science", "history", "literature"]
  },
  "metrics": [
    {
      "date": "2024-01-20",
      "demoSessions": 45,
      "conversions": 7,
      "averageScore": 680,
      "dropoffPoints": {
        "registration": 0.3,
        "firstGame": 0.1,
        "secondGame": 0.05
      }
    }
  ]
}

Scoring System

Score Calculation

  • Base Points: 100 per correct answer
  • Time Bonus: Faster answers get up to 50% bonus
  • Streak Multiplier: Hot streaks multiply points by up to 2x
  • Difficulty Bonus: Harder questions give 25-50% more points

Streak System

  • Hot Streak: 3+ consecutive correct answers
  • Cold Streak: 3+ consecutive incorrect answers
  • Streak Multiplier: Increases with streak length (max 2x)
  • Streak Recovery: Cold streaks reduce multiplier

Experience System

  • Base XP: 5 XP per correct answer
  • Completion Bonus: 25 XP for finishing session
  • Performance Bonus: Up to 50 XP for high accuracy
  • Level Up: Every 1000 XP increases level

Error Responses

Session Not Found

{
  "error": "Session not found",
  "details": "No active session found with the provided ID"
}

Demo Expired

{
  "error": "Demo session expired",
  "details": "Demo sessions are limited to 24 hours",
  "canCreateNew": true
}

Invalid Answers

{
  "error": "Invalid answer format",
  "details": "Answer must be true or false"
}

Session Already Completed

{
  "error": "Session already completed",
  "details": "Cannot modify completed session"
}

Rate Limits

  • Session creation: 10 per hour per user
  • Demo sessions: 5 per IP per hour
  • Session completion: No limit (expected behavior)
  • Demo conversion: 3 attempts per demo session

Implementation Notes

  1. Session Persistence: Active sessions stored in memory with periodic database saves
  2. Demo Isolation: Demo data isolated from main player data until conversion
  3. Anti-Cheat: Server-side validation of answer timing and patterns
  4. Progressive Difficulty: AI adjusts statement difficulty based on player performance
  5. Data Recovery: Sessions can be restored if interrupted (5-minute window)
← AI Tools Catalog API NPC API →
PadawanForge v1.4.1