규칙의 나라 (Class Republic)
규칙의 나라는 Next.js와 React Three Fiber(R3F)를 기반으로 구축된 3D 학급 경영 및 게이미피케이션 플랫폼입니다. 교사와 학생이 입법(국회), 행정(정부), 경제 활동을 3D 메타버스 환경에서 직접 체험하고 만들어갈 수 있도록 설계되었습니다.
🚀 Tech Stack
- Framework: Next.js 14+ (App Router)
- UI & 3D Rendering: React, React Three Fiber (R3F), Three.js, Drei
- State Management: Zustand
- Database & Auth: Supabase (PostgreSQL, RPC, Auth)
- Styling: CSS Modules, Inline Styles (Glassmorphism UI)
🏗️ Core Features & Architecture
1. 3D World & Editor (메타버스 및 맵 에디터)
Map3D: 메인 3D 월드 화면으로, 인게임 플레이어(Character)와 상호작용 가능한 요소들이 배치되는 뷰어입니다.MapEditor / MapEditorLegacy:
- 지형 생성 (Terrain): 지형의 높낮이 조절, 물(Water) 배치, 브러시를 이용한 페인팅이 가능합니다.
- 에셋 및 커스텀 아이템 배치 (AssetManager): 나무, 바위, 집, NPC, 그리고 직접 만든 커스텀 3D 모델(GLTF/GLB) 을 맵에 배치할 수 있습니다.
- 최근 업데이트: 커스텀 아이템 배치 시 바닥면(Bounding Box)을 계산해 지면에 정확히 맞닿도록 보정(
GenericGLTFAsset)하는 기능이 추가되었습니다.
- 구역 및 퀘스트 설정 (BoundaryManager): 특정 구역에 접근 시 퀘스트가 발동되거나 메시지가 뜨도록 설정할 수 있습니다.
VoxelEditor: 마인크래프트처럼 블록을 쌓거나 파내고 색칠하여 자신만의 지형이나 커스텀 에셋을 디자인할 수 있는 3D 에디터입니다.
2. Assembly (국회)
학급의 법(규칙)을 제정하고 건의하는 공간입니다.
LawForm / LawsTab: 새로운 법안을 발의하고 투표를 통해 통과시킬 수 있습니다.PetitionsTab: 학생들의 건의사항(청원)을 작성하고 관리합니다.RulebookTab: 제정된 학급 규칙(법률)을 열람합니다.
3. Government (정부)
국가를 운영하는 행정부의 역할을 담당하며, 경제 정책을 총괄합니다.
EconomyGridTab / TaxTab / FinanceTab:
- 세금, 복지 비용, 직업별 월급 등을 설정하고 국가 예산을 관리합니다.
DecreeForm / DecreesTab: 정부의 행정 명령(포고령)을 공포합니다.ReceivedLawsTab: 국회에서 넘어온 법안을 확인하고 처리합니다.
4. Economy (경제 시스템)
학생들이 경제 활동을 통해 재화를 획득하고 소비하는 시스템입니다. Supabase RPC를 통해 무결성이 보장된 트랜잭션으로 처리됩니다.
BankTab: 예금, 출금, 이자 수익 관리.ShopTab: 맵 에디터용 커스텀 에셋이나 소모품 구매.StockTab: 주식(모의 투자) 시스템을 통한 자산 증식.
5. Teacher Dashboard (교사 전용)
교사가 학급 전체의 활동을 모니터링하고 제어하는 관리자 페이지입니다.
ActivityLogsTab: 학생들의 경제 활동, 법안 발의, 퀘스트 달성 등 모든 활동 로그를 실시간으로 확인합니다.EconomyAdminTab: 경제 시스템의 밸런스를 조정하거나 특정 학생에게 재화를 지급/차감합니다.QuestLogsTab: 학생들의 퀘스트 진행 상황을 모니터링합니다.
📂 Directory Structure
📦 규칙의나라 (class-republic)
┣ 📂 app
┃ ┣ 📂 api # API 라우트
┃ ┣ 📂 assembly # 국회 페이지
┃ ┣ 📂 economy # 경제 페이지
┃ ┣ 📂 government # 정부 페이지
┃ ┣ 📂 teacher # 교사 페이지
┃ ┣ 📜 page.js # 메인 3D 월드 (Map3D) 진입점
┃ ┗ 📜 layout.js # 전역 레이아웃 및 폰트 설정
┣ 📂 components
┃ ┣ 📂 Assembly # 법안 발의, 청원, 법전 UI
┃ ┣ 📂 Economy # 은행, 상점, 주식 UI
┃ ┣ 📂 Government # 세금, 복지, 행정 UI
┃ ┣ 📂 Teacher # 활동 로그, 관리자 패널 UI
┃ ┣ 📂 MapEditor # 3D 맵 에디터 컴포넌트 모음 (지형, 에셋 매니저 등)
┃ ┣ 📂 VoxelEditor # 복셀 빌딩 시스템 컴포넌트
┃ ┗ 📜 AuthProvider.jsx # 전역 인증 및 권한 관리 (Supabase Auth)
┣ 📂 store
┃ ┣ 📜 useMapStore.js # 3D 맵 상태 관리
┃ ┣ 📜 useVoxelStore.js # 복셀 에디터 상태 관리
┃ ┗ 📜 useInventoryStore.js # 유저 인벤토리 및 퀘스트 상태 관리
┣ 📂 supabase
┃ ┗ 📜 economy_init.sql # 데이터베이스 스키마 및 트랜잭션 RPC 스크립트
┗ 📜 package.json
🛠️ State Management & Data Flow
- 3D 렌더링에 필요한 무거운 상태(예: 지형 배열, 배치된 에셋 목록)는 Zustand를 사용하여 렌더링 최적화를 진행했습니다.
- 유저 데이터, 법안, 경제 내역 등 영구 저장이 필요한 데이터는 Supabase PostgreSQL에 실시간(Realtime) 연동 또는 RPC 프로시저를 통해 동기화됩니다.
💻 Getting Started (개발 서버 실행)
# 패키지 설치
npm install
# 환경변수 설정 (.env.local)
# NEXT_PUBLIC_SUPABASE_URL=...
# NEXT_PUBLIC_SUPABASE_ANON_KEY=...
# 개발 서버 실행
npm run dev
