Class CustomProductDefinitionBuilder

Namespace

S1API.Products

Assembly

S1API.dll

Builds and lifecycle-registers a generic, non-mixable custom product definition.

public sealed class CustomProductDefinitionBuilder

Inheritance

object

CustomProductDefinitionBuilder

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

The builder creates a plain native product definition. It does not create a weed, methamphetamine, cocaine, or shroom-family definition and does not register the product with native mix generation.

Presentation references are borrowed from an existing product through WithRepresentationsFrom(ProductDefinition). A registered ProductPresentationProfile may replace the generic product's loose presentation contexts while preserving the borrowed native scaffolds. Packaged-content visuals, product-manager UI tabs, station recipes, and mixing remain outside this builder's scope. Register the same definition and presentation profile before save-item restoration on every participating peer; the game cannot restore or transmit definitions or assets supplied by a missing mod.

Constructors

CustomProductDefinitionBuilder(string, ProductKind)

Creates a builder for a stable generic custom product.

public CustomProductDefinitionBuilder(string id, ProductKind productKind)

Parameters

id string

A stable namespaced product ID in mod-id:product-id form.

productKind ProductKind

The immutable logical product kind. Its compatibility drug type is required by native save and product-item data but does not enable mixing.

Remarks

Keep this durable ID namespaced for saves and multiplayer. If you do not want to type the namespace when testing through the console, register the short name with ConsoleItemAliases after building the definition so give <alias> resolves it locally.

Properties

ProductId

Gets the stable product ID this builder will create.

public string ProductId { get; }

Property Value

string

Methods

Build()

Builds and registers the generic product through S1API's process-lifetime custom-product lifecycle registry.

public CustomProductDefinition Build()

Returns

CustomProductDefinition

The new custom product definition, or the same instance on repeated calls.

Remarks

Build does not discover, list, add to shops, or add this definition to the native created-products list. Call the explicit discovery, listing, and shop APIs when wanted.

Exceptions

InvalidOperationException

Thrown when required configuration is missing, effects do not resolve, a product-kind compatibility type is absent, or the stable product ID collides.

WithBaseAddictiveness(float)

Sets base addictiveness before native property contributions.

public CustomProductDefinitionBuilder WithBaseAddictiveness(float baseAddictiveness)

Parameters

baseAddictiveness float

A finite value, clamped to the native 0 through 1 range.

Returns

CustomProductDefinitionBuilder

This builder.

WithDefaultQuality(Quality)

Sets the quality used by CreateInstance(int). The default is Standard.

public CustomProductDefinitionBuilder WithDefaultQuality(Quality quality)

Parameters

quality Quality

A defined quality value.

Returns

CustomProductDefinitionBuilder

This builder.

WithDescription(string)

Sets the product description. The default is an empty description.

public CustomProductDefinitionBuilder WithDescription(string description)

Parameters

description string

The description, which may be empty but not null.

Returns

CustomProductDefinitionBuilder

This builder.

WithEffectDurations(int, int)

Sets native consumption-effect durations.

public CustomProductDefinitionBuilder WithEffectDurations(int playerSeconds, int npcSeconds)

Parameters

playerSeconds int

Non-negative player effect duration in seconds.

npcSeconds int

Non-negative NPC effect duration in seconds.

Returns

CustomProductDefinitionBuilder

This builder.

Remarks

When omitted, both durations are copied from the representation template.

WithLegalStatus(LegalStatus)

Sets whether the product is legal or illegal. The default is Illegal.

public CustomProductDefinitionBuilder WithLegalStatus(LegalStatus legalStatus)

Parameters

legalStatus LegalStatus

A defined legal-status value.

Returns

CustomProductDefinitionBuilder

This builder.

WithName(string)

Sets the non-empty display name.

public CustomProductDefinitionBuilder WithName(string name)

Parameters

name string

The product display name.

Returns

CustomProductDefinitionBuilder

This builder.

WithNativeMixerMap(ProductMixingMap)

Selects the native product family used to execute a generic custom product.

public CustomProductDefinitionBuilder WithNativeMixerMap(ProductMixingMap mixerMap)

Parameters

mixerMap ProductMixingMap

Returns

CustomProductDefinitionBuilder

Remarks

This is an explicit runtime strategy, not logical-kind metadata. It lets a product kind with no vanilla DrugType use a supported native product and mixer implementation without changing that kind's identity.

WithProductPrice(float)

Sets the product's initial native price.

public CustomProductDefinitionBuilder WithProductPrice(float productPrice)

Parameters

productPrice float

A finite price. Values are clamped to 1 through 999 and rounded to the nearest integer, matching the native product-manager price policy.

Returns

CustomProductDefinitionBuilder

This builder.

WithProperties(params PropertyBase[])

Replaces all configured product properties.

public CustomProductDefinitionBuilder WithProperties(params PropertyBase[] properties)

Parameters

properties PropertyBase[]

Distinct vanilla property tokens or registered custom property wrappers. An empty array creates a product without effects.

Returns

CustomProductDefinitionBuilder

This builder.

WithProperty(PropertyBase)

Adds one vanilla or registered custom product property.

public CustomProductDefinitionBuilder WithProperty(PropertyBase property)

Parameters

property PropertyBase

The property token or wrapper to add.

Returns

CustomProductDefinitionBuilder

This builder.

WithRepresentationsFrom(ProductDefinition)

Borrows the existing loose/stored/held/icon/consumption references needed for item use.

public CustomProductDefinitionBuilder WithRepresentationsFrom(ProductDefinition template)

Parameters

template ProductDefinition

An existing native-backed product definition.

Returns

CustomProductDefinitionBuilder

This builder.

Remarks

The builder shares the template references; it does not clone or redistribute game assets. It deliberately does not copy the template's station representation because generic products are not production-station or mixing inputs.

WithSaveProvider(string, int, string)

Associates this definition with a process-registered provider that can recreate it on a fresh-process save load.

public CustomProductDefinitionBuilder WithSaveProvider(string providerId, int providerVersion, string providerData = "")

Parameters

providerId string

The stable, namespaced provider ID.

providerVersion int

The provider's non-negative scalar payload version.

providerData string

Bounded provider-owned scalar data; never pass assets or paths.

Returns

CustomProductDefinitionBuilder

This builder.

WithValidPackaging(params PackagingDefinition[])

Replaces the packaging types accepted by this product.

public CustomProductDefinitionBuilder WithValidPackaging(params PackagingDefinition[] packaging)

Parameters

packaging PackagingDefinition[]

Distinct packaging definitions. The builder stores them in native ascending-capacity order. An empty array makes the product loose-only.

Returns

CustomProductDefinitionBuilder

This builder.