🎹 3D Mechanical Keyboard Simulator

A beautiful, interactive 3D mechanical keyboard demo built with Vite and Three.js. Press your physical keys to see the 3D keycaps animate, hear satisfying switch samples, and experiment with themes, layouts, and lighting.

---

✨ Highlights

• Interactive 3D keyboard with realistic key animations
• Selectable switch sound sets (Red, Blue, Brown, Black)
• macOS / Windows labeling and multiple visual themes
• Lightweight: baked lighting, cached textures, and optimized meshes

---

🚀 Quick start

1. Clone the repo

git clone <repo-url>
cd keyboard
npm install

2. Start the dev server

npm run dev

Vite serves the app (default port 3000) and should open your browser automatically.

To build for production:

npm run build
npm run preview

---

🧩 What you can do

• Press any physical key to animate the corresponding 3D keycap and play a switch sound
• Toggle layouts between macOS and Windows (legend rendering updates automatically)
• Change themes and dark mode from the settings panel
• Adjust room lighting intensity for different presentation moods
• Scroll to zoom the camera (rotation and panning intentionally disabled)

---

📁 Project structure (key files)

• index.html — App shell and UI controls
• src/main.js — Bootstraps the Three.js scene, UI wiring, and animation loop
• src/Keyboard.js — Builds and rebuilds the keyboard mesh from layout data
• src/Key.js — Keycap geometry, legend rendering, and press animations
• src/KeyboardLayout.js — 65% layout, key sizes, and theme color lookup
• src/InputHandler.js — Maps browser keyboard events to animations and audio
• src/SoundManager.js — Loads switch samples from public/sounds/ and plays them
• src/SettingsManager.js — Centralized settings (layout, theme, dark mode)

Public assets

• public/sounds/ — Switch audio files named {switch-type}-{index}.mp3

---

🛠 Development notes

• Use the setters in src/SettingsManager.js to change layout/theme so events keep the UI in sync
• When rebuilding the keyboard, dispose of old meshes/materials/geometries and call clearKeyCaches() to avoid memory leaks
• Keep asset paths root-relative (e.g. /sounds/red-1.mp3)

---

📦 NPM scripts

• npm run dev — Start Vite dev server
• npm run build — Create production bundle
• npm run preview — Preview production build locally

---

Contributing

Contributions welcome — open issues or PRs. For UI changes, preserve the baked-lighting approach and avoid enabling real-time shadows.