pxt-common-packages 9.4.3 → 9.4.7

package/libs/game/docs/reference/scene/set-tile-at.md

@@ -3,15 +3,15 @@
 Set a tile at a location in the tilemap.
 
 ```sig
-tiles.setTileAt(null, tiles.getTileLocation(0, 0))
+tiles.setTileAt(tiles.getTileLocation(0, 0), null)
 ```
 
 You can set a tile at a specific column and row in the tilemap using a tile location object. Specify a tile to set in the tilemap and a location for it.
 
 ## Parameters
 
-* **tile**: the to set in the tilemap.
 * **loc**: a tile location in the tilemap.
+* **tile**: the to set in the tilemap.
 
 ## Example #example
 

package/libs/game/docs/reference/scene/tile-at-location-equals.md

@@ -3,7 +3,7 @@
 Check if a location in the tilemap contains the tile you're looking for.
 
 ```sig
-tiles.tileAtLocationEquals(location, null)
+tiles.tileAtLocationEquals(tiles.getTileLocation(0, 0), null)
 ```
 
 ## Parameters

package/libs/game/docs/reference/sprites/sprite/ax.md

@@ -36,13 +36,15 @@ mySprite.ax = 0
 
 * **value**: the new horizontal acceleration for the sprite in pixels per second, per second.
 
-## Sprite acceleration
+## Sprite horizontal acceleration
 
-Acceleration of a sprite makes it speed up or slow down. The value for acceleration determines how quickly the speed  of the sprite will change. A positive value makes the sprite speed up as it moves. A negative value causes the sprite to slow down while it moves.
+The value for acceleration determines how quickly the speed of the sprite will change. Acceleration of a sprite makes it speed up in a direction toward the right or left. A positive value causes the sprite's speed in the `right` direction to increase. A negative value causes the sprite's speed in the `left` direction to increase.
+
+Acceleration can be used as an opposing force too. If a sprite is travelling toward the right at a certain speed and a negative horizontal acceleration is applied, the sprite will keep moving to the right but it will slow down. When the sprite's speed reaches `0`, the sprite will begin to move to the left.
 
 ### ~ hint
 
-**How speed changes**
+#### How speed changes
 
 Speed, or velocity, is how much distance an object moves during some period of time. Distance in your game is measured in pixels so the speed of a sprite is in _pixels per second_. Speed is changed by _accelerating_ an object. In your game, a sprite is accelerated by some amount of change in speed per second. So, acceleration is measured in _pixels per second per second_.
 
@@ -131,6 +133,35 @@ game.onUpdateInterval(1000, function () {
 })
 ```
 
+### Opposite force #ex3
+
+Make a sprite move from the left side of the screen to the right side. Apply acceleration in the opposite direction to slow the sprite down and send back to the left.
+
+```blocks
+let mySprite = sprites.create(img`
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . 5 5 5 5 5 5 . . . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . . . 5 5 5 5 5 5 . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    `, SpriteKind.Player)
+mySprite.setStayInScreen(true)
+mySprite.left = 0
+mySprite.vx = 100
+mySprite.ax = -35
+```
+
 ## See also #seealso
 
 [ay](/reference/sprites/sprite/ay),

package/libs/game/docs/reference/sprites/sprite/ay.md

@@ -36,13 +36,16 @@ mySprite.ay = 0
 
 * **value**: the new vertical acceleration for the sprite in pixels per second, per second.
 
-## Sprite acceleration
+## Sprite vertical acceleration
+
+The value for acceleration determines how quickly the speed of the sprite will change. Acceleration of a sprite makes it speed up in a direction toward the bottom or top. A positive value causes the sprite's speed in the `bottom` direction to increase. A negative value causes the sprite's speed in the `top` direction to increase.
+
+Acceleration can be used as an opposing force too. If a sprite is travelling toward the bottom at a certain speed and a negative vertical acceleration is applied, the sprite will keep moving to the bottom but it will slow down. When the sprite's speed reaches `0`, the sprite will begin to move to the top.
 
-Acceleration of a sprite makes it speed up or slow down. The value for acceleration determines how quickly the speed  of the sprite will change. A positive value makes the sprite speed up as it moves. A negative value causes the sprite to slow down while it moves.
 
 ### ~ hint
 
-**How speed changes**
+#### How speed changes
 
 Speed, or velocity, is how much distance an object moves during some period of time. Distance in your game is measured in pixels so the speed of a sprite is in _pixels per second_. Speed is changed by _accelerating_ an object. In your game, a sprite is accelerated by some amount of change in speed per second. So, acceleration is measured in _pixels per second per second_.
 
@@ -129,6 +132,34 @@ game.onUpdateInterval(1000, function () {
     interval += 1
 })
 ```
+### Opposite force #ex3
+
+Make a sprite move from the top of the screen to the bottom. Apply acceleration in the opposite direction to slow the sprite down and send back to the top.
+
+```blocks
+let mySprite = sprites.create(img`
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . 5 5 5 5 5 5 . . . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . . . 5 5 5 5 5 5 . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    `, SpriteKind.Player)
+mySprite.setStayInScreen(true)
+mySprite.top = 0
+mySprite.vy = 80
+mySprite.ay = -35
+```
 
 ## See also #seealso
 

package/libs/game/docs/reference/sprites/sprite/fx.md

@@ -0,0 +1,123 @@
+# fy (property)
+
+Get or set the friction opposing a sprite's motion in the vertical direction.
+
+## Get
+
+Get the vertical friction on the sprite.
+
+```block
+let mySprite: Sprite = null
+
+let horzAccel = mySprite.fy
+```
+
+```typescript-ignorelet
+horzAccel = mySprite.fy
+```
+
+### Returns
+
+* a [number](/types/number) that is the current vertical friction of the sprite.
+
+## Set
+
+Set the vertical friction for the sprite.
+
+```block
+let mySprite: Sprite = null
+
+mySprite.fy = 0
+```
+
+```typescript-ignore
+mySprite.fy = 0
+```
+
+### Parameter
+
+* **value**: the new vertical friction opposing the sprite's motion in pixels per second, per second.
+
+## Sprite vertical friction
+
+Friction is an opposing force against the motion of a sprite. If a sprite has a vertical velocity (`vy`), it's friction will slow the sprite down until it's vertical velocity becomes `0`. This is similar to setting an opposite vertical acceleration but the opposite acceleration goes away once the sprite stops.
+
+## Examples #example
+
+### Measure stopping time #ex1
+
+Move the sprite from top to bottom across the screen. Use the correct amount of friction (`fy`) to make the sprite stop at `3` seconds.
+
+```blocks
+let stopTime = 0
+let counting = true
+let mySprite = sprites.create(img`
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . 5 5 5 5 5 5 . . . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . . . 5 5 5 5 5 5 . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    `, SpriteKind.Player)
+mySprite.setStayInScreen(true)
+mySprite.top = 0
+mySprite.fy = 20
+mySprite.vy = 60
+game.onUpdateInterval(100, function () {
+    if (counting) {
+        stopTime += 0.1
+        if (mySprite.vy == 0) {
+            counting = false
+            mySprite.sayText("" + stopTime + "sec", 5000, false)
+        }
+    }
+})
+```
+
+### Skipppng sprite #ex2
+
+Make a sprite move from the top to the bottom. Make it skip to the right once every second.
+
+```blocks
+let mySprite = sprites.create(img`
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . 5 5 5 5 5 5 . . . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . . . 5 5 5 5 5 5 . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    `, SpriteKind.Player)
+mySprite.setStayInScreen(true)
+mySprite.top = 0
+mySprite.fy = 60
+mySprite.vy = 60
+for (let index = 0; index < 3; index++) {
+    mySprite.vy = 60
+    pause(1000)
+}
+```
+
+## See also #seealso
+
+[fx](/reference/sprites/sprite/fx),
+[ay](/reference/sprites/sprite/ay)

package/libs/game/docs/reference/sprites/sprite/fy.md

@@ -0,0 +1,123 @@
+# fy (property)
+
+Get or set the friction opposing a sprite's motion in the horizontal direction.
+
+## Get
+
+Get the horizontal friction on the sprite.
+
+```block
+let mySprite: Sprite = null
+
+let horzAccel = mySprite.fx
+```
+
+```typescript-ignorelet
+horzAccel = mySprite.fx
+```
+
+### Returns
+
+* a [number](/types/number) that is the current horizontal friction of the sprite.
+
+## Set
+
+Set the horizontal friction for the sprite.
+
+```block
+let mySprite: Sprite = null
+
+mySprite.fx = 0
+```
+
+```typescript-ignore
+mySprite.fx = 0
+```
+
+### Parameter
+
+* **value**: the new horizontal friction opposing the sprite's motion in pixels per second, per second.
+
+## Sprite horizontal friction
+
+Friction is an opposing force against the motion of a sprite. If a sprite has a horizontal velocity (`vx`), it's friction will slow the sprite down until it's horizontal velocity becomes `0`. This is similar to setting an opposite horizontal acceleration but the opposite acceleration goes away once the sprite stops.
+
+## Examples #example
+
+### Measure stopping time #ex1
+
+Move the sprite from left to right across the screen. Use the correct amount of friction (`fx`) to make the sprite stop at `3` seconds.
+
+```blocks
+let stopTime = 0
+let counting = true
+let mySprite = sprites.create(img`
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . 5 5 5 5 5 5 . . . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . . . 5 5 5 5 5 5 . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    `, SpriteKind.Player)
+mySprite.setStayInScreen(true)
+mySprite.left = 0
+mySprite.fx = 30
+mySprite.vx = 90
+game.onUpdateInterval(100, function () {
+    if (counting) {
+        stopTime += 0.1
+        if (mySprite.vx == 0) {
+            counting = false
+            mySprite.sayText("" + stopTime + "sec", 5000, false)
+        }
+    }
+})
+```
+
+### Skipppng sprite #ex2
+
+Make a sprite move from the left to the right. Make it skip to the right once every second.
+
+```blocks
+let mySprite = sprites.create(img`
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . 5 5 5 5 5 5 . . . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . 5 5 5 5 5 5 5 5 5 5 5 5 . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . 5 5 5 5 5 5 5 5 5 5 . . . 
+    . . . . . 5 5 5 5 5 5 . . . . . 
+    . . . . . . . . . . . . . . . . 
+    . . . . . . . . . . . . . . . . 
+    `, SpriteKind.Player)
+mySprite.setStayInScreen(true)
+mySprite.left = 0
+mySprite.fx = 80
+mySprite.vx = 80
+for (let index = 0; index < 3; index++) {
+    mySprite.vx = 80
+    pause(1000)
+}
+```
+
+## See also #seealso
+
+[fy](/reference/sprites/sprite/fy),
+[ax](/reference/sprites/sprite/ax)

package/libs/game/docs/reference/sprites.md

@@ -58,6 +58,8 @@ sprites.onOverlap(0, 0, function (sprite, otherSprite) {})
 * [**vy- velocity y**](/reference/sprites/sprite/vy)
 * [**ax - acceleration x**](/reference/sprites/sprite/ax)
 * [**ay - acceleration y**](/reference/sprites/sprite/ay)
+* [**fx - friction x**](/reference/sprites/sprite/fx)
+* [**fy - friction y**](/reference/sprites/sprite/fy)
 
 ### Image and Attributes
 

package/libs/game/hitbox.ts

@@ -1,21 +1,19 @@
 namespace game {
     export class Hitbox {
-        img: Image;
-        rev: number;
+        hash: Fx8;
         parent: Sprite;
         ox: Fx8;
         oy: Fx8;
         width: Fx8;
         height: Fx8;
 
-        constructor(parent: Sprite, width: number, height: number, ox: number, oy: number) {
-            this.img = parent.image;
-            this.rev = parent.image.revision();
+        constructor(parent: Sprite, width: Fx8, height: Fx8, ox: Fx8, oy: Fx8) {
+            this.hash = parent.calcDimensionalHash();
             this.parent = parent;
-            this.width = Fx8(width);
-            this.height = Fx8(height);
-            this.ox = Fx8(ox);
-            this.oy = Fx8(oy);
+            this.width = width;
+            this.height = height;
+            this.ox = ox;
+            this.oy = oy;
         }
 
         get left() {
@@ -41,7 +39,23 @@ namespace game {
         }
 
         isValid() {
-            return this.img === this.parent.image && this.rev === this.parent.image.revision();
+            return this.hash === this.parent.calcDimensionalHash();
+        }
+
+        contains(x: Fx8, y: Fx8): boolean {
+            return (x >= this.left) && (x <= this.right) && (y >= this.top) && (y <= this.bottom);
+        }
+
+        overlapsWith(other: Hitbox): boolean {
+            if (this.contains(other.left, other.top)) return true;
+            if (this.contains(other.left, other.bottom)) return true;
+            if (this.contains(other.right, other.top)) return true;
+            if (this.contains(other.right, other.bottom)) return true;
+            if (other.contains(this.left, this.top)) return true;
+            if (other.contains(this.left, this.bottom)) return true;
+            if (other.contains(this.right, this.top)) return true;
+            if (other.contains(this.right, this.bottom)) return true;
+            return false;
         }
     }
 
@@ -51,24 +65,28 @@ namespace game {
             return s._hitbox;
 
         const i = s.image;
-        let minX = i.width;
-        let minY = i.height;
-        let maxX = 0;
-        let maxY = 0;
+        let minX = Fx8(i.width);
+        let minY = Fx8(i.height);
+        let maxX = Fx.zeroFx8;
+        let maxY = Fx.zeroFx8;
 
-        for (let c = 0; c < i.width; c++) {
-            for (let r = 0; r < i.height; r++) {
+        for (let c = 0, fxc = Fx.zeroFx8; c < i.width; c++, fxc = Fx.add(fxc, Fx.oneFx8)) {
+            for (let r = 0, fxr = Fx.zeroFx8; r < i.height; r++, fxr = Fx.add(fxr, Fx.oneFx8)) {
                 if (i.getPixel(c, r)) {
-                    minX = Math.min(minX, c);
-                    minY = Math.min(minY, r);
-                    maxX = Math.max(maxX, c);
-                    maxY = Math.max(maxY, r);
+                    minX = Fx.min(minX, fxc);
+                    minY = Fx.min(minY, fxr);
+                    maxX = Fx.max(maxX, fxc);
+                    maxY = Fx.max(maxY, fxr);
                 }
             }
         }
 
-        const width = maxX - minX + 1;
-        const height = maxY - minY + 1;
+        minX = Fx.mul(minX, s._sx);
+        minY = Fx.mul(minY, s._sy);
+        maxX = Fx.mul(maxX, s._sx);
+        maxY = Fx.mul(maxY, s._sy);
+        const width  = Fx.add(Fx.sub(maxX, minX), Fx.oneFx8);
+        const height = Fx.add(Fx.sub(maxY, minY), Fx.oneFx8);
 
         return new Hitbox(s, width, height, minX, minY);
     }

package/libs/game/renderText.ts

@@ -61,6 +61,8 @@ namespace sprites {
         }
 
         calculatePartialHeight(startLine: number, lengthToDraw: number) {
+            if (this.linebreaks.length === 0) return this.font.charHeight;
+
             let current = 0;
 
             for (let i = startLine; i < this.linebreaks.length + 1; i++) {
@@ -93,9 +95,9 @@ namespace sprites {
             return total;
         }
 
-        protected lineEnd(index: number) {
-            const prevEnd = index > 0 ? this.linebreaks[index - 1] : 0;
-            let end = index < this.linebreaks.length ? this.linebreaks[index] : this.text.length;
+        lineEnd(lineIndex: number) {
+            const prevEnd = lineIndex > 0 ? this.linebreaks[lineIndex - 1] : 0;
+            let end = lineIndex < this.linebreaks.length ? this.linebreaks[lineIndex] : this.text.length;
             let didMove = false;
 
             // Trim trailing whitespace
@@ -115,8 +117,8 @@ namespace sprites {
             return didMove ? end + 1 : end;
         }
 
-        protected lineStart(index: number) {
-            let start = index > 0 ? this.linebreaks[index - 1] : 0;
+        lineStart(lineIndex: number) {
+            let start = lineIndex > 0 ? this.linebreaks[lineIndex - 1] : 0;
 
             // Trim leading whitespace
             while (start < this.text.length) {
@@ -133,6 +135,29 @@ namespace sprites {
 
             return start;
         }
+
+        widthOfLine(lineIndex: number, fullTextOffset?: number) {
+            if (fullTextOffset != undefined) {
+                return (Math.min(this.lineEnd(lineIndex), fullTextOffset + 1) - this.lineStart(lineIndex)) * this.font.charWidth;
+            }
+            return (this.lineEnd(lineIndex) - this.lineStart(lineIndex)) * this.font.charWidth;
+        }
+
+        widthOfLines(lineStartIndex: number, lineEndIndex: number, offset?: number) {
+            if (this.linebreaks.length === 0) return this.widthOfLine(0, offset);
+
+            let width = 0;
+            let fullTextOffset: number;
+            for (let i = lineStartIndex; i < Math.min(lineEndIndex, this.linebreaks.length + 1); i++) {
+                if (offset != undefined) {
+                    fullTextOffset = this.lineStart(i) + offset;
+                    offset -= this.lineEnd(i) - this.lineStart(i);
+                }
+                if (fullTextOffset !== undefined && this.lineStart(i) > fullTextOffset) break;
+                width = Math.max(width, this.widthOfLine(i, fullTextOffset));
+            }
+            return width;
+        }
     }
 
 
@@ -203,6 +228,9 @@ namespace sprites {
         protected pageLine: number;
         protected timer: number;
         protected pauseMillis: number;
+        protected onTickCB: () => void;
+        protected onEndCB: () => void;
+        protected prevOffset: number;
 
         constructor(public text: RenderText, public height: number) {
             this.state = RenderTextAnimationState.Idle;
@@ -232,17 +260,21 @@ namespace sprites {
         }
 
         currentHeight() {
-            const maxHeight = Math.min(
-                Math.idiv(this.height, this.text.lineHeight()) + 1,
-                this.text.linebreaks.length + 1 - this.pageLine
-            ) * this.text.lineHeight();
+            const minHeight = this.text.lineHeight();
+            const maxHeight = Math.max(
+                Math.min(
+                    Math.idiv(this.height, this.text.lineHeight()) + 1,
+                    this.text.linebreaks.length + 1 - this.pageLine
+                ) * this.text.lineHeight(),
+                minHeight
+            );
 
 
             if (this.state === RenderTextAnimationState.Printing) {
-                return Math.min(
+                return Math.max(Math.min(
                     this.text.calculatePartialHeight(this.pageLine, this.currentOffset()),
                     maxHeight
-                );
+                ), minHeight)
             }
             else if (this.state === RenderTextAnimationState.Pausing) {
                 return maxHeight
@@ -252,10 +284,34 @@ namespace sprites {
             }
         }
 
+        currentWidth() {
+            return this.text.widthOfLines(
+                this.pageLine,
+                this.pageLine + Math.idiv(this.currentHeight(), this.text.lineHeight()) + 1,
+                this.state === RenderTextAnimationState.Printing ? this.currentOffset() : undefined
+            );
+        }
+
         currentOffset() {
             return Math.idiv(control.millis() - this.timer, this.tickPeriod)
         }
 
+        isDone() {
+            return this.state === RenderTextAnimationState.Idle;
+        }
+
+        cancel() {
+            this.state = RenderTextAnimationState.Idle;
+        }
+
+        onCharacterPrinted(cb: () => void) {
+            this.onTickCB = cb;
+        }
+
+        onAnimationEnd(cb: () => void) {
+            this.onEndCB = cb;
+        }
+
         draw(canvas: Image, left: number, top: number, color: number) {
             if (this.state === RenderTextAnimationState.Idle) return;
             else if (this.state === RenderTextAnimationState.Printing) {
@@ -269,6 +325,10 @@ namespace sprites {
                     this.pageLine + Math.idiv(this.height, this.text.lineHeight()) + 1
                 );
 
+                if (this.onTickCB && this.prevOffset !== this.currentOffset()) {
+                    this.onTickCB();
+                }
+
                 if (pageFinished) {
                     this.state = RenderTextAnimationState.Pausing;
                     this.timer = this.pauseMillis
@@ -290,6 +350,7 @@ namespace sprites {
                     this.pageLine += Math.idiv(this.height, this.text.lineHeight()) + 1;
                     if (this.pageLine > this.text.linebreaks.length) {
                         this.state = RenderTextAnimationState.Idle;
+                        if (this.onEndCB) this.onEndCB();
                     }
                     else {
                         this.state = RenderTextAnimationState.Printing;
@@ -297,6 +358,8 @@ namespace sprites {
                     }
                 }
             }
+
+            this.prevOffset = this.currentOffset();
         }
     }
 }