Tutorial #2

-- Tutorial #2
-- This tutorial is focusing more on Parameters.
--By: CodeaNoob
-- Vocab for Tutorials:
-- CallBack Function: A function that checks to see if something is done, like a returned phone call, you want to see what they wanted.
-- Variable: is something that is Creator-Defined. Can represent anything you want.
-- Sprite: A image from your Camera Roll, or art from provided sprite packs.
-- integer: A number that can be positive or negative.

 
-- Use this function to perform your initial setup
function setup() -- The beginning of a specific "job" that Codea does. This one is setting up the game before the drawing happens.
    parameter.integer("SpriteWidth", 356, 500)-- The left # is the Minimum the spriteWidth can be, while the right # is the Max.
parameter.action("Clear Output", output.clear)--This parameter is a button. 
    -- the Red Letters between the ".." are the Variable(or whats on the button, while the blue is the callback function.
    parameter.watch("X")-- The simplist of parameters. They just watch the Variable the whole simulation/Game.
     parameter.color("TextColour", 10, 50, 232)-- This sets a color changing parameter that is user-Edited. See fill() in the draw() function for the rest.
    parameter.color("RectColour", 255, 50, 190)
    -- RectColour is a variable for the fill() of the Rectangle/Square.
    
   parameter.text("TitleText", "Tutorial #2", function(t) print(t) end )
 -- This isnt the only way to do it, but this way is what i prefer as it is simpler.
-- "print" is what prints the changes of the Text.
X = Gravity -- This shows Codea that the Variable X is a different name for Gravity.
end -- This ends the function


-- This function gets called once every frame
function draw()
    
    fill(TextColour)-- This is what changes the text colour.
    -- This sets a dark background color 
    background(40, 40, 50)-- Sets the background shade
    fontSize(40) -- how big the font is
    font("AmericanTypewriter-Bold")-- the style of font
    
    -- Draw text using the 'TitleText' parameter exposed
    --  in setup() above
    text(TitleText, WIDTH/2, HEIGHT - 100)
    -- This sets the line thickness
    strokeWidth(5) -- if you have circles, this sets the width of the stroke, in Pixels.
text(TitleText, WIDTH/2, HEIGHT - 100)
    -- Do your drawing here
    pushStyle()-- This saves the style being drawn at the time its called, and adds it to the top of the "pile" to save it
    -- Don't worry about them.
    spriteMode(CENTER) -- Sets the general area of the "spawn point" for the sprite
    sprite("Cargo Bot:Codea Icon", WIDTH/2, HEIGHT/2, SpriteWidth)-- this draws the Codea Icon
    popStyle()-- This returns things the way they were before pushStyle() was called and saves the changes made after pushStyle()
        fill(RectColour)
    rect(100, 100, 100, 100)
-- This draws a Square/Rectangle with the given width and height at the X and Y coordinates given.
end
  function touched(touch) -- A function that handles the touches on screen.
    if touch.tapCount == 1 and touch.state == ENDED then --this checks if you've tapped twice on the screen and if the last touch has ended, only then will it proceed to the purpose of the touches.
startRecording() -- Records the screen, A cool addition if you want to record the screen without the record button.
end
if isRecording() and touch.tapCount == 2 and touch.state == ENDED then
    stopRecording()
    end
    
-- "isRecording" checks to see if the startRecording() has started
end -- Two ends are needed because there are two things working in this function.
-- Thats it for Tutorial #2, If you have any questions or requests for the next tut, PM me at codeanoob@icloud.com
-- Later

I suggest telling the reader at the beginning what the tutorial will teach them, ie how to do X.

Also, it helps them to learn if you suggest they play with some of the settings so they get a better understanding of them, eg sprite x, y, or fill settings, or…

Actually, I would explain pushStyle and popStyle very early on, because it’s important to realise that sprites are just drawings and not objects, and that you have to prepare the canvas before you draw them.

I thought of a nice analogy for pushMatrix and popMatrix, which have a similar function. If you are drawing a little picture on a big sheet of paper, and you have to draw the same picture all over the sheet, sometimes sideways or upside down, what you do without thinking is move and rotate the paper so you can draw the picture the right way up, directly in front of you. That is what the settings transform, rotate etc do, which is to make it easy for the software to draw the sprite. Then you have to put the paper back the way it was before doing the next one.

A similar analogy for styles might be that before drawing a picture on paper, you have to pick up the right pencil/brush, and get your palette mixed correctly. And what you draw is just a picture, not an object. All of this is exactly how Codea works, and I wish I had understood that much sooner than I did.

So what I’m mainly suggesting is that explaining individual lines of code should come after people understand the bigger picture, otherwise it is just a maze of disconnected lines of code that don’t hang together. If people understand push/popStyle, they will naturally start using them, but if they are black magic, they will be confused and will use them badly.

Thank you for the feedback. But ive had feedback saying that pushStyle() and popStyle() is too confusing for early tuts. It will be in tut #3 which is focusing more on sprites and drawing. Thanks

But are you sure your just a beginner, ive seen the Codesplitter utility and it seems WAY to good for even me and ive been using Codea for a couple months.

May I suggest that you format it a bit differently. It’s quite hard to read the text when embedded as comments. Try splitting it up into segments with an explanation as to what each segment does (then include the full code at the end for ease of cutting and pasting).

As an example of what I’m suggesting, take a look at my tutorials: http://loopspace.mathforge.org/14/

@CodeaNoob I borrow all the best bits from elsewhere :smiley:

I am certainly a beginner with the graphics

Ignatz,

“Also, it helps them to learn if you suggest they play with some of the settings”

I hope that everybody feels this way naturally without being told.

CodeaNoob,

I know this is intended for absolute beginners, but you might take care of the wording of some explanations. Sometimes, a simplification may help beginners, sometimes confuse them.

Some suggestions:

a) Callback function


-- CallBack Function: A function that checks to see if something is done, like a returned phone call, you want to see what they wanted.

-- Callback function: A function you write yourself, you pass it to some other code
-- that doesn't give you a result right now but may work in the background for a while.
-- If this other code has a message for you at some point in time, it will call your
-- function to tell you something.

b) parameter.action


parameter.action("Clear Output", output.clear)--This parameter is a button. 
    -- the Red Letters between the ".." are the Variable(or whats on the button, while the blue is the callback function.

-- The first argument is the button's label string.
-- The second argument is the callback function, it will be called when the button
-- is tapped.

c) Assignment


X = Gravity -- This shows Codea that the Variable X is a different name for Gravity.

This is a tricky one for beginners.


X = Gravity
-- Gravity is a table, this means it is a reference type.
-- This further means that X doesn't simply hold some kind of snapshot of
-- Gravity's contents at the time of assignment but it points to Gravity.
-- If Gravity changes, X will reflect the change.

This alone could be a mini tutorial or a true “play around” suggestion to show the difference of integral values and reference values.

d) parameter.xyz

Maybe explain that every time you pass “a variable” into the parameter functions, you shall pass the name of the variable. The parameter function will look up the actual contents for you. And perhaps explain why it is done that way, this would make up a better tutorial than a one line description of the command being run.

e) Formatting

Even if you don’t follow Andrew’s suggestion and use his literate style, at least make use of proper indentation and insert some extra newlines to give the comments some structure.

Btw., here’s a nice up-to-date example of real literate programming à la Andrew:

http://coffeescript.org/#literate