Waifu-Lox: An Interpreter with a Visual Soul

A complete, dynamically-typed scripting language interpreter written in Python. Instead of printing to a boring terminal, the ultimate goal of this project is to visualize code execution and output through a real-time, animated 3D character.

About The Project

This project started as an implementation of a Lox-like interpreter, following the principles outlined in "Crafting Interpreters." The backend is a fully-featured tree-walk interpreter capable of handling complex scripts with modern language features.

The Unique Selling Proposition (USP) is the planned front-end: a visual application where an interactive avatar acts as the output medium. She will react to the code, speak the results of print statements, and show different emotions for successful execution versus runtime errors, creating a unique and engaging programming experience.

Core Interpreter Features

The backend interpreter is feature-complete and supports a wide range of programming paradigms.

• Full Arithmetic & Logic: +, -, *, /, !, and, or.
• Comparison Operators: ==, !=, <, >, <=, >=.
• Control Flow: if/else statements, while and for loops.
• Variables: Global and local variable support with var.
• Lexical Scoping: Proper block-level scope is handled by a static resolver.
• First-Class Functions:
  • Declare named functions with fun.
  • Functions are objects that can be passed as arguments.
  • Support for closures (functions that capture their enclosing environment).
  • Support for recursion.
• Data Types: Numbers, Strings, Booleans, and nil.
• Built-in Functions: A native clock() function is included.

Project Roadmap

The project is divided into two main phases:

1. ✅ Phase 1: The Interpreter "Brain" (Complete)

   • The core engine for parsing and executing code is finished and robust.

2. ▶️ Phase 2: The Animated "Body" (In Progress)

   • Develop the visual front-end application.
   • Implement the communication protocol (JSON over stdout) to link the interpreter to the front-end.
   • Design and implement the "Animation API" for character actions (speak, emote, think, etc.).
   • Integrate a real-time 3D model (e.g., a VTuber .vrm model) using a dedicated graphics library or game engine.

Usage

To run a script using the core interpreter:

python your_program.sh run path/to/your/script.lox

Example Script (factorial.lox)

This example demonstrates functions, recursion, and control flow.

fun factorial(n) {
  if (n <= 1) {
    return 1;
  }
 
  return n * factorial(n - 1);
}

print "The factorial of 5 is:";
print factorial(5); // Expected output: 120