How to make a 1.4 mod

powerpoint56

Hi! If you don't know me, I'm powerpoint56, the creator of the Scratch mod Explore. I've decided to make an easy-to-read tutorial for anyone who wants to add new features and blocks to Scratch 1.4.

Chapters
Intro - Getting Started
Area fifty-what? - Navigating the source code
Adding your first block
Mastering Block-Making
Coder's Notepad
Add a new category

Note: I would recommend starting from the beginning. The pace picks up and the tutorials get more and more advanced, which gets confusing if you don't start from the beginning. However, if you have already had a lot of experience, you can try starting in the middle.

Last edited by powerpoint56 (June 16, 2014 18:55:36)

Explore, my Scratch mod | Car Crash | My projects | (image by @MicroMacro)

powerpoint56

Getting Started

To create a brand new mod, download the Scratch Source Code and extract the contents to a normal folder. You may also want to see some more information. Also, if you don't have Scratch, download it here. Then, copy the following files from your Scratch folder into the Scratch Source Code folder:

Scratch.exe
Scratch configuration settings
CameraPlugin.dll
Mpeg3Plugin.dll
ScratchPlugin.dll
UnicodePlugin.dll
WeDoPlugin.dll

Then, you can rename Scratch.exe, ScratchSourceCode1.4, and Scratch config. settings to fit your mod. For instance, if your mod was called Bubble, then you'd rename Scratch.exe to Bubble.exe. In this tutorial, I'll always pretend Bubble is the name of your mod.

Open Bubble.exe! You should see three areas in the window: the normal Scratch program, the “System Browser”, and the “Workspace”. This is where you will make your mod.

Next chapter

Last edited by powerpoint56 (Jan. 31, 2014 14:29:13)

Explore, my Scratch mod | Car Crash | My projects | (image by @MicroMacro)

powerpoint56

Area fifty-what?
The Scratch source code may be hard to navigate at first, but with a little guidance it's very easy. You can drag the windows around however you like. To close a window, click the X on it. If there is no X, middle-click the window and click the pink X that appears in the corner. Opening new windows is pretty easy too. Now try clicking anywhere in the white space around the windows. A menu labeled “World” should appear: this is where you will start to get to anywhere in the source code. Often you will need to select {Open…>Browser} to edit the source code or {Open…>Workspace} to test a new code.

Explore these menus and windows a little more, and get used to opening and closing them. The final step is to learn how to save your work. Click the white space and select “Save” or “Save and quit”. If you want to save your work so that it looks normal (without the source code open), shift-click the File menu and select “Save Image in User Mode”. The next time you open Bubble, I'm warning you that you may panic and scream, “No, all of my source code is gone!!!” But no, just shift-click the File menu and select “Exit User Mode”. The white space will appear again.

Open the system browser (if you don't remember how to find it, reread the first paragraph). You will see four columns. The first on the left is a list of all the categories in Squeak. Imagine a category like the main, thick part of a tree. Both categories and tree trunks hold together many big branches, called sub-categories (in the second column). Each sub-category has a role to play, and that role is determined by the code inside of it.

Note: Actually, the whole story about categories and sub-categories is much more complicated, but unnecessary to learn yet. If you would like to do more research, see dreamod's excellent Squeak Tutorial: here

Go to the category Scratch-Objects, and then to its sub-category ScriptableScratchMorph. Notice that right below the second column, there are two buttons: Instance and Class. Let's say that you had a sub-category called Car. Instance would have events (called methods) that Car needs to do, like “Drive”, “Stop”, or “Turn”. These events happen only happen if they are told to. Sometimes, methods tell each other to do certain things, but often, the Class will tell a method in Instance to work. Class is often used to describe attributes and properties of sub-category. For example, the School Class might describe the teachers at the school and then tell them to begin teaching.

Overview of everything so far: You have learned how to navigate the source code easily and how to save your work. I've explained the browser and categories. Finally, I have explained the difference between Class and Instance methods and the role they play.
Once you understand this, go to the next chapter to add your first block!

Next chapter

Last edited by powerpoint56 (July 30, 2014 00:36:06)

Explore, my Scratch mod | Car Crash | My projects | (image by @MicroMacro)

Epicness123

Thanks! This really helped me!

Sadly, my kumquats were eaten by an evil forum signature.

powerpoint56

Epicness123 wrote:
Thanks! This really helped me!

You're welcome! A lot of new tutorials are coming soon!

Explore, my Scratch mod | Car Crash | My projects | (image by @MicroMacro)

powerpoint56

Adding your first block
You may have heard of obsolete blocks, old blocks that used to be in Scratch but aren't anymore. A few of these blocks can actually be very useful, and it's easy to add them to your mod.

Go to Scratch-Objects > ScriptableScratchMorph (Class) > block specs > obsoleteBlockSpecs. This is where all obsolete blocks are stored. Note the layout of this code. Let's analyze it. The first line says “obsoleteBlockSpecs”. This is the title of the method; all methods have titles so other methods can refer to each other. Next, you see a line in quotes, a comment. Just like in Scratch, a comment doesn't do anything except tell the user a message. The ^ is reporting a long list surrounded in parentheses. Each item is formatted like this:

('block name' -block type- method)

The block name is what shows up on an actual block in Bubble. The block name for

move (10) steps

is 'move %n steps'. But why “%n”? Why not… “%Bubble”? “%n” stands for Number input. The block has a place where you put in a number, and your block name has to show that. Take note of these types:

%s = String
%n = Number
%b = Boolean
%c = Color

Also, every block item has a type. This is usually - (normal stack), r (reporter) or b (boolean). Finally, every block item has a method. This method will be from ScriptableScratchMorph Instance. Remember, Instance is where you put actions for Class to describe. These block specs are describing blocks that come from methods in Instance.

Now you know how blocks specs are formatted. Go down to the ‘obsolete sound blocks’ in the obsolete block specs, and cut the “rewind sound” block spec. Press ALT+S or right-click+Save to save your work. Open the blockSpecs method and find the Sounds category. Then, paste the “rewind sound” block into the category. Make sure that your block spec fits the format of the other specs, and is in the right place. Save the method and open the Sounds category. Your block should be there! Shift-click the File menu and save your .IMAGE.

Next chapter

Last edited by powerpoint56 (Feb. 3, 2014 00:15:22)

Explore, my Scratch mod | Car Crash | My projects | (image by @MicroMacro)

powerpoint56

Mastering Block-Making
We're going to do a little practice coding that will add really cool features to Bubble (or whatever your mod is called). Open Bubble again, exit user mode, and open the browser. Go to ScriptableScratchMorph (Instance) > looks ops > changeGraphicEffect:by:. This is the method for

change [color v] effect by (10)

Look through the code. There's are a lot of phrases that say "'blah' = effect ifTrue: []“. This sees if the effect the block says to change is ”blah“. You'll see effects that you know, like ”color“ or ”brightness“, but there are also new ones like ”saturation“ and ”blur". How do you get those into your mod? The code for these effects is already made, so all we need to do is add the new effects to the option dropdown in the block. Find the method graphicEffectNames. This is a list (similar to block specs) of all of the options in the dropdown. Add 'blur', 'saturation' and 'pointillize' to the list, so the code looks something like this:

graphicEffectNames
	"Answer a collection of graphic effect names."

	^ #(
		'color'
		'fisheye'
		'whirl'
		'pixelate'
		'mosaic'
		'brightness'
		'ghost'
		'blur'
		'saturation'
		'pointillize')

Save the method and open the Looks category. Try out the new graphic effects you added!
But don't leave yet. You've learned a little bit about block specs and block code, and now it's time for the ultimate challenge of making a new block.

We're going to try to make this Scratch 2.0 block for our mod:

(current [minute v])

Coding blocks in Squeak often needs a special sub-category related to the block. We need to find a category first, related to “amounts” or “size”. Scroll through the categories until you see Kernel-Magnitude. This has sub-categories dealing with size, which may help. Open it, and you'll discover categories for time and the date! Open Date (class) > instance creation. This has methods that describe what you want to find about the date. We want the current date, just like our block says. Open a new browser window, and go to ScriptableScratchMorph (Instance) > sensing ops. In the scripting area, begin to create the code.

currentTime: wanted
	| date time |
	date _ Date today.

“currentTime:” is the title. The variable, “wanted”, is shown so it can be used later. Two temporary variables, surrounded by “| |”, are shown in the next line. The actual code starts with setting the variable “date” to the date today (remember the sub-category Date?).

We also need to find the current time. Go to Kernel-Magnitudes > Time (class) > instance creation. You'll see the method now, which, like today in Date, will lead us to find the specific time. Write this:

currentTime: wanted
	| date time |
	date _ Date today.
	time _ Time now.

The rest is easy. Look through the Time and Date Instance methods to find each item. Here's what the result should be like:

currentTime: wanted
	| date time |
	date _ Date today.
	time _ Time now.
	'time' = wanted ifTrue: [^ time asString].
	'hour' = wanted ifTrue: [^ time hours].
	'minute' = wanted ifTrue: [^ time minutes].
	'second' = wanted ifTrue: [^ time seconds].
	'date' = wanted ifTrue: [^ date asString].
	'year' = wanted ifTrue: [^ date year].
	'month' = wanted ifTrue: [^ date monthIndex].

^ View a cool Scratch block version
There! Save your work. But you still have to create the dropdown and the spec for the block. Make the dropdown items, like you did for the graphic effects block:

currentTimeDropdown
	^ #('time' 'hour' 'minute' 'second' 'date' 'year' 'month')

Save that, too. Now, remember how block specs have input types, like %n (number) and %s (string)? We need to make a new kind of input type for the dropdown in our block. Go to Scratch-Blocks > CommandBlockMorph (instance) > private > uncoloredArgMorphFor:. This is where a list of all of the input types is stored. Add your dropdown to the end of the list, according to the way the others are done.

	$y = code ifTrue: [^ ExpressionArgMorphWithMenu new numExpression: '1'; menuSelector: #listIndexForDeleteMenu].
	$T = code ifTrue: [^ ChoiceArgMorph new getOptionsSelector: #currentTimeDropdown; choice: 'minute'].
	^ ExpressionArgMorph new numExpression: '10'

Save. Go to blockSpecs in ScratchSpriteMorph (class). Add in the block spec in the Sensing category:

('current %T'          r     currentTime:)

You'll also need to add this spec to the blockSpecs in ScratchStageMorph (class). Why? Some categories, including Sensing and Looks, have some blocks only sprites use and some only the Stage uses, so their specs have to be separated.

Save. Congratulations! This is your first real block! Make sure to also save the image.
Next Chapter

Extra: Your (current {minute}) block will probably have a check-mark next to it. If you don't want that to be there, open Scratch-Blocks > CommandBlockMorph (instance) > private > canBecomeWatcher. Add your block title to the list, like this:

canBecomeWatcher
	"I determine which blocks can become watchers."

	| i |
	i _ selector asString findAnySubStr: #('mouse' 'key' 'touching' 'distance') startingAt: 1.
	^ (self isReporter) &
	   (self argumentCount <= 1) &
	   ((#(not atRandom abs rounded lineCountOfList: stringLength: currentTime:) includes: selector) not) &
	   (i > selector asString size)

Next chapter

Last edited by powerpoint56 (Feb. 3, 2014 01:31:56)

Explore, my Scratch mod | Car Crash | My projects | (image by @MicroMacro)

powerpoint56

Go back to your tutorial
This is a comparison of the Squeak code and equivalent Scratch code for the (current {minute}) block:

currentTime: wanted
	| date time |
	date _ Date today.
	time _ Time now.
	'time' = wanted ifTrue: [^ time asString].
	'date' = wanted ifTrue: [^ date asString].
        "etc"

set [date v] to (current [date v])
set [time v] to (current [time v])
if <[time] = (wanted)> then
say (time)
end
if <[date] = (wanted)> then
say (date)
end // etc

Last edited by powerpoint56 (Feb. 3, 2014 00:40:09)

Explore, my Scratch mod | Car Crash | My projects | (image by @MicroMacro)

powerpoint56

Coder's Notepad
Next Chapter

At this point, it's hard to teach about how to make code in Squeak. There's too many details that will get confusing if I try to teach them all at once. Instead, just look at the code and see how things are done. If you need help, scan through this “coder's notepad” for the solution.

_ The underscore looks like an arrow pointing to the left in Squeak. It is used to set a variable to a certain value.
Example: variable _ ‘hello world’. – This sets a variable to “hello world”.

^ This looks like an arrow pointing up in Squeak. It's used to report a value.
Example: ^ ‘hello world!’ – This reports “hello world”.

ifTrue: After a boolean, this does an action if the boolean is true. The action is contained inside of square brackets and ended with a period.
Example: (2 = 2) ifTrue: [self say: ‘hello!’]. – This makes a sprite say ‘hello!’ if 2 is equal to 2.

ifFalse: The same as ifTrue:, but the opposite.

timesRepeat: The same as the {repeat x times} c-block. Put a number before it (i.e. 2 timesRepeat: ). After that, put the action to be repeated in brackets. End with a period.
Example: 2 timesRepeat: . – This does the action twice.

whileTrue: Put a boolean surrounded by brackets before it (i.e. [2 = 2] whileTrue: ). After that, put the action to be repeated in brackets. End with a period.
Example: [2 = 2] whileTrue: . – This does the action while 2 equals 2.

whileFalse: – The same as whileTrue:, but the opposite.

self This is a very important part of Squeak. This is often followed by a method in the sub-category it's being run from.
Example: self doThis. – If this were done in ScriptableScratchMorph, it would make ScriptableScratchMorph run its method “doThis”.

self ownerThatIsA: is always followed by the name of a sub-category. It “reports” the instance section of the sub-category so you can run its methods.
Example: (self ownerThatIsA: ScratchFrameMorph) doThis – This would make ScratchFrameMorph do the instance method “doThis”.

(Sub-category new) doThis Replace “Sub-category” with a real sub-category. This makes a new instance of the sub-category and runs the method.

t1 findTokens: t2 reports a list that is identical to t1, except that it is split at every occurrence of t2.
Example: t3 _ ‘Hi. How are you?’ findTokens: ‘.’ – This would make a list (OrderedCollection) called t3: “Hi”, “How are you?”.

t1 at: t2 reports item t2 of OrderedCollection t1.
Example: ^ t1 at: 5 – This would report the 5th item of the list t1.

t1 at: t2 put: t3 replaces (t1 at: t2) with t3.
Example: t1 at: 5 put: ‘Replacement’ – This replace (t1 at: t2) with “Replacement”.

t1 add: t2 adds t2 to the OrderedCollection t1.

Next Chapter

Last edited by powerpoint56 (July 8, 2015 18:37:03)

Explore, my Scratch mod | Car Crash | My projects | (image by @MicroMacro)

powerpoint56

Add a new category
I learned most of this from LS97's tutorial: Modding Scratch VFAQ

To add a new category, you first need to download the Scratch Skin here: http://download.scratch.mit.edu/source-code/ScratchSkin1.4.zip. Extract the ZIP folder to your mod's folder. Copy the files controlPressed, controlOver, and control and rename the copies with the name of your category (yourCategoryPressed, yourCategoryOver, yourCategory). Optionally, you can edit the pictures with a graphics-editing software so that they're the color of your category.

Then, open Bubble (your mod), and from there open the workspace. Type in the below code, select it, and choose to “do it”.

ScratchFrameMorph readSkinFrom: (FileDirectory default directoryNamed: 'ScratchSkin')

Any time you edit the Skin in any way, you'll need to run this code to make your changes take effect.
Go to Scratch-UI-Panes > ScratchViewerMorph (instance) > –all– > rebuildCategorySelectors. Add your category/categories to the list. If you're adding an odd number of categories, go down to where it says “catButtonsExtent _” and replace the line with this code:

catButtonsExtent _ ((2 * maxExtent x) + (3 * pad)) @ ((((catList size / 2) rounded) * (maxExtent y + 6)) + 25).

Finally, we have to specify the color of the blocks in our category. Go to ScriptableScratchMorph (class) > blockSpecs > blockColorFor:. Add the below line to the other lines like it in the code. Replace “yourCategory” with your category's name and the color with any color. You can also use rgb.

	'yourCategory' = aCategory ifTrue: [^ (Color h: 25 s: 0.88 v: 0.95)].

Save the .IMAGE and open your mod again. You'll see your new category there!

Last edited by powerpoint56 (July 8, 2015 18:31:53)

Explore, my Scratch mod | Car Crash | My projects | (image by @MicroMacro)

powerpoint56

bump

Explore, my Scratch mod | Car Crash | My projects | (image by @MicroMacro)

turkey3

These are great! Thanks!

DigiTechs

Just a quick suggestion; to make everything more compact, you could ask the ST or other people with the permissions to either move all posts by other people to the end when you've finished the tutorials, or ask them to delete the posts.

I do, in fact, have my own site; it's here.
I'm also working on a thing called Fetch. Look at it here!
@thisandagain pls explain. @thisandagain pls explain. @thisandagain pls explain. @thisandagain pls explain. @thisandagain pls explain.

powerpoint56

DigiTechs wrote:
Just a quick suggestion; to make everything more compact, you could ask the ST or other people with the permissions to either move all posts by other people to the end when you've finished the tutorials, or ask them to delete the posts.

Yeah, having to click Next Chapter or scroll waayyy down is kind of inconvenient. I'll probably do that when I finish.

Any suggestions for new tutorials, by the way?

Explore, my Scratch mod | Car Crash | My projects | (image by @MicroMacro)

liam48D

Please help! I did EXACTLY what you did for my New Category button, but when I try to open it, it says “key not found”:

Dictionary(Object)>>error:
Dictionary>>errorKeyNotFound
[] in ScratchFrameMorph class>>skinAt:
Dictionary>>at:ifAbsent:
ScratchFrameMorph class>>skinAt:ifAbsent:
ScratchFrameMorph class>>skinAt:
[] in ScratchViewerMorph>>rebuildCategorySelectors
Array(SequenceableCollection)>>collect:
ScratchViewerMorph>>rebuildCategorySelectors
ScratchFrameMorph>>createBasicPanes

Why? I worked hard on 4Mod, so hopefully you can fix this.

202e-202e-202e-202e-202e UNI-CODE~~~~~

liam48D

Oh wait, I fixed it. Turns out I forgot to put the “your category” gifs into the folder, and when I did, I forgot to run that workspace command.

202e-202e-202e-202e-202e UNI-CODE~~~~~

powerpoint56

^ Good. When I got that error once, it took forever for me to figure it out.

Explore, my Scratch mod | Car Crash | My projects | (image by @MicroMacro)

liam48D

powerpoint56 wrote:
^ Good. When I got that error once, it took forever for me to figure it out.

It's ok. But I have a question: I made a function in the Sensing category for the Sprite morph:

doubled: input
    ^ input * 2

But when I put the block spec in the sensing category for the Sprite morph, it didn't run right. It said, Error!

Why did it report an error? How can I fix it?

202e-202e-202e-202e-202e UNI-CODE~~~~~

powerpoint56

liam48D wrote:
powerpoint56 wrote:
^ Good. When I got that error once, it took forever for me to figure it out.
It's ok. But I have a question: I made a function in the Sensing category for the Sprite morph:
doubled: input
    ^ input * 2
But when I put the block spec in the sensing category for the Sprite morph, it didn't run right. It said, Error!

Why did it report an error? How can I fix it?

Weird… does your block spec look about like this? If it doesn't, that may be the reason.

('double %n' #r #doubled:)

Otherwise, there shouldn't be a problem.

Last edited by powerpoint56 (March 15, 2014 15:15:23)

Explore, my Scratch mod | Car Crash | My projects | (image by @MicroMacro)

liam48D

Wow, these tutorials are the best. They've been super handy! Are you going to make more?

202e-202e-202e-202e-202e UNI-CODE~~~~~

Discuss Scratch