NPCs¶

HTSkyBlock includes a flexible NPC system for spawning interactive characters with custom appearances and dialogue.

Overview¶

The NPC system allows you to: - Spawn NPC entities at specific locations - Clone player appearances onto NPCs - Set custom display names - Configure chat messages on interaction - Persist NPCs across server restarts

NPCs are stored in plugins/HTSkyBlock/npcs.json and automatically respawn when the server starts.

Commands¶

npcspawn¶

Spawn a test NPC entity at your location using a default model.

Usage: /npcspawn <name>

Permission: htskyblock.npc.spawn

Example:

/npcspawn TestNPC

What It Does: - Spawns an NPC 2 blocks in front of you - Uses a default humanoid model - Has a bounding box and is interactable - Shows the specified name above its head

Basic NPC

This command creates a simple NPC with a default appearance. For NPCs that look like specific players, use /npcclone instead.

npcclone¶

Spawn an NPC that clones a player's appearance.

Usage: /npcclone <name> <player>

Permission: htskyblock.npc.clone

Arguments: - <name> - Display name for the NPC - <player> - Username of online player to clone

Example:

/npcclone ShopKeeper Steve
/npcclone QuestGiver Alice

Requirements: - Target player must be online - Player's skin and cosmetics are copied - NPC is registered for persistence

What Gets Cloned: - Player skin (haircut, face, clothing) - Body proportions - Cosmetic items - Display name

Online Requirement

The player must be online when you run the command so their appearance data can be accessed. Once cloned, the NPC persists even if the player is offline.

npctest¶

Test command for exploring NPC and entity spawning capabilities. Outputs detailed API information to a file.

Usage: /npctest

Permission: htskyblock.npc.test

Output: plugins/HTSkyBlock/npc_api_dump.txt

This is a developer command for debugging and exploring the NPC system internals.

NPC Data Structure¶

NPCs are stored in plugins/HTSkyBlock/npcs.json:

{
  "npcs": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "displayName": "Shop Keeper",
      "worldName": "world_spawn",
      "position": {
        "x": 100.5,
        "y": 64.0,
        "z": 200.5
      },
      "rotation": {
        "x": 0.0,
        "y": 180.0,
        "z": 0.0
      },
      "playerSkin": {
        "haircut": "default_haircut",
        "face": "default_face",
        "overtop": "default_outfit"
      },
      "chatMessages": [
        "Welcome to my shop!",
        "Check out the latest items!",
        "Come back soon!"
      ]
    }
  ]
}

Fields¶

Field	Description
`uuid`	Unique identifier for the NPC
`displayName`	Name shown above NPC's head
`worldName`	World where NPC spawns
`position`	XYZ coordinates
`rotation`	Rotation angles (yaw, pitch, roll)
`playerSkin`	Skin data (if cloned from player)
`chatMessages`	Messages shown when players interact

Customizing NPCs¶

Adding Chat Messages¶

After spawning an NPC, you can manually edit npcs.json to add custom chat messages:

"chatMessages": [
  "Hello, traveler!",
  "I have quests for you.",
  "Come back when you're stronger!"
]

Messages are displayed in order when players interact with the NPC (right-click).

Changing Position¶

To move an NPC:

Note the NPC's UUID (shown when spawned)
Edit npcs.json
Update the position coordinates
Run /htskyblock reload or restart the server

Alternatively, delete the NPC from npcs.json and respawn it at the new location.

Changing Display Name¶

Edit the displayName field in npcs.json:

"displayName": "Village Elder"

Then reload the plugin or restart the server.

Removing NPCs¶

To remove an NPC:

Find the NPC's entry in npcs.json by display name or UUID
Delete the entire entry
Run /htskyblock reload or restart the server

The NPC will despawn immediately.

NPC Interactions¶

Built-in Interactions¶

By default, NPCs respond to: - Right-click - Displays a random chat message - Collision - Players can't walk through NPCs

Custom Interactions¶

To create custom NPC interactions, you can:

Edit chat messages in npcs.json
Use shop NPCs (spawn near shop UI trigger)
Create quest NPCs (integrate with quest system if available)

Shop NPCs

Spawn an NPC near your spawn point and configure chat messages that guide players to use /shop command.

Common Use Cases¶

Shop Keeper¶

# Clone a player's appearance
/npcclone "Shop Keeper" Steve

# Edit npcs.json to add messages:
"chatMessages": [
  "Welcome to the shop!",
  "Type /shop to browse items!",
  "Great deals today!"
]

Quest Giver¶

/npcclone "Quest Master" Alice

# Edit npcs.json:
"chatMessages": [
  "I have a quest for you!",
  "Gather 10 diamonds and return.",
  "Rewards await the brave!"
]

Greeter¶

/npcclone "Town Greeter" Bob

# Edit npcs.json:
"chatMessages": [
  "Welcome to our town!",
  "Visit /spawn for the main hub.",
  "Need help? Type /help!"
]

Informational Guide¶

/npcclone "Guide" Charlie

# Edit npcs.json:
"chatMessages": [
  "New player? Type /island to start!",
  "Use /shop to buy and sell items.",
  "Join our Discord for updates!"
]

Persistence¶

NPCs automatically persist across server restarts:

When an NPC is spawned with /npcclone, it's registered in npcs.json
On server startup, the NPC manager reads npcs.json
Each NPC is respawned in its configured world and position
If the world is not loaded, NPCs spawn when the world loads

World Loading

NPCs only spawn when their configured world is loaded. If using per-player worlds, NPCs in those worlds spawn when players visit.

Troubleshooting¶

NPC Not Spawning¶

Check npcs.json: - Verify the NPC entry exists - Ensure JSON formatting is valid - Check that worldName matches an existing world

Console Errors: - Look for errors during server startup - NPC spawn failures are logged to console

World Issues: - Ensure the NPC's world is loaded - NPCs won't spawn in unloaded dimensions

NPC Disappeared¶

Possible Causes: - Server crash may have lost unsaved changes - Manual deletion from npcs.json - World was deleted or reset

Recovery: - Check npcs.json for the entry - If missing, respawn the NPC with /npcclone - Ensure regular backups of npcs.json

Chat Messages Not Showing¶

Check Configuration: - Open npcs.json - Verify chatMessages array exists and has entries - Ensure messages are properly quoted strings

Reload Required: - Run /htskyblock reload after editing npcs.json - Or restart the server

"Player not online" Error¶

The /npcclone command requires the target player to be online:

Ensure the player is currently connected
Check spelling of the username
Try using the player's full username

Creating NPCs When Players Are Offline

If you need to create an NPC appearance when a player is offline, you can: 1. Wait for the player to come online 2. Use /npcspawn for a default appearance 3. Manually edit npcs.json with known skin data (advanced)

Advanced: Manual NPC Creation¶

For advanced users, you can manually add NPCs to npcs.json:

{
  "uuid": "generate-new-uuid-here",
  "displayName": "Custom NPC",
  "worldName": "world",
  "position": {"x": 0, "y": 64, "z": 0},
  "rotation": {"x": 0, "y": 0, "z": 0},
  "playerSkin": null,
  "chatMessages": ["Hello!", "I'm a custom NPC."]
}

Important: - Generate a unique UUID (use online UUID generator) - Ensure JSON syntax is valid - Test in a development environment first - Back up npcs.json before editing

Permissions¶

Command	Permission
/npcspawn	`htskyblock.npc.spawn`
/npcclone	`htskyblock.npc.clone`
/npctest	`htskyblock.npc.test`

Grant all NPC permissions:

permissions:
  htskyblock.npc.*

Configuration¶

NPC behavior can be configured in config.json:

{
  "npc": {
    "enabled": true,
    "interactionCooldown": 3,
    "maxNpcsPerWorld": 50
  }
}

Options:

Option	Description	Default
`enabled`	Enable/disable NPC system	`true`
`interactionCooldown`	Seconds between interactions	`3`
`maxNpcsPerWorld`	Maximum NPCs per world	`50`