3D Magnetic Pieces combines guided magnetic-tile tutorials with a browser-based 3D editor and a deterministic geometry engine. Families can explore models step by step, while contributors can extend the model catalog, connection rules, validation logic, and learning experience.
Step-by-step 3D tutorials across multiple themes and difficulty levels
Desktop 3D editor with geometry, connection, serialization, and validation tools
Physical and semantic checks for pieces, connections, construction steps, and model integrity
Responsive learning UI for desktop, tablet, and mobile devices
Unit and Playwright E2E test suites covering models, routes, rendering, and editor workflows
Tech Stack
Framework: React 18 + TypeScript
Build tool: Vite 8
Styling: Tailwind CSS 3
Icons: Lucide React
Routing: React Router DOM 6
3D engine: Three.js + @react-three/fiber + @react-three/drei
Testing: Vitest 3 + Testing Library + Playwright
Requirements
Node.js 20 or later
npm 10 or later
Getting Started
One-click startup on Windows
Double-click 启动磁力片网站.cmd. The script checks port 5174, installs missing dependencies, starts the development server, and opens the browser. Run 停止磁力片网站.cmd to stop it.
Development commands
bash
# Install dependencies
npm install
# Start the website on port 5174
npm run start-site
# Run unit tests in watch mode
npm test# Run unit tests once
npm run test:run
# Run Playwright E2E tests
npm run test:e2e
# Type-check and create a production build
npm run build
Open . See CONTRIBUTING.md for the complete development and pull-request workflow.
Deployment
The application uses BrowserRouter, so static hosting must provide an SPA fallback to index.html.
Vercel
Push the repository to GitHub.
Import it into Vercel.
The included vercel.json supplies the required rewrite rule.
Netlify
Push the repository to GitHub.
Import it into Netlify.
The included netlify.toml supplies the required redirect rule.
Nginx
nginx
location / {
try_files $uri $uri/ /index.html;
}
Project Structure
…
Model Catalog
The project currently includes seven models across house, vehicle, rocket, animal, and castle themes.
Model
ID
Theme
Difficulty
Age
Pieces
Steps
Structure
Cozy House
house-1
House
Medium
4–6
12
3
3D
Race Car
car-1
Car
Easy
3–5
5
4
Flat
Rocket
rocket-1
Rocket
Medium
4–6
6
4
Flat
Cat
cat-1
Animal
Easy
3–5
7
4
Flat
Rainbow Castle
castle-1
Castle
Hard
6–12
20
5
3D
Penguin
penguin-1
Animal
Easy
3–4
8
4
Flat
Dream 3D House
flagship-house-1
House
Hard
5–10
29
9
3D
Supported shapes: square, rectangle, equilateral triangle, isosceles triangle, right triangle, elongated right triangle, trapezoid, rhombus, pentagon, hexagon, sector, and semicircle.
Features
Home
Featured models, theme browsing, and difficulty selection
Popular-model grid on desktop and horizontal scrolling on mobile
Direct entry points to the editor and learning center
Parent-child play tips
Model catalog and details
Search and filters for theme, difficulty, age, and structure type
Shareable URL-based filter state
Interactive 3D preview, parts list, learning goals, and parent guidance
Construction-step preview and a direct start-building action
Step-by-step tutorials
Interactive 3D construction scene with newly added pieces highlighted
Clickable step timeline, parts list, instructions, and parent prompts
Desktop split layout and mobile vertical layout
Camera reset controls
Learning center
Shape reference
Connection tutorials
Basic structure exercises
Safety and maintenance guidance
3D editor and engine
Desktop model-authoring workspace
Geometry, connection, serialization, and solver modules
Physical, semantic, inventory, and step-coverage validation
Unit, integration, route, visual-regression, and Playwright E2E tests
Responsive Design
Desktop: content up to 1440 px wide, shared top navigation and footer, and the complete editor workspace
Mobile: optimized for a 390 px viewport with fixed bottom navigation
Tablet: adaptive layout optimized around a 768 px viewport
The learning website is responsive across devices. The professional editor is intentionally optimized for desktop use.
Roadmap
Local favorites
Saved building progress with localStorage
Magnetic-tile learning center
Desktop design system
Voice guidance
Video tutorial support
User-uploaded models
Social sharing
Real magnetic-tile image assets
Multilingual application UI
Building timer
Achievement system
Contributing and License
Read CONTRIBUTING.md before opening an issue or pull request. The project is released under the MIT License.