Character Trait Models
Models for character traits, trait definitions, and trait value modification options.
CharacterTrait
| Field | Type | Description |
|---|---|---|
id |
str |
Unique identifier |
character_id |
str |
Parent character ID |
value |
int |
Current trait value |
trait |
Trait |
Trait definition |
specialties |
list[CharacterTraitSpecialty] |
Active specialties, oldest first. Only abilities have specialties |
tracker |
Tracker \| None |
In-play tracker state. None when the trait has no tracker for the character's game version |
Tracker
Tracker is a type alias for CounterTracker | StainsTracker. The type field selects the model. Use isinstance() or a match statement to read the variant. Character health is not a Tracker. It is a Health model.
CounterTracker
A trait whose points are spent and regained in play, such as Willpower or Blood Pool.
| Field | Type | Description |
|---|---|---|
type |
Literal["COUNTER"] |
Tracker type |
size |
int |
Maximum, equal to the trait value |
current |
int |
Points available now |
StainsTracker
Humanity stains on a V5 vampire.
| Field | Type | Description |
|---|---|---|
type |
Literal["STAINS"] |
Tracker type |
humanity |
int |
Humanity value |
stain_capacity |
int |
Boxes available for stains: 10 minus Humanity |
stains |
int |
Stains marked. Stains past stain_capacity have no effect |
TrackerStateSet
Request body for set_tracker(), and the tracker field of CharacterCreateTraitAssign. Set only the field for the tracker type. The client does not send fields that are None. A field that does not fit the tracker type causes a ValidationError, even when its value is 0. Any other field causes a RequestValidationError before the client sends the request.
| Field | Type | Description |
|---|---|---|
current |
int \| None |
Counter points available. Required for COUNTER |
stains |
int \| None |
Humanity stains for STAINS |
All values must be 0 or more.
CharacterCreateTraitAssign
A trait to assign in CharacterCreate.traits.
| Field | Type | Description |
|---|---|---|
trait_id |
str |
Trait ID |
value |
int |
Starting value. Ignored for V5 Willpower |
tracker |
TrackerStateSet \| None |
Starting tracker state. None for an unmarked tracker |
CharacterTraitSpecialty
A free-text specialty on an ability trait. Archived specialties are never returned.
| Field | Type | Description |
|---|---|---|
id |
str |
Unique identifier |
name |
str |
Specialty name |
date_created |
datetime |
Creation timestamp |
date_modified |
datetime |
Last modification time |
CharacterTraitSpecialtyCreate
Request model for add_specialty().
| Field | Type | Description |
|---|---|---|
name |
str |
Specialty name, 3-50 characters, unique on the trait ignoring case |
currency |
TraitModifyCurrency |
Currency to pay with (default "NO_COST") |
CharacterTraitSpecialtyUpdate
Request model for update_specialty().
| Field | Type | Description |
|---|---|---|
name |
str |
New specialty name, 3-50 characters, unique on the trait ignoring case |
CharacterTraitAdd
Request model for assigning a trait to an already-created character. Used by the assign() method on the character traits service.
| Field | Type | Description |
|---|---|---|
trait_id |
str |
ID of the trait to assign |
value |
int |
Value to set for the trait |
currency |
TraitModifyCurrency |
Currency to use to pay for the trait |
TraitCreate
Request model for creating a custom trait on a character. Used by the create() method on the character traits service. The trait is always created at a value of 1; the supplied currency pays for that first dot. NPC and STORYTELLER characters accept only "NO_COST".
| Field | Type | Description |
|---|---|---|
name |
str |
Trait name |
category_id |
str |
Parent category ID |
currency |
TraitModifyCurrency |
Currency used to pay for the initial dot |
description |
str \| None |
Trait description |
max_value |
int |
Maximum value (default 5, range 0-100) |
min_value |
int |
Minimum value (default 0, range 0-100) |
show_when_zero |
bool \| None |
Show the trait when its value is zero |
is_rollable |
bool |
Whether the trait is rollable (default True) |
initial_cost |
int \| None |
XP cost to acquire |
upgrade_cost |
int \| None |
XP cost per upgrade |
count_based_cost_multiplier |
int \| None |
Count-based cost multiplier |
BulkAssignTraitResponse
Response from bulk_assign(). Contains results grouped by outcome.
| Field | Type | Description |
|---|---|---|
succeeded |
list[BulkAssignTraitSuccess] |
Successfully assigned traits |
failed |
list[BulkAssignTraitFailure] |
Traits that failed to be assigned |
BulkAssignTraitSuccess
| Field | Type | Description |
|---|---|---|
trait_id |
str |
ID of the trait that was assigned |
character_trait |
CharacterTrait |
The resulting character trait instance |
BulkAssignTraitFailure
| Field | Type | Description |
|---|---|---|
trait_id |
str |
ID of the trait that failed |
error |
str |
Human-readable error message |
Trait
| Field | Type | Description |
|---|---|---|
id |
str |
Unique identifier |
name |
str |
Trait name |
description |
str \| None |
Trait description |
max_value |
int |
Maximum value |
min_value |
int |
Minimum value |
initial_cost |
int |
XP cost to acquire |
upgrade_cost |
int |
XP cost per upgrade |
count_based_cost_multiplier |
int \| None |
Count-based cost multiplier for traits |
category_id |
str |
Category ID |
category_name |
str \| None |
Category name |
custom_for_character_id |
str \| None |
Owning character if custom, else None |
subcategory_id |
str \| None |
Subcategory ID |
subcategory_name |
str \| None |
Subcategory name |
pool |
str \| None |
Traits that contribute to the pool |
opposing_pool |
str \| None |
Traits to counter this trait |
system |
str \| None |
System rules |
is_rollable |
bool |
Whether the trait is rollable |
sheet_section_id |
str |
Sheet section ID |
sheet_section_name |
str \| None |
Sheet section name |
game_versions |
list[GameVersion] |
Available game versions |
character_classes |
list[CharacterClass] |
Applicable classes |
gift_attributes |
GiftAttributes \| None |
Werewolf gift attributes |
powers |
list[TraitPower] |
Powers granted at each dot level |
tracker_type_v4 |
TrackerType \| None |
Tracker on V4 characters, or None |
tracker_type_v5 |
TrackerType \| None |
Tracker on V5 characters, or None |
TraitPower
A power the trait grants at a specific dot level. Ordered by level ascending, then by name. A single level may grant several powers, since Disciplines offer a choice per dot.
Entries come in two shapes. Named powers (Disciplines and Thaumaturgy/Necromancy paths) have a name and usually a system. Nameless per-dot descriptors on Attributes and Skills are a plain sentence describing what each dot rating means, and have name set to None.
Empty list when the trait has no powers.
| Field | Type | Description |
|---|---|---|
id |
str |
Unique identifier |
level |
int |
Dot level at which the power is gained |
name |
str \| None |
Power name, None for dot descriptors |
description |
str \| None |
What the power does |
system |
str \| None |
System rules for using the power |
link |
str \| None |
Link to the power's reference page |
CharacterTraitValueOptionsResponse
Returned when querying available value change options for a character trait. Contains the current state and a map of possible changes with their costs.
| Field | Type | Description |
|---|---|---|
name |
str |
Name of the trait |
current_value |
int |
Current trait value |
trait |
Trait |
Full Trait definition |
xp_current |
int |
Available XP |
starting_points_current |
int |
Available starting points |
options |
dict[str, CharacterTraitValueOption] |
Map of value to change options |
CharacterTraitValueOption
Represents a single value change option for a trait.
| Field | Type | Description |
|---|---|---|
direction |
str |
Direction of change (up/down) |
point_change |
int |
Cost in points for this change |
can_use_xp |
bool |
Whether XP can fund this change |
xp_after |
int |
XP remaining after this change |
can_use_starting_points |
bool |
Whether starting points can be used |
starting_points_after |
int |
Starting points remaining after |