Poly 모드 로더 — 개발자 및 기여자 가이드
Poly 모드 로더 엔진 개발에 참여하려는 분들을 위한 공식 가이드입니다. 소스코드 빌드, 테스트 실행, 디버깅 및 기여 절차를 안내합니다.
1. 사전 요구사항 및 환경 설정
필수 도구
- Java Development Kit (JDK) 25: Poly 모드 로더는 Java 25로 빌드되며 Java 25를 타겟팅합니다. 권장: Eclipse Temurin 25 또는 Microsoft Build of OpenJDK 25.
java -version # java version "25" 이상이어야 합니다.
- Git 2.40+
2. 코드 받기 및 빌드
# 저장소 복제
git clone https://github.com/xyrz47-spec/Poly-Mod-Loader.git
cd Poly-Mod-Loader
# 코드 서식 검사 및 전체 단위 테스트 실행
.\gradlew.bat check
# 독립 실행형 배포용 GUI 설치 프로그램(.jar) 빌드
.\gradlew.bat :poly-installer:installerDistributions
Minecraft 애셋 참고: 첫 빌드 시 Mojang 공식 서버로부터 필요한 마인크래프트 클라이언트/서버 JAR를 자동 다운로드하고 SHA-1 체크섬을 검증합니다. 이 파일들은
~/.gradle/caches/poly-minecraft에 로컬 캐시되며 저장소에는 커밋되지 않습니다.
3. 핵심 Gradle 태스크
| 태스크 | 대상 / 동작 | 비고 |
|---|---|---|
.\gradlew check | Spotless 코드 포맷 및 전 모듈 단위 테스트 검사. | PR 및 커밋 전 필수 실행. |
.\gradlew test | 전 서브모듈 인메모리 빠른 단위 테스트 실행. | 약 30초 내 완료. |
.\gradlew :poly-installer:installerDistributions | 크로스 플랫폼 GUI 설치 프로그램 컴파일. | poly-installer/build/libs/에 .jar 생성. |
.\gradlew serverBootSmokeTest | 헤드리스 환경에서 전용 서버 부팅 및 모드 로드 검증. | 전체 서버 라이프사이클 점검. |
.\gradlew worldCreateSaveTest | 신규 월드 생성, 시뮬레이션 틱, 레벨 저장 검증. | 월드 저장 시 데이터 무결성 입증. |
.\gradlew spotCheckPopularMods | 실세계 인기 Fabric, Forge, NeoForge 모드 매트릭스 검증. | 실제 JAR 대상 호환성 테스트. |
4. 멀티모듈 아키텍처 구조
코드베이스는 역할별로 명확히 분리된 모듈 구조를 따릅니다:
Poly-Mod-Loader/
├── poly-bootstrap/ # 부트스트랩 에이전트, CLI 파싱, JVM 런타임 패치 쉼
├── poly-mod-metadata/ # poly.mod.json, fabric.mod.json, mods.toml 파서
├── poly-runtime-api/ # 공개 라이프사이클 및 런타임 인터페이스
├── poly-runtime-impl/ # 모드 탐색, 클래스로더 조율, 사전 진단 엔진
├── poly-transform-api/ # 선언적 바이트코드 변환 SPI
├── poly-transform-engine/ # ASM 9.11 바이트코드 변환기 및 디스크 캐시
├── poly-bridge-api/ # 타 로더 브릿지 인터페이스
├── poly-bridge-fabric/ # Fabric Loader API 및 Quilt Loader 쉼, Mixin 브릿지
├── poly-bridge-forge/ # Forge 및 NeoForge FML 레이어 가상화
├── poly-game-api/ # 버전 독립적 게임 추상화 계층
├── poly-version-adapter-*/ # 마인크래프트 버전별 매핑 어댑터 (26.1, 26.2, 26.3)
├── poly-game-v*/ # 엔진 내부 게임 구현 훅 (26.1, 26.2, 26.3)
└── poly-installer/ # 크로스 플랫폼 Swing GUI 설치 프로그램
5. 코딩 표준 및 개발 원칙
- Java 25 표준: 레코드(Records), 패턴 매칭, 봉인된 클래스(Sealed classes) 등 모던 자바 표준을 적극 활용합니다.
- 바이트코드 안전성: 마이너 버전 간에도 바닐라 메서드 시그니처가 변경될 수 있으므로, ASM 변환 코드를 작성하기 전에 반드시
javap로 실제 바이트코드를 확인합니다. - 조기 차단(Fail-Fast) 원칙: 호환되지 않는 외부 모드 Mixin을 발견했을 때 게임 중간에 튕기지 않도록, 시작 전 단계에서 해당 모드를 격리하고 명확한
POLY-COMPAT-…진단 코드를 출력합니다.