Mystic Numbers

mystic.tribewarez.com

A match-style puzzle game with deep numerology themes. Players merge numbered tiles, progress through levels, unlock power-ups, and sync progress through a backend API. The game integrates Solana wallets for crypto purchases and token rewards.

Gameplay

Core Mechanics

• Tile matching -- merge numbered tiles on a grid to score points
• Levels -- progressive difficulty with unique board layouts
• Power-ups -- hammer, bomb, undo, shuffle, and more
• Worlds -- themed numerology worlds with boss battles
• Guilds -- player groups with shared progress and shards

Numerology System

The game assigns meaning to numbers and patterns. Tile values, level themes, and boss mechanics are derived from numerological concepts (life path, destiny, soul numbers).

Architecture

Mystic Numbers has three components:

Component	Stack	Role
webapp	Next.js 16, React 19, TypeScript, Tailwind, Zustand	Game frontend and UI
api-backend	Symfony (PHP), API Platform, MariaDB/PostgreSQL	Profiles, progress, chat, shop
webhook-server	Node.js, Prisma, WebSocket	Real-time updates and webhooks

Authentication

The app uses Google OAuth 2.0 for player authentication with server-side session validation:

1. Client-side: GSI (Google Sign-In) renders the one-tap button in the browser
2. Server-side: The Google auth code is exchanged for tokens by the Next.js API route at /api/auth/callback/google/, which proxies to the Symfony backend
3. Session: Symfony's GameSession entity stores the session token, Google sub, and expiry — validated by SessionController on each request
4. Logout: /api/auth/logout revokes the session on both Next.js and Symfony sides

The auth provider (components/auth/auth-provider.tsx) checks the server session on mount via /api/auth/me, falling back to client-only GSI if the server is unreachable.

Background Effects

The game features a CSS-only background effects system with 13 skin types (cosmic, aurora, nebula, code-rain, matrix, geometric, neon-grid, data-stream, solana-wave, particle-field, fireflies, prism, void):

• CSS-only rendering -- all animations use CSS keyframes, no canvas/WebGL
• Device capability detection -- background-effects.tsx probes for max-width, reduced motion preference, and pixel ratio to select appropriate effects
• Performance tiers -- adjusts particle count, animation complexity, and layer count based on device
• Reduced motion -- respects prefers-reduced-motion: reduce by disabling non-essential animations

Real-Time Updates

The app uses Mercure (EventSource/SSE) for live updates -- chat messages, leaderboard changes, and game events stream to connected clients without polling.

Crypto Integration

Wallet Connection

Uses Solana Wallet Adapter with Phantom and Solflare support. RPC priority:

1. TribeWarez testnet (testnet-solana.rpc.gateway.tribewarez.com)
2. Custom RPC URL
3. Helius
4. Solana mainnet fallback

Token Shop

Players can purchase in-game items with crypto:

Item	Accepted Tokens
Coin packs	SOL, PTtC, NMTC
Premium subscription	SOL, NMTC
No-ads	SOL, NMTC

Transaction verification goes through the Terminal backend.

Token Addresses

Configured via environment variables:

NEXT_PUBLIC_TRIBEWAREZ_SOLANA_RPC=https://testnet-solana.rpc.gateway.tribewarez.com
NEXT_PUBLIC_NMTC_MINT=<nmtc_mint_pubkey>
NEXT_PUBLIC_PTTC_MINT=<pttc_mint_pubkey>

Tech Stack

Layer	Technology
Frontend	Next.js 16, React 19, TypeScript
State	Zustand
UI	Tailwind CSS, Radix UI, Framer Motion
Backend API	Symfony (PHP), API Platform
Database	MariaDB / PostgreSQL
Webhooks	Node.js, Prisma
Real-time	Mercure (SSE)
Blockchain	Solana Wallet Adapter, SPL Token
PWA	Service worker, install prompt

API Backend

The Symfony API (api-backend/) provides REST endpoints for:

• Users -- registration, authentication, profiles
• Game progress -- levels, scores, achievements
• Chat -- in-game messaging
• Shop -- purchases, inventory, subscriptions

API documentation is available via API Platform's auto-generated OpenAPI spec.

Docker

Each component runs in its own container, orchestrated from the main docker-compose.yml:

• webapp -- Next.js app
• api-backend -- Symfony with PHP-FPM
• webhook-server -- Node.js
• mercure -- Mercure hub for SSE
• Database containers (MariaDB/PostgreSQL)