예제 모드

Poly 모드 로더 소스의 examples/ 폴더에 Poly 모드 예제가 다섯 개 있습니다. 모두 실제 게임에서 검증한 모드입니다. Poly 모드 로더 소스는 지금 비공개이므로 이 페이지에서는 각 예제가 보여 주는 것을 설명하고, 문서에 필요한 코드는 Native API 페이지에 싣습니다.

새 모드를 시작할 때는 예제가 아니라 모드 템플릿을 다운로드합니다. 모드 템플릿 받기를 보세요.

한눈에 보기

경로	모드 ID	보여 주는 것
examples/crystal-garden	crystal_garden	첫 Poly 모드 만들기 튜토리얼의 완성본. 자라는 블록, 저장 데이터, 명령어·권한, 접속 확인, 클라이언트 그리기, 게임 테스트
examples/minimal-native-mod	minimal_native_mod	가장 작은 Poly 모드. 엔트리포인트, 서버 이벤트, 종료 작업
examples/custom-system-mod	custom_system_mod	시스템 교체(poly:game_brand)
examples/transform-demo-mod	transform_demo_mod	poly.mod.json으로 선언하는 코드 변환·call-site 변경·순서 선언·접근 확대
examples/native-showcase-mod	native_showcase	Native API 전 영역과 게임 내 테스트

crystal-garden

튜토리얼에서 만드는 모드입니다. 다른 예제와 달리 모드 제작자가 쓰는 방식(모드 플러그인 dev.polymodloader.mod)대로 빌드하는 독립 프로젝트입니다. 크리스털 새싹은 4단계에 걸쳐 자라며, 다 자란 새싹을 사용하면 크리스털을 얻습니다.

파일	내용
CrystalGardenMod	common 엔트리포인트. 아이템·블록 선언, 엔티티 데이터 키, 권한 노드, 접속 확인
CrystalSprout	블록 상태 stage, 상태별 모양·밝기, 매 틱 자라는 블록 엔티티, 수확(엔티티 데이터·월드 저장소 기록)
GardenCommands	/garden stats, /garden grow <pos>(권한 crystal_garden:grow)
CrystalGardenClient	접속 확인 답, 새싹 위 성장 표시, 수확 수 HUD, 키 바인딩 toggle_hud(기본 G)
GardenTests	게임 내 테스트 4개

minimal-native-mod

가장 작은 Poly 모드입니다. 블록·아이템 같은 게임 내용은 추가하지 않고, 엔트리포인트가 실행됐다는 사실을 로그로 남깁니다.

파일	내용
poly.mod.json	"minecraft": ["26.*"], common·client 엔트리포인트, poly 의존성
MinimalNativeMod	common 엔트리포인트. 인사 로그, 종료 작업(onShutdown), ServerEvents.STARTED·STOPPING 리스너
MinimalNativeModClient	client 엔트리포인트. 호출됐다는 로그만 남김

custom-system-mod

poly:game_brand 시스템을 교체해 Minecraft가 보고하는 브랜드를 poly/example로 바꿉니다. Minecraft 클래스를 참조하지 않습니다.

파일	내용
poly.mod.json	엔트리포인트 없음. replacesSystems로 제공자를 선언하고, 권한 system.provider.replace를 요청
ExampleBrandProvider	poly:game_brand 제공자

클라이언트 로그에 [Poly 모드 로더] poly:game_brand reported 'poly/example' to Minecraft (CLIENT)가 남습니다. 선언 방법은 poly.mod.json 스키마에 있습니다.

transform-demo-mod

poly.mod.json의 transforms와 accessWidenings로 Minecraft 클래스를 바꿉니다. 첫 규칙은 Java 코드 없이 선언만으로 동작하고, 둘째 규칙은 작은 훅 클래스 TickHooks를 씁니다.

| 규칙 | 대상 | 동작 | 하는 일 | |---|---|---| | transform_demo_mod:storage_format_name | LevelStorageSource.getName()Ljava/lang/String; | replace_returned_string_constant | 표시용 저장 형식 이름 "Anvil"을 "Anvil (Poly 모드 로더 transform demo)"로 바꿈 | | transform_demo_mod:tick_start_nanos | MinecraftServer.tickServer(Ljava/util/function/BooleanSupplier;)V | redirect_call, after: ["poly:server_tick_events"] | 첫 Util.getNanos() 호출을 TickHooks.tickStartNanos()로 바꿈. Poly 모드 로더 내장 시작 훅과 같은 메서드라 순서를 선언 | | 접근 확대 | MinecraftServer.tickCount:I | accessible | private 필드를 public으로 |

• 실패 정책은 disable_rule·skip이라 대상이 달라지면 그 항목만 꺼집니다.
• 권한은 internal.bytecode.transform, internal.callsite.intercept, internal.member.access입니다.
• minecraft는 ["26.2"]입니다. 특정 버전의 게임 코드에 기대므로 정확한 버전을 적습니다.

로그에는 다음이 남습니다. 두 번째 실행부터는 변환 캐시를 써서 from cache가 붙습니다.

• Transformed net/minecraft/world/level/storage/LevelStorageSource with [transform_demo_mod:storage_format_name]
• Transformed net/minecraft/server/MinecraftServer with [poly:server_brand, poly:server_tick_events, transform_demo_mod:tick_start_nanos, poly:server_stopping_event, poly:worldgen_features, access widening by transform_demo_mod]
• [transform_demo_mod] tickServer start time comes from the mod hook; MinecraftServer.tickCount is public: true

native-showcase-mod

Native API의 모든 영역을 한 모드에서 사용하는 예제로, Poly 모드 로더가 Native API를 실제 게임에서 검증할 때 기준으로 삼습니다. poly.mod.json은 "minecraft": ["26.*"]입니다.

클래스

클래스	영역	내용
NativeShowcaseMod	common 엔트리포인트	빛나는 블록 glow_block(밝기 12, 맞는 도구 필요, 사용하면 spark 지급), 아이템 spark, 음식 star_fruit, 명령어, 네트워크 채널, 접속 준비 교환, 이벤트, 월드 저장소, 설정 파일 showcase.properties, 모드 창작 탭 showcase, 다른 클래스의 선언 호출
MachineContent	블록 상태·블록 엔티티	플레이어를 향하고 사용하면 powered가 바뀌며 켜진 동안 틱을 세는 machine, 27칸 인벤토리 crate
AdvancedContent	심화 콘텐츠	색 속성과 상태별 밝기를 가진 lamp, 메뉴 배치와 진행 막대가 있는 grinder, 아이템 데이터 컴포넌트 charge를 쓰는 spark_wand, 투사체 spark_bolt, 발전 과제 트리거 used_wand
CreatureContent	몹과 게임플레이	스폰 알·자연 스폰·탈것이 있는 몹 golem_friend, 상태 효과 glowing_heart, 게임 규칙 golems_greet_players·spark_multiplier, 사운드 chime, 피해·죽음 이벤트
SeekGlowBlockGoal	AI 목표	6블록 안의 glow_block으로 걸어감
VisualContent	몹 모델	상자 모델과 키프레임 애니메이션이 있는 나는 몹 wisp, 파티클 sparkle
MovementContent	모양과 이동	반 칸 높이 블록 stone_step, 헤엄치는 몹 minnow, 관련 게임 테스트
WorldContent	월드 생성	바이옴 glow_meadow, native_showcase:terraces 차원이 쓰는 계단식 지형 생성기, 청크 로드 감시
CodeWorldgenContent	코드 월드 생성	배치 기능 boulder, native_showcase:waves 차원의 밀도 함수 waves, 구조물 shrine, 관련 게임 테스트
InteractionContent	이벤트 우선순위·상호작용 이벤트	BlockEvents.BREAK(높은 우선순위)·PLACE·PLACED와 InteractionEvents로 자신과 그 위에 있는 것을 지키는 warded_block, 각 이벤트가 동작을 취소하고 취소하지 않은 동작은 그대로 되는지 확인하는 게임 테스트 6개
LifecycleContent	생명주기 이벤트	서버·오버월드 생명주기 로그, PlayerEvents.COPY로 옮기는 엔티티 데이터의 리스폰 횟수, RESPAWNED, EntityEvents.JOINED_WORLD, 접속한 모의 플레이어를 쓰는 게임 테스트 2개
TagContent	태그	#native_showcase:warded(보호 블록 판정에 쓰임), #native_showcase:sparkly, #minecraft:mineable/pickaxe에 더한 보호 블록, 게임 테스트 2개
OperationsContent	데이터·동기화·운영	데이터 리로드 리스너, 엔티티 데이터 visits·golem_mood(버전 이전 포함), 클라이언트와 동기화하는 버전 있는 월드 저장소 world_info, 권한 노드 place·secret과 권한 제공자, 접속 검사
NativeShowcaseClient	client 엔트리포인트	키 바인딩, HUD 레이어, 셰이더 파이프라인 glow·pulse(텍스처·모드 유니폼), 월드 그리기 compass, grinder 블록 엔티티 그리기(상태별 램프 모델), 동적 텍스처 noise, 화면, 카메라 시점, 후처리 sepia, 클라이언트 이벤트, #native_showcase:sparkly 아이템의 "Sparkly" 툴팁 줄
ShowcaseScreen	모드 화면	인사 글, 이름 입력칸, 닫기 버튼
ShowcaseGameTests	게임 내 테스트	콘텐츠·월드·엔티티·명령어·데이터·권한 테스트

리소스는 src/main/resources/assets/native_showcase/(블록 상태, 모델, 텍스처, 이름, 셰이더, 후처리)와 src/main/resources/data/(전리품 테이블, 레시피, 태그, 차원 pocket·terraces·waves, 발전 과제, 피해 유형, 월드 생성 데이터)에 있습니다.

명령어, 키, 채널

종류	이름	동작
명령어	/showcase info	블록이 등록됐는지 알려 줌
명령어	/showcase add <a> <b>	두 정수의 합을 명령 결과값으로 돌려줌
명령어	/showcase place <pos>	그 위치에 glow_block을 놓음. 권한 노드 place(기본 수준 2) 필요
키 바인딩	show_info(기본 K)	액션 바에 Native Showcase: key binding works 표시
페이로드 채널	native_showcase:greetings	접속하면 서버가 환영 인사를 보내고, 클라이언트가 thanks로 답함
접속 준비 교환	native_showcase:handshake	월드에 들어가기 전에 서버가 클라이언트의 쇼케이스 버전을 묻고, 답이 없거나 showcase 로 시작하지 않으면 접속을 거절

게임 안에서 테스트

쇼케이스의 게임 내 테스트 52개는 월드 안에서 /test runmultiple native_showcase:*로 실행합니다. 내 모드의 테스트를 만들고 실행하는 방법은 게임 내 테스트에 있습니다.