Onyx Club Blackjack 1.0.0: guía del comprador

Juego HTML5 de simulación de blackjack con apuestas laterales y créditos ficticios gratuitos. Código fuente editable incluido.

Guía de personalización (recetas)

EnglishPortuguêsEspañol

Visión general

Onyx Club Blackjack es un juego HTML5 de simulación de blackjack con apuestas laterales: un club de jazz Art Déco de los años 1920 de noche, con una pantera negra de esmoquin marfil como crupier. Se entrega como juego listo para alojar (game/) y como proyecto completo editable (source/). Funciona en cualquier navegador actual, en móviles, tabletas y ordenadores, en vertical y horizontal, sin servidor, base de datos ni cuenta.

Funciones: blackjack clásico contra un crupier animado (una pantera negra de esmoquin marfil que reparte, aplaude, se encoge de hombros y saluda), hasta 3 manos a la vez en pantallas anchas, todas las jugadas (pedir, plantarse, doblar, dividir hasta 4 manos, rendirse, seguro), dos apuestas laterales (Perfect Pairs y 21+3), el consejo de estrategia básica, tres mesas con límites y sala propios, niveles del jugador que abren las mesas, ruleta diaria de premios, monedas gratis por tiempo, celebraciones de victoria grande/mega/épica, estadísticas y logros, 14 idiomas, voz de locutor grabada y música.

Solo simulación. El jugador recibe créditos ficticios de demostración gratuitos. No tienen valor monetario y no se pueden comprar, transferir, vender ni canjear. No hay depósitos, retiros, premios ni recompensas de valor económico. El precio de compra es el de una licencia de software, no una participación en juegos de azar. La licencia no permite el uso con dinero real ni con ningún otro valor real. Lee SCOPE.md (en la raíz del paquete y dentro de game/): forma parte de los términos de la licencia.

Una mano en juego: las jugadas a la derecha y el consejo de estrategia básica.
Una mano en juego: las jugadas a la derecha y el consejo de estrategia básica.

Instalar en tu sitio web

El juego jugable es la carpeta game/. Es HTML, CSS y JavaScript puros: no necesita compilación, Node.js ni base de datos para alojarlo.

  1. Abre el administrador de archivos de tu alojamiento, o conéctate con un programa de FTP (por ejemplo FileZilla).
  2. Crea una carpeta para el juego, por ejemplo /games/onyx-club/.
  3. Sube el contenido de game/ a ella: index.html, onyx-club.config.js, SCOPE.md, DOCUMENTATION.txt y las carpetas art/, audio/, assets/ y modules/.
  4. Abre la dirección en un navegador, por ejemplo https://tu-sitio.example/games/onyx-club/.

El juego usa rutas relativas, así que funciona en cualquier carpeta o subdominio. Abrir index.html directamente desde el disco (file://) no funciona, porque los navegadores bloquean ahí los módulos JavaScript: pruébalo en un alojamiento o con la vista previa local descrita en "Editar el código fuente".

Ponerlo dentro de una página (iframe)

<iframe src="/games/onyx-club/" style="width:100%;aspect-ratio:16/9;border:0" allow="fullscreen; autoplay"></iframe>

Deja visible el aviso de créditos en pantalla y conserva SCOPE.md junto al juego cuando lo publiques.

Requisitos

  • Cualquier alojamiento estático HTTP o HTTPS (alojamiento compartido, CDN, GitHub Pages, Netlify...). Sin PHP, base de datos ni código de servidor.
  • Un navegador actual: Chrome, Edge, Firefox, Safari (macOS e iOS), Samsung Internet u Opera.
  • Solo para editar el código fuente: Node.js 26 LTS (la línea LTS actual) y npm, ver "Editar el código fuente".
  • No hace falta internet para jugar: arte, sonidos y código están dentro de game/. El juego no hace peticiones a otros sitios.

Cómo se juega y las pantallas

El jugador toca TAP TO PLAY, elige una mesa en la sala, toma una ficha de la bandeja, toca una casilla de apuesta y toca DEAL (REPARTIR). El crupier reparte dos cartas a cada mano y dos para él, una boca abajo. El jugador juega cada mano; después el crupier descubre su carta y pide hasta 17. Todos los importes son créditos ficticios de demostración.

La sala: las mesas en un carrusel (aquí con todas las mesas abiertas). 1 2 3 4 5 6
La sala: las mesas en un carrusel (aquí con todas las mesas abiertas).
  1. carrusel de mesas: flechas, deslizar o un toque
  2. ruleta diaria
  3. saldo de créditos gratis de demostración (el + abre las monedas gratis)
  4. nivel del jugador y XP
  5. menú: ajustes, reglas, estadísticas, mesas
  6. reglas de esta mesa

La sala: tres mesas, tres ambientes

Las mesas esperan en un carrusel: las flechas, deslizar el dedo, tocar una mesa lateral o las flechas del teclado lo mueven, y PLAY (o un toque en la mesa elegida) te sienta. Una mesa bloqueada muestra un candado y el nivel que la abre. Cada mesa tiene sus límites, fichas y ambiente:

  • MESA SALÓN (apuestas 10 - 500): el salón principal del club, sobre tapete esmeralda
  • MESA ESCENARIO (apuestas 100 - 5.000): frente al escenario de jazz, sobre tapete rubí
  • MESA AZOTEA (apuestas 1.000 - 50.000): la terraza sobre el horizonte nocturno de la ciudad, sobre tapete zafiro

Apostar

Toca una ficha de la bandeja y luego una casilla. Las pantallas anchas muestran 3 casillas (un móvil en vertical muestra una). Los círculos pequeños junto a la casilla central son las apuestas laterales. CLEAR devuelve las apuestas, REBET repite las apuestas de la ronda anterior, ×2 las dobla, DEAL empieza la ronda. Toda apuesta queda entre el mínimo y el máximo de la mesa.

Apostando en la primera mesa (MESA SALÓN): tres casillas en una pantalla ancha, las apuestas laterales junto a la central. 1 2 3 4 5 6 7 8 9 10 11 12 13
Apostando en la primera mesa (MESA SALÓN): tres casillas en una pantalla ancha, las apuestas laterales junto a la central.
  1. saldo de créditos gratis de demostración (el + abre las monedas gratis)
  2. nivel del jugador y XP
  3. menú: ajustes, reglas, estadísticas, mesas
  4. reglas de esta mesa
  5. casilla de apuesta
  6. apuesta lateral Perfect Pairs
  7. apuesta lateral 21+3
  8. bandeja de fichas (las cinco fichas de la mesa)
  9. CLEAR: devuelve las apuestas
  10. REBET: repite las apuestas de la última ronda
  11. ×2: dobla las apuestas
  12. DEAL: empieza la ronda
  13. el aviso de créditos gratis (mantenlo visible)

Jugar una mano

Jugada Qué hace
Pedir (Hit) una carta más
Plantarse (Stand) quedarse con la mano como está
Doblar (Double) dobla la apuesta y recibe exactamente una carta más (con dos primeras cartas cualesquiera, también tras dividir)
Dividir (Split) dos cartas del mismo valor pasan a ser dos manos, cada una con su apuesta (hasta 4 manos)
Rendirse (Surrender) abandona la mano en la primera decisión y recupera la mitad de la apuesta (después de que el crupier compruebe el blackjack)
Seguro (Insurance) cuando el crupier muestra un As: una apuesta extra de la mitad de la apuesta que paga 2 a 1 si tiene blackjack

La burbuja de consejo muestra la jugada de la estrategia básica para la mano (el jugador puede apagarla en SETTINGS). Valores de las cartas: del 2 al 10 valen su número, J, Q y K valen 10, el As vale 1 u 11. Un As y una carta de valor 10 como primeras dos cartas es un blackjack y paga 3 a 2. El crupier se planta con cualquier 17.

Una mano en juego: las jugadas a la derecha y el consejo de estrategia básica. 1 2 3 4 5 6
Una mano en juego: las jugadas a la derecha y el consejo de estrategia básica.
  1. HIT: una carta más
  2. STAND: quedarse con la mano
  3. DOUBLE: dobla la apuesta, una carta
  4. SPLIT: una pareja pasa a ser dos manos
  5. SURRENDER: recupera la mitad de la apuesta
  6. consejo de estrategia básica
Una pareja de ochos dividida en dos manos.
Una pareja de ochos dividida en dos manos.

Resultados y celebraciones

Tras el turno del crupier cada mano muestra su resultado en el tapete (WIN, PUSH, BUST, DEALER BUSTS) y las fichas se mueven: las apuestas perdidas van al crupier, las ganadoras se pagan junto a la apuesta. Un blackjack tiene su propio título. Cuando una ronda paga al menos 4 veces su apuesta el juego lanza una celebración BIG WIN (MEGA desde 10×, EPIC desde 25×) con monedas que vuelan al saldo.

Una mano ganadora en la segunda mesa (MESA ESCENARIO), en su propio ambiente.
Una mano ganadora en la segunda mesa (MESA ESCENARIO), en su propio ambiente.
Un blackjack: su propio título y pago.
Un blackjack: su propio título y pago.
Una división con dos dobles que paga un BIG WIN.
Una división con dos dobles que paga un BIG WIN.

Apuestas laterales

Se deciden con las primeras cartas, antes de jugar la ronda, y pagan "a 1" sobre la apuesta lateral:

Apuesta lateral Gana cuando Paga
Perfect Pairs las dos primeras cartas del jugador forman una pareja: mismo palo (perfecta) / mismo color (de color) / mixta 25 a 1 / 12 a 1 / 6 a 1 (perfecta / de color / mixta)
21+3 las dos cartas del jugador y la carta visible del crupier forman una mano de póquer trío del mismo palo 100 a 1, escalera de color 40 a 1, trío 30 a 1, escalera 10 a 1, color 5 a 1

Recompensas fuera de la mesa

Los niveles (la insignia junto al saldo) suben con los créditos jugados; cada nivel nuevo da créditos gratis y abre las siguientes mesas. La ruleta diaria da créditos gratis (se ofrece en cada visita con el ajuste de demostración de fábrica). El botón de regalo da 1.000 créditos gratis cada 3 horas. Cuando se acaban los créditos se ofrece una recarga gratis de 25.000.

La ruleta diaria de créditos gratis. 1 2 3
La ruleta diaria de créditos gratis.
  1. la ruleta: 12 premios de créditos gratis
  2. SPIN (girar)
  3. cerrar

Menú: ajustes, reglas y estadísticas

El menú abre SETTINGS (música, efectos, voz del locutor, velocidad, el consejo, menos movimiento, idioma), las RULES de la mesa actual (las jugadas con cartas pequeñas de ejemplo, los pagos, el conjunto de reglas) y las STATISTICS (manos, victorias, blackjacks, mayor victoria, mejor racha, logros con medallas).

SETTINGS: música, efectos, voz, velocidad, el consejo, menos movimiento y el idioma. 1
SETTINGS: música, efectos, voz, velocidad, el consejo, menos movimiento y el idioma.
  1. cerrar el panel
RULES: cada jugada con cartas pequeñas de ejemplo.
RULES: cada jugada con cartas pequeñas de ejemplo.
STATISTICS y los logros con sus medallas.
STATISTICS y los logros con sus medallas.
La tercera mesa (MESA AZOTEA) y su ambiente.
La tercera mesa (MESA AZOTEA) y su ambiente.
En un móvil en vertical: una casilla, las jugadas bajo la mesa. 1 2 3 4 5 6 7 8 9
En un móvil en vertical: una casilla, las jugadas bajo la mesa.
  1. saldo de créditos gratis de demostración (el + abre las monedas gratis)
  2. nivel del jugador y XP
  3. menú: ajustes, reglas, estadísticas, mesas
  4. HIT: una carta más
  5. STAND: quedarse con la mano
  6. DOUBLE: dobla la apuesta, una carta
  7. SPLIT: una pareja pasa a ser dos manos
  8. SURRENDER: recupera la mitad de la apuesta
  9. consejo de estrategia básica

Teclado

En juego: H pedir, S plantarse, D doblar, P dividir, R rendirse. Enter o Espacio reparte (apostando) y repite las apuestas (tras una ronda). En la sala: las flechas eligen la mesa y Enter te sienta.

Qué hay en el paquete

onyx-club-static-1.0.0/
  START-HERE.txt          primeros pasos
  DOCUMENTATION.html      abre esta guía
  CUSTOMIZATION.html      abre la guía de personalización (recetas, sin programar)
  CHANGELOG.txt
  SCOPE.md                qué es el producto y qué no permite la licencia
  documentation/          esta guía y la guía de personalización (EN/PT/ES), capturas
  game/                   SUBE EL CONTENIDO DE ESTA CARPETA
    index.html            la página
    onyx-club.config.js    tus ajustes (edítalo en el alojamiento, sin compilar)
    modules/              el JavaScript, un archivo legible por módulo del código fuente (más _virtual/preload-helper.js,
                          el pequeño cargador que Vite añade para el módulo del crupier, que se carga bajo demanda)
    assets/ui/            las hojas de estilo (cuatro archivos)
    art/                  imágenes (WebP)
    audio/                sonidos, voz y música (MP3)
    SCOPE.md, DOCUMENTATION.txt
  source/                 el proyecto completo editable
    index.html            la página (versión de desarrollo)
    src/main.js           inicio, pantallas, diseño, carrusel de la sala, apuestas, ruleta diaria, ajustes, entrada
    src/flow/round.js     una ronda: reparto, jugadas, seguro, apuestas laterales, resultados, blackjack, celebraciones (parte de main.js)
    src/config.js         valores por defecto, eventos, clave de guardado
    src/logic/            rules.js (mesas y reglas), engine.js (zapato, manos, créditos), strategy.js (el consejo), progress.js
    src/ui/               table.js (el tapete), sheets.js (paneles), wheel.js, fx.js, feel.js, theme.js, art.js, styles*.css
    src/bear/             sprite-bear.js: el crupier animado
    src/locales/          los 14 idiomas (en.js es la referencia)
    src/audio/audio.js    la lista de sonidos, músicas y voces
    public/               art/, audio/, onyx-club.config.js (se copian a la compilación tal cual)
    tests/                npm test
    tools/                ventaja de la casa, revisión de traducciones, robot de prueba, revisión de textos, formateador
    package.json, package-lock.json, vite.config.js, .prettierrc, README.md
    licenses/             licencias de las herramientas de desarrollo
  THIRD-PARTY-LICENSES/   los mismos textos de licencia

game/ es exactamente lo que npm run build genera a partir de source/ (comprobado archivo por archivo antes de empaquetar). Edita source/ y compila de nuevo, o edita solo onyx-club.config.js en el alojamiento.

Ajustes (onyx-club.config.js)

game/onyx-club.config.js se lee cada vez que se abre el juego, así que puedes cambiar estos ajustes en tu alojamiento con un editor de texto y sin compilar. Todos los campos son opcionales: quita el // delante de la línea para usarla. Un valor incorrecto detiene el juego con un mensaje que dice qué corregir.

window.BLACKJACK_CONFIG = {
  brand: { name: 'Onyx Club Blackjack', storageKey: 'misitio.onyx-club' },
  language: 'auto',
  languages: ['en', 'pt', 'es'],
  texts: { tapToPlay: 'JUGAR', de: { tapToPlay: 'LOS!' } },
  audio: { volume: 0.8, muted: false },
  tips: true,
  lobby: true,
  ageGate: true,
  notice: true,
  rules: { preset: 'vegas', decks: 6, blackjackPays: [3, 2], dealerHitsSoft17: false, startBalance: 25000 },
  progress: { wheel: { alwaysReady: false, everyHours: 24 }, coins: { everyHours: 3, amount: 100 } },
  winTiers: { big: 4, mega: 10, epic: 25 },
};
Opción Qué hace
brand.name nombre del juego en la página y los mensajes
brand.storageKey prefijo de los datos guardados en el navegador (por defecto onyx-club.template.save.v1); cámbialo para empezar una partida nueva
language 'auto' = el idioma del dispositivo (inglés si no está), o un código: en pt es fr de it nl pl tr ru id ja ko zh. La elección del jugador en SETTINGS y ?lang=xx en la dirección tienen prioridad
languages los idiomas ofrecidos en SETTINGS (por defecto: los 14). Uno solo oculta el selector
texts reemplaza cualquier texto de src/locales/en.js en todos los idiomas, o en uno (texts: { pt: {...} })
audio volumen inicial (0 a 1) y silencio
tips el consejo de estrategia básica (el jugador puede apagarlo)
lobby false salta la sala: el jugador se sienta en la primera mesa
ageGate true muestra la insignia 18+ y el aviso de casino social
notice el aviso de créditos de una línea bajo los controles. Déjalo: SCOPE.md lo exige en publicaciones abiertas
showEdge muestra la ventaja de la casa medida en la hoja de reglas (pon rules.houseEdge tras ejecutar npm run edge)
debug solo para pruebas, ver "Enlace de prueba" abajo
rules las reglas de la mesa y la sala, ver "Reglas y límites de las mesas"
progress niveles (enabled, need, reward), la ruleta diaria (enabled, alwaysReady, everyHours, prizes, weights) y monedas gratis (enabled, everyHours, amount). Importes en múltiplos de la apuesta mínima de la primera mesa
winTiers a partir de cuántas veces la apuesta de la ronda empiezan las celebraciones big, mega y epic
integration, callbacks eventos para tu página, ver "Eventos"

El archivo del paquete lista todas las opciones con un comentario. Los valores por defecto completos están en source/src/config.js, source/src/logic/rules.js y source/src/logic/progress.js.

Enlace de prueba

En tu propio equipo (localhost, 127.0.0.1 o una dirección de la red de casa como 192.168.x.x) la dirección ?debug=1 activa un modo de prueba, sin cambiar ningún archivo: &seed=123 repite el mismo zapato, &deal=AS,KH,9D,7C pone esas cartas arriba del zapato, &level=20 empieza en ese nivel (todas las mesas abiertas) y &coins=500000 empieza con ese saldo. En un alojamiento público se ignora, salvo que pongas debug: true en onyx-club.config.js (no lo dejes activo para los jugadores). El robot de prueba y las pruebas lo usan.

Reglas y límites de las mesas

Todo está en rules: { } de onyx-club.config.js (o source/src/logic/rules.js). La mesa de fábrica:

  • preset: 'vegas': un conjunto de reglas listo. 'vegas' (6 barajas, el crupier comprueba el blackjack, doblar con dos cartas cualesquiera, rendición tardía), 'european' (sin carta tapada: el crupier toma su segunda carta tras los jugadores, doblar con 9 a 11, sin rendición) o 'social' (2 barajas, los Ases divididos se pueden volver a dividir y pedir). Cualquier clave de abajo sustituye al preset.
  • decks: 6 (1 a 8); penetration: 0.75 (parte del zapato repartida antes de barajar de nuevo).
  • dealerHitsSoft17: false; blackjackPays: [3, 2], [6, 5], [1, 1] o [2, 1]; peek: el crupier comprueba el blackjack bajo un As o un 10.
  • double: 'any', '9-11', '10-11' o 'none'; doubleAfterSplit; maxHands (1 = sin dividir); splitByValue (K + 10 se puede dividir); resplitAces; hitSplitAces.
  • surrender: 'late' o 'none'; insurance: true o false.
  • seats: casillas de apuesta a la vez en pantallas anchas (1 a 3).
  • sideBets: perfectPairs y twentyOnePlusThree, cada una con enabled y pays; max es la mayor apuesta lateral como parte de la apuesta máxima de la mesa.
  • startBalance: 25.000 (también la recarga gratis).
  • tables: la sala, una línea por mesa: id, minBet, maxBet, chips (1 a 5 valores, de menor a mayor) y unlock (el nivel del jugador que la abre). Importes en múltiplos de 10 para que todo pago sea entero.
Mesa Apuestas Fichas Se abre en el nivel
MESA SALÓN 10 - 500 10, 20, 50, 100, 500 1
MESA ESCENARIO 100 - 5.000 100, 200, 500, 1.000, 5.000 5
MESA AZOTEA 1.000 - 50.000 1.000, 2.000, 5.000, 10.000, 50.000 12

No hay un "porcentaje de victoria" que configurar: el zapato se baraja al azar y la ventaja de la casa sale solo de estas reglas. npm run edge (en source/) juega millones de manos con estrategia básica usando tus ajustes y muestra la ventaja. Las pruebas del motor (npm test) comprueban cada regla.

Idiomas

La interfaz está traducida a 14 idiomas: inglés, portugués, español, francés, alemán, italiano, neerlandés, polaco, turco, ruso, indonesio, japonés, coreano y chino (simplificado). La voz del locutor y los títulos pintados (BLACKJACK, BIG WIN, MEGA WIN, EPIC WIN, DAILY WHEEL) están en inglés en todos los idiomas. El juego se abre en el idioma del dispositivo; el jugador puede cambiarlo en SETTINGS, y ?lang=pt en la dirección fuerza uno.

Los textos están en source/src/locales/<código>.js, un archivo por idioma, con las mismas claves que en.js (los nombres de las mesas son table_<id>). Una clave que falte usa el inglés. Para cambiar algunos textos sin compilar, usa texts en onyx-club.config.js. Tras editar los archivos de idioma, ejecuta npm run locales para comprobar que ninguna traducción perdió un marcador {valor}.

La misma mesa en portugués.
La misma mesa en portugués.

Datos guardados

El juego guarda el saldo, el nivel, las estadísticas, los ajustes, la mesa elegida y los temporizadores de recompensas en el localStorage del navegador, con claves que empiezan por onyx-club.template.save.v1. (por ejemplo onyx-club.template.save.v1.balance). No se envía nada a ninguna parte. Una ronda interrumpida al recargar devuelve las apuestas de la mesa. Borrar los datos del sitio en el navegador reinicia el juego. Si publicas dos copias del juego en el mismo dominio, da a cada una su propio brand.storageKey.

Eventos para tu página

El juego envía eventos para que tu página muestre estadísticas, logros o una clasificación de puntuaciones ficticias. No son una interfaz contable ni de pago y no deben usarse como tal.

  • callbacks en onyx-club.config.js: onReady(info), onRound(round), onWin(round), onBalance({ balance }), onBonus({ kind, amount, balance }), onError.
  • window.OnyxBlackjack.on('round', fn), window.OnyxBlackjack.getBalance(), window.OnyxBlackjack.version, window.OnyxBlackjack.rules.
  • Eventos DOM en window: blackjack:round, blackjack:win, blackjack:bonus...
  • Con integration: { postMessage: true, targetOrigin: 'https://tu-sitio.example' } el juego también envía { source, type, payload } a la página contenedora cuando funciona dentro de un iframe.

round.spent son los créditos de demostración puestos en la ronda (apuestas, dobles, divisiones, apuestas laterales, seguro), round.payout los créditos que devolvió, round.net la diferencia, round.hands las cartas y el resultado de cada mano, round.table el id de la mesa. bonus.kind es 'wheel', 'coins', 'level' o 'refill'.

Editar el código fuente (Node.js para principiantes)

Solo lo necesitas para cambiar código, estilos, arte o sonidos y generar un game/ nuevo. Para cambiar ajustes, edita onyx-club.config.js.

1. Instalar Node.js

  1. Entra en https://nodejs.org y descarga la versión LTS (Node.js 26 LTS). Windows y macOS: ejecuta el instalador con las opciones por defecto. Linux: usa tu gestor de paquetes o los binarios oficiales.
  2. Cierra y abre de nuevo la terminal (Windows: PowerShell o Símbolo del sistema; macOS: Terminal).
  3. Comprueba las versiones: los dos comandos deben mostrar un número, y Node debe ser 26.13.0 o más nuevo.
node --version
npm --version

2. Instalar las herramientas del proyecto

Abre la terminal en la carpeta source/ (Windows: abre la carpeta en el Explorador, haz clic en la barra de direcciones, escribe powershell y pulsa Enter; macOS: arrastra la carpeta al icono de Terminal). Luego ejecuta:

npm ci

Instala las versiones exactas de package-lock.json (Vite, Prettier y Playwright) en node_modules/. Necesita conexión a internet una vez.

3. Probar, ver la vista previa y compilar

npm test
npm run dev
npm run build
  • npm test ejecuta las pruebas del motor (zapato, valores de las manos, cada jugada, seguro, rendición, apuestas laterales, créditos, estrategia básica, ventaja de la casa). Todas deben pasar.
  • npm run dev abre una vista previa local en http://localhost:5223/ que se recarga al guardar un archivo. Ctrl+C para pararla. El enlace de prueba funciona ahí (?debug=1&deal=AS,KH,9D,7C).
  • npm run build escribe el juego terminado en source/dist/. Sube el contenido de dist/ a tu alojamiento (sustituye a game/). La compilación no está minificada y se formatea con Prettier, así que sigue siendo legible.

Otros comandos

  • npm run edge muestra la ventaja de la casa de tus reglas (src/logic/rules.js más el rules de public/onyx-club.config.js), medida en millones de manos.
  • npm run locales comprueba las traducciones.
  • npm run format formatea todo el proyecto con Prettier.
  • npm run robot juega rondas reales en un navegador, en tamaño de móvil y de ordenador, y comprueba que cada saldo sea exacto (ver "Robot de prueba").
  • tools/qa-fit.js es una comprobación dentro de la página para la vista previa: en la consola del navegador, (await import('/tools/qa-fit.js')).check() lista cualquier texto que no quepa en su placa.

Robot de prueba

tools/play-robot.mjs apuesta, reparte y juega con los propios botones del juego (todas las jugadas, apuestas laterales, seguro, paneles, REBET / NEW BET) e informa de errores de la página, rondas que nunca terminan y cualquier saldo distinto de lo que el juego dice que pagó la ronda. Instala su navegador una vez con npx playwright install chromium, inicia npm run dev en una terminal y ejecuta npm run robot en otra. El informe queda en robot-report/report.json.

Problemas comunes

  • node o npm no se reconoce: Node.js no está instalado o la terminal se abrió antes de instalarlo. Reinstala y abre una terminal nueva.
  • Windows dice que la ejecución de scripts está desactivada (npm.ps1): usa el Símbolo del sistema, o ejecuta npm.cmd ci.
  • ENOENT ... package.json: la terminal no está en la carpeta source/.
  • EBADENGINE: tu Node.js es anterior a 26.13.0. Instala la LTS actual.
  • npm ci falla con un error de red: revisa la conexión o el proxy de la red de tu empresa y vuelve a ejecutarlo.
  • npm ci dice que el archivo lock no está sincronizado: cambiaste package.json; ejecuta npm install una vez y luego npm ci vuelve a funcionar.
  • El puerto 5223 está ocupado: Vite elige el siguiente libre y lo muestra.
  • El robot dice que falta el navegador: ejecuta npx playwright install chromium.

Personalizar y cambiar el tema

La guía de personalización (CUSTOMIZATION.html) tiene recetas paso a paso para quien no programa: cambiar los fondos y los ambientes, el logo, el crupier, las cartas, las fichas, sonidos y música, colores, textos, reglas de las mesas y recompensas. En resumen:

  • Arte: source/public/art/ (o game/art/ en el alojamiento). Sustituye un archivo por otro WebP con el mismo nombre y tamaño: un tema nuevo es una carpeta de arte más source/src/ui/theme.js.
  • Sonidos: source/public/audio/ (o game/audio/). Sustituye un MP3 por otro con el mismo nombre.
  • Colores y efectos del tema: source/src/ui/theme.js. Tiempos: source/src/ui/feel.js. Solo presentación: nada ahí cambia una carta o un pago.
  • Diseño y estilos: source/src/ui/styles.css y los tres archivos que lo siguen (styles-placement.css, styles-polish.css, styles-final.css, cargados en ese orden).
  • Textos: texts en onyx-club.config.js o source/src/locales/.
  • Reglas y límites de las mesas: rules en onyx-club.config.js o source/src/logic/rules.js, y después npm run edge.

Los cambios en source/ necesitan npm run build. Los cambios en archivos de game/ en el alojamiento (arte, audio, onyx-club.config.js) no necesitan compilar.

Nombres internos

Algunos nombres del código describen otra cosa de lo que dicen. Son solo nombres:

Nombre en el código Qué es
src/bear/, sprite-bear.js, bear, bear-sprites/, bear-*.webp el crupier animado (la pantera negra) y sus imágenes: los nombres vienen del motor compartido
lounge, stage, rooftop los ids de las tres mesas en rules.tables (los archivos de arte usan los mismos nombres)
iceFont, font-ice las cifras pintadas claras (apuestas, totales); goldFont / font-gold son las doradas (saldo, victorias)
crystal-*.webp, flake-*.webp, ice-arrow.webp, title-bust-ice.webp ornamentos Art Déco, destellos dorados, la flecha del carrusel y el título BUST: nombres de archivo del motor compartido
auroraGlow(), @keyframes aurora, .bg-glow las luces del ambiente: un velo lento de luz sobre las ventanas que brilla un momento tras una victoria (nombres del motor compartido)
fx.snow, snowCount, FEEL.ambient.snowDesktop / snowTouch las partículas del ambiente: polvo dorado que sube despacio en este tema (THEME.ambient.rise = true)
fx.frost(), fx.crack(), fx.shards(), 'bust-ice' el estallido, las grietas y las esquirlas dibujados en un BUST y en un nuevo nivel de celebración, y la clave del panel BUST (nombres del motor compartido)
Bank, bank.balance los créditos ficticios de demostración del jugador (sin dinero)
.nine, nine.js placas y botones estirados en nueve partes (9-slice) para que sus extremos decorados conserven la forma
window.__bj el ayudante de prueba del enlace de prueba (?debug=1, solo en tu equipo)

Actualizar el juego y borrar la caché

Tras subir una versión nueva, los navegadores y alojamientos pueden conservar un tiempo los archivos antiguos. Si un cambio no aparece:

  • Recarga sin caché: Ctrl+F5 o Ctrl+Shift+R (Windows/Linux), Cmd+Shift+R (macOS). En el móvil, cierra la pestaña y ábrela de nuevo.
  • Borra los archivos en caché del sitio en los ajustes del navegador ("Imágenes y archivos en caché"). No borres "cookies y datos de sitios" salvo que quieras reiniciar la partida guardada.
  • Prueba una ventana privada (incógnito).
  • Si tu alojamiento o CDN (por ejemplo Cloudflare) tiene caché, púrgala.
  • Añade una versión a la dirección una vez, por ejemplo index.html?v=2.

Los datos guardados se conservan tras una actualización mientras brand.storageKey no cambie.

Qué es el producto (y qué no)

  • Solo créditos ficticios de demostración, gratuitos y sin valor monetario. No se pueden comprar, transferir, vender ni canjear. Ningún premio de ningún tipo.
  • Ningún sistema de pago, depósito, retiro, cuenta ni monedero: ninguno está oculto, desactivado ni incluido en el paquete.
  • Las cartas salen de un zapato barajado al azar; nada en el juego ajusta la probabilidad de ganar.
  • La licencia estándar no permite usar este juego, ni ninguna versión modificada, para apuestas con dinero real o cualquier cosa de valor real: nada de comprar créditos, cobrar, premios según resultados, conexión a monederos de apuestas, sistemas de pago u operadores de dinero real, ni publicidad de apuestas con dinero real.
  • "Seguro", "apuestas laterales" y "doblar" son jugadas del juego de cartas y gastan los mismos créditos ficticios; no son compras.
  • Debes cumplir las leyes de cada lugar donde publiques el juego (clasificación por edades, menores, protección del consumidor). Mantén visible el aviso de créditos; ageGate: true añade un aviso 18+.
  • El soporte no cubre monederos, depósitos, retiros ni ninguna integración con dinero real; esas solicitudes se rechazan.

El texto completo es SCOPE.md.

Preguntas y problemas

  • La página sale en blanco. Comprueba que subiste el contenido de game/ (con modules/ y assets/) y que lo abres por http(s), no file://. La consola del navegador (F12) muestra el archivo que falta.
  • No hay sonido. Los navegadores solo permiten sonido tras un toque: el juego lo inicia en TAP TO PLAY. Revisa SETTINGS (música, efectos, voz) y el volumen del dispositivo. Si el móvil corta el sonido (una llamada, otra app), el siguiente toque lo recupera.
  • ¿Puedo cambiar la ventaja de la casa? Sí, solo con las reglas (blackjackPays, decks, dealerHitsSoft17, double, surrender, pagos de las apuestas laterales...); npm run edge mide tu mesa. No hay una tasa de victoria oculta.
  • ¿Puedo añadir una cuarta mesa? Sí: añade una línea a rules.tables y su nombre como table_<id> en los idiomas (o en texts). Usa el primer ambiente salvo que añadas arte y estilos para ella (guía de personalización, receta 3).
  • ¿Los jugadores pueden comprar créditos o ganar premios? No. El juego no tiene sistema de pago ni de premios, y la licencia no permite añadir uno.
  • ¿Funciona sin conexión? Una vez cargado, sí; no necesita otro sitio.
  • ¿Puedo quitar el aviso de créditos? En una publicación abierta debe seguir visible (ver SCOPE.md).
  • La ruleta diaria se abre en cada visita. Es el ajuste de demostración alwaysReady: true; pon progress: { wheel: { alwaysReady: false } }.
  • ¿Cómo muestro cartas elegidas? En la vista previa local añade ?debug=1&deal=AS,KH,9D,7C (las cartas van al jugador, al crupier, al jugador, al crupier...).

Soporte y créditos

Correo de soporte: willian@polargames.com.br (errores, instalación, diseño en los navegadores compatibles, traducciones, personalización visual y de audio y los ajustes de esta guía). Incluye tu código de compra o de licencia, el navegador y el dispositivo, y una captura de pantalla.

Herramientas de desarrollo: Vite, Prettier y Playwright (licencias en THIRD-PARTY-LICENSES/). No se incluye código de terceros en game/. El arte, la música, la voz y los efectos forman parte del juego y están cubiertos por la licencia de tu compra.