XOGrid Official Documentation

Welcome to XOGrid - Multiplayer Tic-Tac-Toe. This is a highly scalable, real-time multiplayer gaming system built with Vanilla JavaScript, PHP, and MySQL. It completely avoids the high server costs of WebSockets by utilizing an advanced Atomic Polling Engine and direct WebRTC for peer-to-peer video streaming.

Key Enterprise Features:

• WebRTC P2P Video: Players can see each other via direct camera feeds without straining your server bandwidth.
• Smart Bot Injection: If no human opponent is found, the server seamlessly injects a challenging AI.
• ELO Rank System: Players progress from "Iron" to "Legend" based on their win/loss ratios.
• Glassmorphism UI: A premium, fully responsive interface devoid of intrusive native browser alerts.
• Automated Installer: Deploy the entire database structure in seconds via a visual setup wizard.

• Web Server: Apache, Nginx, or LiteSpeed (Compatible with standard shared hosting environments).
• PHP Version: PHP 7.4 or higher (PHP 8.0+ recommended for best performance).
• Database: MySQL 5.7+ or MariaDB.
• PHP Extensions: PDO, pdo_mysql, json.

Deploying your game is incredibly easy thanks to the included automated setup wizard. Follow these steps:

1. Upload Files: Extract the provided ZIP file and upload all contents to your public web directory (e.g., public_html or htdocs) using FTP or your hosting's File Manager.
2. Create Database: Go to your hosting control panel (cPanel, hPanel, etc.) and create a new MySQL Database. Write down the Database Name, Database User, and Password.
3. Run Installer: Open your browser and navigate to the installer file:
   
   https://yourdomain.com/install.php
4. Execute: Enter the database credentials into the elegant setup UI and click "INSTALL NOW". The script will automatically generate the db.php connection file and build all required SQL tables.
5. Security Auto-Cleanup: IMPORTANT! For enterprise-grade security, the install.php script is programmed to automatically delete itself after a successful setup to prevent Remote Code Execution (RCE) attacks. Please verify via your File Manager that the file was successfully removed. If your server permissions blocked the auto-deletion, you MUST delete it manually!

To ensure server health and handle disconnected players, you must configure a Cron Job. The cron_cleanup.php script acts as an automated referee, resolving "Walkovers" (W.O.) if a player closes their browser mid-game.

In your hosting control panel, add a new Cron Job to run Every Minute (* * * * *):

/usr/local/bin/php /home/YOUR_USERNAME/public_html/cron_cleanup.php >/dev/null 2>&1

Note: Adjust the absolute path according to your specific server configuration (e.g., replacing YOUR_USERNAME).

A. Atomic Matchmaking (server.php)

To prevent race conditions where two players might accidentally join the same room slot simultaneously, the matchmaking engine uses MySQL transactional row-level locking (FOR UPDATE).

// server.php - Safe Matchmaking Logic
$pdo->beginTransaction();
try {
    // Locks the row exclusively for this specific request
    $stmt = $pdo->prepare("SELECT id FROM rooms WHERE status = 'waiting' AND player_o_id IS NULL LIMIT 1 FOR UPDATE");
    $stmt->execute();
    $publicRoom = $stmt->fetchColumn();
    
    // Safely assign player to the locked room
    if ($publicRoom) {
        $pdo->prepare("UPDATE rooms SET player_o_id = ?, status = 'playing' WHERE id = ?")->execute([$playerId, $publicRoom]);
        $pdo->commit();
    }
} catch (Exception $e) {
    $pdo->rollBack();
}

B. Server-less WebRTC Signaling (sinalizar.php & main.js)

Traditional WebRTC requires expensive Node.js/WebSocket servers for SDP signaling. This system bypasses that by using high-frequency AJAX polling through standard PHP and MySQL, dropping old signals every 30 seconds to keep the database hyper-light.

C. Security: CSPRNG Session Tokens (login.php)

Instead of relying on fragile cookies, the game issues a Cryptographically Secure Pseudo-Random Number Generator (CSPRNG) token stored in the user's LocalStorage. This prevents session hijacking.

D. Enterprise Security Standards (Marketplace Approved)

This system was built passing the strictest marketplace security reviews, featuring:

• Controller/Router Pattern: The backend API completely avoids monolithic `switch` statements, using a clean, scalable Object-Oriented Controller pattern.
• XSS Protection: Zero reliance on insecure `strip_tags()`. All user-generated content is rigorously sanitized using `htmlspecialchars` with `ENT_QUOTES` and `filter_var`.
• RCE Prevention: The database configuration generator escapes all inputs using `var_export()` to completely neutralize Remote Code Execution payloads.
• Unminified Source: The core logic (`main.js`) is fully documented with internal English comments, avoiding obfuscation to allow for transparent audits.

You have full control over the game's economy, penalties, and timers. Below is a guide on where to find and modify these settings.

A. Changing XP Rewards and Penalties

XP calculations are handled on the backend to prevent cheating. You need to modify two files to completely change the scoring system: server.php and cron_cleanup.php.

In server.php: Search for the UPDATE users SET queries inside the get_state and leave_room cases.

// Example: Winning a match (Currently +15 XP)
$pdo->prepare("UPDATE users SET wins = wins + 1, xp = xp + 15 WHERE id = ?");

// Example: Losing via timeout/yellow cards (Currently -20 XP)
// GREATEST(0, ...) ensures XP never drops below 0
$pdo->prepare("UPDATE users SET abandons = abandons + 1, xp = GREATEST(0, xp - 20) WHERE id = ?");

In cron_cleanup.php: This file handles players who force-close their browsers. Search for the penalty section.

// Penalty for disconnecting (Currently -30 XP)
$pdo->prepare("UPDATE users SET abandons = abandons + 1, xp = GREATEST(0, xp - 30) WHERE id = ?");

B. Adjusting Turn Timers

By default, players have 10 seconds to make a move before receiving a "Yellow Card" (3 yellow cards result in a forfeit/loss). You can increase or decrease this time in server.php.

// Open server.php and find this line near the top:
$MAX_TURN_TIME = 10; // Change 10 to any number of seconds you prefer

C. Matchmaking & Bot Injection Timers

When searching for a match, the system waits for a real player before injecting an AI Bot. You can modify this countdown in main.js.

// Open main.js and find the startDirectMatch function:
let searchTimer = 59; // Total time the search UI displays

// Inside the setInterval, look for:
if (searchTimer === 35) {
    // This injects the bot when the timer hits 35 seconds
    fetch(`server.php?action=add_bot_by_player...`); 
}

D. Modifying Ranks & Trophies

The ELO system promotes players based on their Total Wins. You can change the required wins or the Rank names inside main.js.

Search for the viewProfile function and the getRankColor function:

// In main.js - Change the 'min' value to adjust required wins
const ranks = [
    { name: 'Iron', min: 0 }, 
    { name: 'Aluminum', min: 100 }, 
    { name: 'Copper', min: 200 },
    { name: 'Silver', min: 400 }, 
    { name: 'Gold', min: 800 }, 
    { name: 'Platinum', min: 1600 },
    { name: 'Diamond', min: 3200 }, 
    { name: 'Master', min: 6400 }, 
    { name: 'Legend', min: 12800 }
];

Translating the Game

The entire interface is translation-ready. Open lang.js and simply modify the string values inside the LANG constant object. The system will automatically apply these changes to the UI.

const LANG = {
    documentTitle: "XOGrid - Multiplayer Tic-Tac-Toe",
    loginBtn: "LOGIN NOW",
    arenaBtn: "ENTER THE ARENA",
    // ... modify any string here
};

Changing Theme Colors

Open style.css. At the very top, you will find the CSS root variables. Edit these HEX codes to rebrand the application instantly without touching the core code.

:root { 
    --bg-dark: #1a1a24; 
    --bg-light: #3a3a4f;
    --primary: #670185; /* Main Button Color */
    --success: #28a745; 
}

If you encounter any bugs, database structural issues, or require assistance setting up your environment, please reach out directly via email. When requesting support, kindly provide:

• Your PHP version.
• A link to your live installation.
• Screenshots of any errors in the browser console (F12).