Adding New Lightsaber Hilts to JA Singleplayer

Introduction

This tutorial will (with any luck) explain how to add new lightsaber hilts to the Jedi Academy (JA) singleplayer character creation process. The new hilts will simply be additions to the list, and not replace any of the hilts already provided by the game.
One of the things that helps define a Jedi is his lightsaber. In the Star Wars universe, it is an extention of the Jedi and can reflect their personality in some way. There are a variety of hilts that are provided by the game out of the box for your character. However, you may not find one that is to your liking. Fortunately, like player models there are many custom hilts out there you can use, both original and those based on authentic Star Wars ones.
Adding lightsaber hilts to JA singleplayer is easy, and I’ll take you through the steps to add your own. But first, there are a few things we will need before we start:

WinZip: This will enable us to open, alter, and create .pk3 files (same as a .zip file).
Wordpad: Any text editor will do, really. I use Wordpad instead of Notepad for this because some of the files we will be editing might be too big for Notepad to open.
Graphics Software (optional): You'll need something to alter hilt textures, if you so choose. I like Paintshop Pro, but Photoshop is just as good, or anything equivalent.
ModView (optional): This is the model viewing tool released by Raven to view all the models in Jedi Academy, including hilts.

Once you have these things, you now have all the tools necessary to put new lightsaber hilts into Jedi Academy singleplayer.

Part 1: Extracting the Hilt Model

Once you have the lightsaber hilt you want to use, it has to be modified for use in singleplayer. To provide all the information the game needs, first we need to take the .pk3 file (the container file that holds the hilts model, textures, and other information) apart. A .pk3 file is in the same format as a Zip file, so we can use WinZip (or anything that manipulates Zip files) to extract its contents.
Step 1:
Create a directory. You can call it whatever you want. In this example, I’ll call mine mod.

Step 2:
Now open up the model’s .pk3 file in WinZip. You will see a bunch of different files in there. Click Extract.

Step 3:
In the dialog box, set the directory to our newly created mod directory. Make sure “Use folder names” is checked. Click Extract.
This should extract all the files in the .pk3 into the mod directory, along with the proper directory structure. The most important one is the models/weapons2/ directory, because this is the one with the hilt model and textures. So make sure everything is extracted properly. In this example, let’s say that the directory is models/weapons2/cool_hilt.

Part 2: Defining the Lightsaber Hilt

If you are using someone else’s custom lightsaber hilt, no doubt it will already have its own .sab file. This file provides information to tell the game about the properties of the hilt. If there is a .sab file already provided in the .pk3, you can modify that one. But let’s go through the steps to create our own.

Step 1:
Create in your mod directory a new path called ext_data/sabers/.

Step 2:
Create a text file in this new directory and call it saber_.sab. For example, we’ll call it saber_coolhilt.sab.

Step 3:
The definition of a saber hilt takes the following format:

saber_quizan
{
name ""
saberType
saberModel ""
soundOn ""
soundLoop ""
soundOff ""
saberLength
saberColor
numBlades
saberStyle
throwable
singleBladeStyle
singleBladeThrowable
twoHanded
}

Any values that are not provided go to a default. The default seems to correspond to a single-bladed saber. So let’s suppose that we are using a custom single-bladed saber for our new hilt. In the .sab file we could have the following:

saber_coolhilt
{
name "My Hilt"
saberType SABER_SINGLE
saberModel "models/weapons2/saber_coolhilt/saber_w.glm"
soundOn "sound/weapons/saber/saberon.wav"
soundLoop "sound/weapons/saber/saberhum4.wav"
soundOff "sound/weapons/saber/saberoff.wav"
saberLength 40
saberColor random
}

We don’t need to specify the other parameters in this case. If you are interested in creating a saberstaff hilt, open up the assets1.pk3 file in the GameData/base directory of your JA installation. In there look at the dual_1.sab for an example.

So now the game will know the properties of the new lightsaber hilt.

Part 3 (Optional): Modifying the Hilt Texture

If you like, you can alter the hilt’s texture to give it a different look. This won’t alter the shape, but you can alter the colours or surface designs. To do this, open up the texture file (usually the only image file in the models/weapons2/ directory) with your image editing software. You can check out your changes in ModView like you can with the character models.

Part 4: Adding the Hilt to the Hilt Selection Menu

Right now we have the hilt defined, but the game does not know that the hilt should be used as a player selection. So the hilt needs to be added to the saber list.

Step 1:
Open up the assets1.pk3 file in your GameDate/base directory and extract the saber.menu file into your mod directory. This should put the saber.menu file into a ui directory.

Step 2:
Open up the saber.menu file in Notepad or Wordpad. Search for “@MENUS_SINGLE_HILT1”. You will see the following:

@MENUS_SINGLE_HILT1 "single_1"
@MENUS_SINGLE_HILT2 "single_2"
@MENUS_SINGLE_HILT3 "single_3"
@MENUS_SINGLE_HILT4 "single_4"
@MENUS_SINGLE_HILT5 "single_5"
@MENUS_SINGLE_HILT6 "single_6"
@MENUS_SINGLE_HILT7 "single_7"
@MENUS_SINGLE_HILT8 "single_8"
@MENUS_SINGLE_HILT9 "single_9"

These are all the single saber hilts. We want to add ours to the list, so just add it to the end. So we will end up with:

@MENUS_SINGLE_HILT1 "single_1"
@MENUS_SINGLE_HILT2 "single_2"
@MENUS_SINGLE_HILT3 "single_3"
@MENUS_SINGLE_HILT4 "single_4"
@MENUS_SINGLE_HILT5 "single_5"
@MENUS_SINGLE_HILT6 "single_6"
@MENUS_SINGLE_HILT7 "single_7"
@MENUS_SINGLE_HILT8 "single_8"
@MENUS_SINGLE_HILT9 "single_9"

@MENUS_SINGLE_HILT10 "saber_coolhilt"

Remember to use the same specified at the top of the .sab file we made earlier. Now are not done yet. We need to do this again so that you can use the hilt as part of a dual pair. So search for “@MENUS_SINGLE_HILT1” again, and repeat the same as above. Now the game knows to the hilt can be used for either saber.

If you are adding a saberstaff, seach for “@MENUS_STAFF_HILT1” and add your hilt in the same fashion at the end of that list.

Step 3:
Now we need to give the hilt a name in the menu. This is specified in the MENUS.str file (there is one for each language). This file is in the assets0.pk3 file in your base directory. Extract that into your mod dierctory. It should be put in the path menu/strings/English.

Step 4:
Open up MENUS.str in your text editor. Search for the string “SINGLE_HILT9”. As you can see, the entries for the hilts are of the form

REFERENCE SINGLE_HILT
NOTES "saber hilt name"
LANG_ENGLISH ""

So after SINGLE_HILT9 add the new hilt name:

REFERENCE SINGLE_HILT10
NOTES "saber hilt name"
LANG_ENGLISH "Cool Hilt"

This will cause the hilt to show up in the menu with a name of “Cool Hilt”. You can do the same thing for a saberstaff by adding an entry after the STAFF_HILT5 entry.

NOTE: If you are adding multiple sabers this way, they will all have to be added to the list in the same saber.menu file, and the names in the same MENUS.str file. Otherwise some files will be replaced as they are loaded into the game, and thus not appear in the selection list.

Part 5: Packing up the Hilt

Now that we have edited what we want, we need to package everything together into a .pk3 file. The easiest way to do this is to create a zip file and then just change the extention to .pk3.

Step 1:
Start up WinZip and go to our mod directory. Under "Folders" click Recursive Folders. This includes the directory information the game will need.

Step 2:
Then select "models" (without going into that directory), and click Add with Wildcards. This will put all the necessary files into the .zip file. To confirm, make sure the hilt model and texture files are there, with models/weapons2// listed under “path”. Also make sure that the .sab file is there with ext_data/sabers/ as the path, the saber.menu has the ui path, and the MENU.str in the menu/strings/English path.

Step 3:
Finally, change the extention of our .zip file to .pk3. This can be done by manually renaming the file.

Step 4:
Move this .pk3 file into the GameData/base directory. The game loads every file with a .pk3 extention in alphabetical order. So make sure the name of your .pk3 comes after assets3.pk3. For example, coolsaber.pk3.

Now the saber hilt should be available in the hilt selection lists for both singleplayer and multiplayer.

Closing

I hope this tutorial has helped you add a new lightsaber hilt to JA. You should now be able to add any hilt you want. This is the end of my three part tutorial series!

If you have any questions or comments, feel free to send me an email at maroger@sympatico.ca.

Thanks again for reading,
Prime

Acknowledgements

One final big shout out to everyone who has helped me learn how to edit Jedi Outcast and Jedi Academy over at Lucasforums. You guys have helped me solve many annoying problems, and I really appreciate all your hard work. A lot of my knowledge comes from those great people.