Documentation for Turtle Logo - by Assad Ebrahim - 2018-10-21--Sun--21:55 ========================================== -0. WHAT IS TURTLE LOGO Turtle Logo is a fun, lightweight, simple to use program, with features specifically designed to engage intellectually curious youngsters from ages 3/4 to 7/8 to 12/13 to 16/17. Ages 3/4 - control the turtle with keys, change colors, go home, clear screen, fill the screen with fun colors, simple shapes Ages 5/6 - artwork (scenes) with multiple components, load/save Ages 7/8 - train the turtle to perform repeatable operations, learning Forth Ages 8/9 - introducing cartesian geometry CAN now play a version of battleships --- calling off directions/grids, coordinates and then tracking the ship... including with the CLOAKING features Ages 12/13 - programming the turtle (paired with the remote control physical electronic turtle/car!) to solve problems, mazes, artificial intelligence, creating extensions with add-ons written in Forth. Ages 16/17 - getting under the hood and building a Forth based system, software and hardware ========================================== 0. HOW IT CAME ABOUT & DEV HISTORY Child appropriateness: Jasmine first started doing turtle logo as it was being developed in Aug 2016 (aged 4 yrs and 8 months). She was able to control the turtle, erase mistakes, change colors, control pen-up and pen-down and engage in the software development (finding bugs, pointing out features). Adam started doing turtle logo in Sep 2018 (aged 3yrs and 3 months). By October he is able to control turtle (fwd, turn left, turn right), erase mistakes (backspace), and chance colors (C). With some guidance he is able to do pen-up to move without making a mark, and then pen-down to resume drawing. Jasmine resumed turtle logo in Aug 2018 (aged 6 yrs and 8 months). By October, she is now able to create art work, including text. With some guidance she is able to teach turtle skills and combine and replay these to create reproducible small patterns. Adam resumed turtle logo in Aug 2020 (aged 5 yrs and 2 months). He was now able to create significant art work scene with help, but then wanted to stop and then pick up where he left off and continue. I did not have the load feature done, so picked it up again to develop this. Turtle Logo has been developed so far in 4 months of work over 4 years. In 2016, Aug - concept was developed in 6 days, 300 lines of code, VGA graphics capability, and 5 commands (4 directions and quit) From Sep-Nov, additional features were developed with Jasmine as the main user (4y8mo to 4y11mo). 700 lines of codes, c.29 commands, including a recordable macro system, 16 colors, etc. This was integrated into F-PC, packaged and released to the web. In 2018, Sep - it was pulled out when Jasmine was 6y8 mo and Adam got excited (aged 3y3mo). It was then developed over another month to add text (for Jasmine) and cloaking and other fun features for Adam In 2020, Aug - it was pulled out when Adam was 5y2mo and needed save/load feature to undertake more significant artwork (scenes with many pieces). Jasmine (8y8mo) then used it to explore algorithms. - took that opportunity to streamline the code and simplify - back down to 970 lines of code (v1.7.4052) =========================================== 00. OVERALL DESIGN 24 elements of the Turtle Logo design. Given it's c. 1000 LOC (lines of code), this is approx. 40 LOC per element. - interactivity: instructions, key-presses, interactive screens - configurability: can re-map/re-assign keys for multi-language customization - memory and file use - creating lookup tables with create ... does> - 9 lookup tables including key-mapping - creating parameterized objects (e.g. different colored buttons that do different things when pressed) with create ... does> - 3 menus + Color/Pen Management - 100 Lines of Code --- LITERATE PROGRAMMING COMPLETE (lines 114-211) - 2020-08-16---Sun---11:20 1/ list of 16 colors in the VGA video mode 2/ two types of color: paint color (background) / turtle/text color (foreground) 3/ user scrolls through color list forwards and backwards, choosing the paint color a/ menu shows the color name as user scrolls b/ once paint color is selected, algorithm chooses the optimal turtle color for contrast and to void confusion 4/ penup needs a distinct color which is handled separately as a 17th option 5/ finite state machine provides the memory and manages the logical transitions 6/ implementation uses lookup tables (create ... does>) for efficiency - displaying on screen: - producing the screen graphics with peek and poke pixel - paint with BLANK - textmode - screen geometry main screen layout: border, screen-wrap on all four edges, reserved menu area - menu system providing dynamic view of state and state changes - cool: easy way to create dynamic strings on the fly and display them! (see CARTESIAN) - producing the menus - finite state machine for multiple elements - taking screenshots - moving the turtle (8 direction vectors based on heading, and 2 movements: forward and backwards) - displaying the turtle - heading symbols - managing pixels - paint, erase, and cache/restore pixels - special turtle movements - going home - changing color - switching display modes - preserving screen for altering display - teaching, learning and diaries - key-logging and key-recording - nested diaries - diary stack - key mapping and key-processing engine - all commands - position markers (set-xy, restore-xy) - playback of macros - initialization, running (cold start and warm start -- turtle-resume) - behaviour on quit 1. TURTLE-LOGO There are two entry points for Turtle Logo: TURTLE-GO Shows help screen (SHOW-HELP), then initializes settings (TURTLE-INIT), then starts the key processing loop (PROCESS-KEY-LOOP). TURTLE-RESUME Restores screen, then starts the processing loop Exit happens when user presses Q (quit), which exits the key processing loop in TURTLE-RUN and drops into TURTLE-QUIT ======================== 2. SCREEN GEOMETRY, PICTURE MEMORY and SAVED.SCREEN and QUIT.SCREEN formats: 80x25 colxrows = 2000 pixels = num-pix-scr Example: 1000 $20 $77 poke-pixel linear position: 0-3998 (4000 positions, 2000 pixels, but only every other one leads to a displayed pixel) character: $20 (space) color foreground/background: $77 Graphics - switch to matrix convention for simplicity m rows indexed by y (i) n columns indexed by x (j) So, it's a 25x80 matrix (25 rows, 80 columns) so the linear location of cell a_ij is 2 * (di*n + dj) (display coordinates to physical linear coords) and user coordinates are just offset vs. display di = ui+1 dj = uj+1 The coding is then quite Forthian --- ( x y -- ) is just ( j i -- ) and it is matrix notation processed in a Forth stack way, with i (y) at top of stack In matrix notation, this is just row-major notation instead of column major, i.e. the array proceeds along the row PICTURE MEMORY = 4000 bytes = num-pix-scr x 2 (char + fgbg) SCREENSHOTTING Two picture arrays are used, system-picture and user-picture for saving/restoring of the picture by the system and explicitly by the user. The picture is always taken WITHOUT the turtle, i.e. with the turtle temporarily hidden and then restored. TEXT MODE The color in text mode matches the BACKGROUND The foreground (text color itself) is selected for contrast, so will often not be what you expect. If you choose the color to match the foreground, then the background will be odd ========================= 3. TURTLE POSITIONING STARTUP-TURTLE sets up turtle heading (0=N) and turtle position ex: (0,19) For each position the turtle is in, the pixel is cached (CACHE-PIXEL) move-fwd move-back Position is kept on the stack... complicating the process But there is a coordinate variable: xy-coord ========================= 4. INSTRUCTING THE TURTLE PROCESS-KEY-LOOP Application loop. This reads a user keystroke (KEY), checks if it is a quit request (IS-QUIT?), and if not runs it through the key filter (TURTLE-DO) that triggers an action, or ignores a non-recognized key. The loop is a bit more complex as, if the instruction switches to text mode then a further text-processing loop is activated that prints to the screen (PROCESS-TEXT-LOOP) PROCESS-TEXT-LOOP TURTLE-QUIT If quitting keys (QUIT-KEY, QUIT-KEY2) are pressed (IS-QUIT?), then user is asked to confirm (CONFIRM-QUIT?) and a screen-capture is made (SAVE-POINT). If the user confirms the quit request, the program tidies up (TURTLE-QUIT) --- recording is stopped (STOP-RECORDING) and final screen-capture is written (QUIT-MEM2FILE) to disk file (.quit-screen) --- before quitting, with instructions on how to exit (EXIT) or restart (TURTLE.EXE). TURTLE-RESUME When in development mode, it is possible to resume (TURTLE-RESUME) after quitting, which restores the final screen-capture (PIC-MEM2SCR), turtle position, and restarts the key processing loop (PROCESS-KEY-LOOP). ============================== 5. INITIALIZING THE SYSTEM TURTLE-INIT - Maps keys to actions (MAP-KEY-COMMANDS) in key filter (KEYMAP). - Clears all 9 skills (CLEAR-DIARIES) and resets their starting and ending positions - Sets video to text mode (2000 character screen arranged in 80 columns x 25 rows x 16 colors) - Sets pen-color to red, borders to silver, screen to white, and paints-screen including menus - Initializes state variables and refreshes menus with the dynamic information - Saves key information for undo processes - Shows the turtle, we're ready to go! MAP-KEY-COMMANDS All keys by default are mapped to the ignore-me action. For valid actions, the executable token for the action is stored in the ascii position of the corresponding key. This allows for multiple keys to trigger the same action (synonymns, upper/lower case, canonical and alternative codings, different languages, etc). Note - this requires 256 entries since non-display characters are part of the key presses (e.g. arrow keys have ascii characters in the special section above 128d) As of v1.6, there are 18 distinct commands recognized by turtle logo (counting all playback as one type of command). TURTLE-DO-KEY Processes the user keyed instructions. After each keypress, refreshes menu (MENU-REFRESH) to update dynamic content (heading, color, recording, text mode, or cloaking), and resets turtle's visibility (VISIBILITY-RESET). =============================== 6. DRAWING MODES DRAWING Turtle draws when in PENDOWN mode and advances one PIXEL. You can see this by toggling its SHOWHIDE state -- the pixel it is standing on is not colored yet. For little children (boys especially), this can be explained by turtle leaving pooey marks as he goes. The paint is the poo... (maybe not the right message) PENUPDOWN (PENMODE changes) There are two penmodes managed through state variable PENUP-STATE: PENUP allows moving with no marks; PENDOWN is the default mode moving with marks / delete. PENUPDOWN toggles turtle between the two pen up/down modes, triggered by user pressing PENUPDOWN-KEY ( ' spoken tick). State changes are managed through state check word IS-PENUP? and change words DO-PENUP, DO-PENDOWN, PENUP-RESET and PENUP-TOGGLE Penmode changes are logged when recording is on. In penup mode turtle has a unique appearance (SWITCHTO-PENUP-COLOR) and the menu shows color as PENUP. Pen-color persists between penup and pendown modes due to SAVE-/RESTORE-PREV-PEN-COLOR (with extra PREV-PEN-COLOR state). Penmode persists through showhide, going home, clear-screen, help-screen, quit/turtle-resume, and cloaking on/off (due to SAVE-/RESTORE-PREV-PENUP-STATE, with extra PREV-PENUP-STATE variable). Forced pen-down occurs when exiting text mode or changing color (and this overrules cloaking). Pen-up happens, in addition to when user selects it, when cloaking is enabled (to hide turtle), and when going home (to avoid mark where turtle was). TURTLE-SHOWHIDE TURTLE-HIDE Turtle-hide persists through PENMODE changes. Program hides turtle automatically (without user involvement) in the following cases: - before SAVE-POINT or MEM2FILE takes screenshots, so that the screenshot does not have turtle in it, then TURTLE-RESTORE is called. - as part of go-home, turtle is hidden from previous location before being transported to home location - as part of quitting, so turtle is not visible after program has quit Any of the following will cause turtle to become visible: lowering pen CLOAKING-ONOFF cloaking mode 'z' In cloaking mode when turtle is invisible and pen is up, can move stealthily leaving no trace. Challenge: can you navigate without bumping into things? Can you drive without seeing? Can you steer turtle in the darkness trusting only your situational awareness? SAVE/UNDO save-point and restore-point save/undo the current screen to/from memory. Save-point additionally writes the screen to file. Bug state: Hide then penmode change MOVING TURTLE - 50 lines of code 490-560 (70 LOC) key concept is movement is in two dimensions, forward or backward, with the specific motion depending on the current heading heading is changed in two dimensions, CW and CCW DRAWING painting or erasing DISPLAYING TURTLE key concept is heading indicator, which are 8 symbols. Unfortunately, the diagonals are indistinguishable from each other. DIARY FUNCTION (TEACHING/LEARNING/REPLAYING SKILLS) = 135 lines of code 562-627 = 70loc 710-713 - menu system update = 4 loc 737-800 - logging and viewing = 60 loc Concatenation of skills is allowed. Self-reference, recursion are not SEE-DIARIES key concept: diary - memory block, page - recording pad within the diary We have sentinel characters that serve as overflow protection for each diary preventing from overrunning them. We have a diary stack concept to allow nesting diary instructions Diary has recording mode on/off certain commands (keys) can be logged/actions recorded, others not =====