Make NPC role properties drive prefab configuration

[ifBars]

What would you like to see?

Make NPC role declarations consistent and authoritative at the NPC level.

NPC already exposes IsDealer and IsSupplier, but customer capability is still declared through NPCPrefabBuilder.EnsureCustomer(). Dealer and supplier setup can also still be declared through EnsureDealer() and EnsureSupplier(), which splits a custom NPC's role definition between the NPC type and its prefab configuration.

Add:

public virtual bool IsCustomer => false;

Then use IsCustomer, the existing IsDealer, and the existing IsSupplier as the primary source of truth when S1API prepares the custom NPC prefab. S1API should automatically materialize the required customer component, dealer root/infrastructure, or supplier root/infrastructure before network registration.

Mark these existing methods as non-error obsolete compatibility shims:

• NPCPrefabBuilder.EnsureCustomer()
• NPCPrefabBuilder.EnsureDealer()
• NPCPrefabBuilder.EnsureSupplier()

They should continue forwarding to the same registration/configuration behavior so existing mods remain source-, binary-, and behavior-compatible during the migration.

Why would this help?

Role declarations are fundamental NPC characteristics and are easier to discover and understand near IsPhysical than inside ConfigurePrefab. A custom NPC would read fluently at the top of the type:

public override bool IsPhysical => true;
public override bool IsCustomer => true;
public override bool IsDealer => false;
public override bool IsSupplier => false;

This also removes the opportunity for the role property and prefab-builder calls to disagree, and lets ConfigurePrefab focus on role-specific defaults and optional prefab customization rather than required boilerplate.

Extra context

Document that these properties are declarative type-level configuration inspected during prefab preparation. Overrides should be stable, side-effect-free values and must not depend on normal instance initialization.

Invalid declarations should fail early with a descriptive InvalidOperationException. At minimum, preserve and document the current constraints:

• an NPC cannot be both a dealer and a supplier;
• a supplier must be physical.

Any additional customer/dealer/supplier incompatibilities should only be enforced when confirmed by the native component/root model. Do not invent restrictions for combinations the game supports.

Role-specific configuration such as WithCustomerDefaults, WithDealerDefaults, and WithSupplierDefaults should use the automatically prepared role infrastructure. Existing call patterns must retain their observable behavior through the obsolete forwarding path.

Acceptance criteria

• Add and XML-document NPC.IsCustomer, defaulting to false.
• Treat IsCustomer, IsDealer, and IsSupplier as the primary prefab-role declarations.
• Automatically prepare the required customer, dealer, and supplier prefab components/infrastructure before network registration.
• Throw descriptive InvalidOperationException errors for invalid role declarations, including dealer + supplier and nonphysical supplier.
• Mark NPCPrefabBuilder.EnsureCustomer(), EnsureDealer(), and EnsureSupplier() as [Obsolete(..., false)] with migration guidance.
• Preserve the old methods as forwarding shims with their existing return type, signatures, side effects, and fluent chaining behavior.
• Update XML docs, NPC authoring guides, examples, and generated workbench/export code to prefer the role properties.
• Add focused compatibility tests for legacy Ensure*() callers and property-driven prefab preparation.
• Cover valid and invalid role combinations, defaults, and repeated prefab preparation.
• Validate the prefab/network lifecycle on both Mono and IL2CPP.