BambooBasic can compile your program to run in a web browser. Instead of producing a native executable, the web target transpiles your .bam source to JavaScript and runs it on top of BBRuntimeWeb.js, a WebGPU-based runtime library. Your game runs on a canvas in the browser, with no plugin or install required.

The web runtime aims to behave like the desktop runtime, so most 2D programs port with only small changes. But a browser is a very different environment to a native window, and a few things work differently by necessity. This guide covers the differences and the best practices for a clean port.

Note: Not all of the desktop runtime has been ported to web. See What Is Not Available below.

In the editor, choose the Web (WebGPU) build target from the Target menu, then Build and Run as usual. The transpiler will:

• Convert your .bam source to <name>.js
• Generate an HTML page (<name>.html) that hosts the canvas
• Copy BBRuntimeWeb.js, your Media folder, and any .wgsl shaders into a WebOutput folder
• Start a local web server and open the page in your browser

The HTML page is generated only once. If a <name>.html already exists it is left alone, so you can freely customise the page (add a title graphic, description, styling) and your edits will survive future builds.

This is the single biggest difference from desktop. A native program owns its main loop:

; DESKTOP - the program owns the loop
Function Main()
    SetupGame()
    While running
        b2dCls()
        UpdateGame()
        RenderGame()
        b2dFlip()
    Wend
    b2dEnd()
EndFunction

A browser cannot work this way — an infinite loop would freeze the page. Instead, the browser owns the loop and calls your code once per frame. You provide a function named WebLoop, and start the loop with b2dStartWebLoop():

; WEB - the browser drives the loop, calling WebLoop each frame
Function Main()
    b2dGraphics(WIDTH, HEIGHT, 3)   ; must be in Main - see below
    SetupGame()
    b2dStartWebLoop()                 ; hand control to the browser
    Return 0
EndFunction

Function WebLoop()
    b2dCls()
    UpdateGame()
    RenderGame()
    b2dFlip()
EndFunction

To convert a desktop program, move the body of your While…Wend loop into a WebLoop() function, and replace the loop itself with a call to b2dStartWebLoop(). Use b2dStopWebLoop() to stop it (a browser tab cannot be closed by the program — stopping the loop simply leaves the last frame on screen).

b2dGraphics initialises WebGPU and is asynchronous. The transpiler automatically awaits it and marks Main as an async function. However, only Main is made async — so if you call b2dGraphics from a setup helper, you will get a JavaScript error ("await is only valid in async functions"). Always call b2dGraphics directly from Main, before any other graphics or asset calls.

On desktop, loading an image or sound blocks until it is ready. In a browser, files are fetched over the network in the background. b2dLoadImage, b2dLoadFont, b2dLoadAnimImage, audLoadSound and audLoadMusic all return a handle immediately, but the data arrives some frames later.

This means:

• Do not rely on an asset in the same function that loads it. Its dimensions are not known yet — b2dGetImageWidth, b2dGetStringWidth and friends return 0 until the asset has loaded.
• Do not play a sound or music in your setup code. The buffer is not ready, so the call is silently ignored (it returns channel 0).
• Drawing a not-yet-loaded image simply draws nothing that frame — it does not error — so drawing every frame in WebLoop naturally "fills in" as assets arrive.

Poll for readiness before you use an asset's data or play it:

; Load in setup (returns immediately)
music = audLoadMusic("Media/theme.ogg")

; Start it once ready, inside WebLoop
If musicStarted = 0 And audSoundLoaded(music) = 1 Then
    audPlayMusic(music)
    audSetMusicVolume(music, 0.3)
    musicStarted = 1
EndIf

Browsers block all audio until the user first interacts with the page (a click or key press). This is a browser security rule, not a BambooBasic limitation. The runtime automatically resumes audio on the first interaction, so audio "just works" from the first click onward — but any sound you try to play before the user has interacted will be silent.

Best practice: add a "Click to start" prompt to your HTML page, or simply design your title screen so the first thing the player does is click a button. A welcome sound played at startup will not be heard; trigger such sounds from a button instead.

Keyboard and mouse work as on desktop (inpIsKeyDown, inpIsKeyHit, inpGetMouseX, inpIsMouseHit, etc.). A few notes:

• If your loop uses a fixed timestep and reads input only on some frames, call sysUpdateEvents() inside that timestep block, exactly as on desktop. This tells the runtime to clear "hit" states on your schedule rather than every frame, so presses are never missed.
• sysGetKey() returns the next typed character and consumes it — useful for text entry. Control keys come back as positive codes (Enter 13, Escape 27, Backspace 8, Tab 9), extended keys (arrows, function keys) as negative codes.
• inpClipMouseToWindow() / inpUnclipMouse() use browser Pointer Lock, for FPS-style mouse control. Pointer Lock can only be requested from inside a click or key handler, so call it in response to input, not at startup.
• inpMoveMouse() is not available — browsers do not allow a program to warp the cursor.

Game controllers work as on desktop: the same inpCreateController, inpControllerButtonDown/Hit, D-pad, trigger, stick and vibration functions, the same XINPUT_GAMEPAD_* button constants, ports 0–3, and the same deadzones and trigger threshold. sysUpdateEvents() updates them each frame (programs that don't call it get them updated at b2dFlip). A few browser rules apply:

• A controller is hidden until a button is pressed. Browsers only show a pad to the page once one of its buttons has been pressed while the page is open, so inpGetControllerAmount is 0 and inpIsControllerConnected is false until then. Don't quit when no controller is found; create one for port 0 and show "Press a button on your controller" until it connects.
• Vibration works in Edge and Chrome. In other browsers the vibration functions do nothing.
• Xbox, PlayStation and Switch Pro pads map exactly in Edge and Chrome. A pad the browser doesn't recognise may have its buttons in other places.
• Controllers only work on secure pages: https:// sites, or the editor's local server.

See Controller_Down_web and Controller_Hit_web in examples/BambooRuntime/3 - Input.

WebGPU cannot compile HLSL, so web shaders are written in WGSL (WebGPU Shading Language). The shader system is otherwise the same: the same functions, the same indexed parameter scheme (b2dSetImageShaderFloat(sh, "0", value) writes slot 0, of 64), and image/text/screen shaders all work.

Provide a .wgsl file alongside (or instead of) your .hlsl file and name it explicitly:

; Desktop
glow = b2dLoadImageShader("Media/Glow.hlsl")
; Web
glow = b2dLoadImageShader("Media/Glow.wgsl")

The runtime prepends a preamble to every web shader, so a .wgsl file only needs to define its @fragment fn main. The preamble provides:

• The texture, sampler and parameter bindings
• A PSInput struct (image shaders receive a scalar alpha; text shaders receive a full color vec4)
• param(i) to read parameter slot i as a float, and paramInt(i) to read it as an integer

// Web image shader (Glow.wgsl) - the runtime supplies the rest
@fragment
fn main(input: PSInput) -> @location(0) vec4<f32> {
    let intensity = param(0);
    var c = textureSample(imageTexture, samplerState, input.texCoord);
    c = vec4<f32>(c.rgb * (1.0 + intensity), c.a * input.alpha);
    return c;
}

Gotcha: WGSL forbids the derivative-based textureSample after any non-uniform branch (for example an early return whose condition varies per pixel, as in a screen shader that discards outside a curved edge). In that case use textureSampleLevel(tex, samp, uv, 0.0) instead — level 0 is correct for the non-mipmapped frame buffer.

There is no real filesystem in a browser, so the file functions are backed by the browser's localStorage. The handle-based API (fileWriteFile, fileReadFile, fileWriteInt, fileReadLine, fileSaveString, etc.) works as on desktop, which makes save games and settings portable. Two things to know:

• Writes are only saved when you call fileCloseFile(). An open file is held in memory and written back on close — forget to close it and the data is lost. There is no flush-on-exit as there is on desktop.
• Capacity is limited. localStorage allows roughly 5–10 MB per site, and the data is base64 encoded (a 33% overhead), giving about 3.75 MB of usable file data. It is per-site and is lost if the user clears their browsing data — fine for saves and settings, not for anything irreplaceable.

fileEof() matches C's behaviour: it becomes true only after a read runs past the end, not on reaching it. A While Not fileEof() read loop therefore gets one final iteration that returns an empty value — guard on the returned value, not the loop condition:

While Not fileEof(f)
    line$ = fileReadLine(f)
    If line$ <> "" Then
        ; ... process line$ ...
    EndIf
Wend

To move a file between the web file store and the user's own computer (a save game to keep, a level to load), use fileExportWeb(filepath) — the browser downloads the stored file, usually into the Downloads folder — and fileImportWeb(filter), which opens the browser's file picker and stores the chosen file under its own name. Import can't wait for the user, so check fileImportWebResult() each frame: it gives "" until something happens, then the file's name (or "*cancelled*") once:

If inpIsKeyHit(VKEY_L) Then fileImportWeb(".sav")

Local name$ = fileImportWebResult()
If name$ <> "" And name$ <> "*cancelled*" Then LoadGame(name$)

Browsers only open a file picker straight after a click or key press, so call fileImportWeb from one. These are web only. BGI programs can also use bgiExportFileWeb / bgiImportFileWeb, which answer with a BGI event instead (see the BGI section below).

Directory functions and ZIP functions are not available on web.

The BGI GUI toolkit works on the web. Windows, buttons, lists, menus, tabs, tree and list views, rich text boxes, canvases and the rest are drawn inside the page's canvas, in the same classic Windows look as the desktop, using Dear ImGui compiled to WebAssembly (bbimgui.js). The same bgi functions, gizmo handles and events work, so most of a desktop GUI program carries over as it is. The GUI layer is only loaded when a program calls bgiInitBGI.

Starting a new one: File > New > BGI Application asks Desktop or Web. Web writes a template with the loop in WebLoop() and switches the build target to Web, and the designer keeps its event dispatcher up to date inside WebLoop().

• Call bgiInitBGI from Main. Like b2dGraphics, it is asynchronous on the web. If the program hasn't called b2dGraphics, it starts graphics at the page canvas's size.
• The page canvas is the GUI's desktop. Windows are centred on it, and it is 800x600 unless you make it bigger: call b2dGraphics(width, height, 1) before bgiInitBGI for a larger window.
• Fonts: all GUI text is drawn in Liberation Sans (a free font with Arial's metrics), at the size you ask for. Font names are kept, and saved in RTF files, but not used for drawing.
• Designer files: bgiLoadGizmos("MyApp.bam.bgi") with the file name written as a string is built into the program by the web build, so it works at once, as on desktop.

The body of the desktop While loop moves into WebLoop(), exactly as for any web program. Call bgiFlushEvent() at the end of each WebLoop: an event stays current until it is flushed, so without it the same click is handled every frame. On the web, events queue up instead of overwriting each other, so none are lost.

Function Main()
    bgiInitBGI("Arial", 16)
    window = bgiCreateWindow("My Window", 400, 300)
    button = bgiCreateButton("Click me", 20, 20, 100, 30, window)
    b2dStartWebLoop()
    Return False
EndFunction

Function WebLoop()
    sysUpdateEvents()
    If bgiGetEventMessage() = BGI_EVENT_COMMAND_CLICK And bgiGetEventSource() = button Then
        Print "Clicked!"
    EndIf
    bgiFlushEvent()
EndFunction

A web page can't close itself, so the close box works a little differently:

• The main window (the first one the program makes) folds up to a small title bar when its X is pressed. Pressing X again, or double-clicking the title, opens it again. It raises no CLOSE event.
• Any other window closes when its X is pressed: it is hidden (so bgiSetWindowVisibility can show it again), and CLOSE is raised with that window as the source, as on desktop.

A browser can't stop and wait for an answer, so message boxes and the open, save, colour and font dialogs return at once (0 or "") and the answer arrives later as an event: message BGI_EVENT_COMMAND_CLICK, source = the window passed in, bgiGetEventData() = 1 for OK/Yes or 0 for Cancel/No. The event ID says which dialog answered (the constants are in BBR_INCLUDE.bam):

; Ask...
If eventSource = btnOpen Then bgiOpenFileDialog("Open", "", window)

; ...and handle the answer when it comes
If eventMsg = BGI_EVENT_COMMAND_CLICK And eventID = BGI_EVENT_ID_FILEDIALOG Then
    If bgiGetEventData() = 1 Then LoadMyFile(bgiGetEventExtra())
EndIf

• Open uses the browser's own file picker, and copies the chosen file into the web file store so the file functions can read it.
• Save asks for a file name and hands it back in the event; files you then write with that name go in the web file store (which has no folders).
• Browsers only open a file picker straight after a click or key press, so open it from a button or menu handler.

• Canvases work as on desktop: bgiSetActiveCanvas, the usual b2d drawing, then bgiFlipCanvas. Canvas filters and screen shaders work too (WGSL shaders, as for any web program).
• RichTextBox shows bold, italic, underline, sizes and colours, and has mouse selection, the clipboard and undo. bgiSaveRichTextFile writes RTF into the web file store and bgiLoadRichTextFile reads RTF or plain text from it; use bgiExportFileWeb and bgiImportFileWeb to move those files to and from the user's computer.

• HTMLView (bgiCreateHTMLView and its functions): not possible inside the canvas. The functions exist but do nothing, and say so once in the browser console.
• bgiOpenFolderDialog: a browser can't give a page a folder path. It returns "".

IGI (the igi functions) works the same in the browser as on the desktop. Its module loads on the first igi call, so the GUI appears a few frames after the game (styling set up in Main is kept until then), igiLoadFont fetches its font in the background, and Ctrl+V pastes into IGI text boxes. IGI draws on top of the game, after any screen shader, and BGI windows go on top of IGI.

The web runtime currently covers 2D graphics, movie playback, audio, input (game controllers included), math, strings, timing, file I/O and the BGI GUI. The following are not (yet) ported:

For web projects, import BBRuntimeWeb.decls instead of BBRuntime64.decls. Only the ported functions are declared there, so the transpiler will catch any desktop-only call at build time.

• Change Import "BBRuntime64.decls" to Import "BBRuntimeWeb.decls"
• Move the main loop body into a WebLoop() function; call b2dStartWebLoop() from Main
• Call b2dGraphics directly in Main, not in a helper
• Defer playing sound/music until audSoundLoaded() reports ready
• Compute anything that needs an asset's size (text width, image size) inside WebLoop, not at load time
• Translate any .hlsl shaders to .wgsl and update the load paths
• Make sure every file you write is closed with fileCloseFile()
• Expect no audio until the first click; design your title screen around a click
• GUI programs: call bgiInitBGI from Main, end WebLoop with bgiFlushEvent(), and handle dialog answers as events (see BGI)
• Remove or replace any calls to unported functions the compiler flags

Everything the browser needs is in the WebOutput folder: the HTML page, your transpiled .js, BBRuntimeWeb.js, the Media folder and any .wgsl shaders (plus, for GUI programs, bbimgui.js and the Liberation Sans fonts). Upload that folder to any static web host and it will run — no server-side code is required.

Because assets are fetched over HTTP, the page must be served by a web server (the editor starts one for you locally). Opening the HTML file directly from disk with a file:// URL will fail, as browsers block fetch from local files.

BambooBasic © 2026 Michael Denathorn