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

Revision as of 14:13, 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. VS will show known classes in light blue, but StuffedAnimal part of your class declaraion will be shown in black. Maybe it even gives you an error like this:

Error	1	The type or namespace name 'StuffedAnimal' could not be found (are you missing a using directive or an assembly reference?)

At the top of your code, add using Sims3.Gameplay.Objects.Miscellaneous;. You'll know where. StuffedAnimal will now be shown in light blue, and if you got the stated error, it should vanish if you press F6. The using directive basically tells VS an address and to assume that everything you write might refer to that address. So if we write StuffedAnimal now, VS will assume that we in fact mean Sims3.Gameplay.Objects.Miscellaneous.StuffedAnimal, and obviously that's exactly what we mean. That works well as long as everything we write is unambiguous. If there were two StuffedAnimal classes and we used two using directives with the addresses to these classes, then VS obviously couldn't tell which one we mean when we just write StuffedAnimal. In that case we'd need to in fact use Sims3.Gameplay.Objects.Miscellaneous.StuffedAnimal to specifiy what exactly we mean.

Adding the interaction

Through this step we will be using Reflector so make sure you have it opened and that you have opened the libraries that we extracted in the first step. Let's have a look at how interactions are defined:

• Expand Sims3GameplayObjects -> Sims3GameplayObjects.dll -> Sims3.Gameplay.Objects.HobbiesSkills -> Easel -> ScrapPaintingInteraction
• Open the dissasembler by hitting the spacebar.
• Click on "Expand Methods" on the bottom of the Disassembler window.

The ScrapPaintingInteraction interaction is a very simple interaction. Let's look at it in more detail:

public sealed class ScrapPaintingInteraction : ImmediateInteraction<Sim, Easel>
{
    public static readonly InteractionDefinition Singleton = new Definition();

    public override bool Run()
    {
        if (base.Target.CurrentCanvas.Artist == base.Actor.SimDescription)
        {
            EventTracker.SendEvent(EventTypeId.kScrappedPainting, base.Actor);
        }
        base.Target.ScrapPainting();
        return true;
    }

    [DoesntRequireTuning]
    private sealed class Definition : ImmediateInteractionDefinition<Sim, Easel, Easel.ScrapPaintingInteraction>
    {
        public override string GetInteractionName(Sim a, Easel target, InteractionObjectPair interaction)
        {
            return Easel.LocalizeString("ScrapPainting", new object[0x0]);
        }

        public override bool Test(Sim a, Easel target, bool isAutonomous, ref GreyedOutTooltipCallback greyedOutTooltipCallback)
        {
            return (target.CanScrap(a) && !target.InUse);
        }
    }
}

Let's look at a few key parts:

Interaction Declaration

public sealed class ScrapPaintingInteraction : ImmediateInteraction<Sim, Easel>

• The interaction is declared as public sealed. Public basically means that all other code can "see" the class; sealed means that no sub classes may be derived from it.

• The class is derived from ImmediateInteraction. ImmediateInteractions are interactions that don't get added to a sim's interaction queue and run immediately no matter and not disturbing what a sim is doing. The <Sim, Easel> declares that the Actor of the interaction is a sim and the Target is an easel. Also a ImmediateInteraction can usually be recognized by the orange circle on the button on the pie menu.

Running

public override bool Run()

• The Run() method is where the actual action happens. We'll come back to that later.

Definition

[DoesntRequireTuning]
private sealed class Definition : ImmediateInteractionDefinition<Sim, Easel, Easel.ScrapPaintingInteraction>

• In the game, an actual interaction is something with an actual actor and an actual target, in this case one specific sim and one specific easel. The abstract idea of an interaction that might or might not run at some point in the future, including a prospective sim and a prospective easel, is referenced by an InteractionDefinition.

• In this case Definition is derived from ImmediateInteractionDefinition which is appropriate for an ImmediateInteraction. <Sim, Easel, Easel.ScrapPaintingInteraction> doesn't look much different from the declaration of the Interaction, except that the last part declares it as an InteractionDefinition for a Easel.ScrapPaintingInteraction.

• The [DoesntRequireTuning] attribute tells the game that there's no ITUN resource containing tuning for this interaction, so it doesn't need to bother looking for one. Adding tuning to your interactions goes beyond the scope of this tutorial; just use the attribute whenever you write an interaction without tuning.

Singleton

public static readonly InteractionDefinition Singleton = new Definition();

• The static Singleton field is that mentioned InteractionDefinition the game uses to reference the mentioned "idea of an interaction". We'll see later how to use that.

Getting A Name

protected override string GetInteractionName(Sim a, Easel target, InteractionObjectPair interaction)

• The GetInteractionName() method gets used for the string on button in the pie menu and the mouse over text on the interaction's thumbnail in a sim's interaction queue. Of course an ImmediateInteraction doesn't show up in the queue so the latter part is JFYI.

Testing It

protected override bool Test(Sim a, Easel target, bool isAutonomous, ref GreyedOutTooltipCallback greyedOutTooltipCallback)

• The Test() method is the special sanity check for the interaction. It will get called before the game shows a pie menu and only if Test() returns True will the interaction show up in the pie menu.

• There's an exception to the previous point: If Test() return False, but assigns a GreyedOutTooltipCallback, the interaction button will show up, but will be greyed out. But again, that goes beyond the scope of this mod.

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].