평지 맵 study room 을 실습장으로 삼아, 데이터팩·리소스팩·커맨드로 할 수 있는 것을 초심자 → 중급자 → 마스터 → 실전 순서로 전부 다루는 학습 저장소입니다.
문서만 있는 게 아니라 실제로 작동하는 데이터팩과 리소스팩이 들어 있습니다.
넣고 /reload 하면 바로 게임 안에서 학습 메뉴가 열립니다.
zip 으로 이미 묶여 있습니다. 다운로드해서 폴더에 넣기만 하면 끝입니다.
| 무엇 | 다운로드 | 넣는 곳 |
|---|---|---|
| 데이터팩 | study_room_datapack.zip | <월드 폴더>/datapacks/ |
| 리소스팩 | study_room_resourcepack.zip | <.minecraft>/resourcepacks/ |
위 링크는 항상 최신 릴리즈를 받습니다. 저장소에서 직접 받으려면
dist/폴더의 파일을 열고 Download raw file 을 누르세요. 전체 릴리즈 목록: Releases
- 데이터팩 zip 을
<월드 폴더>/datapacks/에 넣습니다 — 압축을 풀지 마세요. - 리소스팩 zip 을
<.minecraft>/resourcepacks/에 넣고 게임 설정에서 켭니다 (선택 — 없어도 기능은 다 작동). - 게임에서:
/reload /function study:lesson/menu
월드 폴더 찾기: 게임의 월드 목록 → 월드 선택 → [편집] → [월드 폴더 열기]
또는 %appdata%\.minecraft\saves\<월드이름> (Windows) /
~/Library/Application Support/minecraft/saves/<월드이름> (macOS) /
~/.minecraft/saves/<월드이름> (Linux)
버전 경고가 떠도 대부분 그냥 작동합니다.
supported_formats범위를 넓게 잡아 두었습니다. 그래도 정확히 맞추고 싶거나 뭔가 안 되면 VERSION.md 를 보세요.
대상 버전은 26.2 로 가정했습니다. 다만 이 저장소는 1.21.x 계열 문법으로 작성되어 있고, 26.2 의 정확한
pack_format숫자와 일부 신규 명령어는 확인하지 못했습니다. 그래서 버전에 민감한 부분마다 구/신 문법을 나란히 적어 두었고,pack_format은supported_formats범위로 넓게 잡아 한 곳만 고치면 되게 했습니다. 자세한 내용과 확인 절차는 VERSION.md 를 보세요.
버전이 안 맞아 뭔가 안 되면, 그 파일 맨 위 주석에 대안 문법이 적혀 있습니다.
zip 만 받아 쓸 거면 이 절은 건너뛰세요. 내용을 고쳐서 쓰려면 이렇게 합니다.
# 1) 저장소 받기
git clone https://github.com/kjooy0305/mindcraft_study.git
cd mindcraft_study
# 2) 내 버전에 pack_format 맞추기 (권장)
python3 tools/set_pack_format.py --from-jar "~/.minecraft/versions/26.2/26.2.jar"
# 3) 오류 미리 검사
python3 tools/validate.py
# 4) zip 으로 빌드
python3 tools/build.py
# 5) 설치까지 자동으로 (월드 이름을 넣으면 데이터팩까지 복사)
python3 tools/build.py --install --world "study room"수동 설치라면:
| 무엇 | 어디에 |
|---|---|
| 데이터팩 | <월드 폴더>/datapacks/ 에 dist/study_room_datapack.zip |
| 리소스팩 | <.minecraft>/resourcepacks/ 에 dist/study_room_resourcepack.zip |
게임에서:
/reload # 데이터팩 적용
/function study:lesson/menu # 학습 메뉴 열기 ← 여기서 전부 시작
/function study:util/room_setup # 평지에 학습실(아레나+실험대) 짓기
/function study:item/give_all # 커스텀 아이템 6종 받기리소스팩을 켜면 지팡이·검·램프가 전용 텍스처로 보입니다. 안 켜도 기능은 전부 작동합니다.
| 문서 | 내용 |
|---|---|
| 01 시작하기 | 폴더 구조, /reload, 오류 읽는 법, 디버깅 도구 |
| 02 명령어 기초 | 게임모드·좌표 3종·셀렉터·execute·필수 명령 전부 |
| 03 커맨드 블록 | 3종류·2모드·체인 연결·비교기 센서·실전 패턴 |
| 문서 | 내용 |
|---|---|
| 04 데이터팩 구조 | 폴더 규칙, load/tick, 태그, 함수 설계 |
| 05 스코어보드 시스템 | 변수·연산·타이머·상태머신·NBT↔점수 변환 |
| 06 구조물 블록 | SAVE/LOAD/CORNER/DATA, 지그소, /place |
| 07 커스텀 아이템 | 컴포넌트 전체, 우클릭 감지, 강화 시스템 |
| 08 리소스팩 | 아이템 모델 정의, 조건부 모델, 소리, 폰트 |
| 문서 | 내용 |
|---|---|
| 09 BDEngine 연동 | 모델 가져오기, 몹에 붙이기, 애니메이션 |
| 10 커스텀 몹·보스 | 새로운 적 만들기, 페이즈, 커스텀 AI·투사체 |
| 11 월드젠·바이옴 | 커스텀 바이옴·차원, 지형 생성 규칙 부수기 |
| 12 RPG 시스템 | 레벨·스탯·직업·스킬·NPC·퀘스트 |
| 문서 | 내용 |
|---|---|
| 13 스터디룸 구축 | 이 맵에 실제로 얹는 순서, 성능 관리, 배포 |
| 14 MythicCraft 대조표 | MythicMobs·ModelEngine 기능 → 데이터팩 구현법 |
| 99 치트시트 | 명령어·NBT·컴포넌트 빠른 참조 |
mindcraft_study/
├── datapack/study_room/ ← 작동하는 데이터팩 (네임스페이스: study)
│ └── data/
│ ├── minecraft/tags/function/ load·tick 등록
│ └── study/
│ ├── function/ 77개 함수
│ │ ├── core/ load, tick, uninstall
│ │ ├── lesson/ 게임 안에서 읽는 강의 8개
│ │ ├── item/ 커스텀 아이템 동작
│ │ ├── block/ 커스텀 블록(마법 램프)
│ │ ├── mob/ 보스·하수인·스킬·페이즈
│ │ ├── rpg/ 레벨·스탯·직업·마나
│ │ ├── display/ BDEngine 모델·NPC
│ │ ├── util/ 레이캐스트·매크로·학습실 설치
│ │ └── reward/ 발전 과제 보상
│ ├── loot_table/ 보스·하수인 드롭
│ ├── recipe/ 커스텀 제작법
│ ├── advancement/ 이벤트 감지 + 보상
│ ├── predicate/ 영역·확률·장비 조건
│ ├── item_modifier/ 아이템 강화
│ ├── tags/ 블록·엔티티·함수 태그
│ ├── dimension/ 커스텀 차원
│ └── worldgen/biome/ 커스텀 바이옴
├── resourcepack/study_room/ ← 작동하는 리소스팩
│ └── assets/study/
│ ├── items/ 아이템 모델 정의 (1.21.4+)
│ ├── models/item/ 모델
│ ├── textures/item/ 16x16 텍스처 (코드로 생성)
│ └── lang/ 한국어
├── tools/
│ ├── build.py zip 빌드 + 자동 설치
│ ├── validate.py 게임 켜기 전 오류 검사
│ ├── bdengine_import.py BDEngine → 데이터팩 함수 변환
│ ├── set_pack_format.py 버전 맞추기
│ └── gen_textures.py 텍스처 생성
├── dist/ ← 빌드된 zip (바로 다운로드용)
│ ├── study_room_datapack.zip
│ └── study_room_resourcepack.zip
├── examples/ 구버전 방식 등 참고 자료
└── docs/ 15개 문서
커스텀 아이템 6종 — 번개 지팡이(레이캐스트+번개), 건축 지팡이(발판 생성), 순간이동 부적, 마법 램프 설치기(커스텀 블록), 영혼검(컴포넌트만으로 완성), 안내서(클릭 가능한 책)
커스텀 보스 — 고대의 감시자. 체력 400, 3페이즈, 광역 강타·하수인 소환·화염 탄막, 보스바 연동, 아레나 이탈 방지, 전용 드롭 테이블, 토벌 시 발전 과제 + 전용 무기 보상
RPG 시스템 — 레벨/경험치/스탯 3종(힘·민첩·지능)/마나 재생/직업 3종/스탯 포인트 분배, 속성(attribute)에 실시간 반영, 액션바 HUD
커스텀 블록 — 디스플레이 엔티티 + light 블록 조합, 설치/회수/회전 애니메이션
커스텀 차원·바이옴 — 시간이 멈춘 학습의 공허, 보라 하늘 수정 평원
학습실 자동 건축 — 21×21 아레나 + 커맨드 블록 3종 실험대 + 구조물 블록 실험대
/reload # 먼저 이걸 해본다
/datapack list # 데이터팩이 로드됐는지 확인
/function study:core/uninstall # 스코어보드·엔티티 완전 제거
/function study:util/cleanup # 엔티티만 정리/reload했을 때 빨간 오류 메시지가 나오면 그게 답입니다. 파일 경로와 이유를 알려줍니다.- 아무 반응이 없으면
python3 tools/validate.py로 오타·경로 오류를 먼저 잡으세요. - 자세한 진단은 docs/01-초심자-시작하기.md 의 "오류 읽는 법" 참고.
데이터팩으로 할 수 없는 것도 알아야 시간을 낭비하지 않습니다.
| 못 하는 것 | 이유 / 대안 |
|---|---|
| 완전히 새로운 블록·아이템·엔티티 종류 추가 | 레지스트리는 모드(Fabric/Forge) 영역. 바닐라를 껍데기로 재활용해야 한다 |
| 새 GUI(인벤토리 창) 만들기 | 셜커 상자·책·tellraw 메뉴로 대체 |
| 커스텀 차원 포탈 | 블록을 밟으면 tp 하는 방식으로 대체 |
| 이미 생성된 청크의 지형 변경 | 바이옴만은 /fillbiome 으로 가능 |
| 새 소리 파일 없이 커스텀 사운드 | 리소스팩에 .ogg 를 직접 넣어야 한다 |
| 진짜 삼각함수·소수 연산 | 스코어보드는 정수뿐. 스토리지 + store 배율로 우회 |
| 모델 본(bone) 단위 골격 애니메이션 | 디스플레이 엔티티를 여러 개 쌓아 근사 (BDEngine 방식) |
MythicMobs·ModelEngine 은 서버 플러그인(Paper/Spigot) 이지 데이터팩이 아닙니다. 기능의 70~80% 는 데이터팩으로 재현 가능하며, 어떤 기능이 어떻게 대응되는지는 14 MythicCraft 대조표 에 항목별로 정리했습니다.