루미너스 런처
Luminous Wanderlust 전용 런처
Luminous Wanderlust를 마인크래프트 클라이언트 없이 플레이하는 Godot 전용 게임 클라이언트 (Windows·macOS·Android)
- 개발 중
- Windows · macOS · Android
INFO 기본 정보
Minecraft Bedrock RPG 서버 Luminous를 위해 Godot 4(.NET)로 직접 만든 전용 게임 클라이언트. 블록 월드 렌더링, 엔티티 모델·애니메이션, 서버 UI, Xbox 로그인, 설치 파일까지 갖춰 Windows·macOS·Android에서 마인크래프트 없이 바로 접속한다.
- 개발 기간
- 2026.09 ~ 현재
- 개발 상태
- 개발 중
- 플랫폼
- Windows · macOS · Android
- 장르
- 액션 RPG, 게임 클라이언트
- 게임 엔진
- Godot 4.7 (.NET)
- 사용 언어
- C#
ABOUT 프로젝트 소개
소개
Luminous RPG 서버에 접속하기 위해 처음엔 Electron 클라이언트를 썼지만, Godot 4(.NET)로 새로 만들면서 사실상 별도의 게임이 되었다. 마인크래프트를 설치하지 않아도 런처 하나로 로그인하고, 서버에 접속하고, 필요한 리소스를 받아 플레이한다.
서버와는 Bedrock 네트워크를 쓰지 않는다. 서버에 내장한 게이트웨이와 직접 설계한 프로토콜로 통신하고, 블록과 엔티티는 Mojang이 공개한 기본 리소스 팩과 서버 리소스 팩을 읽어 클라이언트가 직접 그린다.
타이틀 화면에서 로그인과 서버 주소를 정하고, 런처 홈에서 접속자 수와 진행 중인 이벤트를 본 뒤 게임 시작 한 번으로 접속한다. 이벤트·커뮤니티·라이브·설정 메뉴가 있다. 배포 페이지에서 Windows·Android·macOS용 설치 파일을 받을 수 있다.
주요 특징
- Godot 4 .NET으로 만든 독립 게임 클라이언트 (C# 약 9만 줄)
- 블록 메시·바이옴 색·엔티티 모델·Molang 애니메이션을 직접 렌더링
- Bedrock 네트워크 대신 서버 게이트웨이와 자체 프로토콜(WebRTC·WebSocket)로 통신
- 앱 안 Xbox 로그인, Discord 활동 표시, 터치 조작
- Windows 설치 마법사 · macOS 유니버설 앱 · Android APK 배포
게임 플레이
- Xbox 계정으로 로그인한 뒤 게임 시작을 누르면 캐릭터가 서버에 접속한다. 기본 서버 주소가 미리 들어 있고, 타이틀 화면에서 바꿀 수 있다.
- WASD 이동, 스페이스 점프, Ctrl 달리기, Shift 웅크리기, 마우스 시점, 좌·우클릭 공격·사용, 숫자 키·휠 단축 슬롯, T 채팅으로 조작한다.
- 모바일에서는 터치 조작으로 플레이하고, 자동 달리기·자동 점프·조준 보조와 버튼 크기·투명도·감도를 설정할 수 있다.
개발 연혁
- Godot 클라이언트로 새로 시작, 런처 배포 페이지와 릴리스 1.0.0 (Windows·Android·macOS)
TECH 기술 스택
설계 / 패턴
- Core: 경로, 사용자 설정, 팩 JSON 파싱, 로그
- Net: 주소 정규화, 리소스 목록 동기화, 플레이 세션(접속·이동·섹션·행동·종료), 연결 품질
- Auth: Microsoft/Xbox 로그인, 기억한 토큰 암호화 저장
- Resources: 기본+서버 팩 스택, 블록 아틀라스, 바이옴 색, 번역
- World / Entities: 섹션 메시·조명·안개·구름·시간대, 엔티티 모델·애니메이션
- Game / UI / JsonUi: 세션 루프, 이동 예측, 런처 화면·HUD·서버 폼
- Dev: 클라이언트 안에서 쓰는 스토리 편집기·던전 편집기·UI 디자이너
FEATURES 핵심 구현 기능
블록 월드와 엔티티를 직접 그리는 렌더러
마인크래프트 엔진 없이 Bedrock 리소스 팩을 읽어 월드를 그린다.
- 동작 방식
- 블록 아틀라스를 만들고, 섹션 단위로 메시를 만든다. 가려진 면 제거, 조명 곡선, 면별 음영, 바이옴 색을 적용하고 정육면체·교차형 식물·반 블록·액체 모양을 지원한다.
- 바이옴 색은 색 지도와 색조 규칙을 따라 계산하고, 안개·구름·시간대·색 보정으로 분위기를 낸다.
- 엔티티는 Bedrock 모델과 애니메이션을 읽고 Molang 식을 계산해 움직인다. Molang 의미 검사 하네스로 결과를 확인한다.
- Mojang이 공개한 기본 리소스 팩은 설치 파일에 넣지 않는다. 실행할 때 공식 저장소의 최신 리비전을 확인해 바뀌었을 때만 받고, 검증을 통과해야 교체한다. 실패하면 이전 팩을 그대로 쓰고, 한 번 받은 뒤에는 오프라인에서도 실행된다.
- 사용 기술
서버 게이트웨이와 자체 프로토콜
- 동작 방식
- 서버에 내장한 게이트웨이와 WebRTC 또는 WebSocket으로 직접 설계한 프로토콜을 주고받는다. Bedrock 패킷은 이 연결로 오가지 않는다.
- 이동은 서버가 최종 결정하고, 클라이언트는 이동·블록 예측과 보간으로 지연을 가린다. 지형 섹션은 받는 속도를 조절하며 스트리밍한다.
- 서버 리소스는 SHA-256 콘텐츠 주소로 캐시하고, 모두 받은 뒤 한 번에 활성화해 중간 상태가 섞이지 않게 했다.
- 서버가 보내는 Bedrock JSON UI(HUD, 채팅, 폼)를 클라이언트가 해석해 그린다.
- 사용 기술
앱 안 Xbox 로그인과 Discord 활동 표시
- 동작 방식
- 로그인 화면의 Xbox 로그인 버튼을 누르면 Microsoft 계정 페이지가 외부 브라우저 없이 앱 안에서 열린다. 데스크톱은 네이티브 웹뷰, Android는 APK에 넣은 로그인 플러그인을 쓴다.
- 인증 코드 + PKCE(S256), 무작위 state, 콜백 주소 정확 일치를 지키고 Xbox 사용자 토큰과 XSTS를 검증한다. 런처는 비밀번호 입력 화면을 직접 만들지 않는다.
- Windows·macOS에서는 Discord 데스크톱 앱과 로컬 IPC로 직접 통신해, 라이브러리 없이 '런처 / 리소스 받는 중 / 플레이 중'과 레벨·직업·던전 정보를 Discord 활동에 띄운다. 설정에서 끌 수 있다.
- 사용 기술
세 플랫폼 배포
- 동작 방식
- Windows는 설치 경로·바로가기·제거 프로그램을 갖춘 설치 마법사로 배포하고, 필요한 WebView2 런타임 설치기를 함께 넣었다. 업그레이드하거나 지워도 설정·받은 리소스·로그인 정보는 사용자 폴더에 남는다.
- macOS는 Intel과 Apple Silicon을 함께 담은 유니버설 앱으로 만들고, DMG·PKG 설치 파일을 만든다. 패키징 전에 앱 서명과 실제 실행을 검사한다.
- Android는 arm64 APK로 빌드한다.
자동 검사와 에이전트용 편집기 API
- 동작 방식
- 리소스 → 접속 → 지형 → 폼 → 종료까지 이어지는 헤드리스 통합 검사를 돌리고, 같은 과정을 화면에 그려 스크린샷으로 남길 수 있다.
- 렌더링·메시·파티클·HUD 성능, 섹션 스트리밍, 폼 회귀, 그래픽 설정 등을 확인하는 검사 장면을 따로 두었다.
- 클라이언트 안의 UI 디자이너와 스토리 편집기는 AI 에이전트가 직접 조작할 수 있는 로컬 HTTP API를 연다. 127.0.0.1에서만 열리고, 편집기가 만든 토큰이 있어야 하며, 웹 페이지에서 온 요청은 거부한다.
TROUBLESHOOTING 기술적 문제 해결
접속 직후 엔티티가 늦게 보이고 메모리를 많이 쓰던 문제 해결
- 문제 상황
- 상태 응답이 한 프레임씩 늦게 적용되고 메모리를 많이 썼다. 접속 직후 다른 엔티티 모델이 몇 초 동안 보이지 않았다.
- 원인 분석
- 엔티티 모델 준비가 리소스 팩 색인 작업 뒤에 한 줄로 서 있었고, 그 색인이 접속한 뒤에야 시작됐다. 지형 데이터와 상태 처리에도 불필요한 복사와 할당이 많았다.
- 해결 과정
- 리소스를 준비하는 동안 엔티티 색인을 미리, 병렬로 만들어 두게 했다.
- 도착한 프레임에 바로 응답을 적용하고, 지형 배열과 섹션 인코딩 형식을 줄였다.
- 결과
- 개발 PC의 로컬 서버에 WebRTC로 접속해 같은 위치·입력으로 반복 측정한 결과다. 휴대폰에서는 따로 측정하지 않았다.
| 항목 | 개선 전 | 개선 후 |
|---|---|---|
| 접속 후 첫 엔티티 모델 표시 | 3.1 s | 중앙값 60~130 ms |
| 상태 왕복 RTT p50 (로컬 서버) | 12.3 ms | 6.0 ms |
| 클라이언트 관리 힙 (GC 후) | 643 MB | 191 MB |

다운로드
