obviousstudios / scratch-ext-utils

Tools made by Obvious Studios for interacting with the Scratch VM

Table of contents

• Intro
  • VM Surfer
  • Extension Builder
    • Initilizing
    • Adding a Block
      • Event activated Hats
    • Arguments
      • Inline Images
    • Adding a Button
    • Menus
      • Static
      • Dynamic
    • Adding Labels
    • Adding Dividers
    • Filtering
    • Hiding Blocks
    • Registering

What is VM-Utilities?

A bunch of wrappers for better interacting with the scratch VM and the object's it holds within itself.

VM surfer

VM surfer allows you to surf through all sprites clones and the stage as well as thier local variables and lists. All you really need to know is how to refresh

vmSurfer.refreshJSON();

Extension Builder

Some code that makes building extensions faster since you don't have to sort through json and everything can be done through simple functions

Initilizing an extension

const extension = new ExtensionBuilder("Extension", "extension")

Adding a block

extension.addBlock() allows you to create a block in your extension
the first argument is the text.
the second is the block's ID.
the third is the block type.
the fourth is the functions code.
the fifth is optional but allows you to overide and modify values in the block.

extension.addBlock("Test Block [testArg]","tBlock",Scratch.BlockType.BOOLEAN,
// The blocks code goes after the block type
() => {
  console.log("This Works!")
})

Event activated hats

Say you want to create a hat and activate it at certain points. How would you do that?
well that is where setEdgeActivation() comes in handy
after declaring a block you can use setEdgeActivation() to set the edge activation status
The first and only argument for this function is weather edge activation is on.
For this hat we will set it to false.

When we want to activate it all we need to do is run the function runHat() .
The first and only argument of runHat() is the target Hat's ID.
Like this

extension.runHat("eventHat");

Example

Adding an argument to a block

Adding an argument is a simple as running addArgument() after declaring a block
the first argument is the argument's name.
the second argument is the default value with type inference built in.
the third is optional and allows you to overide the type inference for the argument.
the fourth is optional and lets you define a menu for the argument.

extension.addBlock("Test Block [testArg]","tBlock",Scratch.BlockType.BOOLEAN,
// The blocks code goes after the block type
() => {
  console.log("This Works!")
}).addArgument("testArg","1")

Adding an image to a block

Adding an image as an argument is as simple as running addImage() after declaring a block
the first argument is the argument's name.
the second argument is the image's dataURI.
the third is optional and allows you to flip the image.

const imageURI = //Very long data URI of an image or SVG
    
extension.addBlock("Look at this cool iamge! [image]","imageTest",Scratch.BlockType.COMMAND,
() => {
  console.log("Why are you looking at the console >:(")
}).addImage("image",imageURI,false)

Example

Adding a button

extension.addButton() allows you to create a button in your extension
the first argument is the button's ID.
the second is the button's function
the third is the button's text

extension.addButton("myButton",
  ()=>{
    alert("Buttons!")
  },
  "My button!");

Example

Adding a menu

adding a menu can be done via extension.addMenu()
the first argument is the menu name.
the second argument is the menu's items this can either be a function or a json a function will make it a dynamic menu.
the third optional is whther the menu accepts reporters or not.

Static menu example

extension.addMenu("Menu",["1","2","3"])

Dynamic menu example

extension.addMenu("Menu",() => {
    return ["1","2","3"]
})

Adding Labels

You can use addLabel() to add a Label between two blocks

extension.addLabel("Made by ObviousAlexC")

Adding Dividers

You can use addDivider() to add a divider between two blocks

extension.addDivider()

Filtering Blocks

You can use setFilter() to filter the blocks to a specific sprite type
the first argument is the filter type. This is optional and if you don't put in anything it will be sprite only.

extension.addBlock("This is a boolean that only appears on the sprite!","tBlock3",Scratch.BlockType.BOOLEAN,() => {
    console.log("This Works!")
}).setFilter(Scratch.TargetType.SPRITE)

Example

Hiding Blocks

You can use hideBlock() to hide the current block

extension.addBlock("This Block won't appear.","tBlock",Scratch.BlockType.BOOLEAN,() => {
    console.log("This Works!")
}).hideBlock()

Registering an extension

and finally you can call extension.register() to register your extension

const extension = new ExtensionBuilder("Test Extension", "tExt")

extension.addBlock("Test Block [testArg]","tBlock",Scratch.BlockType.BOOLEAN,() => {
    console.log("This Works!")
}).addArgument("testArg","1",null,"Menu")

extension.addMenu("Menu",["1","2","3"])

extension.register()

the final code for creating an extension with a testing block!