Beginner’s Guide to Sims 4 Toolkit

Take the Tedium Out of TS4 Modding

STOP!

This article was written before the Sims 4 Toolkit VS Code extension was published. Most users should be using the extension instead of using the S4TK Node library itself. This article may still be of interest to those wanting to write their own scripts.

If you want to learn how to use Sims 4 Toolkit (S4TK) but don’t know the first thing about JavaScript or Node, you’re in the right place. This article will teach you the purpose of S4TK, the basics of JavaScript and TypeScript, and how you can use S4TK to supercharge your mod making.

No prior knowledge of JavaScript, TypeScript, Node, or npm is assumed, and no setup is required to follow along. While the ultimate goal is for you to be comfortable setting up your own development environment, this article will link to tutorials in the S4TK Sandbox, so you can practice right here in your internet browser*.

*Chrome, Edge, or Firefox is recommended. Safari has known performance issues, and no other browsers were tested for compatibility.

Table of Contents

1. What Is Sims 4 Toolkit, and What Does It Do?
2. The World of JavaScript
3. S4TK at a High Level
4. Learning S4TK With the Sandbox
5. Setting Up an S4TK Node Environment

What Is Sims 4 Toolkit, and What Does It Do?

Sims 4 Toolkit is an open source Node.js library written in JavaScript (well, TypeScript, but I’ll get into that later). It can create, read, and edit package files and the resources that they contain (such as XML tuning, SimData, and string tables).

S4TK can be used to extract and search through the game’s files, generate resources, perform batch-fixes, and power web-based tools for modding, such as the TDESC Browser, String Table Studio, and the Package Viewer. If what you want to do involves tuning, SimData, and string tables (plus some other various resources), S4TK can probably automate it.

The S4TK library consists of several modules that are distributed on npm. These modules are documented on sims4toolkit.com, and their source code can be viewed on GitHub. If you’re not familiar with JavaScript, TypeScript, Node, and npm, do not fret — you’ll learn more about them in the next section.

The World of JavaScript

This section will teach you what you need to know about JavaScript, TypeScript, Node, and npm to get started with S4TK. It is by no means a complete introduction, and I encourage you to continue learning on your own — the internet is saturated with resources.

What’s What

JavaScript is the programming language that powers the internet. It’s notorious for being quirky and having many different “flavors” — most notably, there’s the JavaScript that runs in your browser, and there’s the JavaScript that runs in Node. To keep things simple, we’re going to focus on Node, since that’s what S4TK uses.

TypeScript is a statically typed superset of JavaScript, which means that type errors can be caught at compile time rather than at runtime. The type system of TypeScript is a façade — TypeScript itself cannot run in your browser or in Node, it must first be compiled to plain JavaScript. All of the S4TK packages are written in TypeScript and distributed as JavaScript. For the purposes of this article, do not worry about TypeScript — you’ll be using JavaScript in the S4TK Sandbox.

Node is a runtime that allows you to run JavaScript code outside of an internet browser, so that servers and applications can be written with JavaScript as well. There are many more non-browser JavaScript runtimes out there, but Node is by far the most popular one. To use Node, you just have to download and install it from its website. Installing Node will also install npm, which is the “Node Package Manager”.

npm is the default package manager for Node. Its website hosts many JavaScript-based packages, such as S4TK, and its command line interface allows you to install these packages in your JavaScript projects.

Learning JavaScript Syntax & Concepts

Writing my own beginner’s guide to JavaScript here would be doing you a disservice. There are plenty of solid JavaScript tutorials out there, including this extremely well written one for beginners. It is lengthy, but worth the read if you’re serious about learning JavaScript for use with S4TK. However, you do not have to read part 2, as it covers browser JavaScript, which is something you cannot use in Node.

If you’re not already familiar with JavaScript, please read through the linked article, and feel free to do your own research and learning as well. You don’t need to be an expert, but a good grasp on the JavaScript language is important to using S4TK, and the remainder of this article will assume that you understand JavaScript syntax.

Getting Acquainted With Node

So far, you’ve read about the JavaScript language itself, not Node. JavaScript is (mostly) the same regardless of where it’s used, but it differs greatly in terms of available modules how you use them. For instance, there is no browser DOM in Node, and there are no Node modules in the browser.

To import modules in Node scripts, you can use require :

// fs is the built-in Node filesystem module
const fs = require("fs");

// now that you've imported fs, you can use it to read files
const buffer = fs.readFileSync("path/to/file");

require is not magic, it’s just a function that returns a value. When “importing” Node modules, all you’re doing is calling a function and saving its returned value in a variable. There are many more modules built-in to Node; you can view the Node.js API documentation for a complete list.

To use external libraries/modules (like S4TK), you need to use a package manager like npm or yarn (note that S4TK is only available through npm). Setting up a Node project with npm will be explained in the “Setting Up an S4TK Node Environment” section, after you’ve used the S4TK Sandbox to learn the fundamentals of the library.

S4TK at a High Level

Sims 4 Toolkit can “read and write package files and the resources they contain”, but what does that really mean?

Packages and Resources

To understand S4TK, you need to understand what packages are. They are just a file format, similar in concept to a ZIP archive. Packages contain resources, which are things like tuning, SimData, string tables, etc.

In order to work with packages and resources, S4TK has models that represent their data in a way that is easy to work with. For instance, there is a model called Package that represents packages, and it contains a list of resources. Individual resources also have models, such as XmlResource which has an XML document, and StringTableResource which contains a list of key/string pairs.

Sims 4 Toolkit vs. Sims 4 Studio

You may be wondering what the purpose of S4TK is when we have Sims 4 Studio, which offers a GUI for editing packages and their resources. The answer is the potential for automation.

S4S is a very manual program, and relies on the user creating and editing their files themselves. This is fine, and is often very helpful. However, it also means that if you want to create 50 buffs, you have to manually create 100 individual files (50 tunings + 50 SimDatas), not to mention the strings you’d have to hash and add to a string table.

With S4TK, you can write a script that generates those files, fills their content, and even hashes your strings automagically. Not only does this make the creation of the files easier, but it’s also easier to maintain (need to change something in every file? just regenerate them). Finally, it reduces the potential for human error — after all, computers don’t get bored and lose focus, but you and I certainly do.

That’s It

Seriously, that’s all it is. S4TK is just a way to model and interact with TS4 files using JavaScript, which enables you to automate tasks like file generation with a script. Hopefully this de-mystifies things a bit, and you’re now ready to jump right in to learning S4TK.

Learning S4TK With the Sandbox

The S4TK Sandbox is a website where you can run S4TK scripts without setting up your own Node environment. It has a code editor that provides some Node features, such as require(), buffers, and of course S4TK.

The scripts that you write in the sandbox should Just Work™ in Node, with the exception being how files are read/written. When converting sandbox scripts to Node, be sure to replace the sandbox import/download functions with Node’s fs module (find the docs for fs here).

The Tutorials

Other than the main code editor (which has its own file system you can use to import/download files), there are many interactive tutorials specifically designed for newcomers to JavaScript. You can find these tutorials here:

S4TK Tutorials (sims4toolkit.com)

To get started, you should follow the “Get to Know the Sandbox” and “Introduction to S4TK” tutorials to set the context for everything else. From there, start with the beginner tutorials, and then move up to intermediate, and eventually go on to the advanced ones (coming soon).

Setting Up an S4TK Node Environment

To get the most out of S4TK, you’ll have to graduate from the sandbox to using it locally in Node. When used locally, S4TK can extract resources from your game and bundle loose XML files into a package.

For the best development experience, I recommend using TypeScript with S4TK, since getting types right is paramount when working with binary files like you do in S4TK. However, since this is a beginner’s guide, I will be sticking to JavaScript for now.

Install Node & npm

If you haven’t installed Node and npm yet, do that now. Choose the version for your operating system and follow the instructions. If on Windows, some additional software (such as Chocolatey) may need to be installed as well.

To verify your installations were successful, run the node -v and npm -v commands in Terminal (macOS) or PowerShell (Windows). If they output a version number, you’re good to go.

Install an IDE for JavaScript/TypeScript

An IDE is an “integrated development environment” — you’ll need one for your S4TK projects. You can use whichever IDE you prefer, but I highly recommend Visual Studio Code (VSC) — it’s free, customizable, and comes with first-class support for JavaScript, TypeScript, and Node.

The rest of this tutorial assumes that you are using VSC, so if you are not, your steps may be a little different.

Create a Node Project

This step varies depending on your intentions with S4TK. Since this is a beginner’s tutorial, I’ll assume you’re either making one-time scripts (such as file generation or extraction) or a package builder for a mod, so I’ll explain both in following sections.

Regardless of the project you’re making, the first step is to create a folder for it wherever you want, then open it with your IDE (if using VSC, go to File > Open Folder in the toolbar).

Since you’re not publishing this project on npm, using npm init would add some unnecessary boilerplate. Instead, just create a file called package.json in your folder, and paste in the following content (replacing "your-project-name" with whatever your project’s name is).

{
  "name": "your-project-name"
}

Congrats! You now have a Node project. Yes, it’s as simple as a folder with a single 3-line JSON file in it. Now let’s add some dependencies.

Add Dependencies from npm

One dependency you’re almost always going to need when working with S4TK is @s4tk/models — this contains the code for packages, resources, enumerations, and much more. So, let’s install that now.

If you do not see a command prompt open in the bottom of VSC, go to View > Terminal to toggle it on. Then, type in the following command:

npm i @s4tk/models

npm i is short for npm install , which installs a package as a dependency in your current project. After running this command, 3 things happen:

• The node_modules folder is created. This folder contains all of your dependencies, and all of their dependencies. You usually don’t have to touch this folder, and should ignore it from your source control.
• The package-lock.json file is generated. This file ensures that your dependencies install with compatible versions. You should never modify this file manually, and should check it into source control.
• Your package.json file is updated. A new section, dependencies , should have been added, and should contain @s4tk/models with a mapping to the version you installed (most recent by default).

Now that you know how to install packages, and what happens when they are installed, you can move on to creating your actual project.

Writing One-Time Scripts With S4TK

If you want to search the game files, generate resources, run a batch fix, etc., your setup will be minimal. Your first step is to determine which S4TK packages you’re going to need (documentation | npm) and install them.

For the sake of this guide, let’s write a script that generates 50 identical snippets, which differ only in name and ID. To do this, you’re going to need @s4tk/models and @s4tk/hashing. You installed @s4tk/models in the last section, so just install @s4tk/hashing now with npm i @s4tk/hashing.

Now, create a file called generate-snippets.cjs (Note: The .cjs extension stands for “CommonJS”, the flavor of JS that Node uses. You can use the regular .js extension, but using .cjs helps VSC’s intellisense).

As a recap, your file explorer should now look like this:

VSC File Explorer — One-Off Script

In the generate-snippets.cjs file, paste in the following.

// Remember - `const x = require("y")` is how you import Node modules
// If VSC is telling you to use `import x from "y"`, it is a trap
const fs = require("fs"); // built-in Node file system
const path = require("path"); // built-in Node path utilities
const { Package, XmlResource } = require("@s4tk/models");
const { TuningResourceType } = require("@s4tk/models/enums");
const { fnv64 } = require("@s4tk/hashing");

// function that turns a filename and tuning ID into a snippet resource
const createSnippet = (filename, tuningId) =>
  new XmlResource(`<?xml version="1.0" encoding="utf-8"?>
<I c="SomeSnippet" i="snippet" m="some.snippet" n="${filename}" s="${tuningId}">
  <T n="something">12345</T>
</I>`);

// new package that will contain your snippets
const pkg = new Package();

// generating 50 of these snippets
for (let i = 0; i < 50; ++i) {
  const filename = `creator_mod:statistic_${i}`;
  const tuningId = fnv64(filename);

  // creating the snippet and adding it to the package with a unique key
  pkg.add(
    { type: TuningResourceType.Snippet, group: 0, instance: tuningId },
    createSnippet(filename, tuningId)
  );
}

// making sure there is a subfolder called "out"
const outDir = path.resolve(__dirname, "./out");
if (!fs.existsSync(outDir)) fs.mkdirSync(outDir);

// writing your package in the "out" folder
fs.writeFileSync(path.join(outDir, "RandomSnippets.package"), pkg.getBuffer());

To run this script, use the command node generate-snippets.cjs — it should generate a folder called out which contains a file called RandomSnippets.package . If you open this file in S4S (alternatively, if you’re not following along, you can view it online), you’ll see that there are 50 snippets with generated names and tuning IDs.

Obviously, this is a very bare-bones example, but that’s all you need to know — this is how you would set up a project for one-off scripts using S4TK, and how you would run them.

Writing a Package Builder With S4TK

This section got unwieldy — a standalone article explaining how to set up a package builder script can be found here.