Bolt Screw Puzzle Project Report
1. The Concept
Bolt Screw Puzzle is a mobile-style wood bolt puzzle game inspired by casual titles like *Wood Screw: Bolts Puzzle*. The player taps screws, moves them to empty holes, and uses gravity to drop layered planks off the board. The goal is to clear every wooden piece before time runs out — simple to learn, but tricky when planks pivot, overlap, and block each other.
The project was built as a zero-install browser game: clone the repo, open index.html, and play. No npm, no build pipeline, no backend.
2. The Stack
The Stack: HTML5, CSS3, Canvas 2D, vanilla JavaScript, Matter.js (vendored in vendor/), Web Audio API, localStorage for save data, and Python + Pillow for optional procedural PNG asset generation (tools/generate_v2_assets.py).
The AI Assist: Cursor AI pair-programmed the full loop — level design, canvas rendering, custom pivot physics, Matter.js integration for falling planks, screw-collision slide-off logic, UI polish (start screen, HUD, settings, tutorial), 100-level procedural expansion, icon generation, project cleanup, and documentation (README.md).
3. The 1 Day Sprint
Morning (Hours 1–3): Core game shell and reference alignment. Built the canvas board, screw tap/move flow, plank hole cutouts, support detection (screws only hold planks when aligned with attachment holes), and basic fall/pivot physics. Matched the v2 visual direction with wood backgrounds, procedural plank textures, and a mobile 9:16 (later 10:16) portrait frame.
Afternoon (Hours 4–6): Polish and feel. Added screw twist/lift animations, move arcs, Web Audio SFX, hit-target improvements, screen shake and particles, hard-level variants (locked screws, bomb timers, metal planks), circle plank shapes, and Matter.js for realistic falling/sliding after release. Expanded content to 15 handcrafted + 85 procedural levels and wired hint, undo, drill, and boost power-up logic.
The Finish Line (Hour 7–8): Bug fixes, cleanup, and ship-ready docs. Fixed planks stuck on screws (block.geometry undefined in slide-off code), tuned UI buttons (undo-btn-v2, hint-btn-v2), removed ~27 unused assets and obsolete scripts, wrote README.md, and verified the project runs with no install beyond a browser.
4. The Roadblocks
Roadblocks: Matching reference videos (v1/v2) while keeping gameplay readable was harder than art alone — early z-order experiments made screws hard to tap and physics feel wrong, so screws were kept on top with enlarged hit radii instead. Planks resting on (but not pierced by) screws would freeze mid-pivot until collision slide-off logic was fixed. A typo (0xW00D) broke procedural level generation silently. UI evolved from image-based footer bars to CSS-native HUD, leaving many generated PNGs unused until a dedicated cleanup pass. Balancing custom pivot math with Matter.js required a hybrid: pivot on one screw in canvas logic, full rigid-body simulation only after release.
5. Key Takeaways
Shipping a small puzzle game in one day is feasible when scope stays browser-native and assets are procedural or vendored. The hardest problems were feel (tap accuracy, fall/slide believability), not rendering. Keeping screw positions tied to plank attachment holes made support logic and visuals stay in sync. A hybrid physics model — custom pivots + Matter.js drops — gave better control than either approach alone. Cleaning unused files early would have reduced confusion; documenting clone-and-run steps in README.md makes handoff trivial.
My final thought: Bolt Screw Puzzle proves a polished casual puzzle can live entirely in static files — and that the last 20% (physics edge cases, touch targets, one-day cleanup) is what separates a demo from something people actually want to keep playing.