Welcome to L2Project Documentation

Documentation wanted! Join us on GitHub!

About L2Project Script Engine

L2Project uses plain V8 - JavaScript engine provided by ClearScript, V8 is widely used JavaScript engine by Chrome Web Brower and Node.JS platform.

As L2Project is only using V8, many things that are common to web browsers or Node.JS platform are not available. Common things you may use in JS such as DOM elements or Node.JS modules are simply not there, even something like setTimeout, console.log is not available in plain V8, but don't worry it's availabe in L2Project, but it uses custom (in-house, much simpler) implementation, you might not even notice. Good example of what you won't find in L2Project script engine are events, but they are easy to implement if needed.

You can expect ECMAScript to work flawlessly.

JavaScript really fits well for scripting L2 and better, you can even write scripts using TypeScript, you can write tests for your scripts, you can run different preprocessors on your code. Whole world of npm packages is available to you (not all of them will work).

Using TypeScript and L2Project Type definitions

See examples/typescript.

Using TypeScript and ESBuild for writting scripts

esbuild is great for building TypeScript code and guess what, it does support "neutral" platform, it can also bundle your dependencies into a single file and watch for changes as you write your script, fyi. L2Project automaticaly reloads your script if it changes, that makes really nice dev workflow.

esbuild supports TypeScript files by default, so you don't have to do anything. VSCode is strongly suggested when you are working with JS/TS.

Suggested esbuild options to use:

• --platform=neutral
  • --main-fields=module,main
• --bundle (outputs single file)
• --define:process.env.NODE_ENV="\`"production\`"" (some of the libraries are checking for this, eg. xstate)
  • watch out for "production" escaping as int this example it's escaped for PowerShell
• --define:global=globalThis (some of the libraries are using global, eg. xstate)

Example for PowerShell

npx esbuild --platform=neutral --bundle --main-fields=module,main .\index.ts --outfile=bundle.js --define:process.env.NODE_ENV="\`"production\`"" --define:global=globalThis

Examples

Hello World example!

// async functions cannot be run on the top level, you must wrap them inside the closure
(async () => {
    await sleep(1000);
    console.log('Hello World'); // Will show "Hello World!" in L2Project JS Console window, after 1s.
})().catch(err => console.error(err.stack)); // When something fails withtin the closure function above, you would not know without this log statement.