20.13.0: UI update (checkbox, slider, skins, layout, scrolling, shadows, bounce, keyboard/gamepad focus); gamepad plugin hover fix by obiot · Pull Request #1808 · melonjs/melonJS

obiot · 2026-10-31T03:10:08Z

Description

20.13.0: bump the version. melonjs and .claude-plugin/plugin.json go from 20.12.0 to 20.13.0, together, as scripts/release.ts requires.
UI widgets (UI: standardize the UI example's button, checkbox and panel into engine widgets, and add a slider #1722). The UI example's hand-made button, checkbox and panel become engine widgets, plus a slider.
Review passes (bugs) and an API consistency pass against the existing UI widgets (UIBaseElement, UITextButton, UIPanel, ProgressBar), so one style object fits every widget.
Drop shadows on UIPanel and ProgressBar.
A bounce on every UIBaseElement: hoverScale and pressScale.
Keyboard and gamepad focus, on the widgets themselves: focus().
Gamepad plugin (Gamepad plugin: a touch on the controls still reaches the game as a hover (pointerover / pointerenter) #1805): a touch on the controls no longer reaches the game as a hover.

New widgets

UICheckbox: a box with its label (label, or labelOn / labelOff, both settable later). Clicking the label toggles it too.
- Drawn: boxSize, boxColor, boxHoverColor, checkColor, borderColor, borderWidth, radius.
- Skinned: skin: { atlas, on, off, hoverOn?, hoverOff?, disabledOn?, disabledOff? }.
- checked and toggle() from code never call onChange(checked, checkbox); only the user does.
- With a group, it is a radio button: one checked, drawn round. UICheckbox.checkedIn(group) returns the checked one, and changing group moves it at once.
UISlider:
- min, max, step (all settable; they re-clamp silently), value, ratio, horizontal or vertical.
- Drag the thumb (it keeps following off the track), click the track to jump, use the wheel, or the arrows with the focus.
- onChange(value, slider) while it moves and onChangeEnd once on release. Neither fires from code.
- Caption and value text with valueFormat(value, ratio).
- Drawn (trackColor, fillColor, thumbColor, thumbHoverColor, thumbBorderColor, thumbBorderWidth), or skinned ({ atlas, track, fill?, thumb, thumbHover? }).

Keyboard and gamepad focus

For a game played without a mouse or a touch screen. There is no focus manager to set up: a widget takes the focus with focus().

From then on, the arrows or the D-pad move the focus to the nearest focusable widget that way, edge to edge.
Enter, Space or A press the focused widget as a click does. Left and right step a slider.
A ring (UIBaseElement.focusRingColor) shows the focus while the keyboard or a pad is used, and hides when the mouse moves. A focused widget in a scrolling panel scrolls into view.
Until a widget has the focus, nothing listens and the keys and the pad are the game's. blur(), or the focused widget leaving the scene, gives them back. The pad is read directly, real or virtual, so the game's pad bindings stay as they are.
On UIBaseElement: focus(), blur(), focused, focusable (on for buttons, checkboxes and sliders), onNavigate, and the static focusOwner.
Enter goes to the focused button: another button bound to Enter through bindKey waits while the ring shows elsewhere.

Changes to existing widgets

UITextButton:
- an onClick setting (onClickCallback), called on a completed click: pointer, bindKey or focus accept; never a press dragged off, cancelled or turned into a scroll.
- skin: { atlas, normal, pressed?, hover?, disabled? } as nine-slices, with pressed art drawn lowered.
- pressedColor: left undefined, it follows hoverOnColor, so existing buttons look the same.
- The names the other widgets use: width / height for its size, fontSize (pixels, also with a bitmap font), labelFillStyle, borderColor. The old borderWidth / borderHeight / size / fillStyle / borderStrokeColor still work.
- Colours take any Paint. resize(). Settings are no longer written back, so one object can make several buttons.
- A bitmap font is used as before (by name, fontData, or an image); any other font is drawn as a CSS font, where the button used to throw.
- label is the text. bitmapText is deprecated but keeps its BitmapText type, so existing TypeScript code compiles.
UIPanel:
- nine-slice skin, title (titleFont, titleFontSize, titleFillStyle), draggable (moved by its title or frame, never through a widget on it; comes to the front);
- layout: column, row or grid, with padding, gap, align and autoSize. "stretch" only resizes buttons and panels.
- scroll: cropped content, wheel, drag with momentum, scrollbar, scrollTo, scrollToChild(child, margin?), scrollX / scrollY, maxScrollX / maxScrollY, onScroll.
- A drag starting on a button scrolls and cancels the press. A slider, or anything with keepsDrag, keeps its drags. A scrolling panel inside another scrolls alone.
Drop shadows, UIPanel and ProgressBar:
- shadowColor (its alpha sets the darkness), shadowOffsetX, shadowOffsetY, shadowBlur.
- The soft edge is stacked translucent rounded rectangles, the same on Canvas, WebGL and WebGPU.
- It follows radius and goes under a skin. It is drawn outside the bounds, so it never takes the pointer.
UIBaseElement:
- enabled (shared by every UI element), cancelPress() / onCancel(), keepsDrag.
- hoverScale / pressScale, also a setting on every widget: an eased bounce under the pointer or the focus and while held, scaling the drawing only, not the hit area or the layout.
- The focus methods above.
- A draggable element tapped with no hover first (touch) no longer throws, and drags by touch. In the world it no longer jumps by the camera position.
ProgressBar: onChange also gets the bar.
Input:
- A child cropped by a container with clipping, or scrolled out of a panel, no longer receives pointer events where it is not drawn (Container#clipContains).
- Drags end on their own pointer's release only, in the event family the engine listens to.
- A virtual gamepad in the same slot as a real pad is no longer hidden by it when the UI reads the pads.
Exported: UINavAction, UIJuiceSettings, UISkin, UILabel, Paint, and every widget's settings and skin types, all under @category UI.

Known limitation, documented in the skill: on WebGL, a scrolling panel inside another clipping container is cropped to its own area only.

Gamepad plugin (#1805)

A touch fires pointerover and pointerenter before its pointerdown, and pointerout and pointerleave after its pointerup. The plugin only kept down, move, up and cancel from the engine, so the widget under a button got onOver as it was pressed: the Alex 4 menu arrow jumped to the line under B.

The plugin now also captures the four hover events and stops them for a touch that lands on, or lifted from, a control. A mouse hovering over the controls is left alone. Changelog entry under [1.0.2] - unreleased; the package version is unchanged until it is released.

Example, docs

The UI example uses all of these:
- a skinned options panel laid out as a column: music and sound FX checkboxes, volume sliders wired to audio, Accept / Cancel (Cancel restores from code, showing that onChange does not fire), and Video Options;
- the progress bars;
- a level list at the top right showing 16 of 30 levels and scrolling the rest, with the last six locked;
- soft drop shadows, a bounce on the buttons and checkboxes, and keyboard / gamepad play starting on the first checkbox, with a hint line for the controls.
One shared { font, fontSize, labelFillStyle } style object goes to buttons, checkboxes and sliders alike.
melonjs-ui-and-text skill: sections per widget, panel art, shadows, layout and scrolling, the bounce, focus(), plus a symptom table.
Changelog under 20.13.0: Added, Changed, Deprecated, Fixed.

How it was checked

tests/ui-widgets.spec.js (120 tests): driven by real pointer, wheel, mouse, touch and keyboard events, and a virtual gamepad. It covers:
- every widget's behaviour, drawn and skinned, horizontal and vertical;
- layout and scrolling, including sideways and line-mode wheels, wheel pass-through at a panel's end, fling limits, grid stretch, row autoSize and clearChildren;
- each review finding;
- the API changes, with the real button instead of stub subclasses;
- drop shadows, also under a faded parent, and scrollbar geometry;
- the bounce, including its easing and that it doesn't change the hit area;
- focus: nothing without focus(), arrows, accept on a button and a checkbox, slider steps, disabled and hidden widgets skipped, stuck presses called off, bindKey yielding, the ring drawn only while it shows, scroll into view, a gamepad's D-pad and A (and one already held), blur(), and the keys given back when the focused widget leaves;
- clipping through a real container;
- a draw pass of all four widgets on Canvas and WebGL.
A review of the tests for gaps found three bugs, now fixed, each with a test checked to fail without the fix:
- a slider's default value text kept the old decimals after step changed;
- Enter on a focused button the pointer already held clicked it on release;
- a virtual gamepad sharing a slot with a real pad was not read.
UI, pointer, progress bar, container, draggable, gamepad, keyboard and input suites: 576 tests pass. Changed tests:
- a button with no bitmap font no longer throws;
- ProgressBar's onChange gets a third argument.
Gamepad plugin: 46 tests pass, including a new one for Gamepad plugin: a touch on the controls still reaches the game as a hover (pointerover / pointerenter) #1805, checked to fail without the fix.
tsc, eslint, biome and the build, including the declaration check, pass.
The example was driven in headless Chromium with mouse, touch and keyboard, and the published demo was run under a strict content security policy.

Type of change

Checklist

I have read the Contributing Guide
My code follows the existing code style (pnpm lint passes)
I have tested my changes locally: the UI, pointer, input, gamepad and container suites; CI runs the whole suite
I have added tests that cover my changes (if applicable)
The build succeeds (pnpm build)

Related issues

Closes #1722
Closes #1805

🤖 Generated with Claude Code

https://claude.ai/code/session_01JnzwA4xBNBw7cEZzG1bUru

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JnzwA4xBNBw7cEZzG1bUru

Copilot