Character API Reference

API reference for working with characters in code.

Game Methods

getCharacter(id)

Get a character by ID.

const mc = game.getCharacter("mc");

getParty()

Get all characters in the party.

const party = game.getParty();
for (const character of party) {
  console.log(character.getName());
}

getAllCharacters()

Get all characters in the game.

const allChars = game.getAllCharacters();

createCharacter(id, template, skipEvents?)

Create a character from a template object or registered template ID.

// From a registered template ID
const shopkeeper = game.createCharacter("shopkeeper_1", "shopkeeper_template");
game.addCharacter(shopkeeper);

// From a custom template object
const npc = game.createCharacter("custom_npc", {
  traits: { name: "Custom NPC" },
  stats: { health: 100, strength: 10 },
  attributes: { sex: "male" }
});
game.addCharacter(npc);

// Skip creation events (for previews, etc.)
const preview = game.createCharacter("preview", "some_template", true);

addCharacter(character, isParty?)

Add a character to the game. Optionally add to party.

game.addCharacter(npc);       // Add without joining party
game.addCharacter(npc, true); // Add and join party

isCharacterInParty(character)

Check if a character is in the party. Accepts character instance or ID string.

if (game.isCharacterInParty("alice")) {
  console.log("Alice is in the party");
}

addToParty(character)

Add a character to the party. Accepts character instance or ID string. Triggers character_join_party event.

game.addToParty("alice");  // Using ID string
game.addToParty(npc);      // Using Character instance

removeFromParty(character)

Remove a character from the party. Accepts character instance or ID string. Triggers character_leave_party event.

game.removeFromParty("alice");  // Using ID string
game.removeFromParty(npc);      // Using Character instance

deleteCharacter(character)

Delete a character from the game entirely. Accepts character instance or ID string. Removes their private inventory and removes them from party. Triggers character_delete event.

game.deleteCharacter("alice");  // Using ID string
game.deleteCharacter(npc);      // Using Character instance

createStatus(template)

Create a status from a template object or registered template ID.

// From a registered template ID
const buff = game.createStatus("strength_buff");
character.addStatus(buff);

// From a custom template object
const customStatus = game.createStatus({
  id: "custom_buff",
  stats: { strength: 10 },
  maxStacks: 3
});
character.addStatus(customStatus);

registerStatGroupResolver(resolver)

Register a function that controls which stat groups appear in the character sheet per character. The resolver receives a character and returns an array of stat tag names. The engine filters stats by those tags, sorts by order, and resolves group display names from locale key group.{tag}.

Without a resolver, the character sheet defaults to two groups: "Resources" and "Stats".

// Show combat and survival for everyone, allegiance only for MC
game.registerStatGroupResolver((character) => {
    const tags = ['survival', 'combat'];
    if (character.tags.includes('mc')) tags.push('allegiance');
    return tags;
});

Group names are resolved from locale entries. For the tags above, define locale entries with IDs: group.survival, group.combat, group.allegiance.

Character Properties

ID Methods

getId()

Get the character's ID.

const id = character.getId();

setId(id)

Set the character's ID. Also updates the private inventory ID to match.

character.setId("new_character_id");

Trait & Attribute Methods

getTrait(key)

Get a trait value.

const mood = character.getTrait("mood");

setTrait(key, value)

Set a trait value on the character's core status.

character.setTrait("mood", "happy");

getAttribute(key)

Get an attribute value.

const hairColor = character.getAttribute("hair_color");

setAttribute(key, value)

Set an attribute value on the character's core status.

character.setAttribute("hair_color", "blonde");

getName()

Get the character's display name (from 'name' trait).

const name = character.getName();

Stat & Resource Methods

getStat(name)

Get a stat's computed value directly as a number. Works reactively in Vue templates and computed properties.

const maxHealth = character.getStat("health");

setStat(name, value)

Set the base value of a stat on the character's core status.

character.setStat("semen_collected_potency", 42);

getStatRef(name)

Get a stat's reactive ComputedRef. Use when you need the ref itself (e.g., for watch() or storing).

const healthRef = character.getStatRef("health");
watch(healthRef, (newVal) => console.log("Health changed:", newVal));

getResource(name)

Get the current value of a resource (e.g., current HP).

const currentHp = character.getResource("health");

addResource(name, value)

Add to a resource value. Use negative to subtract. Value is clamped between 0 and max.

character.addResource("health", -10); // Take 10 damage
character.addResource("health", 20);  // Heal 20

setResource(name, value)

Set a resource to a specific value. Value is clamped between 0 and max.

character.setResource("health", 50);

getResourceRatio(name)

Get the ratio of current resource to max stat value (0 to 1).

const healthPercent = character.getResourceRatio("health"); // 0.75 = 75%

Status Methods

getCoreStatus()

Get the core status (first status, contains base character data).

const coreStatus = character.getCoreStatus();

addStatus(status)

Add a status effect. If status already exists and is stackable, adds stacks instead. Use game.createStatus(id) to build the Status instance from a registered template.

const poison = game.createStatus("poison");
character.addStatus(poison);

removeStatus(id)

Remove a status effect by ID.

character.removeStatus("poison");

getStatus(id)

Get a status by ID.

const status = character.getStatus("blessed");

getStatuses()

Get all status effects on this character.

const statuses = character.getStatuses();
const boons = statuses.filter(s => s.tags?.includes('boon'));

setStatusStacks(statusId, newStacks)

Set a status's stack count with proper resource adjustment for replenishable stats.

character.setStatusStacks("power_buff", 3);

addStatusStacks(statusId, amount?)

Add stacks to a status with proper resource adjustment. Returns true if stacks were added successfully.

character.addStatusStacks("poison", 2);

Note: Use setStatusStacks() and addStatusStacks() instead of status.currentStacks or status.addStacks() directly when you need replenishable resources (like health) to adjust with the stat change.

Skin Layer Methods

addSkinLayers(layers)

Add skin layers to the character.

character.addSkinLayers(["armor_plate", "helmet"]);

removeSkinLayers(layers)

Remove skin layers from the character.

character.removeSkinLayers(["armor_plate", "helmet"]);

getSkinLayers()

Get the set of active skin layer IDs.

const layers = character.getSkinLayers();

setSkinLayerStyle(layerId, styles)

Set (overwrite) the CSS style classes for a skin layer.

character.setSkinLayerStyle("face", ["blushing", "sweating"]);

addSkinLayerStyle(layerId, styleClass)

Add a CSS style class to a skin layer.

character.addSkinLayerStyle("face", "blushing");

removeSkinLayerStyle(layerId, styleClass)

Remove a CSS style class from a skin layer.

character.removeSkinLayerStyle("face", "blushing");

Skill Tree Methods

addSkillTree(skillTreeId)

Add a skill tree to this character's available skill trees.

character.addSkillTree("combat_skills");

removeSkillTree(skillTreeId)

Remove a skill tree from this character's available skill trees.

character.removeSkillTree("combat_skills");

learnSkill(skillTreeId, id, level?)

Learn a skill. If already learned, increases level (up to max).

character.learnSkill("combat_skills", "fireball", 1);

unlearnSkill(skillTreeId, id)

Unlearn a skill. Refunds currency if the skill tree has a refund_factor set.

character.unlearnSkill("combat_skills", "fireball");

getSkillStatusId(skillTreeId, skillSlotId)

Generate a status ID for a skill.

const statusId = character.getSkillStatusId("combat", "fireball");
// Returns: "_skill_combat_fireball"

Inventory Methods

setPrivateInventory(inventory)

Set the character's private inventory.

character.setPrivateInventory("mc_backpack");

getPrivateInventory()

Get the character's private inventory.

const inventory = character.getPrivateInventory();

getPartyInventory()

Get the inventory to use for equipping items. Returns party inventory if in party, otherwise private inventory.

const inventory = character.getPartyInventory();

getEquippedItems()

Get all items currently equipped by this character.

const equipped = character.getEquippedItems();

equipItem(item, slotId?, slotIndex?)

Equip an item to this character. Accepts Item instance or uid string.

character.equipItem("item_uid_123");           // Auto-find slot
character.equipItem(swordItem);                // Using Item instance
character.equipItem("item_uid_123", "weapon"); // Specific slot type
character.equipItem("item_uid_123", "ring", 1); // Specific slot index

unequipItem(item)

Unequip an item from this character. Accepts Item instance or uid string.

character.unequipItem("item_uid_123");
character.unequipItem(swordItem);

Item Slot Methods

addItemSlot(id, slotId, x, y)

Add an equipment slot to the character.

character.addItemSlot("main_hand_1", "weapon_slot", 100, 200);

getItemSlotById(id)

Get an item slot by its unique ID.

const slot = character.getItemSlotById("main_hand_1");

getItemSlots()

Get all item slots on this character.

const slots = character.getItemSlots();

removeItemSlot(slot)

Remove an item slot from the character.

character.removeItemSlot(slot);

getItemSlotsBySlotId(slotId)

Get all item slots of a specific slot type.

const weaponSlots = character.getItemSlotsBySlotId("weapon_slot");

getAvailableSlotsForItem(item)

Get all slots where an item can be equipped.

const availableSlots = character.getAvailableSlotsForItem(sword);

Ability Methods

getAbilities()

Get all final computed abilities (base + modifiers merged).

const abilities = character.getAbilities().value;
// {
//   fireball: {
//     meta: { name: "Fireball", icon: "...", cooldown_base: 3 },
//     effects: {
//       main_damage: { damage: 50, damage_type: "fire" }
//     }
//   }
// }

getAbility(abilityId)

Get a specific computed ability by ID.

const fireball = character.getAbility("fireball");
for (const effectId in fireball.effects) {
  const aspects = fireball.effects[effectId];
  console.log(effectId, aspects.damage);
}

getGroupedAbilities()

Get abilities organized by ability groups. Returns { useGroups, groups }.

• If no abilities have a group meta assigned, useGroups is false and all ability IDs are in a single flat group.
• If any ability has a group, useGroups is true and groups contains sorted groups with their ability IDs. Ungrouped abilities are logged as warnings and excluded.

const { useGroups, groups } = character.getGroupedAbilities();

if (useGroups) {
  for (const group of groups) {
    console.log(group.name, group.abilityIds);
  }
} else {
  // Flat list — all abilities in groups[0].abilityIds
  console.log(groups[0].abilityIds);
}

Utility Methods

update(data)

Bulk update character data.

character.update({
  stats: { strength: 10 },
  traits: { mood: "happy" },
  attributes: { hair_color: "red" }
});

Spine Animation Methods

getSpineTrackAnimations(view?)

Get the current track-to-animation mapping based on character attributes. Animations are grouped by underscore prefix — each group plays on its own Spine track, driven by the matching attribute.

// Spine has animations: "body", "belly_0", "belly_1", "face_idle", "face_ahegao"
// Character attributes: belly = "1", face = "idle"
// Result: { 0: "body", 1: "belly_1", 2: "face_idle" }
const trackMap = character.getSpineTrackAnimations();

// Change belly animation by setting the attribute:
character.setAttribute('belly', '2'); // automatically plays belly_2 on track 1

hasSpineAnimation(animation, view?)

Check if a spine animation exists for the given view. Returns false if spine hasn't loaded yet.

if (character.hasSpineAnimation('belly_2', '')) {
  character.setAttribute('belly', '2');
}

setAvailableSpineAnimations(view, names)

Register available animation names for a view. Called automatically by CharacterDollSpine on load — you normally don't call this directly.

isSpineCharacter()

Returns true if the character has a default spine config.

isSpineForView(view)

Check if a spine config exists for the given view (e.g. "back").

getSpineSkins()

Returns an array of Spine skin names derived from the character's current attributes.

Status Interface

Status effects applied to characters.

Status Methods

// Check if stackable and add stacks
if (status.isStackable()) {
  // Use character.addStatusStacks() for proper resource adjustment
  character.addStatusStacks(status.id, 2);

  // Or use status.addStacks() directly if you don't need resource adjustment
  // status.addStacks(2);
}

// Add stat modifier
status.addStat("strength", 5);

// Set computed stats key
status.setComputedStats("level_scaling");

// Set values from template
status.setValues({
  stats: { strength: 10 },
  traits: { name: "Power Buff" },
  abilities: ["power_strike"]
});

ItemSlot Interface

Equipment slots on characters.

const slotDef = slot.getSlotObject(); // Get slot type definition

CharacterSkinLayerObject Interface

Skin layer data for rendering.