Add visible character control to Text and BitmapText (#1411)

Add `visibleCharacters` and `visibleRatio` properties to both Text and
BitmapText for progressive text reveal and typewriter effects. Animate
`visibleRatio` with Tween for character-by-character text display.

BitmapText: skip glyph rendering past the visible count in the draw loop.
Text: substring each line before fillText/strokeText, re-render canvas
texture when visibleCharacters changes.

Also add `repeatDelay` to Tween — delay before each repeat cycle.
Clean up outdated `me.` references in Text/BitmapText JSDoc examples.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: obiot

README.md

@@ -57,7 +57,7 @@ Graphics
 - 3D mesh rendering with OBJ/MTL model loading, perspective projection and hardware depth testing
 - Built-in shader effects (Flash, Outline, Glow, Dissolve, CRT, Hologram, etc.) and custom shader support via `ShaderEffect` for per-sprite fragment effects (WebGL)
 - Trail renderable for fading, tapering ribbons behind moving objects (speed lines, sword slashes, magic trails)
-- System & Bitmap Text
+- System & Bitmap Text with built-in typewriter effect
 - Video sprite playback
 
 Sound

packages/examples/src/examples/text/text.ts

@@ -5,6 +5,7 @@ import {
 	Renderable,
 	Stage,
 	Text,
+	Tween,
 } from "melonjs";
 
 /**
@@ -123,19 +124,29 @@ export class TextScreen extends Stage {
 			1,
 		);
 
-		// ---- Multiline text (right aligned) ----
-		app.world.addChild(
-			new Text(165, 290, {
-				font: "Arial",
-				size: 14,
-				fillStyle: "white",
-				textAlign: "right",
-				textBaseline: "top",
-				lineHeight: 1.1,
-				text: "this is another web font \nwith right alignment\nand it still works!",
-			}),
-			1,
-		);
+		// ---- Multiline text (right aligned) with typewriter ----
+		const rightText = new Text(165, 290, {
+			font: "Arial",
+			size: 14,
+			fillStyle: "white",
+			textAlign: "right",
+			textBaseline: "top",
+			lineHeight: 1.1,
+			text: "this is another web font \nwith right alignment\nusing typewriter effect!",
+		});
+		rightText.visibleCharacters = 0;
+		app.world.addChild(rightText, 1);
+
+		new Tween(rightText)
+			.to(
+				{ visibleRatio: 1.0 },
+				{
+					duration: 5000,
+					repeat: Infinity,
+					repeatDelay: 1500,
+				},
+			)
+			.start();
 
 		// ---- Fancy BitmapText multiline with word wrap ----
 		const fancy = new BitmapText(620, 230, {
@@ -151,16 +162,28 @@ export class TextScreen extends Stage {
 		);
 		app.world.addChild(fancy, 1);
 
-		// ---- BitmapText multiline centered ----
+		// ---- BitmapText multiline centered with typewriter effect ----
 		const bMulti = new BitmapText(w / 2, 400, {
 			font: "xolo12",
-			size: 2.5,
+			size: 1.5,
 			textAlign: "center",
 			textBaseline: "top",
-			text: "THIS IS A MULTILINE\n BITMAP TEXT WITH MELONJS\nAND IT WORKS",
+			text: "THIS IS A MULTILINE BITMAP TEXT\n USING TYPEWRITER EFFECT",
 		});
+		bMulti.visibleCharacters = 0;
 		app.world.addChild(bMulti, 1);
 
+		new Tween(bMulti)
+			.to(
+				{ visibleRatio: 1.0 },
+				{
+					duration: 5000,
+					repeat: Infinity,
+					repeatDelay: 1500,
+				},
+			)
+			.start();
+
 		// ---- BitmapText baseline test (y=375) ----
 		xPos = 0;
 		const tmpBFont = new BitmapText(0, 0, { font: "arialfancy", size: 1.275 });

packages/melonjs/CHANGELOG.md

@@ -3,6 +3,8 @@
 ## [19.2.0] (melonJS 2) - _unreleased_
 
 ### Added
+- 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.
 - Renderable: multi-pass post-effect chaining — `postEffects` array replaces single `shader` property. Multiple effects are applied in sequence via FBO ping-pong (e.g. `sprite.addPostEffect(new DesaturateEffect(r)); sprite.addPostEffect(new InvertEffect(r));`). Single-effect renderables use a zero-overhead `customShader` fast path (no FBO). Camera manages its own FBO lifecycle; per-sprite effects use a separate FBO pair.
 - Renderable: `addPostEffect(effect)`, `getPostEffect(EffectClass?)`, `removePostEffect(effect)`, `clearPostEffects()` — manage post-processing shader effects on any renderable

packages/melonjs/src/renderable/text/bitmaptext.js

@@ -26,13 +26,13 @@ export default class BitmapText extends Renderable {
 	 * @param {number} [settings.wordWrapWidth] - the maximum length in CSS pixel for a single segment of text
 	 * @param {(string|string[])} [settings.text] - a string, or an array of strings
 	 * @example
-	 * // Use me.loader.preload or me.loader.load to load assets
-	 * me.loader.preload([
-	 *     { name: "arial", type: "binary" src: "data/font/arial.fnt" },
-	 *     { name: "arial", type: "image" src: "data/font/arial.png" },
+	 * // Use loader.preload or loader.load to load assets
+	 * loader.preload([
+	 *     { name: "arial", type: "binary", src: "data/font/arial.fnt" },
+	 *     { name: "arial", type: "image", src: "data/font/arial.png" },
 	 * ])
 	 * // Then create an instance of your bitmap font:
-	 * let myFont = new me.BitmapText(x, y, {font:"arial", text:"Hello"});
+	 * let myFont = new BitmapText(x, y, {font:"arial", text:"Hello"});
 	 * // two possibilities for using "myFont"
 	 * // either call the draw function from your Renderable draw function
 	 * myFont.draw(renderer, "Hello!", 0, 0);
@@ -133,6 +133,22 @@ export default class BitmapText extends Renderable {
 			this.anchorPoint.set(0, 0);
 		}
 
+		/**
+		 * the number of characters to display (use -1 to show all).
+		 * Useful for typewriter effects combined with Tween.
+		 * @public
+		 * @type {number}
+		 * @default -1
+		 * @see BitmapText#visibleRatio
+		 * @example
+		 * // show only the first 5 characters
+		 * bitmapText.visibleCharacters = 5;
+		 * // typewriter effect
+		 * bitmapText.visibleCharacters = 0;
+		 * new Tween(bitmapText).to({ visibleRatio: 1.0 }, { duration: 2000 }).start();
+		 */
+		this.visibleCharacters = -1;
+
 		// instance to text metrics functions
 		this.metrics = new TextMetrics(this);
 
@@ -188,6 +204,33 @@ export default class BitmapText extends Renderable {
 		return this;
 	}
 
+	/**
+	 * the ratio of visible characters (0.0 to 1.0).
+	 * Setting this automatically updates {@link visibleCharacters}.
+	 * @public
+	 * @type {number}
+	 */
+	get visibleRatio() {
+		if (this.visibleCharacters === -1) {
+			return 1.0;
+		}
+		const total = this._text.reduce((sum, line) => {
+			return sum + line.length;
+		}, 0);
+		return total > 0 ? this.visibleCharacters / total : 1.0;
+	}
+
+	set visibleRatio(value) {
+		if (value >= 1.0) {
+			this.visibleCharacters = -1;
+		} else {
+			const total = this._text.reduce((sum, line) => {
+				return sum + line.length;
+			}, 0);
+			this.visibleCharacters = Math.floor(value * total);
+		}
+	}
+
 	/**
 	 * update the bounding box for this Bitmap Text.
 	 * @param {boolean} [absolute=true] - update the bounds size and position in (world) absolute coordinates
@@ -314,6 +357,10 @@ export default class BitmapText extends Renderable {
 				break;
 		}
 
+		// running character counter for visibleCharacters
+		let charCount = 0;
+		const maxChars = this.visibleCharacters;
+
 		for (let i = 0; i < this._text.length; i++) {
 			x = lX;
 			const string = this._text[i].trimEnd();
@@ -335,6 +382,11 @@ export default class BitmapText extends Renderable {
 			// draw the string
 			let lastGlyph = null;
 			for (let c = 0, len = string.length; c < len; c++) {
+				// stop drawing when visibleCharacters limit is reached
+				if (maxChars !== -1 && charCount >= maxChars) {
+					return;
+				}
+
 				// calculate the char index
 				const ch = string.charCodeAt(c);
 				const glyph = this.fontData.glyphs[ch];
@@ -371,6 +423,8 @@ export default class BitmapText extends Renderable {
 						"BitmapText: no defined Glyph in for " + String.fromCharCode(ch),
 					);
 				}
+
+				charCount++;
 			}
 			// increment line
 			y += stringHeight;

packages/melonjs/src/renderable/text/text.js

@@ -38,7 +38,7 @@ export default class Text extends Renderable {
 	 * @param {number} [settings.wordWrapWidth] - the maximum length in CSS pixel for a single segment of text
 	 * @param {(string|string[])} [settings.text=""] - a string, or an array of strings
 	 * @example
-	 * let font = new me.Text(0, 0, {font: "Arial", size: 8, fillStyle: this.color});
+	 * let font = new Text(0, 0, {font: "Arial", size: 8, fillStyle: this.color});
 	 */
 	constructor(x, y, settings) {
 		// call the parent constructor
@@ -179,6 +179,20 @@ export default class Text extends Renderable {
 			offscreenCanvas: false,
 		});
 
+		/**
+		 * the number of characters to display (use -1 to show all).
+		 * Useful for typewriter effects combined with Tween.
+		 * @public
+		 * @type {number}
+		 * @default -1
+		 * @see Text#visibleRatio
+		 * @example
+		 * // typewriter effect
+		 * text.visibleCharacters = 0;
+		 * new Tween(text).to({ visibleRatio: 1.0 }, { duration: 2000 }).start();
+		 */
+		this.visibleCharacters = -1;
+
 		// instance to text metrics functions
 		this.metrics = new TextMetrics(this);
 
@@ -317,6 +331,34 @@ export default class Text extends Renderable {
 		return this;
 	}
 
+	/**
+	 * the ratio of visible characters (0.0 to 1.0).
+	 * Setting this automatically updates {@link visibleCharacters}.
+	 * @public
+	 * @type {number}
+	 */
+	get visibleRatio() {
+		if (this.visibleCharacters === -1) {
+			return 1.0;
+		}
+		const total = this._text.reduce((sum, line) => {
+			return sum + line.length;
+		}, 0);
+		return total > 0 ? this.visibleCharacters / total : 1.0;
+	}
+
+	set visibleRatio(value) {
+		if (value >= 1.0) {
+			this.visibleCharacters = -1;
+		} else {
+			const total = this._text.reduce((sum, line) => {
+				return sum + line.length;
+			}, 0);
+			this.visibleCharacters = Math.floor(value * total);
+		}
+		this.isDirty = true;
+	}
+
 	/**
 	 * update the bounding box for this Text, accounting for textAlign and textBaseline.
 	 * @param {boolean} [absolute=true] - update in absolute coordinates
@@ -382,6 +424,18 @@ export default class Text extends Renderable {
 	 * @param {CanvasRenderer|WebGLRenderer} renderer - Reference to the destination renderer instance
 	 */
 	draw(renderer) {
+		// re-render the canvas texture when visibleCharacters changes
+		if (this.isDirty && this.visibleCharacters !== -1) {
+			this.canvasTexture.invalidate(renderer);
+			this.canvasTexture.clear();
+			this._drawFont(
+				this.canvasTexture.context,
+				this._text,
+				this.pos.x - this.metrics.x,
+				this.pos.y - this.metrics.y,
+			);
+		}
+
 		// adjust x,y position based on the bounding box
 		let x = this.metrics.x;
 		let y = this.metrics.y;
@@ -402,8 +456,20 @@ export default class Text extends Renderable {
 	_drawFont(context, text, x, y) {
 		setContextStyle(context, this);
 
+		let remaining = this.visibleCharacters;
+
 		for (let i = 0; i < text.length; i++) {
-			const string = text[i].trimEnd();
+			let string = text[i].trimEnd();
+
+			// limit visible characters if needed
+			if (remaining !== -1) {
+				if (remaining <= 0) {
+					break;
+				}
+				string = string.substring(0, remaining);
+				remaining -= string.length;
+			}
+
 			// draw the string
 			if (this.fillStyle.alpha > 0) {
 				context.fillText(string, x, y);

packages/melonjs/src/tweens/tween.ts

@@ -61,6 +61,7 @@ export default class Tween {
 	_yoyo: boolean;
 	_reversed: boolean;
 	_delayTime: number;
+	_repeatDelayTime: number;
 	_startTime: number | null;
 	_easingFunction: EasingFunction;
 	_interpolationFunction: InterpolationFunction;
@@ -117,6 +118,7 @@ export default class Tween {
 		this._yoyo = false;
 		this._reversed = false;
 		this._delayTime = 0;
+		this._repeatDelayTime = 0;
 		this._startTime = null;
 		this._easingFunction = Easing.Linear.None;
 		this._interpolationFunction = Interpolation.Linear;
@@ -224,6 +226,7 @@ export default class Tween {
 	 * @param [options.delay] - delay before starting, in milliseconds
 	 * @param [options.yoyo] - bounce back to original values when finished (use with `repeat`)
 	 * @param [options.repeat] - number of times to repeat (use `Infinity` for endless loops)
+	 * @param [options.repeatDelay] - delay in milliseconds before each repeat cycle
 	 * @param [options.interpolation] - interpolation function for array values
 	 * @param [options.autoStart] - start the tween immediately without calling `start()`
 	 * @returns this instance for object chaining
@@ -236,6 +239,7 @@ export default class Tween {
 			yoyo?: boolean | undefined;
 			repeat?: number | undefined;
 			delay?: number | undefined;
+			repeatDelay?: number | undefined;
 			interpolation?: InterpolationFunction | undefined;
 			autoStart?: boolean | undefined;
 		},
@@ -258,6 +262,9 @@ export default class Tween {
 			if (options.delay !== undefined) {
 				this.delay(options.delay);
 			}
+			if (options.repeatDelay !== undefined) {
+				this.repeatDelay(options.repeatDelay);
+			}
 			if (options.interpolation !== undefined) {
 				this.interpolation(options.interpolation);
 			}
@@ -347,6 +354,16 @@ export default class Tween {
 		return this;
 	}
 
+	/**
+	 * Set a delay before each repeat.
+	 * @param amount - delay in milliseconds before each repeat cycle
+	 * @returns this instance for object chaining
+	 */
+	repeatDelay(amount: number) {
+		this._repeatDelayTime = amount;
+		return this;
+	}
+
 	/**
 	 * Allows the tween to bounce back to their original value when finished.
 	 * To be used together with repeat to create endless loops.
@@ -507,7 +524,7 @@ export default class Tween {
 					this._reversed = !this._reversed;
 				}
 
-				this._startTime = time + this._delayTime;
+				this._startTime = time + (this._repeatDelayTime || this._delayTime);
 
 				return true;
 			} else {