Minecraftonia - .NET 9 / C# 13, Avalonia로 진행중인 복셀 샌드박스

프로그래밍 C# / .NET
1

Minecraftonia - C#/.NET 기반 복셀 샌드박스 게임

프로젝트 개요

Minecraftonia는 C# 13/.NET 9와 Avalonia를 사용하여 개발 중인 크로스 플랫폼 복셀 샌드박스 게임입니다. 커스텀 복셀 레이 트레이싱, 절차적 지형 생성, 반응형 데스크톱 UI를 실험하는 프로젝트입니다.

핵심 기능

1. 커스텀 복셀 엔진

  • 수제 플레이어 물리학: 블록 상호작용과 청크 없는 세계 표현

  • 실험 최적화: 튜닝된 게임 플레이 경험

2. 소프트웨어 레이 트레이싱

  • 실시간 복셀 레이 마처: WriteableBitmap으로 세계를 렌더링

  • 독특한 스타일: GPU 셰이더 없이 구현된 특별한 시각적 효과

3. 절차적 지형 생성

  • 레이어드 노이즈: 바이옴 기반 표면 처리

  • 나무 배치: 자동화된 식생 시스템

  • 지하 동굴: 자동 동굴 생성 시스템

4. Avalonia 기반 UI

  • 키보드/마우스 제어: 완전한 포인터 캡처

  • 설정 가능한 감도: 반전 설정 지원

  • 컴포저블 UI 셸: 메뉴 시스템

5. 저장 및 재개 시스템

  • JSON 저장 파일: 세계 블록, 플레이어 상태, 팔레트 선택 저장

  • 세션 간 지속성: 게임 진행 상황 보존

시스템 요구사항

필수 요구사항

  • .NET SDK 9.0 프리뷰 이상 (dotnet --info로 확인)

  • 데스크톱 OS: macOS, Windows, Linux

  • GPU: 360×202 내부 해상도에서 소프트웨어 렌더링 처리 가능한 GPU

권장 개발 환경

  • JetBrains Rider

  • Visual Studio

  • VS Code + Avalonia 확장

설치 및 실행 방법

클론 및 빌드

git clone https://github.com/<your-account>/Minecraftonia.git
cd Minecraftonia
dotnet build Minecraftonia.sln
dotnet run --project Minecraftonia

배포 빌드

로컬 릴리스 배포

# Linux x64
dotnet publish Minecraftonia/Minecraftonia.csproj -c Release -r linux-x64 --self-contained true -o publish/linux-x64

# macOS Apple Silicon
dotnet publish Minecraftonia/Minecraftonia.csproj -c Release -r osx-arm64 --self-contained true -o publish/osx-arm64

# Windows x64
dotnet publish Minecraftonia/Minecraftonia.csproj -c Release -r win-x64 --self-contained true -o publish/win-x64

GitHub Actions 워크플로우

  • 트리거: main 브랜치 푸시, PR, v 접두사 태그

  • 빌드 대상: linux-x64, osx-arm64, win-x64

  • 자동 릴리스: 태그된 커밋에서 자동 GitHub Release 생성

  • 릴리스 생성 방법: git tag v0.3.0 && git push origin v0.3.0

게임플레이 컨트롤

기본 조작

동작 키 비고
이동 W A S D 화살표 키는 카메라 회전, Q/E는 마우스 없이 요 조정
달리기 Shift 이동 중 홀드로 속도 증가
점프 Space 지면 접촉 필요
시점 조작 마우스 F1로 포인터 캡처 토글, Esc로 해제
블록 파괴 좌클릭 현재 레이 트레이싱 히트 위치
블록 설치 우클릭 선택된 핫바 블록 설치

게임 메뉴 및 설정

동작 키 설명
일시정지/메뉴 Esc 게임 내 메뉴 오버레이 열기
X축 반전 F2 독립적 토글
Y축 반전 F3 독립적 토글
감도 조절 +/- 마우스 룩 배율 조정

인벤토리 및 아이템

동작 키 설명
핫바 1-7, Tab, 스크롤 휠 스크롤로 팔레트 순환

프로젝트 구조

Minecraftonia.sln
├── Minecraftonia/ # Avalonia 데스크톱 프론트엔드
├── Minecraftonia.Game/ # 게임 오케스트레이션, 렌더링 브릿지, 저장 시스템
├── Minecraftonia.VoxelEngine/ # 핵심 복셀 세계 데이터 구조 및 물리학
├── Minecraftonia.VoxelRendering/ # 레이 트레이서, 텍스처 아틀라스, 오버레이 헬퍼
└── publish/ # 자체 포함 배포 출력 (선택사항)

아키텍처 및 알고리즘

Minecraftonia (데스크톱 UI 프론트엔드)

  • Avalonia 네비게이션 셸: GameControl 커스텀 컨트롤 호스팅, XAML 메뉴 오버레이

  • 포인터 캡처 관리: 원시 마우스 캡처, 윈도우 중앙 포인터 워프, Esc/F1 토글

  • 컴포지터 동기화 렌더 루프: TopLevel.RequestAnimationFrame을 통한 시뮬레이션 진행

  • SIMD 인식 프레임 오케스트레이션: System.Numerics.Vector 연산 활용

Minecraftonia.Game

  • MinecraftoniaGame 오케스트레이션: 플레이어 입력, 움직임 통합, 복셀 조작, 저장/로드 조정

  • 바이옴 인식 세계 생성: 파도 함수 붕괴 타일 맵으로 8개 바이옴 지원

  • 저장 시스템: GameSaveData/PlayerSaveData로 세계 차원, 청크 매개변수, 블록 배열 캡처

  • 입력 파이프라인: 키보드/마우스/포인터 이벤트를 GameInputState로 변환

Minecraftonia.VoxelEngine

  • 청크 기반 복셀 저장소: VoxelWorld으로 청크 딕셔너리 유지

  • 점유 추적: 청크가 고체 블록 수 추적으로 컬링/스트리밍 휴리스틱 제공

  • 플레이어 물리학: 평면 위시 방향, 중력, 스프린트, 점프 해결

Minecraftonia.VoxelRendering

  • 적응형 레이 마처: 픽셀당 중앙 레이 캐스팅, 색상/알파 분산 시 지터 샘플 추가

  • SIMD 색상 파이프라인 및 FXAA: Vector4 수학으로 모든 색상 블렌딩, 루마 평가, 선명화

  • HUD 오버레이: 십자선, FPS 카운터, 핫바 선택, 블록 윤곽 그리기

데이터 흐름 요약

  1. GameControl이 입력(키보드, 마우스, 포인터 델타)을 매 프레임 수집하여 GameInputState로 마샬링하고 _game.Update 호출

  2. MinecraftoniaGame이 룩, 움직임, 상호작용을 적용하고 MinecraftoniaVoxelWorld 업데이트

  3. VoxelRayTracer가 세계를 WriteableBitmap으로 렌더링하여 GameControl.Render가 Avalonia 표면에 블릿

  4. HUD 오버레이가 팔레트 상태, FPS, 십자선, 블록 윤곽을 프레임버퍼 위에 그리기

  5. 메뉴 액션이 StartNewGame, LoadGame, CreateSaveData 또는 포인터 캡처 토글 호출

저장 파일

저장 위치

  • macOS/Linux: ~/.config/Minecraftonia/Saves/latest.json

  • Windows: %APPDATA%\Minecraftonia\Saves\latest.json

파일 형식

  • JSON 인코딩: GameSaveData 객체

  • 오류 처리: 손상되거나 버전 불일치 파일은 UI에서 명확한 오류 메시지와 함께 거부

개발 가이드

기여 방법

  1. 포크 및 브랜치: main에서 분기 (예: feature/improve-water)

  2. 빌드 확인: dotnet build Minecraftonia.sln 실행

  3. 문서화: 새 애셋이나 저장 스키마 추가 시 README 문서화

  4. PR 생성: 간결한 설명과 스크린샷/비디오 포함

개발 팁

  • 범위 제한: 변경사항을 범위 내로 유지

  • 테스트: 빌드 성공 확인

  • 문서화: 새 기능은 README에 문서화

로드맵

단기 목표

  • 다중 저장 슬롯: 저장 미리보기 기능

  • 설정 가능한 세계 생성: 시드와 바이옴 레이어 커스터마이징

중기 목표

  • 동적 낮/밤 조명: 날씨 시스템

  • 접근성 개선: 색맹/고대비 모드

장기 목표

  • 멀티플레이어 프로토타입: 네트워크 기능

라이선스 및 크레딧

라이선스

GNU Affero General Public License v3.0

크레딧

  • 제작자: Wiesław Šoltés (@wieslawsoltes)

  • 엔진 기초: 이 프로젝트를 위해 특별히 제작된 커스텀 복셀 수학, 물리학, 렌더링

  • 라이브러리: Avalonia UI, System.Numerics (SIMD), .NET 런타임

링크

2

image
image1282×752 117 KB