Turtle-Logo, written by Assad Ebrahim (assadebrahim2000@gmail.com) Copyright (c) 2016-2020, Mathematical Science & Technologies, All Rights Reserved Comments, bug-reports, feature-requests to: assad.ebrahim@mathscitech.org License: GNU License - Users are permitted to re-use freely provided: 1/ All modified versions are also made freely available under the GNU License 2/ Attributions are preserved (lines 1-6 and Revision History) Download & Installation ====================== + Available for download from: http://www.mathscitech.org/articles/downloads + Run turtle-logo.exe from any location. + Install to: c:\totalcmd\ + Will create a subfolder: turtle-logo + ** Run _start_turtle_logo.bat to launch the program. ** + Instructions will be shown at startup. Key Features =========== + Draws directly to screen memory using assembly language set-char routine + Polling loop processes in real-time user submitted key presses to control the turtle and activate features + Evolved from 4-key (up,rotL,rotR,quit) to 11 key (see revision history) + Includes pen-up/pen-down/erase modes. Pen-up switches pen color to screen bg-color so that cursor can move with appearance of not drawing; pen-down restores the previous color. + Uses intelligence for visual usability, e.g. cursor background changes to provide sufficient contrast for all turtle colors + Allows macro capability through associating macro to function pointer. Has complete key processing engine. + Provides up to 9 independently recordable macros for playbacks + Allows PARTIAL nesting of macros (but not recursion) + Provides status bars with on-screen help. + Child Friendly - works same whether caps lock is on or not Stats ===== 2000 pixels (80 cols x 25 rows) using standard text mode graphics with 16 colors 20 commands + 9 macros screen-save snapshots is 4KB Code is 970 lines (v1.7.4052) Code size is 16K of code memory, 8k of list memory Code file is 61K including comments Developed in 4 months spread over 4 years (3 months in 2016, 1 month in 2018, 2 days in 2020) Version 0.1 was 300 lines of code, developed in 6 days, with 4 movement keys + quit 9 diaries for logging instructions, each capable of recording 500 keypresses 9 lookup tables, including key mapping 3 menus Revision History =============== v1.8.4054 - AE - FIXED: Paint fresh menus so loaded picture does not change menu system v1.8.4053 - AE - FEATURE: New menu layout with top and bottom menus :) re-grouped bottom menu controls - FIXED: Menu colors now show what turtle/paint and text/paint that will occur 2020-08-28---Fri---03:46 v1.7.4052 - AE - finished first pass streamlining - 972 lines of code! :) v1.7.4051 - AE - completed simplification of menu drawing system v1.7.4050 - AE - IN PROGRESS: introducing local variables for anything that needs repeated use of three parameters, one constant, and requires therefore stack juggling - STREAMLINED: write-char+, write-string, new-menu - still too complicated! STREAMLINED: simplifying the character emit portion of the code giving [poke-pixel] a wrapper that works with a local copy of fgbg to take all the noise out of the stack management with 3 params rationale: color is not changing with every pixel poke, but infrequently. rest of times just follow along. So best to take it from a memory cell local-fgbg - STREAMLINED: fill-screen used to have 8 instructions in loop. now it has 5 (fill-screen) - simplifying use of local-fgbg with get/set and pure-color words - STREAMLINED: line drawing - STREAMLINED: using pixel concept (num-pix-scr) to simplify drawing of screens (fill-screen) STREAMLINED: clarifying that local-fgbg is for repetitive paint jobs - fill-screen, border-painting, string writing, menu painting not for [paint-xy] turtle movements, as the two colors need to be managed independently... For this [poke-pixel] is fine. v1.7.4049 - AE - STREAMLINED: saveprompt promptbox unprompt - STREAMLINED: key pattern matching code used for small choice selection (e.g. yYnN) - STREAMLINED: renamed menus in appearance order v1.7.4048 - AE - FEATURE: added 'G' to show cartesian grid coordinates! and 'W' waves [RELEASE 28] - SIMPLIFIED: screen geometry explanation / variable naming - ADDED: example for creating dynamic strings on the fly and displaying them! :) CAN now play battleships --- calling off coordinates and then tracking the ship... including with the CLOAKING features 2020-08-16---Sun---11:20 v1.7.4047 - AE - starting the refactoring, streamlining, essential simplification full code review [RELEASE 27] - CHANGED: Silver is now Grey (children look for grey) - SIMPLIFIED: color-management, pen-modes - SIMPLIFIED: menu-management (TO DO) - SIMPLIFIED: use of create...does> into lookup tables (9 instances) vs. complex object (1 instance - new-menu) - FIXED: entering text mode preserves paint(bg)/text(fg) coloring \ v1.6.4046 - AE - FIXED: allowed clear screen without sending turtle home; [RELEASE 26] FIXED: buggy interation between load/undo/home/save that was leaving unintended pixels \ v1.6.4045 - AE - FEATURE: turtle-logo starts up with where it left off (quit screen is loaded) [RELEASE 25] \ v1.6.4044 - AE - FEATURE: # loads previously saved screen from file. [RELEASE 24] Next Round of Development started 2020-08-14---Fri---03:01 --- (Adam 5 yrs & 2 months, Jasmine 8yrs 9mo) Motivated by Adam wanting to do Turtle Logo and able to draw complex pictures and wants to save them and come back to them later. Needed to finish off the load file feature. ============================================================================ - Ideas for next round of development... geared to adding randomness, maze application, robotics, and save/load with files 2018-11-01 - End of Nov 2018 development push (Adam 3 yrs & 3 months, Jasmine 6yrs 9mo) \ v1.6.4043 - AE - stubbed out loading file (with # as load key) Nov 1, 2018 @ 2300h. \ v1.6.4042 - AE - final saved file Nov 1, 2018 @ 2300h. \ v1.6.4041 - AE - STREAMLINED code - penupdown, cloaking, text-processing --- move all key processing into process-key-loop. 2018-10-30--Tue--01:18 \ v1.6.4040 - AE - USABILITY: improved cloaking usability (preserves pencolor, pen state, etc.) 2018-10-27--Sat--05:24 \ v1.6.4039 - AE - FEATURE: added cloaking mode ('z') in cloaking mode when turtle is invisible and pen is up, can move stealthily leaving no trace. 2018-10-25--Thu--10:23 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? \ v1.6.4038 - AE - minor code streamlining and improvements, a few minor bug fixes \ v1.6.4037 - AE - USABILITY - inverted colors -- turtle draws based on the cursor color (background), and the foreground (symbol) is chosen to be consistent (Rationale - 3 year old children see the background color as the main color component, not the color of the thin symbol that is the turtle) - STREAMLINED code... 2018-10-22--Mon--20:07 \ v1.6.4036 - AE - FEATURE added save screen to file when [s] saving or [q] quitting (separate files) 2018-10-21--Sun--20:22 - STREAMLINED quitting code removing extra screen saves \ v1.6.4035 - AE - USABILITY (Jasmine): when in text mode, backspace should stay in text mode 2018-10-13--Sat--21:43 - AE - USABILITY - for large diaries, show diary commands one page at a time Motivation for next phase of feature additions is playing with Adam --- added cloaking mode to do "where is it" navigation! ================================================================== \ v1.5.4034 - AE - ** RELEASE TO WEB -- RELEASE CANDIDATE 5 ** [RELEASE 23] -- 2018-09-23--Sun--21:40 \ - AE - FIXED - BUG: when recording, if same skill is indicated, stack increases by 1 \ - AE - FIXED - USABILITY: when memory is full - print notification on the screen \ - AE - FIXED - USABILITY: when switching to text mode -indicate that on menu (highlight) \ - AE - FIXED - USABILITY: When in pen-up mode selecting text mode should put pen down \ - AE - FIXED - BUG: When in drawing mode, Text-mode-off should do nothing. \ - AE - FIXED - USABILITY: When in text mode should show cursor so clear what direction the text will be appearing \ v1.5.4033 - AE - FIXED: Extended diary memory to 500 bytes (from 100). - Streamlined startup and installation. - Fixed directory issues in vDosPlus *** RC4 [RELEASE 22] \ v1.5.4032 - AE - FIXED: clear screen clears all pixels including turtle's current pixel *** RC 3 [RELEASE 21] \ v1.5.4031 - AE - CHANGED: added third menu with additional instructions. *** RELEASE CANDIDATE 2 [RELEASE 20] (released to web) (Adam 3 yrs & 3 months, Jasmine 6yrs 9mo) \ v1.5.4030 - AE - CHANGED: moved both menus to the bottom of the screen. - AE - FEATURE: check diary for existence and prompt for overwrite before clobbering 2018-09-20--Thu--07:09 - AE - CHANGED: reduced diary size to 100 chars from 1000 chars (frugality prompts resourcefulness and needing to think about efficiency) \ v1.5.4029 - AE - FEATURE: diary records printable text (e.g. F/B). non-printable commands (arrow keys, backspace) are synonymns. \ v1.5.4028 - AE - FEATURE: '0' shows diary contents. **** RELEASE CANDIDATE 1 [RELEASE 19] (29 keys total, 21 keys if treat all 9 playbacks as 1 key) 2018-09-16--Sun--06:59 - AE - FIXED: pen up ESC (clear screen) leaves grey square in home position - shouldn't do that. \ v1.5.4027 - AE - Streamlined code (recording strings, menu, and diary update) 2018-09-15 \ v1.5.4026 - AE - FIXED: BUG: undo leaves cursor residue at last point and cursor remains at current point (cursor should be at last point as well...) needs a real undo function... - FIXED: BUG: need a separate pic memory for saved screenshots independent of drawing preservation \ v1.5.4025 - FEATURE - writing to screen. press [0] to flash Hello! where the turtle is for a few seconds and then restore screen - FEATURE - emit text to screen. press [ to emit text and ] to stop text mode. 2018-09-13--Thu--06:14 \ v1.5.4024 - AE - FEATURE: screen messages are now in a textbox prompt (textbox) \ v1.5.4023 - AE - FEATURE: set [s]ave and recover a restore point [u]ndo \ v1.5.4022 - AE 2018-09-09--Sun--14:15 - FEATURE: 1 see-diary (shows the diaries) - FEATURE: turtle-resume - FEATURE: able to see the macro playing on the screen as constructing the one being recorded - FEATURE: 16 levels of nesting are allowed in macros (but not recursion) - FIXED: ESC and Home are allowed while recording, but selecting them ends recording - FIXED: ESC properly clears screen including where cursor was - FIXED: Backspace does not take effect when pen-up \ v1.5.4021 - AE - FEATURE: can record macros and see them execute as well. \ v1.5.4020 - AE - Streamlined code (string management, fixed string data structures) - Streamlined code (drawing, menu production, menu dynamic updates) \ v1.5.4019 - AE - Usability: changed from Record/Recording to TeachSkill/Learning to help children understand better what it is they are doing - Fixed: Capital letters now work (i.e. caps lock on does not break command recognition) - child friendly - Usability: Penup mode has a distinct appearance matching in both cursor and menu - Fixed: Clean-screen does not work in pen-up mode - Fixed: Penup forgets previous color when going home \ FIXED - BUG: > pen-up > move to middle of screen > clear screen > home > should not leave a red dot \ FIXED - Usability: put Pen-Up in red so it calls attention, e.g. when Home is pressed and the behaviour is unexpected... Or maybe it is ok because if the pixel is colored then pressing pen up will preserve it? \ FIXED - Clear screen not clearing current cursor pixel \ FIXED - Clear screen sends turtle home \ FIXED - BUG: Colors get messed up when pressing home (i.e. Red > Penup > Home > Pendown >> not red!) \ FIXED - Usability: key should work even if caps lock is on... i.e. should detect both types of keys including capitals. \ FIXED - BUG: Home is not recorded (either it should be, or recording should flash if it is pressed) \ FIXED - Usability: Recording - when recursion is attempted, flash the warning \ FIXED - BUG: Clear screen should be prevented when recording, flash the warning \ v1.5.4018 - AE - Fixed: clear screen leaves turtle where it is. Should put turtle in home position. \ - Streamlined code (drawing section - IN PROGRESS) \ v1.5.4017 - AE - 2018-08-21--Tue--02:19 - Restarted development with vDosPlus instead of DOSbox, and working with Jasmine, now 6.5yrs - Modified for use with vDosPlus instead of DOSBox. - Usability: Edited instructions, added comments for developers. - Usability: simplified on screen menu instructions - Fixed: heading label jitter - Usability: Added diary to recording message, e.g. Recording #3 - Fixed: pen up/down does not change state when pressing [h]ome - Usability: Added splash screen at startup - Fixed: broken development environment Started second round of development 2018-08-21 with Jasmine 6 yrs and 5 months old. Motivation Jasmine could now read, write, spell, and do more with Turtle Logo including teach skills. She wanted to be able to write on the screen (into stories). Adam at 3 years old, could navigate the screen himself with key presses autonomously. ============================================================================ 2016-11-26 - End of (first) Nov 2016 development push (Jasmine was 4 yrs 11 months) \ v1.4.4015 - AE - **RELEASE 18 TO WEB, multi-macro record functionality \ v1.4.4006 - AE - Added multi-macro record functionality (up to 9 diaries). (24 keys -- D + 2-9) (~800 lines of code) (2016-11-17--Thu--06:34, took 5 hours to add) \ DONE: allow recording multiple macros (diaries). Cycle diaries using D -- later D prompts to enter the diary number. ============================================================================ \ v1.3.4002 - AE - **RELEASE 17, along with website article. Further streamlined code. Added turnkey executable. (2016-11-05--Sat--01:30) \ v1.2.3999 - AE - Fixed various bugs (delete, pen-up). Further streamlined code. ~750 lines of code. (2016-11-02--Wed--12:27) \ v1.2.3989 - AE - Replaced if/else key processing with vectored execution. \ v1.2.3979 - AE - Informed user how to restart turtle logo ============================================================================ \ v1.2.3977 - AE - **RELEASE 16 (splash) Introduction of macro language; streamlining test harnesses. Refactored code to simplify key-processing. (~800 lines) 2016-10-30--Sun--11:20 \ v1.1.3968 - AE - various bug fixes: home now lifts pen-up to protect home pixel \ v1.1.3967 - AE - optimized cursor pallete for color contrast & usability. cursor w/ different appearance when pen-up (white on silver) from white brush w/ pen-down (white on dark grey) \ v1.1.3966 - AE - Refactored design to use one key-processing loop. (~700 lines) ============================================================================ \ v1.1.3963 - AE - **RELEASE 15 (15-key) Added hide/show turtle (;) so can complete a drawing with showing turtle (~750 lines) 2016-10-20--Thu--21:22 ============================================================================ \ v1.0.3952 - AE - **RELEASE 14 to web - Added recording information into status bar. 2016-10-17--Mon--04:34 (~800 lines) \ v0.9.3946 - AE - Added real pen-up/pen-down (i.e. does not erase previous pixels). Changed back arrow to backspace (back arrow was confusing users). Restores picture after help screen. Added white border around picture area. 2016-10-08--Sat--21:24 \ v0.8.3940 - AE - Added menu and status bars with updating information (location, color, TODO: recording status) 2016-10-05--Wed--04:52 (+100 lines of code) 2016-10-06--Thu--07:54 ============================================================================ \ v0.7.3934 - AE - **RELEASE 13 to web - **stable** 25.Sep.2016 Sun 22:18 \ v0.7.3925 - AE - 14-key - Release 12. Added screenshot (Ctrl+F5) feature from DosBox. 2016-09-24--Sat--17:38 (first release to web) \ v0.7.3924 - AE - 13-key - Release 11. Added 'x' to cycle backward through colors. \ v0.7.3922 - AE - Release 10. Bug fixes (2 causes of crashes) \ v0.7.3919 - AE - Release 9. Packaged with DOS Box. 2016-09-22--Thu--23:45 \ v0.6.3918 - AE - Release 8. Added two-dimensional wrap-around. (~500 lines) \ v0.6.3916 - AE - 12-key - Release 7. Added 'r' recording toggle, save to numbered macro ('1' by default). Replay using key processing engine. Removed 'p'. \ v0.5.3907 - AE - Release 6. Revised processing engine to allow full macro key control; completed example macro feature - 2016-09-04--Sun--14:21 (~600 lines 2016-09-18--Sun--12:19) \ v0.4.3905 - AE - 11-key - Release 5. Added 'p' prototype play macro feature to control turtle programming - 2016-09-04--Sun--07:23 \ v0.3.3904 - AE - 10-key - Release 4. Added 'ESC' to clear screen; added cursor contrast; several bug fixes - 2016-09-04--Sun--06:10 \ v0.2.3898 - AE - 9-key - Added ? to show help screen - 11:31 \ v0.2.3897 - AE - 8-key - Added pen up/down toggle and back arrow as erase - 2016-09-03--Sat--10:28 \ v0.2.3895 - AE - 6-key - Release 3. Added 'h' home to find cursor 16:35 \ v0.1.3892 - AE - 5-key - added pen color change 'c' - 14:39 \ v0.1.3891 - AE - 4-key - Release 2. Removed back arrow (was confusing test users) - up,rotL,rotR,quit - 13:59 \ v0.1.3890 - AE - 5-key - Release 1. First working version - 4 arrow keys + quit - 2016-08-28--Sun--11:57 (~300 lines) \ v0.0.3883 - AE - began project on Aug 22, 2016 (2016-08-22--Mon--02:19) Major changes ============ Through v1.1.3965: The core of the program is the keystroke processing loop, which uses two if-else filters to match valid keystrokes to an event handler. First is key-process which processes keys that should not be recorded into any macro, i.e. clear-screen, show-help, toggle turtle visibility, turtle-home, as well as record-macro and play-macro. Second is turtle-process, which processes 4 recordable turtle commands: turtle-move, change-heading, change pen color, toggle pen-up/pen-down, and if macro-recording is active, also logs them to diary. Any key-presses not recognized by either filter are ignored and not retained in the macro log. During playback of a macro (triggered by key-process), turtle-process is called after each instruction is read. Key-processing was refactored in v1.1.3966 into a single processing word using Forth’s executable token (function pointer) concept. Turtle Logo Forth in the News ============================= [1] Article written on Turtle Logo in Forth: http://mathscitech.org/articles/turtle-logo-forth [2] Referenced on Y-combinator: https://news.ycombinator.com/item?id=13078063 [3] Referenced on Reddit.com: https://www.reddit.com/r/Forth/comments/5j34df/coding_for_preschoolers_a_turtle_logo_in_forth/ Related Software ================ Turtle Logo for Kids: https://archive.codeplex.com/?p=logo Turtle Graphics the Logo Way: http://wiki.tcl.tk/1097 Turtle Graphics on the Fignition: https://blogs.msdn.microsoft.com/ashleyf/2012/02/18/turtle-graphics-on-the-fignition/ Forth Factory Turtle Graphics: https://www.atarimagazines.com/v1n3/forthfactory.html hForth: A Small Portable ANS Forth: https://www.taygeta.com/hforth.html