# VoxelDraft

> VoxelDraft is a free, browser-based 3D voxel editor built with React, Three.js, and React Three Fiber. It enables users to create, edit, and export voxel art (3D pixel art) with no installation required. Features include real-time rendering, undo/redo, mirror mode, multiple export formats (OBJ, VOX, Minecraft Schematic), and a community gallery powered by Cloudflare D1.

Important notes:

- VoxelDraft is a fully client-side application with local storage for projects
- The application uses Vike (SSG/SPA) for routing and supports 3 languages (English, Japanese, Chinese)
- Gallery functionality requires Cloudflare D1 database backend
- All 3D rendering is done client-side using WebGL via React Three Fiber

## Core Documentation

- [Project Structure](docs/architecture.md): Overview of the codebase architecture, state management, and component hierarchy
- [Types System](types.ts): TypeScript interfaces for VoxelData, AppState, Tools, and all core types
- [Store/State Management](store.tsx): Zustand-based global state with undo/redo history
- [Voxel Rendering](components/Scene.tsx): Three.js scene setup with instanced mesh rendering for performance

## Key Components

- [Scene Component](components/Scene.tsx): Main 3D viewport with raycasting, camera controls, and voxel interaction
- [Tools System](components/Tools.tsx): Toolbar UI and tool selection (Add, Remove, Paint, Pick, Line, Bucket, Select)
- [Header Component](components/Header.tsx): Top navigation with export/import, language selector, and view controls
- [Animation Studio](components/AnimationStudio.tsx): GIF export with 40+ animation presets (explosions, rotations, physics effects)
- [Gallery System](components/Gallery.tsx): Community gallery with upload, like, tag, and daily challenge features

## Features & Workflows

- [Export System](exporters.ts): OBJ/MTL export with face culling, VOX format, Minecraft Schematic
- [Project Manager](projectManager.ts): Local storage-based project management with thumbnails
- [Image to Voxel](components/ImageToVoxel.tsx): Convert images to 3D voxel models with height mapping and processing filters
- [Live Recorder](components/LiveRecorder.tsx): Real-time timelapse GIF recording during modeling

## API & Backend

- [Gallery API](functions/api/gallery/[[route]].ts): Cloudflare Pages Functions for D1 database operations
- [Database Schema](migrations/schema.sql): D1 tables for gallery items, tags, likes, daily challenges
- [D1 Configuration](wrangler.toml): Cloudflare Workers configuration for database binding

## Internationalization

- [Translations](store.tsx#L60-L300): English, Japanese, Chinese UI strings
- [Routing](pages/@lang/): Dynamic language routes with SSG pre-rendering

## Optional

- [Legal Pages](components/Legal.tsx): Terms of Service and Privacy Policy components
- [Home Page](components/Home.tsx): Landing page with templates, features, FAQ
- [Blog System](blogPosts/): Markdown-based blog with multi-language support
- [Contact Form](components/Contact.tsx): Google Forms integration for user feedback