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 src/scenes/*.js as 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, with spawning handled by src/spawn.js and goal messaging handled by src/goals.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.
• src/scenes/: Scene presets split per file (scene-*.js) plus index.js that registers them to window.PhysilinksScenes (e.g., zero-G grid, balanced, low-G, fast drop, lava drift).
• src/scenes/scene-template.js: Reference-only template documenting every scene config option; not loaded by default.
• src/config.js: Base game config defaults (gravity, spawn timing, link settings, palettes, message defaults).
• src/engine.js: Matter engine/render/runner setup helpers (create, start/stop runner, resize render).
• src/decomp-setup.js: Registers poly-decomp with Matter to allow concave shapes (stars, blobs) built via Bodies.fromVertices.
• src/ui.js: DOM access, HUD updates, overlays, popups, and control/selector wiring.
• src/spawn.js: Spawner utilities (intervals, batch/column/grid spawns), ball creation (shapes/blobs), radius scaling, and blob cleanup.
• src/goals.js: Goal computation and messaging (timer/score/clear/color goals, milestone announcements, intro message).
• src/input.js: Pointer/touch handling, drag constraints, chain linking/undo flow, and input event wiring.
• src/main.js: Physics setup, state machine, chain interaction, scene application, and pause/restart logic; delegates spawn duties to src/spawn.js, goal handling to src/goals.js, and input/chain interactions to src/input.js.

Development quick start

• No build step. Open index.html directly in the browser.
• Key files: index.html (layout), styles.css (styling), src/ui.js (DOM/HUD), src/main.js (physics/game logic), src/scenes/index.js (scene registration).
• Adjust or add scenes by extending the files in src/scenes/ with config and a createBodies(width, height) function.

Adding a new scene

• Create src/scenes/scene-<your-id>.js based on src/scenes/scene-template.js or an existing scene, and keep the id aligned to the filename suffix.
• Add the script tag to index.html with the other scene files so it loads in the browser.
• Register the scene id in src/scenes/index.js (append to desiredOrder or rely on the unordered fallback).
• If the scene uses new DOM ids/classes or storage keys, document them in your commit notes per the repo guidelines.