BlueGit

projects-timfalken-com microchess

Files

microchess / web / README.md

README.md

feat: scaffold Synhex hex tactics on the Microchess lobby shell
timfa project_86226080_bot_b6e0858ac0a12dc6d49a8d25b3b0be9b · pushed by timfa · 2 months ago
24f20754 History
README.md 4.6 KiB Download Raw

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.

Source
1# Synhex
2
3Self-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.
4
5Synhex reuses Microchess's lobby (game tiles, friends, invites, rematches, avatars, custom colours, PWA, SQLite, PHP API, auth via [auth.timfalken.com](https://auth.timfalken.com)) and replaces chess with a hex-grid simultaneous-turn tactics game.
6
7## Run locally
8
9From the repository root:
10
11```sh
12php -S 127.0.0.1:8080 -t web web/router.php
13```
14
15Open 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.
16
17Autologin requires a loopback client IP and a localhost Host header. Do not expose the local development site through a public proxy.
18
19## Production
20
21Requirements: 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`.
22
23On 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:
24
25```php
26<?php
27return [
28 'base_url' => 'https://your-synhex-domain.example',
29 'client_id' => 'your-registered-domain.example',
30 'client_secret' => 'your-client-secret',
31 // Optional: override any key from lib/game-config.php
32];
33```
34
35Environment equivalents: `SYNHEX_BASE_URL`, `SYNHEX_CLIENT_ID`, `SYNHEX_CLIENT_SECRET`.
36
37Register `/callback.php` in the [auth service admin](https://auth.timfalken.com/admin). See the service's [integration guide](https://auth.timfalken.com/help).
38
39**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/`.
40
41Apache: enable `AllowOverride All` so `.htaccess` denies `data/`, `lib/` and `tests/`. Nginx equivalent:
42
43```nginx
44location ~* ^/(data|lib|tests)(/|$) { deny all; }
45location ~ /\. { deny all; }
46location ~* ^/(README\.md|router\.php)$ { deny all; }
47```
48
49Verify that `/data/synhex.sqlite`, `/data/config.php` and `/lib/bootstrap.php` return 403 before putting real data in the app.
50
51## Game config
52
53All combat/board tunables are in [`lib/game-config.php`](lib/game-config.php):
54
55- Board: **17 columns × 14 rows**, pointy-top, odd-r offset (238 hexes). Axial internally: `q = col - floor(row / 2)`, `r = row`.
56- Wall density, spawn layout, walk range (5 hexes/act), act duration (3 seconds)
57- Base accuracy 15% and each accuracy bonus
58- Weapon rates of fire and shotgun pellet count
59- Vision cone (forward direction + two adjacent = 120°) and ranges
60
61Same-named keys in `data/config.php` override these defaults on a server without editing the committed file.
62
63## How a match works
64
651. 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.
662. **Lock plan**. When both have committed, the server simulates the 3-second act (walk, vision cones, raycast shots, friendly fire).
673. Each tile shows **Play** to play back the same server timeline. After both have watched, planning starts again.
684. If a VIP dies, that player loses.
69
70First-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.
71
72Friends, invites, rematches, matchmaking, ratings, avatars, custom colours, notifications and data export behave as in Microchess.
73
74## Checks
75
76From the repository root:
77
78```sh
79find web -name '*.php' -not -path '*/artifacts/*' -print0 | xargs -0 -n1 php -l
80php web/tests/synhex.php
81php web/tests/colors.php
82php web/tests/push.php
83python3 web/tests/startup.py
84python3 web/tests/integration.py
85node --check web/assets/app.js
86node --check web/assets/pwa.js
87node --check web/sw.js
88node web/tests/pwa.mjs
89```
90
91`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.
92
93Optional 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.
94
95## Deferred
96
97Perfect 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.