Forced Single Player Playermodel

by lassev

Appetizers

Until Jedi Academy, the Jedi Knight games presented Kyle Katarn as the player character and, consequently, playermodel. With Jedi Academy the players were treated with a possibility to select their own model and skin, within preset alternatives. As welcome as it must have been, it still presented an unforeseen hindrance to those custom SP projects which, following the traditional way, wanted to tell the story of a particular hero. It wasn't enough anymore to ship with your mod a model that replaced "kyle". No, the way to force a certain character seemed more complicated.

Why not use the script command to force a playermodel? There is, after all, such a specific set_playermodel command in ICARUS. Well, by trying that, you would learn that you lose the skin of your custom, forced playermodel as soon as you make the mistake of pressing your quick load button. Unfortunate, and totally unacceptable. Wherein lies the solution then? That's what this article is all about.

Technical note: This tutorial does not require any mapping or scripting skills. However, it assumes you know the basics of model skin files and user interface (ui) menu files. All the steps are thoroughly detailed, so most probably you will be able to follow, no matter what your previous skills might be - as long as you have deep interest in the subject.

Revision note: This tutorial has gone through some significant changes since the first version. The changes greatly simplify the use of .skin files. Under optimal circumstances, this means as much as 80% reduction to the work needed to be done to have your forced playermodel in game. I thank the Dark Forces TC demo for pointing out this simple method.

Revision note 2: Due to bug reports and problems observed by myself, some notes have been added to the tutorial in case a modder encounters problems with the stability of the skin of the forced model. To be specific, if the skin won't be reloaded properly after the player has saved and then loaded the savegame.

The Recipe

You will need your custom model, in a custom folder. So, you don't need to replace any of the existing folders. In fact, that is discouraged, since you might one day need those models you were about to replace, after all. Just create your custom folder under /models/players/. After that, you will need to have a look at your skin files - I will explain the details later. You will also need to edit your menu files. We will deal with the menu files in the end. Let's first consider the skin files.

Skinning The Game

Forcing the playermodel starts with having a look at your intended forced model. All of the player models have a skin file default.skin. Some models have nothing else, some have other possible skin alternatives. Rare custom models and all the models originally available to the player in JA SP have separate skin files for head, torso, and lower. Your job begins with having a look at the skin file possibilities and deciding which one(s) to choose.

If your model has only model_default, that's your obvious choice. If it has two or more complete choices, you need to know which one you want. For example, the original Raven "Cultist " model has four different, complete skins: model_red, model_blue, model_brown, and model_default. Although I will later on only talk about model_default, you can use any complete skin file instead of it. Or if you want to use one specific variation of one of the original characters, with all their different head, torso, and legs skins, you need to know which skin files to select. Use ModView program to pick your choices, and keep in mind the name or names of the skin files for the next Chapter.

This is all you need to do with skin files. Now, let's move forward to some real action.

What's On The Menu Today, Anyway?

When building your SP project you will mess with the menus sooner or later, so why not mess with them a little more? But before we go and make the actual changes, it's better to explain why they need to be done. That will also explain the very nature of this tutorial and the method it depicts. The game saves the player character model it uses as a default in the jaconfig.cfg file in the Jedi Academy base folder. That is the same file that stores all your graphic settings, your custom short-cuts to force powers, and basically everything you modify in the game that will stay stored for your next gaming session. This is the fundamental problem faced when trying to affect which playermodel the game uses. To make a permanent impact, that is, to ensure the wanted, forced, playermodel is loaded successfully each time your mod is started or loaded from a save game, the information must be stored in the jaconfig.cfg.

The easiest solution no doubt would seem to be to ship a ready and proper jaconfig.cfg with your level. That would, after all, ensure that when the random player somewhere out there launches your mod, he would get the playermodel loaded as it's stated in the file. However, I can guarantee that the random player won't be happy. Because he would get not only the correct playermodel, but he would get all your graphic settings, all your force power short-cuts and everything. Now, I wouldn't like that a bit, and I sure few else would.

So, the solution to the problem is to let the game create a jaconfig.cfg file, based on the player's current settings, for your mod (it will be stored in the Gamedata/modname folder and thus doesn't disturb the original SP game), and then edit that file appropriately so that the needed custom playermodel is forced instead of the who-knows-which playermodel the random player happened to had from the last time he started the original SP campaign.

This is accomplished by editing the newgame_first.menu and newgame.menu files. This method also removes the character selection screen, since it has been rendered unnecessary by forcing a predefined model, and launches your map when the player presses the next button in the game difficulty selection screen. If you wish to handle things differently, you can edit the menus to suit your purposes, for example if you still want to have the saber selection menu screen. However, that's not a subject covered in this tutorial, and no further thought is invested in it here.

To proceed with the tutorial, create an ui subfolder under you mod folder, and copy the original newgame_first.menu and newgame.menu there. Now, open the files (in Notepad) and scroll all the way to the end. You will find the item definition for the Next button. This is what we are going to edit. The beginning looks like this:

Now, scroll a little down until you will find this (under the itemDef, indented):

You need to edit the action part to suit our purposes. Edit it along the guidelines below, only adjusting it to serve the specific name of your model. Be sure to remove the line "open characterMenu". You can also have a look at an example I have provided. It sets a custom model under rebornserpent folder to be the player character model, yet it will use the original Raven reborn2 sounds. Be sure to adjust the sex of your character, as it will affect, for example, the sound the player utters when force healing. This sound is stored among the force sounds, and not under your other player specific misc sounds.

Like I said earlier, if you have other complete skin files (complete means here that the single file will provide information for head, torso, legs and everything, covering the complete model), you can just replace the model_default parameter with some other model_xxxxx skin file.

Example:

You will also notice three rows defining RGB values. If the model (skins) supports them, they will cause the so called player tint to take effect. This may cause some parts of the character's clothes, for example, have different coloring depending on the values you enter here.

In order for your custom level to loaded and launched, you will need to execute a simple text file called gamestart.cfg. This file is easy to create and will produce the professional image of starting your level through menus, not through an amateurish console command. In order to create the gamestart.cfg just create a new file in Notepad. It contains nothing but the following line:

map mapname

That's the same command you would use to start your map in the console. Then just save the file by the name gamestart.cfg. Be sure you don't add the unnecessary .txt anymore to the end of the filename. This file must be in the root of your .pk3 packet.

Dessert

After all the work done, you just pack 'em all up in your .pk3. You must bear now in mind that this method should only be used with projects released as Mods, since they will alter the players jaconfig.cfg file. But as long as it is kept in its own mod folder, it will edit but the personal copy of the file meant just for this mod. So, it won't affect in any way any other maps or levels the player might want to play. But starting the map as a mod requires one additional step: Loading the mod.

Due to a bug in JA SP, the load mod menu option is flawed. It still works partially, so you may opt to use it. The fully functional way is to load the mod using a batch file. This .bat file, located in the Gamedata folder, is again nothing more than a text file containing one command. It will start the game launching the mod at the same time. It provides, compared to the load mod menu command, the additional advantage that your custom strings will work (subtitles, mission description etc...).

For the batch file, you need nothing more than to launch Notepad, and enter one line following the guidelines below, and save it as modname.bat. Again, make sure you don't add .txt in the end of the name.

jasp +set sv_pure 0 +set fs_game modname

for example:  jasp +set sv_pure 0 +set fs_game deception

In the command above, the modname is the name of the mod folder, which should optimally also be the name of your .pk3.

Bug Hunting Notes

It has come to my attention the method described in this tutorial may under unknown circumstances consistently produce a systematic error where the skin of the forced model won't be loaded properly when a savegame is loaded. Thus, the effect is similar to the flawed script command forcing a playermodel. Should the modder encounter such a problem, following the simple steps described here may solve it. One sign of this particular problem is an error message visible in the game console when the level is loaded: "Com_sprintf: overflow of...". This error is already shown when the level is launched from the Start New Game option and even though the skin still looks proper.

This particular error seems to be connected to using the "model_default" method of assigning the skin. To fix the error, head to your model folder, and copy the "model_default" into three separate files, then rename them "head_a1", "torso_a1", and "lower_a1". Then edit your "newgame.menu" and "newgame_first.menu" files and change the cvars to point to these three files instead of the "model_default". The tables above also show how to use these three files instead of the "model_default".