API Hero import_character

gm.hero.import_character

Endpoint: gm.hero.import_character

Syntax

gm.hero.import_character <filename> <clan> [type] [settlement] [withParty]

Parameters

Parameter	Type	Required	Position	Description
filename	string	Yes	0	Character set filename without .json extension
clan	string	Yes	1	Target clan name, StringId, or partial match
type	string	No	2	Override hero type: lord, wanderer, or companion. Defaults to the type saved in the file
settlement	string	No	3	Placement settlement name or ID. Defaults to auto-resolved from clan
withParty / party	bool	No	4	For lords: whether to create a party (true/false). Defaults to true

Description

Creates a brand new hero by importing a previously exported character set file. The saved appearance, development (skills, attributes, perks), traits, and equipment are all applied to the newly generated hero.

The new hero receives a fresh identity — a new name (from the saved file or auto-generated), a new StringId, and a new MBGUID — while inheriting all the visual and gameplay data from the exported character.

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

Examples

Minimal Import (Use Saved Type)

gm.hero.import_character my_king 'dey meroc'

Import as a Lord

gm.hero.import_character king_export meroc lord

Import as a Companion

gm.hero.import_character ira_backup meroc companion

Import with Named Arguments

gm.hero.import_character filename:ira_backup clan:meroc type:companion

Import with Settlement Placement

gm.hero.import_character ira_backup 'dey meroc' wanderer Poros

Import as Lord at a Castle

gm.hero.import_character ira_backup meroc lord 'Vladiv Castle' false

Output:

[gm.hero.import_character] filename: ira_backup | clan: Dey Meroc | type: lord | settlement: Vladiv Castle | withParty: False
SUCCESS: Imported character from 'ira_backup'. Created hero '{Name}' (ID: {StringId}).

Usage Tips

Standard Import Workflow:

# 1. Check available character files
gm.hero.list_characters

# 2. Import the character into a clan
gm.hero.import_character my_king 'dey meroc' lord

Sharing Characters Between Saves:

# Export from one save
gm.hero.export_character derthert custom_lord

# Import into another save session
gm.hero.import_character custom_lord vlandia lord

Import as Wanderer (No Clan Party):

gm.hero.import_character ira_backup meroc wanderer

Error Handling

File Not Found:

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

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

Clan Not Found:

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

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

Invalid Type:

Error: Invalid hero type '{type}'. Valid types: lord, wanderer, companion

Solution: Use one of the three valid type values.

Settlement Not Found:

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

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

Hero Creation Limit:

Error: Hero creation limit reached.

Solution: Reduce the number of custom heroes in the game or adjust BLGM configuration.

Filename or Clan Empty:

Error: Filename argument cannot be empty.
Error: Clan argument cannot be empty.

Solution: Ensure both required arguments are provided.

Related Commands

• gm.hero.export_character - Export a hero's full character data to a file
• gm.hero.load_character - Load a character set onto an existing hero
• gm.hero.list_characters - List all saved character set files
• gm.hero.create_lord - Create a new lord without a character set file
• gm.hero.create_companions - Create companions without a character set file
• API-Hero-Overview - All hero commands

Notes

New Identity: Imported heroes receive a new name (from the character set or auto-generated), a new StringId, and a new MBGUID. They are treated as entirely new game entities even though their visual and gameplay data comes from the exported hero.

Type Override: If the type argument is provided, it overrides the hero type stored in the character set file. If omitted, the type from the file is used. Valid types are lord, wanderer, and companion.

Settlement Auto-Resolution: If no settlement is specified, the system automatically determines an appropriate spawn location based on the target clan's holdings.

Party Creation: The withParty parameter only applies when the hero type is lord. Wanderers and companions do not have mobile parties. Defaults to true.

Single Quotes Required: The TaleWorlds console requires SINGLE QUOTES (not double quotes) for multi-word arguments. This applies to multi-word clan names like 'dey meroc' and settlement names like 'Vladiv Castle'.

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

Last Updated: 3/3/2026