Skip to content

Latest commit

 

History

History
124 lines (88 loc) · 4.63 KB

README.md

File metadata and controls

124 lines (88 loc) · 4.63 KB

LUME

GLAS

WebGL in WebAssembly with AssemblyScript.

This is a work-in-progress port of Three.js, a JavaScript 3D WebGL library, into AssemblyScript.

Motivation

It'd be sweet to have a high-performing WebGL engine that runs in the web via WebAssembly and is written in a language that web developers are already familiar with: JavaScript, in the form of TypeScript (a superset of JavaScript with types).

Enter AssemblyScript, a toolchain that allows us to write a strictly-typed subset of TypeScript code and compile it to WebAssembly (an assembly-like language representing machine code) for speed.

Status

⚠️ ALPHA STATE

The project is currently in its very early alpha stages. We have an amazing group of programmers building the initial ASWebGLue library. This library allows AssemblyScript programs to call the browser's underlying WebGL interface. This is required before we are able render anything to the screen. A majority of the Three.js library and their unit test have been ported over.

See the current progress in the project board or review our issues.

Goal

Our initial port project board we're tracking all the classes that need to be ported. The initial goal is to reproduce the following basic Three.js demo, but entirely in AssemblyScript:

Initial Goal: https://codepen.io/trusktr/pen/EzBKYM

A brief overview of the work consists of picking a Three.js class, translating it from JavaScript (with TypeScript declaration files), and porting into AssemblyScript (effectively merging the .js and .d.ts files).

Most logic can be ported unchanged, but sometimes there are features of plain JS that AssemblyScript does not support. For example Assembly script does not support any type. Three.js APIs that accept plain object literals with arbitrary properties need to be converted into class structures with specific property types. Additionally unit test files also need to be ported over from *.test.js and into as-pect *.spec.ts files.

If you would like to help, awesome! We are currenty looking for help, testing, and feedback. Please read about how to contribute or view a detailed example of how to port some of the code.

How It Works

We have an HTML page that loads the glas WebAssembly module and runs it, but so far this module only instantiates an Object3D instance to show that we're able to run the module.

Later we'll eventually connect the module to a <canvas> element in the DOM and actually render something.

Build & Run

To run the example GLAS application in your browser use the following command:

# install or update dependencies
npm install

# build and serve the project in browser
npm start

Now see the devtools console in your browser tab for some output that tell us that our GLAS program has been loaded and initialized.

NOTE: the project does not currently have a watch mode with automatic rebuild. So you will need to execute npm run build again and then refresh to see the changes.

Our goal is to get GLAS distributed as a library on NPM so that you can include into your own AssemblyScript application. Until this is implemented, you can add your application code into the src/as/index.ts AssemblyScript file. This is currently the entry point for GLAS.

Testing

Unit testing is handled by the as-pect test runner for AssemblyScript. It is based on Mocha testing API with similar describe and it functions, etc.

To run the tests, run the following commands in your terminal:

# run unit tests
npm test

The console output should report which tests pass and which tests fail.

If you are interested in developing GLAS please read the detailed process on our development page