Avatar Tool: Importing and Exporting Meshes & Textures
This page will guide you through how to export, create and import meshes for use in FreeSO. I recommend Blender 2.8 or later, as it has a builtin glTF importer and exporter utility. This page will focus on the process with blender, but any other applications that support glTF import and export may be able to produce working models.
Exporting Existing Outfits and Appearances
Open up the Avatar Tool from the Volcanic main window, then find and select the outfits/appearances you want with the search bar. You can match it up with animations of your choice, which will be exported along with the meshes. You can bind any number of appearances you want, if you want to keep them all in one file.
When you're ready, click "Export glTF" to export your selected resources to a glTF scene. The
.glb format keeps all textures in the same file, but if you'd like to edit them separately you can export as
In blender, create a new scene and import the glTF you exported from the Avatar Tool from File>Import. The avatar should appear in the scene with the meshes and animations you bound. You may want to set the animation speed of the scene to 36fps before importing if you care about animation accuracy.
Editing Meshes in Blender
Due to how the GLTF Builder works, all meshes included in the export have to be combined into the same mesh. This is a little frustrating for extracting meshes and putting in new ones, but means we don't have to duplicate the armature for each mesh in the scene.
In the screenshot above, you'll see that all the mesh names appear in the materials list. (names may become more descriptive in the future) To select a mesh, enter Edit Mode and deselect all geometry. Click on the target mesh in the materials tab, and click "select" to select all the vertices for that mesh.
Separating a mesh for easier modification
After selecting all the vertices of a mesh, you can use
Mesh>Separate>Selection. If you feel like separating all parts, use
Mesh>Separate>By Material instead.
Forcing the Armature to the Rest Pose
Bone bindings in Edit Mode are always relative to the Rest pose, so editing and binding a new outfit or appearance during an animation frame will just result in it being misaligned after binding. You need to make sure the Rest pose is being displayed when you're creating your new mesh.
Click on the green armature and you will see an option to set Pose Position or Rest Position. Change this to Rest Position so you can easily edit meshes relative to rest. Remember to set it back to Pose Position when testing animations or poses!
Creating a new mesh and binding it to the Armature
Create your mesh as normal, with the Armature in a the rest pose. For outfits, this means building the mesh around the armature. For accessories, this means placing the object in the correct place relative to the avatar before you bind it.
Remember that due to the way meshes in The Sims work, each mesh has a strict 1-to-1 mapping with a texture. That means that bodies MUST use only one texture, heads MUST use a separate one, appearances must use one texture EACH etc.
At any point, you can set your mesh(es) to be a child of the Armature. Do this by dragging your mesh over the Armature and holding shift:
When you do this, you will see a number of options. The easiest way to make an outfit is to use automatic weights, but this will really screw with accessories. If you are making an accessory or want to do manual bone bindings anyways, select "with empty groups".
Bone Binding for Appearances (all verts to one bone)
Select your new mesh in the Armature and enter Edit Mode. Make sure you are in the rest pose - meaning no animation is playing. Place your new object relative to the mesh in the place where you want it to appear.
Select all the vertices in the object, and view the Vertex Groups section of the Object Data tab. Select your desired bone, and then click "Assign" to bind all of the vertices to it. For instance, I have bound all the vertices of a Cube object to the head bone after placing it above the avatar's head, to make it appear like a hat.
After changing the Armature to use Pose Position, playing the animation shows the cube bound to the avatar's head. Feel free to bind your mesh to any bone on the avatar, except from the pelvis. (just kidding, but really don't)
Bone Binding for Outfits
Outfits are not supported yet. You can still make outfit-like appearances by binding to the armature with automatic weights or painting your own, though I don't know too much about the latter to make a tutorial.
Giving your mesh a name and material
As stated above, meshes MUST have a 1-to-1 mapping with a material. If two meshes share a material, they will combine on import!
The best way to create a material is just to dupe an existing one. This will keep all the default UV configuration. Give it the name you want the mesh to have (like
suit-watercan-right, see ingame for naming conventions) and bind your own texture.
To bind a texture to a duplicated material, expand BASE COLOR and you should see a texture input. Import textures in the PNG format and bind it to your new material. For best results, these should have power of 2 resolution. For outfits, try to follow the existing template for heads and bodies when UV mapping.
You should do whatever you want with UV mapping, just keep in mind only the first UV is used, and only the diffuse texture.
Once you're done modifying your mesh, you'll want to join it back into the Avatar mesh.
In Object Mode, select all your separate meshes and THEN the main mesh. Use
Object>Join (CTRL-J), and everything should be together again. Make sure your bone bindings still work by playing your exported animation or moving the bones.
Importing New Meshes
IMPORTANT: Make sure you have joined all your meshes into one, and configured the 1-to-1 material to game-mesh mapping!
First you'll want to export your scene from Blender. Use the (.gltf) exporter, but remember to tick "custom properties" in the exporter options (mostly for animations). You'll suffer a lot less exporting as (.glb), though if you wish to debug the gltf json I'd recommend glTF + external textures.
The next step is to import your meshes ingame. Thanks to the Avatar Tool, this is rather simple. Just click "Import glTF scene" and the mesh list should populate with the ones in the imported file.
You can preview and import individual meshes from here by selecting them on the list. Depending on the name, they may be treated as outfits rather than appearances in the preview. You can mix and match with appearances and outfits in the game via the selection on the left.
When you click Import, a secondary window will pop up asking you for more information about the Appearance or Outfit you are importing. I haven't made this yet, so I have absolutely no idea what it will look like.