API 안정성
공개 타입의 안정성 등급은 코드의 @ApiStability 애너테이션에 적혀 있습니다. 이 문서와 코드가 다르면 코드를 기준으로 하세요.
0.1 계열에는 STABLE API가 없습니다
첫 공개 API는 실제로 써 보며 검증하기 전까지 PREVIEW로 둡니다. 모드가 쓰는 Native API는 모두 PREVIEW이므로 버전 사이에 바뀔 수 있습니다.
등급
| 등급 | 뜻 |
|---|---|
STABLE | 호환성을 약속하는 API(아직 없음) |
PREVIEW | 공개 API이지만 바뀔 수 있음 |
VERSION_BOUND | 특정 Minecraft 버전에 묶인 구현 |
INTERNAL | Poly 모드 로더 내부용. 모드가 쓰면 안 됨 |
UNSAFE | 게임을 직접 바꾸는 위험한 기능 |
동작 분류
각 타입이 할 수 있는 일을 나타냅니다. 값은 READ, WRITE, REGISTER, EXTEND, REPLACE, INTERCEPT, TRANSFORM, MIGRATE, INSPECT이고, 이벤트에는 OBSERVE도 있습니다.
영역별 요약
모든 타입은 dev.polymodloader.api 아래에 있고 등급은 PREVIEW입니다.
| 영역 | 주요 타입 | 시점·스레드 |
|---|---|---|
| 생명주기 | CommonModInitializer, ClientModInitializer, DedicatedServerModInitializer, ModContext | 의존성 순서, 메인 스레드, 게임 main 전 |
| 이벤트 | EventKey, EventRegistry, ServerEvents, ServerView | 등록은 아무 때나(스레드 안전). 서버 이벤트는 서버 스레드 |
| 시스템 | SystemId, SystemProvider, SystemLookup, GameBrandSystem | 제공자: 메인 스레드, 엔트리포인트 전 1회 |
| 콘텐츠 | ContentRegistrar, BlockDefinition, ItemDefinition, BlockBehavior, ItemBehavior, CreativeTab, ResourceId | 선언: common 엔트리포인트. 동작: 월드 스레드, 양쪽 |
| 블록 상태·블록 엔티티 | BlockProperty, BlockStateView, BlockEntityDefinition, BlockEntityView, MenuLayout, InventoryView | 월드 스레드. 틱: 서버 스레드 |
| 아이템 데이터 | ItemComponentKey, ComponentType, ItemStackRef | 월드 스레드 |
| 월드·엔티티 | WorldView, EntityView, LivingEntityView, MobView, PlayerView, StoredData, DataTree | 월드 스레드, 콜백 동안만 유효. 변경은 서버 |
| 몹·게임플레이 | EntityDefinition, AiGoal, ProjectileDefinition, EffectDefinition, GameRuleKey, AdvancementTrigger | 서버 스레드(동작) |
| 월드 생성 | WorldgenRegistrar, BiomeSelector, BiomeDefinition, TerrainGenerator, ColumnBuilder | common 엔트리포인트. 지형 생성기: 월드 생성 스레드(동시 호출) |
| 명령어·권한 | CommandRegistrar, CommandNode, CommandContext, CommandSource, PermissionRegistrar, PermissionNode, PermissionProvider | 서버 스레드. 서버 시작·/reload마다 설치 |
| 네트워크 | NetworkRegistrar, PayloadChannel, PayloadCodec | 송신: 서버/클라이언트 스레드. 코덱: 네트워크 스레드(게임 상태 접근 금지) |
| 클라이언트 | ClientRegistrar, KeyBinding, HudCanvas, ClientView, ModScreen, BlockEntityCanvas, DynamicTexture, ClientEvents | 클라이언트 스레드. HUD·그리기·시야각: 렌더 스레드, 매 프레임 |
| 리소스 | ResourceRegistrar, ResourceReloadListener, BinaryReloadListener | 리로드 적용 스레드 |
| 저장·동기화 | EntityDataKey, EntityDataOptions, StorageOptions, DataMigration | 서버 스레드. 클라이언트는 읽기 전용 사본 |
| 게임 테스트 | GameTestRegistrar, GameTestContext, TestArea | 게임 테스트 서버의 서버 스레드 |
내부 API
| 패키지 | 등급 |
|---|---|
dev.polymodloader.internal.transform.* (변환 규칙) | INTERNAL — 모드는 아직 쓸 수 없음. 모드 변환은 poly.mod.json의 transforms로 선언 |
dev.polymodloader.game.version.* (버전 어댑터 계약) | INTERNAL |
| 버전별 어댑터·게임 계층 | VERSION_BOUND |
poly.mod.json 필드의 상태는 poly.mod.json 스키마에 있습니다.