Character Traits Service
Manage character traits including retrieval, assignment, and value modification.
Usage
from vclient import character_traits_service
traits = character_traits_service(
character_id="CHARACTER_ID", on_behalf_of="USER_ID", company_id="COMPANY_ID"
)
Methods
CRUD Operations
| Method | Returns | Description |
|---|---|---|
get(character_trait_id) |
CharacterTrait |
Get a character trait by ID |
assign(trait_id, value, currency) |
CharacterTrait |
Assign an existing trait to the character with TraitModifyCurrency |
bulk_assign(list[CharacterTraitAdd]) |
BulkAssignTraitResponse |
Assign multiple traits at once with best-effort semantics |
create(TraitCreate, **kwargs) |
CharacterTrait |
Create a custom trait |
delete(character_trait_id, currency?) |
None |
Delete a character trait. Optional TraitModifyCurrency to recoup the cost |
NPC and Storyteller characters require NO_COST
On NPC and STORYTELLER characters, every trait operation that takes a currency (assign, bulk_assign, create, change_value, delete, and add_specialty) accepts only currency="NO_COST". Passing "XP" or "STARTING_POINTS" raises ValidationError (400). PLAYER characters accept all three currencies.
Pagination
| Method | Returns | Description |
|---|---|---|
get_page(limit?, offset?, category_id?) |
PaginatedResponse[CharacterTrait] |
Get a page of traits |
list_all(category_id?) |
list[CharacterTrait] |
Get all character traits |
iter_all(limit?, category_id?) |
AsyncIterator[CharacterTrait] |
Iterate through traits |
Value Modification
| Method | Returns | Description |
|---|---|---|
get_value_options(character_trait_id) |
CharacterTraitValueOptionsResponse |
Get available value options |
change_value(character_trait_id, new_value, currency) |
CharacterTrait |
Change trait value |
Check Options First
Always call get_value_options() before changing a trait value to ensure the change is valid and to understand the cost implications.
Lowering an ability to 0 with change_value(), or deleting the trait with delete(), also removes its specialties and refunds what each cost. For the "0" and "DELETE" options, xp_after and starting_points_after include those refunds. point_change counts dots only.
Concurrent changes raise ConflictError
change_value() with any currency, and delete(), assign(), and create() with "XP" or "STARTING_POINTS", raise ConflictError (409) when another request changed the trait's value first. Nothing is spent or refunded. Fetch the trait again and retry.
assign() also raises ConflictError when the character already has the trait. This check runs before the value range check, so a duplicate with an out-of-range value also returns 409. Do not retry it. Use the value methods on the existing trait instead.
from vclient.exceptions import ConflictError
try:
await traits.change_value(trait.id, new_value=4, currency="XP")
except ConflictError:
trait = await traits.get(trait.id)
# Decide again with the current value, then retry
Specialties
| Method | Returns | Description |
|---|---|---|
add_specialty(character_trait_id, name, currency?) |
CharacterTrait |
Add a specialty to an ability |
update_specialty(character_trait_id, specialty_id, name) |
CharacterTrait |
Rename a specialty |
delete_specialty(character_trait_id, specialty_id) |
None |
Remove a specialty and refund its cost |
Specialties are free-text focuses on ability traits, such as "Knives" on Melee. Only abilities with a value of 1 or higher accept them. The name must be 3 to 50 characters and unique on the trait, ignoring case.
The cost depends on the company's specialty_xp_cost_enabled setting:
- Off (default): specialties are free, whatever the
currency. - On: a specialty paid with
"XP"or"STARTING_POINTS"costs 3 points."NO_COST"follows the company's free trait changes setting.
delete_specialty() refunds the cost in the currency used to buy it. An XP refund follows the company's permission_recoup_xp setting. Starting points are always refunded.
add_specialty() raises ValidationError when the trait is not an ability, has a value of 0, already has a specialty with that name, or the character cannot afford the cost. update_specialty() and delete_specialty() raise NotFoundError for an unknown specialty or one that belongs to a different trait.
melee = await traits.add_specialty(trait.id, name="Knives", currency="XP")
knives = melee.specialties[0]
melee = await traits.update_specialty(trait.id, knives.id, name="Throwing Knives")
await traits.delete_specialty(trait.id, knives.id)
V5 Willpower
On V5 characters, Willpower always equals Composure + Resolve. The server keeps it in sync, so you cannot change it directly:
change_value()anddelete()raiseValidationError(400).get_value_options()returns an emptyoptionsdictionary.assign()raisesConflictError(409), andbulk_assign()puts the item infailed, because every V5 character already has Willpower.
To change V5 Willpower, change Composure or Resolve. Then fetch the Willpower trait again, because change_value() returns only the trait that you changed. For the same reason, fetch health again with characters.get_health() after you change V5 Stamina, because Stamina sets the size of the health track. V4 Willpower has none of these limits.
Trackers
| Method | Returns | Description |
|---|---|---|
get_tracker(character_trait_id) |
Tracker |
Get the in-play state of a trait |
set_tracker(character_trait_id, TrackerStateSet, **kwargs) |
Tracker |
Replace the full tracker state |
apply_tracker_action(character_trait_id, action, amount?) |
Tracker |
Apply one in-play action |
A tracker holds the in-play state of a trait that is spent or stained during a session. Tracker is one of two models. Read its type field to know which one you have:
type |
Model | Used for | Field for set_tracker() |
Actions |
|---|---|---|---|---|
COUNTER |
CounterTracker |
Willpower in V4 and V5, Blood Pool, Rage, Gnosis, Conviction, and Humanity for every character except a V5 vampire | current (required) |
spend, gain, reset |
STAINS |
StainsTracker |
Humanity on a V5 vampire | stains |
add_stain, remove_stain, reset |
The same tracker object is on CharacterTrait.tracker. It is None when the trait has no tracker for the character's game version. Custom traits never have a tracker. Trait.tracker_type_v4 and Trait.tracker_type_v5 tell you which traits have a tracker before you assign them.
Humanity
Choose the Humanity control from CharacterTrait.tracker.type, not from the blueprint. Trait.tracker_type_v5 for Humanity is STAINS, but only a V5 vampire gets a STAINS tracker. Every other character gets a COUNTER.
Use apply_tracker_action() for changes during play, and set_tracker() to correct the full state. An empty set_tracker() request clears a stains tracker. Each method returns the updated tracker, so you do not need to fetch it again. The actions for each tracker type and game version are in characters.TrackerRules from the Options Service. Stains past stain_capacity stay on the tracker and have no other effect.
The methods raise these errors:
NotFoundError(404): the trait has no tracker for the character's game version.ValidationError(400): the field or action does not fit the tracker type, a spend is more thancurrent, or a value is more than the tracker size.AuthorizationError(403): you are not the character's player or a storyteller.RequestValidationError: a value is negative,amountis less than 1, orset_tracker()receives a field other thancurrentandstains. The client raises this error before it sends the request.
API version
The tracker endpoints need a Valentina API release later than v0.28.0. An older API returns 404, and CharacterTrait.tracker is always None. API v0.29.0 sends V5 Willpower as a DAMAGE tracker, which this client rejects, so parsing any V5 character's traits from that release raises a pydantic.ValidationError. Use an API release later than v0.29.0.
from vclient.models import CounterTracker, StainsTracker
tracker = await traits.get_tracker(willpower.id)
match tracker:
case CounterTracker():
print(f"{tracker.current}/{tracker.size} Willpower")
case StainsTracker():
print(f"{tracker.stains} stains, {tracker.stain_capacity} free boxes")
# Spend two points of Willpower
tracker = await traits.apply_tracker_action(willpower.id, "spend", amount=2)
# Correct the full state
tracker = await traits.set_tracker(willpower.id, current=3)
Example
from vclient.models import TraitCreate
# Assign an existing trait from the blueprint
trait = await traits.assign(trait_id="strength_trait_id", value=3, currency="XP")
# Create a custom trait (preferred method: use model object).
# The trait is always created at a value of 1; the currency pays for that first dot.
# Custom traits are rollable by default; pass is_rollable=False for a non-rollable trait.
request = TraitCreate(
name="Street Smarts",
category_id="skills_category_id",
currency="XP",
max_value=5,
)
custom = await traits.create(request)
# Alternative: pass fields as keyword arguments
custom = await traits.create(
name="Street Smarts",
category_id="skills_category_id",
currency="XP",
max_value=5,
)
# Check available value change options
options = await traits.get_value_options(trait.id)
print(f"Available values: {options.available_values}")
print(f"Current value: {options.current_value}")
# Change the trait value
updated = await traits.change_value(trait.id, new_value=4, currency="XP")
Bulk Assignment
Assign multiple traits in a single request. Each item is processed independently — successful assignments are saved and failed ones are reported with error details.
from vclient.models import CharacterTraitAdd
items = [
CharacterTraitAdd(trait_id="strength_id", value=3, currency="XP"),
CharacterTraitAdd(trait_id="dexterity_id", value=2, currency="NO_COST"),
CharacterTraitAdd(trait_id="stamina_id", value=1, currency="STARTING_POINTS"),
]
result = await traits.bulk_assign(items)
for success in result.succeeded:
print(f"Assigned: {success.character_trait.trait.name}")
for failure in result.failed:
print(f"Failed {failure.trait_id}: {failure.error}")
Running Currency Balance
Currency balances are tracked across the batch. If early traits spend XP or starting points, later traits in the same request see the reduced balance. Order items strategically — place flaw traits (which grant currency) before traits that spend it.
Maximum batch size is 200 items. Exceeding this raises ValidationError.
See Response Models for CharacterTrait, Trait, and related types.