Skip to content

osrlib.core.npc

NPC adventuring parties: rival groups of adventurers, generated with the SRD's procedure.

An NPC (non-player character) is a person in the game who isn't one of the players' characters. An NPC party is a group of NPC adventurers with classes, levels, gear, and treasure, like the players' party. A row of a wandering monster table can be an NPC party, or you can place one in an adventure as rivals.

generate_npc_party is the entry point. Pass it the kind of party, "basic" or "expert", and how many members it has. Also pass two seeded streams and an IdAllocator for the members' ids. It returns an NpcParty: the members with their gear and memorized spells, the alignment they share, and the treasure they carry. In a session, the engine generates a party and opens an encounter with it for you when it resolves a SpawnNpcParty command.

The members are Character models, the same model as the players' characters, so every function that takes a character takes them. They fight with the functions in osrlib.core.combat and cast with the functions in osrlib.core.spells. When the players defeat one, npc_defeat_xp returns the experience points it's worth.

You set how many adventurers appear. When a wandering monster table row is an NPC party, roll the row's count_dice and pass the total as count.

The members' rolls come from the stream keyed by NPC_PARTY_STREAM: the shared alignment, and each member's class, level, ability scores, hit points, and spells. The party's treasure and the expert members' magic items come from the stream keyed by TREASURE_STREAM instead, with the rest of a game's treasure rolls.

In these places osrlib settles a rule the SRD leaves open, and the adaptations register, the site page that lists every place osrlib commits to one reading of the rules, records each one:

  • generate_npc_party doesn't check NPC adventurers against their class's minimum ability scores, because the SRD's procedure rolls the class before the scores and gives no re-roll.
  • The equipment kits are osrlib's, in place of the SRD's "normal adventuring gear".
  • A caster's spells are rolled at random from their class's list. The SRD lets the referee choose or roll, and only rolling gives the same party from the same seed.
  • An expert member rolls for magic items at 5% per level for each kind of item they could use. An item the member can't use is dropped, not rolled again.

Typical usage:

from osrlib.core.monsters import IdAllocator
from osrlib.core.npc import NPC_PARTY_STREAM, generate_npc_party
from osrlib.core.rng import RngStreams
from osrlib.core.treasure import TREASURE_STREAM

streams = RngStreams(master_seed=5)
party = generate_npc_party(
    "basic",
    count=3,
    npc_stream=streams.get(NPC_PARTY_STREAM),
    treasure_stream=streams.get(TREASURE_STREAM),
    allocator=IdAllocator(),
)
print(party.alignment.value)
# neutral
for member in party.members:
    print(member.id, member.class_id, member.level, member.max_hp)
# npc-0001 halfling 2 4
# npc-0002 thief 3 14
# npc-0003 fighter 1 6

NPC_PARTY_STREAM module-attribute

NPC_PARTY_STREAM = StreamName.NPC_PARTY

The stream key for generating NPC adventurers, "npc_party".

A stream key is the name of one independent random-number sequence in an RngStreams set. Pass streams.get(NPC_PARTY_STREAM) as the npc_stream argument of generate_npc_party. It rolls the party's alignment from this stream, and then each member's class, level, ability scores, hit points, and spells. A GameSession uses this key when it generates an NPC party.

The party's treasure and magic items come from TREASURE_STREAM instead. Because the streams are separate, a change to how NPC parties are generated doesn't change the treasure rolls in a save you've already made.

NpcParty

Bases: BaseModel

A party of NPC adventurers, with the alignment they share and the treasure they carry.

generate_npc_party returns one. Run the members as an encounter: roll the monster reaction with roll_reaction, fight them with the functions in osrlib.core.combat, and, if the players win, award npc_defeat_xp for each member defeated. In a session, execute a SpawnNpcParty command instead. The engine generates the party and opens the encounter for you.

kind instance-attribute

kind: Literal['basic', 'expert']

"basic" for a party of low-level adventurers, or "expert" for a higher-level one.

The dice rolled for each member's level, the armour the members wear, and whether they roll for magic items all depend on it.

alignment instance-attribute

alignment: Alignment

The alignment every member shares, from one roll for the whole party. A spell that works differently against another alignment, like protection from evil, treats every member the same way.

members instance-attribute

members: list[Character]

The adventurers, as Character models.

Each member's id comes from the allocator you passed, like "npc-0001". Each member's name is the class name and the member's position, like "Thief adventurer 2". Every function that takes a character takes these.

treasure instance-attribute

The coins, valuables, and magic items the party carries, rolled once for the whole party.

In a session, the treasure drops where the players' party stands once every member is slain. If any member fled or routed, the party takes the treasure away with it.

generate_npc_party

generate_npc_party(
    kind: Literal["basic", "expert"], *, count: int, npc_stream: RngStream, treasure_stream: RngStream, allocator: Any
) -> NpcParty

Generate a party of NPC adventurers, with their gear, spells, and treasure.

Use it when you need other adventurers, like a wandering encounter or a rival party in a room of an adventure. You pass the number of members, because the encounter table or the adventure sets it. Everything else is rolled here. In a session, execute a SpawnNpcParty command instead. The engine calls this function and opens an encounter with the party.

The party shares one alignment, rolled once. Then each member gets, in turn:

  • A class and a level, from the SRD's NPC party table.
  • Ability scores, 3d6 for each ability in order.
  • Hit points for that level.
  • Experience points equal to the threshold for that level.
  • An equipment kit their class can use, with rations, a waterskin, and torches.
  • If they cast spells, memorized spells rolled at random from their class's list.

In an expert party, clerics, dwarves, and fighters wear plate mail instead of chainmail. Each expert member also has a 5% chance per level of a magic item from each kind of item they could use. The party's treasure is treasure types U and V, rolled once for the whole party and added together.

The first level's hit die is rolled directly, with the CON modifier added, and gives at least 1 hit point. Each level after the first is added with level_up, which rolls a die only when that level adds a hit die. The expert level dice can put a dwarf, fighter, or thief above name level, the level at which a character may build a stronghold, and no die is rolled for a level past name level.

This function doesn't check members against their class's minimum ability scores, because the SRD's procedure rolls the class before the scores. An elf here can have an INT too low for a player character elf.

The rolls come from the two streams in a fixed order, so the same seeds give the same party. The alignment and then each member's rolls, in member order, come from npc_stream. Each member's magic items, and then the party's treasure, come from treasure_stream.

Parameters:

Name Type Description Default
kind Literal['basic', 'expert']

"basic" for a party of levels 1 to 3, or "expert" for a higher-level party, whose level dice depend on the class rolled.

required
count int

How many adventurers appear, 1 or more. Roll it from the count_dice of the encounter table row for the party.

required
npc_stream RngStream

The stream for the members, usually streams.get(NPC_PARTY_STREAM).

required
treasure_stream RngStream

The stream for the magic items and the party's treasure, usually streams.get(TREASURE_STREAM).

required
allocator Any

The IdAllocator that assigns ids to the members and to the magic items and valuables they carry. In a session, pass GameSession.allocator, so the new ids don't repeat ids already in the game.

required

Returns:

Type Description
NpcParty

The party: its members, their shared alignment, and their treasure.

Raises:

Type Description
ValueError

If kind is neither "basic" nor "expert", or count is less than 1. Neither stream advances, and the allocator assigns no id.

Examples:

from osrlib.core.monsters import IdAllocator
from osrlib.core.npc import NPC_PARTY_STREAM, generate_npc_party, npc_defeat_xp
from osrlib.core.rng import RngStreams
from osrlib.core.treasure import TREASURE_STREAM

streams = RngStreams(master_seed=5)
party = generate_npc_party(
    "basic",
    count=2,
    npc_stream=streams.get(NPC_PARTY_STREAM),
    treasure_stream=streams.get(TREASURE_STREAM),
    allocator=IdAllocator(),
)
print(party.kind, party.alignment.value)
# basic neutral
for member in party.members:
    print(member.name, member.level, member.max_hp, member.armour_class)
# Halfling adventurer 1 2 4 6
# Thief adventurer 2 3 14 7
print(sum(npc_defeat_xp(member.level) for member in party.members))
# 55

npc_defeat_xp

npc_defeat_xp(level: int) -> int

Return the experience points a party earns for defeating one NPC adventurer of this level.

Call it once for each defeated member of an NpcParty, and add the results to the rest of the party's experience. Divide the total among the surviving characters and award each share with apply_xp. In a session, the session counts defeated NPCs for you.

The SRD gives experience for monsters by Hit Dice, and gives no rule for NPC adventurers. osrlib counts an NPC adventurer as a monster with as many Hit Dice as the NPC has levels, and no special abilities. The adaptations register, the site page that lists every place osrlib commits to one reading of the rules, records this reading.

Parameters:

Name Type Description Default
level int

The NPC's level, 1 or higher.

required

Returns:

Type Description
int

The experience points for defeating the NPC.

Raises:

Type Description
ValueError

If level is less than 1.

Examples:

from osrlib.core.npc import npc_defeat_xp

print(npc_defeat_xp(1), npc_defeat_xp(3), npc_defeat_xp(5))
# 10 35 175