Chat API — Ruleta

Backend PHP + MySQL para el sistema de chat del juego de ruleta (Godot 4). Simula tiempo real mediante long-polling, sin WebSockets, compatible con hosting compartido HostGator.

Componentes del sistema

Estructura del proyecto

Requisitos

Pasos de instalación

1. Crear base de datos en cPanel
   Ve a cPanel → MySQL® Databases. Crea una base de datos, un usuario y asígnalo con todos los permisos. Anota el nombre de la BD, usuario y contraseña.
2. Importar el schema
   En phpMyAdmin, selecciona tu base de datos, ve a la pestaña Importar y sube schema.sql. Esto crea las tablas chat_messages y banned_players.
3. Editar config.php
   Llena las credenciales de BD y genera las API keys con OpenSSL (ver sección Configuración).
4. Subir archivos
   Sube la carpeta chat-api/ completa a public_html/ via FTP o el Administrador de archivos de cPanel.

   public_html/
   └── chat-api/   ← aquí

5. Verificar permisos
   Asegúrate de que config.php tenga permisos 644 y que .htaccess esté presente en la raíz de chat-api/.
6. Probar el endpoint
   Abre en el navegador: https://tudominio.com/chat-api/api/get_messages.php?wait=0
   Respuesta esperada: {"ok":true,"since_id":0,"messages":[]}

Configuración — config.php

// Base de datos
define('DB_HOST', 'localhost');
define('DB_NAME', 'cpanelusr_chat');
define('DB_USER', 'cpanelusr_chatuser');
define('DB_PASS', 'tu_password');

// Genera con: openssl rand -hex 32
define('SYSTEM_API_KEY', 'clave_servidor_juego');  // ← servidor Godot
define('ADMIN_API_KEY',  'clave_moderacion');     // ← endpoints REST de moderación

// Contraseña del panel web admin
define('ADMIN_WEB_PASSWORD', 'contrasena_panel_web');

// Long-polling
define('LONG_POLL_TIMEOUT',  25);    // segundos máximo de espera
define('LONG_POLL_INTERVAL', 0.75); // segundos entre consultas a BD

Generar API keys seguras

# En terminal (Linux/Mac/WSL):
openssl rand -hex 32

# Salida de ejemplo:
a3f7c2e891b04d56f2a8e3c7b1d94f20e5a6b8c3d7e2f1a4b9c6d8e3f2a1b5c4

Esquema SQL

Importar schema.sql en phpMyAdmin. Crea dos tablas:

CREATE TABLE chat_messages (
    id         INT UNSIGNED    NOT NULL AUTO_INCREMENT,
    type       VARCHAR(20)     NOT NULL,
    sender     VARCHAR(100)    NOT NULL,
    text       TEXT            NOT NULL,
    data       JSON                NULL,
    created_at DOUBLE          NOT NULL,  -- microtime(true)
    PRIMARY KEY (id)
);

CREATE TABLE banned_players (
    id           INT UNSIGNED  NOT NULL AUTO_INCREMENT,
    player_id    VARCHAR(100)  NOT NULL,
    reason       VARCHAR(255)      NULL,
    banned_at    DATETIME      NOT NULL DEFAULT CURRENT_TIMESTAMP,
    banned_until DATETIME          NULL,  -- NULL = permanente
    PRIMARY KEY (id),
    UNIQUE KEY (player_id)
);

Tablas

chat_messages

banned_players

Cómo funciona el long-polling

HostGator no soporta WebSockets en hosting compartido. Esta API los simula manteniendo la conexión HTTP abierta hasta 25 segundos:

El cliente debe reconectarse inmediatamente al recibir cada respuesta, usando el id más alto recibido como nuevo since_id.

Short-polling (alternativa ligera)

Para reducir carga del servidor con muchos jugadores, usa ?wait=0 y llama cada 2-3 segundos:

GET /api/get_messages.php?since_id=42&wait=0

Endpoints públicos Sin auth

// Respuesta
{
  "ok": true,
  "since_id": 0,
  "messages": [
    {
      "id": 1,
      "type": "CHAT",
      "sender": "Juan",
      "text": "¡Buena suerte!",
      "data": {},
      "created_at": 1718200000.123
    }
  ]
}

// Body JSON
{ "player_id": "maria_92", "text": "¡Hola a todos!" }

Endpoints del sistema SYSTEM_API_KEY

Todos usan POST a api/system_message.php con el campo action. Requieren el header X-API-Key: SYSTEM_API_KEY.

Ejemplos

// Apuesta
{ "action": "bet", "player_id": "maria_92", "selection": "Rojo", "cash": "100.00" }

// Premio destacado
{ "action": "prize_top", "player_name": "Carlos", "prize": "500.00" }

// Total de premios de la ronda
{ "action": "prize_total", "total_prizes": "1234.50" }

// Propina
{ "action": "tip", "player_nickname": "Pedro", "tip": "25.00" }

Endpoints de moderación ADMIN_API_KEY

Autenticación

La API key puede enviarse por cualquiera de estas tres vías (en orden de prioridad):

Formato de respuestas

Todas las respuestas son JSON con la forma {"ok": true, ...} o {"ok": false, "error": "..."}.

// Éxito
{ "ok": true, "message": { ... } }

// Error
{ "ok": false, "error": "Descripción del error." }

Chat público web

Acceso: https://tudominio.com/chat-api/web/

• El usuario elige un nickname (guardado en localStorage)
• Recibe mensajes en tiempo real via long-polling
• Los mensajes se auto-eliminan con fade-out al expirar (según created_at del servidor)
• Indicador visual de estado de conexión (verde / amarillo / rojo)
• Múltiples pestañas del navegador = múltiples "jugadores" para testing

Panel de administración web

Acceso: https://tudominio.com/chat-api/web/admin.html

Contraseña: ADMIN_WEB_PASSWORD definida en config.php

Integración con Godot 4

El cliente está en godot_client_example.gd. Añade dos nodos HTTPRequest como hijos: HttpPoll y HttpSend.

# Configuración mínima
const API_BASE  := "https://tudominio.com/chat-api/api"
const PLAYER_ID := "jugador_prueba"  # reemplazar con el nickname real

# 1. Iniciar el long-polling
func _ready() -> void:
    _http_poll.request_completed.connect(_on_poll_completed)
    _http_send.request_completed.connect(_on_send_completed)
    _start_polling()

# 2. Loop de long-polling
func _poll_once() -> void:
    var url := "%s/get_messages.php?since_id=%d&wait=1" % [API_BASE, _last_id]
    _http_poll.request(url)

func _on_poll_completed(..., body):
    var json := JSON.parse_string(body.get_string_from_utf8())
    for msg in json.get("messages", []):
        if msg["id"] > _last_id: _last_id = int(msg["id"])
        _apply_message(msg)
    _poll_once()  # reconectar inmediatamente

# 3. Enviar mensaje del jugador
func send_chat_message(text: String) -> void:
    var body    := JSON.stringify({ "player_id": PLAYER_ID, "text": text })
    var headers := PackedStringArray(["Content-Type: application/json"])
    _http_send.request(API_BASE + "/send_message.php", headers,
                       HTTPClient.METHOD_POST, body)

Publicar eventos del juego (SYSTEM_API_KEY)

# Apuesta registrada
var body := JSON.stringify({
    "action": "bet", "player_id": player_id,
    "selection": "Rojo", "cash": "100.00"
})
var headers := PackedStringArray([
    "Content-Type: application/json",
    "X-API-Key: " + SYSTEM_API_KEY
])
http.request(API_BASE + "/system_message.php", headers,
             HTTPClient.METHOD_POST, body)

Tipos de mensaje y colores

Pendientes de integración

1. require_player_token() en includes/auth.php
   Actualmente, send_message.php es público y acepta cualquier player_id sin verificación de identidad. Conectar con el sistema real de tokens de RouletteApi (JWT, sesiones PHP, etc.) para validar que el jugador es quien dice ser.
2. GameChatMessage::money_format() en includes/GameChatMessage.php
   Ajustar el símbolo de moneda y el formato numérico para que coincida exactamente con CurrencyManager.money_format() del proyecto Godot.
3. Remitente "Tú" en el cliente Godot
   El backend almacena el player_id real. El cliente debe mostrar "Tú" cuando msg.sender == PLAYER_ID (ya implementado en godot_client_example.gd).
4. life_time correcto al recargar historial
   Al cargar mensajes previos via since_id=0, calcular el tiempo de vida restante como:
   life_time = max(0.0, 6.0 - (Time.get_unix_time_from_system() - msg.created_at))
   en lugar de reiniciar siempre a 6s (ya implementado en el cliente web y en el ejemplo GDScript).

Seguridad

Recomendaciones adicionales para producción

• Servir todo bajo HTTPS (certificado SSL gratuito via Let's Encrypt disponible en HostGator)
• Añadir rate limiting por IP en send_message.php para evitar spam
• Implementar validación de token (require_player_token()) antes de aceptar mensajes
• Rotar las API keys periódicamente
• Mantener config.php fuera del repositorio git (.gitignore)