마인크래프트 플러그인 만들기 – 환경 세팅부터 배포까지 (IntelliJ + Paper API) | 마크빌드업 EP.05

IntelliJ + Gradle + Paper API로 플러그인 개발 준비를 해보자!

 

---

이런 분들께 추천합니다

• EP4에서 Paper 서버를 설치하고, 이제 직접 플러그인을 만들어보고 싶은 분
• IDE, 빌드 도구 등 개발 환경 세팅이 처음인 분
• 플러그인을 만들어서 내 서버에 올려보고 싶은 분

---

이 글에서 할 것

이 글에서는 코드를 본격적으로 작성하기 전에, 개발 환경을 세팅합니다.

1. IDE 설치 — 코드를 작성할 프로그램 (IntelliJ IDEA)
2. 로컬 Paper 서버 설치 — 내 PC에서 플러그인을 테스트할 서버
3. 프로젝트 생성 + 빌드 — Gradle로 프로젝트를 만들고 .jar 파일로 빌드
4. Hello World 배포 — 만든 플러그인을 로컬 서버 → GCP 서버에 올리기

이 과정을 한번 세팅해두면, 다음 글부터는 코드만 작성하면 "코드작성 ->빌드 → 테스트 → 배포" 과정으로 파이프 라인을 만들어 진행할 수 있습니다.

---

요약

문제	머릿속에 있는 기능을 내 서버에 넣고 싶다
시도	직접 플러그인을 만들어보자
해결	IDE + 로컬 서버 + 빌드 환경 세팅 → 배포까지 완료!

 

---

1. 개발에 필요한 것들

도구	역할	비용
Java JDK 21	Java 코드 컴파일	무료
IntelliJ IDEA	코드 작성 (IDE)	Community 무료
Gradle	프로젝트 빌드 + 의존성 관리	무료
Paper API	마인크래프트 서버와 상호작용하는 API	무료
로컬 Paper 서버	플러그인 테스트용	무료

 

처음 보는 단어가 많을 수 있으니 하나씩 정리합니다.

컴파일이란 사람이 작성한 코드를 컴퓨터가 이해할 수 있는 형태로 번역하는 것입니다.
우리가 작성하는 `.java` 파일은 사람이 읽기 편한 형태이고, 컴퓨터는 이걸 직접 실행할 수 없습니다.
컴파일러가 이 코드를 컴퓨터가 실행할 수 있는 형태로 변환해줍니다.

빌드란 컴파일 + 필요한 파일들을 묶어서 최종 결과물(.jar)을 만드는 전체 과정입니다.
플러그인을 서버에 넣으려면 `.jar` 파일이 필요한데, 빌드가 이걸 만들어줍니다.
컴파일이 "번역"이라면, 빌드는 "번역한 것들을 하나로 포장"하는 것입니다.

의존성 관리란 내 코드가 사용하는 외부 라이브러리를 자동으로 다운로드하고 연결해주는 것입니다.

(여기서 라이브러리는 다른 사람이 미리 만들어둔 코드 묶음입니다.)
우리 플러그인은 Paper API가 필요한데, 이걸 직접 사이트에서 다운로드해서 폴더에 넣고 경로를 설정하면 번거롭습니다.
Gradle 설정 파일에 "Paper API 써줘"라고 한 줄 적어두면, 알아서 다운로드하고 연결해줍니다.

IDE(통합 개발 환경) 란 코드 작성, 빌드, 디버깅을 한 곳에서 할 수 있는 프로그램입니다.
메모장으로도 코드를 쓸 수 있지만, IDE를 쓰면 자동 완성, 오류 표시, 프로젝트 관리 등이 지원되어 훨씬 편합니다.
이 글에서는 Java 개발에 가장 많이 쓰이고 Paper Team에서도 사용하는 IntelliJ IDEA를 사용합니다.

API(Application Programming Interface) 란 다른 프로그램의 기능을 정해진 방법으로 가져다 쓸 수 있게 해주는 것입니다.
어디서든 쓰이는 개념입니다:

상황	API (예시)	하는 일
웹 서비스	백엔드 API	"이 유저의 정보 줘" → 서버가 응답
데스크톱 앱	Electron API	"파일 열어줘" → 운영체제가 실행
앱 개발	카카오맵 API	"이 주소의 지도 보여줘" → 지도가 표시
마인크래프트 플러그인	Paper API	"플레이어를 텔레포트시켜줘" → 서버가 실행

공통점은 같습니다. 내가 직접 밑바닥부터 만들 필요 없이, 상대방이 정해둔 방법대로 요청하면 기능을 쓸 수 있다는 것입니다.
이 글에서 말하는 Paper API는, Paper 서버가 미리 만들어둔 기능들(텔레포트, 블록 변경, 채팅 등)을
우리 플러그인 코드에서 가져다 쓸 수 있게 해주는 것입니다.

1-1. JDK vs JRE

EP1에서는 JRE(Java Runtime Environment) 를 설치했습니다. JRE는 Java 프로그램을 실행하기 위한 환경입니다.

플러그인을 개발하려면 JDK(Java Development Kit) 가 필요합니다.

	JRE	JDK
역할	Java 프로그램 실행	Java 프로그램 개발 + 실행
포함 도구	실행 환경만	컴파일러, 디버거 등 개발 도구 포함
누가 쓰나	서버 운영자 (실행만 하면 됨)	개발자 (코드를 작성해야 함)

 

JDK 안에 JRE가 포함되어 있습니다. JDK를 설치하면 실행도 개발도 다 됩니다.

---

2. Java JDK 21 확인

EP1에서 JDK 21을 이미 설치했으므로, 확인만 하면 됩니다.

javac -version

javac 21.x.x이 뜨면 준비 완료입니다.

참고: JDK vs JRE

EP2에서 GCP 서버에는 openjdk-21-jre-headless(JRE)를 설치했습니다.
서버는 플러그인을 실행만 하면 되기 때문에 JRE로 충분합니다.

반면 내 PC에서는 코드를 컴파일해야 하므로 JDK가 필요합니다.
JDK 안에 JRE가 포함되어 있어서, JDK를 설치하면 실행도 개발도 다 됩니다.

	JRE	JDK
역할	Java 프로그램 실행	Java 프로그램 개발 + 실행
어디서 쓰나	GCP 서버 (실행만)	내 PC (개발)

---

3. IntelliJ IDEA 설치

3-1. 다운로드

JetBrains 공식 사이트에서 IntelliJ IDEA Community Edition을 다운로드합니다.

주소: https://www.jetbrains.com/idea/download/?section=windows

Community vs Ultimate:
Community (무료) — Java 개발에 충분. 플러그인 개발에 필요한 기능 모두 포함
Ultimate (유료) — 웹 개발, 프레임워크 지원 추가. 플러그인 개발에는 불필요

3-2. 설치

다운로드한 파일을 실행하고 설치합니다.

저 같은 경우 연결 생성을 체크하여 해당 확장자를 클릭했을 때 IDE가 바로 실행되게 진행했습니다.

 

---

4. 빌드 도구: Gradle

4-1. 빌드 도구란?

Java 코드를 작성하면 그걸 .jar 파일(플러그인)로 만들어야 합니다. 이 과정을 빌드라고 합니다.

파일이 몇 개 안 되면 수동으로 해도 되지만, 프로젝트가 커지면:

• 외부 라이브러리(Paper API 등)를 직접 다운로드하고 경로를 설정해야 하고
• 컴파일 명령어를 매번 직접 입력해야 하고
• 파일이 많아지면 순서도 신경 써야 합니다

빌드 도구는 이걸 자동으로 해줍니다. "어떤 라이브러리가 필요하고, 어떻게 빌드해라"를 설정 파일에 적어두면 명령어 하나로 끝납니다.

4-2. Gradle vs Maven

Java 빌드 도구는 크게 두 가지입니다.

	Gradle	Maven
설정 파일	build.gradle.kts (Kotlin)	pom.xml (XML)
문법	간결함	XML이라 장황함
빌드 속도	빠름	상대적으로 느림
플러그인 개발	최근 튜토리얼 대부분 Gradle	예전 튜토리얼에 많음

 

PaperMC 공식 문서에서도 Gradle을 사용합니다.
이 시리즈에서는 Gradle을 사용합니다.

4-3. Gradle은 따로 설치 안 해도 됩니다

IntelliJ에서 프로젝트를 만들면 Gradle Wrapper가 자동으로 포함됩니다.
./gradlew build 명령어를 치면 필요한 Gradle 버전을 알아서 다운로드하고 실행합니다.

---

5. 플러그인 프로젝트 생성

2026-02-24 수정: 5번의 방식은 프로젝트를 수동으로 설정하는 방법입니다. IntelliJ의 "Minecraft Development" 플러그인을 사용하신다면 더욱 편하게 프로젝트 세팅이 가능합니다!

글 맨 하단에 추가로 작성하였으니 5번 세션은 개념 이해용으로 보시고 글 하단의 "플러그인을 사용한 프로젝트를 세팅"을 보셔도 상관없습니다!

5-1. 새 프로젝트 만들기

IntelliJ를 실행하고 New Project를 클릭합니다.

항목	설정값
Name	my-first-plugin (원하는 이름)
Language	Java
Build System	Gradle
JDK	21
Gradle DSL	Kotlin

 

Gradle DSL이 Kotlin? — Gradle 설정 파일을 작성하는 문법이 Kotlin이라는 뜻입니다.
플러그인 코드 자체는 Java로 작성합니다!

5-2. build.gradle.kts 설정

프로젝트가 생성되면 build.gradle.kts 파일이 아래처럼 되어 있습니다.

plugins {
    id("java")
}

group = "org.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

dependencies {
    testImplementation(platform("org.junit:junit-bom:5.10.0"))
    testImplementation("org.junit.jupiter:junit-jupiter")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

tasks.test {
    useJUnitPlatform()
}

 

이걸 Paper 플러그인용으로 수정합니다. 아래 내용으로 전체를 교체합니다.

plugins {
    id("java")
}

group = "org.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
    maven {
        name = "papermc"
        url = uri("https://repo.papermc.io/repository/maven-public/")
    }  // Paper 저장소 추가
}

dependencies {
    compileOnly("io.papermc.paper:paper-api:1.21.11-R0.1-SNAPSHOT")  // Paper API 추가
}

java {
    toolchain.languageVersion.set(JavaLanguageVersion.of(21))  // Java 21 지정
}

 

 

뭘 바꿨나?

변경	이유
repositories에 Paper 저장소 추가	Paper API를 다운로드할 수 있는 곳을 알려줌
dependencies에 Paper API 추가	우리 코드에서 Paper API를 가져다 쓸 수 있게 함
java 툴체인 21 지정	Java 21로 컴파일
테스트 관련(JUnit) 삭제	플러그인 개발에 지금은 불필요

 

 

compileOnly는 빌드할 때만 Paper API를 참조하고,
실제 플러그인 .jar에는 포함하지 않는다는 뜻입니다.
Paper 서버가 이미 API를 가지고 있기 때문입니다.

5-3. plugin.yml 작성

src/main/resources/ 폴더에 plugin.yml 파일을 생성합니다.

name: MyFirstPlugin
version: 1.0.0
main: org.example.myfirstplugin.MyFirstPlugin
description: My first Minecraft plugin
author: 내이름
api-version: '1.21'

 

plugin.yml은 플러그인의 신분증 같은 파일입니다.
서버가 이 파일을 읽고 플러그인을 로드합니다.

필드	의미
name	플러그인 이름
version	플러그인 버전
main	메인 클래스 경로 (서버가 이 클래스를 찾아서 실행)
api-version	사용하는 Paper API 버전

5-4. 메인 클래스 작성

src/main/java/org/example/myfirstplugin/ 폴더에 MyFirstPlugin.java 파일을 생성합니다.

package org.example.myfirstplugin;

import net.kyori.adventure.text.Component;
import org.bukkit.Bukkit;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.plugin.java.JavaPlugin;

public class MyFirstPlugin extends JavaPlugin implements Listener {

    @Override
    public void onEnable() {
        Bukkit.getPluginManager().registerEvents(this, this);
        getLogger().info("MyFirstPlugin이 활성화되었습니다!");
    }

    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event) {
        event.getPlayer().sendMessage(
            Component.text("Hello, " + event.getPlayer().getName() + "!")
        );
    }
}

이것만으로도 플러그인이 동작합니다.
서버가 시작되면 onEnable()이, 서버가 꺼지면 onDisable()이 실행됩니다.

 

build.gradle.kts를 수정한 후에는 오른쪽 상단에 뜨는 코끼리 아이콘(Gradle 동기화) 을 클릭하세요.

이 버튼을 누르면 Gradle이 설정 파일을 다시 읽고, Paper API를 자동으로 다운로드합니다.
동기화 전에는 코드에 빨간색 오류가 뜰 수 있지만, 동기화가 끝나면 사라집니다.

---

6. 로컬 테스트 서버 준비 (윈도우)

플러그인을 GCP에 올리기 전에 내 PC에서 먼저 테스트합니다.
매번 GCP에 업로드하고 확인하면 너무 느리기 때문에, 로컬에서 빠르게 테스트하는 환경을 만듭니다.

사진을 첨부한 자세한 과정이 궁금하다면 EP1을 참고해 주세요!

6-1. 테스트용 폴더 만들기

원하는 위치에 테스트용 폴더를 만듭니다.

C:\minecraft-test-server\

6-2. Paper 서버 다운로드

PaperMC 다운로드 페이지에서 최신 버전의 Paper를 다운로드하고,
위 폴더에 paper.jar로 저장합니다.

6-3. 서버 실행 파일 만들기

C:\minecraft-test-server\ 폴더에 start.bat 파일을 만듭니다.

java -Xms3G -Xmx3G -jar paper.jar --nogui
pause

6-4. 첫 실행 + EULA 동의

start.bat를 더블클릭하면 eula.txt가 생성됩니다.
eula.txt를 열어 eula=false를 eula=true로 바꾸고 저장합니다.

다시 start.bat를 실행하면 서버가 시작되고, plugins/ 폴더가 자동으로 생성됩니다.

자세한 과정이 궁금하다면 EP1을 참고해 주세요!
EP1에서 바닐라 서버를 열었던 과정과 동일합니다. jar 파일만 paper.jar로 바뀐 것뿐입니다.

---

7. 빌드 & 테스트

7-1. 빌드

IntelliJ 터미널(좌측 하단 Terminal 탭)에서 빌드합니다.

./gradlew build

빌드가 성공하면 프로젝트의 build/libs/ 폴더에 my-first-plugin-1.0-SNAPSHOT.jar 파일이 생성됩니다.

7-2. 플러그인 복사 & 서버 실행

빌드된 .jar 파일을 로컬 Paper 서버의 plugins/ 폴더에 복사합니다.

build/libs/my-first-plugin-1.0-SNAPSHOT.jar
  → C:\minecraft-test-server\plugins\

start.bat로 서버를 실행합니다.

7-3. 확인

제가 코드에 텍스트가 뜨게 작성했기 때문에 서버 콘솔에 MyFirstPlugin이 활성화되었습니다!가 뜨면 성공입니다.

(제 사진에는 한글이 깨져보이네요)

마인크래프트에서 localhost로 접속한 뒤 /plugins 명령어로도 확인할 수 있습니다.

 

참고로 localhost는 127.0.0.1과 같은 뜻으로, 내 컴퓨터 자신을 가리키는 주소입니다.

이걸 루프백(Loopback) 주소라고 합니다 — 네트워크를 통하지 않고 내 컴퓨터 안에서 되돌아오는(loop back)
주소라는 뜻입니다.

내 PC에서 Paper 서버를 열고, 같은 PC의 마인크래프트에서 localhost로 접속하면 바로 들어갈 수 있습니다.

 

---

8. GCP 서버에 배포

로컬에서 테스트가 끝나면 GCP 서버에 배포합니다.

8-1. 플러그인 업로드

SSH 브라우저에서 UPLOAD FILE 버튼을 클릭하여 .jar 파일을 업로드합니다.

 

아래 명령어를 입력하여 업로드된 파일을 plugins 폴더로 이동합니다.

업로드 한 파일은 "home" 위치에 존재합니다.

mv ~/my-first-plugin-1.0-SNAPSHOT.jar ~/minecraft-server/plugins/

 

8-2. 서버 재시작

만약 서버를 가동중인 상황에서 서버를 재시작하면 플러그인이 로드됩니다.

stop

java -Xms3G -Xmx3G -jar paper.jar --nogui

GCP 서버에서도 MyFirstPlugin이 활성화되었습니다!가 뜨면 배포 완료입니다!

 

---

마무리

전체 흐름을 정리하면 다음과 같습니다:

1. JDK 21 설치 → 개발 도구 준비 (JRE가 아닌 JDK)
2. IntelliJ IDEA 설치 → 코드 작성 환경
3. Gradle + Paper API → 프로젝트 생성 + 의존성 설정
4. plugin.yml + 메인 클래스 → 플러그인 코드 작성
5. 윈도우 로컬 Paper 서버에서 테스트 → 빠르게 동작 확인
6. GCP 서버에 배포 → 실제 서버에 적용

일단 각 단계를 수행하면서 진행하면 되고, 프로세스 이해를 위해 빌드하면 자동으로 GCP 서버에 배포되는 프로세스는 서술하지 않았습니다.

 

이번 글은 Paper 공식문서를 참고하여 작성하였으니 궁금하시다면 링크로 들어가셔서 확인 가능합니다.

 

다음 글에서는 플러그인 개발에 필요한 주요 개념을 알아보고, 코딩을 몰라도 가능하게 AI 툴로 간단한 미니게임 플러그인을 만들어보겠습니다!

---

References

• PaperMC 개발 문서
• Paper API Javadoc
• IntelliJ IDEA 다운로드
• Gradle 공식 문서

---

추가 내용: 5-1. IntelliJ의 Minecraft Development Plugin으로 프로젝트 만들기

  위 5번 세션에서 build.gradle.kts, plugin.yml, 메인 클래스를 직접 만들었는데,
  Minecraft Development 플러그인을 쓰면 이 과정을 한번에 할 수 있습니다.

  1) 플러그인 설치

File → Settings (Ctrl + ,)로 설정 창을 엽니다.

 

Plugins → Marketplace 탭에서 minecraft을 검색하고,
Minecraft Development의 Install 버튼을 클릭합니다.

 

Third-Party Plugins Notice가 뜨면 Accept을 클릭합니다.

 

설치가 끝나면 Restart IDE를 클릭해서 IntelliJ를 재시작합니다.

 

  2) 프로젝트 생성

File → New → Project... 를 클릭합니다.

 

왼쪽에 Minecraft 항목이 생겼습니다. 선택하고 아래처럼 설정합니다.

번호	항목	설정값
1	Minecraft	왼쪽 목록에서 선택
2	Name	프로젝트 이름 (원하는 이름)
5	Groups	Plugin 선택
6	Templates	Paper 선택
7	Build System	Gradle 선택
8	Language	Java 선택
9	Minecraft Version	원하는 버전 선택 (예: 1.21.11)
12	Use Paper Manifest	체크 안 함 (아직 실험적 기능)
13	Build System Properties	Group ID와 Artifact ID는 본인 이름이나 닉네임으로!
14	JDK	21
15	Create	클릭!

  3) 생성 완료

메인 클래스, plugin.yml, build.gradle이 자동으로 생성됩니다.
위에서 직접 만든 것과 거의 같은 구조입니다.
이 과정이 끝나면 세션 5-4로 돌아셔서 쭉 진행하시면 됩니다!