this is my first tutorial since a long time, but I felt like this information needs to be shared because I just went through this painful procedure. Might be useful for somebody! :D
What is a library?
A library is a collection of code with a certain functionality. A library can be imported into any map and be used afterwards.
However, libraries are also required when working with MOD-Files, since all script within mods needs to be within a library. So if your map makes use of mods containing script, you are also automatically using libraries! :)
What is a library ID?
Each Starcraft library has a certain ID associated with it. The ID is necessary to avoid naming conflicts between libraries and to improve organization of code.
The library ID can have 2 formats:
1. Hexadezimal (This is the default)
2. Four Character
For example, the native Starcraft 2 library has the id "ntve", which obviously is an abbreviation of "native" to match the four character format.
Why would you want to change a library ID?
By default, the editor creates new libraries using a hexadezimal ID. This is because it minimizes the chance of two libraries having the same ID and therefore its very unlikely to get naming conflics when using multiple user libraries from the community.
However, a hexadezimal ID has 3 big disadvantages:
- Its non descriptive of the libraries functionality and very hard to remember
- Its hard to read and clutters the galaxy source code
- Its longer than the four character format, and therefore increases the size of triggers.xml and script.galaxy files within projects using them. (This may not seem like a big deal, but the triggers.xml file as an example can get HUGE for big projects)
How to change the library ID?
This tutorial assumes that you have created and used a library with a hexadezimal ID and want to change it to a four character ID, but it also works the other way around. :)All following steps assume that your current library ID is "FFFFFFFF" (hexadezimal) and it shall be changed to "TEST" (four character) to make it easier to read, but it also works for all other possible library IDs.
IMPORTANT: BEFORE YOU START, MAKE SURE TO BACKUP ALL IMPORTANT FILES! IM NOT RESPONSABLE TO ANY DAMAGE TO YOUR PROJECT!
Step 1: Fixing your custom script
This step may not be neccesary for everyone, but if you have used custom script at any point within your library referrencing GUI stuff you need to perform it first.
1. Save your library/Mod as SC2Components file
2. Open the created folder and search for a file named "Triggers" within the root folder
3. By using a text editor, search for "libFFFFFFFF" and replace it with "libTEST" (Important: Add the lib prefix to just replace custom script referrences!)
4. Save the file
We now fixed all custom script references and make them use the new library ID.
Step 2: Change the library ID
If you have performed Step 1, open your SC2Components folder with the Starcraft II editor.
Make sure to pay close attention to the Editor Console. If it displays any unusual errors, such as "invalid trigger reference removed", you eventually messed something up editing the Triggers.xml file in Step 1. In this case, repeat Step 1 and try again.
You will notice that you can NOT compile the script any longer due to trigger errors, but don't worry.
If you did not perform Step 1, simply open your Library/Mod file directly.
1. Right click on your library and select Library -> Change Library ID from the menu
2. Simply click on "Four Character" and enter "TEST" as your new library ID.
3. Force a complete recompile of the source code. To do that, simply copy paste a random trigger and delete it afterwards, to make the editor think something got changed. Now simply save the project.
Step 3: Fixing localization and Strings
One could assume that we are done after performing Step 2, but unfortunately there seems to be a bug within the editor which makes changing the library ID not work as intented.
If you reopen your recently changed library you will notice that all trigger, variable and function names are blank and have been reset. You will not be able to use your library properly this way, so we need to fix it! :D
DO NOT SAVE WHILE THE PROJECT IS IN THIS STATE!
1. Again open your .SC2Components folder and search for a folder named "enUS.SC2Data" within the root folder (Please note that depending on your game language the folder name may be different, such as "deDE.SC2Data" for the german client. The folder always has the name of the primary locale. You may also have more than one localization folder, in this case you need to perform the following steps for ALL of them)
3. Open "LocalizedData" subfolder
4. Open the file "TriggerStrings.txt" with a text editor
5. Replace all "lib_FFFFFFFF" with "lib_TEST" (please note the "_" between lib and library ID)
6. Save the file.
7. Locate and open a file called "GameStrings.txt"
8. Replace all "lib_FFFFFFFF" with "lib_TEST" (please note the "_" between lib and library ID)
9. Save the file.
10. Open the components folder with your editor
11. Check if the blank names have disappeared and are displayed properly again
12. If so, again force a complete recompile of the script by changing random stuff and save the project as .SC2Mod or .SC2Library
13. In case you get some rare compilation errors due to blank variable names, simply rename the variable by pressing F2 in the editor. For some reason this happened to one of my variables in over 100k lines of code, im not sure why.
Congratulations! You have successfully changed your library ID! However, there are additional steps which need to be performed if you already used your library in any of your projects.
When trying to open a project referencing the recently changed library it will throw errors at you and basically completely wipe all library data from the project, since the referrences can no longer be resolved. This is because the Triggers.xml file within your project finds the library by looking for its ID.
Step 4: Fix all your projects using the recently changed library
1. Open your project using the import manager (Important: Do not open the trigger window, otherwise the project will delete all library references.)
2. Save the project as SC2Components folder
3. Locate and open the folder and again search for "Triggers.xml" within the root directory
4. Now, find and replace "FFFFFFFF" with "TEST". (This time we do NOT add a lib or lib_ prefix)
5. Save the file.
Now, reopen the project by loading the components folder into the editor. You should no longer receive errors within the editor console and all trigger references should be resolved properly.
Force a recompile of the script and save the project as .SC2Map/.SC2Mod
Congratulations! You are finally done!
Now make sure to double check your work by loading a project using your new library within Starcraft 2. Using the trigger debug window you can now check for your new library ID. (For example, all functions under "Function profiling" which are part of your library should now start with "libTEST".
If your library was part of a mod file and you have trouble loading a project referencing this mod, try to test the project from the mod itself by using Test Document. Starcraft has a weird caching mechanism which sometimes doesnt update the mod files properly when trying to launch a project referrencing them, and therefore you may see a script load failure due to wrong identifiers.
Also remember to reupload all your projects to battle.net after uploading your changed library/Mod, since otherwise they will fail to load.
Hey guys,
this is my first tutorial since a long time, but I felt like this information needs to be shared because I just went through this painful procedure. Might be useful for somebody! :D
What is a library?
A library is a collection of code with a certain functionality. A library can be imported into any map and be used afterwards.
However, libraries are also required when working with MOD-Files, since all script within mods needs to be within a library. So if your map makes use of mods containing script, you are also automatically using libraries! :)
What is a library ID?
Each Starcraft library has a certain ID associated with it. The ID is necessary to avoid naming conflicts between libraries and to improve organization of code.
The library ID can have 2 formats:
1. Hexadezimal (This is the default)
2. Four Character
For example, the native Starcraft 2 library has the id "ntve", which obviously is an abbreviation of "native" to match the four character format.
Why would you want to change a library ID?
By default, the editor creates new libraries using a hexadezimal ID. This is because it minimizes the chance of two libraries having the same ID and therefore its very unlikely to get naming conflics when using multiple user libraries from the community.
However, a hexadezimal ID has 3 big disadvantages:
- Its non descriptive of the libraries functionality and very hard to remember
- Its hard to read and clutters the galaxy source code
- Its longer than the four character format, and therefore increases the size of triggers.xml and script.galaxy files within projects using them. (This may not seem like a big deal, but the triggers.xml file as an example can get HUGE for big projects)
How to change the library ID?
This tutorial assumes that you have created and used a library with a hexadezimal ID and want to change it to a four character ID, but it also works the other way around. :) All following steps assume that your current library ID is "FFFFFFFF" (hexadezimal) and it shall be changed to "TEST" (four character) to make it easier to read, but it also works for all other possible library IDs.
IMPORTANT: BEFORE YOU START, MAKE SURE TO BACKUP ALL IMPORTANT FILES! IM NOT RESPONSABLE TO ANY DAMAGE TO YOUR PROJECT!
Step 1: Fixing your custom script
This step may not be neccesary for everyone, but if you have used custom script at any point within your library referrencing GUI stuff you need to perform it first.
1. Save your library/Mod as SC2Components file
2. Open the created folder and search for a file named "Triggers" within the root folder
3. By using a text editor, search for "libFFFFFFFF" and replace it with "libTEST" (Important: Add the lib prefix to just replace custom script referrences!)
4. Save the file
We now fixed all custom script references and make them use the new library ID.
Step 2: Change the library ID
If you have performed Step 1, open your SC2Components folder with the Starcraft II editor.
Make sure to pay close attention to the Editor Console. If it displays any unusual errors, such as "invalid trigger reference removed", you eventually messed something up editing the Triggers.xml file in Step 1. In this case, repeat Step 1 and try again.
You will notice that you can NOT compile the script any longer due to trigger errors, but don't worry.
If you did not perform Step 1, simply open your Library/Mod file directly.
1. Right click on your library and select Library -> Change Library ID from the menu
2. Simply click on "Four Character" and enter "TEST" as your new library ID.
3. Force a complete recompile of the source code. To do that, simply copy paste a random trigger and delete it afterwards, to make the editor think something got changed. Now simply save the project.
Step 3: Fixing localization and Strings
One could assume that we are done after performing Step 2, but unfortunately there seems to be a bug within the editor which makes changing the library ID not work as intented.
If you reopen your recently changed library you will notice that all trigger, variable and function names are blank and have been reset. You will not be able to use your library properly this way, so we need to fix it! :D
DO NOT SAVE WHILE THE PROJECT IS IN THIS STATE!
1. Again open your .SC2Components folder and search for a folder named "enUS.SC2Data" within the root folder (Please note that depending on your game language the folder name may be different, such as "deDE.SC2Data" for the german client. The folder always has the name of the primary locale. You may also have more than one localization folder, in this case you need to perform the following steps for ALL of them)
3. Open "LocalizedData" subfolder
4. Open the file "TriggerStrings.txt" with a text editor
5. Replace all "lib_FFFFFFFF" with "lib_TEST" (please note the "_" between lib and library ID)
6. Save the file.
7. Locate and open a file called "GameStrings.txt"
8. Replace all "lib_FFFFFFFF" with "lib_TEST" (please note the "_" between lib and library ID)
9. Save the file.
10. Open the components folder with your editor
11. Check if the blank names have disappeared and are displayed properly again
12. If so, again force a complete recompile of the script by changing random stuff and save the project as .SC2Mod or .SC2Library
13. In case you get some rare compilation errors due to blank variable names, simply rename the variable by pressing F2 in the editor. For some reason this happened to one of my variables in over 100k lines of code, im not sure why.
Congratulations! You have successfully changed your library ID! However, there are additional steps which need to be performed if you already used your library in any of your projects.
When trying to open a project referencing the recently changed library it will throw errors at you and basically completely wipe all library data from the project, since the referrences can no longer be resolved. This is because the Triggers.xml file within your project finds the library by looking for its ID.
Step 4: Fix all your projects using the recently changed library
1. Open your project using the import manager (Important: Do not open the trigger window, otherwise the project will delete all library references.)
2. Save the project as SC2Components folder
3. Locate and open the folder and again search for "Triggers.xml" within the root directory
4. Now, find and replace "FFFFFFFF" with "TEST". (This time we do NOT add a lib or lib_ prefix)
5. Save the file.
Now, reopen the project by loading the components folder into the editor. You should no longer receive errors within the editor console and all trigger references should be resolved properly.
Force a recompile of the script and save the project as .SC2Map/.SC2Mod
Congratulations! You are finally done!
Now make sure to double check your work by loading a project using your new library within Starcraft 2. Using the trigger debug window you can now check for your new library ID. (For example, all functions under "Function profiling" which are part of your library should now start with "libTEST".
If your library was part of a mod file and you have trouble loading a project referencing this mod, try to test the project from the mod itself by using Test Document. Starcraft has a weird caching mechanism which sometimes doesnt update the mod files properly when trying to launch a project referrencing them, and therefore you may see a script load failure due to wrong identifiers.
Also remember to reupload all your projects to battle.net after uploading your changed library/Mod, since otherwise they will fail to load.