Skip to main content

Introducing Feature v2

· 4 min read
rgantzos

As of ScratchTools v2.25.0, there's a new version for making ScratchTools features. It's called Feature v2, and makes it easier for developers to make new features and edit existing ones. I'll walk you through the changes that this new version brings. Head's up: Feature v2 is, in most cases, the only acceptable format for new features that you may want to add to ScratchTools. This means that all features should be made in Feature v2 before opening a pull request to the repository.

Feature File​

In the features.json file, here's what a normal feature would look like before Feature v2:

{
    "title": "Custom Studio Section",
    "description": "On the homepage of the Scratch website, the newest projects from the studio of your choice are displayed above the Featured Projects.",
    "credits": ["rgantzos"],
    "urls": ["https://scratch.mit.edu/users/rgantzos/"],
    "file": "custom-studio",
    "tags": ["Featured", "New"],
    "type": ["Website"],
    "options": [
      { "id": "Studio ID", "name": "Studio ID", "default": "27205657" }
    ]
  }

With Feature v2, here's what the changes to the features.json file would look like:

{
  "version": 2,
  "id": "emoji-status",
  "versionAdded": "v2.29.0"
}

Yeah- it's a lot simpler. And organizing the features is easier than ever. Speaking of organizing features, here's how it works.

Feature Folder​

Every feature has an id. This replaces the file key that is used in the features.json file in Feature v1. While the id remains in that file, a new folder is created within the /features/ directory, and the folder is named after the id.

Inside the folder you've made, create a file called data.json. This is where the feature's information goes. Here's what it looks like:

{
  "title": "Emoji Statuses",
  "description": "Set the status on your profile to an emoji. Other ScratchTools users will be able to see this status.",
  "credits": [
    { "username": "rgantzos", "url": "https://scratch.mit.edu/users/rgantzos/" }
  ],
  "tags": ["Featured"],
  "scripts": [{ "file": "script.js", "runOn": "/users/*" }],
  "styles": [{ "file": "style.css", "runOn": "/users/*" }],
  "dynamic": true,
  "default": true,
}

Here's what each key means:

title (string)​

This is the title of the feature. It's how it's displayed in all languages on the settings page, as well as the website.

description (string)​

This is the feature's description. Like the title, it will be displayed in all languages on the settings page and website.

credits (object)​

This array should include the credits for the feature- who contributed to the feature in a significant way. Each object within the array should have a username key and a url key, both of which are strings. One is the username of the user who contributed, and the other is a link to their profile.

tags (object)​

This is an array with multiple strings in it, each one meaning a different thing. Here are the different tags:

  • Featured (only maintainers will add this tag, usually during release)
  • Recommended (this a significant feature that users should try)
  • New (this is a new feature)

While tags aren't currently in full use, they will be soon.

scripts (object) and styles (object)​

These are arrays that contains all the scripts/styles that the feature should run, and where to run them. Here are the keys that each item in the array should hold: file This is the file to run, relative to the folder itself. For example, if the file's path is /features/myfeaturefolder/script.js, then the it should look like this:

{ "file": "script.js", "runOn": "weWillGetToThisLater" }

The same is true for CSS files, but in the styles key of the data.json file. runOn This is what pages of the Scratch website the specified file should run on. It will never be inserted into other pages of the Scratch website. It's a regex. Here are some examples:

  • Scratch homepage: /
  • Project pages and the editor: /projects/*
  • Profile pages: /users/*

dynamic (boolean)​

This specifies whether or not the feature can be enabled/disabled without reloading the Scratch page. If a dynamic feature has styles on an open page of a Scratch website, and the feature is disabled, then the CSS files will automatically be removed from the page.

When disabling a feature with JavaScript on a page (scripts), the file must specify how it should be disabled. Both CSS and JS files will be inserted into the page if they belong to a dynamic feature that has been enabled.

default (boolean)​

This determines whether or not the feature should be automatically enabled for users that download the extension. This is usually only added by maintainers when merging a new feature.

Concluding​

So, this is what Feature v2 looks like in ScratchTools. All new features should aim to use this new version, and many existing features are being converted into the new Feature version.