BlueGit

projects-timfalken-com microchess

Files

microchess / web
README.md

Synhex

Self-contained PHP 8.2+ application. Set the document root to this web/ directory. No Composer, Node, build step or files outside this directory are required in production.

Synhex reuses Microchess's lobby (game tiles, friends, invites, rematches, avatars, custom colours, PWA, SQLite, PHP API, auth via auth.timfalken.com) and replaces chess with a hex-grid simultaneous-turn tactics game.

Run locally

From the repository root:

php -S 127.0.0.1:8080 -t web web/router.php

Open http://127.0.0.1:8080. You are automatically signed in as test_user_1. Account → Switch to test_user_2 switches accounts. Use a second browser profile or private window for two independent sessions.

Autologin requires a loopback client IP and a localhost Host header. Do not expose the local development site through a public proxy.

Production

Requirements: PHP 8.2+, PDO SQLite, cURL, mbstring, OpenSSL with elliptic-curve support, writable web/data/, and HTTPS. All application writes remain under web/data/. Session name is synhex_session; the database is data/synhex.sqlite.

On the first page request, the app creates web/data/config.php with empty base_url, client_id and client_secret if the file does not exist. Fill it in on each server:

<?php
return [
    'base_url' => 'https://your-synhex-domain.example',
    'client_id' => 'your-registered-domain.example',
    'client_secret' => 'your-client-secret',
    // Optional: override any key from lib/game-config.php
];

Environment equivalents: SYNHEX_BASE_URL, SYNHEX_CLIENT_ID, SYNHEX_CLIENT_SECRET.

Register /callback.php in the auth service admin. See the service's integration guide.

Production FTP deploy is currently off in .gitlab-ci.yml (ftp_upload uses when: never) until a Synhex host exists. When deploying manually, preserve data/ (config, database, WAL, push keys). Never upload your development database or tests/artifacts/.

Apache: enable AllowOverride All so .htaccess denies data/, lib/ and tests/. Nginx equivalent:

location ~* ^/(data|lib|tests)(/|$) { deny all; }
location ~ /\. { deny all; }
location ~* ^/(README\.md|router\.php)$ { deny all; }

Verify that /data/synhex.sqlite, /data/config.php and /lib/bootstrap.php return 403 before putting real data in the app.

Game config

All combat/board tunables are in lib/game-config.php:

  • Board: 17 columns × 14 rows, pointy-top, odd-r offset (238 hexes). Axial internally: q = col - floor(row / 2), r = row.
  • Wall density, spawn layout, walk range (5 hexes/act), act duration (3 seconds)
  • Base accuracy 15% and each accuracy bonus
  • Weapon rates of fire and shotgun pellet count
  • Vision cone (forward direction + two adjacent = 120°) and ranges

Same-named keys in data/config.php override these defaults on a server without editing the committed file.

How a match works

1. Both players plan at the same time. Click a unit, click hexes or drag a path. The path end is a hologram; click a waypoint to place it there and drag the hex in front to set facing. 2. Lock plan. When both have committed, the server simulates the 3-second act (walk, vision cones, raycast shots, friendly fire). 3. Each tile shows Play to play back the same server timeline. After both have watched, planning starts again. 4. If a VIP dies, that player loses.

First-pass planning UX is intentionally simple (click-to-path / drag-path). Full art polish and perfect path-drag are out of scope for this scaffold.

Friends, invites, rematches, matchmaking, ratings, avatars, custom colours, notifications and data export behave as in Microchess.

Checks

From the repository root:

find web -name '*.php' -not -path '*/artifacts/*' -print0 | xargs -0 -n1 php -l
php web/tests/synhex.php
php web/tests/colors.php
php web/tests/push.php
python3 web/tests/startup.py
python3 web/tests/integration.py
node --check web/assets/app.js
node --check web/assets/pwa.js
node --check web/sw.js
node web/tests/pwa.mjs

synhex.php covers hex math, vision, wall/path, simultaneous commit → timeline, deterministic seeds and VIP elimination. Integration tests cover lobby/API plus plan lock, playback and resign.

Optional real-browser tests (requires Node.js / Playwright; see previous Microchess README for install). web/tests/browser.mjs exercises the lobby plus hex Lock plan / Play.

Deferred

Perfect path-drag UX, full fog-of-war playback filtering, production FTP host, renaming the GitLab project itself, and visual art beyond existing piece/colour assets.