Table of Contents

Class NPCPrefabBuilder

Namespace
S1API.Entities
Assembly
S1API.dll

Builder for composing NPC prefab configuration before network spawn. Use to declare networked components, spawn position, customer behavior, relationships, schedules, and appearance defaults.

public sealed class NPCPrefabBuilder
Inheritance
NPCPrefabBuilder
Inherited Members
Extension Methods

Remarks

Configuration must be done in ConfigurePrefab(NPCPrefabBuilder) for proper save/load behavior. All builder methods return the builder instance for fluent chaining.

Methods

EnsureCustomer()

Ensures customer infrastructure for compatibility with existing prefab-builder declarations.

[Obsolete("Override NPC.IsCustomer to return true instead.", false)]
public NPCPrefabBuilder EnsureCustomer()

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Compatibility shim for existing mods. New NPC types should override IsCustomer.

EnsureDealer()

Ensures dealer infrastructure for compatibility with existing prefab-builder declarations.

[Obsolete("Override NPC.IsDealer to return true instead.", false)]
public NPCPrefabBuilder EnsureDealer()

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Compatibility shim for existing mods. New NPC types should override IsDealer. This marks the NPC type as dealer-capable; S1API will ensure the generated spawnable prefab has a Dealer-compatible NPC component before network registration when the selected base prefab does not already include one. When the NPC spawns, EnsureDealer() will be called automatically to initialize dealer functionality and ensure the messaging app displays the correct Dealer category badge.

EnsureDrinking(EquippablePath)

Adds drinking behaviour. Use Beer, Coffee, etc.

public NPCPrefabBuilder EnsureDrinking(EquippablePath drinkEquippablePath)

Parameters

drinkEquippablePath EquippablePath

Returns

NPCPrefabBuilder

EnsureDrinking(string?)

Adds drinking behaviour to the NPC. Enables equipping a drink and playing the drinking animation.

public NPCPrefabBuilder EnsureDrinking(string? drinkEquippablePath = null)

Parameters

drinkEquippablePath string

Resources path. Null for default. Use Beer, Coffee, etc.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Adds DrinkItem as a standalone component. Use asset paths like "Avatar/Equippables/Beer" or "Avatar/Equippables/Coffee".

EnsureGraffiti(EquippablePath)

Adds graffiti behaviour. Use SprayPaint or Custom(string) for mod items.

public NPCPrefabBuilder EnsureGraffiti(EquippablePath sprayPaintEquippablePath)

Parameters

sprayPaintEquippablePath EquippablePath

Returns

NPCPrefabBuilder

EnsureGraffiti(string?)

Adds graffiti behaviour to the NPC. Enables spray painting with spray can equip and effects.

public NPCPrefabBuilder EnsureGraffiti(string? sprayPaintEquippablePath = null)

Parameters

sprayPaintEquippablePath string

Resources path. Null for default. Use SprayPaint.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Adds GraffitiBehaviour and SprayPaint. If sprayPaintEquippablePath is null, tries: (1) Resources "Weapons/SprayPaint/SprayPaint_AvatarEquippable", (2) runtime fallback: first SprayPaint in scene with non-null _sprayPaintPrefab. Modders can pass a Resources path or bundle a spray paint equippable.

EnsureItemHolding(EquippablePath)

Adds item holding behaviour. Use Phone_Lowered, Flashlight, etc.

public NPCPrefabBuilder EnsureItemHolding(EquippablePath equippablePath)

Parameters

equippablePath EquippablePath

Returns

NPCPrefabBuilder

EnsureItemHolding(string?)

Adds generic item holding behaviour to the NPC. Enables equipping any AvatarEquippable item.

public NPCPrefabBuilder EnsureItemHolding(string? equippablePath = null)

Parameters

equippablePath string

Resources path. Null for default. Use EquippablePath constants.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Adds HoldItem as a standalone component. Use Phone_Lowered, Flashlight, etc.

EnsureSmokeBreak(string?, bool?)

Adds smoke break behaviour to the NPC. Enables scheduled smoking with cigarette visual and animation.

public NPCPrefabBuilder EnsureSmokeBreak(string? cigarettePrefabPath = null, bool? debugMode = null)

Parameters

cigarettePrefabPath string

Resources path to cigarette EquippableData or TPEquippedItem. Null to try default paths.

debugMode bool?

Whether to enable SmokeBreakBehaviour debug logging. Null leaves the current value unchanged.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Adds SmokeBreakBehaviour and SmokeCigarette. Requires cigarette equippable data. If cigarettePrefabPath is null, tries the current base game Resources path "equippables/cigarette/Cigarette", then runtime SmokeCigarette data fallbacks, then the legacy CigarettePrefab fallback for older game builds. Modders can pass a Resources path to an EquippableData asset or a TPEquippedItem prefab. Adds a placeholder smoke location.

EnsureSupplier()

Ensures supplier infrastructure for compatibility with existing prefab-builder declarations.

[Obsolete("Override NPC.IsSupplier to return true instead.", false)]
public NPCPrefabBuilder EnsureSupplier()

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Compatibility shim for existing mods. New NPC types should override IsSupplier. Supplier NPCs support dead-drop orders, supplier meetings, delivery unlocks, and debt tracking. S1API reserves a location-dialogue schedule action required by the native supplier lifecycle. A custom NPC cannot be both a dealer and a supplier.

WithAppearanceDefaults(Action<AvatarDefaultsBuilder>)

Declares appearance defaults via a wrapper builder. Values are embedded as an AvatarSettings asset reference on the prefab and applied to the runtime avatar on spawn (server and clients).

public NPCPrefabBuilder WithAppearanceDefaults(Action<NPCPrefabBuilder.AvatarDefaultsBuilder> configure)

Parameters

configure Action<NPCPrefabBuilder.AvatarDefaultsBuilder>

Returns

NPCPrefabBuilder

WithCustomerDefaults(Action<CustomerDataBuilder>)

Configures customer behavior defaults using the CustomerDataBuilder.

public NPCPrefabBuilder WithCustomerDefaults(Action<CustomerDataBuilder> configure)

Parameters

configure Action<CustomerDataBuilder>

Action to configure customer defaults using the builder.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Configure spending behavior, order frequency, customer standards, product preferences, and relationship requirements. Override IsCustomer to declare customer capability. This method retains the legacy implicit declaration behavior for source and behavioral compatibility. This configuration is essential for proper save/load behavior and must be done in ConfigurePrefab(NPCPrefabBuilder).

WithDealerDefaults(Action<DealerDataBuilder>)

Configures dealer behavior defaults using the DealerDataBuilder.

public NPCPrefabBuilder WithDealerDefaults(Action<DealerDataBuilder> configure)

Parameters

configure Action<DealerDataBuilder>

Action to configure dealer defaults using the builder.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Configure dealer settings such as signing fee, commission cut, dealer type, quality restrictions, and deal tracking. Override IsDealer to declare dealer capability. This method retains the legacy implicit declaration behavior for source and behavioral compatibility. This configuration is essential for proper save/load behavior and must be done in ConfigurePrefab(NPCPrefabBuilder).

WithIcon(Sprite)

Declares the icon sprite to be embedded on the prefab. This sprite is used for UI elements such as messages, contacts, and relationships. Should be 64x64 or 128x128 pixels. Uses default if not set.

public NPCPrefabBuilder WithIcon(Sprite icon)

Parameters

icon Sprite

Optional sprite for UI elements. Uses default if null.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

WithIdentity(string, string, string)

Declares identity defaults (ID, first and last name) to be embedded on the prefab. These values are applied on spawn on both server and clients.

public NPCPrefabBuilder WithIdentity(string id, string firstName, string lastName)

Parameters

id string
firstName string
lastName string

Returns

NPCPrefabBuilder

WithInventoryDefaults(Action<RandomInventoryItemsBuilder>)

Declares default inventory configuration for this NPC type. Supports startup items (always present) and random cash (varies on each sleep).

public NPCPrefabBuilder WithInventoryDefaults(Action<RandomInventoryItemsBuilder> configure)

Parameters

configure Action<RandomInventoryItemsBuilder>

Action to configure inventory defaults using the builder.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

All configurations are optional. Applied when the NPC is spawned.

WithRegion(Region)

Sets the NPC's designated map region on the native prefab before it is network-spawned.

public NPCPrefabBuilder WithRegion(Region region)

Parameters

region Region

The NPC's designated map region.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Configure this in ConfigurePrefab(NPCPrefabBuilder) when the NPC has relationship connections. The native relationship initializer removes connections to NPCs in a different region, so setting Region later in OnCreated() is too late.

WithRelationshipDefaults(Action<NPCRelationshipDataBuilder>)

Configures default relationship settings (delta, unlock type, connections) for this NPC type. Applied to the instance after spawn and before save-data hydration.

public NPCPrefabBuilder WithRelationshipDefaults(Action<NPCRelationshipDataBuilder> configure)

Parameters

configure Action<NPCRelationshipDataBuilder>

Action to configure relationship defaults using the builder.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Configure starting relationship level, unlock state, and connections to other NPCs. This configuration must be done in ConfigurePrefab(NPCPrefabBuilder) for proper save/load behavior.

WithSchedule(params IScheduleActionSpec[])

Declares a schedule using a params array of specs for convenience.

public NPCPrefabBuilder WithSchedule(params IScheduleActionSpec[] specs)

Parameters

specs IScheduleActionSpec[]

Array of schedule action specifications.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

WithSchedule(Action<PrefabScheduleBuilder>)

Defines the NPC's schedule using the PrefabScheduleBuilder. Schedule actions are planned and pre-created on the prefab.

public NPCPrefabBuilder WithSchedule(Action<PrefabScheduleBuilder> configure)

Parameters

configure Action<PrefabScheduleBuilder>

Action to configure schedule using the builder.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Use to configure movement patterns, building visits, and timed activities. The plan is applied at runtime to activate precreated actions. Schedule configuration must be done in ConfigurePrefab(NPCPrefabBuilder) for proper save/load behavior.

WithSchedule(IEnumerable<IScheduleActionSpec>)

Declares a schedule using a prebuilt set of specs. Use when composing plans externally or sharing between NPC types.

public NPCPrefabBuilder WithSchedule(IEnumerable<IScheduleActionSpec> specs)

Parameters

specs IEnumerable<IScheduleActionSpec>

Enumerable collection of schedule action specifications.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

WithSpawnPosition(Vector3)

Sets the spawn position with default rotation. Applied every time the NPC is spawned.

public NPCPrefabBuilder WithSpawnPosition(Vector3 position)

Parameters

position Vector3

World position where the NPC will spawn.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

WithSpawnPosition(Vector3, Quaternion)

Sets the spawn position and rotation for this NPC type. Applied every time the NPC is spawned (new games and loaded games).

public NPCPrefabBuilder WithSpawnPosition(Vector3 position, Quaternion rotation)

Parameters

position Vector3

World position where the NPC will spawn.

rotation Quaternion

Rotation for the NPC (defaults to Quaternion.identity).

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Use world coordinates. Consider building entrances, roads, and safe spawn areas. Position should be on a walkable surface.

WithSupplierDefaults(Action<SupplierDataBuilder>)

Configures native supplier data for this NPC type.

public NPCPrefabBuilder WithSupplierDefaults(Action<SupplierDataBuilder> configure)

Parameters

configure Action<SupplierDataBuilder>

Action that defines order limits, delivery items, and supplier messages.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Override IsSupplier to declare supplier capability. This method retains the legacy implicit declaration behavior for source and behavioral compatibility.

Exceptions

ArgumentNullException

Thrown when configure is null.

WithVoice(NPCVoiceDefinition)

Selects a supported base-game voice while preserving the prefab's inherited pitch.

public NPCPrefabBuilder WithVoice(NPCVoiceDefinition voice)

Parameters

voice NPCVoiceDefinition

The S1API-owned voice definition.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Exceptions

ArgumentNullException

Thrown when voice is null.

InvalidOperationException

Thrown when the voice database or custom NPC data is unavailable.

WithVoice(NPCVoiceDefinition, float)

Selects a supported base-game voice and default pitch.

public NPCPrefabBuilder WithVoice(NPCVoiceDefinition voice, float pitch)

Parameters

voice NPCVoiceDefinition

The S1API-owned voice definition.

pitch float

The default playback pitch, from 0.1 through 4.0.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Exceptions

ArgumentNullException

Thrown when voice is null.

ArgumentOutOfRangeException

Thrown when pitch is outside the supported range.

InvalidOperationException

Thrown when the voice database or custom NPC data is unavailable.

WithVoice(string)

Selects a supported base-game voice by its stable, case-insensitive identifier.

public NPCPrefabBuilder WithVoice(string identifier)

Parameters

identifier string

An identifier from NPCVoiceCatalog.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Exceptions

ArgumentException

Thrown when identifier is missing or unsupported.

InvalidOperationException

Thrown when the voice database or custom NPC data is unavailable.

WithVoice(string, float)

Selects a supported base-game voice and default pitch by identifier.

public NPCPrefabBuilder WithVoice(string identifier, float pitch)

Parameters

identifier string

An identifier from NPCVoiceCatalog.

pitch float

The default playback pitch, from 0.1 through 4.0.

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Exceptions

ArgumentException

Thrown when identifier is missing or unsupported.

ArgumentOutOfRangeException

Thrown when pitch is outside the supported range.

InvalidOperationException

Thrown when the voice database or custom NPC data is unavailable.

Edit this page