Skip to content

API Hero save_appearance

Jump to bottom
SolWayward edited this page Mar 4, 2026 · 1 revision

gm.hero.save_appearance

Endpoint: gm.hero.save_appearance

Syntax

gm.hero.save_appearance <hero> <filename>

Parameters

Parameter Type Required Position Description
hero string Yes 0 Hero name, StringId, or player
filename string Yes 1 Name for the save file (without .json extension)

Description

Saves a hero's appearance to a JSON file. The saved data includes the hero's face code, body properties (facial features, hair, beard, tattoos, body shape, height). Age is NOT saved as part of appearance since it is tied to the hero's birth date and game timeline.

The saved file can later be loaded onto any hero using gm.hero.load_appearance. Use gm.hero.list_appearances to view all saved files.

Examples

Save by Partial Name

gm.hero.save_appearance derthert my_face

Output:

[gm.hero.save_appearance] hero: Derthert | filename: my_face.json
SUCCESS: Saved Derthert's appearance to: my_face.json
Hero: Derthert (Male, Vlandian)
BodyProperties: <body properties string>

Save Multi-Word Hero Name

gm.hero.save_appearance 'Ira of the Aserai' ira_look

Output:

[gm.hero.save_appearance] hero: Ira of the Aserai | filename: ira_look.json
SUCCESS: Saved Ira of the Aserai's appearance to: ira_look.json
Hero: Ira of the Aserai (Female, Aserai)
BodyProperties: <body properties string>

Using Named Arguments

gm.hero.save_appearance hero:derthert filename:king_look

Save Player Appearance

gm.hero.save_appearance player my_character

Usage Tips

Creating Appearance Templates:

# Save from a hero with the look you want
gm.hero.save_appearance derthert kingly_look

# Apply it to any other hero
gm.hero.load_appearance 'Ira of the Aserai' kingly_look

Backing Up Before Editing:

# Backup current appearance before opening the face editor
gm.hero.save_appearance derthert derthert_backup
gm.hero.edit_appearance derthert

# Restore if you want to undo
gm.hero.load_appearance derthert derthert_backup

List available files:

gm.hero.list_appearances

Error Handling

Hero Not Found:

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

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

Multiple Matches:

Error: Multiple heroes found matching '{query}'. Please be more specific.

Solution: Use a more specific name or the exact StringId.

Filename Empty:

Error: Filename cannot be empty.

Solution: Provide a valid filename as the second argument.

Related Commands

Notes

Age Not Saved: Appearance files do not include age. Age is tied to a hero's birth date in the game timeline and cannot be transferred via appearance files. Use gm.hero.set_age to adjust age separately.

Gender Matching: By default, appearances can only be loaded onto heroes of the same gender. Use force:true in gm.hero.load_appearance to override this restriction.

File Overwrite: If a file with the same name already exists, it will be overwritten without warning. Use gm.hero.list_appearances to check existing files first.

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

Quick Links

🏠 Home | Quick Reference | Syntax Guide

Hero Commands
Clan Commands
Kingdom Commands
Settlement Commands
Item Commands
Troop Commands
Caravan Commands
Bandit Commands
Query Commands

Clone this wiki locally