API Hero load_character

gm.hero.load_character

Endpoint: gm.hero.load_character

Syntax

gm.hero.load_character <hero> <filename>

Parameters

Parameter	Type	Required	Position	Description
hero	string	Yes	0	Target hero name, StringId, or player
filename	string	Yes	1	Character set filename without .json extension

Description

Loads a previously exported character set file and applies it to an existing hero. This command applies the saved character data onto the target hero while preserving their identity.

Applied from the character set file:

• Appearance (face code, body properties, hair, beard, tattoos, body shape, height)
• Development (skills, attributes, perks, focus points, XP, level)
• Traits (all personality, persona, political, and role/skill traits)
• Battle equipment
• Civilian equipment
• Age
• Culture

NOT applied (preserved from target hero):

• Name
• Gender
• StringId
• MBGUID
• Type / Occupation

This makes load_character ideal for applying a character template to an existing hero without changing who they are in the game world.

Use gm.hero.list_characters to see available files, and gm.hero.export_character to create them.

Examples

Load by Partial Name

gm.hero.load_character derthert my_king

Output:

[gm.hero.load_character] hero: Derthert | filename: my_king
SUCCESS: Loaded character set onto Derthert from my_king.json

Load Multi-Word Hero Name

gm.hero.load_character 'Ira of the Aserai' warrior_template

Using Named Arguments

gm.hero.load_character hero:derthert filename:king_export

Load onto Player

gm.hero.load_character player my_character_backup

Usage Tips

Restore from Backup:

# Restore a hero to a previously exported state
gm.hero.load_character derthert derthert_complete_backup

Apply a Build Template:

# Export a well-designed character
gm.hero.export_character derthert elite_cavalry_template

# Apply that template to multiple other heroes
gm.hero.load_character 'Ira of the Aserai' elite_cavalry_template
gm.hero.load_character meroc elite_cavalry_template

Verify Available Files:

gm.hero.list_characters

Error Handling

Hero Not Found:

Error: No hero found matching '{query}'.

Solution: Use gm.query.hero to verify the hero name or StringId.

File Not Found:

Error: Character set file '{filename}' not found.
Directory: C:\...\BLGM\CharacterSets\

Solution: Use gm.hero.list_characters to see available files.

Filename Empty:

Error: Filename argument cannot be empty.

Solution: Provide a valid filename as the second argument.

Related Commands

• gm.hero.export_character - Export a hero's full character data to a file
• gm.hero.import_character - Create a new hero from a character set file
• gm.hero.list_characters - List all saved character set files
• gm.hero.load_appearance - Load appearance only
• gm.hero.load_development - Load development only
• gm.hero.load_traits - Load traits only
• API-Hero-Overview - All hero commands

Notes

Identity Preserved: The target hero's name, gender, StringId, MBGUID, and occupation/type are never modified by this command. Only their visual and gameplay state is updated.

Age and Culture Applied: Unlike the individual load_appearance command, load_character also applies the saved age and culture from the character set file.

Gender Appearance Note: Since gender is preserved from the target hero, loading a character set from a hero of the opposite gender will apply the body properties as-is. This may produce unexpected visual results if the saved appearance was designed for a different gender.

Immediate Effect: All changes take effect immediately without requiring a save/reload.

Single Quotes Required: The TaleWorlds console requires SINGLE QUOTES (not double quotes) for multi-word arguments.

Named and Positional Arguments: Both named (hero:value) and positional arguments are supported. Named arguments use the format argName:value with no spaces around the colon.

Last Updated: 3/3/2026