Time Warp Studio

Educational Multi-Language Programming Environment with Integrated IDE, Debugger, and Turtle Graphics

Time Warp Studio is a unified desktop programming environment designed for educators and students. It brings together 24 programming languages spanning seven decades of computing history into a single, modern IDE. Built with Python and PySide6 (Qt6), it provides an integrated platform for learning programming concepts, exploring vector turtle graphics, and working through structured lessons.

---

Table of Contents

• Core Features
• Requirements
• Quick Start
• Installation
• Your First Program
• Example Code
• Documentation
• Project Structure
• Running the IDE
• Testing
• Contributing
• License

---

🎯 Core Features

Multi-Language Support

24 languages spanning seven decades of computing history:

Language	Paradigm	Era	Execution Mode
LISP/Scheme	Functional / Educational	1958	Whole-program
COBOL	Business / Procedural	1959	Whole-program
APL	Array / Symbolic	1966	Whole-program
BASIC	Imperative / Educational	1964	Line-by-line
Logo	Turtle Graphics / Educational	1967	Line-by-line
PILOT	Computer-Aided Instruction	1969	Line-by-line
Forth	Stack-based / Concatenative	1970	Line-by-line
Pascal	Structured / Educational	1970	Line-by-line
C	Systems / Procedural	1972	Line-by-line
Prolog	Logic / Declarative	1972	Line-by-line
6502 Assembly	Machine / Educational	1975	Whole-program
PostScript	Stack-based / Graphics	1982	Whole-program
Erlang	Concurrent / Functional	1986	Whole-program
HyperTalk	Event-driven / English	1987	Whole-program
REXX	Scripting / Procedural	1979	Whole-program
Smalltalk	Object-oriented / Message	1980	Whole-program
Tcl	Scripting / Embeddable	1988	Whole-program
Haskell	Purely Functional / Lazy	1990	Whole-program
Python	Multi-paradigm / Educational	1991	Whole-program
Lua	Scripting / Embedded	1993	Whole-program
Brainfuck	Esoteric / Turing	1993	Whole-program
JavaScript	Scripting / Web	1995	Whole-program
Ruby	Object-oriented / Scripting	1995	Whole-program
Perl 5	Scripting / Text processing	1987	Whole-program

Integrated IDE

• Code Editor — Syntax highlighting, line numbers, and auto-indentation per language
• Output Console — Program results, error messages, and interactive input
• Graphics Canvas — Real-time turtle graphics rendering with zoom and pan
• Theme System — 28 built-in themes (Dracula, Monokai, Catppuccin Mocha, Gruvbox Dark, VS Code Dark/Light, GitHub Dark/Light, Nord, Solarized, retro CRT, and more)
• Find & Replace — Advanced search with regex, case sensitivity, whole word matching, and live match highlighting
• Auto-Completion — Context-aware completions from language keywords and document identifiers
• Learning Hub & Project Explorer — Guided challenges, remix workflows, recent projects, and workspace browsing
• 16+ Feature Panels — Lessons, AI Assistant, Error Explainer, Turtle Inspector, Debugger, classroom tools, and more

Turtle Graphics & Vector Graphics

• Native turtle support with position, heading, and pen state tracking
• 50+ drawing commands across Logo, BASIC, Forth, and more
• Real-time rendering with Qt painter, zoom/pan controls
• SVGA mode — 800×600 (or custom) virtual canvas with crisp anti-aliased rendering
• Vector shapes — cubic Bezier curves, gradient-filled rectangles and ellipses
• Sprite system — define named pixel-art sprites, stamp and animate them with rotation and scaling
• Advanced pen styles — dash patterns, configurable cap and join styles, Z-ordering
• Cross-language graphics support (Logo, Turbo BASIC, Forth, Erlang)

Advanced Debugger

• Statement-level stepping with breakpoint support
• Timeline recording of program execution with state snapshots
• Variable inspector with real-time value tracking
• Rewind capability to navigate backwards through execution history

Educational Tools

• Lesson System — Step-by-step guided instruction with auto-verification
• AI Assistant — Intelligent code suggestions and explanations
• Error Explainer — Human-readable explanations of programming errors
• Examples Browser — example programs across all 24 languages
• Achievements — Gamified progress tracking

---

📋 Requirements

Requirement	Minimum	Recommended
Python	3.10	3.12+
PySide6	Any recent	Latest
Pillow	10.0.0	Latest
OS	Windows 10, macOS 10.14, Ubuntu 20.04	Any modern OS
RAM	4 GB	8 GB
CPU	SSSE3/SSE4 support	Any modern CPU

---

🚀 Quick Start

Linux / macOS

git clone https://github.com/James-HoneyBadger/Time_Warp_Studio.git
cd Time_Warp_Studio
python3 run.py

Windows (PowerShell)

git clone https://github.com/James-HoneyBadger/Time_Warp_Studio.git
cd Time_Warp_Studio
python3 run.py

The run.py launcher will automatically:

1. Check your Python version (3.10+ required)
2. Create a virtual environment if one doesn't exist
3. Install all dependencies
4. Launch the IDE

That's it — you should see the Time Warp Studio window in a few seconds.

---

🔧 Installation

Option 1: Smart Launcher (Recommended)

python3 run.py              # Auto-setup and launch
python3 run.py --fresh      # Force-recreate virtual environment
python3 run.py --skip-setup # Skip dependency checks (faster startup)
python3 run.py --no-venv    # Use system Python (not recommended)
python3 run.py --help       # Show all options

Option 2: Manual Setup

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate        # Linux/macOS
# .venv\Scripts\activate         # Windows

# Install dependencies
pip install -r Platforms/Python/requirements.txt

# Launch the IDE
python3 Platforms/Python/time_warp_ide.py

Option 3: Shell Script (Linux/macOS)

./run.sh

---

✏️ Your First Program

1. Open Time Warp Studio
2. Select BASIC from the language dropdown (top-right)
3. Type this in the editor:

PRINT "Hello, World!"
FOR I = 1 TO 5
  PRINT "Count: "; I
NEXT I

1. Press Ctrl+R (or click Run)

You'll see the output in the console panel below the editor.

---

📝 Example Code

BASIC — Turbo Graphics

SCREEN 1
COLOR 14, 1
LINE (10, 10)-(200, 100)
CIRCLE (150, 150), 50
PSET (300, 200)
PRINT "Graphics demo complete!"

Logo — Turtle Drawing

; Draw a colorful square
SETPENCOLOR "RED
REPEAT 4 [FORWARD 100 RIGHT 90]

; Draw a star
PENUP SETPOSITION 150 0 PENDOWN
SETPENCOLOR "BLUE
REPEAT 5 [FORWARD 80 RIGHT 144]

PILOT — Interactive Lesson

T: Welcome to the math quiz!
T: What is 2 + 2?
A: 4
TY: Correct! Well done!
TN: Not quite. The answer is 4.

Pascal — Structured Programming

program Hello;
var
  i: integer;
begin
  writeln('Hello from Pascal!');
  for i := 1 to 5 do
    writeln('Count: ', i);
end.

Prolog — Logic Programming

parent(tom, bob).
parent(bob, ann).
grandparent(X, Z) :- parent(X, Y), parent(Y, Z).
?- grandparent(tom, ann).

Forth — Stack Operations

: GREET ." Hello from Forth!" CR ;
GREET
5 3 + . CR

Browse more examples in the Examples/ directory or through File → Examples in the IDE.

---

📖 Documentation

Quick References

Document	Description
ARCHITECTURE.md	System design and technical details
INSTALLATION.md	Detailed installation instructions
CONTRIBUTING.md	How to contribute

Guides (in docs/guides/)

Guide	Description
Getting Started	First steps with the IDE
IDE Basics	Editor, menus, and panels
Lessons	Working through guided lessons
Turtle Graphics	Drawing with the turtle
Settings	Customizing the IDE
Keyboard Shortcuts	Complete shortcut reference
Troubleshooting	Fixing common problems

Language Tutorials (in docs/tutorials/)

Tutorial	Description
BASIC	BASIC programming with graphics
Logo	Turtle graphics programming
PILOT	Interactive lesson creation
C	C language basics
Pascal	Structured programming
Prolog	Logic programming
Lua	Lightweight scripting language
JavaScript	Scripting in the browser era
Forth	Stack-based programming
Brainfuck	Esoteric Turing-complete language
HyperTalk	Event-driven scripting
Erlang	Concurrent / functional programming

Reference

Document	Description
FAQ	Frequently asked questions
Documentation Index	Full documentation listing
Examples Catalog	Example programs catalog

---

🗂️ Project Structure

Time_Warp_Studio/
├── run.py                         # Smart launcher (auto-setup + launch)
├── run.sh                         # Shell wrapper for Linux/macOS
├── Makefile                       # Build automation targets
├── docker-compose.yml             # Multi-service orchestration
│
├── README.md                      # This file
├── ARCHITECTURE.md                # System design document
├── CHANGELOG.md                   # Version history and release notes
├── CONTRIBUTING.md                # Contributor guide
├── ROADMAP.md                     # Development roadmap (Q2–Q4 2026)
├── SECURITY.md                    # Vulnerability reporting policy
├── LICENSE                        # MIT License
│
├── Platforms/Python/              # Main application source
│   ├── time_warp_ide.py           # IDE entry point
│   ├── smoke_test.py              # Fast smoke test without pytest
│   └── time_warp/
│       ├── core/                  # Interpreter engine and services
│       │   ├── interpreter.py     # Central command dispatcher (~1,500 lines)
│       │   ├── debugger.py        # Step-through debugger with timeline
│       │   ├── sql_engine.py      # SQLite-backed T-SQL compatibility
│       │   ├── orchestrator.py    # System integration / component registry
│       │   └── config.py          # Canonical paths (~/.time_warp/)
│       ├── languages/             # 24 language executors
│       │   ├── base.py            # Executor protocol definition
│       │   ├── basic.py           # BASIC with Turbo graphics
│       │   ├── logo.py            # Logo turtle graphics
│       │   ├── pilot.py           # PILOT CAI system
│       │   ├── python.py          # Python sandboxed executor
│       │   └── ...                # 19 more language executors
│       ├── ui/                    # PySide6 (Qt6) UI components
│       │   ├── main_window.py     # Main IDE window (6 mixins)
│       │   ├── editor.py          # Code editor with syntax highlighting
│       │   ├── canvas.py          # Turtle graphics canvas
│       │   ├── themes.py          # 28-theme manager
│       │   ├── output.py          # Output panel + interpreter threads
│       │   ├── debug_panel.py     # Debugger controls/watch/call-stack
│       │   ├── command_palette.py # Ctrl+Shift+P command palette
│       │   ├── feature_panels.py  # 24 dynamic feature panels
│       │   └── mixins/            # Collaboration, classroom, debug, etc.
│       ├── graphics/              # Turtle state and rendering
│       │   └── turtle_state.py    # Position, heading, pen state (~600 lines)
│       ├── features/              # Lessons, autosave, achievements, games, etc.
│       ├── utils/                 # Expression evaluator, error hints, etc.
│       └── tests/                 # 41 test files
│
├── Examples/                      # 140 example programs across 24 languages
│   ├── CATALOG.md                 # Searchable example index
│   ├── basic/ logo/ pilot/ c/
│   ├── pascal/ prolog/ forth/
│   ├── javascript/ lua/ hypertalk/
│   ├── brainfuck/ erlang/ lisp/
│   ├── cobol/ tcl/ postscript/
│
├── tests/                         # Root-level integration tests
│   ├── test_all_demos.py          # Standalone demo verifier
│   └── test_basic_functionality.py # Quick smoke test
│
├── docs/                          # Documentation
│   ├── INDEX.md                   # Documentation hub
│   ├── guides/                    # 8 progressive how-to guides
│   └── tutorials/                 # 24 language-specific tutorials
│   └── reference/                 # FAQ and reference material
│
├── Scripts/                       # Build, launch, deploy, and utility scripts
├── docker/                        # Dockerfiles, nginx, supervisord, health checks
├── packaging/linux/               # Desktop shortcut and icon
└── .github/                       # CI/CD workflows (10) and templates

---

🏃 Running the IDE

Launch Commands

# Recommended: Smart launcher
python3 run.py

# Direct launch (requires venv activated)
python3 Platforms/Python/time_warp_ide.py

# Shell script (Linux/macOS)
./run.sh

What Happens on Startup

1. All 24 language executors are initialized
2. Configuration is loaded from ~/.time_warp/config.json
3. The main IDE window opens with editor, canvas, and output panels
4. Your last theme and settings are restored

Performance

Metric	Typical Value
Startup time	2–5 seconds
Memory usage	200–300 MB
Codebase	56,000+ lines across 130+ Python modules

---

🧪 Testing

Run from the repository root:

# Quick root-level test run
pytest -q

# Full package suite with integrated reporting
PYTHONPATH=Platforms/Python pytest Platforms/Python/time_warp/tests -q

# Fast smoke test without pytest
python3 Platforms/Python/smoke_test.py

Current status: Tests passing across test modules covering all 24 language executors, graphics, GUI, and interpreter tests.

---

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository

2. Clone your fork and create a feature branch:

   git checkout -b feature/my-improvement

3. Set up the development environment:

   python -m venv .venv
   source .venv/bin/activate
   pip install -r Platforms/Python/requirements.txt

4. Make your changes following PEP 8 style

5. Test that all tests pass:

   pytest -q
   python3 Platforms/Python/smoke_test.py

6. Commit with a clear message and submit a pull request

See CONTRIBUTING.md for detailed guidelines.

---

📄 License

Licensed under the MIT License.

---

🔗 Resources

• Repository: github.com/James-HoneyBadger/Time_Warp_Studio
• Maintainer: James Temple — james@honey-badger.org
• Version: 13.0.0

---

🙏 Acknowledgments

Time Warp Studio honors the educational legacy of BASIC, Logo, PILOT, Forth, Prolog, and other pioneering programming languages spanning six decades of computing history, while providing a modern IDE experience for today's learners. Special thanks to the open-source communities behind Python, PySide6/Qt, and the many educators who continue to champion accessible programming education.

---

Happy Programming! 🚀