View on GitHub

Metal Gear Solid V: The Phantom Pain technical information

Player motions

Introduction

Check out prettier version: https://chocmake.github.io/guides/mgsv-adding-player-motions/ (IH+this guide)

Player animations are stored in *.mtar files which are actually archives with different motions archived inside. Animations have `*.gani` extension and don't exist outside *.mtar archives. Up to this date there is no unpacker since no one is interested in motions :(. Anyway, every object has animations and animations are somewhat compatible between each other which is pretty cool - see this https://www.youtube.com/watch?v=bObxq7N-EKk for example.

Since there is no unpacker for *.mtar archives and there is not a single person who wants to research the format, the only way of having fun with them is reusing motions. I tried to play a "FOB victory" motion (when you get into the FOB core) in a singleplayer, but to my surprise it failed to play and "mission successful" motion (wiping forehead) played flawlessly. It made me to look into motions more.

I decided to work on DLC motions from MGO - https://store.steampowered.com/sub/97952/. They are unavailable in single player and exist only in MGO. Let's take a closer look at them.

Mod process

Since animations have *.mtar extension, the only smart move would be to unpack all MGO files and run a search for them. I did that before and compiled list of all files in a handy repository - https://github.com/unknown321/mgsv_lua_dump/. List of files in fpk archives in chunk0 is stored in /tpp/mgo/inf/chunk0/fpks/fpk_patches.txt. I recommend you to clone that repository and use something like grep to wade through lua code and files fast, GitHub search doesn't work on big files and has issues in general. After looking through gorillion of lines with 'mtar' in them you make a smart move and start thinking about how and where motions can be. File /Assets/mgo/pack/player/motion/mgo_player_resident_motion.fpk is the answer - it loads on the game start, has "player" and "motion" in name, has a nice size (over 18 megabytes). We can see the contents of that fpk in a link above (fpk_paths.txt) by just looking for mgo_player_resident - there is a mgoplayer_resident.mtar file which is definitely what we need.

Now we need to bring that file back into TPP. Using the same logic we find the file \Assets\tpp\pack\player\motion\player2_resident_motion.fpk in chunk0. Copy it somewhere else and unpack. Now it's time to combine them, just copypaste mgoplayer_resident.mtar into player2_resident_motion_fpk\Assets\tpp\motion\mtar\player2\ directory. However it's not over yet.

Game still has no idea that we added new animations. Since "FOB victory" motion was available only while playing online missions, there had to be a way to make the game load them the same way it does for FOB missions. Let's take a look at o50050_area.fpkd which exists in 00.dat. Main file of our interest is Assets\tpp\level_asset\chara\player\game_object\player2_online_motion.fox2. Unpack the file, use FoxTool to make a proper xml file out of it, open with your text editor. As you can see, it contains descriptions of what should be loaded into the memory, we are interested in <entity class="TppPlayer2AdditionalMtarData"> tag. It clearly adds player_online.mtar, so why don't we add MGO motions in the same way, but to singleplayer file? Player2_resident_motion.fox2 file sits in chunk0, player2_resident_motion.fpkd.

<staticProperties>
        <property name="name" type="String" container="StaticArray" arraySize="1">
            <value>TppPlayer2AdditionalMtarData0000</value>
        </property>
        <property name="dataSet" type="EntityHandle" container="StaticArray" arraySize="1">
            <value>0x05126751</value>
        </property>
        <property name="mtarFiles" type="FilePtr" container="DynamicArray" arraySize="1">
            <value>/Assets/tpp/motion/mtar/player2/mgoplayer_resident.mtar</value>
        </property>
    </staticProperties>
    <dynamicProperties />
</entity>

Hashes and values are mostly irrelevant (aside from mtar path), it just worked after copypasting so I guess it's ok.

Great, now pack back that xml file into fox2 script with FoxTool and pack fpkd back using whatever packer you use. After all these manipulations we have our motions in the game, TPP will gladly load them along with others and since player2_resident_motions loads motions that play game-wide, our animations will be playable everywhere (including title screen and intro/outro helicopter sequences, cinematic cutscenes are not included).

Now we are almost ready to play our animations in the game, all we need is to call a function with a path to needed animation.

Playing right animation

Looking for *.gani in Lua scripts gives us file /tpp/mgo/chunk0/Assets/mgo/level_asset/player/ParameterTables/AppealActions.lua has a list of all appeal actions with paths to *.gani files. Copypaste one of the values and use function Player.RequestToPlayDirectMotion('mymotion','PATH_TO_GANI') to play it (or just use provided lua file, it has everything already). Tada you did it.

Installation

Download animation_changer+script_loader pack.

Install script_loader.mgsv from archive (script_loader_IH.mgsv for compability with Infinite Heaven).

Install motions.mgsv.

Create directory lua in your main game directory (where mgsvtpp.exe is located). Put there files from put_us_into[MGS_TPP-lua] directory.

You are ready to go.
NOTE: I don't use Snakebite, so provided archives are untested. Same goes for IH, I think it shoud be compatible.

Using the mod

I use my mod along with my script loader which allows me to bind functions to keys via config file.

Script loader instructions

Hold zoom button (V) and action button (E) at the same time for about a second, loader will load code and bind it to keys. Hold zoom (V) and following buttons to play animations:

PlayerPad.UP (arrow up) to play current animation
PlayerPad.DOWN (arrow down) to play next step in animation (beginning-idle-end)
PlayerPad.RIGHT (arrow right) to play next animation
PlayerPad.LEFT (arrow left) to stop holding the animation (see issues below)

Feel free to rebind keys to whatever you want (aside from ZOOM and ACTION), list of keys here - https://wiki.nexusmods.com/index.php/Input_handling. Reload the config right in the game using ZOOM+ACTION combination, no need to restart the game.

Debug, repeat and hold options can be changed right in the animation_changer.lua. Make your changes, then hold ZOOM+ACTION to reload the script without exiting the game.

If you have message about keys being binded, but animation is not playing, create log.txt in the same folder as mgsvtpp.exe.

Issues

First time you try to play an animation while being in ACC, it will be played by your avatar instead (break the animation, stand up and look behind you using binoculars).
Animations are not playable during cinematic cutscenes.
MGO animations consist of 3 files - beginning, idle and end motions. Some poses can be repeated (see ani_repeat parameter), at least it works for 'mission clear' motion. If you set ani_hold_forever flag to true, after finishing the animation you will stand still in same pose unable to move. This is handy for posing; standing still can be interrupted by using Player.RequestToStopDirectMotion(), which is binded to 'arrow left' by default. You have to interrupt it every time after playing a motion to be able to play another one if you have ani_hold_forever set to true (off by default).
Sometimes motion won't play immidiately, you'll hear clacking sound (or debug messages if debug is on), but nothing will happen. Holding a button for longer time fixes that, I think game takes time to load motion or whatever.
Increased loading times, nothing you can do about it.
Sometimes you can get stuck in animation and stopping it does nothing. No fix for that, only checkpoint reload/back to title can bring you control over your character back.
You cannot get names for more animations (let's say bear ones) without an unpacker (which doesn't exist).
MGO has the ability to mirror animations and TPP has not (at least I am unaware of it), so instead of 40+ motions we have only 28.

Notes

Gani files definitely have some references to the sounds which are played every time you play an animation.
Mod works well with 'Good subsistance' mod which allows you to go around without weapons, resulting in weapon-free screenshots.(not public yet, links will be added later)
You can get out of helicopter by playing an animation, stopping it and running to the left or right (the faster your character is, the better). You can also get out from helicopter intro by playing an animation - that will leave you in the air, helicopter will land and immidiately leave the area.
Trying to play non-existing motions will break your character and you will be unable to play even proper motions. Fixed by restarting the game. (needs more testing)
Soldier motions ("SoldierLookWatch") don't play. Do they depend on currently used model/parts or was I using wrong mtar file (Soldier_common/npc_human_common.mtar)?