API Hero load_appearance

gm.hero.load_appearance

Endpoint: gm.hero.load_appearance

Syntax

gm.hero.load_appearance <hero> <filename> [force]

Parameters

Parameter	Type	Required	Position	Description
hero	string	Yes	0	Hero name, StringId, or player
filename	string	Yes	1	Name of the save file (without .json extension)
force	bool	No	2	Set to true to allow loading across genders (default: false)

Description

Loads a hero's appearance from a previously saved JSON file and applies it to the target hero. The loaded data includes face code, body properties (facial features, hair, beard, tattoos, body shape, height).

Age is NOT applied when loading an appearance — age is tied to the hero's birth date and game timeline. Use gm.hero.set_age to adjust age separately.

By default, the command enforces gender matching — you cannot load a female appearance onto a male hero or vice versa. Set force:true to bypass this restriction.

Use gm.hero.list_appearances to see all available saved files, and gm.hero.save_appearance to create them.

Examples

Load by Partial Name

gm.hero.load_appearance derthert my_face

Output:

[gm.hero.load_appearance] hero: Derthert | filename: my_face.json | force: False
SUCCESS: Loaded appearance onto Derthert from my_face.json

Load Multi-Word Hero Name

gm.hero.load_appearance 'Ira of the Aserai' warrior_face

Load with Force (Cross-Gender)

gm.hero.load_appearance 'Ira of the Aserai' warrior_face force:true

Using Named Arguments

gm.hero.load_appearance hero:derthert filename:king_look

Load onto Player

gm.hero.load_appearance player my_character

Usage Tips

Standard Appearance Transfer Workflow:

# 1. Find which appearance files are available
gm.hero.list_appearances

# 2. Load desired appearance onto target hero
gm.hero.load_appearance derthert king_look

Backup and Restore Workflow:

# Backup before editing
gm.hero.save_appearance derthert derthert_backup

# Make changes via face editor or load a preset
gm.hero.edit_appearance derthert

# Restore if needed
gm.hero.load_appearance derthert derthert_backup

Cross-Gender Loading:

# Apply a female appearance file to a male hero (use force)
gm.hero.load_appearance derthert ira_look force:true

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: Appearance file not found: '{filename}.json'

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

Gender Mismatch (without force):

Error: Cannot load a female appearance onto a male hero. Use force:true to override.

Solution: Add force:true as the third argument if cross-gender loading is intended.

Filename Empty:

Error: Filename cannot be empty.

Solution: Provide a valid filename as the second argument.

Related Commands

• gm.hero.save_appearance - Save a hero's appearance to a file
• gm.hero.list_appearances - List all saved appearance files
• gm.hero.edit_appearance - Open the native face generator UI
• gm.hero.set_age - Set hero age (not applied by this command)
• gm.hero.load_development - Load hero skills and progression
• gm.hero.load_traits - Load hero traits
• gm.hero.load_character - Load full character data (appearance + development + traits + equipment)
• API-Hero-Overview - All hero commands

Notes

Age Not Applied: Age is tied to the hero's birth date in the game timeline and is not transferred. Adjust age separately with gm.hero.set_age.

Gender Enforcement: By default, only appearances from the same gender can be loaded. This prevents visual glitches from mismatched body geometry. Use force:true only if you understand the visual consequences.

Immediate Effect: The appearance change takes effect immediately. The hero's updated appearance will be visible in the game world without reloading the save.

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