Custom NPCs Mod Wiki

Custom NPCs is a comprehensive toolset designed for creative players and adventure map creators to populate their Minecraft worlds with interactive characters. The mod provides an extensive suite of editors to define NPC appearance, combat stats, AI behavior, and complex RPG elements like factions, branching dialog trees, and multi-stage quests. Whether building a bustling fantasy city or a scripted dungeon crawl, Custom NPCs offers the flexibility to make a world feel reactive and alive.

Key Features

• Deep Customization: Modify every aspect of an NPC, from their model size and skin to their resistance against specific damage types.
• RPG Systems: Built-in systems for player factions, mail, banking, and global quest tracking.
• Advanced AI: Define complex movement patterns, tactical combat behaviors, and interaction triggers.
• Scripting Engine: Support for JavaScript (ECMAScript) and other languages to create custom logic for NPCs, items, and blocks.

The mod introduces several essential tools used to create and manipulate NPCs and the world around them. Most of these tools are only accessible in Creative Mode or by players with operator permissions.

When editing an NPC with the NPC Wand, the interface is divided into several tabs, each controlling a specific aspect of the character.

Display

This tab controls the visual identity of the NPC.

• Skin: Choose from local files, URLs, or player names. Custom skins should be placed in .minecraft/customnpcs/assets/customnpcs/textures.
• Model: Change the NPC's entity model (e.g., Human, Orc, Naga, or even vanilla mobs like Spiders).
• Scale: Adjust the size of the NPC (0.1 to 5.0). Individual parts like the head, body, and limbs can be scaled independently.
• Overlay: Add capes, glowing eyes, or additional texture layers.

Stats

Defines the NPC's physical attributes and combat capabilities.

• Health: Set maximum HP and regeneration rates (combat and non-combat).
• Melee/Ranged: Configure attack strength, speed, knockback, and range. For ranged NPCs, an item must be placed in the 'Shoot' slot in the Inventory tab.
• Resistances: Set percentage-based protection against Melee, Arrows, Explosions, and Knockback.

AI (Artificial Intelligence)

Determines how the NPC interacts with the environment.

• Movement: Options include Standing, Wandering, or Following a Path. You can set the walking speed and whether the NPC can swim or open doors.
• Tactical: Defines combat behavior, such as 'Hit & Run', 'Ambush', 'Stalk', or 'Tactical Retreat'.
• Interaction: Controls if the NPC looks at the player, retreats when attacked, or seeks shelter at night.

Roles and Jobs are the functional 'brains' of an NPC. Roles usually require player interaction, while Jobs are passive behaviors performed automatically.

NPC Roles

• Trader: Allows the NPC to function as a shopkeeper. You can set up to 18 trade recipes.
• Follower: Enables the NPC to be hired by players for a set price and duration.
• Bank: Provides access to a global or local storage system (similar to an Ender Chest).
• Transporter: Acts as a fast-travel node. Players must discover transporters to unlock them in the travel menu.
• Mailman: Allows players to send and receive mail through the NPC.
• Companion: A more advanced follower system with leveling, talent trees, and specific combat roles.
• Puppet: Used for posing NPCs for dioramas or cinematics.

NPC Jobs

• Bard: Plays background music or specific sound files when players are nearby.
• Healer: Automatically heals nearby players or friendly NPCs.
• Guard: Attacks specific factions or monster types within a defined range.
• Item Giver: Hands out items to players based on timers or quest status.
• Spawner: Spawns other entities or clones when the NPC dies or enters combat.
• Conversation: Triggers automated chat messages between multiple NPCs.
• Chunk Loader: Keeps the surrounding chunks loaded even when no players are present.

Factions

Factions manage the relationships between NPCs and players. By default, there are three factions: Friendly, Neutral, and Hostile.

• Points: Players gain or lose points with factions by completing quests or killing NPCs.
• Aggro: NPCs will automatically attack players if their faction standing is too low.

Dialog System

The mod features a branching dialog editor. Dialogs are organized into categories and can be linked together to create complex conversations.

• Dialog Options: Up to 6 choices per dialog screen. Options can lead to other dialogs, close the menu, start a quest, or execute a command.
• Availability: Dialogs can be restricted based on faction standing, quest completion, or player level.

Quest System

Quests are the primary way to drive progression. They are managed in the Global tab and assigned to NPCs or Dialogs.

• Quest Types:
  • Item Quest: Requires the player to collect specific items.
  • Kill Quest: Requires the player to kill a certain number of specific entities or NPCs.
  • Dialog Quest: Completed by speaking to a specific NPC.
  • Location Quest: Completed by reaching a specific coordinate (marked by a Waypoint block).
  • Manual Quest: A custom quest type that must be completed via scripting or commands.

Custom NPCs adds various blocks and items to support RPG world-building.

Functional Blocks

• Carpentry Bench: A 4x4 crafting table used for custom recipes defined in the Global menu.
• Mailbox: A block that allows players to access the mail system without an NPC.
• Waypoint Block: Used for Location Quests; triggers completion when a player stands near it.
• Redstone Block: A programmable block that emits a redstone signal based on player proximity or quest status.
• Copy/Builder Block: Used to save and paste structures or schematics within the world.

Items and Equipment

The mod includes a massive variety of aesthetic and functional equipment, including:

• Weapons: Daggers, Battleaxes, Maces, Glaives, Scythes, Spears, and Tridents. These generally function like swords but with different reach and speed attributes.
• Ranged: Muskets, Pistols, and Crossbows. These require specific ammunition (Bullets/Bolts) to function.
• Staves: Elemental staves that consume 'Mana' items to fire magical projectiles.
• Currency: Coins (Bronze, Silver, Gold, Emerald) used for trading and quest rewards.

Scripting API

For advanced users, the mod includes a powerful scripting API. Scripts can be attached to NPCs, Items, Blocks, or the Forge event bus.

• Languages: JavaScript (via Nashorn/GraalVM) is the default. Other languages like Python or Lua can be added via external libraries.
• Hooks: Common hooks include init (when spawned), tick (every 10 ticks), interact (when clicked), damaged, and died.

Commands

Commands are prefixed with /npc or /noppes.

• /npc create [name] - Spawns a new NPC.
• /npc home - Sets the NPC's home position to your current location.
• /noppes config - Opens the mod configuration menu.
• /noppes clone spawn [name] [tab] - Spawns a saved clone at your location.
• /noppes quest finish [player] [id] - Force-completes a quest for a player.