본문으로 건너뛰기
버전: Minecraft 26.2

공통 규칙

ID​

모든 콘텐츠 ID는 <mod id>:<path> 형식입니다. 선언할 때는 path만 넘기면 Poly 모드 로더가 모드 ID를 붙여 줍니다.

  • path에는 소문자, 숫자, _ . / -만 쓸 수 있습니다.
  • 이름이 중복되거나 잘못되면 POLY-CONTENT-001 오류가 납니다.
  • 코드에서는 ID를 ResourceId로 다루며, 생성할 때 이름을 검증합니다.
ResourceId mine = ResourceId.of("ruby_mod", "ruby_block");
ResourceId vanilla = ResourceId.minecraft("stone");
ResourceId parsed = ResourceId.parse("ruby_mod:ruby");

선언 메서드는 대부분 핸들(BlockHandle, ItemHandle, EntityHandle 등)을 돌려줍니다. handle.id()로 ID를, handle.isRegistered()로 게임에 등록됐는지를 확인할 수 있습니다.

선언 시점​

콘텐츠·명령어·채널·생성기·리로드 리스너·권한 노드·테스트는 엔트리포인트 안에서 선언합니다.

  • Poly 모드 로더는 게임이 레지스트리를 동결하기 직전에 블록, 블록 아이템, 아이템 순서로 등록합니다.
  • 그 뒤에 선언하면 영역별 "등록이 닫힌 뒤" 오류가 납니다(POLY-CONTENT-002, POLY-COMMAND-002, POLY-WORLDGEN-002 등).
  • 모드는 엔트리포인트에서 선언만 하면 됩니다. Poly 모드 로더는 게임 버전과 무관하게 선언을 즉시 검증하고, 게임 계층은 게임이 준비된 시점에 그 선언을 실제 게임 객체로 만듭니다.

양쪽 일치​

클라이언트와 서버는 같은 콘텐츠를 같은 순서로 선언해야 합니다. 게임이 블록 상태를 번호로 동기화하기 때문입니다. 그래서 콘텐츠 선언은 common 엔트리포인트에 둡니다.

스레드와 뷰 수명​

  • 뷰(WorldView, EntityView, PlayerView 등)는 해당 월드의 스레드에서, 콜백이 실행되는 동안에만 사용합니다. 필드에 저장하지 마세요.
  • 콜백이 어느 스레드에서 호출되는지는 각 페이지와 API 안정성의 표에 나와 있습니다.

서버와 클라이언트​

  • 월드를 바꾸는 메서드는 서버에서만 쓸 수 있으며, 클라이언트에서 호출하면 IllegalStateException이 발생합니다.
  • 동작 콜백(BlockBehavior, ItemBehavior 등)은 서버와 클라이언트 양쪽에서 호출될 수 있습니다. world.isClientSide()로 확인한 뒤 서버에서만 상태를 바꾸세요.
public InteractionResult onUse(BlockUse use) {
    if (!use.world().isClientSide()) {
        use.player().give(SPARK, 1);
    }
    return InteractionResult.SUCCESS;
}
  • PASS를 반환하면 게임의 기본 동작이 그대로 실행됩니다.

리소스​

모델, 텍스처, 번역(assets/)과 레시피, 전리품, 태그, 월드 생성(data/)은 바닐라 26.2 형식 그대로 모드 jar에 넣습니다. 자세한 내용은 리소스와 데이터를 참고하세요.

실패​

선언이 잘못되면 그 자리에서 POLY-영역-번호 코드와 함께 실패합니다. 실행 중 콜백에서 예외가 나면 영역에 따라 기록만 하고 계속하거나(예: POLY-SCHEDULE-001), 해당 기능만 끕니다(예: HUD 레이어의 POLY-CLIENT-003). 자세한 내용은 오류 코드를 참고하세요.

Buy me a coffee