KubeJS Easy NPC

This is an addon exposing Easy NPC’s public API to KubeJS scripts. This mod includes a preset NPC that is stored at data/kubejs_easynpc/easy_npc/preset/guide.npc.snbt, which is used in the following example.

Quick Start Example:

// Copy to kubejs/server_scripts/easynpc.js, then join/rejoin the world.
// A persistent per-player UUID prevents creating another guide on each login.
PlayerEvents.loggedIn(event => {
    let player = event.player
    if (player.persistentData.contains('kjsenGuide')) return
    let npc = EasyNPC.spawn(player.serverLevel(),
        'kubejs_easynpc:easy_npc/preset/guide.npc.snbt',
        player.x + 2, player.y, player.z,
        EasyNPC.spawnOptions().type('data').owner(player).identifier('example:guide'))
    player.persistentData.putString('kjsenGuide', String(npc.uuid))
})

EasyNPCEvents.scriptAction(event => {
    let player = event.player
    if (player == null) return // Some actions have no initiating player.
    switch (String(event.details.key)) {
        case 'example:greet':
            event.npc.getActions().getMessage().sendTo(player, 'This message came from KubeJS.')
            let visits = event.npc.getActions().getState().get('example:visits')
            event.npc.getActions().getState().setNumber('example:visits', (visits == null ? 0 : visits.asNumber()) + 1)
            break
        case 'example:follow':
            event.npc.getObjectives().add('FOLLOW_OWNER')
            break
        case 'example:stop':
            event.npc.getObjectives().remove('FOLLOW_OWNER')
            break
    }
})

EasyNPCEvents.stateChanged(event => {
    console.info(`[EasyNPC] ${event.npc.uuid}: ${event.details.stateId} changed`)
})

For a more sophisticated example, check this.

NPCHandle

NPCHandle is a KubeJS container to call various methods involving the NPC entity.

Methods to construct or query

Methods to respawn, despawn or delete

Methods to access handlers

KubeJS Server Events

The following events should be used in server_scripts. They are only used to notify occurrence and are not cancellable.

KubeJS Startup Event

EasyNPCStartupEvents.registerObjective registers custom Easy NPC AI objectives from KubeJS scripts. The script should be placed in startup_scripts. Restart the game or server after changing registrations.

Event methods

Basic registration

// kubejs/startup_scripts/custom_objectives.js

EasyNPCStartupEvents.registerObjective(event => {
    event.register('example:periodic_greeting', (npc, data) => {
        let ticks = 0

        return ScriptGoalBuilder.create()
            .canUse(() => npc.isLoaded())
            .canContinueToUse(() => npc.isLoaded())
            .requiresUpdateEveryTick(() => true)
            .tick(() => {
                ticks++
                if (ticks % 200 != 0) return

                npc.getActions().getMessage().showBubble('Hello!')
            })
            .build()
    })
})

This goal displays a speech bubble every 200 ticks (10 seconds) while running.

Configured registration

Use ScriptObjectiveBuilder to configure priority, compatibility, travel classification or a target goal.

// kubejs/startup_scripts/custom_objectives.js

EasyNPCStartupEvents.registerObjective(event => {
    event.registerConfigured(
        'example:periodic_greeting',
        ScriptObjectiveBuilder.create()
            .defaultPriority(5)
            .hasTravelObjective(false)
            .isCompatible(npc => npc.getDialog().isSupported())
            .goal((npc, data) => {
                let ticks = 0

                return ScriptGoalBuilder.create()
                    .canUse(() => npc.isLoaded())
                    .canContinueToUse(() => npc.isLoaded())
                    .requiresUpdateEveryTick(() => true)
                    .tick(() => {
                        ticks++
                        if (ticks % 200 != 0) return

                        npc.getActions().getMessage().showBubble('Hello!')
                    })
                    .build()
            })
    )
})

ScriptGoalBuilder methods

ScriptGoalBuilder creates a Minecraft Goal using JavaScript callbacks.

Adding the objective to an NPC

After registration, add an entry to an NPC from a server-side callback:

// Call this function with a loaded NPCHandle.
function enablePeriodicGreeting(npc) {
    let objectives = npc.getObjectives()
    let id = 'example:periodic_greeting'

    if (!objectives.has(id)) {
        objectives.addEntry(objectives.createCustomEntry(id))
    }
}

You can then query, reprioritize or remove it:

npc.getObjectives().has('example:periodic_greeting')
npc.getObjectives().setPriority('example:periodic_greeting', 3)
npc.getObjectives().remove('example:periodic_greeting')

EasyNPC Binding

EasyNPC is a binding available in server_scripts. It provides methods for spawning and finding NPCs, working with presets, and creating action and condition data.

Methods to spawn or find NPCs

Spawning throws an exception if the preset cannot be used or the requested UUID is already registered. Use the existing handle’s restore or revive methods for an existing NPC.

Spawn options

EasyNPC.spawnOptions() creates a reusable options builder.

Methods to create actions

Script action keys and arguments must be non-empty tokens without whitespace.

Methods to create conditions

Methods to create action contexts

An ActionContext contains information about how an action was triggered, including its initiator and audience.

Methods to query or delete presets

listPresets() and presetExists() reject the client-local LOCAL source.

A preset missing from listPresets() is not necessarily absent: it may be hidden from listings.

DATA preset IDs

For a file at:

data/example/easy_npc/preset/merchant.npc.snbt

Use:

example:easy_npc/preset/merchant.npc.snbt

WORLD preset IDs

WORLD file operations require this format:

easy_npc:preset/<path>.nbt
easy_npc:preset/<path>.snbt