Node-based combat rules editorEdit NPC — general settings with live model previewNPC combat and targeting settingsNavigation and A* pathfinding settingsZone editor — defining named zonesNPC spawn listA selected zone outlined in the world
LunaNPC

LunaNPC turns Minecraft worlds into living places. Spawn and edit NPCs in-game, give them zones to roam, alliances and factions to honor, and combat behavior of your own design — no datapacks, no restarts.

Version0.1.0
Downloads18
Minecraft26.2

Overview

LunaNPC is a Fabric-first NPC framework for building and controlling custom NPCs. It supports combat, factions, spawning, trading, dialog, and custom models straight from in-game menus, and developers get the exact same features through a public API.

Dependencies

Feature overview

Versions

latest v0.1.0
v0.1.0currentJul 23, 2026 · 1.4 MB26.2
Download

Developer API

Java · Fabric
package net.lunacore.lunanpc.examples;

import net.minecraft.server.MinecraftServer;
import net.lunacore.luna_npc.api.LunaNpcApi;
import net.lunacore.luna_npc.api.NpcAttackSettings;
import net.lunacore.luna_npc.api.NpcDefinition;
import net.lunacore.luna_npc.api.NpcReactionSettings;
import net.lunacore.luna_npc.api.NpcRegistry;
import net.lunacore.luna_npc.api.SurfaceMode;

// A heavy melee construct: a metallic iron golem that natural-spawns at villages, hits hard but slowly,
// and drops scrap. Shows structure spawning, a weaponless melee attack, and per-item chance drops.
public final class SteelGolemExample {

    private SteelGolemExample() {
    }

    public static void build(MinecraftServer server) {
        NpcRegistry npcs = LunaNpcApi.npcs(server);
        NpcDefinition golem = npcs.getOrCreate("SteelGolem");

        golem.setHealth(200);
        golem.setCategory("golems");
        golem.setAllianceId("golems");
        golem.setModelSettings(golem.modelSettings().withModel("iron_golem", "iron_golem_movie"));

        golem.setHurtSoundId("minecraft:entity.iron_golem.hurt");
        golem.setDieSoundId("minecraft:entity.iron_golem.death");
        golem.setCombatCloseSoundId("minecraft:entity.iron_golem.attack");

        // 20 damage, 3-block reach, one swing every 5 seconds — no weapon item, it strikes bare-handed.
        golem.setCombat(golem.combat().withMelee(NpcAttackSettings.melee(20.0F, 3.0F).withInterval(5.0F)));

        // Walks and charges at the same 2 blocks/second.
        golem.setMovement(golem.movement().withWalkSpeed(2.0F).withRunSpeed(2.0F));

        golem.setTraits(golem.traits().asCreature()
                .withReaction(NpcReactionSettings.defaults().withMode(NpcReactionSettings.AGGRESSIVE)));

        // Spawns at any village, at the surface, with a 5% spawn chance.
        golem.setSpawn(golem.spawn()
                .withStructureChance("minecraft:village_plains", 5)
                .withStructureChance("minecraft:village_desert", 5)
                .withStructureChance("minecraft:village_savanna", 5)
                .withStructureChance("minecraft:village_snowy", 5)
                .withStructureChance("minecraft:village_taiga", 5)
                .withSurfaceMode(SurfaceMode.SURFACE_ONLY));

        // Each drop rolls its own chance on death. Drops are one item per slot (no stack counts), so
        // repeated slots stand in for "a few" stone / iron.
        golem.setDropSettings(golem.dropSettings()
                .withDrop(0, "minecraft:dandelion", 8.0F)
                .withDrop(1, "minecraft:poppy", 5.0F)
                .withDrop(2, "minecraft:cornflower", 3.0F)
                .withDrop(3, "minecraft:oxeye_daisy", 2.0F)
                .withDrop(4, "minecraft:flint_and_steel", 5.0F)
                .withDrop(5, "minecraft:stone", 10.0F)
                .withDrop(6, "minecraft:stone", 10.0F)
                .withDrop(7, "minecraft:stone", 10.0F)
                .withDrop(8, "minecraft:iron_ingot", 5.0F)
                .withDrop(9, "minecraft:iron_ingot", 5.0F)
                .withDrop(10, "minecraft:iron_ingot", 5.0F)
                .withDrop(11, "minecraft:iron_ingot", 5.0F));
    }
}

Full type reference

Every type, function and enum, browsable at api.lunacore.dev/LunaNPC.

Open API