Three.js React Hackathon Boilerplate

A modern boilerplate for building 3D web applications using React, Three.js, TypeScript, Vite, and shadcn/ui. This project provides a well-structured foundation for hackathons, game jams, or any creative 3D web project.

🚀 Features

• React 18 with TypeScript
• Three.js integration via React Three Fiber
• Cannon.js for physics
• Vite for fast development and building
• shadcn/ui for beautiful UI components
• Tailwind CSS for styling
• ESLint for code quality
• Prettier for consistent code formatting
• Tailwind Class Sorter for automatically organizing Tailwind classes

📦 Project Structure

src/
├── components/     # 3D scene components (<SceneCanvas />, <Player />, etc.)
│   └── ui/         # shadcn/ui primitives
├── hooks/          # Custom hooks (useControls, useFollowCamera, etc.)
├── systems/        # Global loop logic (physics, animation, AI)
├── stores/         # Global state management (Zustand/Jotai)
├── loaders/        # Asset loading logic
├── utils/          # Helpers and math utilities
├── ui/             # High-level UI components (menus, HUD)
├── shaders/        # Custom GLSL shaders
├── App.tsx         # Main app layout
└── main.tsx        # Vite entry point
memory-bank/        # Project documentation and planning
├── PRD.md          # Product requirements document
└── plan.md         # Development roadmap and milestone tracking

🛠️ Getting Started

Prerequisites

• Node.js (v18+)
• yarn

Installation

1. Click the "Use this template" button at the top of this repository
2. Create a new repository from the template

Or clone manually:

# Clone the repository
git clone https://github.com/vltansky/wow-vibe-coding.git
cd wow-vibe-coding

# Install dependencies
yarn

Development

# Start dev server
yarn dev

Build

# Build for production
yarn build

Code Formatting

The project uses Prettier for consistent code formatting. Formatting will automatically be applied when you save files if you're using VSCode with the recommended extensions.

# Format all files
yarn format

# Check if files are formatted correctly
yarn format:check

🔌 Cursor: Model Context Protocol (MCP)

The project leverages Model Context Protocol (MCP) for enhanced AI-assisted development. MCPs provide contextual understanding and specialized tools for different aspects of development:

• Three.js MCP: Provides AI-assisted access to Three.js documentation, examples, and best practices
• Cannon-es MCP: Offers physics-related documentation and implementation guidance
• Context7: Advanced code context analysis and documentation lookup
• Playwright MCP: Browser automation and testing capabilities

These MCPs enable:

• AI-powered documentation assistance
• Contextual code suggestions
• Automated testing and browser control
• Enhanced development workflows through AI understanding of specific domains

📚 Documentation

• Three.js Documentation
• React Three Fiber
• shadcn/ui Documentation
• Tailwind CSS Documentation
• Vite Documentation

Three.js Game Asset Resources

2D Assets

• OpenGameArt (Free): Pixel art, sprites, tilesets (PNG). Best for indie prototyping. opengameart.org
• Itch.io (Free/Paid, $5-$20): Pixel art, UI, tilesets (PNG). Stylized indie look. itch.io
• Kenney (Free/Donation): Sprites, UI (PNG). Rapid prototyping. kenney.nl
• FLUX.1 (Hugging Face) (Free/Paid): AI-generated textures (PNG). Free tier; paid via fal.ai/Replicate. Custom prototyping. huggingface.co
• CraftPix.net (Free/Paid, $5-$50): UI kits, sprites, effects (PNG). Clean UI focus. craftpix.net
• Lospec (Free): Pixel art palettes, tools (PNG). Stylized palette design. lospec.com

3D Assets

• Trellis (Hugging Face) (Free): AI-generated models (GLB) from FLUX.1 images. Rapid prototyping. huggingface.co/spaces/JeffreyXiang/TRELLIS
• Sketchfab (Free/Paid, $10-$100): Models (GLTF/GLB). High-poly, realistic. sketchfab.com
• Poly Pizza (Free): Low-poly models (GLTF). Stylized indie look. poly.pizza
• Clara.io (Free): Models, materials (GLTF). Simple prototyping. clara.io
• CGTrader (Free/Paid, $5-$50): Models (FBX, convert to GLTF). Realistic assets. cgtrader.com
• Mixamo (Free): Rigged characters, animations (FBX, convert to GLTF via Blender plugin/FBX2GLTF). Animated prototyping. mixamo.com
• Hunyuan 3D (Free/Paid): AI-generated models (GLTF). Custom prototyping. 3d-models.hunyuan.tencent.com
• MeshyAI (Free/Paid, ~$10/mo): AI-generated models (GLTF). Stylized prototyping. meshy.ai
• Quaternius (Free): Low-poly packs (GLTF/FBX). Stylized indie look. quaternius.com
• Turbosquid (Free/Paid, $10-$200): Models (FBX/GLTF). High-poly, realistic. turbosquid.com
• Google Poly Archive (Free): Mirrored low-poly models (OBJ/GLTF). Basic prototyping. poly.google.com

Sound Assets

• Freesound (Free): Effects, loops (WAV/MP3, some need attribution). General prototyping. freesound.org
• Zapsplat (Free/Paid, $20-$60/yr): Effects, music (MP3/WAV). Game soundscapes. zapsplat.com
• Itch.io (Free/Paid, $5-$15): Chiptune, effects (WAV/MP3). Retro indie look. itch.io
• Kenney Audio (Free/Donation): Effects, loops (WAV). Rapid prototyping. kenney.nl
• ElevenLabs (Free/Paid, ~$5/mo): AI-generated SoundFX (WAV/MP3). Custom effects. elevenlabs.io
• SunoMusic (Free/Paid, ~$10/mo): AI-generated music (MP3/WAV). Vibe-coded soundtracks. suno.com
• Bfxr (Free): Procedural retro sound FX (WAV). Retro prototyping. bfxr.net

Skybox Assets

• Blockade Labs (Free/Paid, ~$10/mo): AI-generated 360° skyboxes (cube maps, PNG). Stylized environments. skybox.blockadelabs.com

Animation/Sprite Helpers

• Rive (Free/Paid, ~$15/mo): Realtime 2D animations (SVG/canvas). Dynamic UI/prototyping. rive.app
• Aseprite (Paid, $20): Sprite sheets, pixel art animations (PNG). Stylized indie look. aseprite.org

Optimization & Conversion Tools

• Blender (Free): Convert FBX/OBJ to GLTF, decimate models. Asset optimization. blender.org
• glTF-Transform (Free CLI): Compress/optimize GLTF files. Performance tuning. gltf-transform.donmccurdy.com

Workflow Helpers

• Three.js Editor (Free): Online scene editor. Rapid prototyping. threejs.org/editor
• Spline (Free/Paid, ~$7/mo): 3D design with Three.js export (GLTF). Intuitive prototyping. spline.design

Notes

• Formats: GLTF/GLB for 3D, WAV/MP3 for audio, PNG/SVG for 2D. Convert FBX/OBJ to GLTF via Blender/FBX2GLTF.
• Vibe Coding: Trellis, FLUX.1, MeshyAI, ElevenLabs, Suno, Blockade Labs enable AI-driven workflows.
• Licensing: Verify commercial use. Free tiers have limits; paid tiers offer quality/volume.
• Community: Three.js Discord, r/threejs for integration tips.