CNPC Natural Spawner

DESCRIPTION

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

Command	Description
/cns gui	Opens the configuration screen
/cns reload	Reloads config/cnpc_natural_spawns.json after manual edits
/cns pack export <name> <tab> [clone]	Creates a transfer pack
/cns pack list	Lists available packs
/cns pack import <name>	Dry run: shows what would be added or overwritten, changes nothing
/cns pack import <name> confirm	Queues the pack to be applied the next time the world or server starts

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)

Setting	What it does	Default
Activa	Enables or disables this rule without deleting it	true
Clon	The clone to spawn, listed as tab:name. If no clones are found, you get two text fields (tab number and clone name) instead	,
Peso	Relative chance of being picked when several rules are valid. Example: 10 = rare, 100 = common	50
Grupo min / max	How many NPCs spawn together (1 to 16)	1 / 1
Max cerca	Maximum NPCs of this rule within the despawn distance of a player	4
Despawn lejos	Removes the NPC when no player is within the despawn distance. Turn off for quest or story NPCs	true

Conditions tab (per rule)

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

Setting	What it does	Example
Dimensiones	Allowed dimensions (full ids)	minecraft:overworld
Biomas / #tags	Allowed biomes or biome tags (tags start with #)	minecraft:plains, #minecraft:is_forest
Biomas prohibidos	Biomes where it must never spawn	minecraft:desert
Bloque suelo	Block it must stand on (ids or #tags)	minecraft:grass_block, #minecraft:sand
Y min / Y max	Height range	-64 / 320
Luz bloque min / max	Block light range (0 to 15)	0 / 15
Luz cielo min / max	Sky light range (0 to 15)	0 / 15
Hora	ANY, DAY or NIGHT	NIGHT
Clima	ANY, CLEAR, RAIN or THUNDER	ANY
Cielo	ANY, OPEN (sees the sky) or COVERED (caves, roofs)	OPEN

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

Setting	What it does	Default
Mod activo	Master switch for all natural spawning	true
Intervalo (ticks)	How often each player is evaluated (20 ticks = 1 second, minimum 20)	100
Intentos/ciclo	Position attempts per evaluation	3
Dist. min / max	Spawn ring around the player, in blocks	24 / 48
Max total cerca	Total NPCs from this mod allowed around one player	12
Dist. despawn	Radius used for caps and despawning	128

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 included. Factions referenced by the NPC, its dialogs or its quests are exported and merged by ID into the destination’s factions.dat. A faction with the same ID is overwritten, and factions.dat is part of the automatic backup. The dry run reports how many factions are new or corrected.
• 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, quests and the factions they reference. 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. Faction detection depends on the factions.dat layout, so check the export report.

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.