How andrewwoan/woan-minecraft-folio works
Project type and purpose
• This is a single-page, front-end only “immersive three.js portfolio” built with React (JSX/SCSS), Vite, and Three.js.
• Purpose: deliver a 3D Minecraft-inspired interactive portfolio with audio, models, UI overlays, and modal interactions.
Key architectural components
A. Host & Build
• Vite dev server / build pipeline (vite.config.js, package.json scripts)
• Static file host (serves public/ assets: audio, models, images, WASM)
B. Application Shell
• index.html → root
• main.jsx → ReactDOM.render + global styles (index.scss)
C. UI Layer (React Components)
• Reusable UI components (src/components/...): Buttons, Info, Modal, LoadingScreen, AudioToggleButton, Project, About
• SCSS modules for styling
D. 3D Experience Layer
• Experience.jsx: sets up Three.js scene, renderer, camera, lighting
• Scene.jsx: mounts canvas, orchestrates model loading and update loop
• Model wrappers (src/Experience/models/*.jsx): load and place GLB assets in scene
E. State Management
• Stores (src/Experience/stores): audioStore (controls SFX/music), modalStore (open/close UI overlays)
• React hooks for subscribing to state changes
F. Asset Pipeline / Utilities
• wasm transcoder (public/basis/basis_transcoder.wasm + .js) for KTX2 texture decoding
• Helpers & hooks (src/Experience/utils): material conversion, GLTF loader wrapper, general utilities
• Global utilities (src/utils/audioSystem.js) for centralized audio playback
How components interact
• The browser loads index.html → main.jsx bootstraps React app.
• UI Layer and Experience Layer coexist:
• Experience sets up WebGL canvas and scene graph.
• UI Layer components overlay HTML controls that dispatch actions to stores.
• Stores mediate audio playback and modal visibility.
• Utility functions/hook abstract WebGL asset loading (GLTF + KTX2 via WASM) and material conversion.
• Vite bundles all JS/JSX/SCSS, copies public assets and WASM into final build.
Architectural patterns & principles
• Component-based UI (React)
• Separation of concerns: UI vs. 3D experience vs. state vs. assets
• Hook-based state management (lightweight custom stores, akin to Zustand)
• Asset loading pipeline abstracted via utility hooks
• WASM integration for texture transcoding