Merge pull request #1421 from melonjs/feat/freeze-hitstop

feat: add state.freeze() for hit-stop / hit-pause effects

Author: obiot

packages/examples/src/examples/whac-a-mole/ExampleWhacAMole.ts

@@ -1,6 +1,7 @@
 import { Application, audio, loader, save, state } from "melonjs";
 import { createExampleComponent } from "../utils";
 import { data } from "./data";
+import { setupViewportEffects } from "./effects";
 import { PlayScreen } from "./play";
 import { resources } from "./resources";
 
@@ -11,6 +12,9 @@ const createGame = () => {
 		scale: "auto",
 	});
 
+	// vignette (always on) + dormant chromatic aberration (burst on hit)
+	setupViewportEffects(_app.viewport, _app.renderer);
+
 	// initialize the "sound engine"
 	audio.init("mp3,ogg");
 

packages/examples/src/examples/whac-a-mole/effects.ts

@@ -0,0 +1,77 @@
+import {
+	type Camera2d,
+	ChromaticAberrationEffect,
+	DropShadowEffect,
+	pool,
+	type Renderer,
+	type Sprite,
+	Tween,
+	VignetteEffect,
+	type WebGLRenderer,
+} from "melonjs";
+
+/**
+ * Attach an always-on vignette to the viewport.
+ * Effects degrade gracefully on Canvas (ShaderEffect logs a warning and
+ * leaves `enabled = false`; all method calls become no-ops).
+ */
+export function setupViewportEffects(
+	viewport: Camera2d,
+	renderer: Renderer,
+): void {
+	viewport.addPostEffect(new VignetteEffect(renderer as WebGLRenderer));
+}
+
+/**
+ * Attach a dormant chromatic aberration effect to a sprite.
+ */
+export function attachChromaticAberration(
+	sprite: Sprite,
+	renderer: Renderer,
+): ChromaticAberrationEffect {
+	const fx = new ChromaticAberrationEffect(renderer as WebGLRenderer, {
+		offset: 0,
+		textureSize: [sprite.width, sprite.height],
+	});
+	sprite.addPostEffect(fx);
+	return fx;
+}
+
+/**
+ * Attach a static drop shadow to a sprite, giving it weight on the scene.
+ */
+export function attachDropShadow(sprite: Sprite, renderer: Renderer): void {
+	sprite.addPostEffect(
+		new DropShadowEffect(renderer as WebGLRenderer, {
+			offsetX: 2.0,
+			offsetY: 3.0,
+			color: [0.0, 0.0, 0.0],
+			opacity: 0.2,
+			textureSize: [sprite.width, sprite.height],
+		}),
+	);
+}
+
+/**
+ * Trigger a brief chromatic-aberration burst on the given effect.
+ * Uses a Tween with `updateWhenPaused = true` so the decay animates
+ * *through* a freeze.
+ * @param fx - the effect to drive
+ * @param peak - peak offset in texels
+ * @param durationMs - total duration of the decay
+ */
+export function triggerChromaticBurst(
+	fx: ChromaticAberrationEffect,
+	peak = 8,
+	durationMs = 250,
+): void {
+	fx.setOffset(peak);
+	const driver = { offset: peak };
+	const tween = pool.pull("me.Tween", driver) as Tween;
+	tween.updateWhenPaused = true;
+	tween
+		.to({ offset: 0 }, { duration: durationMs })
+		.easing(Tween.Easing.Cubic.Out)
+		.onUpdate(() => fx.setOffset(driver.offset))
+		.start();
+}

packages/examples/src/examples/whac-a-mole/mole.ts

@@ -1,5 +1,19 @@
-import { audio, input, pool, Sprite, save, Tween } from "melonjs";
+import {
+	audio,
+	type ChromaticAberrationEffect,
+	game,
+	input,
+	pool,
+	Sprite,
+	save,
+	Tween,
+} from "melonjs";
 import { data } from "./data";
+import {
+	attachChromaticAberration,
+	attachDropShadow,
+	triggerChromaticBurst,
+} from "./effects";
 
 /**
  * a mole entity
@@ -12,11 +26,19 @@ export class MoleEntity extends Sprite {
 	initialPos: number;
 	displayTween: Tween;
 	hideTween: Tween;
+	chromaticEffect: ChromaticAberrationEffect;
 
 	constructor(x: number, y: number) {
 		// call the constructor
 		super(x, y, { image: "mole", framewidth: 178, frameheight: 140 });
 
+		// per-mole shader effects:
+		// - drop shadow gives the mole weight against the hole
+		// - chromatic aberration bursts on hit
+		// shadow is added first so chromatic aberration applies on top
+		attachDropShadow(this, game.renderer);
+		this.chromaticEffect = attachChromaticAberration(this, game.renderer);
+
 		// idle animation
 		this.addAnimation("idle", [0]);
 		// laugh animation
@@ -60,6 +82,13 @@ export class MoleEntity extends Sprite {
 			// play ow FX
 			audio.play("ow");
 
+			// juice trifecta: shake + per-mole chromatic burst + hit-stop
+			// (start motion/burst first, then freeze — the chromatic decays in
+			// real-time *during* the freeze, making the impact feel punchy)
+			game.viewport.shake(8, 400);
+			triggerChromaticBurst(this.chromaticEffect, 8, 250);
+			game.freeze(150);
+
 			// add some points
 			data.score += 100;
 

packages/melonjs/CHANGELOG.md

@@ -3,6 +3,8 @@
 ## [19.2.0] (melonJS 2) - _unreleased_
 
 ### Added
+- State: `state.freeze(duration, music?)` — freeze the current stage for a fixed duration in milliseconds, then automatically resume. Returns a `Promise<void>` that resolves on unfreeze. Reentrant calls extend the freeze to whichever end-time is later (they do not stack). Useful for hit-stop / hit-pause effects on impact.
+- Application: `app.pause(music?)`, `app.resume(music?)`, `app.freeze(duration, music?)` — convenience proxy methods on the Application instance for the corresponding `state.*` methods.
 - Text: `visibleCharacters` and `visibleRatio` properties on Text and BitmapText for progressive text reveal and typewriter effects. Animate `visibleRatio` with Tween for character-by-character text display.
 - Tween: `repeatDelay(ms)` method and `repeatDelay` option in `to()` — adds a delay before each repeat cycle.
 - Camera: FBO-based post-processing pipeline — assign a `ShaderEffect` to any camera's `shader` property to apply full-screen post-effects (vignette, scanlines, desaturation, etc.). Works with multiple cameras independently (e.g. main camera + minimap with different effects). Renderer manages FBO lifecycle via `beginPostEffect()`/`endPostEffect()`/`blitEffect()` methods.

packages/melonjs/src/application/application.ts

@@ -552,6 +552,45 @@ export default class Application {
 		this.isDirty = true;
 	}
 
+	/**
+	 * Pause the current stage. Convenience proxy for {@link state.pause}.
+	 * @param [music=false] - also pause the current music track
+	 * @example
+	 * app.pause();        // pause game updates, keep music playing
+	 * app.pause(true);    // pause game updates and music
+	 */
+	pause(music: boolean = false): void {
+		state.pause(music);
+	}
+
+	/**
+	 * Resume the current stage. Convenience proxy for {@link state.resume}.
+	 * @param [music=false] - also resume the current music track
+	 */
+	resume(music: boolean = false): void {
+		state.resume(music);
+	}
+
+	/**
+	 * Freeze the current stage for a fixed duration, then automatically resume.
+	 * Useful for hit-stop / hit-pause effects on impact. Reentrant calls extend
+	 * the freeze to whichever end-time is later (they do not stack).
+	 * Convenience proxy for {@link state.freeze}.
+	 * @param duration - duration of the freeze in milliseconds
+	 * @param [music=false] - also pause the current music track during the freeze
+	 * @returns a Promise that resolves once the freeze ends
+	 * @example
+	 * // simple hit-stop on impact
+	 * app.freeze(80);
+	 *
+	 * // chain VFX after the freeze
+	 * await app.freeze(120);
+	 * spawnImpactParticles();
+	 */
+	freeze(duration: number, music: boolean = false): Promise<void> {
+		return state.freeze(duration, music);
+	}
+
 	/** @ignore */
 	_tick(time: number): void {
 		this.update(time);

packages/melonjs/src/state/state.ts

@@ -62,6 +62,12 @@ let _extraArgs: unknown[] | null = null;
 // store the elapsed time during pause/stop period
 let _pauseTime: number = 0;
 
+// freeze() bookkeeping
+let _freezeTimer: ReturnType<typeof setTimeout> | null = null;
+let _freezeEndsAt: number = 0;
+let _freezeMusic: boolean = false;
+let _freezeResolvers: Array<() => void> = [];
+
 /**
  * @ignore
  */
@@ -93,6 +99,21 @@ function _pauseRunLoop(): void {
 	_isPaused = true;
 }
 
+/**
+ * End an active freeze: resume the run loop and resolve waiters.
+ * @ignore
+ */
+function _endFreeze(): void {
+	_freezeTimer = null;
+	_freezeEndsAt = 0;
+	state.resume(_freezeMusic);
+	const resolvers = _freezeResolvers;
+	_freezeResolvers = [];
+	for (const resolve of resolvers) {
+		resolve();
+	}
+}
+
 /**
  * this is only called when using requestAnimFrame stuff
  * @param time - current timestamp in milliseconds
@@ -328,6 +349,53 @@ const state = {
 		}
 	},
 
+	/**
+	 * Freeze the current stage for a fixed duration, then automatically resume.
+	 * Useful for hit-stop / hit-pause effects on impact.
+	 *
+	 * If `freeze()` is called again while a freeze is already active, the freeze
+	 * is *extended* to whichever end-time is later (calls do not stack). The
+	 * `music` flag from the initial call is preserved for the eventual resume.
+	 * @param duration - duration of the freeze in milliseconds
+	 * @param [music=false] - also pause the current music track during the freeze
+	 * @returns a Promise that resolves once the freeze ends
+	 * @example
+	 * // simple hit-stop on impact
+	 * state.freeze(80);
+	 *
+	 * // chain VFX after the freeze
+	 * await state.freeze(120);
+	 * spawnImpactParticles();
+	 */
+	freeze(duration: number, music: boolean = false): Promise<void> {
+		// guard against NaN, Infinity, and negative durations — silently no-op
+		// (mirrors how state.pause/resume quietly ignore invalid states)
+		if (!Number.isFinite(duration) || duration < 0) {
+			return Promise.resolve();
+		}
+		const now = globalThis.performance.now();
+		const newEndsAt = now + duration;
+
+		if (_freezeTimer !== null) {
+			// already frozen: only extend if the new end-time is later
+			if (newEndsAt > _freezeEndsAt) {
+				clearTimeout(_freezeTimer);
+				_freezeEndsAt = newEndsAt;
+				_freezeTimer = setTimeout(_endFreeze, newEndsAt - now);
+			}
+		} else {
+			// start a new freeze
+			_freezeMusic = music;
+			_freezeEndsAt = newEndsAt;
+			this.pause(music);
+			_freezeTimer = setTimeout(_endFreeze, duration);
+		}
+
+		return new Promise<void>((resolve) => {
+			_freezeResolvers.push(resolve);
+		});
+	},
+
 	/**
 	 * return the running state of the state manager
 	 * @returns true if a "process is running"