libwasmoon
v0.3.1
Published
A real lua VM with JS bindings made with webassembly (library version for embeddable lua bundles)
Maintainers
leso-knReadme
Based on ❤️ wasmoon
libwasmoon
A real lua VM with JS bindings made with webassembly (library version for embeddable lua bundles)
About
Libwasmoon is a javascript template which allows to run Lua code in the browser.
It is based on the wasmoon project and works by loading base64-encoded versions of custom-tailored Lua binaries. This allows to embed compiled Lua bundles and native Lua modules (e.g. written in C) via WebAssembly.
The result is a single javascript file which runs Lua code that can interact with the DOM / javascript APIs and vice versa – meaning that other <script>-tags can interact with variables and functions provided by Lua (see Interacting with Javascript APIs).
Feature Additions
- Compile modules into a single javascript file
- Support for native Lua modules (e.g. written in C)
- Provides a system interface for most POSIX features via WASI
Usage
The template is designed to work together with lrc (the LRocket-compiler) which targets WebAssembly.
Installing the WebAssembly target for the LRocket compiler:
> luarocks install lrocket-build-wasmThe compiler provides three targets for WebAssembly:
You can compile to Javascript, to include your code as javascript module:
> lrc --otype wasm-js main.lua -o output-lib.jsYou can compile directly to HTML, to write your complete page in Lua (starting off with window.document.body.innerHTML = [[...]]):
> lrc --otype wasm-html main.lua -o index.htmlOr compile to .wasm to handle the embedding into the libwasmoon template yourself:
> lrc --otype wasm main.lua -o lua-module.wasmIf you would like to handle the compilation yourself (e.g. use a different compiler than lrc) virtually any compiler that targets wasm32 can be used to build your own Lua binary script.
For details see Using a Different Compiler.
Interacting with Javascript APIs
Libwasmoon makes the window-object available inside the global Lua environment – This allows to use any desired Javascript API via Lua syntax!
All is made possible by the fantastic work of the wasmoon project!
Examples
Button Callback
window.document.innerHTML = '<button>Click me!</button>'
-- for syntactic convenience we can export all contents of 'window.<...>' to the global environment
setmetatable(_G, { __index = window })
local button = document.querySelector 'button'
button.addEventListener('click', function()
alert('Lua function called!')
end)Lua Function in Javascript
function window.myLuaFunction()
return math.random(1, 42)
end// in javascript
alert('The answer to everything is: ' + myLuaFunction());Geo Location
window.navigator.geolocation.getCurrentPosition(function(loc)
-- prints to console.log()
print('You are here', loc.coords.latitude, loc.coords.longitude)
end)Using a Different Compiler
Any compiler that targets wasm32 (ideally wasm32-wasi / wasm32-wasi-threads) can be used to build the binary that will be embedded into the libwasmoon template.
The compiled binary should export a symbol named void __lr_entrypoint(lua_State *L) (called by libwasmoon after the Lua-state has been initialized).
We recommend linking against lua-wasm32, which is a static lua library (the one lrc links against when compiling bundles for WebAssembly). It is available via luarocks (note that the rock also ships a copy of the libwasmoon template):
> luarocks install lua-wasm32For example, the clang-compiler could be used to compile a custom lua interpreter which can then be embedded into the libwasmoon template:
> clang --target=wasm32-wasi-threads -o lua-module.wasm my-custom-interpreter.c \
<path-to-lua-wasm32>/lib/liblua-5.4.aTurining lua-module.wasm into Javascript:
> sed dist/loader.js.tpl "s/{{libwasmoon:wasm_bytes}}/$(base64 -w0 lua-module.wasm)/g" > \
output-lib.jsUsing the module in HTML:
<!DOCTYPE html>
<body></body>
<script src="output-lib.js"></script>You may also embed the script between an inline <script>...</script>-tag.
License
Just like wasmoon, libwasmoon is licensed under the MIT License.
Created by Lesosoftware in 2025