Table of Contents

Class NPC

Namespace
S1API.Entities
Assembly
S1API.dll

Abstract base class for creating custom NPCs with modular architecture supporting both physical and non-physical NPCs. Physical NPCs are visible in the game world with 3D models, movement, and direct interaction. Non-physical NPCs are invisible contacts primarily used for messaging and phone interactions.

public abstract class NPC : Saveable, IEntity, IHealth
Inheritance
NPC
Implements
Derived
Inherited Members
Extension Methods

Remarks

NPCs provide access to component systems: Appearance, Dialogue, Schedule, Customer, Relationship, Inventory, and Movement. Customer, relationship, and schedule configuration must be done in ConfigurePrefab(NPCPrefabBuilder) for proper save/load behavior.

Constructors

NPC()

Base constructor for a new NPC. Identity is configured via ConfigurePrefab(NPCPrefabBuilder) using WithIdentity(string, string, string) and optionally WithIcon(Sprite).

protected NPC()

Remarks

Not intended for direct instancing. Create your derived class and let S1API handle instancing. Identity information (ID, firstName, lastName, icon) must be provided in ConfigurePrefab(NPCPrefabBuilder) using the builder methods.

NPC(string, string?, string?, Sprite?)

Backwards-compatible constructor for non-physical NPCs that provides identity directly via parameters. This constructor is intended for backwards compatibility with mods that used the old constructor pattern.

[Obsolete("Use the parameterless constructor and configure identity via ConfigurePrefab with NPCPrefabBuilder.WithIdentity. This constructor is provided for backwards compatibility with non-physical NPCs.")]
protected NPC(string id, string? firstName, string? lastName, Sprite? icon = null)

Parameters

id string

Unique identifier for the NPC.

firstName string

The first name for the NPC.

lastName string

The last name for the NPC. Can be null.

icon Sprite

The icon sprite for the NPC. Can be null to use default.

Remarks

This constructor is marked as obsolete. For new code, use the parameterless constructor and configure identity via ConfigurePrefab(NPCPrefabBuilder) using WithIdentity(string, string, string) and optionally WithIcon(Sprite).

This constructor is appropriate for non-physical NPCs (where IsPhysical returns false) that don't require prefab configuration. Physical NPCs should use ConfigurePrefab(NPCPrefabBuilder) for proper network spawn support.

Fields

All

List of all NPCs within the base game and modded.

public static readonly List<NPC> All

Field Value

List<NPC>

Responses

A list of text responses you've added to your NPC.

protected readonly List<Response> Responses

Field Value

List<Response>

Properties

Aggressiveness

How aggressive this NPC is towards others.

public float Aggressiveness { get; set; }

Property Value

float

Appearance

Access to the appearance customization system for visual avatar management.

public NPCAppearance Appearance { get; }

Property Value

NPCAppearance

CombatBehaviour

The current CombatBehaviour instance.

public CombatBehaviour CombatBehaviour { get; }

Property Value

CombatBehaviour

ConversationCanBeHidden

Set's whether the text message can be deleted/hidden

public bool ConversationCanBeHidden { get; set; }

Property Value

bool

CurrentBuilding

The enterable building the NPC is currently in, if any.

public Building? CurrentBuilding { get; }

Property Value

Building

CurrentHealth

The current health the NPC has.

public float CurrentHealth { get; }

Property Value

float

CurrentVehicle

The current vehicle the NPC is occupying, if any.

public LandVehicle? CurrentVehicle { get; }

Property Value

LandVehicle

CustomNpcsReady

Whether all custom NPCs have been instantiated and finalized. This flag is set to true once all custom NPC types have been spawned and initialized. Mods can check this to ensure custom NPCs are ready before performing operations that depend on them.

public static bool CustomNpcsReady { get; }

Property Value

bool

Customer

Access to the customer behavior system for NPCs that act as business customers.

public NPCCustomer Customer { get; }

Property Value

NPCCustomer

Dealer

Access to the dealer system for NPCs that act as product distributors.

public NPCDealer Dealer { get; }

Property Value

NPCDealer

Dialogue

Access to the dialogue system for interactive conversations and dialogue trees.

public NPCDialogue Dialogue { get; }

Property Value

NPCDialogue

Drinking

Access to the drinking action for this NPC.

public NPCDrinking Drinking { get; }

Property Value

NPCDrinking

FirstName

The first name of this NPC.

public string FirstName { get; set; }

Property Value

string

FullName

The full name of this NPC. If there is no last name, it will just return the first name.

public string FullName { get; }

Property Value

string

ID

The unique identifier to assign to this NPC. Used when saving and loading. Probably other things within the base game code.

public string ID { get; protected set; }

Property Value

string

Icon

The icon assigned to this NPC.

public Sprite? Icon { get; set; }

Property Value

Sprite

Inventory

Access to the inventory system for item management.

public NPCInventory Inventory { get; }

Property Value

NPCInventory

IsConscious

Whether the NPC is currently conscious or not.

public bool IsConscious { get; }

Property Value

bool

IsCustomer

Determines whether this NPC has native customer functionality. Override as true for NPCs that should buy products from the player.

public virtual bool IsCustomer { get; }

Property Value

bool

Remarks

This declarative type-level value is inspected while S1API prepares the NPC prefab. Overrides must be stable, side-effect-free, and must not depend on constructor or field initialization. When true, S1API adds and configures the customer component before network registration.

IsDead

Whether the NPC is dead or not.

public bool IsDead { get; }

Property Value

bool

IsDealer

Determines if the NPC has dealer functionality. Override as true for NPCs that should be dealers.

public virtual bool IsDealer { get; }

Property Value

bool

Remarks

Dealer NPCs (true): Can manage customers, handle contracts, accept cash payments, and track inventory for sales. When true, the NPC prefab will use the "Dealer" network prefab instead of "CivilianNPC". Non-dealer NPCs (false): Regular NPCs without dealer-specific functionality. This declarative type-level value must be stable, side-effect-free, and independent of normal instance initialization.

IsInBuilding

Whether the NPC is currently inside a building or not.

public bool IsInBuilding { get; }

Property Value

bool

IsInVehicle

Whether the NPC is currently inside a vehicle or not.

public bool IsInVehicle { get; }

Property Value

bool

IsInvincible

Whether the NPC is invincible or not.

public bool IsInvincible { get; set; }

Property Value

bool

IsKnockedOut

Whether the NPC is knocked out or not.

public bool IsKnockedOut { get; }

Property Value

bool

IsPanicking

Whether the NPC is currently panicking or not.

public bool IsPanicking { get; }

Property Value

bool

IsPhysical

Determines if the NPC is visible in the game world. Override as true for physical NPCs with 3D models, movement, and direct interaction.

public virtual bool IsPhysical { get; }

Property Value

bool

Remarks

Physical NPCs (true): Visible in world, have collision detection, can move and follow schedules, can be damaged/healed. Non-physical NPCs (false): Invisible, primarily for messaging and phone contacts, cannot move or be directly interacted with.

IsSupplier

Determines whether this NPC uses the native supplier root and supplier framework data.

public virtual bool IsSupplier { get; }

Property Value

bool

Remarks

Supplier NPCs can provide dead-drop orders, meetings, delivery unlocks, and debt tracking. A custom NPC cannot be both a dealer and a supplier. Suppliers must also override IsPhysical to return true. This declarative type-level value must be stable, side-effect-free, and independent of normal instance initialization.

IsUnsettled

Whether the NPC is currently unsettled or not.

public bool IsUnsettled { get; }

Property Value

bool

IsVisible

UNCONFIRMED: Whether the NPC is currently visible to the player or not. If you confirm this, please let us know so we can update the documentation!

public bool IsVisible { get; }

Property Value

bool

ItemHolding

Access to the item holding action for this NPC.

public NPCItemHolding ItemHolding { get; }

Property Value

NPCItemHolding

LastName

The last name of this NPC.

public string LastName { get; set; }

Property Value

string

MaxHealth

The maximum health the NPC has.

public float MaxHealth { get; set; }

Property Value

float

Messaging

Gets access to the NPC's phone messaging state, events, and message helpers.

public NPCMessaging Messaging { get; }

Property Value

NPCMessaging

Movement

Access to the movement system for controlling NPC movement and navigation.

public NPCMovement Movement { get; }

Property Value

NPCMovement

NPCId

Static NPC ID for this NPC type. Used to resolve connections during prefab configuration when NPC instances are not yet available. Override this in derived classes to provide the NPC ID string (e.g., "kyle_cooley", "ludwig_meyer").

public static string? NPCId { get; }

Property Value

string

Remarks

For built-in NPC wrappers, this should return the ID string that matches the base game NPC. For custom NPCs, this should return the ID configured via WithIdentity(string, string, string).

Position

The world position of the NPC.

public Vector3 Position { get; set; }

Property Value

Vector3

Region

The region the NPC is associated with. Note: Not the region they're in currently. Just the region they're designated to.

public Region Region { get; set; }

Property Value

Region

Relationship

Access to the relationship system for social connections and relationships with the player.

public NPCRelationship Relationship { get; }

Property Value

NPCRelationship

RequiresRegionUnlocked

UNCONFIRMED: Whether the NPC requires the region unlocked in order to deal to. If you confirm this, please let us know so we can update the documentation!

public bool RequiresRegionUnlocked { get; set; }

Property Value

bool

Scale

Sets the scale of the NPC.

public float Scale { get; set; }

Property Value

float

Schedule

Access to the schedule system for movement and activity scheduling.

public NPCSchedule Schedule { get; }

Property Value

NPCSchedule

Smoking

Access to the smoking action for this NPC.

public NPCSmoking Smoking { get; }

Property Value

NPCSmoking

SprayPainting

Access to the spray painting action for this NPC.

public NPCSprayPainting SprayPainting { get; }

Property Value

NPCSprayPainting

Supplier

Access to the supplier system for NPCs that provide dead drops and supplier meetings.

public NPCSupplier Supplier { get; }

Property Value

NPCSupplier

Transform

The transform of the NPC. Please do not set the properties of this transform.

public Transform Transform { get; }

Property Value

Transform

gameObject

INTERNAL: Tracking for the GameObject associated with this NPC. Not intended for use by modders!

public GameObject gameObject { get; }

Property Value

GameObject

Methods

ClearConversationCategories()

Clears the NPC's conversation categories, removing any badge (C/S/D) from the messages UI. This makes the NPC appear like Uncle Nelson - present in messages but without a category badge.

public void ClearConversationCategories()

ConfigurePrefab(NPCPrefabBuilder)

Override to configure NPC components and default behavior before the NPC is spawned. Called during prefab creation to set up spawn position, customer behavior, relationships, and schedules.

protected virtual void ConfigurePrefab(NPCPrefabBuilder builder)

Parameters

builder NPCPrefabBuilder

Prefab builder for configuring this NPC type.

Remarks

Customer, relationship, and schedule configuration must be done here for proper save/load behavior and network compatibility. Use the builder pattern for fluent configuration. Runtime initialization should be done in OnCreated() instead.

Damage(int)

Deals damage to the NPC.

public void Damage(int amount)

Parameters

amount int

The amount of damage to deal.

Get(string)

Gets the instance of an NPC by its unique ID. Supports already-materialized wrappers and built-in NPC wrappers.

public static NPC? Get(string npcId)

Parameters

npcId string

The S1 NPC ID.

Returns

NPC

The matching wrapper instance, or null if one could not be resolved.

Get<T>()

Gets the instance of an NPC. Supports base NPCs as well as other mod NPCs. For base NPCs, S1API.Entities.NPCs.

public static NPC? Get<T>() where T : NPC

Returns

NPC

Type Parameters

T

The NPC class to get the instance of.

Goto(Vector3)

Tells the NPC to travel to a specific position in world space.

public void Goto(Vector3 position)

Parameters

position Vector3

The position to travel to.

Heal(int)

Heals the NPC.

public void Heal(int amount)

Parameters

amount int

The amount of health to heal.

Kill()

Kills the NPC.

public void Kill()

KnockOut()

Knocks the NPC out. NOTE: Does not work for invincible NPCs.

public void KnockOut()

LerpScale(float, float)

Smoothly scales the NPC over lerpTime.

public void LerpScale(float scale, float lerpTime)

Parameters

scale float

The scale you want set.

lerpTime float

The time to scale over.

OnCreated()

Called when the NPC is fully created and spawned. Override for runtime initialization after all components are set up. Use this to configure appearance, dialogue systems, subscribe to events, enable schedule system, and set basic properties.

protected override void OnCreated()

Remarks

Called after the NPC is instantiated and all components are initialized. Appearance, dialogue, and schedule setup should be done here rather than in the constructor.

OnResponseLoaded(Response)

Called when a text message response is loaded from the save file. Override to re-attach callbacks to loaded responses.

protected virtual void OnResponseLoaded(Response response)

Parameters

response Response

The response that was loaded from save data.

Panic()

Requests that the NPC become panicked.

public void Panic()

PreRegisterAllNpcPrefabs()

Compatibility shim for manually scanning and pre-registering NPC prefabs.

[Obsolete("S1API automatically pre-registers NPC prefabs. Remove this call.", false)]
public static void PreRegisterAllNpcPrefabs()

Remarks

S1API owns prefab registration and retry timing. Mods should not call this method.

PreRegisterPrefabForType(Type)

Compatibility shim for manually pre-registering a per-type NPC prefab.

[Obsolete("S1API automatically pre-registers NPC prefabs. Remove this call.", false)]
public static void PreRegisterPrefabForType(Type npcType)

Parameters

npcType Type

The custom NPC type whose prefab S1API will pre-register.

Remarks

S1API owns prefab registration and retry timing. Mods should not call this method.

RefreshMessagingIcons() 

public void RefreshMessagingIcons()

Revive()

Revives the NPC. For a network-spawned custom NPC, the server uses the native revive method. A client call does not alter local state. Unspawned custom NPCs use a temporary compatibility fallback until FishNet initializes.

public void Revive()

SendTextMessage(string, Response[]?, float, bool)

Sends a text message from this NPC to the players. Supports responses with callbacks for additional logic.

public void SendTextMessage(string message, Response[]? responses = null, float responseDelay = 1, bool network = true)

Parameters

message string

The message you want the player to see. Unity rich text is allowed.

responses Response[]

Instances of Response to display.

responseDelay float

The delay between when the message is sent and when the player can reply.

network bool

Whether this should propagate to all players or not.

SetEquippable(EquippablePath)

Sets an equippable item for the NPC using a type-safe path.

public void SetEquippable(EquippablePath equippablePath)

Parameters

equippablePath EquippablePath

Use EquippablePath (e.g. Phone_Lowered).

SetEquippable(string)

Sets an equippable item for the NPC.

public void SetEquippable(string assetPath)

Parameters

assetPath string

The asset path to the equippable item. Use EquippablePath or Misc.

StopPanicking()

Causes the NPC to stop panicking, if they are currently.

public void StopPanicking()

Unsettle(float)

Causes the NPC to become unsettled. UNCONFIRMED: Will panic them for a short duration.

public void Unsettle(float duration)

Parameters

duration float

Length of time they should stay unsettled.

Events

OnDeath

Called when the NPC died.

public event Action OnDeath

Event Type

Action

OnEnterVehicle

Occurs when the NPC enters a vehicle.

public event Action<LandVehicle> OnEnterVehicle

Event Type

Action<LandVehicle>

Remarks

This event preserves the timing of the native vehicle-entry callback.

OnExitVehicle

Occurs when the NPC exits a vehicle.

public event Action<LandVehicle> OnExitVehicle

Event Type

Action<LandVehicle>

Remarks

This event preserves the timing of the native vehicle-exit callback.

OnExplosionHeard

Called when this NPC hears an explosion. The snapshot is null only when the native event has no noise event.

public event Action<NPCNoiseEvent?> OnExplosionHeard

Event Type

Action<NPCNoiseEvent>

OnGunshotHeard

Called when this NPC hears a gunshot. The snapshot is null only when the native event has no noise event.

public event Action<NPCNoiseEvent?> OnGunshotHeard

Event Type

Action<NPCNoiseEvent>

OnHitByCar

Called when this NPC is hit by a vehicle. The vehicle is null when the native event has no vehicle.

public event Action<LandVehicle?> OnHitByCar

Event Type

Action<LandVehicle>

OnInventoryChanged

Called when the NPC's inventory contents change.

public event Action OnInventoryChanged

Event Type

Action

OnNoticedDrugDealing

Called when this NPC notices a player dealing drugs. The player is null when S1API has no wrapper for the native player.

public event Action<Player?> OnNoticedDrugDealing

Event Type

Action<Player>

OnNoticedGeneralCrime

Called when this NPC notices a player committing a general crime. The player is null when S1API has no wrapper for the native player.

public event Action<Player?> OnNoticedGeneralCrime

Event Type

Action<Player>

OnNoticedPettyCrime

Called when this NPC notices a player committing a petty crime. The player is null when S1API has no wrapper for the native player.

public event Action<Player?> OnNoticedPettyCrime

Event Type

Action<Player>

OnNoticedPlayerViolatingCurfew

Called when this NPC notices a player violating curfew. The player is null when S1API has no wrapper for the native player.

public event Action<Player?> OnNoticedPlayerViolatingCurfew

Event Type

Action<Player>

OnNoticedSuspiciousPlayer

Called when this NPC notices a suspicious player. The player is null when S1API has no wrapper for the native player.

public event Action<Player?> OnNoticedSuspiciousPlayer

Event Type

Action<Player>
Edit this page