mozempk/scopone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 228 Activity

fix(SCOPONE-0008): refresh lag fix docs

Browse Source
This commit is contained in:
Giancarmine Salucci
2026-04-02 20:55:49 +02:00
parent 5b360bf191
commit c9accb7ae4
2 changed files with 54 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/FINDINGS.md
View File

@@ -1,20 +1,22 @@
# Findings
> Last Updated: 2026-04-02T18:12:18.000Z
> Last Updated: 2026-04-02T19:05:00.000Z
## Summary
Initializer refresh for the current Scopone Scientifico codebase. The existing findings were stale relative to the latest AI and tracker implementation, so the observations below reflect the current source tree.
Initializer refresh for the current Scopone Scientifico codebase. The existing findings were stale relative to the current worker-backed AI execution path, so the observations below reflect the live source tree.
## Codebase Observations
- Primary gameplay code lives in 8 TypeScript source files under `src/`; the Android wrapper adds 3 Java files.
- The largest modules are `src/scenes/GameScene.ts` (1446 lines) and `src/game/ai.ts` (1210 lines).
- The gameplay runtime now includes three AI transport files in addition to the rules engine: `ai-worker-protocol.ts`, `ai-worker-client.ts`, and `ai.worker.ts`.
- The largest concentration of logic still sits in `src/scenes/GameScene.ts` and `src/game/ai.ts`.
- `src/game/` remains framework-independent and contains the rules engine, score calculation, card tracker, and AI logic.
- The AI now has three distinct difficulty levels: `beginner`, `advanced`, and `master`.
- The `advanced` and `master` tiers use `CardTracker` to reason about unseen cards instead of reading hidden hands directly.
- The `master` tier performs determinization plus alpha-beta search and reports progress back to the scene.
- `GameScene` displays AI progress through a top think bar and updates it from the `AIDecisionProgress` callback.
- The `master` tier performs determinization plus alpha-beta search and reports progress back through `AIDecisionProgress`.
- `GameScene` displays AI progress through a top think bar and updates it from worker-forwarded progress messages.
- `AIWorkerClient` degrades cleanly to in-thread `chooseMove()` execution when workers are unavailable or fail.
- Audio remains fully procedural via Web Audio; no audio asset pipeline is present.
- No ESLint or Prettier config is present.
- The only repository-wide verification command supplied is `npx tsc --noEmit`.
@@ -23,6 +25,7 @@ Initializer refresh for the current Scopone Scientifico codebase. The existing f
- `GameScene.ts` still centralizes scene layout, input, effects, audio, HUD, and round transitions in one file, which raises maintenance cost.
- `ai.ts` mixes heuristic tiers, inference helpers, determinization, and alpha-beta evaluation in one module.
- Worker message types and fallback behavior are separated cleanly, but the UI still knows about AI progress presentation details directly.
- The `master` profile allows up to 9800 ms of search budget, which may be expensive on slower devices even with batch yielding.
- There is still no dedicated automated test suite for rules or AI behavior beyond type-checking.
- Formatting rules are enforced socially rather than by a linter/formatter toolchain.
@@ -43,6 +46,14 @@ Initializer refresh for the current Scopone Scientifico codebase. The existing f
- `master` orders legal moves with a quick evaluator, samples hidden hands, then scores moves with alpha-beta search under a deadline.
- `masterMove()` yields back to the browser between batches so Phaser can repaint the progress UI.
### Worker execution snapshot
- `GameScene` creates a fresh `AIWorkerClient` on scene creation and disposes it on shutdown.
- `AIWorkerClient` serializes a tracker snapshot instead of sending a live `CardTracker` instance across the worker boundary.
- `ai.worker.ts` reconstructs tracker state with `CardTracker.fromSnapshot()` before calling `chooseMove()`.
- Progress, results, and serialized worker errors all travel through `ai-worker-protocol.ts`.
- If worker initialization, posting, or message deserialization fails, pending requests are rerun with the in-thread AI path.
### Scene / UI implementation snapshot
- `MenuScene` exposes difficulty selection before match start.