34 lines
3.1 KiB
Markdown
34 lines
3.1 KiB
Markdown
# Physilinks
|
||
|
||
Physilinks is a browser-based physics linking game built with Matter.js. Match and chain same-colored falling balls; link enough to clear them and rack up points.
|
||
|
||
## Play instructions
|
||
- Open `index.html` in a modern browser (desktop or mobile touch).
|
||
- Choose a scene from the selector (changes gravity, obstacles, spawn rate, palette, ball size). Switching scenes restarts the run.
|
||
- Click/touch a ball to start a chain; drag through balls of the same color to add them. Drag back to the previous ball to undo the last link.
|
||
- Release: if the chain length is below the minimum, links vanish; if it meets/exceeds the minimum, linked balls are cleared and you score `10 × length²` (popup shows the gain).
|
||
- The top is open; if a new ball cannot enter because the entry is blocked, the run ends. The overlay shows final score with a restart button.
|
||
- Pause/resume with the button or `Esc`. HUD shows spawn rate, min link, chain length, score, per-scene high score, and palette legend.
|
||
|
||
## Tech notes
|
||
- **Engine**: Matter.js (via CDN). Canvas rendering with custom overlays for HUD, pause, game over, and score popups.
|
||
- **Scenes**: Defined in `scenes.js` as an array of presets (config + `createBodies` factory). Applying a scene updates gravity, spawn rate, ball radius, palette, link constraints (stiffness/stretch/damping/width), and static bodies, then restarts the game.
|
||
- **Physics entities**: Falling balls (`Bodies.circle`) with gentle restitution/friction; static boundaries/obstacles per scene. The top is open; sides and floor are static bodies.
|
||
- **Input**: Pointer/touch events mapped to scene coords; chain state tracks bodies and a dashed preview line to the pointer. Undo by dragging back to the previous node.
|
||
- **Scoring**: `10 × length²` per cleared chain. Score popup rendered as DOM element near release point (via UI module).
|
||
- **Persistence**: Per-scene high score stored in `localStorage` under `physilinks-highscore-<sceneId>`; loaded on scene change; HUD shows current scene's best.
|
||
- **Game loop**: Single Matter runner controlled in `main.js`. Pause/game over stop the runner and spawner and zero `engine.timing.timeScale` so physics and rotating obstacles freeze; resume restarts the runner and spawner.
|
||
- **Lose detection**: Spawned balls monitor entry; if they remain near the spawn zone with negligible velocity after a short delay, the run is over.
|
||
|
||
## File structure
|
||
- `index.html`: Shell layout and HUD overlays; loads Matter.js plus game scripts.
|
||
- `styles.css`: Styling for canvas, HUD, overlays, and score popups.
|
||
- `scenes.js`: Scene presets and per-scene static body factories.
|
||
- `ui.js`: DOM access, HUD updates, overlays, popups, and control/selector wiring.
|
||
- `main.js`: Physics setup, state machine, chain interaction, spawning, scene application, and pause/restart logic.
|
||
|
||
## Development quick start
|
||
- No build step. Open `index.html` directly in the browser.
|
||
- Key files: `index.html` (layout), `styles.css` (styling), `ui.js` (DOM/HUD), `main.js` (physics/game logic), `scenes.js` (scene data).
|
||
- Adjust or add scenes in `scenes.js` by extending the `scenes` array with config and a `createBodies(width, height)` function.
|