NeoForge 26.1 Docs

dimension JSON, dimension_type JSON, biome JSON 세 파일로 master_dimension:magic_realm 커스텀 차원을 NeoForge 데이터팩 방식으로 등록하는 전체 과정을 다룹니다.

차원 등록 개요

NeoForge 26.1(Minecraft 1.21+)에서 커스텀 차원을 만들려면 순수 데이터팩 JSON 3종이 필요합니다. Java 코드 없이 JSON 파일만으로 등록하는 것이 공식 권장 방식입니다.

JSON 파일	역할
`data/<mod_id>/dimension/<id>.json`	차원 진입점 — 지형 생성기·바이옴 소스 연결
`data/<mod_id>/dimension_type/<id>.json`	차원 물리 속성 — 하늘·높이·밝기 등
`data/<mod_id>/worldgen/biome/<id>.json`	바이옴 환경 — 날씨·색상·스포너

세 파일은 모두 동일한 네임스페이스(master_dimension)와 동일한 ID(magic_realm)를 사용해야 합니다.

1. dimension JSON

차원 등록의 진입점입니다. 차원 타입과 지형 생성기를 연결합니다.

// data/master_dimension/dimension/magic_realm.json
{
  "type": "master_dimension:magic_realm",
  "generator": {
    "type": "minecraft:noise",
    "biome_source": {
      "type": "minecraft:fixed",
      "biome": "master_dimension:magic_realm"
    },
    "settings": "minecraft:overworld"
  }
}

주요 필드

필드	값	설명
`type`	`master_dimension:magic_realm`	아래서 정의할 `dimension_type` JSON 참조
`generator.type`	`minecraft:noise`	소음 기반 지형 생성기 (바닐라 기본 방식)
`biome_source.type`	`minecraft:fixed`	차원 전체를 단일 바이옴으로 고정
`biome_source.biome`	`master_dimension:magic_realm`	아래서 정의할 바이옴 JSON 참조
`settings`	`minecraft:overworld`	바닐라 오버월드 소음 설정 재사용

2. dimension_type JSON

차원의 물리 속성을 정의합니다. 이 파일이 없으면 차원 로드가 실패합니다.

// data/master_dimension/dimension_type/magic_realm.json
{
  "ultrawarm": false,
  "natural": true,
  "coordinate_scale": 1.0,
  "has_skylight": true,
  "has_ceiling": false,
  "ambient_light": 0.5,
  "monster_spawn_light_level": 0,
  "monster_spawn_block_light_limit": 0,
  "piglin_safe": false,
  "bed_works": true,
  "respawn_anchor_works": false,
  "has_raids": false,
  "logical_height": 256,
  "min_y": -64,
  "height": 384,
  "infiniburn": "#minecraft:infiniburn_overworld",
  "effects": "minecraft:overworld",
  "fixed_time": 6000
}

주요 필드

필드	값	설명
`ultrawarm`	`false`	네더처럼 물이 증발하지 않음
`natural`	`true`	나침반·시계 정상 작동
`coordinate_scale`	`1.0`	오버월드 1:1 좌표 비율
`has_skylight`	`true`	하늘 밝기 존재 (낮/밤 사이클)
`has_ceiling`	`false`	네더처럼 위쪽 천장 없음
`ambient_light`	`0.5`	기본 주변광 (0.0~1.0, 0.0 = 완전 어두움)
`min_y` / `height`	`-64` / `384`	오버월드와 동일한 높이 범위
`fixed_time`	`6000`	항상 낮(6000틱 = 정오)
`effects`	`minecraft:overworld`	하늘 색상·안개 효과 오버월드 스타일

3. biome JSON

차원 안에서 사용할 바이옴 환경을 정의합니다.

// data/master_dimension/worldgen/biome/magic_realm.json
{
  "has_precipitation": false,
  "temperature": 0.7,
  "downfall": 0.5,
  "effects": {
    "sky_color": 9999999,
    "fog_color": 5263232,
    "water_color": 6394502,
    "water_fog_color": 5263232
  },
  "spawners": {
    "monster": [],
    "creature": [],
    "ambient": [],
    "water_creature": [],
    "water_ambient": [],
    "axolotls": [],
    "underground_water_creature": [],
    "misc": []
  },
  "spawn_costs": {},
  "carvers": [],
  "features": [[], [], [], [], [], [], [], [], [], [], []]
}

주요 필드

필드	값	설명
`has_precipitation`	`false`	비/눈 없음
`temperature`	`0.7`	온도 (0.0 = 추움, 1.0 = 더움)
`effects.sky_color`	`9999999` (16진수 `0x98967F`)	하늘 색상 — 연보라빛 마법 톤
`effects.fog_color`	`5263232`	안개 색상
`effects.water_color`	`6394502`	물 색상
`spawners`	모든 카테고리 `[]`	이 챕터에서는 몬스터 스폰 없음
`features`	`[[], [], ...]` 11개	지형 피처 없음 (빈 차원)

파일 배치 구조 확인

세 JSON을 모두 만들면 아래 구조가 됩니다:

examplemod-master-projects/dimension/
└── src/main/resources/
    └── data/
        └── master_dimension/
            ├── dimension/
            │   └── magic_realm.json          ← 차원 등록
            ├── dimension_type/
            │   └── magic_realm.json          ← 차원 타입
            └── worldgen/
                └── biome/
                    └── magic_realm.json      ← 바이옴

⚠️ dimension_type JSON 누락

dimension JSON만 있고 dimension_type JSON 없으면: → 차원 로드 실패: "Unknown dimension_type"

세 JSON 모두 필수 — dimension, dimension_type, biome

인게임 진입 확인

모드를 빌드하고 게임을 실행한 후 콘솔 명령으로 차원에 진입합니다:

/execute in master_dimension:magic_realm run tp @s ~ 64 ~

master_dimension — mod_id (gradle.properties의 mod_id=master_dimension)
magic_realm — dimension JSON 파일명 (슬러그)
tp @s ~ 64 ~ — 현재 x/z, y=64 위치로 텔레포트

명령 실행 후 하늘이 연보라빛으로 바뀌면 차원 진입 성공입니다.

자주 하는 실수

실수	증상	해결
`dimension_type` JSON 누락	게임 시작 시 `Unknown dimension_type` 오류	`dimension_type/magic_realm.json` 추가
`mod_id` 불일치	차원 명령어가 자동완성되지 않음	`gradle.properties`의 `mod_id`와 JSON 네임스페이스 일치 확인
`features` 배열 길이 오류	Velite/데이터팩 로드 실패	`features`는 정확히 11개 내부 배열 필요
바닐라 차원 수정	기존 오버월드/네더 비헤이비어 파괴	반드시 새 네임스페이스(`master_dimension:...`) 사용

다음 단계

세 JSON으로 빈 차원 등록을 완료했습니다. 다음 챕터에서 차원에 포탈 블록과 진입 메커니즘을 추가합니다.

02-portal-block — 커스텀 포탈 블록 등록
03-portal-trigger — 포탈 활성화 이벤트
04-world-generation — 지형/구조물 추가

차원 등록 개요

JSON 파일	역할
`data/<mod_id>/dimension/<id>.json`	차원 진입점 — 지형 생성기·바이옴 소스 연결
`data/<mod_id>/dimension_type/<id>.json`	차원 물리 속성 — 하늘·높이·밝기 등
`data/<mod_id>/worldgen/biome/<id>.json`	바이옴 환경 — 날씨·색상·스포너

세 파일은 모두 동일한 네임스페이스(master_dimension)와 동일한 ID(magic_realm)를 사용해야 합니다.

1. dimension JSON

차원 등록의 진입점입니다. 차원 타입과 지형 생성기를 연결합니다.

// data/master_dimension/dimension/magic_realm.json
{
  "type": "master_dimension:magic_realm",
  "generator": {
    "type": "minecraft:noise",
    "biome_source": {
      "type": "minecraft:fixed",
      "biome": "master_dimension:magic_realm"
    },
    "settings": "minecraft:overworld"
  }
}

주요 필드

필드	값	설명
`type`	`master_dimension:magic_realm`	아래서 정의할 `dimension_type` JSON 참조
`generator.type`	`minecraft:noise`	소음 기반 지형 생성기 (바닐라 기본 방식)
`biome_source.type`	`minecraft:fixed`	차원 전체를 단일 바이옴으로 고정
`biome_source.biome`	`master_dimension:magic_realm`	아래서 정의할 바이옴 JSON 참조
`settings`	`minecraft:overworld`	바닐라 오버월드 소음 설정 재사용

2. dimension_type JSON

차원의 물리 속성을 정의합니다. 이 파일이 없으면 차원 로드가 실패합니다.

// data/master_dimension/dimension_type/magic_realm.json
{
  "ultrawarm": false,
  "natural": true,
  "coordinate_scale": 1.0,
  "has_skylight": true,
  "has_ceiling": false,
  "ambient_light": 0.5,
  "monster_spawn_light_level": 0,
  "monster_spawn_block_light_limit": 0,
  "piglin_safe": false,
  "bed_works": true,
  "respawn_anchor_works": false,
  "has_raids": false,
  "logical_height": 256,
  "min_y": -64,
  "height": 384,
  "infiniburn": "#minecraft:infiniburn_overworld",
  "effects": "minecraft:overworld",
  "fixed_time": 6000
}

주요 필드

필드	값	설명
`ultrawarm`	`false`	네더처럼 물이 증발하지 않음
`natural`	`true`	나침반·시계 정상 작동
`coordinate_scale`	`1.0`	오버월드 1:1 좌표 비율
`has_skylight`	`true`	하늘 밝기 존재 (낮/밤 사이클)
`has_ceiling`	`false`	네더처럼 위쪽 천장 없음
`ambient_light`	`0.5`	기본 주변광 (0.0~1.0, 0.0 = 완전 어두움)
`min_y` / `height`	`-64` / `384`	오버월드와 동일한 높이 범위
`fixed_time`	`6000`	항상 낮(6000틱 = 정오)
`effects`	`minecraft:overworld`	하늘 색상·안개 효과 오버월드 스타일

3. biome JSON

차원 안에서 사용할 바이옴 환경을 정의합니다.

// data/master_dimension/worldgen/biome/magic_realm.json
{
  "has_precipitation": false,
  "temperature": 0.7,
  "downfall": 0.5,
  "effects": {
    "sky_color": 9999999,
    "fog_color": 5263232,
    "water_color": 6394502,
    "water_fog_color": 5263232
  },
  "spawners": {
    "monster": [],
    "creature": [],
    "ambient": [],
    "water_creature": [],
    "water_ambient": [],
    "axolotls": [],
    "underground_water_creature": [],
    "misc": []
  },
  "spawn_costs": {},
  "carvers": [],
  "features": [[], [], [], [], [], [], [], [], [], [], []]
}

주요 필드

필드	값	설명
`has_precipitation`	`false`	비/눈 없음
`temperature`	`0.7`	온도 (0.0 = 추움, 1.0 = 더움)
`effects.sky_color`	`9999999` (16진수 `0x98967F`)	하늘 색상 — 연보라빛 마법 톤
`effects.fog_color`	`5263232`	안개 색상
`effects.water_color`	`6394502`	물 색상
`spawners`	모든 카테고리 `[]`	이 챕터에서는 몬스터 스폰 없음
`features`	`[[], [], ...]` 11개	지형 피처 없음 (빈 차원)

파일 배치 구조 확인

세 JSON을 모두 만들면 아래 구조가 됩니다:

examplemod-master-projects/dimension/
└── src/main/resources/
    └── data/
        └── master_dimension/
            ├── dimension/
            │   └── magic_realm.json          ← 차원 등록
            ├── dimension_type/
            │   └── magic_realm.json          ← 차원 타입
            └── worldgen/
                └── biome/
                    └── magic_realm.json      ← 바이옴

⚠️ dimension_type JSON 누락

dimension JSON만 있고 dimension_type JSON 없으면: → 차원 로드 실패: "Unknown dimension_type"

세 JSON 모두 필수 — dimension, dimension_type, biome

인게임 진입 확인

모드를 빌드하고 게임을 실행한 후 콘솔 명령으로 차원에 진입합니다:

/execute in master_dimension:magic_realm run tp @s ~ 64 ~

master_dimension — mod_id (gradle.properties의 mod_id=master_dimension)
magic_realm — dimension JSON 파일명 (슬러그)
tp @s ~ 64 ~ — 현재 x/z, y=64 위치로 텔레포트

명령 실행 후 하늘이 연보라빛으로 바뀌면 차원 진입 성공입니다.

자주 하는 실수

실수	증상	해결
`dimension_type` JSON 누락	게임 시작 시 `Unknown dimension_type` 오류	`dimension_type/magic_realm.json` 추가
`mod_id` 불일치	차원 명령어가 자동완성되지 않음	`gradle.properties`의 `mod_id`와 JSON 네임스페이스 일치 확인
`features` 배열 길이 오류	Velite/데이터팩 로드 실패	`features`는 정확히 11개 내부 배열 필요
바닐라 차원 수정	기존 오버월드/네더 비헤이비어 파괴	반드시 새 네임스페이스(`master_dimension:...`) 사용

다음 단계

세 JSON으로 빈 차원 등록을 완료했습니다. 다음 챕터에서 차원에 포탈 블록과 진입 메커니즘을 추가합니다.

02-portal-block — 커스텀 포탈 블록 등록
03-portal-trigger — 포탈 활성화 이벤트
04-world-generation — 지형/구조물 추가

차원 등록 — 데이터팩 3종 JSON

차원 등록 개요

1. dimension JSON

주요 필드

2. dimension_type JSON

주요 필드

3. biome JSON

주요 필드

파일 배치 구조 확인

인게임 진입 확인

자주 하는 실수

다음 단계

On this page

차원 등록 — 데이터팩 3종 JSON

차원 등록 개요

1. dimension JSON

주요 필드

2. dimension_type JSON

주요 필드

3. biome JSON

주요 필드

파일 배치 구조 확인

인게임 진입 확인

자주 하는 실수

다음 단계

On this page