pencilcode/jquery-turtle

Turtle Graphics for JQuery

How To Build and Test PencilCode

First install the prerequisites: git, nodejs, and grunt. Next, be sure you're in your home directory. Then:

git clone https://github.com/PencilCode/pencilcode.git
cd pencilcode
npm install
grunt
grunt devserver

On Windows Subsystem for Linux (WSL) only:

git clone https://github.com/cacticouncil/pencilcode.git
cd pencilcode
npm install --no-shrinkwrap
grunt
grunt devserver

Development can be done on Linux, Mac, or Windows. The prerequisites are a standard node.js development environment which is very widely used, plus grunt (you'll need to npm install -g grunt-cli).

Prerequisites

First, you need git, which is easy. On Linux, just sudo apt-get install git or sudo yum install git-core if you don't have it.

Second, you need node.js (which is the node and npm binaries) and grunt (which is the build tool popular in the node.js community). The Ubuntu and Debian packages for node.js are pretty old, so don't just apt-get install the packages. Get and build the latest node and npm and grunt binaries as follows:

(For Linux:)

mkdir -p /tmp/nodejs && cd /tmp/nodejs
wget -N http://nodejs.org/dist/v0.12.7/node-v0.12.7.tar.gz # http://nodejs.org/dist/node-latest.tar.gz
tar xzvf node-*.tar.gz && cd `ls -d node-v*`
./configure --prefix=$HOME/local
make install
echo 'export PATH=$HOME/local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g grunt-cli

Zsh users should change bashrc to zshrc in the above code.

(For Windows Subsystem for Linux:)

sudo apt-get install npm git
sudo update-alternatives --install /usr/bin/node node /usr/bin/nodejs 10
sudo npm install -g grunt-cli

(For Mac:)

mkdir -p /tmp/nodejs && cd /tmp/nodejs
curl http://nodejs.org/dist/v0.12.7/node-v0.12.7.tar.gz > node-latest.tar.gz
tar xzvf node-*.tar.gz && cd `ls -d node-v*`
./configure --prefix=$HOME/local
make install
echo 'export PATH=$HOME/local/bin:$PATH' >> ~/.profile
source ~/.profile
npm install -g grunt-cli

The above drops all the built binaries into ~/local/bin so you don't need root.

On the Mac, git comes from Apple (you can get it as part of the Command line tools for XCode), and if you'd rather not build it, node.js can be installed from http://nodejs.org/download/. You will still need to sudo npm install -g grunt-cli.

On Windows, git can be installed from here: http://git-scm.com/download/win and node.js can be installed from here: http://nodejs.org/download/. Windows development is untested, but if you try it, let me know.

Because node.js does not work on cygwin, when I work with node.js on a Windows box, I just run it with debian under a vbox instance https://www.virtualbox.org/.

How To Experiment with PencilCode

To experiment with PencilCode, you will want to run a local copy of the site's frontend. Your webpage may appear in plain (rather ugly) text unless you run devchrome with your grunt devserver.

To build and start the dev server (by default it runs on localhost:8008):

devchrome
bg %1
grunt
grunt devserver

(Use grunt sdevserver to run https instead of http.)

To use the devserver, modify DNS resolution so *.pencilcode.net.dev points to localhost. For example, with chrome on OSX, add a couple aliases to your .profile by running the following:

cat >> ~/.profile <<EOF
alias chrome="/Applications/Google\\ \\Chrome.app/Contents/MacOS/Google\\ \\Chrome"
alias devchrome='chrome --host-resolver-rules="MAP *pencilcode.net.dev localhost:8008" --user-data-dir=$HOME/devchrome --ignore-certificate-errors http://pencilcode.net.dev/'
EOF
source ~/.profile

And then "devchrome" will launch an instance of Chrome with the right proxy.

On Linux, add something like this to your .bashrc:

alias devchrome='google-chrome --host-resolver-rules="MAP *pencilcode.net.dev localhost:8008" --user-data-dir=$HOME/devchrome http://pencilcode.net.dev/'

On Windows:

You can set up command line options for the Canary Chrome shortcut, with the following options.

--host-resolver-rules="MAP *pencilcode.net.dev localhost:8008" --ignore-certificate-errors https://pencilcode.net.dev/"

When running devchrome, any URL with a hostname that ends with ".dev" will be routed to the development server. Visit https://pencilcode.net.dev/ to browse your local copy of the website.

PencilCode Internals

The structure of pencilcode is really simple.

• It is a single HTML file content/src/editor.html that does all the work. All pencilcode.net/edit/... URLs resolve to this static file.
• The javascript behind editor.html is in the src/ directory (symlink to content/src). These javascript files are combined and minified into content/src/editor.js by the build.
• The editor javascript does JSON requests to pencilcode.net/load/... and pencilcode.net/save/... to read and write actual data.
• There are a bunch of other static files that can be found in content.

JSON save and load

To get a sense for the protocol used by /load/ and /save/, just try hitting the URLs directly in your browser. For example, visit http://guide.pencilcode.net/load/ to see the JSON response for a directory listing. To see the details of how /load/ and /save/ work, see the code in site/wsgi.

The production site is an nginx server, configured in nginx/nginx_site.conf.

The devserver is simpler: it is a node.js proxy server. When using the devserver, the proxy.pac will direct the requests to your local dev server, and the dev server will produce editor.html (and its related javascript) for /edit/ urls. The devserver does not do any storage - it forwards /load/ and /save/ to the live website on pencilcode.net.

Editor view and storage and controller

The PencilCode editor is broken into three main pieces:

• editor-storage.js is the storage layer. It deals with the protocol for talking to /load/ and /save/ URLs, and it also does local caching, offline storage, and backup. Someday when we build a fully offline version of PencilCode, or when we adapt it to use Google Drive for storage, the major work will be in this file.
• editor-view.js is the UI for the development environement. It knows how to show directory listings, source code editors, and framed run sandboxes. Other UI affordances: login dialog box UI, a butter bar notification, and whizzy horizontal animated transitions. The idea is that the view doesn't do any thinking for itself: it just does rendering and surfaces events.
• editor-main.js is the controller logic. This is the main "business logic" for the editor and sets out what happens whenever something happens. It loads and saves things from the storage and pours the data into the view; and it responds to events that come from the view.

The view and the main logic are a bit large and probably should be refactored into further smaller pieces.

Roadmap

Improvements we'd like to make in PencilCode are in several basic directions:

1. Better Debugging. That ultimately means giving kids the ability to stop and step programs, and visualize their program state (their variables).
2. A Block Language. That means something like blockly, or maybe something new. The goal is to make it easy to use on the tablet while also making it easy for beginners to quickly build programs by multiple-choice.
3. Richer Libraries. The turtle is fun, but we want to point the way for students to do many other things: 3d, math, games, presentations, music, and so on.
4. A Learning Framework. Students should be given more guidance on which concepts to learn next. This could be in the form of automatic tips, better editor warning messages, exercises, or just better (e.g., more visual) navigation throught he site.
5. Community Tools. The site has grown to more than 1000 users pretty quickly. There should be ways to leave comments on on other peoples' sites. The UI for creating URLs to share your work should be easier. And it should be easier to do basic things like change your website name, or find your site once you have forgotten its name.
6. Better UI. Lots of little examples. Here is one: instead of navigating projects by name only, it should be possible to navigate them visually. After you run a project, we should capture a bitmap of the drawing and serve thumbnails.

We are always looking for more ideas too.

[email protected]

jquery-turtle's Issues

Easy way to prevent "freak-out turtle" appearance of movedraw?

The movedraw example (http://yendred.pencilcode.net/edit/movedraw) is one of the first bits of code that pencilcode shows students, and it has what looks like a glitch: in most cases, if one leaves the mouse in a single location, the turtle saunters over to the pointer, and then begins "freaking out": it moves .5 pixel past the pointer, then turns 180 degrees back toward the pointer, then .5 pixel past, etc.

This might be fixable by having "turnto" return false and do no turning if the location being turned toward is less than some distance away, allowing:

tick 100, ->
if turnto lastmousemove
then fd 1

Not a slam dunk in terms of added complexity vs added gain, but thought it might be worth a discussion.

Is there any kind of "reset()" or "clear()" function ?

For my use case I loading jquery and the jquery-turtle library one time and want to reused it for several movements.

$(q).home() works great to reset the position, but I don't found any function which remove the drafted lines / shapes or everything besides the turtle so that I could start with an clean screen without reloading the window or content.

Collect email address when creating username / pass

Allows for account recovery, tracking, emailing updates, etc.

Make clearer how to run in development

I've been away from any kind of JavaScript development long enough to leave me completely at a loss about how to use modern JS tooling. So, for example, while the instructions at https://github.com/PencilCode/pencilcode-site/blob/master/README.md are great at explaining how to build and test changes to the main IDE, I'm less sure how I might make and test my first change here.

David, if you can point me in a general direction, I'd be happy to write up what I find as breadcrumbs to those to come after.

Performance: speed up drawing.

Currently the animation of the turtle sprite is a bottleneck for performance: you can't go faster than a few hundred moves per second. That is because each time the turtle is moved and a new line segment is drawn, its current position is recomputed in a pretty slow way. (The 2d transforms are zeroed, then the untransformed position is read, then the 2d transforms are reapplied, and the math is done in parallel by hand to see exactly where the transform-origin of the turtle is on the screen.)

We should investigate ways to speed it up, e.g.,:

• Assume that the untransformed position doesn't change under certain conditions.
• And in those cases assume that we can just cache and read position data on the side instead of deriving it from the dom.

Should have built-in alternatives to the turtle.

Currently you can say "wear red" (or any color) to change the turtle shell, or "wear url" to wear an arbitrary image.

We should also support (and document) a few other built-in characters such as "hero"/"heroine", "mouse", "cat", "dog", "rocket", "car", "boat", "fish"; and maybe a few built-in abstract shapes such as "circle", "square", "triangle", "arrow".

A palette of built-in characters would be a more classroom-friendly alternative to Scratch's drawing program (which is where kids will spend all their time instead of programming), or going to the internet to look for image urls (which is another way for kids to spend all their time instead of learning to program).

If we allow color combinations with a dozen built-in shapes, that's plenty of room for personalization for kids in a classroom setting.

Consider to use musical.js as a dependency

I just saw that the code from musical.js is just copied into this repo https://github.com/PencilCode/jquery-turtle/blob/master/jquery-turtle.js#L3865

Why not use musical.js as a dependecy?
It can be already installed with npm via GitHub endpoint with this command:

npm i PencilCode/musical.js --save

Then just require('musical.js') or any other way, but this is the common way to do it.

Implement a network and storage API

Here is a proposed api:

Storage:
netsave 'filename', [options], text
netload 'filename', [options], (text) -> see text

Queuing: exactly one delivery to exactly one receiver. If there are multiple sends, they get queued up for a while (e.g., an hour). Each recv dequeues exactly one message from some sender.
netsend 'filename', [options], text
netrecv 'filename', [options], (text) -> see text

Chatting: broadcast delivery to all listeners, but only those who are listening at the moment.
netchat 'filename', [options], text
neton 'filename', [options], (text) -> see text
netoff 'filename', [callback]

save should be equivalent to $.post('/save/(parentdir)/filename', { data: text })
load should be equivalent to $.get('/load/(parentdir)/filename'...)
In other words, the storage APIs should allow you to load and save new files on pencilcode.net itself, including new programs.

The interesting thing here is implementing send/recv/chat/on. These should also bounce off of pencilcode.net - on the server, there should be a node.js websocket implementation of send/recv/chat/
netsend/recv/chat/

See http://stackoverflow.com/questions/16392260/which-websocket-library-to-use-with-node-js for alternative websocket libraries to consider.

Add conversion API from key code to meaningful values

For example, letters or macros that indicate non-letter keys.

Better instruments for audio API

There are some fantastic js libraries that will render "soundfonts" that have terrific instruments, such as

https://github.com/mudcube/MIDI.js

We should revamp the audio API to allow soundfonts to be loaded and played; and we should provide a default set of soundfonts.

correct hittesting based on the image shape of alternate sprites

jquery-turtle supports convex hull hit testing, but it only takes advantage of this for the default turtle shape. It should automatically compute the convex hull of an image loaded via the 'wear' command, and use it for "touches" and "enclosedby" tests. The fact that it does not do this has been noticed by high school students.

Doing correct hit testing requires three things:
(1) we need to inspect the image bits when an alternate image is loaded. Not too hard if we have access to the bits (via CORS). The moment to inspect an image is at finishSet, added in e072cd1
(2) when we don't have access to the bits (because it's offdomain without cross-origin sharing headers), we need make a proxy on pencilcode and bounce the request off, so we get access to the bits.
(3) finally we need to do the bit of computational geometry to make the convex hull and load it up. Before adding new code, see convexHull in the jquery-turtle code.

Piano bug(?)

When transposing a song to Pencilcode, I may have stumbled across a bug/glitch.

In the last second of the song, [g,, ^a,, d, g,]/4 is played as [_g,, ^a,, d, _g,]/4

Is this something I am doing wrong or a bug? Note that I was able to fix this earlier in the song by switching some sharps and flats, but that doesn't work now.

http://benabbott.pencilcode.net/edit/Strength_of_a_Thousand_Men

Design an API for 3-d turtle drawing.

3d drawing would be very cool and also awesome for math class.

APIs such as three.js are still too hard. Can we design a turtle-based API that makes it even easier?

I imagine:

• Switching to path-based drawing instead of canvas-based drawing, or providing for a mode that does it.
• Adding an "ut" for up-turn or "dt" for down-turn, or "rr" for right-roll or "lr' for left-roll.
• Making "fill" more approachable - you should be able to fill a planar polygon that you have already drawn.
• Adding a "camera turtle" of some sort so you can fly around the figure that you've drawn.

Design a function for "program this" puzzles

Should design a system to make puzzles for kids to solve. It might work something like this:

puzzle 'http://puzzles.turtlebits.net/somename'

Running the program would maybe show a picture and then give a prompt 'try to match the picture in N lines of code'. Modifying the program to add some lines of code like this

puzzle 'http://puzzles.turtlebits.net/somename'
pen red
fd 100
rt 90
fd 50

That might say "bravo" if you've matched the picture, or "nope, you're close" or "try again" or "can you do it with less code" etc if not.

Probably could be done by scanning the canvas to see if what's drawn approximately matches the target image.

Support for jQuery 3.x

Its seems that the current implementation of "JQUERY EVENT ENHANCEMENT" will not work for jQuery 3.x, not sure about the rest.

Would be great if you could make sure that jQuery 3.x will be fully supported.

Grid numbers

Allow numbers on the grids so people can know where to move the turtle in x,y rather than just relative movements

Differentiation between different audio standards

In this if statement a distinction is made between different audio standards, but the code in the branches are the same.

Figure out copyright assignment for contributions.

If we aggregate contributions from people other than David, we should probably figure out how to keep copyright assignment in a single entity (probably just David, unless somebody figures out how to make a foundation or something) so that years from now, it is possible to do things like offer the code under different licenses without having to chase down ancient contributors.

This should be done in a way that does not affect the openness of the licensing. The code is offered under MIT license.

Anybody with experience with this?

Every turtle function should have an optional "done" callback last argument.

Every turtle function should have an optional "done" callback last argument.

For example, "lt 90, -> write 'finished'" should wait until the left turn is finished before writing the message.

Here is why: when learning "await done defer()" with iced coffeescript, the question sometimes comes up, "why can't I wrap await and defer around any function?" By implementing callbacks uniformly around turtle methods that do queuing, the answer can be, "you can do that for any function that can queue an async process."

await lt 90, defer()

This would affect the signatures of a lot of methods: fd, bk, lt, rt, slide, movexy, moveto, jump, jumpto, turnto, home, pen, fill, dot, pause, st, ht, pu, pd, pe, pf, play, speed, wear, reload, twist, scale... However "read" methods that are synchronous such as getxy would not get the optional argument.

The change would look something like this:
https://github.com/PencilCode/jquery-turtle/compare/continuationstyle

Opinions?

Show shortcut keys on mouseover

Ctrl+Enter for run.

`turnto Turtle` is weird

The program

turnto Turtle

Causes a turtle to be created wearing an image of a house under a bridge.

Allow me to mix colors as percents of RGB

Kids learn to mix Reds, Greens, Blues together to make colors. Similar to hexidecimal and color names, allow me to mix percents of different colors together to make a new color.

Grid lines off

Allow a simple way to turn on and off the grid lines

investigate: modify iced parser so that"await done defer()" can be abbreviated as "await done".

The simple case of await, which is to await a single async call that calls back a zero-argument callback, should be simplified to just "await simplecall". In particular, this would allow turtlebits students to write "await done" which makes more sense than "await done defer()".

Should investigate whether the iced parser can be modified cleanly to accomplish this.

Better color API

Consider integrating chroma.js or something like it to have robust color support.

http://driven-by-data.net/about/chromajs

Error in Safari

In pencilcode, after the Run button is clicked, the following errors occur:

[Error] TypeError: 'undefined' is not a function (evaluating 'a.createPeriodicWave(e,f)')
    b (turtlebits.js, line 11)
    (anonymous function) (turtlebits.js, line 11)
    (anonymous function) (turtlebits.js, line 11)
    (anonymous function) (turtlebits.js, line 11)
[Error] ReferenceError: Can't find variable: pen
    anonymous (undefined, line 3)
    run (turtlebits.js, line 5)
    c (turtlebits.js, line 5)
    runScripts (turtlebits.js, line 5)
    close
    (anonymous function) (editor.js, line 1)
    dequeue (editor.js, line 1)
    (anonymous function) (editor.js, line 1)
    each (editor.js, line 1)
    each (editor.js, line 1)
    queue (editor.js, line 1)
    setPaneRunText (editor.js, line 1)
    (anonymous function) (editor.js, line 1)

Need API for audio capture.

We need APIs that help kids connect their software to the real world. One way is by using the computer (or phone)'s microphone: we need a simplified way for kids to collect audio, manipulate it, and replay it.

For example, what would it take to let a student write a 10-line program to record a snippet of audio, and then use the snippet as a sample to play music with the "play" function?

For an audio capture API discussion, see: http://www.html5rocks.com/en/tutorials/getusermedia/intro/

Play function only works in google chrome

So yeah that's pretty much it. I had the same experience testing on the example sites as on my own servers. The .play() function will only play notes if google chrome is used, also portions of the code that rely on this function completely don't work if other browsers are used. My website is mytunebook.net. click new tune and type characters into the textarea. In chrome it will make music, in other browsers nothing happens. Select a block of text, in chrome a "play selection" button pops up, in other browsers nothing happens, possibly because play selection uses the .play() function.

Add a an API for text-to-speech.

A request from kids: a way to do text-to-speech, i.e., a way to say 'hello, I am the turtle', and have the turtle speak it out.

Source line mapping for uncaught exceptions

A very common problem I see with programs on pencilcode is programs left with uncaught exceptions that aren't fixed.

This is probably due to the fact that kids can't understand where they are coming from.

The newly landed improvement in onError events in chrome should make it possible to fix.

https://code.google.com/p/chromium/issues/detail?id=147127

We should

• Unroll the stack from the uncaught exception.
• Map the lines back to the source using coffeescript's sourcemap.
• Highlight the line of source which caused the problem in the editor.

Need a build system

jquery-turtle.js is getting a little bit big and would probably benefit from a simple build.

Should probably:

• minify jquery-turtle.js
• concatenate versions of jquery, coffeescript, and see.js, and package as turtlebits.js.

see.js console prompt angle should not be copy-pastable.

Kids like to enter several commands in the console, then copy and paste them into the editor. Because the ">" symbols in the console are copyable, they end up getting pasted too, which makes the code non-working.

The console ">" symbols should be rendered some other way (e.g., as background images?) so that they are not copied and pasted.

Show number of programs (files) in each users directory when browsing by user

Allows you to know which users have created the most amount of programs that might be of interest.

Create quick link to reference card from PencilCode

Create a quicker link to the PencilCode reference card rather than having to search through the help link. Make the reference card a modal pop-in that is HTML and not a PDF.

Need unit tests

Enough complexity here that unit tests are needed.

• Should verify that each method does what it should.
• Should verify both "speed Infinity" and queueing behavior.

What is the right way to do unit tests of async code in this context?

Improve loadscript

We're going to start using loadscript in material. For example, an exercise about search algorithms will begin with this:

await loadscript '//csp.pencilcode.net/lib/find.coffee', defer()

A couple things should be fixed:
(1) Let's shorten this line by shortening the name of the function to 'script' from 'loadscript'.
(2) When the URL is incorrect, the error message shown is incomprehensible. There should be a good error message, and it should highlight the line of code that contains the call to load the script.