NicolaiNPC

Nicolai is a custom NPC designed to behave similarly to a wandering trader while having his own unique personality and mechanics. Is Nicolai better than the wandering trader? Well, he doesn't own any llamas so maybe...

Features:

- Custom villager-style NPC
- Configurable variants
- Configurable trades
- Natural spawning
- Custom spawn conditions
- Unique abilities
- Custom animations
- Custom sounds
- Custom death drops
- Multiplayer compatible
- Supports modded items in trades
- In-game configuration reloading

Nicolai can have multiple configurable variants, each with their own appearance, spawning conditions, and trade pool.

Variants can control:

- Appearance
- Apron color
- Spawn conditions
- Lifetime
- Trade pools

Variants can be created and modified through JSON configuration files, allowing modpacks to easily customize Nicolai by copying the default.json and adjusting the values.

Look under 'Configuration' for more details.

Nicolai can naturally spawn throughout the world according to configurable spawning rules.

- Configurable spawn chance
- Chance increases after unsuccessful spawn attempts
- Configurable maximum number of Nicolais per player
- Spawn attempts become more frequent with additional players
- Supports different dimensions
- Configurable biome, dimension, structure, and other spawn conditions
- Configurable Nicolai lifetime

Nicolai uses Minecraft's standard trading system, allowing trades to support both vanilla and modded items.

Each variant can have its own pool of possible trades, with configurable:

- Trade selection
- Trade weights
- Number of trades offered
- Duplicate trade prevention
- Item quantities
- Maximum trade uses
- Primary and secondary costs

NicolaiNPC provides several commands for testing and configuration:

- `/nicolaimod reload` — Reloads Nicolai configuration
- `/nicolaimod list` — Lists available variants
- `/nicolaimod summon ` — Summons a specific variant
- `/nicolaimod getodds` — Displays natural spawn probabilities at player location
- `/nicolaimod dospawnevent` — Forces a natural spawn attempt
- `/nicolaimod dospawneventhere` — Forces a natural spawn attempt at player location

Variant Configuration Guide:

NicolaiNPC is designed to be highly configurable. Each JSON file placed in:

config/nicolainpc/variants/

defines one Nicolai variant.

The default configuration is automatically created as:

config/nicolainpc/variants/default.json

You can create additional variants by copying the default file and changing its values.

Each variant has five main sections:

- `id` — The unique identifier for the variant
- `appearance` — Controls the variant's appearance
- `spawn` — Controls natural spawning and variant conditions
- `conditions` — Controls the possible spawn locations
- `trades` — Controls the variant's possible trades

Please refer to default.json example to see the general structure

a null value ignores the restriction. AKA anything goes for that stipulation.

-----------------------------------------------------------------------------

"id": "insert Id here"
All Nicolai variants need to have a unique id. The id will populate on their nametag whenever they spawn. So a 'farmer' id will result in a 'farmer nicolai' spawning.

-----------------------------------------------------------------------------

"apron_color": "insert hexcode here"
You can only control apron color by providing a hexcode. The default is #000000, which creates a black apron.

-----------------------------------------------------------------------------

"enabled": insert true/false
With this, you can disable a variant without deleting the json file.

"bucket": "insert common/rare/exotic"
There are three buckets. When a spawn is triggered, it randomly rolls a bucket before selecting a variant. The names should be relatively self explanatory. Put common variants in the common bucket, etc.

"bucketweight": insert any number higher than 1
This determines odds for a certain variant being selected from within a single bucket. A bucketweight of 10 is 5 times more likely to be chosen than a bucketweight of 2. This only affects selections from variants within the same bucket.

"lifetime": insert tick counter
The lifetime determines how long a Nicolai will last before despawning. The default is 48000. That is two minecraft days and the same amount of time that a wandering villager will last

-----------------------------------------------------------------------------

"dimensions": [insert dimension values]
This determines what dimensions the variant can spawn in. A potential value could be ["minecraft:overworld", "minecraft:the_nether"]

"biomes": [insert biome values]
This determines what biomes the variant can spawn in. A potential value could be ["minecraft:plains", "minecraft:forest"]

"structures": [[insert structure, insert block distance]]
This determines how close to a structure a variant needs to be in order to spawn. When multiple structures are listed, only one needs to be within range to fullfill this requirement. It is reccomended to place less restrictive structures/ranges first. A potential value could be [["minecraft:village_plains", 64], ["minecraft:village_desert", 32]]

"minY": insert lowest possible height at spawn location
This determines the lowest range of spawn height. A value of 30 will prevent this variant from spawning on Y level 29 or below. A potential value could be -30

"maxY": insert highest possible height at spawn location
This determines the highest range of spawn height. a value of 30 will prevent this variant from spawning on Y level 31 or above. A potential value could be 52.

"minLight": insert lowest possible light at spawn location
This determines the lowest amount of light accepted at a spawn location. A value of 3 will prevent this variant from spawning at light level 2 or below. A potential value could be 7.

"maxLight": insert highest possible light at spawn location
This determines the highest amount of light accepted at a spawn location. a value of 5 will prevent this variant from spawning at light level 6 or above. A potential value might be 10.

"time": [insert start of time range, insert end of time range]
This determines the time range when this variant can spawn. A full day is 24000 ticks. For reference, day is 1000, noon is 6000, night is 13000, midnight is 18000, sunrise is 23000. To spawn this variant between night and noon the next day, this value is needed: [13000, 6000] The reverse, [6000, 13000] spawns the variant only between noon and sundown.

"weather": [insert weather here]
This determines what kind of weather is required for the variant to spawn. Please note that thunder and rain are different weather. If you want a variant to spawn during both, include both. A potential value might be ["clear", "rain"]

-----------------------------------------------------------------------------

"count": insert number of trades here
This determines how many trades this variant will have. If you set this to 7 and there are only 7 possible trades in the pool, then all 7 will be selected every time nicolai spawns. If there are 14 in the pool, 7 will be randomly selected.

"allow_duplicates": insert true/false
This determines whether the same trade can be represented several times by a variant. If it is set to true and the trade count is set to 7, it's theoretically possible for the same trade to be selected 7 times in a row even if there are other trades in the pool.

-----------------------------------------------------------------------------

Trade Pool structure:

"weight": insert number greater than 0
This determines how likely a trade is to be selected from the trade pool when a variant is spawned. A weight of 10 is twice as likely as a weight of 5 and half as likely as a weight of 20

"cost": [insert item to pay, [lower range amount, higher range amount]]
This determines what is paid in the first slot. This cannot be empty as per minecraft trade logic. A possible value could be ["minecraft:emerald", [1, 3]]. But another valid entry could be ["minecraft:emerald", 2] if you don't want a range for the ammount.

"cost2": [insert item to pay, [lower range amount, higher range amount]]
Same as the the regular cost, but it's for the second slot. This can be set to null for no secondary cost.

"result": [insert item to gain, [lower range amount, higher range amount]]
This determines what is gained from a trade. This cannot be empty as per minecraft trade logic.

"max_uses": insert number higher than 0
This determines how many times a trade can be completed by a player until it is greyed out. Set this to null for infinite trades.

{
   "id": "default",

   "appearance": {
     "apron_color": "#000000"
   },

   "spawn": {
     "enabled": true,
     "bucket": "common",
     "bucketWeight": 1,
     "lifetime": 48000,

     "conditions": {

       "dimensions": null,
       "biomes": null,
       "structures": null,
       "minY": null,
       "maxY": null,
       "minLight": null,
       "maxLight": null,
       "time": null,
       "weather": null

     }
   },

   "trades": {
     "count": 3,
     "allow_duplicates": false,

     "pool": [

       {
         "weight": 10,
         "cost": ["minecraft:emerald", [1, 3]],
         "cost2": null,
         "result": ["minecraft:bread", [8, 15]],
         "max_uses": 3
       },

       {
         "weight": 10,
         "cost": ["minecraft:emerald", [3, 6]],
         "cost2": null,
         "result": ["minecraft:cooked_beef", [9, 18]],
         "max_uses": 3
       },

       {
         "weight": 10,
         "cost": ["minecraft:emerald", [5, 8]],
         "cost2": null,
         "result": ["minecraft:golden_carrot", [10, 20]],
         "max_uses": 3
       }

     ]
   }
 }