Difference between revisions of "Tutorial:Sims 3 Object Modding"

Revision as of 12:16, 19 February 2011

Introduction

While the Object Mod per se isn't limited to a specific set of properties, it is always an object that uses a custom script. The most basic sort of object mod is a simple clone of the original object rigged with some new interactions. This tutorial will show you how to clone an object, write a script for it and make the object use that script.

What You Need

• Microsoft Visual C# Express - simply called VS later in this tutorial
• Sims3 Package Editor - simply called S3PE later in this tutorial
• Sims3 Object Cloner - simply called S3OC later in this tutorial
• redgate .NET Reflector - simply called Reflector later in this tutorial
• A basic understanding of the C# syntax or at least any C-like language.
• A game that is properly set up to support scripting mods. If you fail to accomplish that, you can’t hope to successfully write object mods.

Getting Started

• Extract the core libraries with S3PE if you haven’t already. Here’s how to do that:
  1. Open S3PE and click on File -> Open…
  2. Navigate to the installation folder of The Sims 3 and from there to the sub-folder where the executable is located.
     In this folder are three packages: gameplay.package, scripts.package, and simcore.package
  3. Open one of these packages.
  4. Click on an S3SA resource. Note that S3PE shows some information about that resource in the preview area. Locate where it says ManifestModule. Remember what comes after the colon, e.g. Sims3GameplaySystems.dll.
  5. Click on Grid at the bottom of the S3PE window, and then click on the Assembly row and the little drop-down arrow on the right. Click on Export…
  6. Choose a sensible folder for the library and save it under the name you remembered from the ManifestModule entry.
  7. Repeat steps 4 to 6 for every S3SA resource in the package.
  8. Repeat steps 3 to 7 for every package listed under step 2.
  9. Close S3PE.
• Create a game-compatible Visual Studio project as explained here: Sims_3:Creating_a_game_compatible_Visual_Studio_project
• Start Reflector and load the core libraries with it.

Cloning Your Object

The next step in this process is to make your new cloned object.

• Open S3OC, Clone -> Normal Objects
• Scroll to the object to clone, select Clone or Fix button
• Enter a unique username and leave all default options checked
• Change any catalog options such as name, description, price or category
• Select Start, browse to your project folder and give the package a name

Finding The Original Object's Class

This next step is important because it will later be used to make your script be derived from the previous object. That will ensure that the new object has all the properties of the original object.

• Open the package in S3PE.
• Select the OBJK resource.
• Click on "Edit OBJK".
• Look at the content of the Data field in the Script row. That is the class name including the full namespace. (Sims3.Gameplay.Objects.Miscellaneous.StuffedAnimal in this case)

Starting Your Code

We are going to start off by changing the namespace and the class. The namespace is like the address of a class. You can have two classes having the same name as long as they're located in diffeent namespaces. To make sure that your classes never clash with an EAxian class or with another modder's class, you need to make your namespace unique to you. Don't use an EAxian namespace or another modder's namespace! Ever.

In case of object mods, you'll always need to put an object's class in a namespace that begins with Sims3.Gameplay.Objects. If you don't do that, the object will cause the game to crash when you try to buy it in the catalog. The example namespace in this tutorial is:

namespace Sims3.Gameplay.Objects.Miscellaneous.KolipokiMod

(Remember: You need to use something different for your mod!)

Next we'll change the class name. That's not absolutely necessary, but it's not good style to give a derived class the same name as its base class. It is good style however to choose all names, be it classes or fields or whatever, in a way that they indicate what they do or stand for. Now what do you think will be the better class name for our mod? SomethingIDontKnowOrWhatever or TalkingTeddy? Right.

public class TalkingTeddy : StuffedAnimal

Now what is that "StuffedAnimal" stuff after the colon for? The colon basically means "derived from". It can also mean "implements" in case of interfaces, but we'll try to reduce the confusion to a minimum here. In this case TalkingTeddy is derived from StuffedAnimal. That is a core feature of object oriented programming and means that TalkingTeddy does not only share all properties of a StuffedAnimal, it IS in fact a StuffedAnimal while a StuffedAnimal isn't necessarily a TalkingTeddy. Think of how a weiner dog is a special type of dog, but a dog isn't necessarily a weiner dog and you'll get the idea.

For more advanced object mods, you'll derive your class from the abstract GameObject class which is the base class for all objects visible in the game, sims included. GameObject has no specific properties, so it's for the best to stick with expanding existing objects for the beginning.

The base class should be what was in the script class entry of your object. You may be wondering why it now only is StuffedAnimal while it was Sims3.Gameplay.Objects.Miscellaneous.StuffedAnimal in the script class entry. Visual Studio will know what class you mean. If it does not, right click on it and hit resolve and then it should work. Visual Studio will add a using directive to the top of your source code, so you don't need to type the whole namespace over and over again. In this case it's using Sims3.Gameplay.Objects.Miscellaneous.

Adding the interaction

Through this step we will be using Reflector so make sure you have it opened and that you have opened the .dll's that we extracted in the first step. If you do not know how the game calls an interaction it is best to see how they do it. Because all we are doing is telling the interaction to tell us Hi, we need an immediate interaction. In the Sims 3 immediate interactions have those orange circle things next to their name. We are going to be exploring the Stereo TurnOnOff function.

• Expand Sims3GameplayObjects -> Sims3GameplayObjects.dll -> Sims3.Gameplay.Objects.Electronics -> Stero -> TurnOnOff
• Open the dissasembler by hitting the spacebar
• Select TurnOnOff to see what it does. Be sure to hit the expand method at the bottom of the dissasembler so you can see the whole code. Look through the disassembler and see how the code works.

When you have finished exploring we are going to need most of the code of the TurnOnOff Method so select the code in the disassembler and copy it. Paste it within your class definition in MVSC#. Because this is for the stero we will need to change it.

Change the private sealed class name of TurnOnOff to what you want the name of it to be, make it something that describes the interaction. I'll be naming mine TalktoMe. Also make note that the class is derived from an immediateInteraction class. Be sure to change the Stereo to the name of your object (the first class). In my case it will say TalkingTeddy instead of stereo.

A lot of this stuff we took we will not be needing and we will have to change. You will also need to change the code so that where it says stereo you refer to your object and where it says TurnOnOff you refer to your interaction name.

private sealed class TalktoMe : ImmediateInteraction<Sim, TalkingTeddy>
{
    // Fields
    public static readonly InteractionDefinition Singleton = new Definition();
    private const string sLocalizationKey = "Gameplay/Objects/Miscellaneous/TalkingTeddy/TalktoMe";

    // Methods
    private static string LocalizeString(string name, params object[] parameters)
    {
        return Localization.LocalizeString("Gameplay/Objects/Miscellaneous/TalkingTeddy/TalktoMe:" + name, parameters);
    }

    protected override bool Run()
    {
        //do interaction here
        return true;
    }

    // Nested Types
    private sealed class Definition : ImmediateInteractionDefinition<Sim, TalkingTeddy, TalkingTeddy.TalktoMe>
 {
                      // Methods
                      protected override string GetInteractionName(Sim a, TalkingTeddy target, InteractionObjectPair interaction)
                      {
                          return TalkingTeddy.TalktoMe.LocalizeString("TalktoMe", new object[0]);
                      }
                      protected override bool Test(Sim a, TalkingTeddy target, bool isAutonomous, ref GreyedOutTooltipCallback greyedOutTooltipCallback)
                      {
                          return !isAutonomous;
                      }
                  }
}

Making the Interaction Do Something

With the right code, interactions could do anything. They could start a fire to a whole lot like in the ChaosMagePainting. They could lock doors such as in the Lockable door.

For this tutorial i will simply make it say "Hi". The Sims 3 has a nice way of setting up a notification. It's simply:

base.Actor.ShowTNSIfSelectable("Hello", StyledNotification.NotificationStyle.kTip, ObjectGuid.InvalidObjectGuid, base.Actor.ObjectId);
base.Target.mRevealingSim = base.Actor;

The first line in this code is calling the ShowTNSIfSelectable, which is a nice method of telling things through notifications. If you search in the relfector for the ShowTNSIfSelectable you will find that the parameters are 1)what you want it to say, 2)the theme of the notification is this case kTip(there are i believe 5 different themes, so go look them up and choose one you like), 3)thumbnail 1 and 4) thumbnail 2. This code will going into the "protected override bool Run" inside your interaction class.

Congratulations! now your code will add the interaction and tell you hello. Here is what the final product should look like:

using System;
using System.Collections.Generic;
using System.Text;
using Sims3.Gameplay.Objects.Miscellaneous;
using Sims3.Gameplay.Utilities;
using Sims3.Gameplay.Interactions;
using Sims3.Gameplay.Actors;
using Sims3.Gameplay.Autonomy;
using Sims3.SimIFace;
using Sims3.Gameplay.Skills;
using Sims3.UI;
using Sims3.Gameplay.Objects;
      
      namespace Sims3.Gameplay.Objects.Miscellaneous.KolipokiMod
      {
          public class TalkingTeddy : StuffedAnimal
          {
              protected Sim mRevealingSim;

              public override void OnStartup()
              {
                  base.OnStartup();
                  base.AddInteraction(TalktoMe.Singleton);
              }
              private sealed class TalktoMe : ImmediateInteraction<Sim, TalkingTeddy>
              {
                 // Fields
                   public static readonly InteractionDefinition Singleton = new Definition();
                    private const string sLocalizationKey = "Gameplay/Objects/Miscellaneous/TalkingTeddy/TalktoMe";
                // Methods
                   private static string LocalizeString(string name, params object[] parameters)
                  {
                   return Localization.LocalizeString("Gameplay/Objects/Miscellaneous/TalkingTeddy/TalktoMe:" + name, parameters);
                  }
                  protected override bool Run()
                  {
                      //Do the interaction here.                   
                      base.Actor.ShowTNSIfSelectable("Hello", StyledNotification.NotificationStyle.kGameMessagePositive, ObjectGuid.InvalidObjectGuid, base.Actor.ObjectId);
                      base.Target.mRevealingSim = base.Actor;
                      return true;
                  }
                  // Nested Types
                  private sealed class Definition : ImmediateInteractionDefinition<Sim, TalkingTeddy, TalkingTeddy.TalktoMe>
                  {
                      // Methods

                      protected override string GetInteractionName(Sim a, TalkingTeddy target, InteractionObjectPair interaction)
                      {
                          return TalkingTeddy.TalktoMe.LocalizeString("TalktoMe", new object[0]);
                      }
                      protected override bool Test(Sim a, TalkingTeddy target, bool isAutonomous, ref GreyedOutTooltipCallback greyedOutTooltipCallback)
                      {
                          return !isAutonomous;
                      }
                  }
              }
          }
      }

Save your project (again) and click on Build -> Build Solution. This will build the project and see if it has any errors, if it doesn't it will create a nice .dll for you. You will find it in Documents\Visual Studio xxxx\Projects\{YourProjectName}\{YourProjectName}\bin\Release. That file will be used to add your script to your cloned object and make it work. If you ever change the code be sure to click on Build -> Build Solution again.

Adding your script to your package

The next step in this process is to add the script to the package. We are going to be making a new resource that will have the tag S3SA. Before we go making a new resource we need to FNV Hash and get an instance name.

• Tools -> FNV Hash. Inside the box that says Text to Hash write the class name of your object. For me I would write "TalkingTeddy". Copy the FNV64 number, that will become the new instance.
• Close the FNV Hash tool and back in the S3PE main window, click on Resource -> Add…
• As type choose S3SA. Enter 0 for the Group and paste the FNV64 value into the Instance field. For convenience, tick the “Use resource name” field and enter the name of the resource in the Name field. Once you’re done, click on Ok.

S3PE will now show the S3SA resource and a _KEY resource. You can just ignore the latter one. Select the S3SA resource and on the bottom of the S3PE window, click on Grid.

• Select Import/Export/Edit…, click on the drop-down button on the right and click on Import…
• Navigate to the .dll file MVSC# created. It will be in Documents\Visual Studio xxxx\Projects\{YourProjectName}\{YourProjectName}\bin\Release. Select the file; click on the Open button and back in S3PE’s Data Grid window click on Commit

Language Localization

When your testing your object in game after finishing the last step you may have noticed that the interaction would say Something like KolipokiMod.TalkingTeddy.TalktoMe. If you would like to change that you will need to edit the STBL resource.

• Open your package in s3pe
• Tools -> FNV Hash
• Enter the namespace you saw in game in the Text to Hash box -> Click Calculate and copy the value in the FNV64 field. That value will be the instance of your STBl resource.

FNV Hash the name that shows up in game and copy the instance in the FNV64. Find the file with an STBL file type (make sure its your language) and hit editor. A STBL Resource Editor will appear. Change the instance in the bottom to the FNV64 Hash and hit add. A new string will appear. Click on it and in the box to the right write out what you want it to say.

Congratulations

You have now finished your object and should have an understanding of how to make your own object mod. I cannot wait to see what you guys create.

Special Thanks goes specially to Wito who helped me start out in object modding. I'd also like to thank Rick, Tiger, and ChaosMage for there help answering questions that I had come across. Thanks to Sri for telling me to try Object Modding.

Video Version

This tutorial is now on video and can be found at The Sims Supply, [URL=http://thesimsupply.com/showthread.php?tid=231]here[/URL].