Fonts.md

@@ -29,4 +29,48 @@ This configuration creates a font named `custom-font` for use in text [Assets](/
 
 ## Spritesheet
 The sprite sheet for a font is considered a grid of character tiles sized `height` x `height`.  The above example would be a 32px by 32px sheet made of 8px square characters, for example.
-Sprite sheet textures do not have to be square, but do have to have exact resolution measurements to be read correctly.  If textures load but seem misshapen or offset, it is likely a sprite-sheet resolution issue.
\ No newline at end of file
+Sprite sheet textures do not have to be square, but do have to have exact resolution measurements to be read correctly.  If textures load but seem misshapen or offset, it is likely a sprite-sheet resolution issue.
+
+### Animation Example
+This is a complex example walking through how to utilize a custom MythicHUD font to turn various Unicode characters into image frames for stop-motion animation.\
+These Unicode frames are being delivered via a PlaceholderAPI placeholder, which is being managed and animated by a third-party software solution.\
+MythicHUD can display those unicodes as frames of animation through displaying the PAPI text as a custom font.
+
+This is an example `/MythicHUD/assets/hud/` animated asset:
+```yaml
+anim:
+  layers:
+    display:
+      text: "%icon_sparkle%"
+      font: "sparkle"
+      outlined: false
+      align: center
+      offset:
+        x: 0
+        y: 0
+```
+It would utilize the `/MythicHUD/assets/font/` custom font:
+```yaml
+sparkle:
+  providers:
+    spaces:
+      type: "space"
+      advances:
+        " ": 4
+        "\u200c": 0
+    ascii:
+      type: "bitmap"
+      texture: font/sparkles.png
+      height: 12
+      chars:
+        - "\u8080\u8081\u8082\u8083\u8084"
+        - "\u8085\u8086\u8087\u8088\u8089"
+```
+This font is sourced from a 60x24px image at `/MythicHUD/textures/font/sparkles.png`, and displays 10 12px-square sprites in two rows of 5.
+
+The PAPI placeholder `%icon_sparkle%` is then delivering unicodes `\u8080` - `\u8089` in sequence to play back those frames as animation.
+
+<details open>
+  <summary>Animation Tip!</summary>
+MythicHUD's config determines the framerate it updates HUDs for players - for example, an update rate of 4 ticks per update out of 20 ticks per second is an animation playback of 5fps. Keep this in mind when planning animation frames and playback speed.
+</details>
\ No newline at end of file