blockstate JSON과 모델 JSON

블록을 등록했다면 이제 어떻게 보일지를 정의해야 합니다. Minecraft는 두 단계로 블록 외형을 결정합니다.

1. blockstate JSON — 블록의 현재 상태(예: facing=north)에 따라 어떤 모델을 쓸지 선택
2. 모델 JSON — 실제 3D 형태, 텍스처 매핑, 부모 모델 지정

두 파일 모두 src/main/resources/assets/examplemod/ 아래에 위치합니다.

1. blockstate JSON

1-1. 파일 위치

src/main/resources/assets/examplemod/
└── blockstates/
    └── first_block.json

블록 ID가 examplemod:first_block이면 파일명도 반드시 first_block.json이어야 합니다. 이름이 다르면 Minecraft가 파일을 찾지 못합니다.

1-2. variants 방식 (단순 블록)

상태가 하나뿐인 블록은 빈 문자열 키 ""를 사용합니다.

{
  "variants": {
    "": { "model": "examplemod:block/first_block" }
  }
}

• "variants" — 상태별 모델 매핑 객체
• "" — 상태 조건 없음 (항상 이 모델 사용)
• "model" — 참조할 모델 JSON 경로 (네임스페이스:block/파일명)

1-3. variants 방식 (facing 회전 블록)

HorizontalDirectionalBlock 등 방향 속성이 있는 블록은 각 방향마다 y 회전값을 지정합니다.

{
  "variants": {
    "facing=north": { "model": "examplemod:block/oriented", "y": 0   },
    "facing=east":  { "model": "examplemod:block/oriented", "y": 90  },
    "facing=south": { "model": "examplemod:block/oriented", "y": 180 },
    "facing=west":  { "model": "examplemod:block/oriented", "y": 270 }
  }
}

• y 값은 Y축 기준 시계 방향 회전 각도입니다 (0 / 90 / 180 / 270만 허용).
• x 키로 X축 회전도 가능합니다 (경사면 등).

1-4. multipart 방식 (펜스·벽 등)

여러 조건을 조합해 부분 모델을 쌓는 방식입니다. 펜스처럼 연결 방향에 따라 모양이 달라지는 블록에 씁니다.

{
  "multipart": [
    { "apply": { "model": "examplemod:block/post" } },
    {
      "when":  { "north": "true" },
      "apply": { "model": "examplemod:block/side_north" }
    },
    {
      "when":  { "south": "true" },
      "apply": { "model": "examplemod:block/side_south" }
    }
  ]
}

• when 없는 항목은 항상 렌더링됩니다 (기둥 부분).
• when이 있는 항목은 조건이 참일 때만 추가됩니다.
• variants와 multipart는 같은 파일에 혼용할 수 없습니다.

2. 모델 JSON

2-1. 파일 위치

src/main/resources/assets/examplemod/
└── models/
    └── block/
        └── first_block.json

2-2. parent 종류

parent는 모델의 기본 형태를 결정합니다. 바닐라 모델을 상속받아 텍스처만 교체하는 방식이 일반적입니다.

2-3. cube_all 예시 (6면 동일)

{
  "parent": "minecraft:block/cube_all",
  "textures": {
    "all": "examplemod:block/first_block"
  }
}

텍스처 경로 "examplemod:block/first_block"은 textures/block/first_block.png를 가리킵니다.

2-4. cube_column 예시 (원목 스타일)

{
  "parent": "minecraft:block/cube_column",
  "textures": {
    "end":  "examplemod:block/log_top",
    "side": "examplemod:block/log_side"
  }
}

• end — 위아래 면 텍스처
• side — 4개 측면 텍스처

2-5. orientable 예시 (방향 블록)

{
  "parent": "minecraft:block/orientable",
  "textures": {
    "front": "examplemod:block/furnace_front",
    "side":  "examplemod:block/furnace_side",
    "top":   "examplemod:block/furnace_top"
  }
}

facing 속성과 blockstate JSON의 y 회전을 함께 쓰면 방향에 따라 앞면이 바뀝니다.

3. 전체 파일 경로 정리

src/main/resources/assets/examplemod/
├── blockstates/
│   └── first_block.json        ← variants 또는 multipart
├── models/
│   └── block/
│       └── first_block.json    ← parent + textures
└── textures/
    └── block/
        └── first_block.png     ← 16×16 PNG

블록 아이템(BlockItem)도 별도 아이템 모델이 필요합니다.

models/
└── item/
    └── first_block.json        ← 블록 아이템 모델

블록 아이템 모델은 보통 블록 모델을 그대로 참조합니다.

{
  "parent": "examplemod:block/first_block"
}

4. 안티패턴 — parent 누락 시 투명 블록

⚠️ parent 없는 모델 JSON

// ❌ parent 없음 → Minecraft가 모델 형태를 알 수 없음
{
  "textures": { "all": "examplemod:block/test" }
}

인게임에서 블록이 투명하게 렌더링됩니다. 충돌 박스(collision)는 정상이지만 눈에 보이지 않습니다.

콘솔에 Missing model 경고가 출력됩니다.

해결: 반드시 parent를 명시하세요. 단순 블록이라면 "minecraft:block/cube_all"이 가장 안전합니다.

5. 인게임 검증

5-1. facing 4방향 설치 확인

HorizontalDirectionalBlock을 사용하는 블록이라면 4방향으로 설치해 텍스처가 올바르게 회전하는지 확인합니다.

1. runClient로 클라이언트 실행
2. 크리에이티브 탭에서 블록 꺼내기
3. 북/동/남/서 방향으로 각각 설치
4. 각 방향에서 앞면 텍스처가 플레이어를 향하는지 확인

5-2. F3 디버그로 blockstate 확인

블록을 바라보면 F3 화면 오른쪽에 현재 blockstate 값이 표시됩니다.

examplemod:first_block
  facing: north

blockstate JSON의 키와 일치하는지 대조합니다.

요약

다음 챕터에서는 블록에 BlockEntity를 붙여 데이터를 저장하는 방법을 학습합니다.