Introduction

WebX68k is a web player that runs a WebAssembly build of the X68000 emulator px68k-libretro in your browser.

The IPLROM/CGROM and a bootable Human68k system disk (human302.xdf) are bundled ahead of time, so you can start right away with no setup.

Starting the emulator

A start overlay appears when you open the page, offering two choices: "Start Without a Disk" (boots from the built-in IPL ROM menu) or "Start with System Disk" (inserts the bundled human302.xdf into FDD0 before starting).

Due to browser autoplay restrictions, a click is required to start.

If a HDD is already set (see the next section), the first button's label changes to "Boot with the Selected Disks" and boots with that HDD.

URL parameters can also control disk loading and the overlay: ?fd1=URL / ?fd2=URL load a disk image into FDD0/FDD1, and ?hdd=URL sets one into the HDD, all before the page finishes opening (the URL must be served from a CORS-enabled origin). Revisiting the same URL doesn't re-download it — the image already saved in the browser, including any edits, is reused. ?system=1 loads the bundled system disk into FDD0 (unless fd1 is also given, which takes priority), and ?run=1 auto-boots without showing the overlay (playback starts muted until the first click or key press, due to autoplay restrictions). If the URL resolves to a ZIP/LZH archive containing multiple disks, it won't auto-boot — the Disk Library opens instead so you can pick. ?lib=URL (repeatable, e.g. &lib=URL2) is a sharing-link parameter that only registers images in the Disk Library, regardless of kind (FD/HDD). It never auto-inserts into a slot — the Library always opens — and skips run=1 auto-boot whenever it's given.

When the URL carries any of ?fd1= / ?fd2= / ?hdd= / ?system=, any slot the URL doesn't mention is cleared as the page opens — this is what makes a shared link boot into the same state for everyone who opens it. Note that a SCSI hard disk can't be specified via URL parameters: if a SCSI disk is inserted, opening a link with any of those parameters clears the SCSI slot too.

Screen display (1:1 pixels / 4:3 display)

Real X68000 hardware always filled a 4:3 CRT monitor, regardless of the resolution of the current screen mode. WebX68k defaults to 4:3 display, reproducing that real-hardware look, but you can switch to the core's native resolution drawn with square pixels via "…" → "Display" → "1:1 pixel display".

For example, 512x512-family screens (such as text mode) stretch horizontally, while 768x512 screens stretch vertically — which way it corrects depends on which side the native resolution leans toward. The correction always enlarges, so dots that were visible at 1:1 are never dropped. In 4:3 display, the image is first upscaled to an integer multiple without blurring the dots, then only the leftover fractional amount is smoothed — this "sharp bilinear" approach stays crisp even on high-DPI displays like Retina.

Your choice is saved in your browser and carries over to your next visit.

Loading disk images

Drag & drop a file onto an FDD0/FDD1/HDD slot row at the bottom of the player, or use the "Insert Disk" button to pick one. You can also insert from the library, create a new blank disk, or download the currently inserted disk.

There are two more places you can drop a file besides a slot row; while dragging, the drop-accepting area is highlighted with a border. Dropping onto the screen area (over the emulator display) sends a HDD image to the HDD slot (a message is shown if it's already locked after boot), and a FD image to FDD0 (or FDD1 if FDD0 is occupied and FDD1 is free). An archive containing multiple images isn't inserted into a slot — it's registered to the library, which then opens. Dropping onto the Disk Library dialog only registers the file(s) into the library without inserting into any slot, since opening the library means you're about to choose a destination yourself.

• FDD extensions: .xdf .dim .d88 .hdm .img .2hd
• HDD extensions: .hdf .dup

ZIP and LZH archives can be dropped or selected directly. Only the disk image(s) inside are extracted (readme files etc. are ignored); a single image goes straight into the target slot. If an archive contains multiple images, none of them are auto-inserted — they're registered as a folder in the Disk Library for you to pick from (see the next section for details). Supported formats: LZH lh0/lh5/lh6/ lh7, ZIP stored and deflate.

Note that the file manager (File Transfer) described below can only edit the FAT of .xdf .dim .hdm .img .2hd images. .d88 uses a different sector format and is not supported for editing.

Disk Library

"Disk Library" in the "…" menu's Disk group opens the list of disk images you have inserted so far. Choose a drive (FDD0 / FDD1 / HDD) to re-insert an image saved in your browser.

When you load a ZIP/LZH archive containing multiple disk images, it's registered here as a folder. Opening the folder switches to the list of disks inside, and you can insert each one into FDD0 / FDD1 — so a title that expects both drives loaded at once can be set up here in two steps. If the archive was loaded via a URL parameter (fd1/fd2/hdd), this dialog opens automatically with that folder expanded and highlighted.

Each slot row's "Insert from Library" button works the same way — picking a folder switches to the disks inside it, so you can swap in the 2nd, 3rd disk, etc. The FDD rows' "New Blank" creates a freshly formatted image (2HD 1232KB, the X68000 standard) and saves it to the library. The HDD row has its own "Create blank HDD" button, which builds a Human68k-partitioned, FAT16-formatted 40MB image on the spot, saves it to the library, and sets it into the HDD slot right away. It carries no IPL (boot code), so it can't boot on its own — boot Human68k from a floppy and use it as a data drive (the system disk picks it up as C:). Creating or setting a HDD is only possible before boot.

Using a SCSI hard disk

A SCSI hard disk uses its own slot, separate from the HDD (SASI) slot, and both can be used at the same time. Drag & drop a file onto the SCSI slot row at the bottom of the player, use its insert button, or "Insert from Library".

The SCSI slot row's "Create Blank SCSI Disk (choose size, FAT16)" button builds a new image (extension .hds) on the spot. Size is an integer from 1 to 2047 MB; the 2047 MB ceiling comes from the SCSI HLE (high-level emulation) handling the image size as a signed 32-bit integer. An image with multiple partitions shows up as multiple drives.

It's stored separately from the FD/HDD disk library, in your browser's OPFS (Origin Private File System) under scsi/. The settings dialog's library has its own "SCSI Disks" section for listing and deleting them. The image currently inserted in the slot can't be deleted. The "Download" button on the drive row exports the image — including the guest's writes — as a file on your machine. See "How disks are saved, and when the data disappears" below for where it's stored and when it can be lost.

HostFS (expose a local folder as a drive)

HostFS lets a folder you pick in the browser appear to the guest as a single drive (e.g. C:), without going through a disk image — you can dir, type, and copy files straight out of that folder. Use the "HostFS" row below the SCSI row at the bottom of the player.

Supported on Chrome-family browsers on PC and Android (any browser with showDirectoryPicker). Not supported on iPhone (Safari) or Firefox.

The gist: "Connect a folder" → "Install HostFS" onto the disk you want to boot → insert that disk with "To FDD0" → boot.

See the HostFS Setup Guide for step-by-step screenshots and full details

File transfer (browser ⇔ disk image)

"File Transfer" in the "…" menu's Disk group opens a two-pane file manager dialog. One pane is "Host (this PC)" and the other is the disk image. Files to transfer are staged first, then written.

Writing to a disk image only supports ASCII 8.3-format file names. Double-byte characters (such as Japanese names) or long file names cannot be written.

Existing Japanese file names, on the other hand, are supported for read-only display. Human68k stores SJIS file names concatenated with an MS-DOS reserved area, so the viewer decodes them by joining the two parts.

The HDD can only be edited before boot. Edits are saved straight to IndexedDB (the disk library), so they survive a page reload. Once running, the HDD row shows "locked while running" and becomes read-only.

Toolbar buttons

Only these 5 buttons are always visible. Everything else lives inside the "…" button's menu.

Pressing the "…" button shows 4 groups — Display / Input / Disk / State — plus "Settings", "Help", and "Language", which sit outside any group. At wide screen widths (640px and up), hovering (or tapping) a group opens a submenu to its right while the parent menu stays open. At narrow widths, the menu's contents are replaced with the group's contents instead, with a "← Back" row to go up one level.

Keyboard and mouse

While the screen (canvas) has focus, keys you press are passed straight through to the guest (X68000). Key detection is based on KeyboardEvent.code (the physical key position), so it works the same regardless of your host keyboard layout (JIS, US, etc.) — it maps to whatever is engraved at that position.

Pressing the "Virtual Keyboard" toolbar button shows/hides an on-screen keyboard at the bottom of the screen, for situations like touch devices where a physical keyboard is awkward to use. Modifier keys come in two flavors: one-shot (auto-released after the next keypress — SHIFT / CTRL / OPT.1 / OPT.2) and lock (held until tapped again — CAPS / Kana / Romaji / Code Input / Hiragana / Zenkaku), and multiple can be latched at the same time. At PC widths (640px and up), a small kana engraving is always shown in the corner of each key, like a real keycap. At phone widths (below 640px) there's no room for that, so it's hidden instead — the primary (alphanumeric) engraving swaps for the kana one only while kana lock is active. Latching SHIFT while kana lock is active swaps it again to the secondary engraving (ぁ ぃ っ 、 。 「 」 etc.). Pressing the "Ten-key" key toggles the numeric pad cluster (hidden by default since its extra width tends to break the layout on mobile).

Holding a key down repeats it (works for both the physical and virtual keyboard). The repeat delay and interval follow the guest-side SWITCH.X configuration utility, and changes you make there are saved in the browser, so they persist across reloads. However, key-click sound and keyboard LED control are not supported on the host side. Also, changing the memory size in SWITCH.X has no lasting effect — the value from the settings dialog (or ?ram=) always takes priority.

The physical keyboard, virtual keyboard, and automated input (e.g. via MCP) each keep their own reference count of pressed keys per input source, so pressing the same key from more than one source doesn't release it until the last source lets go. Losing focus (e.g. switching tabs) forcibly releases every held key, so keys never get stuck down.

Once the mouse is captured, subsequent mouse input is passed to the guest (X68000). Capture starts with a right double-click on the screen, or via "Capture Mouse" in the "…" menu's Input group. (Right double-click is detected heuristically by checking whether the timestamp gap between contextmenu events is within 500ms.)

Release capture with Esc (a standard feature of the browser's Pointer Lock API). Mouse button input is only passed to the guest while captured.

While not captured, the mouse runs in absolute position tracking mode: movement deltas are sent so that the guest cursor lands where your host cursor is. (The X68000 mouse can only report relative movement, so this is a closed loop that reads the actual cursor position back from the IOCS work area.)

The mouse sensitivity setting is stored under the browser's localStorage key webx68k.mouseSensitivity.

Using a joystick (gamepad support)

Connect a USB/Bluetooth gamepad that follows the Gamepad API's standard mapping (Xbox-style controllers, etc.) and it's recognized right away, up to two at once as Port 1/2. Directional input works from both the D-pad and the left stick (the left stick is read as digital, quantized input, with adjustable deadzone sensitivity); either one moving is passed through as the X68000-side direction.

Open the settings dialog from "Joystick Settings" in the "…" menu's Input group. Alongside the list of connected pads, it shows a numbered live display of physical input (buttons/axes) and a live display of what's currently being sent to the X68000 side (directions/TRG buttons) for that pad, so you can see with your own eyes whether a binding is actually taking effect.

You can edit bindings by pressing [Detect (Replace)] and then pressing the matching button on the pad to replace that binding, by picking one from the dropdown to add it (a single target can have multiple inputs combined), or by removing one individually with a chip's [x]. [Reset to XInput Defaults] resets everything at once. Deadzone adjustment and manually pinning which pad is used for each port are also done here.

Pad type can be set to "Default (2 Buttons)", "CPSF-MD (8 Buttons)", or "CPSF-SFC (8 Buttons)". Changing it takes effect once you press Reset (Reset performs a hard reset that restarts the core, so it takes effect at the same point as other machine configuration changes).

The "Other Bindings" section lets you map a pad button to an X68000 keyboard key — handy for titles where starting the game or pausing needs a key press, so you can play with the pad alone.

Settings are saved per connected pad, keyed by its gamepad.id, so each pad keeps its own settings even after being unplugged and reconnected.

Virtual pad (playing on a phone)

Pressing the toolbar's "Input Panel" button shows the virtual keyboard, the virtual pad, or the virtual trackpad at the bottom of the screen (mutually exclusive). While a panel is shown, small keyboard/pad/mouse icon chips appear so you can switch between them. Directional input is analog-stick-style (a fixed base with a knob, snapping to 8 directions) — a light tap near the edge of the circle is enough to get a direction out.

What each part sends is a profile. The built-ins are Joystick (2 Buttons) / Cursor Keys + Space / Tenkey / Joystick (6 Buttons). The 6-button layout follows a real Mega Drive 6-button pad — X/Y/Z on the top row, A/B/C on the bottom, both rising left to right. Pressing the pad chip opens this profile-select menu.

The pad's on-screen position is chosen automatically from measured layout space (never a hardcoded screen-width breakpoint):

• Panel — when there's spare room below the screen (as in portrait), shown as a docked strip in the same slot as the virtual keyboard. The screen is not shrunk.
• Sides — when there's spare room on the left/right of the screen (as in landscape), the stick and buttons go there so nothing covers the guest screen.
• Overlay — when neither kind of margin is big enough, the pad is drawn semi-transparently on top of the screen.

"Edit assignments…" at the end of the pad chip's menu lets you bind each of the pad's 12 input sources (stick up/down/left/right, A/B/C, X/Y/Z, Aux 1/2) to a key or a joystick button. The key picker shares the virtual keyboard's layout, and assigning a key automatically advances to the next row. Editing a built-in profile automatically creates a copy — the built-in itself is never changed.

Virtual trackpad (mouse control via touch)

iOS Safari doesn't support the Pointer Lock API, so the usual mouse-capture flow doesn't work there. As a substitute, the input panel has a third kind: the virtual trackpad. Open the input panel with the toolbar's "Input Panel" button, then pick the mouse chip from the keyboard/pad/mouse chips.

The surface sits in the strip between the screen and the toolbar and never overlaps the screen (so your finger doesn't cover the guest display while you're using it). A one-finger drag moves the cursor (relative movement, just like a laptop trackpad, with the mouse sensitivity setting applied). A tap is a left click, a two-finger tap is a right click, and a long press (450ms) holds the left button down so you can drag.

Mapping the physical keyboard to a joystick

For PC users without a gamepad who want to play joystick-only software, a physical key can be mapped to a joystick input. Enable it from "Keyboard Assignment" in the "…" menu's Input group. It is disabled by default, so it never gets in the way of normal typing.

Three built-in profiles are included: Arrows -> Joystick (2 Buttons), Arrows -> Joystick (6 Buttons) (for CPSF-MD-style software), and Arrows -> Numpad — the last one also doubles as a way to play numpad-only software on a laptop with no numpad.

Saving state and resuming

Use "Save State" and "Load State" in the "…" menu's State group to save/restore the running state to/from IndexedDB, gzip-compressed.

The disk configuration at save time (what was inserted in FDD0/FDD1/HDD) is recorded alongside the state. If it differs from the current configuration at load time, a confirmation dialog appears; canceling it aborts the restore.

How disks are saved, and when the data disappears

Anything the guest (the X68000 side) writes to a disk — in-game save data, for example — is saved to the disk library automatically. Once a write is detected, the image is written back as soon as disk activity settles down (the HDD is saved less often because of its size). Saving also happens when you eject a disk, change the machine configuration, or leave the tab, so inserting that disk again picks up where you left off.

This is stored in your browser's storage (IndexedDB for FD/HDD), not on a server. It behaves just like cookies, and it all disappears when:

• You clear "Cookies and other site data" (clearing only "Cached images and files" does not remove it)
• You clear browsing data with site data included
• You close a private/incognito window
• The device runs low on space and the browser reclaims storage
• You don't open this site in Safari for seven days (WebKit deletes all script-writable storage)

BIOS / machine configuration

If you have iplrom.dat / cgrom.dat dumped from real hardware, you can upload them from "Settings" in the "…" menu. Uploaded files are saved to IndexedDB and take priority over the bundled ROMs.

You can also configure CPU speed (10 / 16 / 25 / 33(OC) / 66(OC) / 100(OC) MHz, plus "∞MHz (host-dependent)" and "∞MHz (max speed, coarse display)") and RAM size (1–12MB) as part of the machine configuration. CPU speed applies immediately, with no reset. "∞MHz" keeps the clock as high as the device can sustain in real time, so where it settles depends on the device and its current load. "∞MHz (max speed, coarse display)" goes one step further: it throttles the display to about 30fps and spends the freed time on emulation (measured: 53-61MHz to 75-84MHz). Pick a fixed clock when you need comparable benchmark numbers.

Using the serial port (RS-232C)

Open "Settings" from the "…" menu and connect from the "Serial Port" section at the very bottom. Pressing the connect button prompts the browser to choose a serial port; pick the one you want to use.

Set the baud rate to match the connected device. A warning appears if it doesn't match the X68000 (guest) side's setting.

Add to Home Screen (iPhone)

On iPhone, there is no way for a web page to hide the browser's URL bar. Adding WebX68k to the Home Screen (via the share menu's "Add to Home Screen") and launching it from there runs it without the URL bar. On Android, the "Fullscreen" button's native fullscreen already hides it.

Controlling WebX68k from AI agents (MCP)

Open WebX68k with ?bridge=1 (or ?bridge=<port> to use a specific port; the default port is 3099) to have it connect to a local WebSocket bridge that AI agents can drive.

See mcp/README.md for full setup instructions.

Troubleshooting

• Audio is delayed or missing — Due to browser restrictions, starting requires an initial click.
• The mouse doesn't respond — The mouse may not be captured. Right double-click the screen, or use "Capture Mouse" in the "…" menu's Input group. If the cursor drifts out of sync, use "Resync Mouse" in the same group.
• A disk isn't recognized — Check the file extension (FDD: .xdf,.dim,.d88,.hdm,.img,.2hd; HDD: .hdf,.dup).
• Loading a state causes odd behavior — If a confirmation dialog about a disk configuration mismatch appears, canceling it aborts the load.
• Drives like C: don't appear even though a SCSI disk is inserted — Depending on the boot disk's configuration, there may be no room to register a SCSI driver, so the SCSI drive won't be recognized. This doesn't prevent booting itself. If you need the drive, try a different boot disk (such as the bundled system disk).