neoforge.mods.toml 메타데이터 이해

모드를 NeoForge에 등록하려면 neoforge.mods.toml 파일이 반드시 있어야 합니다. 이 파일은 모드의 이름, 버전, 라이선스, 의존성 등 모든 메타데이터를 담고 있으며, NeoForge 로더가 게임 시작 시 가장 먼저 읽는 파일입니다.

파일 위치

템플릿 프로젝트에서 이 파일은 다음 경로에 있습니다:

examplemod-template-26.1.2/
└── src/
    └── main/
        └── templates/
            └── META-INF/
                └── neoforge.mods.toml   ← 여기

templates/ 폴더에 있는 이유가 있습니다. Gradle의 generateModMetadata 태스크가 빌드 시 이 파일을 읽어 ${mod_id}, ${mod_version} 같은 변수를 실제 값으로 치환한 뒤 src/main/resources/META-INF/에 복사합니다. 원본 파일을 직접 resources/META-INF/에 두면 변수 치환이 일어나지 않으니 주의하세요.

전체 파일 구조

# 최상위 필드
license="${mod_license}"
 
# 모드 블록
[[mods]]
modId="${mod_id}"
version="${mod_version}"
displayName="${mod_name}"
description='''
Example mod description.
'''
 
# 의존성 블록
[[dependencies.${mod_id}]]
    modId="neoforge"
    type="required"
    versionRange="[${neo_version},)"
    ordering="NONE"
    side="BOTH"
 
[[dependencies.${mod_id}]]
    modId="minecraft"
    type="required"
    versionRange="${minecraft_version_range}"
    ordering="NONE"
    side="BOTH"

필드 전체 정리

최상위 필드

참고: modLoader와 loaderVersion은 템플릿 파일에 주석 처리되어 있지만, NeoForge가 내부적으로 기본값을 적용합니다. 명시적으로 작성하면 의도를 더 명확히 할 수 있습니다.

[[mods]] 블록 필드

[[dependencies.<modId>]] 블록 필드

변수 치환 이해하기

${mod_id}, ${mod_version} 같은 표현은 gradle.properties에 정의된 값으로 치환됩니다.

gradle.properties:

mod_id=examplemod
mod_name=Example Mod
mod_version=1.0.0
mod_license=MIT
neo_version=26.1.2.64-beta
minecraft_version_range=[1.21.5,1.22)

neoforge.mods.toml (치환 전):

modId="${mod_id}"
version="${mod_version}"

빌드 후 src/main/resources/META-INF/neoforge.mods.toml (치환 후):

modId="examplemod"
version="1.0.0"

이 방식 덕분에 버전을 바꿀 때 gradle.properties 한 곳만 수정하면 됩니다.

modId 규칙

modId는 NeoForge 생태계에서 모드를 식별하는 유일한 키입니다. 규칙을 어기면 모드가 로드되지 않습니다.

허용: 소문자 영문자 a-z, 숫자 0-9, 밑줄 _

금지: 대문자, 공백, 하이픈, 특수문자

올바른 예:

modId="my_awesome_mod"
modId="neoforge_tutorial"
modId="examplemod"

잘못된 예:

modId="MyAwesomeMod"    # 대문자 금지
modId="my-mod"          # 하이픈 금지
modId="my mod"          # 공백 금지

⚠️ 잘못된 modId 사용 시 modId에 대문자/공백 사용 시 모드 로드 실패:

Caused by: net.neoforged.fml.ModLoadingException: invalid mod ID

반드시 lowercase a-z, 0-9, _ 만 사용

의존성 type 상세

versionRange 표기법

Maven 버전 범위 표기를 사용합니다:

[ ]는 포함(inclusive), ( )는 미포함(exclusive)입니다.

프로젝트 트리에서 파일 확인

전체 흐름 요약

gradle.properties          neoforge.mods.toml (templates/)
      │                              │
      │  ${mod_id} = examplemod      │
      └──────────────────────────────►
                                     │ generateModMetadata 태스크
                                     ▼
                    src/main/resources/META-INF/neoforge.mods.toml
                    (변수 치환 완료, JAR에 포함됨)
                                     │
                                     ▼
                    NeoForge 로더가 읽어 모드 등록

다음 단계

neoforge.mods.toml의 구조를 이해했으니, 다음 챕터에서는 실제 모드 진입점인 ExampleMod.java의 @Mod 어노테이션과 이벤트 버스 등록 방법을 살펴봅니다.

💡 Mods 메뉴에서 확인하기 모드를 빌드하고 runClient로 게임을 실행한 뒤 타이틀 화면의 Mods 버튼을 클릭하면 displayName, version, description, authors 필드가 실제로 표시되는 것을 확인할 수 있습니다. 인게임 캡처는 04-run-client 챕터를 참조하세요.