API Hero rename

gm.hero.rename

Endpoint: gm.hero.rename

Syntax

gm.hero.rename <heroQuery> <name>

Parameters

Parameter	Type	Required	Description
heroQuery	string	Yes	Hero identifier (StringId or partial name match) to find a single hero
name	string	Yes	The new name for the hero. Use SINGLE QUOTES for multi-word names

Description

Renames the specified hero to a new name. This command allows you to change the display name of any hero in the game, including player companions, lords, and wanderers. The name change is immediate and permanent for the current save.

The command finds a single hero matching the provided query (either by StringId or by name search) and updates their display name to the specified new name.

Examples

Basic Renaming

gm.hero.rename lord_1_1 'Sir Galahad'

Output:

Hero renamed from '{Previous Name}' to 'Sir Galahad' (ID: lord_1_1)

Rename by Current Name

gm.hero.rename 'old hero name' NewName

Output:

Hero renamed from 'old hero name' to 'NewName' (ID: {hero_id})

Rename Companion

gm.hero.rename companion_1 'The Bold Knight'

Output:

Hero renamed from '{Previous Name}' to 'The Bold Knight' (ID: companion_1)

Usage Tips

Finding Heroes to Rename: Use query commands to find hero IDs:

# Find hero by partial name match
gm.query.hero Marcus
gm.query.hero_info lord_1_1

# Then rename using the ID
gm.hero.rename lord_1_1 'Sir Marcus the Bold'

Multi-word Names: Always use SINGLE QUOTES for names with spaces:

# Correct - using single quotes
gm.hero.rename lord_1_1 'Lord of Winterfell'
gm.hero.rename companion_1 'The Swift Blade'

# Incorrect - double quotes don't work in TaleWorlds console
gm.hero.rename lord_1_1 "Lord of Winterfell"  # This will fail

Single-word Names: No quotes needed for single-word names:

gm.hero.rename lord_1_1 Marcus
gm.hero.rename companion_1 Ragnar

Renaming Player Companions:

# Find your companion
gm.query.hero companion

# Rename them
gm.hero.rename companion_1 'Loyal Guard'

Renaming Lords: Change the name of faction lords:

# Find the lord
gm.query.hero empire

# Rename specific lord
gm.hero.rename lord_3_5 'Emperor Marcus'

Renaming Wanderers: Rename wanderers before recruiting them:

# Spawn a wanderer
gm.settlement.spawn_wanderer pen

# Find the wanderer
gm.query.hero wanderer

# Rename them
gm.hero.rename {wanderer_id} 'Skilled Warrior'

Using with Create Commands: Rename heroes after creation:

# Create a lord with temporary name
gm.hero.create_lord 'Temp Name' vlandia male

# Find the created lord
gm.query.hero 'Temp Name'

# Rename to final name
gm.hero.rename 'Temp Name' 'Sir Lancelot'

Partial Name Matching: The heroQuery parameter supports partial matches:

# If there's only one hero with "Marcus" in the name
gm.hero.rename Marcus 'Marcus Aurelius'

# Be specific if multiple matches possible
gm.hero.rename lord_1_1 'Marcus Aurelius'

Error Handling

Multiple Matches: If the heroQuery matches multiple heroes:

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

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

No Matches: If no hero is found:

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

Solution: Verify the hero exists using gm.query.hero first.

Empty Name: If the new name is empty:

Error: New name cannot be empty.

Solution: Provide a valid name for the hero.

Related Commands

• API-Hero-Overview - All hero commands
• API-Hero-create_lord - Create new lord with custom name
• API-Hero-generate_lords - Generate multiple lords
• gm.query.hero - Find heroes by name
• gm.query.hero_info - Get detailed hero information
• gm.query.hero_any - Advanced hero search

Notes

Name Persistence: The name change is saved with your game save and will persist through save/load cycles.

Immersion and Role-Play: This command is useful for:

• Customizing companion names to fit your story
• Renaming lords after conquest to reflect your empire
• Creating themed playthroughs with specific naming conventions
• Fixing auto-generated names you don't like

No Culture Effect: Renaming a hero does not change their culture, skills, equipment, or any other properties - only their display name.

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

Last Updated: 2025-12-20