플러그인을 새 Minecraft 버전으로 업데이트하는 법

단계별 안내

1. 1.먼저 예전 .jar로 시도하기

   새 버전의 테스트 서버에 넣고 콘솔을 읽어 보세요. 로드되고 작동한다면 아무것도 바꿀 필요가 없을 수도 있어요.

2. 2.API 의존성 바꾸기

   pom.xml이나 build.gradle에서 paper-api 또는 spigot-api를 새 버전으로 설정하세요.

3. 3.api-version과 Java 업데이트하기

   plugin.yml의 api-version을 설정하고(예: '1.21') 새 버전에 필요한 Java로 컴파일하세요. 1.20.5 이전은 Java 17, 1.20.5부터는 Java 21, 26.x는 Java 25.

4. 4.더 이상 컴파일되지 않는 부분 고치기

   빌드하고 오류를 하나씩 살펴보세요. 이름이 바뀐 재료, 사라진 메서드, 바뀐 이벤트 클래스. 컴파일러가 파일과 줄 번호와 함께 알려 줘요.

5. 5.의존성 업데이트하기

   플러그인이 쓰는 플러그인(Vault, PlaceholderAPI, ProtocolLib, WorldGuard)도 빌드 파일과 서버 양쪽에서 새 Minecraft 버전을 지원하는 버전이어야 해요.

6. 6.새 버전에서 테스트하기

   같은 플러그인들이 있는 새 버전 서버에 불러오고, 시작만 보지 말고 모든 명령어와 기능을 써 보세요.

흔히 망가지는 부분

• 재료와 enum 이름: 1.13 업데이트에서 대부분의 아이템과 블록 이름이 바뀌었고, 이후 버전에서도 일부가 추가되거나 이름이 바뀌거나 사라져요. 예전 이름이나 숫자 ID를 쓰는 코드는 실패해요.
• 사용 중단된 메서드 제거: 여러 버전 동안 사용 중단(deprecated)으로 표시된 메서드는 결국 사라져요.
• 아이템 데이터: 1.20.5부터 아이템 NBT가 데이터 컴포넌트로 바뀌었어요. 아이템 NBT를 직접 수정하는 플러그인은 그 부분을 다시 작성해야 하고, 일반적인 ItemMeta API는 계속 작동해요.
• NMS와 리플렉션: 서버 내부 클래스를 쓰는 코드는 거의 모든 버전에서 망가져요. 가능하면 API로 바꾸거나 ProtocolLib 같은 라이브러리를 쓰세요.
• 라이브러리 버전: 예전 Java용으로 빌드된 셰이딩된 라이브러리는 새 Java에서 실패할 수 있어요.

여러 버전을 건너뛰어 업데이트하기

1.8이나 1.12에서 1.21로 가는 건 업데이트라기보다 아이템, 블록, 파티클을 다루는 부분을 다시 작성하는 것에 가까워요. 버전을 하나씩 거치지 말고 새 API에 맞춰 한 번에 하고, 설정 파일에도 새 재료 이름이 필요할 거라고 예상하세요.

플러그인이 여러 버전을 동시에 지원해야 한다면, 지원하는 가장 오래된 버전으로 컴파일하고 나중에 추가된 API는 피하거나, 버전마다 따로 빌드하세요.

Codexe로 하기

Pro 이상에서는 플러그인 소스를 ZIP으로 가져와서 예를 들어 "이건 내 Paper 1.20.4 플러그인이야. Paper 1.21.4로 업데이트해 줘"라고 요청할 수 있어요. Codexe는 빌드 파일에서 Minecraft 버전을 읽고, 그 버전에 필요한 Java로 빌드하고, 빌드 대상 API의 실제 시그니처를 써서 컴파일 오류를 고쳐요. Codexe에서 만든 플러그인이라면 프로젝트 채팅에서 새 버전을 요청하세요.

컴파일이 된다는 건 플러그인이 새 API로 빌드된다는 뜻이에요. 버전 간 동작 변화는 컴파일 오류로 드러나지 않으니, 그다음 테스트 서버에서 체험해 보세요.

질문