CNPC Natural Spawner

CNPC Natural Spawner

Make your CustomNPCs clones spawn naturally in the world, and move your NPCs with their dialogs and quests between worlds, all from inside the game.

CustomNPCs lets you build amazing NPCs, bandits, villagers, bosses and wildlife, but they only appear where you place them. CNPC Natural Spawner adds two tools on top of CustomNPCs:

1. Natural spawning: your saved clones spawn like vanilla mobs, in the biomes, dimensions, light levels, times of day and weather you choose.
2. Transfer packs: export a clone together with every dialog and quest (rewards included) it depends on, and import it into another world or server. Every spawned NPC is a full copy of your saved clone, so skin, model, equipment, drops, dialogs, quests, factions and scripts all work exactly as you set them up.

Requirements

• Minecraft 1.21.1
• NeoForge 21.1.x
• CustomNPCs Unofficial (NeoForge 1.21.1)
• Must be installed on both server and clients

Features

Natural spawning

• Spawn any saved CustomNPCs clone naturally
• Unlimited spawn rules, each with its own conditions
• Weighted random selection between valid rules
• Group spawning (min/max group size)
• Filter by dimension, biome, biome tag, floor block, height, light, time, weather and sky exposure
• Population caps per rule and per player, plus automatic despawn when players leave
• Full in-game GUI, no restart needed, changes apply instantly
• Plain JSON config for manual editing and sharing Transfer packs
• Export a clone with all its linked dialogs and quests, rewards included
• Dry run before importing, so you see exactly what will change
• Automatic backup before anything is written to a world
• Works between singleplayer worlds and servers Safety
• Only operators can use commands and the GUI
• All values are validated server-side

Quick start: natural spawning

1. Create and save a clone with CustomNPCs (a clone is created with the Cloner item).
2. Run /cns gui (requires operator permission level 2).
3. Click New, then in the General tab pick your clone from the Clone selector.
4. In the Conditions tab set where it can spawn (for example, minecraft:plains in Biomes).
5. Click Save. The rule is live immediately.

Commands

All commands require operator permission level 2.

Configuration guide

The GUI has three tabs. The left column lists your rules. Use Nueva (New), Dup (duplicate) and Borrar (delete) to manage them, and the arrows to scroll. Long tabs are split into pages with the < and > buttons at the bottom. Click Guardar (Save) to apply.

General tab (per rule)

Conditions tab (per rule)

Leave any list empty to mean "anywhere / any". Lists are comma separated.

Common mistake: setting light max to 0 means "total darkness only", so the rule will almost never spawn on the surface. For "any light" use 0 to 15. Also remember dimension ids need the namespace: minecraft:overworld, not overworld.

Global tab

Example setups

Bandits on the plains, regularly

• Biomes: minecraft:plains, Dimension: minecraft:overworld
• Light: 0 to 15 for both block and sky
• Weight 100, group 1 to 3, max nearby 6
• Global interval 40 to 100 ticks Rare night wanderer in forests
• Biomes: #minecraft:is_forest, Time: NIGHT, Sky: OPEN
• Weight 10, group 1, max nearby 1 Cave dwellers
• Sky: COVERED, Y max 40, Luz cielo max 0
• Weight 40, group 2 to 4

Transfer packs: moving NPCs between worlds

When you move a clone to another world, its dialogs, quests and rewards normally stay behind, because the clone only stores numeric IDs that point to data in the world folder. Packs carry that data along.

Step by step

In the source world (where the NPC already works):

/cns pack export juan_pack 1 Juan

This takes the clone Juan from clone tab 1 and creates config/cnpc_spawner/packs/juan_pack.zip. The pack contains the clone plus every dialog and quest it links to, following the whole chain (quest to dialog to next quest, and so on). Quest rewards travel inside the quest. Leave out the clone name to export the whole tab.

In the destination world:

/cns pack import juan_pack

This is a dry run. It lists how many files are new, how many are corrections that will overwrite existing files, and how many are identical. Nothing is changed.

/cns pack import juan_pack confirm

This queues the pack. It is applied when you close and reopen the world (or restart the server), right before CustomNPCs loads its data.

• Singleplayer: the config folder is shared by every world of the same instance, so there is nothing to copy.
• Servers: upload the .zip to the server's config/cnpc_spawner/packs/ folder.

What you should know

• IDs are preserved, not reassigned. If the destination already has a dialog or quest with the same ID, the pack's version overwrites it and is treated as a correction. If the same ID exists in a different category folder, that old file is removed and replaced. Other NPCs in the destination that use those IDs will start showing the pack's content, so always read the dry run first.
• Automatic backup. Before anything is written, the affected folders are saved to <world>/cnpc_spawner_backups/, so anything overwritten can be restored.
• Factions are not copied. The export tells you which faction IDs the NPC uses so you can create them in the destination with the same IDs.
• Detection is automatic. References are found by scanning the files for dialog and quest IDs. If the export reports zero dialogs and zero quests for an NPC that has them, send the reported file name examples with your bug report.
• Packs only contain clones, dialogs and quests. They never touch other world data.

Manual configuration

Rules are stored in config/cnpc_natural_spawns.json on the server. You can edit it by hand and run /cns reload. Invalid or out of range values are corrected automatically on load.

Server notes

• All spawning happens on the server; players only see the NPCs through CustomNPCs itself.
• The clone list in the GUI comes from the server world (<world>/customnpcs/clones/).
• Only operators (permission level 2) can open the GUI or use pack commands, and the server re-checks permissions and validates every saved value.
• To lower server load, raise the interval and lower the attempts per cycle.
• Spawned NPCs are tagged and saved with the world, so they persist across restarts until despawned by their rule.

Known limitations

• Does not yet respect the doMobSpawning gamerule or Peaceful difficulty.
• No integration with claim or protection mods.
• Packs apply on world or server restart, not instantly.
• Packs do not remap IDs and do not include factions.

Credits

• Noppes, creator of the original CustomNPCs mod. This mod would not exist without his work.
• Goodbird, author of CustomNPCs Unofficial, the port this mod is built on. CNPC Natural Spawner is an unofficial addon and is not affiliated with or endorsed by Noppes or the CustomNPCs Unofficial team. Please support the original authors.

Feedback

Discord Server: https://discord.gg/krAeCzEjvT

Found a bug or want a feature? Open an issue on the project page and include your latest.log and your cnpc_natural_spawns.json.