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 six 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 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 six decades of computing history:

Language	Paradigm	Era	Status
BASIC	Imperative / Educational	1964	Complete
Logo	Turtle Graphics / Educational	1967	Complete
PILOT	Computer-Aided Instruction	1969	Complete
C	Systems / Procedural	1972	Complete
Forth	Stack-based / Concatenative	1970	Complete
Pascal	Structured / Educational	1970	Complete
Prolog	Logic / Declarative	1972	Complete
SQL	Relational / Query	1974	Complete
Smalltalk	Object-Oriented	1980	Complete
APL	Array / Mathematical	1966	Complete
Assembly	Low-level / x86	1950s	Complete
Brainfuck	Esoteric / Turing	1993	Complete
CICS	Mainframe / Transaction	1969	Complete
COBOL	Business / Data	1959	Complete
Fortran	Scientific / Numeric	1957	Complete
Haskell	Functional / Typed	1990	Complete
HyperTalk	Event-driven / English	1987	Complete
JavaScript	Scripting / Web	1995	Complete
JCL	Job Control / Mainframe	1964	Complete
Lua	Scripting / Embedded	1993	Complete
Python	Multi-paradigm / Modern	1991	Complete
REXX	Scripting / Mainframe	1979	Complete
Scheme	Functional / Lisp	1975	Complete
SQR	Report / Database	1980s	Complete

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
• 14 Feature Panels — Lessons, AI Assistant, Error Explainer, Examples Browser, Turtle Inspector, Debugger, and more

Turtle Graphics

• Native turtle support with position, heading, and pen state tracking
• 50+ drawing commands across Logo and BASIC
• Real-time rendering with Qt painter, zoom/pan controls
• Cross-language graphics support (Logo and Turbo BASIC)

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 — 93 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
python run.py

Windows (PowerShell)

git clone https://github.com/James-HoneyBadger/Time_Warp_Studio.git
cd Time_Warp_Studio
python 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)

python run.py              # Auto-setup and launch
python run.py --fresh      # Force-recreate virtual environment
python run.py --skip-setup # Skip dependency checks (faster startup)
python run.py --no-venv    # Use system Python (not recommended)
python 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
python 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 93 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
Python	Modern scripting & sandboxed execution
Lua	Lightweight scripting language
JavaScript	Scripting in the browser era
Haskell	Pure functional programming
Scheme	Lisp-family functional programming
Smalltalk	Object-oriented programming
REXX	Mainframe scripting language
Forth	Stack-based programming
Brainfuck	Esoteric Turing-complete language
COBOL	Business data processing
Fortran	Scientific computing
Assembly	x86 low-level programming
APL	Array programming language
HyperTalk	Event-driven scripting
JCL	IBM Job Control Language
CICS	IBM Transaction processing
SQL	Relational database queries
SQR	Structured Query reporting

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
│   ├── test_runner.py             # Test orchestration with HTML reports
│   └── 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
│       │   └── ...                # 20 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  # 14 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 (1,700+ tests)
│
├── Examples/                      # 93 example programs across 24 languages
│   ├── CATALOG.md                 # Searchable example index
│   ├── basic/ (5)   logo/ (5)     pilot/ (3)    c/ (5)
│   ├── pascal/ (4)  prolog/ (4)   cobol/ (5)    sqr/ (4)
│   ├── fortran/ (3) haskell/ (3)  javascript/ (4) assembly/ (3)
│   ├── apl/ (3)     hypertalk/ (3) brainfuck/ (3) forth/ (3)
│   ├── lua/ (4)     rexx/ (3)    scheme/ (4)   smalltalk/ (3)
│   ├── python/ (5)  sql/ (4)     cics/ (4)     jcl/ (5)
│   └── demo/ (2)    # Cross-language showcases
│
├── extras/HB_Banking/             # Optional banking/ERP demo application
│   ├── main.py                    # CLI entry point
│   ├── gui_main.py                # PySide6 GUI
│   └── modules/                   # Accounts, transactions, reports
│
├── 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
python run.py

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

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

What Happens on Startup

1. All 24 language interpreters 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
python Platforms/Python/test_runner.py --comprehensive

# Basic smoke suite
python Platforms/Python/test_runner.py --basic

# Full package tests directly via pytest
PYTHONPATH=Platforms/Python pytest Platforms/Python/time_warp/tests -q

# Optional backend load/security suites (require backend services)
RUN_BACKEND_INTEGRATION=1 PYTHONPATH=Platforms/Python pytest Platforms/backend/tests -q

Current status: 1,700+ tests passing across 41 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
   python Platforms/Python/test_runner.py --basic

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: 9.0.0

---

🙏 Acknowledgments

Time Warp Studio honors the educational legacy of BASIC, Logo, PILOT, COBOL, Fortran, APL, 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! 🚀