Scratch

Here's what I have of my tutorial book so far:

Scratcher7_13 wrote:

How to Modify Scratch:
A Complete Guide on How to Make a Modification of Scratch to Fit Your Needs 
Getting Started

The first thing anyone who wants to make a Scratch mod (modification) should know is that it involves much more complicated programming than Scratch. Scratch is programmed in a language called Squeak!, so the most important thing that anyone who is modifying Scratch needs to know is a little bit of Squeak! Note that I said a little bit. This book will teach anything that needs to be known about Squeak! to make a modification. Not only will this book teach how to make a modification, but also in the process of learning this, you will make a modification called Sizzle.

How to install Scratch

If you already have downloaded the Scratch installer, you can skip to the first chapter. A quick note: This book teaches how to make a mod using Scratch, not the source code, though it can also be followed with the source code.
The scratch installer is on the companion CD, in the folder Installer. You can use this installer, or you can follow the directions below to get it from the Scratch website.
The first thing to do for installing Scratch is to go to http://scratch.mit.edu. At the home screen there is a link to download Scratch 1.4. Click the download link. This will lead to a form. You can fill in the information if you want to, but you can skip the form by scrolling down to the bottom of the page where it says skip to download. Click on the appropriate installer (Mac, Windows, or Linux).
Wait for the installer to download. Then, navigate to the installer and double click on it. Follow the download procedure, changing the download folder from Scratch to Sizzle.
Chapter 1: The Basics

After Scratch has been installed, open it. To edit it, you will have to access Debug mode. This is an easy procedure. First, hold down the shift key. Then, while still holding shift, click on the top loop of the ‘R’ on the Scratch logo in the top left corner. A menu will pop up. It will have three choices: ‘Turn fill screen off’, ‘Turn error catching on’, and ‘Save image for end user’. Click on ‘Turn fill screen off.’ A white area will appear on the bottom and right sides. This is debug mode. Memorize how to do this, as it will be used many times.
Click on the white space. A menu will pop up. This is called the World Menu. Click ‘appearance,’ then click on ‘set desktop color.’ Choose any color you want (I chose blue.) This is the very easiest thing to do when modifying Scratch. Now shift-click the ‘R’ again and choose to turn fill screen on. Then shift-click ‘R’ again and select ‘Save image for end user’. Sizzle will close. Open Sizzle again and open debug mode. The white area is now blue. Open the World Menu. Select ‘Open’, then select ‘Browser’. A window will pop up in the middle of the screen. Get to know this well, as most of the things we are doing will be in the Browser. Click on ‘Scratch-Objects’ then click “ScriptableScratchMorph”. At the bottom of the menus are two buttons that say, ‘instance’ and ‘class’. Click on ‘class,’ then select ‘block specs’. Finally, click on ‘obsoleteBlockSpecs.’ This is where the unused blocks are put. In the area below the menus, there is some complicated looking code, but it is simpler than it looks. These are block specs, which will be explained in more detail in the next chapter. The top line of code should look like this:
obsoleteBlockSpecs
^ #(‘obsolete number blocks’ (‘abs %n’ #r #abs #-) (‘sqrt %n’ #r #sqrt #-) ‘obsolete sound

Normally, you would need to get a piece of paper and a pencil ready, (unless you can remember this,) but it lists the code needed in this book. Delete the section in the code that says, (‘abs %n’ #r #abs #-). Then, on the menu, click on blockSpecs. This is where the block specs for the visible blocks are. Look at the area near the bottom of the window (do not scroll down!) Enter the ‘abs’ block spec between (‘join %s %s’ #r #concatenate:with: ‘hello’ ‘world’) and (‘letter %n of %s’  #r #letter:of: 1 ‘world’). (See figure 1.2) Right click, and click ‘Accept’. Type in your initials, and then exit the browser. Turn the fill screen on, then save the image. When Sizzle is opened again, go to operators. There will now be a new block near the bottom. This is the absolute value block. Congratulations! You have brought an obsolete block back!
The next easiest thing to do is to change the category colors. Open the Browser, then go to Scratch-Objects -> ScriptableScratchMorph (class) -> block specs -> blockColorFor: Then change the color values to:

Control: h: 0 s: 0.29 v: 0.24
Motion: h: 138 s: 0.88 v: 0.94
Motor: h: 155 s: 0.82 v: 0.97
Looks: h: 211 s: 0.675 v: 0.92
Pen: h: 39 s: 0.77 v: 0.63
Operators: h: 201 s: 0.77 v: 1
Sound: h: 222 s: 0.77 v: 0.855
Sensing: h: 114 s: 0.92 v: 0.88

The Variables and List blocks are harder to change, but we’ll get to that later in the book. Save the image. Now we’ll get to scripting your first block.
Open the Browser. Go to Scratch-Objects -> ScriptableScratchMorph (class) -> block specs -> blockSpecs. Look for the area that says, ‘operators’ (it may take awhile to find, but don’t give up. It’s right after the ‘control’ section.) In between two block specs, add the code, (‘%s’ #r #report: ‘’). This is the block spec for our new block. Next, stay in ScriptableScratchMorph, but go to instance -> other ops -> broadcast: Erase all of the code. (This will not change anything.) Type in the code:
Report: t1
    ^ t1

    Right click and accept the changes. Turn the fill screen on and save the image. When you open Sizzle again, and go to operators, there will be a new block. Drop this block into blocks that don’t normally except text, only numbers. The value for text is equal to zero, but not equivalent to zero. This means that if you subtract “hi!” from 56, the answer will be 56, but if you test if “hi!” equals 0, the answer will be false. This first block is useful for comparing text.
    The next block is the record sound block. Go to blockSpecs, then find the ‘sound’ section. Add this block spec:
    (‘record sound’ #- #soundRecord)
    Then go to the instance section of ScriptableScratchMorph, and go to sound ops. Go to the top script in the list and delete it. Then add this code:
soundRecord
    self recordSound
    Save the image. There will now be a new block in sounds that says, “record sound”. This block will bring up the sound recorder dialog box. Try playing around with the new blocks. If there are any problems, make sure the block specs command (i.e. #soundRecord or #Report:) matches the heading of the script.
Chapter 2: Block Specs and Simple Coding

This chapter will focus on how block specs work and teach some simple things about coding in Squeak! You have seen some block specs, so this section should not be too hard. This next section will explain the different parts of a block spec. We will use this block spec as an example: (‘join %s %s’ #r #concatenate:with: ‘hello’ ‘world’). This is the block spec for an existing block, the Join reporter block. The ‘join %s %s’ part is what is shown on the block. The %s is a string inserter. It makes a square on the block that allows text to be typed in to it. There are many other inputs, such as a color inserter and a numerical inserter. These will be discussed soon, but not right now. The #r is the block type. These are the different block types:
#- This is the normal code block.
#b This is a Boolean reporter block.
#r This is a normal reporter block.
#c This is a C block (an iterator.)
#t This is a timed block (like the wait () seconds block.)
#s This is a special form block.
#S This is the When Flag Clicked hat block.
#K This is the When [_] Key Pressed hat block.
#M This is the When Sprite [_] Clicked hat block.
#W This is the When <> Is true hat block.
The last block is obsolete, but it will be added to Sizzle soon. The last part of the block spec, the #concatenate:with: ‘hello’ ‘world’ is the block command. This tells the block to find the ‘concatenate: t1 with: t2’ command and execute the code. The ‘hello’ ‘world’ tells the block what to put into the string inserter as the default strings. There are many different types of inserters (as I said before,) so I won’t list them all here, but the most common ones are:
    %s A string inserter.
    %n A numerical inserter. (this only excepts numbers.)
    %C A color inserter (no palette showing.)
    %b A Boolean reporter inserter.
    %m A list of sprites.
Soon there will be another inserter and two types of blocks added. I won’t go into much detail about this yet, but we’ll get to it. Next are some simple coding things. First, each code has a heading, and this is how the program finds each section of code. A lot of code in Squeak is referencing other code. Sometimes it’s hard to tell which code are Squeak commands and which are referencing other code. Here are some basics that are good to know for programming blocks.
    ^ This is the caret symbol. It reports whatever is after it. This is used in all reporter blocks.
* This is the multiplicaion symbol.
    +This is the addition symbol.
    -This is the subtraction symbol.
    /This is the division symbol.
    raisedTo: This indicates exponentiation.
|var| This is how variables are declared. It is conventional to use t1, t2, etc. as variable names.
abs: This is the absolute value function.
sqrt: This is the square root function.
=,>,< These compare two expressions.
true This reports true.
false This reports false.
The next block that will be made is the exponentiation reporter. Go to block specs (you know the drill.) Find the reporter section and type this block spec: (‘%n ^ %n’ #r #n:toPower:) Then go to other ops and add this code:
n: t1 toPower: t2
    ^ t1 raisedTo: t2

Save the image. There is now a new block in operators (the exponentiation block). Now for your first test. Try to make true and false Boolean reporters using the skills taught in this book so far. They should go into the operators category. If you give up, you can look at the bottom of the page for solutions. If there are errors, you should make sure the block type is a Boolean reporter. Also make sure that the ‘t’ on true and the ‘f’ on false are lowercase.
    You have coded three types of blocks so far. The two shapes of blocks that you haven’t coded yet are a hat block and a C-block. These are much harder to code as C-blocks are always special form, and hat blocks need much more code than normal and do not have a particular form. In the next chapter, you will code a hat block, but you will code a C-block now.
    First, add this block spec:
(‘launch’ #c #doLaunchScript)

    Next, navigate to Scratch-Execution Engine -> ScratchProcess -> instance -> private-special forms, and add this code:
doLaunchScript
| t1 |
t1 _ stackFrame expression.
self popStackFrame.
self pushStackFrame: (ScratchStackFrame new expression: t1 firstBlockList)

This C-block runs the script within. It works like a broadcast, except without the extra lag. Save the image. The next block to be added will be the errorless divide block. Add this block spec:
(‘%n / %n errorless’ #r #divNoError:by: 10 0)

The code for this block should be this:

divNoError: t1 by: t2
    t2 = 0 ifTrue: [^ nil].
^ t1 / t2

Save the image (as usual). Next, try to make a block that will allow Boolean reporters to fit into strings. (A Boolean number reporter.) This is not as easy as it seems.
    Here are a few more blocks to add. From now on, I’ll only give the code and block type.
   
showDialogWithTitle: t1 withText: t2
    DialogBoxMorph inform: t2 title: t1

This shows a dialog with a specified title and specified text. It is a command block.

reportError
    ^ ‘Error!’

This block reports an error. It is (of course) a reporter.

setErrorFlag
    errorFlag _ true

This special command block creates an error. The code for this block goes in private-special forms. Soon we will work on some more complicated things. Here is one last block to add:

getTime: t1
t1 = 'date' ifTrue: [^ Date today].
t1 = 'short date' ifTrue: [^ Date today printFormat: #(1 2 3 $- 2 2 )].
t1 = 'time' ifTrue: [^ Time now].
t1 = 'seconds' ifTrue: [^ Time now seconds].
t1 = 'minutes' ifTrue: [^ Time now minutes].
t1 = 'hours' ifTrue: [^ Time now hours].
t1 = 'day' ifTrue: [^ Date today weekday].
t1 = 'help' ifTrue: [^ 'type date, short date, time, seconds, minutes, day, hours'].
^ 'Error!’

This block allows you to get the date or time. It is useful for making a clock in a project. Now let’s move on to more complicated things.
Chapter 3: Adding Some More Advanced Things

    Now that you know some simple coding things, C-blocks are not very hard. Here are two more C-blocks to add:

doBackwards
| t1 t2 |
t1 _ stackFrame expression.
t2 _ stackFrame arguments.
self popStackFrame.
self pushStackFrame: (ScratchStackFrame new expression: t1 firstBlockList reversed)

doScramble
| t1 t2 |
t1 _ stackFrame expression.
t2 _ stackFrame arguments.
self popStackFrame.
self pushStackFrame: (ScratchStackFrame new expression: t1 firstBlockList shuffled)

These blocks run the scripts within in reverse or a random order. Now, before we move on, take a few moments to customize how Sizzle looks. Alt-click different things and select the menu icon, ‘menu for me’. Then select ‘Change Color.’ Try changing the color of everything. Sizzle’s color theme is red, yellow, orange, and blue. Next, Copy the folder ScratchSkin1.4 from the companion CD. This folder contains the graphics for Scratch. You can edit the graphics as much as you want, as long as you don’t change the sizes (in pixels). Technically, it won’t destroy Sizzle if you increase their sizes, but it won’t look good.

The block specs for the true and false blocks are:
(‘true’ #b #isTrue) (‘false’ #b #isFalse)
The code is:
isTrue
    ^ true

isFalse
    ^ false

These blocks allow you to compare Boolean reporters. Save the image. Now try testing the new blocks that you have made so far.

The code for the block that will allow Boolean reporters to fit into strings is this:

booleanString: t1
    t1 = true ifTrue: [^ ‘true’].
    ^ ‘false’

This will not work if you forget the single quotation marks, because number reporters can only report numbers or strings. Also, if you get a ‘nothing more expected’ error, check that there is a period after the [^ ‘true’].