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

object

NPCPrefabBuilder

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Extension Methods

ReflectionUtils.GetValueTupleItems(object)

ReflectionUtils.IsValueTuple(object)

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()

Adds customer behavior component to the NPC. Required before configuring customer defaults.

public NPCPrefabBuilder EnsureCustomer()

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Enables the NPC to act as a business customer that can buy products from the player.

EnsureDealer()

Adds dealer behavior to the NPC. Required before configuring dealer defaults.

public NPCPrefabBuilder EnsureDealer()

Returns

NPCPrefabBuilder

The builder instance for fluent chaining.

Remarks

Enables the NPC to act as a dealer that sells products to assigned customers. Note: Since Dealer inherits from NPC in the base game, dealer functionality is applied through configuration rather than component addition. This marks the NPC type as dealer-capable. 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.

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. Requires EnsureCustomer() to be called first.

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. 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. Requires EnsureDealer() to be called first.

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. 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.

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.