마인크래프트/플러그인/개발

{{{#!wiki style="margin: -0px -10px -5px; min-height:calc(1.5em + 5px)" {{{#!folding [ 펼치기 · 접기 ] {{{#!wiki style="margin: -5px -1px -11px; word-break:keep-all"	<colbgcolor=darkgreen><colcolor=#fff> 기본 플레이
시스템	세계 (시드) · 게임 모드 · 난이도 · 게임 규칙 · 엔딩 · 죽음 메시지 · 스플래시 · 명령어 · NBT · 런처
인게임	아이템 · 몹 (플레이어) · 개체 · 날씨 · 차원 · 생물군계 · 구조물 · 마법 부여 · 상태 효과 · 조작법 · 피해 · 업적
도움말	튜토리얼 · 팁 (탐험 · 파밍 · 회로) · 재생 가능한 자원 · 브릿징 · PVP · 파쿠르 · 스피드런 · 건축 (맵아트)
시리즈 및 매체
출시 에디션	자바 에디션 (업데이트 · 거리 효과) · 베드락 에디션 (업데이트) · 포켓 에디션* · 콘솔 에디션* · 파이 에디션*
파생 게임	마인크래프트 던전스* · 마인크래프트 레전드* · 마인크래프트 에듀케이션 · 마인크래프트: 스토리 모드* · 마인크래프트 어스*
미디어	OST · 관련 서적 · 레고 · 영화 · 애니메이션 · Minecraft Live · Minecraft Now · Minecraft Monthly
유저 콘텐츠
창작 요소	2차 창작 · 망토 · 맵 · 모드 (개발 · 팁 · 모드팩) · 애드온 · 팩 (리소스 팩 · 데이터 팩) · 외부 프로그램 · 핵
멀티 콘텐츠	멀티플레이 · 서버 · 플러그인 · Realms · EULA
개발	개발 기초 · 모드 개발 · 플러그인 개발
기타
이야깃거리	여담 · 커뮤니티 · 사건 사고 · 문제점 · 용어 · 지원 언어 · 머나먼 땅 · 이미테이션 게임 · 히로빈
관련 문서	나무위키 마인크래프트 프로젝트 · 마인크래프트로 분류된 문서 · 마인크래프트의 하위 문서
* 표시는 서비스가 종료되었거나 개발이 중단되었다는 표시이다.		}}}}}}}}}

1. 개요

2. 편집 지침

3. 도입

3.1. 플러그인 이란?

3.2. 기초적인 지식

• 기본적인 마인크래프트 지식
• Java[2]와 객체 지향 프로그래밍에 대한 지식
• 영어 지식[3]
• 플러그인 API의 구조 이해 및 활용력

4. 준비

4.1. 통합 개발 환경(IDE) 설치

4.1.1. Eclipse

4.1.1.1. 구버전 Eclipse (Mars 버전 이전; 미설치형)

4.1.1.2. 신버전 Eclipse (Mars.1 버전 이후; 미설치형)

4.1.1.3. 신버전 Eclipse (Mars.1 버전 이후; 설치형)

4.1.2. IntelliJ IDEA

4.2. Java Development Kit (JDK) 설치

5. 첫 프로젝트 만들기( Eclipse )

5.1. Eclipse

5.1.1. Eclipse 실행

5.1.2. 작업공간 (Workspace) 설정

5.1.3. 프로젝트 만들기

5.2. Bukkit API 외부 라이브러리 다운로드

5.2.1. Gradle을 사용한 Paper API 다운로드

5.2.2. SpigotMC의 BuildTools를 이용한 다운로드

• BuildTools.jar: SpigotMC에서 제공하는 DMCA 우회 프로그램 BuildTools 다운로드(.exe)
• Java Development Kit 17: Java 코드 컴파일러 및 Jar 생성[7] JDK 17 다운로드
• Git: Git 및 Linux 환경 에뮬레이션 용도[8] Git 다운로드

1. BuildTools를 다운로드하여 폴더 경로에 띄어쓰기나 특수문자가 없는 폴더[9]에 저장 또는 옮긴다.
2. 해당 폴더로 이동하여 빈 공간에 커서를 옮기고 Shift + 우클릭을 이용해 팝업 메뉴를 소환합니다. 그리고 Git Bash Here를 클릭하여 Git Bash를 실행한다.
3. 콘솔에 java -jar BuildTools.jar --rev <원하는 마인크래프트 버전>를 입력하고 엔터를 누른다.[10]
4. 컴파일이 완료될 때까지 콘솔을 종료하지 말고 기다린다.
5. 빌드가 끝나면[11] target 폴더에 Spigot이 컴파일된 것을 확인할 수 있다.

5.3. Bukkit API 외부 라이브러리 적용하기

5.3.1. 패키지와 클래스 생성

5.3.2. 코드 작성

#!syntax java
package main;

import org.bukkit.Bukkit;
import org.bukkit.ChatColor;
import org.bukkit.plugin.java.JavaPlugin;

public class Main extends JavaPlugin{
	@Override
	public void onEnable(){
		Bukkit.getConsoleSender().sendMessage(ChatColor.BLUE + "플러그인이 활성화 되었습니다.");
	}
	
	@Override
	public void onDisable(){
		Bukkit.getConsoleSender().sendMessage(ChatColor.RED + "플러그인이 비활성화 되었습니다.");
	}
}

name: FirstMinecraftPlugin
version: 1.0
author: Devonnuri
description: My First Minecraft Plugin

main: main.Main

6. 첫 프로젝트 시작( intelliJ )

6.1. 프로젝트 시작

6.2. Gradle 버전 설정

6.3. build.gradle 세팅

plugins {
    // 이 플러그인 개발을 위해 필요한 프로그램들을 작성한다.
    // id ''형식으로 작성한다.
    
    id 'java'
}

group = 'org.tutorial' // 그룹명은 intellij를 사용해서 refactor기능을 사용하면 자동으로 변경되므로, 수동 수정은 비권장한다.
version = '1.0-SNAPSHOT' // 버전은 수동으로 바꿔주는게 좋다.

repositories {
    mavenCentral()
    maven {
        name = "papermc-repo"
        url = "https://repo.papermc.io/repository/maven-public/"
    }
    maven {
        name = "sonatype"
        url = "https://oss.sonatype.org/content/groups/public/"
    }
}

dependencies { 
    //참조할 라이브러리들을 작성한다. compileOnly ""형식으로 작성한다.

    compileOnly "io.papermc.paper:paper-api:1.21-R0.1-SNAPSHOT" 
}

def targetJavaVersion = 21 //자바 버전은 경우에 따라 다를 수 있다. 이 경우에는 1.21기준이라 Java 21을 사용하였다.
java {
    def javaVersion = JavaVersion.toVersion(targetJavaVersion)
    sourceCompatibility = javaVersion
    targetCompatibility = javaVersion
    if (JavaVersion.current() < javaVersion) {
        toolchain.languageVersion = JavaLanguageVersion.of(targetJavaVersion)
    }
}

tasks.withType(JavaCompile).configureEach {
    options.encoding = 'UTF-8' // 컴파일시 한국어 지원이 가능하도록 UTF-8 인코더를 지원한다.

    if (targetJavaVersion >= 10 || JavaVersion.current().isJava10Compatible()) {
        options.release.set(targetJavaVersion)
    }
}

processResources {
    def props = [version: version]
    inputs.properties props
    filteringCharset 'UTF-8'
    filesMatching('plugin.yml') {
        expand props
    }
}

7. 코드 작성에 관한 팁

• https://hub.spigotmc.org/javadocs/bukkit/에서 레퍼런스를 보실 수 있습니다. 레퍼런스를 볼 능력이 요구됩니다.
• Java나 객체 지향 프로그래밍을 잘 모르셔도 간단한 플러그인의 경우 그렇게 문제가 되지는 않습니다. 그러나, 미리 Java의 기본을 익히고 오는 것이 매우 강력히 권장됩니다.
• 이 문서에서 다루는 버킷 외에 Spigot에 대해 관심이 있다면 이 곳을 확인하세요.
• 이클립스는 단축키가 지원됩니다. 대표적으로 많이 쓰이는 단축키들입니다.
  

  Ctrl+Shift+F

  자동 정렬

  
  

  Ctrl+Space

  자동 완성

  
  

  Ctrl+Shift+O

  자동 import문 추가

8. 기본설정( 메인 클래스 , 콜백함수 설정)

#!syntax java
package org.tutorial.projectname; //패캐지의 이름이다. Intellij의 경우 refactor를 사용하면 자동으로 변경 가능하다

import org.bukkit.plugin.java.JavaPlugin;

public final class ProjectName extends JavaPlugin { //JavaPlugin 클래스를 상속받는다.

    
    @Override
    public void onEnable() { // 플러그인이 서버 실행 또는 reload를 통해서 서버에 등록되면 실행된다.

    }


    @Override
    public void onDisable() { // 플러그인이 서버가 닫히거나 reload를 통해서 서버가 정지되면 실행된다.

    }
}

8.1. onLoad()

#!syntax java
@Override
public void onLoad() {
    // 플러그인을 로드 하였을 때(활성화 이전) 발생하는 콜백 함수
    // 버킷을 실행하거나 /reload 명령어로 재시작하였을 때 발생합니다.
}

9. 다양한 기능에 관한 기본설정

9.1. 명령어 제작 및 실행

9.1.1. 명령어 실행부 작성( CommandExecutor, TabCompleter )

#!syntax java
package org.tutorial.projectname;

import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.command.TabCompleter;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.util.List;

public class PluginCommand implements CommandExecutor, TabCompleter {

    @Override
    public boolean onCommand(@NotNull CommandSender sender, org.bukkit.command.@NotNull Command command, @NotNull String label, @NotNull String[] args) { //커맨드의 실행을 담당할 부분
        return false;
    }

    @Override
    public @Nullable List<String> onTabComplete(@NotNull CommandSender sender, Command command, @NotNull String label, @NotNull String[] args) { //Tab키를 눌러서 명령어 자동 완성을 담당할 부분
        return null;
    }
}

9.1.2. 명령어를 플러그인에 등록

#!syntax java
getCommand("명령어 이름").setExecutor( new PluginCommand() ); //명령어를 실행할 Class를 정의한다. 이 경우에는 PluginCommand 클래스가 담당한다.
getCommand("명령어 이름").setTabCompleter( new PluginCommand() ); //명령어에서 자동완성 기능을 담당할 Class를 정의한다. 이 경우에는 PluginCommand 클래스가 담당한다.

#!syntax java
package org.tutorial.projectname;

import org.bukkit.plugin.java.JavaPlugin;

public final class ProjectName extends JavaPlugin {

    @SuppressWarnings("DataFlowIssue")
    @Override
    public void onEnable() {
        getCommand("command").setExecutor( new PluginCommand() );
        getCommand("command").setTabCompleter( new PluginCommand() );

    }

    @Override
    public void onDisable() {
        
    }
}

9.1.3. 플러그인 정보에 명령어 등록

name: ProjectName
version: '${version}'
main: org.tutorial.projectname.ProjectName
api-version: '1.21'
commands: 
  command:
    description: tutorial command
    aliases: [ "a" , "b" ]
    usage: tutorial command

10. 제목 표시하기

#!syntax java
public class 클래스명
{
    public void sendTitle(Player player, String title, int FadeInTime, int ShowTime, int FadeOutTime){
			CraftPlayer p = (CraftPlayer)player;
		    PlayerConnection c = p.getHandle().playerConnection;
		    IChatBaseComponent TitleText = ChatSerializer.a(title);
		    Packet<?> Length = new PacketPlayOutTitle(EnumTitleAction.TIMES, TitleText, FadeInTime*20, ShowTime*20, FadeOutTime*20);
		    Packet<?> TitlePacket = new PacketPlayOutTitle(EnumTitleAction.TITLE, TitleText, FadeInTime*20, ShowTime*20, FadeOutTime*20);
		    c.sendPacket(TitlePacket);
		    c.sendPacket(Length);
	}
}

#!syntax java
player.sendTitle ("제목 메시지", "부제목 메시지", 나타나는 시간, 화면에 머무는 시간, 사라지는 시간);
/*제목 메시지나 부제목 메시지를 없에려면 null을, 시간을 기본값으로 설정하려면 -1을 대입하면 됩니다. 시간 기본값은 왼쪽부터 10틱, 70틱, 20틱 입니다.*/

11. Bukkit API

11.1. org.bukkit.plugin.java.JavaPlugin

11.1.1. protected File getFile()

#!syntax java
    @Override
    protected File getFile()
    {
        return super.getFile();
    }

11.1.2. public ChunkGenerator getDefaultWorldGenerator(String worldName, String id)

#!syntax java
    @Override
    public ChunkGenerator getDefaultWorldGenerator(String worldName, String id)
    {
        return super.getDefaultWorldGenerator(worldName, id);
    }

11.1.3. public EbeanServer getDatabase()

#!syntax java
    @Override
    public EbeanServer getDatabase()
    {
        return super.getDatabase();
    }

11.1.4. public FileConfiguration getConfig()

#!syntax java
    @Override
    public FileConfiguration getConfig()
    {
        return super.getConfig();
    }

11.1.5. public InputStream getResource(String filename)

#!syntax java
    @Override
    public InputStream getResource(String filename)
    {
        return super.getResource(filename);
    }

11.1.6. protected void installDDL()

#!syntax java
    @Override
    protected void installDDL()
    {
        super.installDDL();
    }

11.1.7. protected void removeDDL()

#!syntax java
    @Override
    protected void removeDDL()
    {
        super.removeDDL();
    }

11.1.8. public PluginCommand getCommand(String name)

#!syntax java
    @Override
    public PluginCommand getCommand(String name)
    {
        return super.getCommand(name);
    }

11.1.9. public List<String> onTabComplete(CommandSender sender, Command command, String alias, String[] args)

#!syntax java
    @Override
    public List<String> onTabComplete(CommandSender sender, Command command, String alias, String[] args)
    {
        return super.onTabComplete(sender, command, alias, args);
    }

#!syntax java
    @Override
    public List<String> onTabComplete( CommandSender sender, Command command, String label, String[] args) {
        if ( args.length == 1) {
            List<String> list = new ArrayList<>( (int) list의 크기);
            list.add( string source );
            list.add( string source );
            list.add( string source );
            .
            .
            .
            return list;
        }
        else if ( args.length == 2) {
            양식은 비슷함
        }
        .
        .
        .
        else if ( args.length == n[ 자신이 원하는 수 ]){

        }
        return null;
    }

11.1.10. public void reloadConfig()

#!syntax java
    @Override
    public void reloadConfig()
    {
        super.reloadConfig();
    }

11.1.11. public void saveConfig()

#!syntax java
    @Override
    public void saveConfig()
    {
        super.saveConfig();
    }

11.1.12. public void saveDefaultConfig()

#!syntax java
    @Override
    public void saveDefaultConfig()
    {
        super.saveDefaultConfig();
    }

11.1.13. public void saveResource(String resourcePath, boolean replace)

#!syntax java
    @Override
    public void saveResource(String resourcePath, boolean replace)
    {
        super.saveResource(resourcePath, replace);
    }

11.1.14. public List<Class<?>> getDatabaseClasses()

#!syntax java
    @Override
    public List<Class<?>> getDatabaseClasses()
    {
        return super.getDatabaseClasses();
    }

11.1.15. org.bukkit.entity

11.1.15.1. Player 인터페이스

11.1.15.1.1. setPlayerListName

• IllegalArgumentException - 이름이 너무 길거나[15] 누군가가 이미 쓰고 있는 이름인 경우

11.1.15.2. HumanEntity 인터페이스

11.2. org.bukkit.event

12. Craftbukkit 구현부 레퍼런스

12.1. net.minecraft.network.protocol.game

12.1.1. Clientbound 패킷 사용법

#!syntax java
    Clientbound<패킷이름>Packet packet =  new Clientbound<패킷이름>Packet(<...>);

#!syntax java
    ServerPlayer nmsPlayer = ((CraftPlayer) player).getHandle();
    ServerGamePacketListenerImpl connection = nmsPlayer.connection;

#!syntax java
    connection.send(packet);