A complete, production-ready boilerplate for a 3D minigolf game built with React, Three.js, and TypeScript.
This project is aligned with CloneFest 2025 Problem Statement 3 — Reimagining a C-based Minigolf Classic.
The primary goal is to render a single, static 3D golf hole using Three.js.
Players must be able to strike a golf ball, see it respond to physics (with friction), and complete a simple gameplay loop from input → ball movement → hole completion.
# Install dependencies
npm install
# Start development server
npm run dev
# Build for production
npm run build
# Preview production build
npm run preview
✅ Project Requirements
Scene and Asset Rendering
Initialize a Three.js scene with camera, lighting, and renderer.
Load and display a 3D model representing a golf hole.
Render a sphere to represent the golf ball at a start position.
Basic Physics and Interaction
Implement input to apply velocity to the ball.
Use a simple custom physics model with friction so the ball slows and stops.
A full physics engine is not required.
Gameplay and State Management
Track game state: hole, par, strokes.
Detect when the ball reaches the hole (goal detection).
Implement at least 2 levels (holes).
Player Controls
Aiming precision: players can choose shot direction.
Power control: players can choose shot strength.
Provide clear visual feedback during aiming and power selection.
Camera System
Interactive camera with orbit, pan, and zoom.
User Interface
HTML/React UI that shows hole number, strokes, and game state.
Include interactive elements like reset or next-hole buttons.
🎮 Features
Three.js Scene: Lighting, camera, renderer configured.
Two Holes Ready: Pre-configured levels to meet requirements.
Ball Physics: Velocity, friction, stop condition.
Controls: Aim + power drag system with visual guides.
Camera: Orbit/pan/zoom enabled via OrbitControls.
UI: Score, strokes, and par displayed with clean React components.
🏗️ Project Structure
src/
├── components/
│ ├── game/
│ │ ├── GameCanvas.tsx # 3D rendering + scene
│ │ ├── GameUI.tsx # Scoreboard and HUD
│ │ └── StartScreen.tsx # Welcome / instructions
│ └── ui/ # Reusable UI components
├── lib/
│ ├── gameEngine.ts # Three.js setup
│ ├── gameState.ts # Game state management
│ └── assetLoader.ts # Load GLTF models
├── utils/
│ ├── physics.ts # Friction + ball motion
│ └── scoring.ts # Score calculation
└── index.css # Turf + design system
Assets (levels) should be placed in public/assets/models/ as .glb or .gltf files.
📱 Browser Support
Modern browsers (Chrome, Firefox, Edge, Safari).
Requires WebGL support.
Touch support for mobile (aim + power drag).
🏆 Hackathon Ready
Zero Config: Works out of the box.
Extensible: Add new levels and physics easily.
Production Build: Optimized with Vite + React.
Open Source: MIT licensed.
📝 License
MIT License — suitable for hackathons and open-source use.
🤝 Contributing
Fork the repo
Create a feature branch
Make changes + test
Submit a PR
Built with ❤️ for CloneFest 2025