CNPCExtended — Supercharge Your CustomNPCs

The missing toolkit for CustomNPCs. HTML browser GUIs, client-side queries, global script management, NPC data preloading, and a full server-to-client bridge -- all in one mod.

Minecraft 1.20.1 - Forge 47+ - Requires CustomNPCs Unofficial + MCEF

What Is This?

CNPCExtended adds everything CustomNPCs doesn't have out of the box. Query player settings from the server, open full HTML interfaces powered by an embedded Chromium browser, auto-deploy scripts and NPC data across all your worlds, and bridge your CNPC scripts with the client side -- no separate client mod needed.

This isn't just a GUI mod. It's a complete extension framework for CNPC.

See It In Action

Features

HTML GUI System

• Open HTML GUIs from any CNPC script -- NPC, Player, Block, or Item scripts
• Bidirectional events -- HTML sends events to the server, server pushes data back in real-time
• Real Minecraft item overlays -- render actual ItemStacks with enchant glint, durability bars, and hover tooltips on top of your HTML
• Full CSS/JS support -- animations, flexbox, grid, Canvas, SVG -- it's a real browser
• Target any player -- open GUIs on other players, not just the one who triggered the script

Client Bridge Queries

Read player client settings from the server -- no client mods needed beyond MCEF:

• Video settings -- FOV, render distance, graphics mode, GUI scale, framerate limit
• Sound settings -- master volume, music, weather, ambient, hostile, player volumes
• Keybinds -- all vanilla key mappings
• Resource packs -- list of active packs
• Screen info -- resolution, scaled width/height

Global Scripts and NPC Data (NEW in v1.1)

Pre-configure every new world automatically:

• Global player scripts -- place .js and .html files in a config folder, they auto-copy into every new world and register as CNPC player scripts
• Global NPC data -- pre-load clones, dialogs, quests, and linked NPCs from a template into every new world
• /cnpcext commands -- sync, force-sync, and check preload status in-game
• Forge config -- all features toggleable via cnpcextended-common.toml

Quick Example

NPC Script (server-side):

function interact(e) {
    var cnpcext = e.API.getIWorld(0).getTempdata().get("cnpcext")
    cnpcext.openHtmlGui(e, "shop.html", 0, 0, {
        shopName: "Adventurer's Shop",
        items: [{name: "Sword", price: 100}, {name: "Shield", price: 50}]
    })
}

function htmlGuiEvent(e) {
    if (e.eventName === "buy") {
        e.player.giveItem(e.data.get("itemId"), 1)
        e.bridge.sendToBrowser(e.player.getMCEntity(), "purchased", {success: true})
    }
}

Documentation

Full Documentation and API Reference

Covers installation, quick start guide, complete API reference, item overlays, client queries, event flow diagrams, and copy-paste examples.

Requirements

Security

• HTML files loaded from server's world folder only -- no external URLs
• Path traversal blocked -- scripts can't escape the scripts folder
• Event names validated with strict regex
• Client queries are read-only -- server cannot change client settings

Built for modpack creators, RPG server owners, and anyone who wants their NPCs to do more.