AutoHotkey as a Modding Tool
For those who are not familiar with it, Autohotkey is a fantastic open source program designed to replicate repetitive keyboard or mouse actions. As with any sort of coding, the possibilities are technically limitless, but so far I have used small script (about 20 lines) to save and open new exemplars in LeProp, and add/remove properties dozens of props in the Reader. What would have taken probably 20-30 minutes, one is able to achieve in under 5 seconds!
As I said above, the possibilities are limitless, so I will make this tutorial as general as possible while showing examples of scripts I have created.
This tutorial will be continuously updated as suggestions for inclusions are offered.
Introduction
This tutorial is aimed towards any custom content creator who regularly, or semi-regularly has to perform repetitive tasks in the Reader or any other application. Simple text scripts can be used to quickly and easily automate such tasks. Skills learned can also be applied to any program or procedure outside of Sc4 also.
This tutorial is worded simply so those with zero programming experience can complete their first script. This tutorial only covers a few of the basics. There are hundreds of more advanced functions for more experienced users. The AutoHotkey Help file is a great resource for this.
Getting Started
Download AutoHotkey here. You will notice that there is no interface to start up and code into. This is because everything is done through simple text files.
The first step is to identify a procedure you would like to automate, for example, adding Prop Family properties for a collection of 80 props. You will need to know exactly what you are doing for the task at hand. As you go through the process manually for the first few times, make careful notes of when and where you click, what you type in, etc. It may be helpful to write a procedure down on paper as you go.
The second step is to create a new *.txt file that will be used for the script. It is not important at all what it is named or where it is placed. As long as its file extension is changed to *.ahk at some point, it will become associated with Autohotkey and everything will work fine.
Sending Key Presses
The most basic command is the Send command. Typing
Send asdf
will, upon execution of the script, will type out asdf automatically. Not very useful you say? Yes, you’re right.
Some special keys can be activated by enclosing their name in braces { }. Be careful here. Typing
Send Enter
will literally type out Enter as text: that is, the letter “E” followed by “n,” “t,” “e,” “r.” This does NOT have the same effect as pressing the enter button (obviously, typing “Enter” into Word will not put the cursor on a new line – the same concept applies to scripts). To simulate pressing the Enter button,
Send {Enter}
should be used instead. Other examples include {Shift}, {Delete}, {Tab}, etc.; for the arrow keys, {Up}, {Down}, {Left}, {Right} are the appropriate commands. Any of the other special keys are called using special characters instead:
! .......... Alt
#.......... Windows
+.......... Shift
& ......... Used to combine two keys to a single new one (eg. f&g = hold “f” and press “g”)
^ ......... Ctrl
< , > .... If there are a pair of keys, <! Signifies Left Alt and >! Signifies Right Alt; ! would trigger when any Alt is pressed, for example. From this, we can refine our script a little more: !u:: Send asdf Will type “asdf” when Alt and the 'u' key is pressed. A little more useful, don’t you think? Note the double colon after the statement. This demarks the start of the code that will be executed when those buttons are pressed. Adding a return demarks the end of the code for that hotkey. For simple scripts, it is not strictly needed, but for good practice, we will amend the code to include it anyways: !u:: Send asdf return Sending Mouse Clicks Every page can technically be operated without a mouse, but using 50 Tabs or Shift-Tabs to advance focus to the button you are looking for is inefficient, time-consuming, and dumb. There are numerous ways to do this; by far the simplest method is to use mouse clicks. The syntax Click xx, yy or, for a right click, Click right xx, yy simulates a left or right click at xx and yy, where xx and yy are the x and y coordinates of the button on the window you are using. Figuring out these coordinates will probably be the most time-consuming part. Fortunately, there is a tool which comes packaged with AHK that makes this process simple. Navigate to the AHK installation folder and run au3_spy.exe (or type it in the start menu). Among other things, the program will give you a live readout of the x and y coordinates of your mouse pointer for the current window and your overall screen. USE THE COORDINATES FOR THE CURRENT WINDOW. The “On Screen” coordinates are marked “less often used,” which is apt. You want to use the mouse position in the active window for numerous reasons, the largest being that if you drag the window around your screen, the Active Window coordinates will remain constant while the Screen coordinates will change. This is where careful notes come in handy. Going through the process manually with au3_spy open in the background, recording somewhere the x and y coordinates of any buttons needed in your task. For example, we could write a script that (in notepad) will paste something from the clipboard with minimal effort: !u:: Click right Send {Down}{Down}{Down}{Down}{Enter} return NOTE: In the example above, it is possible to use a mouse click to press the paste button instead of pressing Down 4x and enter, however, this method will be dependent on coordinates of the initial right click. Thus, many times it may be easier to chain arrow key commands instead of locating mouse positions. To transition to the next topic, suppose we have the following code: #s:: Click right Send {Down}{Down}{Down}{Enter}{Enter} return Which, when run on my internet browser (Chrome) will right click where the cursor is, open the save dialog box, and hit “Enter” to finalize the save. Run it, and you will notice that it does not entirely do what we want it to do. It will open the save dialog box, but the second enter (to finalize the save) does not seem to execute. This is a simple error in timing. When the script executes, all of the commands are sent instantaneously. This is the ideal condition; in real life, however, it takes some amount of time to do everything. Even a time of fractions of a millisecond is enough to throw your code off. If you manually right click and hit save, there will indeed be a small delay until the dialog box appears. Syncing everything may seem like a difficult fix, but the code required is quite simple. Opening New Windows AHK sends its commands very quickly (as it is supposed to do). If click on any buttons that activate new windows or dialog boxes, you may run into problems. As mentioned above, the script will execute correctly, but not as intended; rather, it will send some (or all) of the commands in the time it takes for the message box to appear and become active. The solution is to wait until the new window is active and ready for input. Simply use the command Winwait, xxxxxx where xxxxxx is the full or partial title of the window. It is important to note that this string can either be the full exact title or just the first few characters. For example, if I am editing a file called nos.17_VehiculosFamilias_1c90deg.dat, I could type Winwait, nos.17 Using just “nos.17” is enough for the script to recognize which window it is waiting on. If the title is not explicitly stated in the window like it is below, Windows Task Manager can give you the appropriate name. Remember, only the first part of a window name is required. If the name is long or complex, the first few letters should suffice. Loops To repeat tasks multiple times, one could either copy and paste the commands the necessary number of times, or use loops. Loops, if you are not familiar with them, will simply repeat the tasks within the braces { } a specified number of times for example, Loop, 4 { Send ^v Send {Enter} } would paste whatever is in the clipboard five times on a new line (another description). For obvious reasons, this method is preferred for larger numbers but is also easier to read and debug for small numbers (like 4) too. NOTE: The number in the loop control starts at 0. So if you want something to happen 4 times you will need to enter 3 (0 1 2 3), and so on. The general equation for the number of times you want to loop: n-1. If you’re interested why, (1) and (2); if not, just try and remember that. Comments Comments are used for your convenience. Comments are bodies of text that the computer skips over and will not execute - their purpose is to either explain what should happen when some code executes or anything else the programmer wants to say. As such, they are never required but always recommended. In AutoHotkey, everything after a semicolon (;) on the same line will not parse (they will be completely ignored by the computer). An example: Click 380,590 ; Click Apply Everything after the semicolon ( Click Apply) will be ignored by the computer. It is only for my benefit to remember what each line is supposed to do. Comments in no way are required on every line. I've merely included them for sake of clarity so others can read my code. Saving and Running the Script Whenever you are finished. Simply save your notepad document. If you haven’t already, change the extension from *.txt to *.ahk. Windows might give you a warning telling you that changing the extension may make the file unstable – this is generally a good warning but not applicable here and can be ignored. Changing *.txt to *.ahk will in no way change anything in the file – it will simply associate that file as an AutoHotkey script instead of a lowly text file. Once the file is renamed, right click on it and you should see some additional options in the menu. “Run Script” will make the script become active. Hit whatever hotkey(s) you assigned, and your script will execute every time you press the key(s). You will see an icon appear in your system tray. Right clicking there will allow you to do a few different things, including closing the script so it will no longer run (Exit). “Compile Script” will automatically convert the script to a *.exe file. It can be exited in the same fashion from the system tray. “Edit Script” opens the notepad file and allows the script to be edited. Note that just double clicking like normal to open the file actually has the same effect of “Run Script.” This is one of the other results of changing the file extension to *.ahk. “Open” “Help” opens the AutoHotkey help documents which can be a great help in finding the correct syntax. “Window Spy” launches au3_spy.exe. See the "Sending Mouse Clicks" subsection for an explanation of its purpose. “Reload This Script” recompiles the script. If any changes were made, they will now be active. “Edit This Script” opens the notepad file and allows the script to be edited in whichever editor you assigned as default for the *.ahk extension. “Suspend Hotkeys” will keep the script active but disable any hotkeys mapped within the script. Useful if the key combination you assigned is actually used in some other program. The H tray icon will be replaced with a similar looking icon, but with an S. “Pause Script” prevents any part of the script from running until it is manually resumed. The tray icon will be replaced with a red one. “Compile Script” will automatically convert the script to a *.exe file. It can be exited in the same fashion from the system tray. “Exit” completely closes and ends the AutoHotkey process. Examples There is simply an immense amount of things one can do with AutoHotkey scripts. However, the things outlined above should be enough to complete most of your scripts for SC4 modding (they’re all I’ve used so far). To make your own, identify something repetitive that you do that can be easily scripted. The two examples below detail my method of solving these problems. As with coding, a multitude of approaches exist, and the only incorrect one is the one that does not work (or perhaps takes an inordinate amount of time). LeProp_SaveClose.ahk
For those that do not know, LeProp has a peculiar bug where it can only save one action at a time. As such, one needs to close and reopen to edit multiple things on a lot. It can be quite tedious having to save, close, navigate to, and run the LeProp executable. This script is designed to fix that. !x:: Click 380,590 ; Click Apply Click 550,120 ; Click Save WinWaitActive, LEProp ; Wait for “Save Successful!” dialogue box Send {Enter} ; Closes “Save Successful!” dialogue box WinWaitActive, iLive ; Waits for main window to be active (“Save Successful!” dialogue box is fully closed) Send {Esc} ; Close LeProp run, C:\Program Files (x86)\iLives\LEProp.exe ; Opens LeProp WinWaitActive, Ilive ; Waits for main window to be active Send {Enter} ; Opens the “Open File” window Reader_Add_BuildingPropFamily.ahk #a:: ; Hit Windows-a to activate Click right 1200, 600 ; Right click in the right pane Send {Down} {Down} {Down} {Down} {Enter} ; Select “Add Property” WinWaitActive, Property : ; Wait for Property editor to appear Click 425, 50 ; Click to expand the Name menu Send buil ; Type to scroll list to Building/prop Family Click 250, 105 ; Select Building/prop Family Click 450, 255 ; Select Add Click 40, 635 ; Click in the Values as text field Click 40, 635 ; Not sure why I have this twice Send 0x5f85e126 ; Your prop family IID goes here Click 435, 635 ; Hit first Apply Click 190, 700 ; Hit Second Apply WinWaitActive, Reader ; Change to Reader main window name; partial name is acceptable Click 1200, 235 ; Click on Building/prop family property Send ^c ; Copies that property to the clipboard Click 870, 1000 ; Click to place focus in the left pane Send {Down} ; Move down to select next exemplar Loop, 257 ; Change to number of exemplars starting count at 0: e.g. if last num is 65, use 66 { Click 1200, 600 ; Click to place focus in the right pane Send ^v ; Paste the property Click 870, 1000 ; Click to place focus in the left pane Send {Down} ; Move down to select next exemplar } ; Repeat Conclusion If anyone has questions or needs help on their scripts, I will be happy to help. If I don't start a thread, just shoot me a PM and we can work out your problems together. Happy modding! ...
#.......... Windows
+.......... Shift
& ......... Used to combine two keys to a single new one (eg. f&g = hold “f” and press “g”)
^ ......... Ctrl
< , > .... If there are a pair of keys, <! Signifies Left Alt and >! Signifies Right Alt; ! would trigger when any Alt is pressed, for example. From this, we can refine our script a little more: !u:: Send asdf Will type “asdf” when Alt and the 'u' key is pressed. A little more useful, don’t you think? Note the double colon after the statement. This demarks the start of the code that will be executed when those buttons are pressed. Adding a return demarks the end of the code for that hotkey. For simple scripts, it is not strictly needed, but for good practice, we will amend the code to include it anyways: !u:: Send asdf return Sending Mouse Clicks Every page can technically be operated without a mouse, but using 50 Tabs or Shift-Tabs to advance focus to the button you are looking for is inefficient, time-consuming, and dumb. There are numerous ways to do this; by far the simplest method is to use mouse clicks. The syntax Click xx, yy or, for a right click, Click right xx, yy simulates a left or right click at xx and yy, where xx and yy are the x and y coordinates of the button on the window you are using. Figuring out these coordinates will probably be the most time-consuming part. Fortunately, there is a tool which comes packaged with AHK that makes this process simple. Navigate to the AHK installation folder and run au3_spy.exe (or type it in the start menu). Among other things, the program will give you a live readout of the x and y coordinates of your mouse pointer for the current window and your overall screen. USE THE COORDINATES FOR THE CURRENT WINDOW. The “On Screen” coordinates are marked “less often used,” which is apt. You want to use the mouse position in the active window for numerous reasons, the largest being that if you drag the window around your screen, the Active Window coordinates will remain constant while the Screen coordinates will change. This is where careful notes come in handy. Going through the process manually with au3_spy open in the background, recording somewhere the x and y coordinates of any buttons needed in your task. For example, we could write a script that (in notepad) will paste something from the clipboard with minimal effort: !u:: Click right Send {Down}{Down}{Down}{Down}{Enter} return NOTE: In the example above, it is possible to use a mouse click to press the paste button instead of pressing Down 4x and enter, however, this method will be dependent on coordinates of the initial right click. Thus, many times it may be easier to chain arrow key commands instead of locating mouse positions. To transition to the next topic, suppose we have the following code: #s:: Click right Send {Down}{Down}{Down}{Enter}{Enter} return Which, when run on my internet browser (Chrome) will right click where the cursor is, open the save dialog box, and hit “Enter” to finalize the save. Run it, and you will notice that it does not entirely do what we want it to do. It will open the save dialog box, but the second enter (to finalize the save) does not seem to execute. This is a simple error in timing. When the script executes, all of the commands are sent instantaneously. This is the ideal condition; in real life, however, it takes some amount of time to do everything. Even a time of fractions of a millisecond is enough to throw your code off. If you manually right click and hit save, there will indeed be a small delay until the dialog box appears. Syncing everything may seem like a difficult fix, but the code required is quite simple. Opening New Windows AHK sends its commands very quickly (as it is supposed to do). If click on any buttons that activate new windows or dialog boxes, you may run into problems. As mentioned above, the script will execute correctly, but not as intended; rather, it will send some (or all) of the commands in the time it takes for the message box to appear and become active. The solution is to wait until the new window is active and ready for input. Simply use the command Winwait, xxxxxx where xxxxxx is the full or partial title of the window. It is important to note that this string can either be the full exact title or just the first few characters. For example, if I am editing a file called nos.17_VehiculosFamilias_1c90deg.dat, I could type Winwait, nos.17 Using just “nos.17” is enough for the script to recognize which window it is waiting on. If the title is not explicitly stated in the window like it is below, Windows Task Manager can give you the appropriate name. Remember, only the first part of a window name is required. If the name is long or complex, the first few letters should suffice. Loops To repeat tasks multiple times, one could either copy and paste the commands the necessary number of times, or use loops. Loops, if you are not familiar with them, will simply repeat the tasks within the braces { } a specified number of times for example, Loop, 4 { Send ^v Send {Enter} } would paste whatever is in the clipboard five times on a new line (another description). For obvious reasons, this method is preferred for larger numbers but is also easier to read and debug for small numbers (like 4) too. NOTE: The number in the loop control starts at 0. So if you want something to happen 4 times you will need to enter 3 (0 1 2 3), and so on. The general equation for the number of times you want to loop: n-1. If you’re interested why, (1) and (2); if not, just try and remember that. Comments Comments are used for your convenience. Comments are bodies of text that the computer skips over and will not execute - their purpose is to either explain what should happen when some code executes or anything else the programmer wants to say. As such, they are never required but always recommended. In AutoHotkey, everything after a semicolon (;) on the same line will not parse (they will be completely ignored by the computer). An example: Click 380,590 ; Click Apply Everything after the semicolon ( Click Apply) will be ignored by the computer. It is only for my benefit to remember what each line is supposed to do. Comments in no way are required on every line. I've merely included them for sake of clarity so others can read my code. Saving and Running the Script Whenever you are finished. Simply save your notepad document. If you haven’t already, change the extension from *.txt to *.ahk. Windows might give you a warning telling you that changing the extension may make the file unstable – this is generally a good warning but not applicable here and can be ignored. Changing *.txt to *.ahk will in no way change anything in the file – it will simply associate that file as an AutoHotkey script instead of a lowly text file. Once the file is renamed, right click on it and you should see some additional options in the menu. “Run Script” will make the script become active. Hit whatever hotkey(s) you assigned, and your script will execute every time you press the key(s). You will see an icon appear in your system tray. Right clicking there will allow you to do a few different things, including closing the script so it will no longer run (Exit). “Compile Script” will automatically convert the script to a *.exe file. It can be exited in the same fashion from the system tray. “Edit Script” opens the notepad file and allows the script to be edited. Note that just double clicking like normal to open the file actually has the same effect of “Run Script.” This is one of the other results of changing the file extension to *.ahk. “Open” “Help” opens the AutoHotkey help documents which can be a great help in finding the correct syntax. “Window Spy” launches au3_spy.exe. See the "Sending Mouse Clicks" subsection for an explanation of its purpose. “Reload This Script” recompiles the script. If any changes were made, they will now be active. “Edit This Script” opens the notepad file and allows the script to be edited in whichever editor you assigned as default for the *.ahk extension. “Suspend Hotkeys” will keep the script active but disable any hotkeys mapped within the script. Useful if the key combination you assigned is actually used in some other program. The H tray icon will be replaced with a similar looking icon, but with an S. “Pause Script” prevents any part of the script from running until it is manually resumed. The tray icon will be replaced with a red one. “Compile Script” will automatically convert the script to a *.exe file. It can be exited in the same fashion from the system tray. “Exit” completely closes and ends the AutoHotkey process. Examples There is simply an immense amount of things one can do with AutoHotkey scripts. However, the things outlined above should be enough to complete most of your scripts for SC4 modding (they’re all I’ve used so far). To make your own, identify something repetitive that you do that can be easily scripted. The two examples below detail my method of solving these problems. As with coding, a multitude of approaches exist, and the only incorrect one is the one that does not work (or perhaps takes an inordinate amount of time). LeProp_SaveClose.ahk
For those that do not know, LeProp has a peculiar bug where it can only save one action at a time. As such, one needs to close and reopen to edit multiple things on a lot. It can be quite tedious having to save, close, navigate to, and run the LeProp executable. This script is designed to fix that. !x:: Click 380,590 ; Click Apply Click 550,120 ; Click Save WinWaitActive, LEProp ; Wait for “Save Successful!” dialogue box Send {Enter} ; Closes “Save Successful!” dialogue box WinWaitActive, iLive ; Waits for main window to be active (“Save Successful!” dialogue box is fully closed) Send {Esc} ; Close LeProp run, C:\Program Files (x86)\iLives\LEProp.exe ; Opens LeProp WinWaitActive, Ilive ; Waits for main window to be active Send {Enter} ; Opens the “Open File” window Reader_Add_BuildingPropFamily.ahk #a:: ; Hit Windows-a to activate Click right 1200, 600 ; Right click in the right pane Send {Down} {Down} {Down} {Down} {Enter} ; Select “Add Property” WinWaitActive, Property : ; Wait for Property editor to appear Click 425, 50 ; Click to expand the Name menu Send buil ; Type to scroll list to Building/prop Family Click 250, 105 ; Select Building/prop Family Click 450, 255 ; Select Add Click 40, 635 ; Click in the Values as text field Click 40, 635 ; Not sure why I have this twice Send 0x5f85e126 ; Your prop family IID goes here Click 435, 635 ; Hit first Apply Click 190, 700 ; Hit Second Apply WinWaitActive, Reader ; Change to Reader main window name; partial name is acceptable Click 1200, 235 ; Click on Building/prop family property Send ^c ; Copies that property to the clipboard Click 870, 1000 ; Click to place focus in the left pane Send {Down} ; Move down to select next exemplar Loop, 257 ; Change to number of exemplars starting count at 0: e.g. if last num is 65, use 66 { Click 1200, 600 ; Click to place focus in the right pane Send ^v ; Paste the property Click 870, 1000 ; Click to place focus in the left pane Send {Down} ; Move down to select next exemplar } ; Repeat Conclusion If anyone has questions or needs help on their scripts, I will be happy to help. If I don't start a thread, just shoot me a PM and we can work out your problems together. Happy modding! ...
-
-
- 6 Comments
