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

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

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