Custom NPCs

The S1API provides a comprehensive system for creating custom NPCs that integrate seamlessly with the base game's systems. This guide covers creating physical NPCs with full functionality including schedules, dialogue, customer behavior, relationships, and appearance customization.

Overview

Custom NPCs in S1API are built on a modular architecture that allows you to create both physical NPCs (visible in the world) and non-physical NPCs (contacts, informants, etc.). The system provides:

• Physical NPCs: Visible in the game world with 3D models, movement, and direct interaction
• Non-Physical NPCs: Invisible contacts for messaging and phone interactions
• Modular Components: Appearance, Dialogue, Schedule, Customer, and Relationship systems
• Save/Load Integration: Full persistence support with the game's save system
• Network Compatibility: Works in both single-player and multiplayer environments
• Cross-branch Compatibility: Works in both Mono and Il2Cpp builds

Documentation Structure

The Custom NPC system is documented across multiple focused pages:

Core Concepts

• Basic NPC Creation - Fundamental concepts and getting started
• Prefab Configuration - Setting up NPC components and behavior
• Runtime Management - NPC lifecycle and runtime properties

Systems & Features

• Appearance Customization - Visual appearance and avatar system
• Scheduling System - NPC schedules and movement patterns
• Dialogue System - Interactive conversations and dialogue trees
• Customer Behavior - NPCs as business customers
• Relationship Management - NPC relationships and connections

API Reference

• S1API - Detailed API documentation

Example Repository

For complete, production-ready NPC implementations, see the S1API NPC Example Repository. This repository contains four fully-featured example NPCs covering all major use cases:

• ExamplePhysicalNPC1 - Customer with dialogue, inventory, and complex scheduling
• ExamplePhysicalNPC2 - Customer events and dealer recommendations
• ExamplePhysicalDealerNPC - Complete dealer implementation
• CharacterCustomizerNPC - UI integration example

Using AI Assistance?

If you use an AI coding agent to create or review custom NPC mods, point it at the schedule-one-custom-npcs agents skill. The skill summarizes the S1API two-phase NPC model, physical versus non-physical NPC choices, customer/dealer setup, appearance constraints, schedules, dialogue, and lifecycle checks that custom NPC implementations should follow.

Quick Start

Here's a minimal example to get you started:

public sealed class MyFirstNPC : NPC
{
    protected override bool IsPhysical => true;
    
    protected override void ConfigurePrefab(NPCPrefabBuilder builder)
    {
        builder.WithIdentity(
                id: "my_first_npc",
                firstName: "John",
                lastName: "Doe")
                .WithSpawnPosition(new Vector3(0, 0, 0))
                .EnsureCustomer()
                .WithCustomerDefaults(cd => {
                    cd.WithSpending(100f, 500f)
                      .WithOrdersPerWeek(1, 3);
                });
    }
    
    public MyFirstNPC() : base()
    {
    }
    
    protected override void OnCreated()
    {
        base.OnCreated();
        
        // Set up appearance
        Appearance
            .Set<CustomizationFields.Gender>(0.5f)
            .Set<CustomizationFields.Height>(1.0f)
            .Build();
        
        // Enable systems
        Schedule.Enable();
        Schedule.InitializeActions();
    }
}

What To Read First

• Start here: Basic NPC Creation
• Then: Prefab Configuration (identity, relationships, schedules, customer/dealer defaults)
• As needed: Dialogue System, Scheduling System, Customer Behavior, Dealer System

Getting Help

• Review the S1API for detailed method documentation
• Look at the example projects in the repository for real-world usage patterns
• When working with an AI coding agent, share the schedule-one-custom-npcs agents skill so generated NPC code follows the same S1API patterns as these docs.

Next Steps

1. Copy an example NPC and get it spawning: S1API NPC Example Repository
2. Make it walk somewhere: Scheduling System
3. Add interaction: Dialogue System