Tutorial; NewResearchItem - HWRM/KarosGraveyard GitHub Wiki
How to Create a New Research Item by Ranger.
The following tutorial describes how to create a new research item.
This tutorial assumes that you have the undumped Lua files unzipped into your game's "Data" directory and that you have a basic understand of Microsoft Windows operations.
A research item can unlock a new ship, upgrade one of a ship's stats, add a new weapon to a ship, and so on. However, this tutorial will only explain how to create a new item; it will not list every possible research item that can be created. The examples in this tutorial describe how to create a research item that adds the anti-ship bomb launcher from the Hiigaran Attack Bomber to the Hiigaran Interceptor, and assumes that the game is installed in the "E:\Homeworld2" directory.
1. Go to the game's "Data\scripts\building and research\<race>" directory, where <race> is the name of the race for which you want to add the research item. E.g., "E:\Homeworld2\data\scripts\building and research\hiigaran".
2. Open the "research.lua" file with a text editor and find a block of research code that is most similar to what you want to create, if such a thing exists. This is to reduce confusion and the number of things that you must edit. For example, if you want to give a ship the Hiigaran Scout's ping ability, then search for the word "ping" to find the corresponding research code. A block of research code is that which starts with a left brace ({) and ends with a right brace that is followed by a comma (},). If there is no existing research item that is similar to what you want to create, then any code block will do. In the example of adding the anti-ship bomb launcher to the Interceptor, search for the code block shown below:
{
Name = "AttackBomberImprovedBombs",
RequiredResearch = "",
RequiredSubSystems = "Research | AdvancedResearch",
Cost = 1500,
Time = 45,
DisplayedName = "$7517",
DisplayPriority = 30,
Description = "$7518",
UpgradeType = Ability,
TargetType = Ship,
TargetName = "Hgn_AttackBomber",
UpgradeName = "UseSpecialWeaponsInNormalAttack",
Icon = Icon_Ability,
ShortDisplayedName = "$7208",
},Looking at the code from top to bottom, this research item has a Name of AttackBomberImprovedBombs, which is the game's internal name that is used when calling this code. The Name value is never seen by the player during the game, and therefore can have any logical value. The RequiredResearch variable indicates that this item does not require any other research to be completed before it can be researched. The RequiredSubSystems variable indicates that the item requires you to have either the Research Module or Advanced Research Module before it can be researched. According to the Cost and Time variables, it costs 1500 RU and takes 45 seconds to complete the research. The DisplayedName value is a string reference to text defined in the "buildresearch.ucs" file. The DisplayPriority value is 30, which determines in what order this research item is displayed in the Research Manager. As with the DisplayedName variable, the Description variable references text defined in the "buildresearch.ucs" file. The UpgradeType variable is set to Ability, meaning that it adds a new ability to the ship, which can be a weapon as in this case. TargetType is set to Ship, meaning that an individual ship will be upgraded. In this case, the Hgn_AttackBomber is upgraded, as specified by TargetName. The UpgradeName variable's name is slightly misleading, as this actually refers to how the new ability is used. In this case, it allows the Attack Bomber to use a special weapon when making a normal attack, as opposed to having the player use the special weapon key to activate the weapon. The icon that is displayed in the Research Manager is defined by the Icon variable, and in this instance is set to Icon_Ability, which is the default icon used for Ability upgrade types. Finally, the ShortDisplayName variable is, as with DisplayedName, a reference to text in the "buildresearch.ucs" file.
See Research Variables for complete definitions and possible values of the variables.
3. Copy the code for which you searched, and paste it at the end of the file before the last } (the only } that is not followed by a comma). This will be modified to become the new research item. Continuing the example, copy the "AttackBomberImprovedBombs" code block and paste it before the last } in the file.
4. Make the appropriate changes to the code to reflect what you want. Refer to the Research Variables page to learn what must be changed to create the desired result. See Modifiable Values for a list of possible modifiers if UpgradeType is Modifier. Some things to consider: the new research item cannot have the same Name nor DisplayPriority as another research item. You can easily discover if a Name or DisplayPriority value is already used simply by searching for those values in the file. Continuing the example, we want to change the Name, DisplayPriority, and TargetName of the copied code, but keep everything else the same so that the Interceptor's new anti-ship bomb research is otherwise identical to the Attack Bomber's research item. Since the names and description should be different to reflect the new ability, we will also change the DisplayedName, Description, and ShortDisplayedName. The new code could be changed as follows:
{
Name = "InterceptorAntiShipBombs",
RequiredResearch = "",
RequiredSubSystems = "Research | AdvancedResearch",
Cost = 1500,
Time = 45,
DisplayedName = "Interceptor Anti-Ship Bombs",
DisplayPriority = 1300,
Description = "<b>Description:</b> Allows the Interceptor to launch anti-ship bombs. \n\n<b>Prerequisites:</b> Research Module.",
UpgradeType = Ability,
TargetType = Ship,
TargetName = "Hgn_Interceptor",
UpgradeName = "UseSpecialWeaponsInNormalAttack",
Icon = Icon_Ability,
ShortDisplayedName = "Anti-Ship Bombs",
},Notice that the DisplayedName, Description, and ShortDisplayedName variables no longer reference the language file and instead have plain text. The modified values were chosen specifically for this example, but you will want to use other text that is specific to your desired result. The DisplayPriority value of 1300 was chose arbitrarily since that value does not already exist. Any integer could have been used as long as no other research item uses it already.
5. Save the file and exit the text editor.
If the research item only applies a multiplier to one of the ship's stats, you can skip directly to the last step.
If the research item adds a new weapon to a ship via research, skip to the New Weapon Steps, starting at step 10.
If the research item adds a new ability to a ship via research, continue with the following steps.
New Ability Steps
6. Go to the game's "Data\ship\<TargetName>" directory, where <TargetName> is the name of the ship for which you want to add the research item, as specified by the TargetName variable in step 4. E.g., "E:\Homeworld2\data\ship\hgn_interceptor".
7. Open the "<TargetName>.ship" file with a text editor. E.g., "hgn_interceptor.ship".
8. Add code to the ".ship" file that corresponds to the ability that you wish to add via research. In most cases, you will use the addAbility function. With the addAbility function, you must set the third parameter to 0, indicating that the ability is gained only after being researched. See the example below.
addAbility(NewShipType,"SensorPing",0,1,10,2.5);
See the addAbility function for more information on the parameters and possible values.
9. Save the file and exit the text editor. You may skip to the last step.
New Weapon Steps
10. For a weapon, this tutorial will assume that you will add an existing weapon. Another tutorial will cover creating a new weapon. Go to the game's "Data\weapon\<weapon>" directory, where <weapon> is the name of that weapon. E.g., "E:\Homeworld2\data\weapon\hgn_antishipbomblauncher".
11. Open the corresponding ".wepn" file with a text editor. E.g., "hgn_antishipbomblauncher.wepn".
12. Check the value of the fifth parameter of the StartWeaponConfig function. If the value is Special Attack, then the weapon will work as is and you can exit the text editor and skip to step 21. Otherwise, continue with the steps in order. Note that the anti-ship bomb launcher already has the Special Attack parameter value, but this weapon will be used regardless throughout the examples for consistency.
13. Close the file and exit the text editor.
14. Go up one directory to the game's "Data\weapon" directory. E.g., "E:\Homeworld2\data\weapon".
15. Make a copy of the appropriate weapon's directory, and paste it to the game's "Data\weapon" directory. You will now have a copy named "Copy of <weapon_dir>", where <weapon_dir> is the individual weapon's directory name. E.g., copy the "hgn_antishipbomblauncher" directory, and paste it to "E:\Homeworld2\data\weapon". This will result in a new directory named "Copy of hgn_antishipbomblauncher".
16. Rename the new directory to something that corresponds to your weapon, while removing Copy of from the name. Sometimes, simply adding a 2 (or higher number) at the end of the name is good enough. E.g., rename "Copy of hgn_antishipbomblauncher" to "hgn_interceptorbomblauncher".
17. Go to the new weapon's directory, and rename the ".wepn" file to the same name chosen in the previous step. E.g., rename "hgn_antishipbomblauncher.wepn" to "hgn_interceptorbomblauncher.wepn".
18. Open the ".wepn" file with a text editor. E.g., "hgn_interceptorbomblauncher.wepn".
19. Set the fifth parameter of the StartWeaponConfig function to Special Attack. E.g.:
StartWeaponConfig(NewWeaponType, "Gimble", "Bullet", "Plasma_Bomb", "Special Attack", 1200, 1800, 0, 0, 0, 0, 1, 1, 0, 2.1, 0, 0, 0, 0, 260, 40, 0.1, "Normal", 0, 0, 0)
20. Save the file and exit the text editor.
21. Go to the game's "Data\ship\<TargetName>" directory, where <TargetName> is the name of the ship for which you want to add the research item, as specified by the TargetName variable in the research code block in step 4. E.g., "E:\Homeworld2\data\ship\hgn_interceptor".
22. Open the "<TargetName>.ship" file with a text editor. E.g., "hgn_interceptor.ship".
23. Add the weapon as you would any other weapon using the StartShipWeaponConfig function. No special values must be set for purposes of marking this as a special attack. This step is easiest to do if you copy one of the existing StartShipWeaponConfig functions, paste it, and edit the parameters. See the StartShipWeaponConfig function for more information on the parameters and possible values. E.g.:
StartShipWeaponConfig(NewShipType,"Hgn_InterceptorBombLauncher","Weapon_FrontGun","Fire");
Note: There is actually more that should be edited for best results when adding new weapons to a ship, namely the events in the ".events" file, but that will be covered in another tutorial.
24. If the new weapon is added with an UpgradeName of "Special Attack" (see Research Variables), you must also add the following code to the .ship file:
addAbility(NewShipType,"SpecialAttack",0,"<Special_Attack_Name>")
<Special_Attack_Name> is the name of the special attack as defined in the specialattacks.lua file. E.g.:
addAbility(NewShipType,"SpecialAttack",0,"EMP")
This code can technically go anywhere in the file after the NewShipType = StartShipConfig() line. For consistency, place it with the other addAbility lines of code.
25. Save the file and exit the editor.
Last Step
26. Start the game and test your work.
Updated Formatting? Initial
Updated for HWRM? Initial