black-8-master

Black 8 Master is a single-player Chinese eight-ball PWA designed for landscape mobile. You can play it by opening the web page, add it to your phone's home screen, and run it offline after the first load. In terms of gameplay, players slide a finger on the table to adjust the cue direction, control shot power with the power bar on the right, and tap "Shoot" to confirm. After the first legal pot, solids or stripes are assigned; after clearing your own group, potting the black 8 wins the game. If the cue ball is potted, no target ball is hit, or the wrong group is hit first, it is a foul and the opponent gets ball in hand; when the player gets ball in hand, tapping a legal position on the table moves the cue ball. Functionally, the project uses Matter.js to implement ball collisions, cushion rebounds, friction deceleration, and six-pocket detection, and includes simplified Chinese eight-ball rules, complete turn state, and win/loss determination. It provides three computer opponent levels: easy, normal, and hard, three sets of table, cue, and environment themes, as well as adjustable aiming line, power sensitivity, sound effects, and vibration. The interface adapts to landscape safe areas and supports offline caching and installable PWA. Local development requires Node.js 22+ and pnpm. After running pnpm install and pnpm dev, open the local address shown in the terminal in a browser and rotate the phone to landscape. To verify, run pnpm test and pnpm build. Tests cover rule fouls, AI legal target selection, collisions, friction, cushion reflection, and pocket detection. In the release process, every push to the main branch runs tests and a production build. After all pass, GitHub Actions publishes dist to GitHub Pages; for the first release, select GitHub Actions in the repository Settings → Pages → Build and deployment. The tech stack is TypeScript, Vite, Phaser 3, Matter.js, Vitest, and vite-plugin-pwa.