Luminous Wanderlust
루미너스 : 원더러스트
Go로 직접 만든 Minecraft 서버 위의 반오픈월드 액션 RPG (구 Luminous RPG)
- 개발 중
- Minecraft Bedrock / Java 서버 + 전용 클라이언트
INFO 기본 정보
유물·장비·직업 특성을 조합해 나만의 전투 스타일을 만드는 반오픈월드 액션 RPG. Go 기반 서버 엔진 Dragonfly를 포크해 게임 서버와 전용 클라이언트, 게이트웨이까지 직접 개발하고 운영한다.
- 개발 기간
- 2020 ~ 현재
- 개발 상태
- 개발 중
- 플랫폼
- Minecraft Bedrock / Java 서버 + 전용 클라이언트
- 장르
- 액션 RPG, 반오픈월드, MMO 서버
- 사용 언어
- Go, C# (Godot 클라이언트), Java (Java Edition 게이트웨이), Python (개발 도구)
ABOUT 프로젝트 소개
소개
2020년에 시작한 장기 프로젝트로, 2023년 12월부터 Go로 작성된 Minecraft Bedrock 서버 엔진 Dragonfly를 포크해 게임 서버를 처음부터 다시 만들었다. 이전 이름은 Luminous RPG다.
구르기·발차기·패링과 연출이 붙은 궁극기로 싸우는 액션 전투에, 4개 계열의 직업, 유물·장비 성장, 스토리 퀘스트, 던전과 협동 던전, 생활 콘텐츠와 길드까지 갖춘 RPG를 서버 쪽 코드로 구현했다.
Bedrock 클라이언트뿐 아니라 직접 만든 전용 클라이언트(Windows·macOS·Android)와 Java Edition 접속 게이트웨이, Discord 안에서 보는 관전 모드까지 붙여 여러 경로로 같은 세계에 들어올 수 있다.
실제 플레이어가 접속하는 라이브 서버로 운영하고 있으며, 운영 공지(2026년 10월) 기준 공개 후 약 3개월 동안 누적 이용자는 약 800명이다.
지금의 Dragonfly 기반 서버는 게임 코드를 사실상 전부 직접 작성했고(게임 패키지 커밋 1,028개 중 1,025개), 2026년 6월부터는 AI 코딩 에이전트와 함께 작업하면서 에이전트용 검증 규칙을 따로 두고 개발하고 있다.
게임 플레이
- 4개 계열(전사·수호자·저격수·지원가) 아래 48개의 직업이 있고, NPC에게 배운 직업을 같은 계열 안에서 바꿀 수 있다. 직업 레벨 3·4·5에 특성 칸이 열린다.
- 무기 45종, 유물 51종, 방어구 12종을 조합한다. 장비 레벨 상한은 기본 45이고 세계를 하나 클리어할 때마다 15씩 오른다. 15레벨마다 돌파 효과 3개 중 하나를 고르고, 같은 장비를 넣어 초월한다.
- 숲 지대, 언덕 마을, 차가운 동굴 지역을 오가며 필드 전투, 던전, 극한 도전, 층을 오르는 '절망의 탑'을 진행한다. 2~4인 협동 던전도 있다.
- 낚시·농사·채광·벌목·요리 같은 생활 콘텐츠와 길드, 플레이어 거래소와 떠돌이 상인이 있다.
- 스스로 플레이하며 성장하고 기억하는 모험가 NPC와, 욕구에 따라 생활하며 심부름과 개인 이야기를 주는 마을 주민이 함께 살아간다.
개발 연혁
- Luminous RPG 프로젝트 시작
- Bedrock 서버 모딩 프레임워크 BDSX 오픈소스에 기능 기여 시작 (2022-03까지 PR 11건 병합)
- BDSX 기반 첫 서버 저장소 구성: 던전·퀘스트·길드·직업·낚시·상점·강화·스킬
- 스토리 시스템, 인챈트
- 던전 카운트다운, 스토리 시스템 개편, 몬스터 생성 비동기 처리
- 새 서버 저장소로 이전, 자동 백업·우편·스토리 데이터
- 상자 UI, 퀘스트·길드 개편
- 레이드 보스와 기간 한정 도전
- 유물·투사체 시스템, 벌목 채집
- 웹 관리 페이지, 서버 렉 개선
- 새 UI, 절망의 탑 첫 버전
- 메인 퀘스트와 스토리 음악, 밸런스 패치
- Go 서버 엔진 Dragonfly를 포크해 새로 개발 시작, 멀티 월드
- 프로토콜 업데이트 대응
- 스토리 시스템
- 직업 시스템
- 틱 처리 성능 개선, 1.21.100 엔진 병합
- 서버 성능 분석과 DB 개선
- AI 코딩 에이전트와 본격 협업 시작, 소환·거래소
- 월드 정지 감시(워치독), 절망의 탑
- Bedrock 1.26.40 프로토콜 업그레이드, 에이전트 작업 규칙
- Discord 관전 모드, Godot 전용 클라이언트와 게이트웨이
- 주민 NPC 에이전트, Java Edition 게이트웨이, 밸런스 시뮬레이터, 1.26.60 대응
- 협동 던전
TECH 기술 스택
설계 / 패턴
- 엔진/게임 분리: 포크한 Dragonfly 엔진 위에 약 90개 게임 패키지(전투·직업·아이템·던전·퀘스트·스토리·길드·거래소·주민 등)를 얹은 구조
- 전투: 입력을 이벤트 버스로 받아 아이템 스킬 훅을 실행하고, 하나의 공격 처리 경로에서 10단계 피해 계산을 거친다
- 데이터: 계정·프로필·길드·랭킹은 ent ORM으로 SQLite(WAL)에, 콘텐츠(던전 122·퀘스트 200·스토리 44)는 JSON 설정으로 분리
- 접속 경로: Bedrock 직접 접속, 전용 클라이언트 게이트웨이, Java Edition 게이트웨이가 모두 같은 서버 세션 경로로 들어온다
- 운영 안전장치: 라이브 서버에서는 에이전트가 재시작·접속 테스트를 하지 못하게 하는 규칙, 업스트림 병합 검증 절차
FEATURES 핵심 구현 기능
전투와 빌드 시스템
무기·유물·방어구·직업 특성을 조합하는 빌드와, 10단계로 계산되는 피해 공식.
- 동작 방식
- 플레이어 입력을 이벤트 버스로 받아 장착 아이템의 스킬 훅을 실행하고, 모든 피해는 하나의 공격 처리 경로를 지난다.
- 피해는 기본 피해 → 전체·속성 피해 보너스 → 속성 상성 → 피해 증가 → 치명타 → 방어(대상의 남은 체력 비율 반영) → 받는 피해 보정 → 속성 특수 효과 → 최종 증가 → 후처리 순서로 계산한다.
- 속성은 없음·빛·어둠·불·물·번개·대지 7종이고, 번개와 대지는 고유 규칙이 있다.
- 장비는 레벨, 인챈트(최대 6칸), 한계 돌파(I~V), 15레벨마다 고르는 돌파 효과, 같은 장비로 하는 초월로 성장한다. 계정 레벨(명성)은 기본 능력치를 올리지 않아 성장이 장비에 묶이게 했다.
- 사용 기술
퀘스트·스토리 저작 파이프라인
코드를 고치지 않고 JSON과 게임 안 도구로 퀘스트·스토리·던전·길 안내를 만든다.
- 동작 방식
- 퀘스트(메인·사이드·일일·주간·랭크·월드·도전)와 스토리, 던전을 JSON 설정으로 정의한다. 현재 던전 122개, 퀘스트 200개, 스토리 44개다.
- 스토리는 컷신 상태 머신이다. 스토리가 태그를 붙이면 퀘스트 단계가 진행되고, 그 단계가 NPC와 던전을 열고, 던전 클리어가 다음 스토리를 시작한다.
- 전용 클라이언트 안에서 동작하는 스토리 장면 편집기와 던전 편집기를 만들었다.
- 게임 안에서 '경로 막대'로 길 그래프를, '구역 막대'로 다각형 구역을 그린다. 퀘스트 목표까지 다익스트라로 경로를 찾아 플레이어별 화살표 입자로 안내한다.
- 사용 기술
주민·모험가 NPC 에이전트
사람과 같은 방식으로 접속해 스스로 플레이하고 배우는 NPC. LLM을 쓰지 않는다.
- 동작 방식
- NPC가 전용 클라이언트 게이트웨이를 통해 실제 플레이어 세션으로 접속해, 사람과 같은 관찰과 입력으로 움직인다.
- 직접 짠 행동 계획에 더해, 빌드 연구에는 UCB 기반 문맥 다중 슬롯 밴딧을 쓰고 아이템을 직접 써 보고 결과를 보며 아이템의 의미를 배운다.
- 감정·성격·용량이 정해진 기억(망각 포함)과 세대가 이어지는 '환생'이 있고, 형태소 사전과 활용·조사 규칙으로 고정 문장 없이 한국어 문장을 만든다.
- 마을 주민은 욕구에 따라 생활하며 심부름, 생활 사건, 소문, 선택지가 갈리는 4단계 개인 이야기를 준다.
- 사용 기술
- 고려 사항
- 설계 문서상 일부 기능은 단위 테스트까지만 확인했고 라이브 서버에서 관찰은 아직이다.
협동 던전과 콘텐츠
2~4인 협동 던전, 절망의 탑, 거래소 등 함께 즐기는 콘텐츠.
- 동작 방식
- 협동 던전은 교회·벌집·소굴·농장·절벽 5종의 절차 생성 맵과 로비, 공유 목숨, 제한 시간, 계열별 파티 버프, 협동 토큰 상점으로 구성했다.
- 보스는 파괴수, 엔더 군주, 슬라임 왕, 여왕벌, 거대 워든, 트렌트, 예티 등 커스텀 엔티티로 구현했다.
- 떠돌이 상인의 가격은 전체 거래 평균과 최근 평균을 30:70으로 섞어 정하고, NPC 판매는 가격 계산에서 빼서 가격이 스스로를 끌어올리지 않게 했다.
전용 클라이언트와 게이트웨이
Godot로 만든 전용 클라이언트가 서버에 내장된 게이트웨이로 접속한다.
- 동작 방식
- 전용 클라이언트는 Godot 4(.NET)로 Windows·macOS·Android용으로 만들었고, 서버의 Bedrock 리소스 팩을 직접 읽어 렌더링한다. 이전의 Electron 클라이언트를 대체했다.
- 서버에 내장한 게이트웨이가 WebRTC 또는 WebSocket으로 자체 프로토콜을 말하고, Xbox 로그인을 거쳐 일반 Dragonfly 세션 경로로 연결한다. Bedrock 패킷 형식은 이 연결로 오가지 않는다.
- Molang 의미 검사 하네스와 헤드리스 접속 테스트로 클라이언트를 검증한다.
- 사용 기술
Java Edition 접속 게이트웨이
수정하지 않은 Minecraft Java Edition 클라이언트로도 같은 서버에 접속한다.
- 동작 방식
- Go 서버가 MCProtocolLib 기반 JVM 프런트엔드를 띄우고 관리한다. ViaVersion으로 Java 1.21.6~26.3 클라이언트를 받는다.
- Microsoft/Xbox 계정을 연결해 Bedrock과 같은 저장 데이터를 쓴다.
- Bedrock 리소스를 버전별 Java 리소스 팩으로 변환하고, Bedrock 폼 UI는 대화창이나 상자 UI로 바꿔 보여 준다.
- 사용 기술
- 고려 사항
- Bedrock과의 기능 동등성은 아직 일부만 확인됐다.
Discord 관전 모드 (LUMINOUS LIVE)
Discord Activity 안에서 서버의 실제 세계를 실시간으로 보는 관전 모드.
- 동작 방식
- WebSocket 백엔드가 세계 영역을 스트리밍하고, 브라우저 렌더러가 서버의 실제 Bedrock 리소스 팩 구성을 읽어 그린다.
- 게임 서버에는 읽기 전용 접근자 세 개만 추가해 관전 기능이 게임 로직에 영향을 주지 않게 했다.
- 사용 기술
운영 자동화와 개발 도구
라이브 서버 운영과 대규모 개발을 받치는 도구들.
- 동작 방식
- 월드마다 심장 박동 트랜잭션을 보내 10초 안에 처리되지 않으면 정지로 보고, CPU·블록·뮤텍스 프로파일과 고루틴 스택을 자동으로 남긴다.
- 네트워크 세션 없이 실제 플레이어 객체를 조종하는 헤드리스 밸런스 시뮬레이터로 전투 밸런스를 확인한다.
- 장비·유물·직업 데이터를 Notion으로 단방향 동기화하고, 리소스 팩을 6개로 나눠 빌드하며, 실제 플레이를 녹화해 영상을 편집하는 도구와 신규 유저 이탈 분석 도구를 만들었다.
- 테스트 파일 111개(그중 110개 직접 작성)로 메모리 월드 위 통합 테스트를 돌린다.
- AI 코딩 에이전트를 위한 규칙을 문서로 두었다: 증거 없이 '고쳤다/검증했다'라고 쓰지 않기, 측정 수치는 조건과 함께 보고하기, 봇 결과를 사람 테스트로 내세우지 않기, 업스트림 병합 후 양쪽 부모 비교와 2인 접속 테스트.
- 반복 작업은 Claude Code 스킬로 만들었다: 실행 중인 서버에 콘솔 명령을 보내고 로그를 읽는 스킬, 실제 플레이를 녹화·편집해 장비 소개 영상(롱폼·숏폼·썸네일)을 만드는 스킬.
- 사용 기술
TROUBLESHOOTING 기술적 문제 해결
Bedrock 1.26.40 업그레이드 후 접속이 끊기는 문제 해결
- 문제 상황
- Bedrock 1.26.30(프로토콜 1001)에서 1.26.40(프로토콜 2168)으로 올린 뒤 클라이언트가 접속 중 끊겼고, 일부 문제는 두 번째 플레이어가 들어올 때만 나타났다.
- 원인 분석
- Dragonfly가 플레이어 목록 항목의 빌드 플랫폼 값을 채우지 않았는데, 1.26.40부터 클라이언트가 이를 거부했다. 플레이어 추가 패킷에도 같은 문제가 있어 2인 접속에서만 드러났다.
- 해결 과정
- 경쟁하던 업스트림 PR 두 개 중 하나를 골라 그 위에서 작업했다.
- Mojang의 프로토콜 스키마 문서와 패킷 추적·검증 도구로 패킷을 비교했다.
- 오래된 아이템 목록과 블록 팔레트도 고쳤지만 원인은 아니었고, 추측으로 넣었던 스킨 관련 수정 세 개는 되돌렸다.
- 세션의 플레이어 목록·추가 처리에 빌드 플랫폼 값을 넣어 해결하고, 빗나간 추측 네 가지를 회고 문서로 남겼다.
- 적용 기술
- 결과
- 1.26.40에 이어 1.26.45, 1.26.50, 1.26.60(프로토콜 2225)까지 버전을 따라 올렸다.
트랜잭션이 끝난 플레이어 객체로 인한 서버 패닉 해결
- 문제 상황
- 던전을 클리어할 때 퀘스트 점수를 올리는 과정에서 서버가 패닉으로 멈췄다.
- 원인 분석
- 월드 트랜잭션 안에서 얻은 플레이어 객체를, 그 트랜잭션이 끝난 뒤 클리어 처리에서 다시 썼다. 퀘스트 점수 API에 새로 넣은 월드 확인이 이 낡은 객체에 접근했다.
- 해결 과정
- 클리어와 보상 처리를 새 트랜잭션 안에서 다시 실행하도록 바꾸고, 접속이 끊긴 플레이어는 건너뛴다.
- 퀘스트 점수 API는 바뀌지 않는 엔티티 핸들로 플레이어를 찾아 단계마다 새 트랜잭션에서 실행하게 했다.
- 지연 실행되는 상태 이상 처리에도 같은 방식을 적용했다.
- 결과
- 트랜잭션이 끝난 뒤에 호출해도 안전한 API 계약을 지키면서 패닉이 사라졌다.
호위 NPC가 땅에 묻히고 점프가 초기화되는 문제 해결
- 문제 상황
- 호위 퀘스트의 NPC가 시작할 때 땅속에 묻히고, 점프가 계속 초기화되어 길을 따라오지 못했다.
- 원인 분석
- 틱마다 엔티티 래퍼가 새로 만들어지는데 점프 속도를 래퍼에 저장해서 매번 사라졌다.
- 해결 과정
- 속도를 엔티티 데이터 쪽으로 옮겼다.
- 발판 탐색을 위아래 3블록으로 제한하고, 수평은 길 그래프를 따르고 높이는 중력에 맡겼다.
- 3초 이상 막히면 몇 블록 앞으로 옮기고, 플레이어가 12블록 넘게 떨어지면 기다린다.
- 던전의 강제 경유 지점 대신 경로 30%·70% 지점에 조우 이벤트를 두었다.
- 결과
- 호위 NPC가 지면을 따라 길을 안정적으로 이동한다.
서버 정지와 DB 대기 병목 부분 해결
- 문제 상황
- 월드 처리가 막히면 서버가 통째로 종료되거나, 플레이어 저장이 줄줄이 밀렸다.
- 원인 분석
- 월드 처리가 10ms 넘게 막히면 프로세스를 강제 종료하는 코드가 있었고, 실행 시간 측정이 채널 전송 시간만 재고 있었다. SQLite 연결 하나에 동시 저장이 몰렸고, 사용자 조회가 동기식이었다.
- 해결 과정
- 성능 분석 보고서로 원인을 정리하고 SQLite를 WAL 모드로 바꿨다.
- 강제 종료를 없애고, 월드 정지를 감지하면 프로파일과 고루틴 스택을 자동으로 남기는 워치독을 만들었다.
- 결과
- 정지가 생겨도 서버가 죽지 않고, 원인을 추적할 자료가 자동으로 쌓인다.
- 남은 문제
- 워치독 보고서에 간헐적으로 긴 틱이 기록되어 계속 추적하고 있다.
전용 클라이언트의 지연과 메모리 해결
- 문제 상황
- 전용 클라이언트에서 상태 응답이 한 프레임씩 늦게 적용되고, 메모리를 많이 썼다. 접속 직후 다른 엔티티 모델이 몇 초 동안 보이지 않았다.
- 원인 분석
- 엔티티 모델 준비가 리소스 팩 색인 작업 뒤에 한 줄로 서 있었고, 그 색인이 접속한 뒤에야 시작됐다. 지형 데이터와 상태 처리에도 불필요한 복사와 할당이 많았다.
- 해결 과정
- 리소스를 준비하는 동안 엔티티 색인을 미리, 병렬로 만들어 두게 했다.
- 도착한 프레임에 바로 응답을 적용하고, 지형 배열과 섹션 인코딩 형식을 줄였다.
- 결과
- 개발 PC의 로컬 서버에 WebRTC로 접속해 같은 위치·입력으로 반복 측정한 결과다. 휴대폰에서는 따로 측정하지 않았다.
| 항목 | 개선 전 | 개선 후 |
|---|---|---|
| 접속 후 첫 엔티티 모델 표시 | 3.1 s | 중앙값 60~130 ms |
| 상태 왕복 RTT p50 (로컬 서버) | 12.3 ms | 6.0 ms |
| 클라이언트 관리 힙 (GC 후) | 643 MB | 191 MB |
| 서버 섹션 인코딩 | 3.98 ms | 1.29 ms |
| 섹션 데이터 크기 | 39.7 KB | 8.6 KB |

다운로드
소개 영상
기획 문서




