Skip to content

Town NPCs

JonataOliveiraa edited this page Nov 14, 2026 · 1 revision
Intermediate

Town NPCs are the characters who move into the houses you build, like the Guide and the Merchant. They have names, talk when you tap them, sell things, and react to each other with emote bubbles. A town NPC is a ModNPC (see NPCs) with a few extra hooks, and this page shows them.

Town NPCs

A resident needs NPC.townNPC = true, a town AI style and a housing head. [AutoloadHead] loads HeadTexture, which defaults to Texture + "_Head": the head shown in the housing menu and on the map. NPCHeadLoader.GetHeadSlot and GetNPCHeadSlot give its index.

CanTownNPCSpawn(int numTownNPCs) is asked when the game looks for a new resident, after the game's own candidates. An existing NPC or a missing housing head prevents a duplicate candidate. CheckConditions(left, right, top, bottom) adds a room condition after the normal housing checks. SetNPCNameList() supplies names; GlobalNPC.ModifyNPCNameList can edit the list, including the names of the game's NPCs: for those, the list holds the name the game picked, and for a mod NPC the whole list it gave. NPC.TownNPCName reads and writes the NPC's given name.

CanChat() controls talk availability. A global's false vetoes it. GetChat() supplies the text, followed by GlobalNPC.GetChat(NPC npc, ref string chat).

The buttons of the conversation come from RegisterChatButtons(NPCInteractionList) and OnChatButtonClicked(NPCInteraction), as in the newest tModLoader. For example:

public override void RegisterChatButtons(NPCInteractionList interactions)
{
    interactions.InsertBefore(NPCInteractions.Shop("Shop"), NPCInteractionDatabase.CloseButton);
}

An NPCInteraction provides Condition, GetText and Interact. NPCInteractions.Shop opens the named shop. Global pre-click callbacks can veto an interaction; mod and global post-click callbacks run afterward. The phone's conversation box has room for two buttons of your own: the first two interactions that are enabled and available fill them, and any beyond those are not shown. Close, happiness and housing stay the game's own buttons; their interaction objects only mark positions in the list.

The older SetChatButtons(ref string button, ref string button2) and OnChatButtonClicked(bool firstButton, ref string shopName) also work. Returning a nonempty shopName opens that registered shop. Use either the modern interaction list or the legacy pair for a given NPC.

Register shops in ModNPC.AddShops:

public override void AddShops()
{
    new NPCShop(Type)
        .Add(ItemID.WoodenArrow)
        .Add(ItemID.Torch, Condition.TimeNight)
        .Register();
}

NPCShop.Entry supports additional conditions, disabling, reserved slots, ordering and shop-open callbacks. An Item template can set shopCustomPrice and shopSpecialCurrency. NPCShopDatabase.GetShopName builds the tModLoader full name, and Main.instance.OpenShop(string) opens it. The phone has room for 74 mod shops (the game's free shop numbers, from 99 down to 26); registering more fails. One slot stays empty unless AllowFillingLastSlot() is used.

GlobalNPC.ModifyShop runs once for a registered shop. For vanilla shops, the first time the game sets up the shop supplies the initial entries; the game still constructs its conditional stock each time the shop opens. GetEntry/TryGetEntry expose that initial snapshot and mod additions. Vanilla entries absent from the first snapshot cannot be looked up through this adapter. Changes to a captured item's template apply when that item is in the shop. Mod-added conditions are evaluated on each opening. ModNPC.ModifyActiveShop(string shopName, Item[] items) and GlobalNPC.ModifyActiveShop(NPC npc, string shopName, Item[] items) then edit the live inventory. Both active-shop callbacks receive the full shop name from NPCShopDatabase.GetShopName. SetupTravelShop edits the Traveling Merchant's stock.

Set relationships in SetStaticDefaults:

NPC.Happiness
    .SetBiomeAffection<ForestBiome>(AffectionLevel.Like)
    .SetNPCAffection(NPCID.Guide, AffectionLevel.Love);

These go into the game's own personality database, so the game works out the prices as usual. Repeating a relationship replaces its level; level zero removes it. SetBiomeAffection<T> takes the game's shopping biomes and also a mod biome.

All TownNPCAttack* methods run at the attack steps of the game's town AI, in tModLoader's order: strength, cooldown, projectile and speed, then the shooting or magic modifier when it applies. Swing attacks use strength, cooldown and the weapon's size. Damage is changed before the game scales it for town NPCs. DrawTownAttackGun and DrawTownAttackSwing choose the texture, frame and position of the weapon drawn in the NPC's hands. Only the NPC types that override these hooks pay for them.

ExamplePerson ports the ExampleMod town NPC with its body/head textures, names, inventory-based spawn gate, chat, two shops, conditional stock, happiness and the SparklingBall attack, and switches to its party and shimmer textures through TownNPCProfile (see "Other NPC hooks"). Portraits are not on the phone yet, and shops have not been tested in multiplayer yet.

Emote bubbles

A ModEmoteBubble is an emote of your own. Its texture holds two frames side by side (34 x 28 each, like the game's); AddToCategory puts it in the emote menu:

public class ExampleItemEmote : ModEmoteBubble
{
    public override void SetStaticDefaults() => AddToCategory(EmoteID.Category.Items);
}
Hook Behavior
IsUnlocked() false keeps it out of the emote menu.
OnSpawn() When a bubble with this emote appears. EmoteBubble is that bubble, and each bubble has its own instance, so instance fields are per bubble.
UpdateFrame() false stops the game's two-frame animation; set EmoteBubble.frame yourself.
GetFrame() The frame in your texture; null uses the frame of the bubble's animation.
GetFrameInEmoteMenu(int frame, int frameCounter) The frame shown in the emote menu.
PreDraw(...), PostDraw(...) false from PreDraw skips the bubble; PostDraw runs anyway.

ModContent.EmoteBubbleType<T>() gives the emote's type, which starts after EmoteID.Count (151 on the phone). Spawn one with EmoteBubble.NewBubble(type, WorldUIAnchor.New(player), time), or over a player with EmoteBubble.MakePlayerEmote(player, type) (in multiplayer a game emote goes through message 120; a mod emote shows only on this device, see below). A GlobalEmoteBubble gets the same hooks for every bubble, the game's included, running before the emote's own; its GetFrame applies to the game's emotes.

NPCs choose emotes with ModNPC.PickEmote(Player closestPlayer, List<int> emoteList, WorldUIAnchor otherAnchor) (and GlobalNPC.PickEmote): return a type, or add to emoteList and return null to let the game draw one from it. On the phone the list starts with the game's own pick, so adding a type several times makes it more likely. NPCID.Sets.FaceEmote[Type] gives a town NPC the emote other NPCs use to mention it. EmoteBubblePosition(ref Vector2 position, ref SpriteEffects spriteEffects) moves the bubble above an NPC.

On the phone the emote menu is the game's GUIEmotesWindow. UpdateFrameInEmoteMenu, PreDrawInEmoteMenu/PostDrawInEmoteMenu (built around the PC's EmoteButton) and the Command chat text are not used there. In multiplayer the game drops an emote above EmoteID.Count that a player sends (message 120), so mod emotes chosen in the menu stay local. NPC emotes in multiplayer have not been tested yet.


← Mod configs  ·  Bosses →

Clone this wiki locally