Essencio

A header-only C++ library for reading MySims binary formats, useful for modding tools, game asset viewers, or research purposes.

If you're looking to inspect game assets visually, please check out MySims Explorer!

Supported Files

The following file types can be read using Essencio:

• WindowsModel - Models used by the Windows version of the game (Taco Bell, EA, Cozy Bundle)
• Material - Materials along with their parameters, including references to textures
• MaterialSet - A collection of references to other materials
• StringFile - A collection of strings used for game localization

There's also the MaterialParameterTypeName enumerator which can be used to translate material parameter types to readable names:

• For MySims: essencio::mysims::MaterialParameterTypeName::ToString(...)
• For MySims Kingdom: essencio::kingdom::MaterialParameterTypeName::ToString(...)

You can use the FNV utility to convert strings to 32-bit and 64-bit FNV hashed, commonly used by the game to link assets together, e.g. linking textures to materials.

• essencio::FNV::FromString32("Hello, world!") -> 0xD6E77C06
• essencio::FNV::FromString64("Hello, world!") -> 0xC22B88B6F5D99986

Example Usage

WindowsModel

#include "essencio/bin/BinFileStream.hpp"
#include "essencio/model/WindowsModel.hpp"

// Create a BinFileStream in read mode, used to read raw bytes from the buffer
essencio::BinFileStream reader("<path to your model>", essencio::BinMode::kRead);

// Create a new model instance and read it using WindowsModel::Read
essencio::WindowsModel model;
essencio::WindowsModel::Read(model, reader);

// Print the amount of meshes in this model
std::cout << "# of meshes: " << model.numMeshes << std::endl;

for (const auto &mesh : model.meshes) {
    // Print the amount of vertices in this mesh
    std::cout << "# of vertices: " << mesh.numVertices << std::endl;
    // Print the amount of faces in this mesh
    std::cout << "# of faces: " << mesh.numFaces << std::endl;
}

Material

#include "essencio/bin/BinFileStream.hpp"
#include "essencio/material/Material.hpp"

// Create a BinFileStream in read mode, used to read raw bytes from the buffer
essencio::BinFileStream reader("<path to your material>", essencio::BinMode::kRead);

// Create a new material instance and read it using Material::Read
essencio::Material material;
// Read the material file for MySims Cozy Bundle
essencio::Material::Read(material, reader, essencio::GameType::kMySimsPC);

for (const auto &param : material.params) {
    // Print the type of this material parameter
    std::cout << "type: " << param.type << std::endl;
    // Print the amount of fields in this material parameter's value
    std::cout << "# of value fields: " << param.valueFieldCount << std::endl;
}

MaterialSet

#include "essencio/bin/BinFileStream.hpp"
#include "essencio/material/MaterialSet.hpp"

// Create a BinFileStream in read mode, used to read raw bytes from the buffer
essencio::BinFileStream reader("<path to your material set>", essencio::BinMode::kRead);

// Create a new material set instance and read it using MaterialSet::Read
essencio::MaterialSet materialSet;
// Read the material set file for MySims Kingdom Wii
essencio::MaterialSet::Read(materialSet, reader, essencio::GameType::kMySimsKingdomWii);

// Print the amount of materials in this material set
std::cout << "# of materials: " << materialSet.materialCount << std::endl;

for (const auto &material : materialSet.materials) {
    // Print the instance hash for the material in the set
    std::cout << "instance: " << material.instance << std::endl;
}

StringFile

#include "essencio/bin/BinFileStream.hpp"
#include "essencio/material/MaterialSet.hpp"

// Create a BinFileStream in read mode, used to read raw bytes from the buffer
essencio::BinFileStream reader("<path to your string file>", essencio::BinMode::kRead);

// Create a new string file instance and read it using StringFile::Read
essencio::StringFile stringFile;
// Read the string file for MySims Wii
essencio::StringFile::Read(stringFile, reader, essencio::GameType::kMySimsWii);

// Print the amount of strings in this file
std::cout << "# of strings: " << stringFile.count << std::endl;

for (const auto &string : stringFile.strings) {
    // Print the ID for this string (the 32-bit FNV hash of the original name)
    std::cout << std::hex << "id" << string.id << std::endl;
    // Print the value for this string
    std::cout << "string: " << string.value << std::endl;
}

For a full example usage of loading each file type, please check out the unit tests to get an idea of how to load each file format.

Notes

• No exceptions are used for error handling to reduce overhead. Instead, it uses asserts, meaning errors will only be thrown for debug builds.
• For a full implementation of this library, please check out MySims Explorer, a tool to visually inspect various assets from MySims and MySims Kingdom.

Credits

Thanks to ThuverX for putting together the MySims Research wiki pages!

License

This project is licensed under the MIT License.