Home

Custom NPCs

CustomNpcs is a plugin that allows you to add custom NPCs using Lua, allowing for more flexibility than ever before.

Making your first custom NPC

To make your first custom NPC, you'll have to create the npcs directory and create a file called npcs.json. You should then copy and paste the following:

[
  {
    "Name": "example",
    "LuaPath": null,
    "BaseType": 1,
    "BaseOverride": {
      "AiStyle": null,
      "BuffImmunities": null,
      "Defense": null,
      "HasNoCollision": null,
      "HasNoGravity": null,
      "IsBoss": null,
      "IsImmortal": null,
      "IsImmuneToLava": null,
      "IStrapImmune": null,
      "KnockbackMultiplier": null,
      "MaxHp": 1000,
      "Name": "Test NPC",
      "NpcSlots": null,
      "Value": null
    },
    "Loot": {
      "TallyKills": false,
      "IsOverride": true,
      "Entries": [
        {
          "Name": "S.D.M.G.",
          "MinStackSize": 1,
          "MaxStackSize": 1,
          "Prefix": -1,
          "Chance": 0.25
        }
      ]
    },
    "Spawning": {
      "ShouldSpawn": false,
      "ShouldReplace": false,
      "SpawnRateOverride": 20,
    }
  }
]

To add more custom NPCs, all you have to do is add another JSON entry like that. We'll go over all the fields:

• Name: The internal name of the custom NPC. This is what you use if you want to spawn the custom NPC with /csm, or if you want to spawn the custom NPC in code.
• LuaPath: An optional path to a Lua file that provides extra functionality to the custom NPC. If you are simply replacing stats, this is not necessary.
• BaseType: The internal ID of the normal NPC that you are basing it off of. Check here for a list of such IDs.
• BaseOverride: Handles optional overrides for the base normal NPC:
  • AiStyle: The AI style. If this is not null, then the custom NPC will be updated extremely frequently and may cause lag.
  • BuffImmunities: An array of buff immunities that the NPC has. If this is not null, then the custom NPC will be updated extremely frequently and may cause lag.
  • Defense: The defense. If this is not null, then the custom NPC will be updated whenever it is hit, which may cause slight lag.
  • HasNoCollision: Whether or not the custom NPC has collision with tiles. If this is not null, then the custom NPC will be updated extremely frequently and may cause lag.
  • HasNoGravity: Whether or not the custom NPC has gravity. If this is not null, then the custom NPC will be updated extremely frequently and may cause lag.
  • IsBoss: Whether or not this custom NPC is a boss. NOTE: If this is set to true, then the custom NPC's overriden name may not be used properly.
  • IsImmortal: Whether or not the custom NPC is immortal. If this is true, then the custom NPC will be updated whenever it is hit, which may cause slight lag.
  • IsImmuneToLava: Whether or not the custom NPC is immune to lava. If this is not null, then the custom NPC will be updated extremely frequently and may cause lag.
  • KnockbackMultiplier: How much to multiply knockback by. If this is not null, then the custom NPC will be updated whenever it is hit, which may cause slight lag.
  • MaxHp: The maximum HP. Only the current HP is sent to players, so they will not actually see the maximum HP but just the current HP.
  • Name: The name. This will override what players see if they mouse over the custom NPC.
  • NpcSlots: The number of NPC slots. This affects the number of NPC slots taken by the custom NPC when calculating maximum spawns.
  • Value: The value. This affects the number of coins the custom NPC drops.
• Loot: Handles the loot options:
  • TallyKills: true to tally kills for this custom NPC and have banners drop, otherwise false.
  • IsOverride: true to override original loot, otherwise false.
  • Entries: A list of loot entries:
    • Name: The item name.
    • MinStackSize: The minimum stack size.
    • MaxStackSize: The maximum stack size. The stack size will randomly chosen from this interval.
    • Prefix: The prefix. -1 is a randomized prefix with probability 0.25, and -2 is a randomized prefix.
    • Chance: The chance of dropping this loot entry.
• Spawning: Handles the spawning options:
  • ShouldSpawn: true if the custom NPC can spawn naturally, otherwise false. NOTE: You must have a Lua file that can provide the relevant logic.
  • ShouldReplace: true if the custom NPC can replace a normal NPC, otherwise false. NOTE: You must have a Lua file that can provide the relevant logic.
  • SpawnRateOverride: number overrides the spawnrate to the number you set if this is not set it will revert to default custom npc spawn rates for that custom npc.