Skip to content

Mask transitions shaped like an image or a sprite, closing on the player (#1399) - #1894

Merged
obiot merged 5 commits into
masterfrom
claude/hopeful-hypatia-jl2ouu
Nov 18, 2026
Merged

obiot merged 5 commits into
masterfrom
claude/hopeful-hypatia-jl2ouu

Conversation

@obiot

@obiot obiot commented Nov 18, 2026

Copy link
Copy Markdown
Member

Description

Mask transitions can now use an image or a sprite as the mask, not only an Ellipse or a Polygon. They can also close on a chosen point and be inverted.

shape (on MaskEffect, state.transition("mask", …) and Trigger) now also takes:

  • an image, or the name of a preloaded one;
  • a Sprite: the frame it shows when the transition starts, flipped the way it is drawn.

The image's alpha is the silhouette, made solid: faint pixels count in full, and enclosed gaps such as eyes are filled. With no shape, MaskEffect uses an iris.

center is where the mask closes and the reveal opens. It takes a renderable, read once on screen when the transition starts (it handles floating containers and Camera3d depth), or a screen point.

invert makes the shape the cover: filled with the colour, it grows to hide the scene.

Trigger: setting shape or center to "touching" means whoever set the trigger off, so a level door can be configured from Tiled properties alone.

How it behaves:

  • Ends uncovered: every shape grows about its thickest part until the screen is fully inside it, so a reveal ends with the scene uncovered. This covers a U shape, a sprite drawn off-centre in its frame, and a polygon that doesn't surround its origin. Diamonds and stars no longer cover the corners from the very start, and no longer snap open at the end of the reveal.
  • The reveal outlives the sprite: it reuses the silhouette and point the hide settled, so a state change that destroys the player in between is fine.
  • state.transition lets go of the sprite: a sprite or renderable is let go after one transition, so later changes never read a destroyed or recycled object.
  • Renderers: it is drawn with plain images and fills, with no shader. Tested on Canvas and WebGL; WebGPU was not available in the test environment, so its tests were skipped.
  • Fallback: a shape that can't be used warns once and uses an iris. That includes an unknown name, an unreadable or fully transparent image, a destroyed sprite, or a value that isn't a shape.

Shared code:

  • Sprite#drawFrame(target, x, y) (internal) now holds the frame placement that Sprite#draw and the silhouette both use.
  • NineSliceSprite draws through it too. As a side effect it now honours flicker(), which it used to ignore.
  • An internal MaskEffect#reverseOptions() builds the reveal for both state.transition and Trigger.

Also in this PR:

  • melonJS is bumped to 20.17.0, with an unreleased changelog section.
  • Skills updated: scenes-and-state, camera-and-drawing, tilemaps, and the skill index.

Type of change

  • Bug fix
  • New feature
  • Documentation update
  • Performance improvement
  • Refactoring (no functional changes)

Checklist

  • I have read the Contributing Guide
  • My code follows the existing code style (pnpm lint passes)
  • I have tested my changes locally (pnpm test passes)
  • I have added tests that cover my changes (if applicable)
  • The build succeeds (pnpm build)

The full engine suite passes (11,427 tests). The two new spec files cover image, sprite and atlas silhouettes, center, invert, the fallbacks, the Trigger reveal, and the full state.transition path, including a pixel check at the end of the reveal.

Related issues

Closes #1399


Generated by Claude Code

…yer (#1399)

- MaskEffect, state.transition("mask") and Trigger take as shape an image,
  the name of a preloaded one, or a Sprite (the frame it shows when the
  transition starts, facing its way). The silhouette is made solid: faint
  pixels count in full and gaps inside the outline are filled
- center closes the mask on a renderable or a screen point, and the reveal
  opens from the same place; invert makes the shape the cover, growing out
  of that point. state.transition takes them as a fifth argument
- On a Trigger, shape and center "touching" stand for whoever walked in,
  usable from Tiled properties
- The reveal reuses the silhouette and point the hide settled, so the state
  change destroying the player in between is fine
- Every shape grows until the screen is wholly inside it, so a reveal ends
  uncovered: a Polygon mask no longer jumps open at the last frame
- Drawn with plain images and fills, the same on Canvas, WebGL and WebGPU
- Platformer example: the door closes the player's own silhouette onto it
- Skills, changelog, TSDoc examples; melonJS 20.17.0 (unreleased)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
- A shape grows about its thickest part (a distance transform of the
  silhouette, or the deepest point of a polygon not around its origin), so
  a U, a crescent or a sprite drawn off-centre still ends with the screen
  uncovered; a fully transparent image or frame warns and is an iris
- A center in a floating container is read on the screen (isFloating), and
  under a Camera3d at its absolute depth
- A shape that is not an Ellipse, Polygon, image, name or Sprite warns that
  it is not supported; no shape at all is the default iris
- state.transition lets go of a sprite or renderable once the hide has read
  it, so a later change never reads a destroyed or recycled player
- Sprite#drawFrame(target, x, y) holds the frame placement Sprite#draw and
  the silhouette share; NineSliceSprite draws through it, so its silhouette
  is its full size and it now honours flicker()
- MaskEffect#reverseOptions() gives the settings of the effect played back,
  used by state.transition and Trigger; MaskEffectOptions is exported
- One CanvasRenderTarget setup for the silhouette and the cover
- Tests: off-centre and empty silhouettes, off-origin and inverted polygons,
  nearly closed draws, floating and Camera3d centers, flips on both axes,
  turned and trimmed atlas frames, nine-slice, unreadable images, the
  Trigger reveal, a pixel check at the end of a state transition, and the
  later change after the player is gone

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
…is internal (#1399)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnzwA4a7ZyjLBpbeEpFLu6
Copilot AI balanced review requested due to automatic review settings November 18, 2026 23:19

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@obiot
obiot merged commit ade18c7 into master Nov 18, 2026
6 checks passed
@obiot
obiot deleted the claude/hopeful-hypatia-jl2ouu branch November 18, 2026 23:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

MaskEffect: add image/texture-based mask support

3 participants