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.

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 1:1 pixel display (the core's native resolution drawn with square pixels, the common look for web-based emulators), but you can switch to a mode that reproduces the real hardware's look via "…" → "Display" → "4:3 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. Interpolation (a soft blur) is only enabled while 4:3 display is on, giving a look closer to a real CRT.

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.

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 either the virtual keyboard or the virtual pad at the bottom of the screen (mutually exclusive). While a panel is shown, small ⌨/🎮 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 🎮 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 🎮 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.

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), 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) and RAM size (1–12MB) as part of the machine configuration.

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.