AuroraScript 1.0.0

<p align="center"> <img src="icon.png" width="128" alt="AuroraScript Logo" /> </p>

<p align="center"> <a href="./README_CN.md">简体中文</a> | <a href="./README.md">English</a> </p>

AuroraScript

AuroraScript is a lightweight, weak-typed script execution engine built on .NET. It compiles scripts into bytecode and executes them on a custom Virtual Machine (VM), designed to be fast, embeddable, and easy to use.

While inspired by JavaScript syntax and mechanisms, AuroraScript is a distinct language with its own optimizations and features, and does not adhere to ECMA specifications. It supports native .NET integration and debugging.

✨ Features

• Lightweight & Fast: No third-party dependencies. Bytecode compilation and optimized VM execution.
• Weak Typed: Flexible variable typing similar to JavaScript.
• Native Interop: Seamlessly register and use .NET (CLR) types and functions within scripts.
• Debugging Support: Full VS Code debugger support (Breakpoints, stepping, variable inspection, call stack).
• Module System:
  • import xxx from 'xxx': Import module exports.
  • include 'xxx.as': Embed script files directly.
  • @module("NAME"): Define module name.
• Advanced Control Flow:
  • yield: Interrupt execution.
  • Interruption & Continue: Pause and resume script execution from external host.
  • debugger: Programmatic breakpoint.
  • where / for loop enhancements.
• Modern Syntax:
  • Closures, Lambdas, and Function Pointers.
  • Destructuring assignment: var { a, b } = obj; and var [ a, ...b ] = arr;.
  • Spread operator: ... for arrays and objects.
  • Template literals: Multi-line strings with ` or |> syntax.
• Standard Library: Built-in support for Math, JSON, Date, Regex, and StringBuffer.

🚀 Getting Started

Installation via NuGet

You can easily install the AuroraScript engine via NuGet:

dotnet add package AuroraScript

Manual Installation

Clone the repository:

git clone https://github.com/l2060/AuroraScript.git
cd AuroraScript

Compiling the Project

To build the core engine library:

dotnet build src/AuroraScript.csproj -c Release

📖 Usage

Running a Script (Host Application)

You can host the engine in your own .NET application.

using AuroraScript;
using AuroraScript.Runtime;

// 1. Initialize Engine
var options = EngineOptions.Default.WithBaseDirectory("./scripts/");
var engine = new AuroraEngine(options);

// 2. Register CLR Types/Functions
engine.RegisterClrType(typeof(Math), "Math2");

// 3. Compile Scripts
await engine.BuildAsync();

// 4. Create Domain & Execute
var domain = engine.CreateDomain();
// Execute 'main' function in 'MAIN' module
domain.Execute("MAIN", "main");

Writing Scripts

AuroraScript uses a syntax familiar to JavaScript developers:

@module("MAIN");

func main() {
    console.log("Hello, AuroraScript!");
    
    // Using imported CLR library
    var res = Math2.Abs(-100);
    console.log("Abs result: " + res);

    var list = [1, 2, 3, 4, 5];
    for (var item in list) {
        if (item % 2 == 0) {
            console.log("Even number: " + item);
        }
    }
}

🐞 Debugging Scripts

AuroraScript provides a full-featured VS Code debugger.

1. Setup Extension

1. Open Extension Folder: Open vscode-extension in VS Code.
2. Install Dependencies: npm install
3. Package: npm run package → Generates a .vsix file.
4. Install: Install the .vsix file via VS Code Extensions menu.

2. Configure Wrapper

Create .vscode/launch.json in your script project:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "AuroraScript",
            "request": "attach",
            "name": "Attach to AuroraScript",
            "host": "localhost",
            "port": 4711
        }
    ]
}

3. Start Debugging

1. Enable debugger in your C# host:

   engine.EnableDebugger();
   await engine.WaitAnyDebugger(TimeSpan.FromSeconds(60));
   

2. Run host.
3. Press F5 in VS Code.

Features

• Breakpoints: Set breakpoints in .as files.
• Stepping: Step Over, Step Into, Step Out.
• Variables: Inspect properties of Objects, Arrays, and Closures.
• Call Stack: View call frames handling script execution.
• debugger Statement: Use the debugger; keyword in your code to trigger a programmatic breakpoint.

Built-in type definitions for easier development:

📚 Built-in API

The AuroraScript runtime provides a comprehensive standard library.

Core Types

Standard Library

Global Context

• global: References the root global scope.
• $state: Access user-injected state object (from C# ExecuteOptions.WithUserState).
• $args: Array of arguments passed to the current function.

📊 Benchmark Results

Performance is a priority. We encourage community contributions to optimize further!

Measured on Intel Core i7-13700KF, .NET 10.0.1.

📂 Examples

• Basic Tests: Syntax and module loading.
• Benchmarks: Performance scripts.

Made with ❤️ by l2060