feat: Add character profile switching feature for multi-character account support

[wahyutrip]

Summary

This PR implements automatic character profile switching functionality, enabling the bot to switch between characters within the same game account during profile initialization. This feature allows multiple characters from the same account to run sequentially on a single emulator instance, maximizing resource utilization when PC limitations restrict concurrent emulator instances.

Key Changes:

• Added character identification fields (ID, name, alliance code, server) to Profile entity as direct database columns
• Implemented CharacterSwitchHelper class for character verification and switching operations
• Integrated character switching into InitializeTask initialization flow
• Added GUI support for character configuration in profile creation/editing
• Added template images and OCR regions for character switching UI navigation
• Implemented robust error handling and retry logic for character switching operations

Implementation Details:

• Character verification occurs after home screen detection but before stamina reading
• Uses OCR to read character ID and name from profile menu
• Navigates through Settings → Switch Character menu using template matching
• Searches character list using Furnace Level template and OCR for character names
• Handles scrolling, character selection, and confirmation dialog
• Supports alliance code prefix stripping for character name matching
• Fully backward compatible - profiles without character config continue to work normally

How to Test

1. Profile Setup:

   • Create or edit a profile
   • Configure character fields (Character Name, Character ID, Alliance Code, Server)
   • Save the profile

2. Character Verification (Correct Character Active):

   • Start bot with profile that has correct character already active
   • Verify bot detects correct character and continues initialization without switching
   • Check logs show "Character verification successful"

3. Character Switching (Wrong Character Active):

   • Start bot with profile that has different character active
   • Verify bot detects mismatch and switches to correct character
   • Verify bot waits for game reload and re-checks home screen
   • Check logs show character switching flow

4. Backward Compatibility:

   • Start bot with profile without character configuration
   • Verify bot skips character verification and continues normally
   • Check logs show "No character configuration found. Skipping character verification."

5. Error Handling:

   • Test with character name that doesn't exist in character list
   • Verify bot closes emulator and continues to next profile (doesn't retry)
   • Check logs show appropriate error messages

6. Multiple Characters:

   • Test switching between multiple characters on same account
   • Verify each character switch completes successfully
   • Verify bot continues with task execution after switching

Related Issues

• Closes Character Profile Switching Feature #113 - Character Profile Switching Feature
• Multi-emulator switch restriction feature will be implemented in a separate PR (issue TBD)

[gemini-code-assist]

Summary of Changes

Hello @wahyutrip, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant feature that allows the bot to automatically switch between different character profiles within a single game account. This is particularly useful for users with PC limitations, as it enables sequential operation of multiple characters on one emulator instance, thereby optimizing resource usage. The changes span across data models, persistence, UI, and core bot logic to seamlessly integrate this new functionality.

Highlights

• Multi-Character Account Support: Enables the bot to switch between characters on the same game account, maximizing resource utilization by allowing sequential operation on a single emulator instance.
• Profile Entity Expansion: Added new fields (characterId, characterName, characterAllianceCode, characterServer) directly to the Profile entity and its corresponding Data Transfer Objects (DTOs) and auxiliary models.
• CharacterSwitchHelper Introduction: Implemented a new dedicated helper class, CharacterSwitchHelper, to encapsulate all logic for character verification, UI navigation, and switching operations.
• GUI Integration: New input fields for character configuration have been added to both the 'New Profile' and 'Edit Profile' dialogs, complete with client-side input validation.
• Automated Character Switching Logic: Integrated character verification and switching into the InitializeTask flow, ensuring the correct character is active after home screen detection and before other tasks begin.
• OCR and Template Matching: Utilizes Optical Character Recognition (OCR) to read character details and template matching for reliable UI navigation during the character switching process.
• Robust Error Handling: Includes retry mechanisms for OCR and template searches, and handles scenarios where the target character is not found, closing the emulator and proceeding to the next profile.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant and well-implemented feature for automatic character profile switching. The changes span across the data, persistence, UI, and service layers, and the new CharacterSwitchHelper class encapsulates the core logic cleanly. My review focuses on improving code consistency, readability, and maintainability by addressing minor issues like code duplication in constructors, inconsistent UI validation logic, use of magic numbers, and regex formatting. Overall, this is a solid contribution.

[neptune-dev-23]

Hey @wahyutrip, looks like a major change that we have struggled to implement ourselves! Would you happen to have a screen recording to demo the features this PR adds?

[wahyutrip]

Hey @wahyutrip, looks like a major change that we have struggled to implement ourselves! Would you happen to have a screen recording to demo the features this PR adds?

Helloo @neptune-dev-23 , apologize for my bad editing skills lol. Here's a video preview

1204.1.1.mp4

[neptune-dev-23]

Wow! Incredible video. It looks like this is OCR-based, which would break when people use non-latin characters. Also, it was unclear if this requires a separate emulator instance for each profile. How does it handle ensuring that only 1 profile remains active at a time? I currently don't have profiles set up like this (and really don't feel like going through creating some new ones right now), so would you be able to run the bot for a few days with this feature first to make sure that everything works as intended? It would also be wonderful if we could switch to Discord for further discussion.

[AjYoutuber]

Hi, I’ve been testing your fork and the new character-switch feature, and I found a couple of issues along with some possible improvements:

Conflict when two profiles use the same emulator
Solution: Add a queue system.
When a profile finishes or reaches its max idle time, it should move to the bottom of the queue.
Since the priority system already exists, the queue can simply respect the existing priorities so higher-priority profiles naturally stay above lower-priority ones.

Emulator closes even when another switch is available
Solution: Add a check—if the next profile uses the same emulator, close only the game; if it uses a different emulator, then close the emulator.

Thanks for your great work on this project! Let me know if you need more details—I’m happy to keep testing.

[wahyutrip]

Wow! Incredible video. It looks like this is OCR-based, which would break when people use non-latin characters. Also, it was unclear if this requires a separate emulator instance for each profile. How does it handle ensuring that only 1 profile remains active at a time? I currently don't have profiles set up like this (and really don't feel like going through creating some new ones right now), so would you be able to run the bot for a few days with this feature first to make sure that everything works as intended? It would also be wonderful if we could switch to Discord for further discussion.

Thank you @neptune-dev-23 . Yes, this is just a start since many been asking for this. Could be improved later about the character, for now it works for me.
Yes, i use assumption 1 profile equals to 1 character, and yes, it would run 1 profile at a time with max running emulators set. For the multi emulator setup i put in separate PR #115 .
Been running on this for the past few days, so far it works. Hope you can test it on your own too

[wahyutrip]

Hi, I’ve been testing your fork and the new character-switch feature, and I found a couple of issues along with some possible improvements:

Conflict when two profiles use the same emulator Solution: Add a queue system. When a profile finishes or reaches its max idle time, it should move to the bottom of the queue. Since the priority system already exists, the queue can simply respect the existing priorities so higher-priority profiles naturally stay above lower-priority ones.

Emulator closes even when another switch is available Solution: Add a check—if the next profile uses the same emulator, close only the game; if it uses a different emulator, then close the emulator.

Thanks for your great work on this project! Let me know if you need more details—I’m happy to keep testing.

Hey, @AjYoutuber .
Thank you for your feedback. Yes I noticed that, I implement the queue improvement in separate PR #115 . I split it for easier review, this PR only cover for the profile switch.
Maybe you can merge both PR on your local branch , to make it fully works and give it a retry.

[wahyutrip]

@daviblro @camoloqlo kindly asking for your review and feedback too, please.
Thank you

[AjYoutuber]

it happen when emulator was in the middle of booting then i clicked start on bot so there was no waiting time to boot

i found the problem here when bot said "continuing to next profile" it was running same profile on wrong character

this profile switch is very helpfull before i need to manually switch character by booting emulator but now i only need to toggle profile to switch(on/off). which save a lot of time. thank you

as for now i cant run multi profiles becouse i only have 4 characters which is few to run smoothly as per #116 settings

[wahyutrip]

it happen when emulator was in the middle of booting then i clicked start on bot so there was no waiting time to boot
i found the problem here when bot said "continuing to next profile" it was running same profile on wrong character

this profile switch is very helpfull before i need to manually switch character by booting emulator but now i only need to toggle profile to switch(on/off). which save a lot of time. thank you

as for now i cant run multi profiles becouse i only have 4 characters which is few to run smoothly as per #116 settings

oh nice catch, i fixed and simplify the checking process here

[mediatech15]

Whats the state of this branch? I can help if it needs work. I would also like to test if needed. @wahyutrip