마인크래프트 서버 구축 및 플러그인 개발 실전 가이드

1.

개요 및 마이그레이션 파이프라인 마인크래프트 서버 구축 및 커스텀 개발 과정은 [개발 환경 조성] → [개발 도구 및 코드 작성] → [아키텍처 구성] → [실전 구동 및 운영]의 단계별 프로세스로 체계화된다.

본 보고서는 입문부터 상용 운영까지 직관적으로 실행할 수 있도록 단계별 흐름과 구체적인 가이드를 제공한다.

2.

[개발 환경] 런타임 및 IDE 구속 조건 개발 환경 구축은 실행 엔진(Java JDK)과 통합 개발 환경(IDE)을 설치하는 과정으로 시작된다.

Java JDK 설치 : 마인크래프트 최신 버전(1.20.5~1.21.x 및 최신 릴리스)을 구동하고 개발하기 위해서는 최소 Java 21 이상(최신 환경은 Java 25 권장)이 필요하다.

Windows 환경에서는 Amazon Corretto 21/25 패키지를 권장하며, 리눅스 환경에서는 GUI 및 폰트 라이브러리가 누락된 -headless 버전 대신 풀 패키지를 설치해야 한다.

IDE 및 필수 플러그인 : 개발 도구로는 IntelliJ IDEA Community 또는 Ultimate Edition을 사용한다.

IntelliJ 내부 마켓플레이스에서 Minecraft Development 플러그인을 설치하면 Paper 프로젝트 템플릿과 설정 파일( paper-plugin.yml ) 생성을 자동화할 수 있다.

3.

[개발 도구 & 코드 스택] 빌드 시스템 및 코드 작성법 개발 도구 및 언어 스택은 프로젝트의 빌드 라이프사이클과 실질적인 코드 구조를 결정한다.

빌드 시스템 및 의존성 관리 현대 마인크래프트 개발 생태계는 Gradle (Kotlin DSL: build.gradle.kts ) 체계를 표준으로 사용한다.

빌드 파일에는 서버 API 라이브러리와 컴파일 타겟 자바 버전이 명시된다.

작성되는 코드 컴포넌트 플러그인 작성 시 주력으로 개발하는 핵심 코드 요소는 세 가지로 구분된다.

메인 클래스(JavaPlugin) : 플러그인이 로드될 때 실행되는 초기화 로직( onEnable )과 종료 로직( onDisable )을 정의한다.

이벤트 리스너(Listener) : "플레이어가 서버에 접속했을 때", "블록을 파괴했을 때" 등 게임 내 사건을 감지하여 특정 로직을 수행한다.

명령어 실행기(CommandExecutor) : 플레이어가 채팅창에 /serverinfo 등의 명령어를 입력했을 때 처리할 동작을 지정한다.

Java package com.example.serverplugin; import org.bukkit.Bukkit; import org.bukkit.ChatColor; import org.bukkit.command.Command; import org.bukkit.command.CommandExecutor; import org.bukkit.command.CommandSender; import org.bukkit.entity.Player; import org.bukkit.event.EventHandler; import org.bukkit.event.Listener; import org.bukkit.event.player.PlayerJoinEvent; import org.bukkit.plugin.java.JavaPlugin; public final class CustomPaperPlugin extends JavaPlugin implements Listener, CommandExecutor { @Override public void onEnable() { getServer().getPluginManager().registerEvents(this, this); if (getCommand("serverinfo") != null) { getCommand("serverinfo").setExecutor(this); } getLogger().info("커스텀 플러그인이 활성화되었습니다."); } @Override public void onDisable() { getLogger().info("커스텀 플러그인이 비활성화되었습니다."); } @EventHandler public void onPlayerJoin(PlayerJoinEvent event) { Player player = event.getPlayer(); player.sendMessage(ChatColor.GREEN + "서버 접속을 환영합니다, " + player.getName() + "님!"); } @Override public void onCommand(CommandSender sender, Command command, String label, String[] args) { if (command.getName().equalsIgnoreCase("serverinfo")) { sender.sendMessage(ChatColor.GOLD + "=== 서버 상태 정보 ==="); sender.sendMessage(ChatColor.AQUA + "온라인 유저 수: " + Bukkit.getOnlinePlayers().size()); return true; } return false; } } 4.

[아키텍처] 서버 구조 설계 서버의 아키텍처는 운용 목적과 동시 접속자 수에 따라 2가지 형태로 설계된다.

구 분 단일 서버 아키텍처 (소규모/테스트) 분산 프록시 아키텍처 (대규모/상용) 핵심 구조 단일 Paper 서버 코어 독립 구동 Velocity(프록시) + 다중 Paper(월드 서버) 구조 특징 구조가 단순하며 인프라 비용 최소화 로비, 야생, 미니게임 등으로 트래픽 분산 데이터 관리 로컬 YML/JSON 파일 저장 중앙 데이터베이스 (MySQL / Redis) 연동 적용 권장 환경 지인 소수 플레이, 개별 플러그인 테스트 상용 서비스, 수십~수백 명 동시 접속 네트워크 5.

[실전 운영 플로우 1] 지인/네트워크 초대용 개발 및 운영 플로우 소규모 인원 초대를 목적으로 로컬 환경에서 테스트 및 운용을 진행하는 단계별 흐름이다.

로컬 서버 준비 : 폴더를 생성하고 Paper 공식 사이트에서 server.jar 다운로드.

실행 스크립트( run.bat ) 생성: java -Xms2G -Xmx2G -jar server.jar nogui 작성 후 실행.

eula.txt 의 eula=true 변경 후 서버 재구동.

플러그인 빌드 및 적용 : IntelliJ에서 개발한 코드를 Gradle Task( build )로 컴파일하여 .jar 파일 추출.

추출된 .jar 파일을 서버 폴더 내 plugins/ 경로에 배치 후 서버 재시작.

외부 네트워크 초대 : 방식 A (포트포워딩) : 공유기 설정에서 25565 포트를 개방하고 공인 IP를 전달.

방식 B (터널링 도구) : Playit.gg 등 터널링 프로그램을 실행하여 외부 접속 가상 주소를 즉시 발급받아 공유.

접속 테스트 : 개발자는 localhost 로 접속하고, 지인들은 발급받은 공인 IP 또는 터널링 주소로 접속.

6.

[실전 운영 플로우 2] 상용 및 대규모 서버 개발 및 운영 플로우 불특정 다수를 대상으로 안정적인 서비스 및 지속적인 기능 업데이트를 제공할 때 적용하는 플로우이다.

인프라 환경 구축 : 리눅스 기반 Cloud/VPS 서버 확보 및 보안 방화벽 설정.

25565 포트는 Velocity 프록시만 바인딩하고, 백엔드 Paper 서버들은 내보내지 않도록 가상 네트워크 구성.

CI/CD 및 빌드 자동화 : 코드 수정을 GitHub 레포지토리에 커밋하면 GitHub Actions를 통해 자동 빌드 및 검증 수행.

검증된 플러그인을 스테이징(테스트) 서버에 선적용 후 본 서버로 배포.

데이터 동기화 및 모니터링 : 플레이어 데이터(돈, 인벤토리, 레벨 등)를 외부 DB(MySQL/Redis)에 동기화하여 서버 간 이동 지원.

내장된 spark 프로파일러를 활용해 CPU, 메모리, 병목 틱(TPS) 현상을 지속적으로 모니터링 및 최적화.