Entity 등록과 AttributeSupplier

Entity란?

Entity는 Minecraft 월드에 존재하는 모든 동적 객체의 기반입니다. 플레이어, 몹, 투사체, 아이템 드롭 — 모두 Entity 계층 구조에 속합니다. 이번 챕터에서는 커스텀 Mob 엔티티를 등록하고, 체력·속도·공격력 같은 속성을 안전하게 연결하는 방법을 다룹니다.

1단계 — ENTITY_TYPES DeferredRegister

엔티티 타입은 Registries.ENTITY_TYPE 레지스트리에 등록합니다. 아이템·블록과 동일한 DeferredRegister 패턴을 사용하되, 별도의 ModEntities 클래스로 분리하는 것을 권장합니다.

examplemod-template-26.1.2/src/main/java/com/example/examplemod/ModEntities.java

public class ModEntities {
 
    // 26.1: 엔티티 전용 특화 DeferredRegister.Entities (createEntities)
    public static final DeferredRegister.Entities ENTITY_TYPES =
            DeferredRegister.createEntities(ExampleMod.MODID);
 
    // 26.1: registerEntityType 가 빌더 UnaryOperator 를 받아 ResourceKey 로 build 까지 수행한다.
    //       MOB_ID_PREFIX / .build(...) 직접 호출은 제거됨.
    public static final Supplier<EntityType<RubyGolemEntity>> RUBY_GOLEM =
            ENTITY_TYPES.registerEntityType(
                    "ruby_golem",
                    RubyGolemEntity::new,
                    MobCategory.CREATURE,
                    builder -> builder
                            .sized(0.6f, 1.95f)          // width, height
                            .clientTrackingRange(80)
                            .updateInterval(3));
}

registerEntityType의 주요 인자:

등록 후 메인 클래스 생성자에서 ENTITY_TYPES.register(modEventBus)를 호출해야 합니다.

public ExampleMod(IEventBus modEventBus, ModContainer modContainer) {
    ModEntities.ENTITY_TYPES.register(modEventBus);
    // ... 다른 레지스터들
}

2단계 — MobCategory 선택

MobCategory는 엔티티가 월드에 자연 스폰될 때 사용하는 분류입니다. 적절한 카테고리를 선택해야 자연 스폰 캡(spawn cap)이 올바르게 적용됩니다.

RubyGolemEntity는 평화로운 크리처 계열이므로 CREATURE를 사용합니다.

3단계 — Entity 클래스 구현

examplemod-template-26.1.2/src/main/java/com/example/examplemod/entity/RubyGolemEntity.java

public class RubyGolemEntity extends PathfinderMob {
 
    public RubyGolemEntity(EntityType<? extends PathfinderMob> type, Level level) {
        super(type, level);
    }
 
    /**
     * Mob 속성 정의 — EntityAttributeCreationEvent에 넘길 Builder 반환.
     */
    public static AttributeSupplier.Builder createAttributes() {
        return Mob.createMobAttributes()
                .add(Attributes.MAX_HEALTH, 30.0)      // 하트 15개
                .add(Attributes.MOVEMENT_SPEED, 0.25)  // 일반 좀비 수준
                .add(Attributes.ATTACK_DAMAGE, 4.0)    // 심장 2개
                .add(Attributes.ARMOR, 2.0);           // 방어력 1포인트
    }
}

Mob.createMobAttributes()는 기본 속성 세트(MAX_HEALTH, MOVEMENT_SPEED 등)를 포함한 Builder를 반환합니다. 여기에 .add()를 체이닝해 원하는 속성 값을 추가하거나 덮어씁니다.

4단계 — EntityAttributeCreationEvent 등록

모든 Mob 엔티티는 이 이벤트에서 AttributeSupplier를 등록해야 합니다. 등록하지 않으면 /summon 또는 월드 스폰 시 NullPointerException이 발생해 게임이 크래시됩니다.

이 이벤트는 모드 이벤트 버스(mod bus) 에서 발생합니다.

examplemod-template-26.1.2/src/main/java/com/example/examplemod/entity/EntityAttributeHandler.java

@EventBusSubscriber(modid = "examplemod")
public class EntityAttributeHandler {
 
    @SubscribeEvent
    public static void onEntityAttributes(EntityAttributeCreationEvent event) {
        event.put(ModEntities.RUBY_GOLEM.get(), RubyGolemEntity.createAttributes().build());
    }
}

event.put(entityType, attributeMap)이 핵심입니다. createAttributes().build()로 AttributeSupplier를 완성해 전달합니다.

인게임 테스트 명령

엔티티를 등록한 뒤 인게임에서 직접 스폰해 확인합니다.

# 현재 위치에 RubyGolem 스폰
/summon examplemod:ruby_golem ~ ~ ~

# 스폰된 RubyGolem 전체 제거
/kill @e[type=examplemod:ruby_golem]

/summon 성공 시 히트박스(0.6×1.95)가 현재 위치에 생성되며, /kill 명령으로 제거할 수 있습니다.

안티패턴

⚠️ AttributeSupplier 누락 → /summon 시 크래시

// ❌ EntityAttributeCreationEvent에 등록 안 함
public static final Supplier<EntityType<RubyGolemEntity>> RUBY_GOLEM =
    ENTITY_TYPES.registerEntityType("ruby_golem", RubyGolemEntity::new, MobCategory.CREATURE, b -> b);
// 어디에도 event.put(RUBY_GOLEM.get(), createAttributes().build()); 없음

→ /summon examplemod:ruby_golem ~ ~ ~ 실행 시:

NullPointerException: Attribute not registered for entity type examplemod:ruby_golem

모든 Mob 하위 엔티티는 반드시 EntityAttributeCreationEvent에서 AttributeSupplier를 등록해야 합니다. Mob.createMobAttributes()를 사용하고, .build()로 완성한 값을 event.put()에 전달하세요.

체크리스트

• ModEntities.ENTITY_TYPES가 ExampleMod 생성자에서 modEventBus에 등록됨
• RubyGolemEntity.createAttributes() 메서드 존재 + AttributeSupplier.Builder 반환
• EntityAttributeCreationEvent 핸들러가 @EventBusSubscriber(modid = "examplemod")로 등록됨 (mod 버스 기본값)
• /summon examplemod:ruby_golem ~ ~ ~ 성공 — 크래시 없음

정리

• 엔티티 타입은 DeferredRegister.createEntities(MODID) + registerEntityType(...)으로 등록합니다.
• registerEntityType의 빌더 UnaryOperator로 히트박스·추적 범위·업데이트 간격을 설정합니다.
• MobCategory는 자연 스폰 분류를 결정합니다 (CREATURE/MONSTER/AMBIENT 등).
• createAttributes()로 체력·속도·공격력·방어력을 정의하고, EntityAttributeCreationEvent에 반드시 등록합니다.
• /summon examplemod:<id> ~ ~ ~로 인게임 테스트, /kill @e[type=examplemod:<id>]로 제거합니다.

다음 챕터에서는 등록된 엔티티에 AI Goal을 추가해 자율 행동을 구현하는 방법을 다룹니다.