Forem: loading

Building a JavaScript Runtime in Rust powered by the Nova engine

loading — Mon, 30 Sep 2024 19:20:52 +0000

Ever wondered how JavaScript runtimes like Node.js or Deno are built? Or maybe you've thought about creating your own JavaScript runtime with custom features and performance tweaks? If so, you're in the right place! In this tutorial, we'll dive into building a JavaScript runtime using Rust and the andromeda_runtime crate.

Introduction

Rust is a systems programming language that guarantees memory safety without the need for a garbage collector, making it an excellent choice for high-performance applications. By leveraging Rust's capabilities along with the andromeda_runtime crate, we can create a custom JavaScript runtime that's both fast and secure.

The andromeda_runtime crate provides a solid foundation for executing JavaScript code. It comes with recommended extensions, built-in functions, and an event loop handler, all of which simplify the process of setting up a runtime.

Prerequisites

Before we get started, make sure you have the following:

Rust: Ensure you have Rust installed. If not, you can download it from rust-lang.org.
Cargo: Cargo is Rust's package manager and comes bundled with Rust installations.
Basic Knowledge of Rust: Familiarity with Rust's syntax and concepts will be helpful.
JavaScript/TypeScript: A basic understanding of JavaScript or TypeScript.

Setting Up the Project

Let's kick things off by creating a new Rust project:

cargo new jsruntime
cd jsruntime

Next, open Cargo.toml and add the necessary dependencies:

[dependencies]
andromeda_core = { git = "https://github.com/tryandromeda/andromeda" }
andromeda_runtime = { git = "https://github.com/tryandromeda/andromeda" }
clap = { version = "4.5.16", features = ["derive"] }
tokio = { version = "1.39.0", features = ["rt", "sync", "time"] }

1. Importing Dependencies

First, we'll import the necessary crates and modules:

use andromeda_core::{Runtime, RuntimeConfig};
use andromeda_runtime::{
    recommended_builtins, recommended_eventloop_handler, recommended_extensions,
};
use clap::{Parser as ClapParser, Subcommand};

Here's what each of these imports does:

andromeda_core: Contains the core components for building our runtime.
andromeda_runtime: Provides recommended built-ins, extensions, and the event loop handler we'll use.
clap: A crate for parsing command-line arguments, which we'll use to build our CLI.

2. Defining the Command-Line Interface

Next, let's define a CLI using clap:

#[derive(Debug, ClapParser)]
#[command(name = "jsruntime")]
#[command(
    about = "JavaScript Runtime built for a blog post",
    long_about = "JS/TS Runtime in Rust powered by Nova built for a blog post"
)]
struct Cli {
    #[command(subcommand)]
    command: Command,
}

#[derive(Debug, Subcommand)]
enum Command {
    /// Runs a file or files
    Run {
        #[arg(short, long)]
        verbose: bool,

        #[arg(short, long)]
        no_strict: bool,

        /// The files to run
        #[arg(required = true)]
        paths: Vec<String>,
    },
}

Here's what's happening:

Cli Struct: This struct represents our command-line interface, including any subcommands and arguments.
Command Enum: This enum defines the available subcommands—in this case, only Run.

3. The Main Function

Our main function orchestrates the runtime execution:

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = Cli::parse();

    let rt = tokio::runtime::Builder::new_current_thread()
        .enable_time()
        .build()
        .unwrap();

    // Run the JSRuntime in a secondary blocking thread so tokio tasks can still run
    let runtime_thread = rt.spawn_blocking(|| match args.command {
        Command::Run {
            verbose,
            no_strict,
            paths,
        } => {
            let mut runtime = Runtime::new(RuntimeConfig {
                no_strict,
                paths,
                verbose,
                extensions: recommended_extensions(),
                builtins: recommended_builtins(),
                eventloop_handler: recommended_eventloop_handler,
            });
            let runtime_result = runtime.run();

            match runtime_result {
                Ok(result) => {
                    if verbose {
                        println!("{:?}", result);
                    }
                }
                Err(error) => runtime.agent.run_in_realm(&runtime.realm_root, |agent| {
                    eprintln!(
                        "Uncaught exception: {}",
                        error.value().string_repr(agent).as_str(agent)
                    );
                    std::process::exit(1);
                }),
            }
        }
    });

    rt.block_on(runtime_thread)
        .expect("An error occurred while running the JS runtime.");

    Ok(())
}

Let's break down what's happening in this function:

a. Parsing Arguments

We start by parsing the command-line arguments using clap:

let args = Cli::parse();

b. Setting Up the Tokio Runtime

We create a new Tokio runtime. Tokio is an asynchronous runtime for Rust that allows us to handle asynchronous operations efficiently.

let rt = tokio::runtime::Builder::new_current_thread()
    .enable_time()
    .build()
    .unwrap();

c. Spawning a Blocking Task

We spawn a blocking task to run our JavaScript code. This ensures our runtime doesn't block other asynchronous tasks.

let runtime_thread = rt.spawn_blocking(|| match args.command { /* ... */ });

d. Handling the `Run` Command

Within the spawned task, we match the command:

Command::Run {
    verbose,
    no_strict,
    paths,
} => {
    let mut runtime = Runtime::new(RuntimeConfig { /* ... */ });
    let runtime_result = runtime.run();

    match runtime_result {
        Ok(result) => { /* ... */ }
        Err(error) => { /* ... */ }
    }
}

Here's what's going on:

Creating the Runtime: We instantiate a new Runtime with the provided configuration.
Running the Runtime: We call runtime.run() to execute the JavaScript code.
Handling Results: If the execution is successful, we print the result if verbose is enabled. If there's an error, we print the uncaught exception.

e. Blocking on the Runtime Thread

Finally, we wait for the spawned task to complete:

rt.block_on(runtime_thread)
    .expect("An error occurred while running the JS runtime.");

Customizing the Runtime

One of the great benefits of building your own runtime is the ability to customize it to your needs. Let's explore some ways you can tailor the runtime.

1. Adding Custom Extensions

Extensions add extra functionality to the runtime. You can add your own custom extensions or modify existing ones.

let custom_extensions = vec![
    // Your custom extensions here
];

let mut runtime = Runtime::new(RuntimeConfig {
    // ...
    extensions: custom_extensions,
    // ...
});

2. Modifying Built-ins

Built-in functions are essential for interacting with the runtime environment. You can add or customize built-in functions to suit your requirements.

let custom_builtins = vec![
    // Your custom built-in functions here
];

let mut runtime = Runtime::new(RuntimeConfig {
    // ...
    builtins: custom_builtins,
    // ...
});

3. Custom Event Loop Handler

If you need custom event loop behavior, you can provide your own event loop handler.

fn custom_eventloop_handler() {
    // Your custom event loop logic here
}

let mut runtime = Runtime::new(RuntimeConfig {
    // ...
    eventloop_handler: custom_eventloop_handler,
    // ...
});

Running the Runtime

To test your runtime, let's create a simple JavaScript file, test.js:

console.log("Hello from the JS Runtime!");

Then, run the runtime using:

cargo run run test.js

If everything is set up correctly, you should see:

Hello from the JS Runtime!

Conclusion

And there you have it! You've built a simple JavaScript runtime using Rust. Not only have you demystified how runtimes like Node.js and Deno work, but you've also set the foundation for endless possibilities in customizing and extending your own runtime.

Remember, this is just the beginning. Keep experimenting, add new features, and most importantly, have fun along the way!

Happy coding! 🚀

References

Pong using Deno and caviar as a native app using WebGPU

loading — Mon, 14 Feb 2022 03:36:18 +0000

Recently Deno has been taking the world by storm. Deno is a fast, secure, and open-source runtime environment created as a replacement for Node.js. In this tutorial we will create a basic pong game using the Caviar library which uses WebGPU bindings and resembles most javascript game engines. Feel free to check out caviar here.

you can find the final version in the examples repo right here aswell.

lets get started shall we?

Project Setup

for this project all we'll need is a file hierarchy as such

├── pong
│   ├── src
│   │   ├── scenes
│   │   │   ├── Game.ts
│   ├── main.ts

lets start by creating a basic setup in main.ts

import { World } from 'https://deno.land/x/caviar/mod.ts';
import { Game } from './src/scenes/Game.ts';

const pong = new World({
    title: "test",
    width: 1300,
    height: 800,
    resizable: true,
}, [Game]);
await pong.start();

after this we will no longer need to touch main.ts and we'll direct our attention to the Game.ts file

Setting up our Components

in the Game.ts file we'll add the following code to create our first player

import { PICO8, Scene, TextureSprite } from 'https://deno.land/x/caviar/mod.ts';

export class Game extends Scene {
    public p1: TextureSprite | undefined;
    public setup() {
      this.p1 = new TextureSprite(this, 0, 336, {
        data: [
          ".9.",
          ".9.",
          ".9.",
        ],
        pixelWidth: 32,
        pixelHeight: 32,
        palette: PICO8,
      })
      this.addChild(this.p1);
    }
    public update() {

    }

}

we create a new texture sprite with 3 pixels down and we use the built-in PICO8 palette.
if we run our code using deno run -A --unstable main.ts we should get a window looking something like
we now create a second player and a ball the same way

export class Game extends Scene {
    public ball: TextureSprite | undefined;
    public p1: TextureSprite | undefined;
    public p2: TextureSprite | undefined;
    public setup() {
      this.p1 = new TextureSprite(this, 0, 336, {
        data: [
          ".9.",
          ".9.",
          ".9.",
        ],
        pixelWidth: 32,
        pixelHeight: 32,
        palette: PICO8,
      });
      this.p2 = new TextureSprite(this, 1168, 336, {
        data: [
          ".A.",
          ".A.",
          ".A.",
        ],
        pixelWidth: 32,
        pixelHeight: 32,
        palette: PICO8,
      });
      this.ball = new TextureSprite(this, 568, 336, {
        data: [
          "E",
        ],
        pixelWidth: 32,
        pixelHeight: 32,
        palette: PICO8,
      });
      this.addChild(this.p1);
      this.addChild(this.p2);
      this.addChild(this.ball);
    }
    public update() {

    }

}

Movement

to listen for keypresses in Caviar you need to define which keys you want to listen for, do this at the beginning of the setup method. In this tutorial we'll listen for W,S,E and D.

 ...
public setup() {
    this.setKeys(['W','S','E','D']);
    ...

next we'll create a keyDown method and check for each key and change the player's positions based on the key pressed

...
public keyDown(key: any) {
    const p1 = this.p1 as TextureSprite;
    const p2 = this.p2 as TextureSprite;
    switch (key) {
      case "W":
        if (p1.y > 25) p1.setY(p1.y - 4);
        break;
      case "S":
        if (p1.y < 700) p1.setY(p1.y + 4);
        break;
      case "E":
        if (p2.y > 25) p2.setY(p2.y - 4);
        break;
      case "D":
        if (p2.y < 700) p2.setY(p2.y + 4);
        break;
    }
  }

Ball Movement

first lets create 2 new properties vx and vy for the balls velocity and why not also make a score property aswell

...
public vx = 2;
public vy = 2;
public score: number[] = [0,0];
...

now we add the ball physics to the update function

...
public update() {
    const ball = this.ball as TextureSprite;
    const p1 = this.p1 as TextureSprite;
    const p2 = this.p2 as TextureSprite;
    if (ball.y > 25 || ball.y < 10) { 
      this.vy *= -1;
    }

    if ( 
      ball.x < p1.x + 32 + 10 &&
      ball.y > p1.y &&
      ball.y < p1.y + 96
    ) {
      this.vx *= -1.1;
      this.vy = Math.floor(Math.random() * 8) - 4; 
    }

    if (
      ball.x > p2.x - 10 && 
      ball.y > p2.y &&
      ball.y < p2.y + p2.height
    ) {
      this.vx *= -1.1;
      this.vy = Math.floor(Math.random() * 8) - 4; 
    }
    if (ball.y < 25 || ball.y > 800) {
      this.vy *= -1;
    }
    if (ball.x < 25) {
      //p1 side
      ball.setX(568);
      ball.setY(336);
      this.score[1] += 1;
      this.vx = 4;
      this.vy = 4;
    }
    if (ball.x > 1168) {
      //p2 side
      ball.setX(568);
      ball.setY(336);
      this.score[0] += 1;
      this.vx = -4;
      this.vy = 4;
    } 
    ball.setX(ball.x + this.vx);
    ball.setY(ball.y + this.vy);

  }
...

now the game should be working.

Conclusion

Caviar is currently only native (time of writing) but we plan to implement cross platform features in the future. feel free to contribute here

Forem: loading

Building a JavaScript Runtime in Rust powered by the Nova engine

Introduction

Prerequisites

Setting Up the Project

1. Importing Dependencies

2. Defining the Command-Line Interface

3. The Main Function

a. Parsing Arguments

b. Setting Up the Tokio Runtime

c. Spawning a Blocking Task

d. Handling the Run Command

e. Blocking on the Runtime Thread

Customizing the Runtime

1. Adding Custom Extensions

2. Modifying Built-ins

3. Custom Event Loop Handler

Running the Runtime

Conclusion

References

Pong using Deno and caviar as a native app using WebGPU

Project Setup

Setting up our Components

Movement

Ball Movement

Conclusion

d. Handling the `Run` Command