네오포지(NeoForge) 및 포지(Forge) 오픈소스 서버 개발 입문 가이드

 

 

서론

네오포지와 포지는 마인크래프트 모드 개발의 핵심 프레임워크로, 2023년 분리 이후 기술적 차이가 확대되었습니다. 초보 개발자가 이 생태계에 진입하기 위해 필요한 핵심 지식을 체계적으로 정리합니다.

---

1. 개발 환경 구성 필수 요소

1.1 JDK 설치 및 버전 관리

• Java 21(LTS) 필수: 네오포지 1.21.1 이상 버전 개발 시 반드시 필요3.
  • Adoptium Temurin 설치 권장(공식 문서 호환성 검증 완료).
• 환경 변수 설정: JAVA_HOME 경로 지정 및 Path에 %JAVA_HOME%\bin 추가6.

1.2 IDE 선택 및 설정

• IntelliJ IDEA Community Edition 최적화:
  • Gradle 통합 지원, Mixin 디버깅 기능 내장.
  • Minecraft Development 플러그인 설치 필수(모드 템플릿 생성 기능).
• VS Code 대안: Java Extension Pack + Gradle for Java 확장 프로그램 조합.

1.3 프로젝트 초기화

• MDK(Mod Development Kit) 템플릿 사용:
  • 네오포지: GitHub NeoForgeMDKs/MDK-1.21-ModDevGradle.
  • 포지: 공식 사이트에서 버전별 MDK 다운로드.
• Gradle 워크플로우:
  

  ./gradlew genIntellijRuns  # IDE 실행 구성 생성
  ./gradlew build            # JAR 파일 빌드[26][29]

---

2. 프로젝트 구조 이해

2.1 핵심 디렉토리 구성

src/
├── main/
│   ├── java/        # 모드 소스 코드
│   └── resources/   # JSON 설정, 텍스처, 언어 파일
build.gradle         # 빌드 스크립트
gradle.properties    # 모드 메타데이터 설정[3][5]

 

 2.2 필수 설정 파일

• mods.toml: 모드 ID, 버전, 저작자 정보 정의
  

  modId="examplemod"
  version="${file.jarVersion}"
  displayName="Example Mod"
  authors="Developer"

  
  
• mixins.json: 코드 인젝션 설정
  

  {
    "required": true,
    "package": "com.example.mixin",
    "compatibilityLevel": "JAVA_17"
  }

  
  

---

3. 네오포지 vs 포지 핵심 차이점

3.1 아키텍처 비교

기능	네오포지	포지
이벤트 처리	비동기 스레드 풀 사용1	단일 스레드 이벤트 버스
레지스트리 시스템	DeferredRegister 강제 사용7	RegistryEvent 기반
믹스인 지원	MixinExtras 내장1	외부 라이브러리 의존
모듈화	기능별 서브모듈 분리 가능3	단일 모듈 구조 유지

 

3.2 API 사용 패턴

• 아이템 등록 예시:

  // 네오포지 방식
  public static final DeferredRegister.Items ITEMS = 
      DeferredRegister.createItems(MOD_ID);
  public static final RegistryObject<Item> EXAMPLE_ITEM = 
      ITEMS.register("example_item", () -> new Item(new Properties()));
  
  // 포지 레거시 방식
  @SubscribeEvent
  public static void registerItems(RegistryEvent.Register<Item> event) {
      event.getRegistry().register(new Item().setRegistryName("example_item"));
  }

---

4. 개발 시 주의사항

4.1 일반적 실수 방지

1. 모드 충돌:
   • @Mod 어노테이션의 고유 ID 검증 필수.
   • resources/META-INF/services 폴더 내 중복 클래스 제거.
2. 버전 호환성:
   • gradle.properties에서 minecraft_version 일치 확인.
3. 리소스 누락:
   • assets/<modid>/textures 경로에 16x16 PNG 파일 필수.

4.2 디버깅 기법

• 런타임 디버거 연결:

  ./gradlew runClient --debug-jvm  # 5005 포트 리스닝

• 크래시 로그 분석:
  • logs/latest.log에서 Caused by: 체인 추적.
  • Mixin 실패 시 mixin.out 파일 생성 여부 확인.

---

5. 커뮤니티 리소스 활용

5.1 학습 자료

• 공식 문서:
  • 네오포지: NeoForged Documentation
  • 포지: Forge Docs

---

6. 배포 및 유지보수 전략

6.1 JAR 패키징

• 최적화 빌드:
  

  jar {
      manifest {
          attributes([
              "Specification-Title": "examplemod",
              "Implementation-Version": project.jar.archiveVersion
          ])
      }
      exclude("**/*.bat")
  }

• 사이즈 축소: ProGuard 사용 시 -dontwarn 설정 필수.

 

6.2 배포 플랫폼

플랫폼	장점	단점
CurseForge	광범위한 유저 기반	승인 프로세스 장기화
Modrinth	오픈소스 친화적	상대적 저명성
GitHub	CI/CD 연동 용이	엔드유저 접근성 낮음

 

---

결론

네오포지와 포지 개발은 각각의 철학과 기술 스택을 이해하는 것이 중요합니다. 신규 개발자는 네오포지의 현대화된 API를 우선 학습하며, 레거시 프로젝트 유지보수 시 포지의 특수성을 고려해야 합니다. 커뮤니티 기여를 통해 지속적인 기술 습득이 가능하며, 모드 배포 시 라이선스(GPL-3.0/MIT) 준수가 필수적입니다.