MySims Research

These files try to document MySims (PC) to the best of our ability. And do not document any of MySims sequels or MySims DS.

Interested in making mods? This wiki now also includes information on how to mod the game using the MySims Modloader here.

⚠️ IMPORTANT

These documents are a work in progress.

Patterns

This documentation uses ImHex's HexPattern files, which are an easy way to program and display how binary file formats are defined.

Versions

MySims was released multiple times on different platforms.

Formats

Any time a "hash" or "id" is mentioned we are talking about an FNV hash.

Some of these formats are based on the research done by Morcutool.

Contributors

This project was started by:

• ThuverX
• Lyralei1
• asteriddle
• Click here for an updated list of contributors

Modding MySims

⚠️ The modding wiki is a work in progress.

The modloader itself is also still undergoing changes.

It is assumed you have basic knowledge of how to make and edit XML

With the introduction of the MySims Modloader it is now possible to mod the game without changing its internal gamefiles or packages. Start with Creating your first mod.

Advanced

• Creating a global controller
• Check out the examples here.

Installation

1. Go to the latest Release
2. Download the file windows-x86
3. Unzip it into your game folder, next to MySims.exe (MySims/bin/)
   • In the end you should have mods, dsound.dll and MySims.exe in the same folder.
4. Done! Launch the game like normal.

Uninstallation

1. Remove dsound.dll
2. Optionally remove the mods folder

Installing mods

• Once you have found a mod that you like, unzip its folder into the mods folder.
  • If it looks like mods/MOD NAME/mod.xml you've done it correctly!.

To uninstall simply remove that folder from the mods.

Creating your first mod

1. To start create a folder and name it anything you want. This is usually the same name as the mod itself.
2. Create a mod.xml inside this folder

2. The Mod XML

Edit the mod.xml with your favorite text editor, I'm using VSCode. The Mod XML contains all the info that a mod needs to work, who made it, what files to load and which hooks to load. We'll get into those later. For now you can copy and paste this text into your editor:

<Mod>
    <Name>Your mod name</Name>
    <Description>Your mod description</Description>
    <Author>Your name</Author>
</Mod>

Replace each of the relevant data. You can also use the author section to give credit to files or info you may have used.

This is the most barebones version of the Mod XML. It will register just fine, but not actually do anything once its loaded!

3. Make it do something

Now here's a bit of a split depending on what you want the mod to do. We'll first go into replacing textures

3.1 Replacing textures

Replacing textures in MSML is easy! No need to package them, or give them weird names. First start by making an assets folder inside your mod folder. It should now look like this:

Then we need to tell MSML that it needs to load these assets. This is done by adding the Assets element to the Mod XML. Like this:

<Mod>
    <Name>MyMod</Name>
    <Description>A simple mod</Description>
    <Author>ThuverX</Author>
+   <Assets path="assets/"></Assets>
</Mod>

If for some reason you have named your assets folder something different make sure to change it here too.

Any texture you place inside the assets folder will now be loaded. Make sure they are of the DDS file type, it's the only format the game understands. But this just loads the textures, it won't actually replace them. To do that we need to add a Replacer element to the Assets element.

Lets go through a full example, I'll be replacing the grass in the game with this texture

And I've added this texture to the assets folder as grass.dds. Now to replace the grass we will need the key of the original key asset. This may sound a bit confusing, but keys are basically file names and extensions, but represented by numbers.

Getting these keys is more difficult and the Editor tries to make this easier, but since it isn't released yet we will use MorcuTool.

This tutorial won't go into using MorcuTool. As it will soon become obsolete.

Once you have found the key for the texture you want to replace, in my case it's: 0x00000000!0x00000000EE93FAC8. It may be in a different format. 0x00000000EE93FAC8 is the important part. Its the instance, basically the file name, while 0x00000000 is the group, or the folder its in. In this case it's in no folder.

Then we can add the replacer to our XML like this:

<Mod>
    <Name>MyMod</Name>
    <Description>A simple mod</Description>
    <Author>ThuverX</Author>
    <Assets path="assets/">
+       <Replacer key="0x00000000!0x00000000EE93FAC8" type="dds">assets/grass.dds</Replacer>
    </Assets>
</Mod>

We add a Replacer element, give it the key of the grass file. We know it's a DDS file so we set that too. Then lastly we set it to the name of the file we want to replace it with. Notice that we started it with assets/ this may seem optional but it is not. The game will only ever load files from the folder you set in the Assets element and nothing else.

You have no successfully replaced a texture. Copy the mod folder to your mods folder, that should be in MySims/bin/mods. Place it next to the Base mod:

Now when you start the game should see a log telling you that one file was loaded:

[2025-03-05 16:03:52] [INFO] (D:\a\MySimsModLoader\MySimsModLoader\src\mods\Mod.cpp:94) MyMod registered 1 replacer(s)

And loading a savefile you should see that the texture was replaced!

Congrats on making your first texture replacement mod! Continue reading if you also want to add new Lua code.

3.2 Lua hook

Lua hooks are an advanced method to add new code to the game. This could be used to add new interactions, NPC's or anything the game needs to register. For now we will make a simple mod that will greet the player once they load a save file.

To start make a lua folder inside your mod. Like this:

And add a new file called greeter.lua, and open it in your text editor. The code inside this file will be loaded every time a lua file is required. That just means your file will always be loaded and sometimes be loaded multiple times. So its always important to check if your code was already loaded before doing any editing the classes or variables. In our case we just want to make sure there's actually a player in the game. i.e. we are not in the menu.

if Player then
end

Here we're asking, is there a Player variable. If so, run the code between the then and end. Good, we now know we can do operations on the Player class.

So lets add a hook, a hook is a piece of code that looks at an object or class, in this case Player. And then looks at its PatchTaskInventory method, and after the PatchTaskInventory method is called (since its a PostHook) it will run the function we define (here function(self) end). We also need to give this hook a name, "Greeter__Player:PatchTaskInventory" seems like a nice and descriptive name.

PatchTaskInventory runs only when a player is just created, so its a good place to greet the player!

if Player then
+   Hooks:PostHook(Player, "PatchTaskInventory", "Greeter__Player:PatchTaskInventory", function(self)
+   end)
end

But this won't do anything on its own, so lets display a message, for this we can use the DisplayMessage function that comes with the game.

if Player then
    Hooks:PostHook(Player, "PatchTaskInventory", "Greeter__Player:PatchTaskInventory", function(self)
+       DisplayMessage("Greeter","Hey I'm here to greet you, have a nice day!")
    end)
end

We add the function call in between the function(self) and end to say: Run this once the hook runs. And then we just call DisplayMessage with our title and message.

There's just one last thing we need to do now. And that's register the hook with mod loader. Open up your Mod XML and add these lines

<Mod>
    <Name>MyMod</Name>
    <Description>A simple mod</Description>
    <Author>ThuverX</Author>
+   <Hooks>
+       <Hook>lua/greeter.lua</Hook>
+   </Hooks>
    <Assets path="assets/">
        <Replacer key="0x00000000!0x00000000EE93FAC8" type="dds">assets/grass.dds</Replacer>
    </Assets>
</Mod>

Here we define a Hooks element with our Hook inside. That's all, now once again add this mod folder to your mods. And run the game.

You will once again see a log saying the hook loaded:

[2025-03-05 16:19:27] [INFO] (D:\a\MySimsModLoader\MySimsModLoader\src\mods\Mod.cpp:116) MyMod registered 1 hook(s)

And once you load a savefile, you will be greeted!

That's it! Texture replacement are more generically file replacers. So you can also replace XML files or anything else. Though some file formats are hard to create, something the Editor will fix once it's released!

Still have questions? Join the Discord server.

Creating a global mod (Controller)

NOTE: This approach requires you to make use of the MySims ModLoader. Make sure you've set that up first before proceeding!

From this point on, the term "global mod" will be now considered a "Controller" as that's what Maxis has done as well.

Intro

In this tutorial we're going to be exploring how to make a controller for My Sims. A controller is exactly what it says on the tin: It's a script that exists in the world and is not connected to any interactions or characters.

When should I consider making a Global Mod?

When you...

• Find yourself making a "Manager". (i.e, a script that needs to keep up with things happening in the world and therefore cannot be connected to an interaction. Think: A weather mod).
• Find yourself in a situation where data needs to either be transfered from one world to another.
• Need something global that keeps track of multiple Game Objects and manipulate said data. (See: Controller_Tag)

Obviously these are just some case scenarios that you might need it. If your scenario isn't here that may not necessarily mean it's a terrible idea to make a controller for it!

A few things to note about controllers:

Most of these things we will tackle in the next section, but in case you need a quick heads up:

• Controllers only run their run() function once by default.
• Controllers don't by default have Class Constructors (not to be confused with constructor() function. That's different. See "Using a Constructor-like way to set up our controller" below.)
• Controllers don't save your variable data by default, after save & Quitting the game.
• You can set up a controller through an interaction call.
• Controllers will keep their current data whenever you go from one world to another

Getting started

First things first, we start with a bare basic setup. In this tutorial I'll go a bit more in depth as what certain approaches for your controller could be a good idea.

if Player then
    -- Make sure to replace everything starting with "MyController" with your controller name!!
    Hooks:PostHook(Player, "PatchTaskInventory", "MyController__Player:PatchTaskInventory", function(self)
       
        -- first grab any existing global controllers, before considering making a new one...
        -- @param `Controller_MyController` make sure that this is the name of your class variable (See section: Controller_MyController = ControllerBase:Inherit( "Controller_MyController" ))
        local myController = GetGlobalScriptObject("Controller_MyController") 

        -- if this is the first time loading it, load it in!
        if myController == nil then
            myController = SpawnObject( "Controller_MyController", "ObjectDefs/Controller_MyController_Def.xml", ObjectTypes.eGlobalScript, 0, 0, 0, 0, GetGlobalScriptsWorld())	
        end 
    end)
end

-- We also check if ControllerBase has been loaded in yet! Otherwise you'll get errors.
if ControllerBase then
    -- Make sure that the variable is global and is the same as the string param for `GetGlobalScriptObject()` and `SpawnObject()`
    Controller_MyController = ControllerBase:Inherit( "Controller_MyController" )
end

Feel free to copy this template when following this tutorial!

Why hook into the player?

Controllers are technically also GameObject, but "Empty" ones (aka, they have no mesh/skin/textures). This is completely normal in games, as it initially means a world has an instance that keeps all the information you'd like to keep, in an object! Think of it as an invisible moving box you're constantly adding things to.

However, because we need it to become a 'game object', it does mean we need to load it in. And what better way than seeing if the player has been instantiated to load in our controller as well! That way we also have the guarantee that everything in the world has been loaded, as the player seems to be loaded last.

Setting up the controller class

Now that we have a class set up and ready to do things, we now will be looking at how to get a simple controller up and running! Keep in mind that from here on the code is going to feel very "Object-oriented". So if you have some experience in C# or the like, you might recognise some patterns here.

Let's take a closer look at our Controller_MyController class we inherited...

First things first, for it to even "exist" we need to add two more functions:

if ControllerBase then
    Controller_MyController = ControllerBase:Inherit( "Controller_MyController" )

    -- Base variables. Just like in object oriented languages, these are variables you want to use all across but defaulting to nil or setting them to a default interger for example.
    function Controller_MyController:Constructor()
      self.
    end

    -- Where the magic happens! This is where our code is executed!
    function Controller_MyController:Run()
    end

end

And ironically that's all we need! Except, that for the player, we don't even know our controller "exists" now. So what better way than demonstrating it with a message box... Your code should now look something like this:

if Player then
    -- Make sure to replace everything starting with "MyController" with your controller name!!
    Hooks:PostHook(Player, "PatchTaskInventory", "MyController__Player:PatchTaskInventory", function(self)
       
        -- first grab any existing global controllers, before considering making a new one...
        -- @param `Controller_MyController` make sure that this is the name of your class variable (See section: Controller_MyController = ControllerBase:Inherit( "Controller_MyController" ))
        local myController = GetGlobalScriptObject("Controller_MyController") 

        -- if this is the first time loading it, load it in!
        if myController == nil then
            myController = SpawnObject( "Controller_MyController", "ObjectDefs/Controller_MyController_Def.xml", ObjectTypes.eGlobalScript, 0, 0, 0, 0, GetGlobalScriptsWorld())	
        end 
    end)
end


if ControllerBase then
    Controller_MyController = ControllerBase:Inherit( "Controller_MyController" )

    -- Base variables. Just like in object oriented languages, these are variables you want to use all across but defaulting to nil or setting them to a default interger for example.
    function Controller_MyController:Constructor()
      self.greetingText = "Hello there! I am a controller!"
    end

    -- Where the magic happens! This is where our code is executed!
    function Controller_MyController:Run()
      DisplayMessage("My Controller Header", self.greetingText)
    end

end

Making the Game Recognize Your Object

Now that we've finished the coding portion, we need to let the game know how to actually spawn your new item. Notice this line in your code:

myController = SpawnObject( "Controller_MyController", "ObjectDefs/Controller_MyController_Def.xml", ObjectTypes.eGlobalScript, 0, 0, 0, 0, GetGlobalScriptsWorld())

The argument "ObjectDefs/Controller_MyController_Def.xml" tells the game to look for an XML definition file in the ObjectDefs folder, located at: ...\MySims\SimsRevData\GameData\ObjectDefs (... represents the preceding path to your MySims installation.)

To add your own definition file, open that ObjectDefs folder and create a new text document, like so: Right-click > New > Text Document

Although the name isn’t strictly important, it’s best to keep it consistent. For example, call it Controller_MyController_Def, then replace the .txt extension with .xml. This ensures the game will recognize and load your custom object definition.

Now, we open up the text file and feel free to copy paste this:

<?xml version="1.0" encoding="utf-8"?>
<ObjectDef>
  <Script>Controller_MyController</Script> <!-- ADD YOUR CONTROLLER CLASS NAME HERE~!! -->
</ObjectDef>

And voila! Now We test it in game and see if it works! 😉 If we did this correctly, once you load your game, we should see a message box that pops up saying "Hello there! I am a controller!".

The Advanced stuff

Now that you know how to set up a basic Controller, there are plenty of other creative ways to expand its functionality. While this guide doesn’t cover every possibility, make sure to review the global files for additional references—especially the files in the controller folder, located under the Lua folder in SimsRevData\GameData. This will help you get a better sense of all the global functions and features available for your custom Controller scripts.

Grabbing your controller outside of our controller class

Sometimes, we need to grab some data from inside an interaction or a place outside of our controller class. To ensure we have the correct data to, for example, display to the player.

Let's say, instead of displaying our message inside of the controller's run() function, we instead do it in the interaction, we may want to do something like:

            local myController = GetGlobalScriptObject("Controller_MyController") -- Since our controller already exists, we grab it from the existing world global script list.
            if myController ~= nil then
                DisplayMessage("My Controller Title", myController.greetingText)
            end

Or, let's say, in case of running a function instead, we could do this:

            local myController = GetGlobalScriptObject("Controller_MyController") -- Since our controller already exists, we grab it from the existing world global script list.
            if myController ~= nil then
                DisplayMessage("My Controller Title", myController:FunctionHere()) -- Of course we can also parse in a parameter like you'd usually! But this isn't shown in the example
            end

Using a Constructor-like way to set up our controller

Sometimes a controller needs a constructor-like approach to set up the variables, similar to when we instantiate a class with a constructor through C#. Often this is done after the controller object has been properly created.

The setup inside of our controller would look something like this...

    Controller_MyController = ControllerBase:Inherit( "Controller_MyController" )

    function Controller_MyController:Constructor()
      self.greetingText = nil
      self.player = nil
    end

    function Controller_Mycontroller:Setup(greeting, player)
      self.greetingText = greeting
      self.player = player
    end

    function Controller_MyController:Run()
      DisplayMessage("My Controller Header", self.greetingText)
    end

and then once we create our object, you may do something like this:

        local myController = SpawnObject( "Controller_MyController", "ObjectDefs/Controller_MyController_Def.xml", ObjectTypes.eLua, 0, 0, 0, 0, GetGlobalScriptsWorld())	
        if (myController ~= nil) then
            local text = "I am a greeting! Salutations!"
            local player = GetPlayerGameObject()

            -- for good measure, you never know if an NPC accidentally calls our function!
            if player ~= nil and text ~= "" then
              controller:Setup(text, sim)
            end

        end

after your setup() function has been called, the Run() should be called automatically by the game!

Calling Run() Multiple times

(Heads Up: Most of these functions are derived/called from their inherited class. That's why you might see some functions without seeing their source code. If you do want to see the source code for them, feel free to check out "ScriptObjectBase").

While most of the time your controller may do very straightforward things, we do have cases where we want it to, let's say, run multiple times or even "keeping track of things". There are a few solutions for this:

Solution 1 - Wait To Be Deleted:

Probably the simplest and most straightforward! However, this of course takes some taking care of on your side, as we need to somehow eventually remove our controller.

While this approach has it's pros, the biggest con is that it will be forever looping your functions every tick. While this is not necessarily bad, you seriously need to consider if you need to fire your functions every tick or rather a couple of hours into the game (Or day even). Otherwise it can tremedously affect gameplay and causing lagging. (Or worse, crashing!)

function Controller_MyController:Run()

    while (self.toBeDeleted ~= true) do 
        self.Counter = self.Counter + 1 -- Just an example.
        self:shouldSelfDistruct()
        Yield() -- We add this here since it seems to help against crashing.
    end
    
end

function Controller_MyController:ShouldSelfDistruct()
    if self.Counter > 10 then
        -- Obviously this is a very "unclean" way of shutting down your controller, which is most of the time okay. However if you have a ton of VFX handling or animations, make sure to reset these in a function before calling this!
        self.toBeDeleted = true
    end
end

Solution 2 - Wait For Notify:

This is probably the best approach to use if you're making something that needs to keep track of differences, updating variables consistently or even time-based reasons! For this, we will also dive a little into timers, so if you want to know more about that, make sure to read the "How To - Create and use Timers".

In this example, we're going for a scenario for my Seasons Manager mod. Here, we want every day to communicate back that there is one day less remaining till the season changes. Or even change the season alltogether!

    function Controller_SeasonManager:Run()
        self:StartTimer()
        while true do
            self:WaitForNotify()
        end
    end

    -- Setting up timer on first run. We make sure that the first timer is always set for next day during 6 am (that's what Times.Day does for us).
    function Controller_SeasonManager:StartTimer()
        local day, hour, minute = GetSimTime()
        self.dayCheckerTimer = TODTimerCreateAbs(self, day + 1, Times.Day, 0, 0)
    end


    function Controller_SeasonManager:TODTimerCallback(timerID, context)
        if timerID == self.dayCheckerTimer then
            local day = GetSimTime()

            self.dayCheckerTimer = TODTimerCreateAbs(self, day + 1, Times.Day, 0, 0)

            -- adding a day before we've reached the next season!
            self.daysRemaining = self.daysRemaining  - 1 

            if self.daysRemaining == -1 then
                
                if self.currentSeason == 3 then
                    self.currentSeason = 0
                else
                    self.currentSeason = self.currentSeason + 1
                end

                self.daysRemaining = self.daysToSwitchSeason
            end
            self:Notify() -- This is what matters the most here. We're now telling our Run() loop that it's been notified and it can continue!
        end
    end

In the example above, I make sure that the Run function includes a while loop. The cool thing about Controllers, is that they're technically "Yielding" the function till we tell it to continue again.

This means, in this case, the first loop will pause, waits till our timer goes off (See: TODTimerCallback()) and once it hits the self:Notify(), it then loops again, waiting for the newest "notify" to happen.

Obviously, this can be quite powerful to use, and therefore feel free to add some additional functions after your "WaitForNotify()" in case stuff needs to run after the timer has rang!

Solution 3 - Using States:

The game also uses a concept of State machines. While that all sounds really complicated, it really doesn't have to be! Basically, we're just setting what "state" of the lifetime of our run function it's at currently. Here we often use terms as "Start", "running" and "End".

Often this approach makes more sense logistically when used together with an interaction, or another controller. But for now, we'll just show a really easy state machine setup.

    function Controller_MyController:Run()
        self:setState("Start") -- Alternatively you can set the state in your Setup() function too!

        while self:GetCurrentState() ~= "Stop" do
            self:HandlingMiddleState()
        end
    end

    function Controller_MyController:HandlingMiddleState()
        self:setState("Breakdancing") -- setting our custom state. Just for good measure!

        local index = 0
        while index < 10 do
            -- Have your sim breakdance 10 times or something here :p Have some fun!
            index = index + 1
        end
        -- Because now we've broken out of the while loop as we've hit over 10, we set the state to stop, so the state machine code EA made for us knows to stop "stating" 😉
        self:setState("Stop")
    end

However, if you ever did want to set the state of your controller outside of the controller class, it's actually pretty much the same approach as we'd do normally (as demonstrated under Grabbing your controller outside the controller class.) :

            local myController = GetGlobalScriptObject("Controller_MyController") -- Since our controller already exists, we grab it from the existing world global script list.
            if myController ~= nil then
                myController:setState("StateNameHere")
            end

Saving our controller data

While the save file of the game might be a little questionable, we can take use of it though! Every controller (or rather, anything that eventually derives from "ScriptObjectBase") you can save data per save file!

The idea is simple. Here's an example of how I did it for the Seasons Manager:

    function Controller_SeasonManager:Constructor()
        self.currentSeason = self.Seasons["Spring"]
        self.daysToSwitchSeason = 1 -- default 4
        self.daysPassed = 0
        self.daysRemaining = self.daysToSwitchSeason -- we make them the same since we're counting donw...
        self.temperature = 20 -- All in C, so 0 is cold, 40 is max (hot af), and -15 is REALLY cold.
        self.dayCheckerTimer = nil
    end

    -- --=========================================--
    -- -- Save/Load callbacks
    -- --=========================================--

    function Controller_SeasonManager:SaveCallback()
        local saveData = self:ConstructSaveData(  { "currentSeason",
                                                    "daysPassed",
                                                    "daysRemaining",
                                                    "temperature", }  )

        return saveData
    end

    function Controller_SeasonManager:LoadCallback(saveData)
        -- This is old data. I'm not entirely sure if this approach is necessary, but I have seen it done before. Other global scripts seem to just use RestoreSaveData()
        if (saveData.currentSeason ~= nil) then
            self.currentSeason = saveData.currentSeason
            self.daysToSwitchSeason = saveData.daysToSwitchSeason
            self.daysPassed = saveData.daysPassed
            self.daysRemaining = saveData.daysRemaining
            self.temperature = saveData.temperature
        else
            self:RestoreSaveData(saveData)
        end
    end

As you can see, I'm not saving everything in data, since I'm really only saving the relevant things. Obviously I want to save what the latest season was, the current days passed, days remaining and temperature so that once the player plays the game again, they have the correct season and such!

Though, you might wonder "Why aren't we saving the timer? What about "DaysToSwitchSeason"?", those things are actually not relevant to be stored in a save for a few reasons:

• The controller will always be 'rebuilt' every time we start the game again. Due to that, our timer will too!
• Some of our variables are simply there as a "tunable", rather than being modified.
• If we save too many items, the save file can get bloated and therefore it takes much longer to actually "restore" our data when loading the game again.

Big

Archive files using EA's BIG file format. For MySims they contain UI definition files using .apt files.

Pattern

import std.string;

struct Header {
    char magic[4];
    u32 archiveSize;
    be u32 entryCount;
    be u32 firstEntry;
};

struct Entry {
    be s32 offset;
    be s32 fileSize;
    std::string::NullString filename;
    if(fileSize > 0)
        u8 data[fileSize] @ offset;
};

Header header @ $;
Entry entries[header.entryCount] @ $;

Apt const

Pattern

import std.string;

enum Type : u32 {
    STRING = 1,
    NUMBER = 4
};

struct Entry {
    Type type;
    u32 value;
    if(type == Type::STRING) {
        std::string::NullString @ value;
    }
};

struct Header {
    char magic[17];
    padding[3];
    u32 aptOffset;
    u32 itemCount;
    padding[4];
    Entry entries[itemCount];
};

Header header @ $;

Bnk

An audio bank, using EA's audio format.

Converting

Converting of these files can be done using vgmstream

Clip

These files are used for any animations in game. They use the Granny3d .gr2 format.

Editing

These files can currently not be edited due to the proprietary nature of Granny3d and its Oodle compression.

DataBase Packed File

Are MySims way of packaging files, they are also refered to as DBPF and use the extension .package.

Files

MySims (PC) contains these package files and are found in MySims/SimsRevData

Format

DBPF have some different names for the files that are inside, in this documentation we will refer to them in the following way:

• Instance, hash - The name of the file. eg: ticketmachine
• Group - This is like a folder, for example the ticketmachine group contains both the files for the model and material of the ticketmachine.
• Type - This is the same as a file type, eg: windowsmodel, material or xml

Its important to note that some of these values have not been unhashed and thus are refered to by their instance id, instead of an actual name.

Pattern

⚠️ WARNING

Currently incomplete!

using FileType;
using DBPFFile;

DBPFFile file @ $;

struct DBPFHeader {
    char magic[4]; // Needs to be DBPF

    u32 majorVersion;
    u32 minorVersion;

    padding[12];

    u32 dateCreated;
    u32 dateModified;

    u32 indexMajorVersion;
    u32 indexEntryCount;
    u32 firstIndexOffset;
    u32 indexSize;

    u32 holeEntryCount;
    u32 holeOffset;
    u32 holeSize;

    u32 indexMinorVersion;
    u32 indexOffset;

    padding[28];
};

bitfield FieldFlags {
    resource_type   : 1;
    resource_group  : 1;
    instance_hi     : 1;
    instance_lo     : 1;
    offset          : 1;
    file_size       : 1;
    mem_size        : 1;
    flags           : 1;
    padding         : 17;
};

struct DBPFIndexHeader {
    FieldFlags fieldFlags;
    if(fieldFlags.resource_type) {
        u32 resourceType;
    }
    if(fieldFlags.resource_group) {
        u32 resourceGroup;
    }
    if(fieldFlags.instance_hi) {
        u32 instanceHi;
    }
    if(fieldFlags.instance_lo) {
        u32 instanceLo;
    }
};

struct DBPFIndex {
    FileType type;
    u32 group;
    u32 instance_hi;
    u32 instance_lo;
    u64 instance;
    u32 offset;
    u32 fileSize;
    u32 memSize;
    u16 isCompressed;
    u16 ukn1;
};

struct DBPFFile {
    DBPFHeader header;
    $ = header.indexOffset;
    DBPFIndexHeader indexHeader;
    DBPFIndex indicies[header.indexEntryCount]; // TODO: use fieldflags
};

enum FileType: u32 {
    Model = 0x01661233,
    RevoModel = 0xf9e50586,
    WindowsModel = 0xb359c791,
    rig = 0x8eaf13de,
    clip = 0x6b20c4f3,
    KeyNameMap = 0x0166038c,
    Geometry = 0x015a1849,
    Material = 0x01d0e75d,
    MaterialSet = 0x02019972,
    OldSpeedTree = 0x00b552ea,
    SpeedTree = 0x021d7e8c,
    dds = 0x00b2d882,
    CompositeTexture = 0x8e342417,
    SimOutfit = 0x025ed6f4,
    LevelXml = 0x585ee310,
    LevelBin = 0x58969018,
    Physics = 0xd5988020,
    LuaScript = 0x474999b4,
    LightSetXml = 0x50182640,
    LightSetBin = 0x50002128,
    xml = 0xdc37e964,
    FootPrintSet = 0x2c81b60a,
    ObjectConstructionXml = 0xc876c85e,
    ObjectConstructionBin = 0xc08ec0ee,
    SlotXml = 0x4045d294,
    SlotBin = 0x487bf9e4,
    swm = 0xcf60795e,
    SwarmBin = 0x9752e396,
    XmlBin = 0xe0d83029,
    CABXml = 0xa6856948,
    CABBin = 0xc644f440,
    big = 0x5bca8c06,
    bnk = 0xb6b5c271,
    lua = 0x474999b4,
    luo = 0x2b8e2411,
    LightBoxXml = 0xb61215e9,
    LightBoxBin = 0xd6215201,
    xmb = 0x1e1e6516,
    ttf = 0xfd72d418,
    ttc = 0x35ebb959
};

lua

MySims uses lua 5.1 as internal scripting, they almost always attach to gameobjects, but there are some hints on global classes too. Lua does not have engine access, only scripting capabilities and are therefore considered the 'front-end'.

Game Validation:

When loading the game, it seems every lua script is validated after the intro screen (the one with the my sims logo being assembled by sims). If a script has an error, this often means the game won't let you choose your save.

However, if your script passed the screen, another way to figure out there's a fault somewhere, is when your playable sim will just teleport in random places in the world.

Error logging:

A quick insight paragraph on what type of logging we can and cannot be using when scripting for MySims PC

EA logger:

There aren't many ways to log errors in the game just yet. While it ships with a "logger", this seems to be an internal tool that EA used that would essentially 'click' onto the game to show you the error logs or even debug messages. This, however, is not available in the released version of the game, nor is the ea logger available to the public, and therefore is deemed not the way to error log your scripts.

How to log potential issues:

While this is still a very new area that hasn't been explored much, or possibly not shared with the community, the only way that might help "debugging" your code as of now is using the "modal" approach, that is used in other sims games. For this, the use of "DisplayMessage()" is recommended. You don't have to import this, as it's a global function within the game's codebase.

Example:

DisplayMessage("My Debug Logger - title", "1")

sim = GetPlayerGameObject() -- Simply fluff code

-- Either continue our count...
DisplayMessage("My Debug Logger - title", "2")

-- OR, we print the variable, if necessary:
DisplayMessage("My Debug Logger - title", tostring(sim))

-- etc, etc....

If in all your messages print, Yay! If not, make sure to double check where it stopped last, and maybe try logging more variables.

Using Pcall()

Now, you might be curious why we don't use pcall() here to error check instead. While in some cases it may be possible to use it, know that, because a lot of things will be called on the same thread, Lua will complain about "tempt to yield across metamethod/C-call boundary" or in that same spirit. Since MySims was written on 5.1, pcall() isn't yieldable, unlike pcall() in lua 5.2 and higher.

While there are libraries that "patch" this out, this won't be possible with the way lua libraries are installed.

Game Objects:

Meant in a very broad way. Including not just furniture and what we would consider "objects" in the real world, but also: sims, furniture, trees, Essences, Buildings, etc. Excluding the level or the world.

All Game Objects that are NOT Player built through CAB (Create a Build), inherit the class "ScriptObjectBase". It sets up the bare basics for our game object to eventually make it possible to do things. It also handles tuning values (aka, the values we can adjust for something to happen more/less) and has an inherited animations table we can use.

Objects that are however CAB-made, use "ConstructedObjectBase" instead. Often the interactions are split from the main script object's class script, probably to avoid huge files.

Keep in mind that a lot of these objects are made with an Object Oriented approach!

Standard Basic ScriptObjectBase setup:

require "ScriptObjectBase"

-- Example: FishingBob = ScriptObjectBase:Inherit( "FishingBob" )
Your_Class_Name_Here = ScriptObjectBase:Inherit( "Needs_To_be_same_as_Class_Name" )

-- Required. Used often for instantiating variables, before usage. Also Instantiates your class.
function Your_Class_Name_Here:Constructor()
end 

-- Not required, but useful: De-instantiates your object if it needs to be destroyed according to the game/script. Often we remove FX effects here.
function Your_Class_Name_Here:Destructor()
end


-- For interactions, See "Interactions" and how to register them to your object

Standard Basic ConstructedObjectBase setup:

require "ConstructedObjectBase"

-- Example: FlowerStand = ConstructedObjectBase:Inherit("FlowerStand")
Your_Class_Name_Here = ConstructedObjectBase:Inherit( "Needs_To_be_same_as_Class_Name" )

-- EA Constructed Objects often include/override the animation table. Example is taken from FlowerStand.lua
Your_Class_Name_Here._animations = 
{
	ANIM_SNIFF               = { sim = "a2o-flowerStand-sniffFlowers" },
    ANIM_FLOWER_WATER_START  = { sim = "a2o-water-start" },
    ANIM_FLOWER_WATER_LOOP   = { sim = "a2o-flowerStand-water" },
    ANIM_FLOWER_WATER_STOP   = { sim = "a2o-water-stop" },
    ANIM_PRUNE               = { sim = "a2o-flowerStand-prune" },
}


-- Required. Used often for instantiating variables, before usage. Also Instantiates your class.
function Your_Class_Name_Here:Constructor()
end 

-- Not required, but useful: De-instantiates your object if it needs to be destroyed according to the game/script. Often we remove FX effects here.
function Your_Class_Name_Here:Destructor()
end

-- For interactions, See "Interactions" and how to register them to your object

Keep in mind that the game seems to point to also use an XML of the game Object to refer to some definitions. Probably to instantiate the item with the right assets from the game file packages?

Here's an example (Keep in mind that these objects are considered ScriptObjectBase!!):

<?xml version="1.0" encoding="utf-8"?>
<ObjectDef> <!-- Seems to depend on the folder its in. Definetly want to check that out -->
 
    <!-- See rig explanation -->   
    <Model>flowerTulipMature</Model>
 
    <!-- rig name. Should be found in the game files with the same name. It's possible that it's one of those name -> fnv32 hashes, where the instance is that.
    <Rig>flowerMature-rig</Rig>
 
    <!-- Name of the variable we call when inheriting in our LUA script. could also be the lua file name without the '.lua' part. -->
    <Script>Flower</Script> 

    <CollisionInfo>0 0.05 0 0.5 0.1 0.5 3</CollisionInfo>	<!-- 3:cylinder --> <!-- Vector4? -->
    <NoFootPrint>1</NoFootPrint> <!-- standard numeric boolean. 0 = false, 1 = true -->
	
</ObjectDef>

Interactions

If you're familiar with Sims 3 coding, this will be very similar to that structure wise.

These can be found on any gameobjects (sims, furniture, trees, etc) and make the object do something. Interactions always come with a: "Test()" and "Run()" Making them the bare minimum to make them work.

A basic Interaction often looks something like this:

require "InteractionBase"

GameObject_InteractionNameHere = InteractionSystem:MakeClass( InteractionBase, "GameObject_InteractionNameHere" )

function GameObject_InteractionNameHere:Test(sim,obj)
    return false -- or true! True means it will show our interaction.
end

function GameObject_InteractionNameHere:Run()
end

Test()

Before we see our interaction when standing in front of our object, or NPC (or ourself if you have Debug Enabler downloaded!), the game checks if the interaction should even be shown at all. "Can we fire it? Is this the correct candidate?" Is basically what it asks.

This can work for both our "actor' and "target" (example: actor=player, target=game object)

Only want Cute sims to use this interaction? Not a problem! That's what you'd want to filter out in Test().

Run()

This is where the magic happens. Here, we make the interaction useable and animatable (or just have our sim animate!)... or for a super simple test, even 'talk' with 'DialogMessage()'.

A few useful functions/params to know and use inside "Run()"

            -- Gets the world:
            GetWorld()

            -- Gets player:
            GetPlayerGameObject()


            -- Route to our slot and see if it was successful!
            primResult, primReason = RouteToSlot( sim, obj, 0 )
            if primResult ~= BlockingResult.Succeeded then
                return
            end

            -- But sometimes we want to route to the footprint instead (think... the object's boundary box. Not the best analogy but feel free to edit!)
            local primResult, primReason = RouteToFootprint( sim, obj )
            if primResult ~= BlockingResult.Succeeded then
                return
            end

            -- Remove Game Obejct:
            RemoveObject(self)

            -- Spawn Object:
            SpawnObject("MineralDispensor", "ObjectDefs/Dispenser_Generic_Def.xml", ObjectTypes.eHarvestingNode, x, y, z, 0)  -- Params: className? or ModelName?, def xml of item, objecttype, x, y, z, degrees

            -- Play animation (Without callback)
            primResult, primReason = PlayAnimBlocking( sim, "a-danceOff-start", 1 ) Params: gameObject, table containing animation strings for sim/object (But anim key is fine here too), Loop count.
            if primResult ~= BlockingResult.Succeeded then
                return
            end

            -- Slightly different approach, now with callback
            primResult, primReason = PlayAnimBlocking( sim, anim, 1, self, self.AnimateCallback ) -- Params: Actor, Anim key, numeric Boolean, parent (your class), function inside your class. 

            -- Attaches Object to other object (think: teacup snapped to sim's hand). 
            AttachToObject( self, "propPicnicBasket", "ContainmentSlot_8" ) --Params: Parent (mostly a sim, but can be any gameobject), modelName of prop/gameobject, slot name.

            -- Cancel Interaction for player. (MIGHT work on townies. need to double confirm this).
            self:CancelUserInteractions()

            -- Sets the item as "used" as it were. This way no other sims will see interactions for it.
            self:DisallowInteractions( true ) -- true == disallow, false == allow.

            -- 'sim' can be anything, but EA only uses it for sims for obvious reasons.
            -- Pushes the sim to follow another interaction, canceling the previous one so this one can now play.
            sim:PushInteraction( self, "Start", nil, nil, true ) -- Game object with interaction, classname of interaction, potential params needed for your interaction, boolean = ? not sure yet. If it's the same as TS3, means if it should continue as pushed.


            -- Returns a vector3 of the pos of your game object:
            local x,y,z = GetGameObjectPosition(self)


            -- returns a vector3 type for where the slot position and rotation is:
            -- EA only seems to want the x and y variable, hence the _ which stands for "blank".
            local x,_,z    = GetSlotPositionRotation(obj, SlotTypes.kRoutingSlot, 0) -- params: game object itself, slot name, z index?

            -- Gets the object rotation. returns a vector3.
            local _,yRot,_ = GetGameObjectOrientation(obj) -- Pararms: GameObject.

            -- Get floor height of item. Might not be necessary ever, but you never know!
            local y = GetFloorHeightAt( pos.x, 0, pos.z ) -- Make sure to at least grab and parse the x and z positions!

            -- Is object facing other object?
            -- Here I made a quick example of what it could look like. obj: can be game object or sim. sim can be game object or sim.
            obj:IsFacing(sim)

            -- rotate the sim/object towards the pos given. 
            primResult, primReason = RotateToFacePosBlocked( sim, x, z ) -- item to move, x pos, z pos. Possibly has a variation where a y pos is possible?
            if primResult ~= BlockingResult.Succeeded then
                return
            end



            -- Snap item to position/rotation you wish it to be at:
            SnapToPositionRotation( self, x, y, z, 360degrees) -- Item to rotate, x,y,z, 360 degrees.

            -- Get camera zoom. Returns Float.
            GetCameraZoom()

            -- Change camera zoom!
            SetCameraZoom( val ) -- float for zoom. 10 is far, 1.0 is close.

            -- Create fx effect! Make sure to attach it to an nil object inside "contructor()"!
            self.fxHandle = CreateFx( "tulip-Effects", x, y, z, false ) -- Params: Effect name (check game files), x,y,z, I believe the last one is for if it needs to load instantly?

          -- proper logic of destroying your fx.
          if self.fxHandle ~= nil then
              DestroyFx(self.fxHandle)
              self.fxHandle = nil
          end

            -- Get current Sim time!
            local day, hour, minute = GetSimTime()

            

            -- FULL INTEREST TYPES TABLE:
            -- InterestType["kFood"]
            -- InterestType["kSciFi"]
            -- InterestType["kSpooky"]
            -- InterestType["kCute"]
            -- InterestType["kStudies"]
            -- InterestType["kFun"]

            -- Get sim's primary interest. InterestType table is global, so can be used as in the example.
            if sim:GetPrimaryInterest() == InterestType["kFood"]
            end

            -- Buuut if we need all the interest of the sim (sometimes they have multiple!)
            sim:GetInterests() -- returns a table.

            -- Get the needs of the object (Works on Sims only, unless you know what you're doing)
            sim:GetNeeds()
    

            -- Set a timer. This is useful if a function needs firing every second, minute, day or hour. (It's good to check "ActivityRocketLauncher's "CreateTimer()" function for inspiration)
            -- MAKE SURE TO CREATE AN NIL OBJECT UNDER CONTRUCTION! Call it timer or whatever you like. Just don't refer to your game object!!
            TODTimerCreateRel( self.timer, days, hours, minutes, seconds ) -- Params: If you don't need to set any time units, just set it to 0.
          
            -- Kill Timer, otherwise it will never stop! D:
            TODTimerKill(self.timer)

            -- Sleeps the simulator. Basically when there's a lot to process, it's good to "sleep" the simulator fora few ticks. The game will continue to run fine however and won't freeze.
            Sleep(30) -- Params: Ticks to sleep for. NOTE: the game's ticks seem to be frames related, but need to double confirm this.

            -- Gets random object weighted (the weight is often defined in the table.) See: CharacterBase.
            SelectRandomWeighted(CharacterBase._idleAnimations, true) -- table with weights, boolean = ?
            
            -- Global function: Get random number till 100.
            GetRandomInteger(100)

Interaction Definitions & Registering our interaction

TO DO! but this is where the magic happens :D

Animations:

TO-DO!!!!

[Lyralei] - I FINALLY figured it out, but still need to wrap my head around how to write it all out :p Basically, depending on the approach and whether it uses ConstructedObjectBase (CAB furniture) or ScriptObjectBase (non CAB items), it looks at the _kAnimations table.

Take, Couch.lua for example. It comes with a Couch._animations table.

It also refers to what our sim or object should animate, referring to the CLIP Key name.

Couch._animations = 
{
    ANIM_COUCH_GETIN_START          = { sim = "a2o-getIn-start",                        obj = nil, },
}

However, for simple objects with animations, it seems to just use parameters and a table with specific keys, to loop/do the animations for us. Unless, we have a more complex object (such as ActivityBookParty where we have to fire a lot of animations in different ways due to variety.

Example:

Couch_Interaction_Nap.def = 
{
    ANIM_GETIN_START    = Couch._animations.ANIM_COUCH_GETIN_START,
    ANIM_GETIN_STOP     = Couch._animations.ANIM_COUCH_GETIN_STOP,
    ANIM_TRANS_IN       = Couch._animations.ANIM_COUCH_SLEEP_START,
    ANIM_LOOPS          = {
                            {   anim = Couch._animations.ANIM_COUCH_SLEEP_BREATHE,
                                stateInfo   =   {
                                                    { startState="base", endState="sleep",      weight=100,},
                                                    { startState="sleep", endState="sleep",      weight=100,},
                                                    { startState="nightmare", endState="sleep",      weight=100,},
                                                },
                            },

                            {   anim = Couch._animations.ANIM_COUCH_SLEEP_DREAM,
                                stateInfo   =   {
                                                    { startState="sleep", endState="sleep",      weight=20,},
                                                },                                
                            },
                            {   anim = Couch._animations.ANIM_COUCH_SLEEP_NIGHTMARE,
                                stateInfo   =   {
                                                    { startState="sleep", endState="nightmare",      weight=10,},
                                                },
                            },
                            {   anim = Couch._animations.ANIM_COUCH_SLEEP_WAKEUP_NORMAL,
                                stateInfo   =   {
                                                    { startState="sleep", endState="base",      weight=0,},
                                                },
                                availabilityTest = Couch_Interaction_Nap.WakeNormal,
                            },
                            {   anim = Couch._animations.ANIM_COUCH_SLEEP_WAKEUP_FAST,
                                stateInfo   =   {
                                                    { startState="sleep", endState="base",      weight=0,},
                                                },
                                availabilityTest = Couch_Interaction_Nap.WakeStartled,
                            },
                            {   anim = Couch._animations.ANIM_COUCH_SLEEP_WAKEUP_SCARED,
                                stateInfo   =   {
                                                    { startState="nightmare", endState="base",      weight=0,},
                                                },
                                --availabilityTest = Couch_Interaction_Nap.WakeStartled,
                            },
                                                        
                          },
    --ANIM_TRANS_OUT      = Couch._animations.ANIM_COUCH_SLEEP_WAKEUP_NORMAL,
    ANIM_GETOUT_START   = Couch._animations.ANIM_COUCH_GETOUT_START,
    ANIM_GETOUT_STOP    = Couch._animations.ANIM_COUCH_GETOUT_STOP,
    
    LOOP_MINUTES        = 20,
    PARKABLE_PLAYER     = true,
    
    ROUTE_FOOTPRINT     = true,
    CONTAINMENT_SLOT    = nil,  -- Non-standard slot name
    
    FORCE_TRANS_OUT     = true,
}

however, refering back to my mention of "complexer objects", the usage of PlayAnimBlocking is primarily used. It's simply playing a solo animation outside of the interaction def, and therefore not needing the need of our interaction def's animation. So I was thinking way too complicated about this :p

So yeah! You can do animations two ways: Play them solo, or put them in the interaction def list! Do make sure though to use the SAME keywords/keys that you see in my research reference, otherwise it will NOT work!!

Also, side note, it probably works, but I feel for the sad dev that made this lua Anim Utils and instead no one used it :p It's probably a debug thing but still... Thanks to them though, I was able to understand some of the params! :)

Event Ids

The Ids I've search and search and I cannot for the life of me figure out how it gets that... it's probably an internal engine thing i'm not realising :p In TS3 they were manually defined in the Jazz script and could get picked up easily within our script. Here however, it's complete magic to me lol.

Material

Materials define which shader along with what parameters the material uses.

Pattern

import type.base;

struct ResourceKey {
    type::Hex<u64> instance;
    type::Hex<u32> type;
    type::Hex<u32> group;
};

struct MaterialParameter {
    type::Hex<u32> type;
    u32 valueType;
    u32 valueFieldCount;
    u32 offset;
    
    u32 jump = $;
    $ = offset + 64;
    
    if(valueType == 1) {
        float color[valueFieldCount];
    } else if(valueType == 2) {
        u32 value;
    } else if(valueType == 4) {
        ResourceKey mapKey;
    }
    
    $ = jump;
};

struct MaterialData {
    u32 one1;
    u32 one2;
    padding[8]; // all zero
    u32 one3;
    ResourceKey self;
    u32 headerSize;
    u32 totalSize;
    char magic1[4];
    u32 version;
    type::Hex<u32> materialHash;
    type::Hex<u32> shaderHash;
    u32 mtrlSize;
    char magic2[4];
    padding[4]; // all zero
    u32 dataSize;
    u32 numParams;
    MaterialParameter params[numParams];
};

MaterialData material @ $;

Parameter names

Material Set

A material set is a list of references to material files.

Pattern

import type.base;

struct ResourceKey {
    type::Hex<u64> instance;
    type::Hex<u32> type;
    type::Hex<u32> group;
};

struct MTST {
    char magic[4];
    u32 version;
    u32 name;
    u32 index;
    u32 count;
    u32 indicies[count];
    padding[4];
};

struct MaterialSet {
    u32 one1;
    u32 one2;
    padding[4];
    u32 materialCount;
    u32 one3;
    ResourceKey selfKey;
    ResourceKey materials[materialCount];
    u32 headerSize;
    u32 mtstSize;
    MTST mtst;
};

MaterialSet materialSet @ $;

Shaders

Shaders have the file extension .fx or .fxh, and can be found in GameData_Win32/Shaders.

HLSL

Shaders use HLSL, the primary language for shaders used in DirectX. The .fx files contain both the Pixel and Vertex Shaders.

Shader hashes

Materials reference shaders using their FNV32 hash:

Win32 Model

Specific model files used only in the windows version of MySims. We don't know their exact extension, but the Taco Bell version refers to them as Win32Models. They can contain a list of models and a list of meshes.

Win32 Mesh

Win32 meshes are parts of a model that usually share the same material. The game refers to them as "Drawables". They contain a reference to a Material, a vertex list, and a face list.

Vertex keys

Vertices are read using a list of vertex keys, which tell the engine how the vertices should be read. This is mostlikely done for space optimization.

enum VertexKeyType: u8 {
    FLOAT2 = 1,
    FLOAT3 = 2,
    FLOAT = 4,
    UNKNOWN = 0
};

struct VertexKey {
    u32 offset;
    VertexKeyType type;
    u8 index; // where to put this data inside the vertex, think position, normal or uv
    u8 subIndex; // used with the uv, to tell if it should be placed in UV2, usually 0
};

Model Pattern

import type.base;
import std.string;

using CString = std::string::NullString;

struct Bone {
    type::Hex<u32> ukn[16];
};

struct ResourceKey {
    type::Hex<u64> instance;
    type::Hex<u32> type;
    type::Hex<u32> group;
};

struct Vector3 {
    float x;
    float y;
    float z;
};

struct WindowsRig {
    u32 numBones;
    type::Hex<u32> boneHashes[numBones];
    Bone bones[numBones];
};

struct VertexKey {
    u32 offset;
    u8 type;
    u8 index;
    u8 subIndex;
};

struct Face {
    u16 a;
    u16 b;
    u16 c;
};

struct WindowsMesh {
    ResourceKey material;
    Vector3 boundsMin;
    Vector3 boundsMax;
    u32 ukn1[2];
    u32 name;
    u32 three;
    padding [12]; // all zero
    u32 numVerts;
    u32 numFaces;
    u32 vertexKeyCount;
    VertexKey vertexKeys[vertexKeyCount];
    u32 vertexArraySize;
    u8 vertexData [vertexArraySize];
    u32 facesArraySize;
    Face faces[numFaces];
    s32 rigIndex;
};

struct WindowsModel {
    u8 four;
    char magic[4];

    u8 minorVersion;
    u8 majorVersion;

    padding [2];

    Vector3 boundsMin;
    Vector3 boundsMax;

    u32 numExtraParams;
    type::Hex<u32> extraParamKeys[numExtraParams];
    if(numExtraParams != 0) {
        u32 extraParamValueSize;
        CString extraPramsValues[numExtraParams];
    } else {
        padding[1];
    }
    
    u32 numRigs;
    WindowsRig rigs[numRigs];
    u32 numMeshes;
    WindowsMesh meshes[numMeshes];
};

WindowsModel model @ $;

XMB

XMB files are a binary XML format, it is not used everywhere and some files have even been switched to XML and back to XMB depending on the game version.

The neighbours and children here act like linked lists.

import std.string;

char magic[4] @ $;
u32 name_table_size @ $;
u32 data_size @ $;
u32 root_offset @ $;

struct Node {
    s32 name_offset;
    s32 text_offset;
    s32 neighbour_offset;
    s32 child_offset;
    padding[4];

    if(name_offset >= 0) {
        std::string::NullString name @ name_offset + 16;
    }

    if(text_offset >= 0) {
        std::string::NullString text @ text_offset + 16;
    }

    if(neighbour_offset >= 0) {
        Node neighbour @ neighbour_offset + 16 + name_table_size;
    }

    if(child_offset >= 0) {
        Node child @ child_offset + 16 + name_table_size;
    }
};

Node root @ root_offset + 16 + name_table_size;

Level

A level is a collection of models with some meta data, like grid size.

Format

<?xml version="1.0"?>
<Level>
  <GridInfo>
    <CellSizeX>32</CellSizeX>
    <CellSizeZ>32</CellSizeZ>
    <!-- Player start position -->
    <StartPosX>-6.670966</StartPosX>
    <StartPosZ>-3.140734</StartPosZ>
    <NumCellsX>2</NumCellsX>
    <NumCellsZ>2</NumCellsZ>
    <ModelName>nook_desert_04</ModelName>
  </GridInfo>
  <GridCells>
    <!-- A list of model instances -->
    <Model>2832803049</Model>
    <Model>2832803048</Model>
    <Model>1759182464</Model>
    <Model>1759182465</Model>
  </GridCells>
  <CharacterLightRig>player_lightrig</CharacterLightRig>
</Level>

World

stub.

Resource keys

Resource keys are the main way files are stored and referenced in many Maxis games. They are an abstraction on top of the filesystem. In simple terms this means they are just file paths.

Format

A resourcekey consists of three parts.

1. The instance
   • A 64bit unsigned integer
   • This is like the file name, as its just that, an FNV64 hashed version of its original file name.
2. The type
   • A 32bit unsigned integer, it's the file type, for a list of knows types check here.
   • In most cases again a FNV32 version of the original file type.
3. The group
   • A 32bit unsigned integer.
   • This is like a folder (also an FNV32 hashed string), but can be 0 if the file is meant to be at the root.

We usually show these files like this: 0x00000000!0x00000000EE93FAC8.dds. Where 0x00000000 is the group and 0x00000000EE93FAC8 is the instance¹.

The Editor also displays them like this 00000000 - 00000000EE93FAC8.

You may also sometimes see them referenced as ITG, because of the order they come in.

Examples

Here are some examples:

These names were found by hashing strings found inside the game files. And comparing them against all known resource keys. Ones that could not be recovered like this may have partial or incomplete names. Like 0xCFFED122!0x000000002FA92BDF.material just becomes decoAppleBowl/2FA92BDF.material (Found in Objects.package).

Pattern

import type.base;

struct ResourceKey {
    type::Hex<u64> instance;
    type::Hex<u32> type;
    type::Hex<u32> group;
};

FNV

Fowler–Noll–Vo or FNV is the hashing system used by MySims to hash various names.

FNV32 vs FNV64

MySims specifically used FNV32 for uint32's and FNV64 for uint64's. In practice this means shaders names and groups use FNV32 while instances use FNV64.

Algorithm

In pseudocode, taken from Wikipedia

algorithm fnv-1 is
    hash := FNV_offset_basis

    for each byte_of_data to be hashed do
        hash := hash × FNV_prime
        hash := hash XOR byte_of_data

    return hash 

In CSharp, taken from MySims Editor.

Note that strings are first lowered before being converted to bytes.

public static class FNV
{
    private static readonly uint PRIME_32 = 0x01000193;
    private static readonly ulong PRIME_64 = 0x00000100000001B3;
    private static readonly uint OFFSET_32 = 0x811C9DC5;
    private static readonly ulong OFFSET_64 = 0xCBF29CE484222325;

    public static uint Create32(byte[] bytes)
    {
        var hash = OFFSET_32;

        for (int i = 0; i < bytes.Length; i++)
        {
            hash *= PRIME_32;
            hash ^= bytes[i];
        }
        return hash;
    }

    public static ulong Create64(byte[] bytes)
    {
        var hash = OFFSET_64;

        for (int i = 0; i < bytes.Length; i++)
        {
            hash *= PRIME_64;
            hash ^= bytes[i];
        }
        return hash;
    }

    public static uint FromString32(string str)
    {
        return Create32(Encoding.UTF8.GetBytes(str.ToLower()));
    }

    public static ulong FromString64(string str)
    {
        return Create64(Encoding.UTF8.GetBytes(str.ToLower()));
    }
}