Drawing commands.

Object transformation.

For each of these functions, the handle that is passed as a first argument can be replaced by an array of handles or by a name of an image. If a name is passed, the transformation will be applied to all objects with that name.

Expressions.

Built-in types.

String

PlaySkript Strings are similar to Javascript Strings. Strings constants can be created with either single quotes ('), double quotes (") or backtick (`). The backtick defines a raw string; it can span multiple lines and you do not need to escape backslashes and other special characters. Strings support many of the same methods supported by JavaScript Strings (see Javascript documentation ). However, playSkript does not yet support the JavaSkript /regexp/ regular expression syntax.

Strings can also be concatenated using the addition (+) operator.

Array

PlaySkript arrays are similar to Javascript Arrays, and they support all the methods supported by them. You can iterate over arrays using for loops. However, playskript also supports array arithmetic similar to python. For example, you can concatenate arrays by adding them together. You can also multiply an array by an integer to get a new array with multiple copies of the contents of the original array. Note that if the content of the array is itself an array, the array will be cloned, but other kinds of objects will be aliased. More specifically, if 'a' is an array of length n, t=a*m is an array of length n*m, where t[i] equals a[i mod n] if this value is not an array, and will equal a deep clone of a[i mod n] if the value is an array. The reason for having cloning semantics only for arrays is to make it easy to construct multi-dimensional arrays as illustrated below.

Dictionary

Dictionaries can be created using curly brace syntax similar to object initializers in JavaScript. Similar to JavaScript objects, elements in the dictionary can be accessed and updated either with dot '.' syntax or with bracket syntax '[]' as shown below: Accessing an object not present in a dictionary will yield a value of 'undefined'.

One big difference with JavaScript objects is that you can use the '+' operator to join two dictionaries. Joining two dictionaries produces a new dictionary with all the keys and values in the original two dictionaries. If the same key is present in both dictionaries, preference is given to the one on the right.

Math

You can use the constant Math to access the JavaScript Math object. You can use this object to call commonly used functions such as Math.abs() or Math.log(), as well as constants such as Math.PI.

Scene Control.

Getting Started

Your first PlaySkript program will usually start with a set of drawing commands. These commands can help you render diferent elements into the screen, including lines, curves, text as well as images from your library. A typical drawing command is the draw() commad. The details of this command can be found in the documentation, but at a high-level, the command takes as input the name of an image, and draws that image at a particular location. The command returns a handle that you can use to refer to this image and manipulate it with any of the Object transformation commands.

Handles

A handle does two things: it identifies a set of images in the screen and it relates them to a particular image in your library or to a particular shape descriptor in the case of shapes like lines, circles and curves. Object transformation commands can also be applied to groups of objects. In some cases, we may want to treat a uniform collection of objects as a single unit. You can do this by making them share the same handle. However, you want to be careful when you do this, because once two objects share the same handle, they can never be disentangled. You can also dynamically change the image associated with a handle. For example, the code above draws a dog using the image "bluedog1", but then replaces it with the image "bluedogTongue". The images are swapped back and forth after a few milliseconds five times, producing an animation effect. You can also use the define command to create aliases for image names.

Transforming objects

We have already seen some examples of transforming objects, whether by moving them, or by redefining the image to which they point to. Shapes such as circles and rectangles have a number of attributes that can be transformed with the update command. For example, in the code above, a new rectangle is created, and then its color is changed with the update command. The last parameter 30 tells the command that the transformation should occur gradually over 30 timesteps, rather than in one step. You can find more information about transformations here.

There are two transformations that are worth particular attention. One is the say transformation, which makes an object "say" something through a speech bubble.

The basic form of the speech bubble is very bare bones, but the addional parameters offer significant sope for customization.

Another transformation worth mentioning is the morph transformation, which is used to modify a curve. A curve is defined by a set of points relative to the reference point of the curve. The morph command replaces those points with a different set of points, gradually morphing from one set of points to the other.

Coordinates and Attachment Points

Given a handle, you can use it to get the coordinates of an already created object. You can do this by using the getX and getY functions. For example, the code below first draws a line and then draws a box with coordinates at the same point as the line origin. Additionally, shapes and text in PlaySkript have "attachment points", which correspond to points in the perimeter of the shape whose coordinates you can get. For example, circles have the following attachment points: 0 - center, 1 - noon, 2 - 1:30, 3- 3:00, 4 - 4:30 , 5 - 6:00, 6-7:30, 7 - 9:00, 8 - 10:30. Similarly, for a rectangle, the attachment points correspond to : 0 - center, 1 - middle of upper edge, 2 - upper right corner, 3- middle of right edge, 4 - lower right corner, 5 - middle of bottom edge, 6 - lower left corner, 7 - middle of left edge, 8 - upper left corner. The attachment points for text are analogous to those of rectangles, and the attachment points for lines are simply 0 - origin, 1 - end point. Additionally, both lines and circles support fractional attachment points. These are illustrated by the example below. In the code above, sh0 is a circle, sh1 is a line that starts in the middle of the upper left quadrant of the circle, where a clock would have the 10:30 mark, and ends in the lower right quadrant at 4:30. Finally, the last line starts three quarters of the way towards the end of the previous line and ends at 6 o'clock in the circle.

Sub-handles

The handles for lines and curves contain sub-handles that allow you to move individual parts of a shape. A line has sub-handles 'start' and 'end' that allow you to independently move the start or the end of a line. For example, the code above draws a line from (10,10) to (10, 20). The first moveTo command moves only the start of the line to a new position at coordinates (20,20). The second moveTo command moves only the end point of the line to the position where the start of the line used to be.

Curves also have sub-handles for every point in the curve which can be referenced with 'pt[index]'. So for example, the code below draws a curve with 3 points, and then independently moves the second point (pt[1]) down and then the first point (pt[0]) to the right.

Scenes and Scene navigation

A program in PlaySkript can be divided into scenes. Each scene starts with the marker
>> "scene_id" , where scene_id is an optional name for the scene. If your program has only one scene, you do not need the marker at the beginning of the scene.

Each scene can have any of the following: code to draw the scene, function definitions and event definitions. If a scene does not define any events, then it will automatically transition to the next scene, but if you do have event handlers, the transition will only happen after you issue a transition command:
next() Jump to the next scene.
prev() Jump to the previous scene.
scene(id) Jump to the scene with id id. The id can be either a number, or the string "scene_id" given as a name to the scene.

Each scene will start out empty, but you can populate a scene with all the elements from the previous scene by using the keep command.
keep() Restores the state from the previous scene in the program. This includes the state of the canvas, as well as all local variables. However, it does not include any handlers or timers. keep Should always be the first command in a scene. If the previous scene has not executed, for example because you jumped to the current scene using the scene command, there will be no state for keep to recover.

Events

PlaySkript supports the following events.
@click Run this code when the user clicks anywhere.
@click handle Run this code when the user clicks on the object with the given handle
@hover_in handle Run this code when the user hovers into the object with the given handle
@hover_out handle Run this code when the user hovers into the object with the given handle @when test Run this code when the test is true.
@timer t Run this code every t milliseconds.
@key keyname Run this code when the keyname key is pressed. Playskript currently only supports the following keys: left, right, up, down, space.

Event handlers can either occur at the end of a scene, or in a function. Having event handlers inside a function allows you to add them dynamically to dynamically created objects. For example, the code below draws a dog and then adds a handler to make it grow larger when it is clicked. However, now suppose we want to add multiple dogs, each with its own event handler. We can do this by creating the dogs in a function, and adding the event handler there. A few things to note about the code above. First, if you put event handlers in a function, they always go at the end of the function. They will have access to any variable defined in the function, and will execute after the function body, even if the function returns somewhere in the middle of its body. The event handler can access variables in the function scope even after the function returns. This can be used to maintain state specific to that object. For example, consider the code below. With that code, every dog will have access to the state variable for the function invocation that created it and will be able to use it to track whether it is small and should be grown or if it is already large and it should shrink. Also note the wait at the end of the handler. This is to control the speed with which the click will react if you leave the mouse button pressed. You can even add a timer inside a function to animate each of the drawn dogs. One important aspect of click events is occlusion: If two objects have event handlers associated with them and one is occluding the other, the event will be caught by whichever object is in front. However, if the occluding objecty (the one in front) does not have an event handler associated with it, then the event will be caught by the object behind, even if that object is not visible. For example, in the code above, the circle is hidden behind a large rectangle. Since the rectangle does not have an event handler of its own, however, clicking in the position of the circle will trigger the circle's event handler which will move the circle forward.

Another important aspect of click events is the notion of a bounding box. For efficiency reasons, the click events are actually caught by a bounding box around the shape. This means that, for example, a circle can catch a click event even if the click fell outside the circle, as long as the click is inside the bounding box around the circle. Another important aspect of bounding boxes is that they do not rotate when you change the angle of the shape. This means that, for example, if you draw a rotated rectangle, the bounding box will stay where it would have been if the rectangle had not been rotated (this is subject to change in future versions of the language).

Finally, it is very common to want to have event handlers that navigate to the previous or next scene when you press the left or right arrow keys respectively. PlaySkript has a function defaultHandlers() that automatically adds these handlers.

For example, in the code above, clicking the right arrow from any scene will navigate to the next scene, while clicking the left arrow will navigate to the previous one. The function also adds a default mouse click handler that navigates to the next scene.

Waiting

We have already seen the wait(n) command, which forces the script to wait for a fixed number of milliseconds before continuing with the animation. There are two other additional wait commands that wait for particular events: waitEvent and waitAndCheckpoint. waitEvent((key|handle) waits until a particular event has been issued before continuing with the execution of the program. In its simplest form, waitEvent() with no arguments simply waits for any event before continuing with the execution. For example, the code below will print "Step 1: first step", draw a circle and move it to the right and then stop and wait for an event. When the user clicks on the canvas or presses any arrow key, then execution will continue, writing the second message, drawing a second circle and moving it. An important aspect of waitEvent() is that it overrides any event handlers already active. For example, consider the program below. Each circle drawn in the loop has an event handler that turns the circle red when you click on it. However, when waiting on waitEvent, clicking on a circle will cause the function to stop waiting, but it will not cause the circle to change color since the click event will be handled by waitEvent instead of by the original handler.

The function waitEvent can also be made to listen selectively to only certain events. For example, consider the code below.

In this case, waitEvent is given a handle to an object, so the wait will only be released by clicks to that object. Clicking anywhere else, or pressing any key will not cause execution to continue, only clicking on the last circle. This means that clicking on the other circles will cause them to change color, since those events are no longer caught by waitEvent.

Alternatively, the code below waits for any click that isn't already handled by the existing handlers. So clicking on any of the circles causes them to change color, but clicking on the background behind them releases the wait from the loop.

As an example of an idiom that uses this feature, consider the code below. Each scene uses the default handlers to navigate to the previous or next scene using the arrow keys. In scene 2, there is a waitEvent on every iteration of the loop that waits for the right or the down events. This means that if you are waiting in this loop and you press the right or down keys, the code will draw the next circle, but if you press the back or up keys, then the default handlers will be invoked and you will navigate to the previous scene.

One shortcoming of waitEvent is that it helps you step forward but not back; in the example above, we saw that clicking back takes you to the previous scene, but what if you only want to go back to the previous step in the loop? For that, you can use waitAndCheckpoint. The waitAndCheckpoint() function is similar to waitEvent() with no parameters, but it also creates a checkpoint of the state of the animation at the point it is invoked. If you press the back or up keys, instead of moving forward, execution jumps back to the previous checkpoint. If there is no previous checkpoint, then the event is passed to the original event handler.

In the code above, scene 2 will write the text to the canvas and wait. Clicking on the screen or clicking the forward or down arrows will continue the execution to draw the first circle. Doing it again will draw the next circle and so on. Clicking back or up while the execution is waiting at a waitAndCheckpoint will jump to the previous one, but doing it while waiting on the first waitAndCheckpoint in the scene will just pass the event through, in this case to the default handler, which takes you back to the previous scene.

An important aspect of both waitEvent and waitAndCheckpoint is that they only override previous event handlers while the execution is waiting on them. That means if you have a long animation between them, pressing a key during that animation will simply invoke the previous handlers.

For example, in the code above, if you are on scene 2 and you click the left arrow when the code is waiting at the waitAndCheckpoint after drawing a circle and moving it, execution will revert to the previous checkpoint. However, if you click the left arrow while the circle is moving but before execution reaches the waitAndCheckpoint, then the left arrow press will be handled by the default handler and you will jump to the previous scene.

Arrays and dictionaries

If you have programmed with JavaScript in the past, some of the syntax in playSkript probably looks familiar. For example, the syntax for loops, conditionals and function definitions is directly borrowed from JavaScript. In PlaySkript you can also define arrays and dictionaries using familiar JavaSkript syntax. However, PlaySkript dictionaries also support some additional operations as illustrated by the example below. In an earlier example, you saw the use of the shape command, which takes as its last parameter a dictionary of arguments. The code below further illustrates how dictionaries can be used.

Drawing Arrays of pixels

Another interesting feature of PlaySkript is that you can treat a two dimensional array of colors as an image, and draw it using the draw() command. In constructing these arrays, the array arithmetic can be very useful. For example, the code below will generate a banded pattern of blue and yellow. Initially, the blue array has a single element with the color blue (you can also use string color names in place of rgb values). Multiplying times 10 creates an array with 10 copies of the color blue. Concatenating with an array of 10 yellows and multiplying by 10 creates an array of length 200 with alternating sequences of blue and yellow. The array [row] has a single such row, but multiplying by 100 creates an array with 100 rows of pixels which will be drawn as an image. Note that the multiplication operations clone the arrays (but not other kinds of objects inside the arrays), so it is possible to change the color in an individual row to create an image with a small red line in the middle. These computed images can also be used with the background command.

Functions and variable scoping

One big difference between PlaySkript and JavaScript is variable scoping. In particular, variables are never defined in PlaySkript.

All variables are local in scope, so for example in the code below, the x inside foo is a different variable from the x outside.

So the code will print "inner x=3" and "outer x = 1". Each scene also introduces its own fresh scope, so a value stored in x in one scene will not be available in the next scene. However, if a variable has not been initialized inside a function, it will have as its initial value the last value that it had outside the function before the function was called. So for example, the code above will print "inner1 x=1" "inner2 x=3", and "outer x=1", because when the first write executes, the variable x inside the function has not been initialized inside the function, so it takes as its initial value the value of x from the outer scope. This behavior is very useful for functions defined inside other functions, but it is not a good idea to rely on this behavior for functions defined in a scene, because such functions may be called by other projects that import this project.

There is, however, a global dictionary called "global", so if there is any data that you want to persist across multiple scopes, you cana store it there.

So for example, the code above will print "global.x=3" both times. The global dictionary persists even from one scene to the other.

In general, it is a bad idea to use globals, because they can create dependencies between scenes that then makes it difficult to reuse scenes across projects. If you are tempted to use globals to store constants that will be used in many places in your project, it is much better to use Styles.

Lambdas, Implicit Lambdas and Composition

PlaySkript supports anonymous functions (lambdas) similar to JavaScript. The notation (params)=>expression defines a function that takes as input the list of parameters given in params and returns the value of the expression. These anonymous functions are especially useful in combination with array methods such as map and filter. For example, consider the code below:

The code can be expressed much more succinctly using lambdas and map: In addition to these JavaScript-style lambdas, PlaySkript also supports the creation of Implicit lambdas. For any function, you can replace any parameter or set of parameters with '_' (underscore), and that has the effect of creating a lambda implicitly. So for example, given a function of two parameters f(x,y), you can write f(_, 7) and that is equivalent to writing (x)=>f(x,7). Or if you have a function g(x,y,z), you can write g(3,_,_) and that's equivalent to writing (x,y)=>g(3,x,y). Using this shorthand, you can write the example above even more succinctly as: PlaySkript also introduces a new composition operator x -> f such that x -> f is equivalent to f(x). The operator is left associative, so that x -> f -> g -> h is equivalent to ((x->f)->g)->h which in turn is equivalent to h(g(f(x))). Using this operator, it is possible to write code like the one below:

together and canvas

The together construct. Commands execute sequentially one after another, with a small delay in between them. This means that, for example, if you draw 10 circles in a row in a loop, you will see them appear one after another. Moreover, some commands such as move, update and turn can be made to execute over multiple timesteps. So for example, the code below will draw circles one at a time and then move them down one at a time:

The example above also illustrates the use of arrays to keep track of a set of handles, as well as the for( in ) loop to iterate over the indices in an array. In some cases, however, we may want many things to happen all at once. We can do this by using the together construct. The together block will execute sequentially, but all the actions in the block will be executed in tandem, so for example, in the code below, all the circles will appear together, and then they will all move down together in tandem. We can further simplify the code above by taking advantage of the fact that together also returns an array of all the handles for all the objects created within its scope, so there is no need to populate the lst array ourselves.

canvas(name, width, height){ body } . This construct creates a hidden canvas of a given width and height. Any commands inside the body will be drawn to this hidden canvas, rather than to the scene. So for example, the code below will draw a complex curve to a hidden canvas. The name of the canvas can later be used as an image name.

The code above will have no visible effect on the scene, but now we can draw a "spiral" as if it were any other image, for example, we can draw spirals of different sizes in a loop. Just like with other images, we can use the handles provided by the draw command to manipulate the spirals.

Scene Navigation Inside Canvas

You can invoke any of the scene navigation commands inside the canvas. The effect will be to clear the canvas and replace its content with the content of the invoked scene. For example, consider the program below. The code in the canvas first writes the text 'Will you see this?', but right after that, it calls the scene navigation function prev(). Just as when prev is called from the main body of the scene, the effect of prev is to clear the canvas and jump to the previous scene—in this case 'Scene1'— and never to jump back. So the result is a canvas that has a blue background and the text 'This is scene 1'. So at a high-level, the effect of navigating between scenes in the canvas is the same as outside the canvas, except everything is confined to the canvas. For a more complicated example, consider the code below. Now, 'Scene1' automatically jumps to the next scene, which is now 'Scene1.5', which uses keep() to keep the contents of 'Scene1'. Thus, the canvas in scene 2 will end up with the two messages from both 'Scene1' and 'Scene1.5'.

Screen Dimensions

The units for the coordinates in the screen are always going to be scaled so that the screen is exactly 50 units height. So if your window has an aspect ratio of 3:2, then your screen will be 75 units wide. You can use the screenWidth function to figure out how wide your screen is. For example, the code above writes the screen width to variable w, and then writes the text at exactly position w. Note that the centx:1.0 parameter means that the position will correspond to the rightmost edge of the text. This ensures that the text "Rightmost ->" will be flush with the right edge of the screen regardless of how wide your window is.

Now, for some applications, it is desirable to fix the screen width. For example, if you are creating slides for a presentation, you want to fix the width of the slides so they display the same way regardless of the window size. You can also use the screenWidth function to do this. If you pass a width to screenWidth, it will rescale the window to have that new width (remember, the height will always stay fixed to 50).

If you want the screen to go back to a flexible width that fills the entire screen, you can just call screenWidth(false).

screenWidth in canvas. A canvas in many ways behaves like a mini-screen whose initial width and height are given by the parameters passed when creating the canvas. For example, in the code below, screenWidth() will return 30, because that is the width of the canvas. When the canvas is drawn, the string will be flush with the right edge of the canvas.

It is also possible to rescale the canvas by calling screenWidth with a numerical parameter. Just like when you rescale the screen, the height of the canvas will remain unchanged after rescaling. For example, the code below rescales the canvas to have a screenWidth of 60. Because the original height of the canvas was 30, it will remain 30 after rescaling. Just like when you rescale the screen, the canvas will have two black areas at the top and at the bottom to make up for the fact that we are now forcing a 2:1 aspect ratio on a square canvas. Notice also the use of centx and centy to align the text at each of the four corners.

Importing from Published Projects

You can import from a published project by going to the import window You can follow the instructions in this window to import projects that you want to use from within your current project. Once a project is imported, you will assign it a name, which will be used in the code to access functionality from the project. For example, suppose you create a project with the following code. Now, if you publish the project, you can reuse this functionality from another project. For example. Suppose that you import this project with the name 'theother' into a new project that we will call 'Importer'. Now, you can use all the functionality from the original project in the Importer project. For example, you can invoke the 'fancy' function to write text into your new project. You can also reuse scenes from a project. For example, if you write the code below, your new project will have a scene called 'S1' that will have all the contents from the scene 'Scene1' in the imported project, in addition to a black circle. The call to 'theother.scene' even adds the event handlers from the scene in the imported project. So for example, if you click on the text, the text will change color from red to blue. Recall that in the imported project, Scene1 had an event handler that if you clicked on the scene, it would transfer you to the next scene. When you invoke a scene from the imported project, however, all scene navigation commands in the imported scene—next,prev and scene—will simply stop the execution of the imported scene, but will not transfer control unless you provide a scenemap. The reason for this is that a scene in the Importer project can only transfer control to another scene in the importer project, so if you want the scene navigation commands in the theother project to have an effect, you need to map scenes in that project to scenes in the Importer project. For example, in the code above, we call 'Scene1' from theother with a scenemap that tells playskript that if the code tries to navigate to the next scene from 'Scene1', it should actually navigate to scene 'S2' in the Importer project. Thus, scene 'S1' will display like 'Scene1' in the imported project, but clicking on the screen will take us to scene 'S2'.

As you may suspect, scenes that start with keep require some additional care, because they are design to run after the previous scene and to use the variables and scene elements defined in that previous scene. Thus, if you want to display such scenes, you need to pass this context to the scene function as shown below.

For example, consider the code above. In this case, after displaying the scene 'Scene2', the scene function returns a context which contains all the information that will be needed by 'Scene3' to execute properly. In the example, we store the context in a local variable and then use keep() to ensure it can be accessed from scene 'S2' which will render 'Scene3'. Also, recall that 'Scene3' in the imported project switched to 'Scene1' when the user clicked on the screen, so we map 'Scene1' to scene 'S1' so that when the user clicks, control will be transfered to scene 'S1'.

There are situations when we want to import a large set of scenes from a project. PlaySkript supports bulk import of scenes from another project with the syntax illustrated below.

The notation above performs a bulk import of scenes 0, 1 and 2 from project 'theother'. PlaySkript will automatically identify any scenes that use keep() and thread the state to ensure correct behavior. The first argument should be the name under which the project was imported, and the second and third argument must be integers representing the range of scenes to be included (the range is inclusive of its endpoints).

Styles

Every project in playskript allows you to define a set of styles that can be passed as attributes to the different drawing commands. To access the project's styles, you must first go to the project information window through the toolbar button , And then inside the project information, select the Styles interface. Each style has a name and a list of attributes and their values. For example, suppose I define a style as shown in the figure below:

The style has three attributes, a color, a border color, and a rounded corner radius. Because I have marked the check to make it 'default rectangle', then if I use the drag and drop functionality to draw a rectangle, the code will automatically use this style as its attributes. So for example, if I drag and drop a rectangle into the canvas at position 10, 10, I will get the following code. All the styles declared through the style window can be accessed through the global variable Style. So in this case, the generated code uses Style.rect. This style can be used anywhere in the project, just like any other dictionary, although it is an error to attempt to modify it from within the code.

Using styles has a number of advantages over directly defining attribute dictionaries within the code. First, they give you a centralized place to control the look of your project. By just changing your style definition in one place, you can globally change how different elements in your presentation are displayed. In principle, you could achieve this by storing the styles in the global dictionary, but this becomes problematic once you want to import scenes from one project into another, because you have to make sure the new project also initializes the styles in the global dictionary in the same way. With styles, you can even control which styles can be overriden by the importing project and which styles are fixed in the project. This is done by setting the 'Final' flag in the style window. If this flag is not set, a project that imports this project can override this style by simply defining a style with the same name. However, if the flag is set, the style will be fixed irrespective of what the importing project has defined.