Hytale 모딩 API: 완전한 서버 플러그인 개발 가이드

Hytale's 서버 플러그인 시스템은 개발자가 게임의 모든 측면에 깊은 컨트롤을 제공합니다. Minecraft에 대한 Bukkit 또는 Spigot 플러그인을 작성한 경우, 이 전환은 곧 시작됩니다. 그러나 Hytale의 아키텍처는 근본적으로 다릅니다. 이 가이드는 초기 설정에서 생산 배포까지 모든 것을 통해 걸어 갑니다. 건축 개요 Before 모든 코드를 작성, Hytale의 modding 작동 방식 이해: 클라이언트는 렌더링입니다. Hytale의 C# 클라이언트는 도표, 입력 및 오디오를 취급합니다 — 그러나 게임 논리를 포함합니다. 모든 시뮬레이션은 단일 플레이어에서 Java 서버에서 실행됩니다. 모든 서버 측입니다. 플레이어가 modded 서버, 사용자 정의 자산 및 행동 스트림을 자동으로 결합 할 때. 클라이언트 모드가 필요하지 않습니다. Four modding 카테고리가 존재합니다: Data Assets (JSON), Art Assets (Blockbench model), Server Plugins (Java) 및 Visual Scripting (곧 진행). Server 플러그인은 가장 강력한 범주입니다. Entity Component System, 이벤트 파이프라인, 명령 프레임 워크 및 세계 조작을 포함한 서버 실행 시간에 완전한 Java 액세스를 제공합니다. 개발 환경 설정 필수 ToolVersion주 Java25+ Hytale는 가상 스레드 (Project Loom)를 포함한 현대적인 기능을 사용합니다. IntelliJ IDEACommunity 또는 Ultimate추천 IDE - 무료 커뮤니티 에디션은 잘 작동 Gradle9.2.0+Build system ( 플러그인 템플릿 포함) 기타 최근 버전 공식 템플릿을 복제하려면 공식 템플릿 Hypixel Studios는 GitHub에서 공식 플러그인 템플릿을 제공합니다: git 복제 https://github.com/HytaleModding/plugin-template.git 나의FirstPlugin cd MyFirstPlugin IntelliJ IDEA에서 프로젝트를 열고 Gradle sync를 해보자. 템플릿에는 올바른 디렉토리 구조, 구성 및 서버 API 의존성을 포함합니다. Alternatively, HytaleIO 프로젝트 생성기에서 hytaleio.com/project-generator는 웹 UI를 가진 Plugin, Mod 또는 Full (combo) 프로젝트 비계를 만들 수 있습니다. 펄진 구조 모든 Hytale 플러그인은 이 디렉토리 레이아웃을 따릅니다: 당신의 플러그인/ ├─ src/main/java/com/yourname/yourplugin/ │ ―――――――― java # 주요 항목 점 ├─ღ♥ღ │ ├──표시. json # 플러그인 메타데이터 (필수) │ ├─ Common/ # 공유 자산 (모델, 질감) │ └─ 서버/ # 서버 측 데이터 자산 ├── build.gradle.kts ღ♥ღ ├─ 설정.gradle.kts └─ gradle.properties manifest.json 모든 플러그인은 컴파일된 JAR의 루트에서 manifest.json를 요구합니다. 이것은 Bukkit의 plugin.yml:와 동일합니다. 이름 * "그룹": "com.yourname", "이름": "YourPluginName", "주요": "com.yourname.yourplugin.YourPlugin", "버전": "1.0.0", "Description": "당신의 플러그인은 무엇입니까", "Authors": [{"이름": "YourName"}], "ServerVersion": "*", "Dependencies": {}, "OptionalDependencies": {}, "LoadBefore": [], "DisabledByDefault": false, "IncludesAssetPack": 거짓 자주 묻는 질문 플러그인 식별자는 로 형성됩니다. 그룹:이름 (예: com.yourname:YourPluginName). 주요 입력 클래스에 필드 포인트 -이 잘못하고 플러그인이로드되지 않습니다. 펄진 수명주기 Your main class는 JavaPlugin를 확장하고 4개의 Lifecycle 단계가 있습니다: 공유 클래스 플러그인 확장 Java 플러그인 이름 * 공개 YourPlugin(@Nonnull JavaPluginInit init) { 슈퍼 (init); getLogger().info("Plugin 건설!"); 이름 * @Override의 장점 public void 설정() 이름 * // 2단계: 이벤트, 명령, ECS 시스템 등록 // 이것은 대부분의 등록 코드가 간다. 이름 * @Override의 장점 공개 void 시작() 이름 * // 단계 3: 서버는 선수를 위해 준비되어 있습니다 // 계획된 작업을 시작, 연결 열기 이름 * @Override의 장점 공중 void 폐쇄 () 이름 * // 단계 4: 서버 종료 전에 정리 // 데이터 저장, 연결 닫기, 작업 취소 이름 * 자주 묻는 질문 상상 여기해야 할 일 1. 건설건설 기본 초기화, 로깅 2. 설정setup() 이벤트 등록, 명령, ECS 구성 요소 및 시스템 3. 시작start() 작업을 시작, 서버는 플레이어를 수락 4. Shutdownshutdown() 데이터 저장, 정리 리소스 듀얼 이벤트 시스템 이것은 이해하는 가장 중요한 개념입니다. Hytale는 두 개의 별도의 이벤트 시스템을 가지고 있으며 잘못된 것을 사용하는 것은 일반적인 실수입니다. 행사 버스 — 글로벌 서버 이벤트 The EventBus는 플레이어 연결, 채팅 및 세계 로딩과 같은 서버 전체 이벤트를 처리합니다. 플러그인으로 제공되는 EventRegistry를 통해 핸들러 등록: @ 더 보기 public void 설정() 이름 * // 동시 글로벌 이벤트 getEventRegistry().register글로벌() PlayerReadyEvent.class는, 이벤트 -> { getLogger().info("플레이어에 가입: " + event.getPlayer().getUsername()); 이름 * · // Async 이벤트 ( PlayerChatEvent와 같은) getEventRegistry().registerAsyncGlobal(()를 호출합니다. PlayerChatEvent.class는, 미래 -> 현재 위치 다음을 제외하고 (event -> { if (event.getMessage().contains("spam")) 이름 * event.setCancelled (true); 이름 * 으로 이름 * · 자주 묻는 질문 키 이벤트 버스 이벤트: PlayerConnectEvent / PlayerDisconnectEvent — 연결 수명주기 PlayerReadyEvent에 대하여 - 플레이어 완전 부하 및 준비 PlayerChatEvent - 채팅 메시지 (Async, cancellable) AddPlayerToWorldEvent - 세계를 입력하는 플레이어 StartWorldEvent / AddWorldEvent / RemoveWorld 이벤트 — 세계 경영 이벤트 우선 순위: EventPriority를 사용하십시오. EARLY 처음 실행하고 다른 핸들러 전에 이벤트를 수정합니다. EventPriority를 사용하십시오. LATE 다른 모든 핸들러가 처리 한 후 최종 상태를 볼 수 있습니다. ECS는 이벤트 — Entity-Specific 액션 Entity-level event like block break, block place, damage are handled through the Entity Component System, not the EventBus. 를 만듭니다. EntityEventSystem: 공동 클래스 BlockBreakHandler EntityEventSystem< 확장;EntityStore, BreakBlock 이벤트> { @Override의 장점 공개 Query getQuery() 이름 * // 특정 컴포넌트를 가진 Target entities 반환 Query.builder().build(); 이름 * @Override의 장점 공개 Class getEventType() 이름 * 계정 만들기 BreakBlockEvent.class; 이름 * @Override의 장점 공 void 손잡이 (EntityStore 상점, CommandBuffer 버퍼, 회사 소개 이벤트) { // 블록 브레이크 // 필터 단계에서 취소, 여기에 이름 * 자주 묻는 질문 문법 규칙: filter 단계 동안 ECS 이벤트를 취소합니다. 검사 단계의 취소는 이미 일어났기 때문에 효과가 없습니다. Entity 구성 요소 시스템 (ECS) Hytale는 사용자 정의 ECS 아키텍처를 사용합니다. 이 이해는 비 트리 바이알 플러그인에 필수적입니다. 핵심 개념 Entity — 유일한 ID는, 자료 자체를 포함합니다 Component - 엔티티티티에 첨부된 순수한 데이터 컨테이너 시스템 — 특정 구성 요소 조합을 처리하는 논리 Ref - 엔티티티티에 안전한 핸들 (직체 참조) Store - 효율적인 메모리 레이아웃에 대한 Archetypes을 사용하여 엔티티티티를 관리 사용자 정의 구성 요소 공석 점수 데이터 구현 컴포넌트 { 공개 int 점수 = 0; public String 팀 = "; 긴 가입 = 시스템.currentTimeMillis(); @Override의 장점 공개 점수데이터 복제() 이름 * ScoreData 복사 = 새로운 ScoreData(); 복사.score = this.score; 이름 * 팀 = this.team; 이름 * 이름 * = 이.joined 에; 반환 사본; 이름 * 자주 묻는 질문 Components는 clone()를 구현해야 합니다. 사용자 정의 데이터를 저장하는 데 필요한 첨부 - 점수, 팀, 멋진 다운, 재고, 또는 모든 게임 별 상태. 저장 PlayerRef A "Player" in Hytale는 특별한 클래스가 아닙니다. - 그것은 구성 요소입니다. PlayerRef는 실제로 플레이어의 사용자 이름, UUID, 언어 및 네트워크 핸들러를 저장하는 구성 요소입니다. 플레이어가 연결되기 때문에 활성화됩니다. Command 등록 Commands는 Command 인터페이스를 구현합니다: 공동 클래스 스파드 명령을 실행 { @Override의 장점 public String getName() { return "spawn"; } @Override의 장점 public void 실행(CommandSender sender, String[] args) { if (sender 인스턴스 플레이어 플레이어) { // 텔레포트 플레이어 sender.sendMessage("스파이팅 ..."); 이름 * 이름 * 이름 * // 설정 등록() commandRegistry.registerCommand(새로운 SpawnCommand()); Both Player 과 CommandSender 지원 hasPermission() 체크. 내장 권한 시스템은 사용자 수준의 권한, 그룹 상속, 와일드 카드 매칭을 지원합니다. 건축 및 배포 건축 ./gradlew build 출력 JAR는 build/libs/로 이동합니다. 직업 경로 플랫폼 모드 디렉토리 Windows (local)%AppData%/Roaming/Hytale/UserData/Mods/ Linux 서버/opt/hytale/Server/mods/ Hot reloading 은 부분적으로 마이너 변경을 위해 지원됩니다. Intelli의 Ctrl+F9 을 사용하십시오. J는 전체 재시작없이 재건축합니다. 주요 변경은 서버 재시작이 필요합니다. EventRegistry는 플러그인 언로드시 핸들러를 자동으로 청소합니다. CurseForge에 게시 CurseForge는 세 가지 모드 유형을 인식합니다. Packs - 자산/내용 팩 (JSON 데이터, 모델, 질감) Plugins - 서버 API를 사용하여 Java JAR 파일 Early Plugins - 낮은 수준의 클래스 변환을위한 부츠 스트랩 플러그인 (advanced, sparingly 사용) 지역 자원 modding 커뮤니티는 Hypixel Studios가 제공하는 것을 넘어 광범위한 문서를 구축했습니다. 출처Focus HytaleModding.dev 가이드, 문서, 도구 — 8,000+ Discord 회원 Britakee Studios GitBook팩 및 플러그인에 대한 효과적인 테스트 자습서 HytaleDocs.comCommunity wiki 및 API 참조 Hytale-Toolkit (GitHub)Decompiled source, javadocs, semantic code search 패치러 (GitHub) 서버 검색 JAR 으로 IntelliJ 프로젝트 주: 서버 JAR는 손상되지 않으며 자유롭게 decompiled 할 수 없습니다. Hypixel Studios는 EA 발사의 1~2개월 이내에 전체 서버 소스 코드를 해제하기 위해 최선을 다하고 있습니다. What's Coming Server 소스 코드 릴리스 — 3월 2026 Visual Scripting — non-programmers (similar to Unreal Blueprints)에 대한 노드 기반 스크립트 Development bounties - Hypixel Studios 커뮤니티 기여에 대한 현상을 제공 할 계획 공식 문서 확장 - 불완전으로 인정, 커뮤니티 피드백을 기반으로 확장 플러그인을 배포하려면? HytaleCharts에 modded server를 목록으로 만들 수 있습니다. Minigame-specific 개발 패턴을 보려면 를 확인하십시오. 사용자 정의 미니 게임 가이드.