Jump to content

Character Renaming Tool


Recommended Posts

I usually use Dragon Wolf Leo's wonderful Extended Sample Character Template as a basis to a new character I make, or sometimes a character of my own that I'd already made, and I got tired of the search & replace and file renaming process, so I wrote a small utility to do it for me.

It searches and replaces one string with another while preserving case, so if you rename esctemplate to SuperDude then everywhere you have esctemplate it will be changed to superdude and everywhere you have ESCTEMPLATE it will be changed to SUPERDUDE.

It also renames all the files it finds accordingly, so esctemplate.lua will be renamed to superdude.lua and folders named esctemplate will be renamed to superdude.

The tool is called CaseReplace and was written in Python 3 so you need to install that if you want to use it.


This tool performs a simple search & replace operation. It doesn't know that you only want to change text when it's referring to a character name.
Therefore the name you replace needs to be unique and only appear as the name of that character!
If your character is named "e" and you run this tool to replace "e" with "a" you'll most certainly break your mod and nothing will work.
Also, this tool has no undo option (replacing "a" with "e" again won't undo it), so it's highly recommended you back your files up before using it.
I have tested it but not rigorously, so it's best to make a backup before running this.
I will not be held responsible for the loss of your work or data as a result of using this tool.

How to Use It

First install Python 3.
I used Python 3.6.6 but I think any version of Python 3 should work, or at least any that are after 3.6.6.

Next, extract the contents of the ZIP file in the download link at the end of this post to your mod folder.

You'll see two files: CaseReplace and RenameDSCharacter.

Normally using RenameDSCharacter will be enough.
Just double-click it, enter the current name of the character and then the new name you want to give it, and it'll do everything for you.

That's it.


Advanced Usage

In case the normal way is not enough - for example if you want it to skip PNG files or something - you can use the CaseReplace script directly.
If you run CaseReplace with the '--help' option you will see something like this:

C:\MyModFolder>python CaseReplace.py --help
usage: CaseReplace.py [-h] [-f FIND] [-r REPLACE] [-m MIXED] [-n] [-v] [-b]
                      [-p [PATH [PATH ...]]] [-x [EXCLUDE [EXCLUDE ...]]]

CaseReplace script, by Tomer Godinger, May 2019.
Search and replace utility that preserves case.

optional arguments:
  -h, --help            show this help message and exit
  -f FIND               the string to find
  -r REPLACE            the string to replace with
  -m MIXED              what to use for mixed-case findings
  -n                    also rename files and directories
  -v                    verbose mode
  -b                    stop in case of an error
  -p [PATH [PATH ...]]  files to search in
  -x [EXCLUDE [EXCLUDE ...]]
                        files NOT to search in
  --version             show version

Example usage:
    CaseReplace.py -f SomeString -r NewString C:\*.txt
        Will replace all occurrences of "SomeString" with "NewString" in all files that end with '.txt' under C:\.
        Case is preserved, so SOMESTRING will become NEWSTRING and somestring will become newstring.
        Mixed-case will be replaced with the casing used in the replace argument.

I'm hoping that's self-explanatory, but I'll write a bit more anyway.
Let's assume I want to rename esctemplate with SuperDude.

When you run it you must provide:

  • The string to search for: -f esctemplate
  • The string to replace it with: -r SuperDude
  • At least one of these two (both is also fine):
    • Which files to look in - for example, to search only in Lua scripts: -p **/*.lua
    • Which files NOT to look in - for example, to skip ZIP files: -x **/*.zip

If you only provide the -x option, the script will process every file except the ones who fit the -x pattern.

This script uses the Python glob module, which uses Unix style pathname pattern expansion, so if you have trouble getting it to work only on the files you want then you may want to look into that.

You also may provide:

  • What to replace mixed-case findings with, for example: -m SUPERDude
    If at any point the search term is found where it isn't all lower-case and it isn't all upper-case (e.g. "EscTemplate"), it will be replaced with what you provide here.
    If you do not provide it, the way you wrote the find name (with -f) will be used, so if you ran the batch file and wrote "SuperDude" then "EscTemplate" will be changed to "SuperDuide", as will "ESCtemplATE", "esctEmplate" and "ESCTEMPLATe".
  • Whether or not to rename files: -n
    If this option is provided, any file and directory in the search criteria (i.e. that fits the "-p" pattern (if given) and doesn't fit the "-x" pattern (if given)) will also have its name changed in the exact same manner (preserves case, though that has very little meaning on Windows).
  • A request to halt the process if an error occurs: -b
  • A request for the script to tell you what it's doing as it does it: -v
    This will show you which files are changed, how many replacements were made in them, which files were renamed, etc.


  • python CaseReplace.py -f ThisDude -r ThatDude -p **/*.scml
    Replaces "ThisDude" with "ThatDude" with case preservation in every SCML (Spriter) file without changing any names.
  • python CaseReplace.py -f wilson -r SpongeBob -n -p **/*.lua
    Replaces "wilson" with "spongebob" with case preservation in every Lua script file while also changing the names of the files (e.g. "SGwilson" will become "SGspongebob").
  • python CaseReplace.py -f superman -r clarkkent -m "Clark Kent" -n -p **/*.lua -x **metropolis**
    Replaces "superman" with "clarkkent" in all Lua script files that don't have the word "metropolis" in their name or path (so everything under a "metropolis" folder will also be skipped).
    This one will also change "Superman" to "Clark Kent" (with a space).
    Not something you usually want to do, but it can be useful, for example, if you only have "Superman" in mixed-case inside descriptions and speech lines, and there you would want to replace it with "Clark Kent" and not "clarkkent" or "ClarkKent".


Where to Get It


You're most welcome to ask any questions if you have them, and also tell me if you encounter a bug or have a suggestion.

Happy modding! =D

Edited by Clopen
Link to comment
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

  • Create New...