Spoiler tag

Thursday, July 18, 2019

JSRF ModTool 2.4 - And character model importing

Hey there, here's the new version of the tool that can import models of the type named "MDLB" (characters and objects).

For learning the basics on how to use the tool, see this post and also this post

While its now possible to import models, keep in mind if you want to do so you will need to have some 3D modelling, uv mapping and rigging skills if you want to make a brand new character and import it.

Therefore this is not going to be a tutorial on how to do 3D modelling as that's a separate gigantic topic, you can find various 3D modelling apps and tutorials online, you might however be able to try doing simple edits on models like changing proportions of the body if you follow this example.

Three new buttons have been added to the top right of the model viewer to import/export models.
The JSRF ModTool will export and import models as .SMD model file format.

The "Collapse vertices" button will move all the model's points to the origin position (0 0 0) making the model invisible, this can be useful to hide parts of the original model such as the different facial expressions the game switches through as the character is animated.
If you don't want to bother making separate models for each facial expression, you can have the body and head model all contained in the first imported MDLB and then you could just make all the other original head models invisible by using the "Collapse vertices" button.

As for the tiny buttons "Expt." and "Impt." they let you export or import the selected item(block of data) as a binary file if you want to take a look with a hexadecimal editor to mod some particular data manually.

Anatomy of a JSRF character .dat file

Here's how playable character models are organized in the .dat file

                          Exporting a model

Just select an MDLB item and click "Extract MDL", it will let you select a folder where you want the model to be exported as .smd files, give it a name and click Save.

The tool also exports the lower level parts of the model which have to have the same naming as the main model so when importing the tool can find the lower parts of the model to import as well to rebuild the model properly.

Using Blender (2.79) to edit a model

Since the JSRF ModTool exports the models in .smd file format, for Blender you will need the Source Tools here  to import the model(s).
Installation instructions for the plugin are on this page

Once the plugin is installed and enabled you should be able to import .smd files by going into the menu File > Import > Source Engine

In this example I am going to make a small edit to the body of Beat, which I exported as "beat_body.smd"

First thing you'll notice is you need to rotate the model 90 degrees on the X axis.
Also note that the models comes inverted on the X axis, unfortunately I don't have the math/trigonometry etc knowledge and skills to code something so the JSRF Tool would sort these issues,luckily you won't need to turn it front 90 degrees again as the SMD exoprting tool can manage that for you.

Unfortunately with the SMD file format I haven't searched a way to have the models export with its texture(s), so you'll need to export them, select a texture and click "Edit texture", the texture will be extracted in the JSRF ModTool folder "resources\tmp"
Then assign the texture(s) manually in blender.

Made some edits to the model here:

Since I am barely familiar with blender, I just make some simple edits for demonstration, making his skates tubes ridiculously long and his shoulder spikes longer.

Once you are done with your edits, go to the top right panel where you see the list of the objects in the scene, right click on "beat_body_skeleton" and "Selected Hierarchy"

Blender and SMD export settings

Now before exporting we need to setup a few things in the Source Engine export panel.

Click on the  third button highlighted by the red circle, to display the
Source Engine export panel with which we can export the model back to SMD format.

Under "Source Engine Export" there's a few things to setup.

1-Set the export path, to the folder where you extracted the models (same folder where you extracted with the JSRF Tool)

2-Set the export format to SMD

3-Set the Target Up axis to Y

4-Now click the "Export" button, that's it!

Importing a model on the JSRF ModTool

Go back to the JSRf ModTool and with the original MDLB selected click  "Import MDL"
Select the first model on the list, in my case "beat_body.smd" and click Open.

This window should show up if there are no errors with the model files.
The lower level models (p_0 p_1 p_2) should be also loaded automatically if the naming is as on this example.

There are many settings here that you'll most likely never will need to modify but I am going to explain them anyways:

-Vertex definition size: size of the block of data defining a vertex(point) and other properties depending on the size, such as UV, Normals, sekeleton/bone ID,
bone deformation factor etc

-Global draw distance
: distance at which the model disappears (for performance optimization)


A JSRF player model usually has multiple materials/shaders that define the shading style.

Your model's materials groups should be named "mat_" and the corresponding number you want the material to be.

You can change the color and transparency of the material with the RGBA values, though this might depend on the type of "Material ID", this seems to be mostly used on models for the menus where they used a flat/solid color, and so the RGBA seems to work mainly on materials types dedicated to menu/UI models.

Material ID: this defines the type of shading for this material group (mat_0), there are many many more material IDs in other models that will show up as a number since I haven't researched them all to give them a name.

Float: this is an unknown parameter, it rarely changes, if you figure out what it does, don't hesitate to post in the comments.

You can remove materials by clicking the [x] box on the top right, and add materials from the button on the top right.


Now that all is setup click "Import", if everything about the model is properly setup it should import without giving any error messages.

Please note that JSRF models are limited to 2 deformers(bones) per vertex

There's the modified model imported, recompiled and ready for the game. 

And there it is ingame.

Some info and tips for full custom character mods

 You must keep the original bone hierarchy, modifying it or replacing it might cause animations to get messed up or even cause a crash.

If you're going to rig a different model, a new model, or ported mesh from some other game, note that you can move the bones around quite a bit(if the proportions differ from the JSRF's original character model) and the game engine will tolerate and will compensate for it anyways, so you can make a character shorter or taller moving bones around.

As you might notice, the exported character model's bones do not have a rotation, they are set to 0 0 0, it seems the rotation is completely dependent and applied by the animation data(which I haven't reverse engineered), some animations seem to be shared between characters and they all share the same or very similar rig(bone hierarchy and placement).

Well, I think that's more or less all there is to it, if you have any questions don't hesitate to ask in the comments.



  1. this is incredibly awesome. i tried to transfer Gum's armature onto a sanya litvyak miku miku dance model but kept getting the error "MDLB_builder.cs : Error, one or multiple vertices do not have a deformer assigned. Error at vert number: 0"

    my experience with 3d modeling is 1 semester of introduction level, so hopefully i figure it out before 2020. your videos of professor k and mario and sonic are super interesting, i would love to see a video of how you rig the old skeleton to a new one. it feels like JSRF character models is too particular of a niche and none of the online tutorials are clicking for me. youre making my dreams come true with this tool. i played with the graffiti tool and already want to replay the whole campaign, i just want to make my custom character before i do that.

    1. also i should note the miku miku dance model is very well ported into blender using just the blender part of this tutorial https://www.youtube.com/watch?v=7P0ljQ6hU0A.

      im pretty sure its just one little thing that needs to be changed for it to work, you probably figured it out with the models you imported.

    2. Hey, sounds like it might be the SMD files is written in a different way my code doesn't handle it properly, could you send me the SMD file so I can test it?

    3. was anything ever found for this? I'm running into the same error. currently trying to find a work around but not really coming to anything.

    4. I'd like to redact my last question as I did end up figuring out what my problem was. It was a matter of datablock organizing in blender.

      my bad! awesome work i really appreciate you making this!

    5. @qwerty, would you care to explain? Same problem here

  2. Nice work, is there a feature to fully export the stages themselves at some point in the future? I am working on a fan remake of the game and I only have the old tool which as you know, breaks the stages into chunks.

    1. Thanks, not planning to re-code the level extraction in the new tool at the moment, I looked quickly at my older JSRF tool code (VB.net), its a mess, the new ModTool is coded in C# much better, I might give it a try again for the levels but we'll see, I can't promise anything, I should move on from JSRF and focus on creating my own videogame, really, though so far I have always come back to JSRF reverse engineering/modding sporadically.

      As for the stages being into chunks, that's just how they are in the game files, I am guessing for optimization, so the chunks are hidden/unloaded when they're out of the player's field of view, I assure you the extraction tool isn't breaking them up, that's how they come in the game files.

  3. What's the scale to export the models from blender, I've tried everything and they always come out gigantic

    1. My bad, I wasn't exporting from blender to the same directory where all the .smd originally were

    2. No worries, by the way I didn't mention it in this post as I discovered it later, the player's head models, their materials work differently, if when re-importing a head model you only have on material in your SMD and after importing ingame the head material looks messed up, try having all the original head materials in your SMD to avoid this issue even if its just one triangle with a material (mat_0, mat_1 etc) that way in the importer it will list all the original materials and compile properly.

      There must be a way to get the head model compiled with a single material and not problems but I still have to looks into it.

  4. Hi! amazing work as usual!

    I was wondering if kitbashing pieces of other characters together would be simple? Say for example i wanted to give Rhyth Gum's head, would i be able to just copy and paste Gums head onto Rhyth? Or would it be more complex?

    Also, two more questions:
    1.Would it be possible to change the name of a character to your desired name? so that it displays in character select and such?

    2.Is it possible to change the voice of a character with your own files?

    Thanks again!

    1. Quick edit* By exchanging character body parts, i was refering to swapping them in the tool.

    2. Actually it seems Chris created a tool to rename characters: https://github.com/chrisderwahre/JSRF_Renamer

      And also the sound importing tool:

    3. Thanks!
      Yes you can easily kit bash / swap model parts of characters as you mention, for instance open gum's player model file "Gum.dat" (located in thefolder \Media\Player\ ), go to one of the models and select the one you want to copy (the head for instance), then click the "copy" button (under the dark grey bar).
      Then open Ryth's player model file her file name is actually named "bin.dat", select the equivalent model (so the head) and click "paste", the selected item you copied will be pasted into that other file, the changes are automatically saved no need to do "save file".

      1-See Chris's tool

      2-I haven't yet tried sound importing, I might give it a try soon, but someone tried, again try Chris's tools, he told me the sound importing maybe wasn't perfect, here's his twitter if you want to ask him questions https://twitter.com/CDW_Dev

  5. First of all this is incredible stuff, well done :)

    I'm having issues when I reimport a model, the textues arent mapping correctly to the model, this is even if I don't make modifications to the model in Blender. Just exporting and instantly reimporting.

    Do I have to map the textures again? (Sorry im new to this stuff :))

    1. Hey its neodos(I can't post with my account, some bug).

      Thanks and sorry for the uv maps bug, that's just the 3D viewer not displaying the UVs properly, try the model ingame and it should work properly there, I am using a third party model viewer, I'll see if I can fix the issue and post an update.

    2. Hey Neodos,just to let you know importing the model in game didnt fix the texture issue for me (tested in xcbx), but I did have some success with rolling back to an older build to get around this(2.4 to be exact.

      The issue im facing now that 2.4 doesnt seem to play friendly with importing hands or heads in my experience :P

      So right now I can texture bodies but not much else :P aha.

  6. Hi! Whenever I import a modified model, the skeleton does not appear in the mod tool. Did I do something wrong?

    1. Hi, the mod tool doesn't show the skeleton, is the imported model working in game?

    2. Yes it is, the model is straight from jsrf

    3. Never mind I found out what’s wrong

  7. sometimes the 3d models won't load (the textures always load). any idea what could be the cause of this?