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_partydoesn'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
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
treasure: GeneratedTreasure
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']
|
|
required |
count
|
int
|
How many adventurers appear, 1 or more. Roll it from the |
required |
npc_stream
|
RngStream
|
The stream for the members, usually
|
required |
treasure_stream
|
RngStream
|
The stream for the magic items and the party's treasure, usually
|
required |
allocator
|
Any
|
The |
required |
Returns:
| Type | Description |
|---|---|
NpcParty
|
The party: its members, their shared alignment, and their treasure. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
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
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 |
Examples: