용어집
Poly 모드 로더 문서에 자주 나오는 용어를 모았습니다. 가나다순이며, 영어 이름인 용어는 읽는 소리로 정렬했습니다(예: Native는 "네이티브"). 각 용어를 자세히 설명하는 페이지를 함께 적었습니다.
| 용어 | 뜻 | 자세히 |
|---|---|---|
| 게임 계층 | 버전별 모듈 poly-game-v<id>입니다. 다운로드한 Minecraft jar에 compileOnly로 컴파일되며, Native API를 그 버전의 게임 클래스로 구현합니다. Poly 모드 로더 패키지 중 유일하게 게임 클래스로더가 정의하는 모듈로, 모드가 선언한 내용을 게임이 준비된 시점에 실제 게임 객체로 만듭니다. | — |
| 게임 테스트 | Mojang의 게임 테스트 서버에서 실제 게임으로 실행하는 모드 테스트입니다. common 엔트리포인트에서 등록하고, ID는 <mod id>:<이름>입니다. 테스트는 succeed()를 호출해야 통과합니다. 창이 뜨지 않으므로 CI에서도 실행할 수 있습니다. | 게임 내 테스트 |
기능 권한 (capabilities) | 위험하거나 게임 깊숙이 개입하는 기능을 쓰려면 poly.mod.json의 capabilities에 먼저 선언해야 하는 권한입니다. 필요한 권한이 없으면 POLY-METADATA-012가 납니다. 현재 실제로 검사하는 대상은 replacesSystems(system.provider.replace)와 transforms(internal.bytecode.transform)입니다. | poly.mod.json 스키마 |
| Native API | Poly 모드가 쓰는 API입니다. 패키지는 dev.polymodloader.api 아래에 있고, Minecraft 타입을 노출하지 않으므로 poly-lifecycle-api만으로 컴파일합니다. 모두 PREVIEW 등급입니다. | Native API 개요 |
| Poly 모드 | Poly 모드 로더의 Native API로 만들어 Poly 모드 로더에서만 실행되는 모드입니다. Fabric 모드, Forge 모드처럼 로더 이름을 붙인 호칭입니다. jar에 poly.mod.json이 있습니다. Poly 모드 로더는 시작할 때 jar의 메타데이터 파일로 모드를 Poly 모드, Fabric, NeoForge, Forge, 알 수 없음으로 분류하고, Poly 모드가 아닌 모드는 로더 브리지가 판정합니다. | 첫 Poly 모드 만들기 |
| 데이터 버전 | 모드가 저장하는 데이터(월드 저장소, 블록 엔티티 데이터, 엔티티 데이터)에 매기는 버전입니다. 예약 키 poly_version에 기록하고, 저장된 데이터가 더 옛 버전이면 DataMigration을 실행합니다. 더 새 버전이면 데이터를 그대로 두고 POLY-STORAGE-001을 기록합니다. | 저장 데이터와 버전 |
| 버전 어댑터 | 버전별 모듈 poly-version-adapter-v<id>입니다. 그 Minecraft 버전의 실행 대상(게임 진입점)과 내장 변환 규칙을 담습니다. Poly 모드 로더는 시작할 때 게임 jar의 version.json을 읽고 ServiceLoader로 맞는 GameVersionAdapter를 고릅니다. 없으면 POLY-BOOTSTRAP-002입니다. | — |
| 변환 규칙과 실패 정책 | 변환 규칙(TransformRuleDefinition)은 규칙 ID, 소유 모드, 게임 버전과 측, 대상(owner 내부 이름, 메서드 이름, JVM descriptor), 동작, 실패 정책을 담은 데이터입니다. 실패 정책은 ABORT_STARTUP(시작 중단)과 DISABLE_RULE(그 규칙만 끔) 두 가지입니다. 실패는 어떤 경우에도 "적용됨"으로 기록하지 않습니다. 모드는 poly.mod.json의 transforms로 선언하며 기본 정책은 disable_rule입니다. | poly.mod.json 스키마 |
| 브리지 (로더 브리지) | 다른 로더(Fabric, NeoForge, MinecraftForge. Quilt는 예정)의 모드를 평가하고 실행하는 SPI(ModLoaderBridge)입니다. 진단을 우선하므로 Poly 모드 로더가 제공하지 못하는 기능을 기능 하나당 발견 항목 하나로 보고합니다. 브리지가 없는 로더의 jar는 POLY-COMPAT-001로 차단됩니다. | 호환성 |
| 생성 팩 | Poly 모드 로더가 만들어 쓰는 데이터 팩(.poly/generated-pack)입니다. 코드로 정의한 바이옴, 배치 기능, 구조물, 게임 테스트 공간의 구조물을 게임의 파일 형식으로 씁니다. 알려진 팩이며, 그 버전은 생성된 파일 내용으로 정해집니다. | 월드 생성 |
시스템과 공급자 (SystemProvider) | 시스템은 모드가 통째로 교체할 수 있는 Poly 모드 로더 기능 단위입니다. ID는 namespace:path이고, 첫 시스템은 poly:game_brand입니다. 공급자(SystemProvider)는 시스템의 구현을 만듭니다. 교체는 poly.mod.json의 replacesSystems에 선언하고, 충돌은 모드 코드가 실행되기 전에 해결합니다. | 시스템 교체, poly.mod.json 스키마 |
| 안정성 등급 | 공개 타입에 @ApiStability로 표시하는 등급으로, STABLE, PREVIEW, VERSION_BOUND, INTERNAL, UNSAFE가 있습니다. 0.1 계열에는 STABLE API가 없고, Native API는 모두 PREVIEW라 버전 사이에 바뀔 수 있습니다. | API 안정성 |
알려진 팩 (KnownPack) | Poly 모드 로더가 모드 jar의 팩에 붙이는 팩 식별 정보입니다(KnownPack("poly", <mod id>, <버전>)). 생성 팩도 알려진 팩입니다. Minecraft 26.2는 알려진 팩에서 온 레지스트리 항목만 안정 항목으로 등록합니다. 그래서 모드의 월드 생성, 차원, 피해 유형 데이터가 월드를 "실험적 설정"으로 만들지 않습니다. | 월드 생성 |
| 엔트리포인트 | Poly 모드 로더가 모드를 초기화할 때 호출하는 클래스로, poly.mod.json의 entrypoints에 적습니다. common은 CommonModInitializer, client는 ClientModInitializer, server는 DedicatedServerModInitializer를 구현합니다. 모든 모드의 common 엔트리포인트를 먼저 호출한 뒤 실행 측(client·server)별 엔트리포인트를 호출합니다. 모든 선언은 common 엔트리포인트 안에서 끝내야 합니다. | 엔트리포인트, 생명주기와 스레드 |
호환성 상태 (Experimental, Blocked) | 다른 로더의 모드를 Poly 모드 로더에서 얼마나 실행할 수 있는지 나타내는 상태입니다: Verified, Partial, Experimental, Blocked, Untested. Experimental은 일부 실험만 통과한 상태로, 지금은 엔트리포인트만 쓰는 Fabric 모드가 여기에 해당합니다. Poly 모드 로더는 이런 모드를 로드하고 POLY-COMPAT-110으로 알립니다. Blocked는 알려진 문제로 실행할 수 없는 상태입니다. 브리지가 막는 발견 항목을 하나라도 보고하면 모드를 로드하지 않습니다. jar가 로드됐다는 사실만으로 Verified라고 쓰지 않습니다. | 호환성 |