# Text Styling Documentation

The macroquad renderer provides the `text-styling` feature flag, which enables the use of a custom styling sytax.

## Syntax & Formatting
Styles are applied using tags enclosed in `{` and `|` and closed with `}`.
* **Format:** `{tag_param=value|Styled Text}`
* **Important:** Do not use spaces between parameters. Use **underscores** `_` as separators (e.g., `{wave_f=0.5_a=0.3|...}`) to avoid bad word breaks.
* **Stacking:** Multiple tags can be stacked. Inner tags overwrite outer tags if they conflict.
* **Escaping:** Use `\` to escape `{`, `|`, `}`, or `\` itself.

---

## Categories

**Properties**

Static attributes applied to the text block. These set specific values like **color** or **opacity**.

**Effects**

Effects applied **individually to each character**. These create movement or visual effects.

**Animations**

Time-based transitions (entry or exit) tracked via a unique `id`. These cause text to appear or disappear.

---

## Processing Order & Priority
When multiple tags are active, they are processed in this strict order:

1.  **Hide** (Effect)
2.  **Type** (Animation)
3.  **Fade** (Animation)
4.  **Scale** (Animation)
5.  **Transform** (Effect)
6.  **Wave** (Effect)
7.  **Pulse** (Effect)
8.  **Swing** (Effect)
9.  **Jitter** (Effect)
10. **Gradient** (Effect)
11. **Opacity** (Property)
12. **Color** (Property)
13. **Shadow** (Effect)

---

## Properties Reference

**color**

Sets the fill color of the text.
* **Parameter:** `color=VALUE` (Hex code `#RRGGBB`, `(r,g,b)`, or named color)
* **Supported Names:** White, Black, LightGray, DarkGray, Red, Orange, Yellow, Lime, Green, Cyan, LightBlue, Blue, Purple, Magenta, Brown, Pink. Case insensitive.
Example: `{color=red|Red Text}`

**opacity**

Sets the transparency of the text.
* **Parameter:** `opacity=FLOAT` (0.0 to 1.0)
Example: `{opacity=0.5|50% Transparent Text}`

---

## Effects Reference

**transform**

Applies static geometric transformations to characters.
* `translate=X,Y`: Pixel offset ratio relative to font size. **Def:** 0,0
* `scale=X,Y`: Size multiplier. One value applies to both axes. **Def:** 1.0
* `rotate=DEGREES`: Clockwise rotation. **Def:** 0

**wave**

Vertical sine wave movement.
* `w=FLOAT`: Wavelength in characters. **Def:** 3
* `f=FLOAT` **OR** `s=FLOAT`: Frequency (bobs/sec) or Speed (chars/sec). **Def:** f=0.5
* `a=FLOAT`: Amplitude (pixel ratio to font size). **Def:** 0.3
* `p=FLOAT`: Phase offset (0-1). **Def:** 0
* `r=FLOAT`: Rotation of the movement vector in degrees. **Def:** 0

**swing**

Rotational sine wave (pendulum motion).
* `w=FLOAT`: Wavelength in characters. **Def:** 3
* `f=FLOAT` **OR** `s=FLOAT`: Frequency (swings/sec) or Speed (chars/sec). **Def:** f=0.5
* `a=FLOAT`: Amplitude in degrees. **Def:** 8
* `p=FLOAT`: Phase offset (0-1). **Def:** 0

**pulse**

Sine wave scaling (growing and shrinking).
* `w=FLOAT`: Wavelength in characters. **Def:** 2
* `f=FLOAT` **OR** `s=FLOAT`: Frequency (cycles/sec) or Speed (chars/sec). **Def:** f=0.6
* `a=FLOAT`: Amplitude size multiplier. **Def:** 0.15
* `p=FLOAT`: Phase offset (0-1). **Def:** 0

**jitter**

Randomized character offset within an ellipse.
* `radii=X,Y`: Maximum offset distance (ratio to font size). **Def:** 0.5,0.5
* `rotation=DEGREES`: Rotation of the jitter ellipse.

**shadow**

Renders a duplicate character behind the text.
* `color=COLOR`: Shadow color. **Def:** Black
* `offset=X,Y`: Pixel offset ratio. **Def:** -0.3,0.3
* `scale=X,Y`: Shadow size multiplier. **Def:** 1.0

**gradient**

Cycles colors across the text.
* `stops=POS:COLOR,POS:COLOR...`: List of anchor points. Positions are character indices. **Def:** Rainbow
* `speed=FLOAT`: Speed in chars/sec. **Def:** 1

**hide**

Prevents the text from rendering completely.
* No parameters.

---

## Animations Reference
*All animations require a unique `id` parameter.*

**type**

Typing writer effect. Characters appear sequentially, left to right.
* `MODE`: `in` or `out`.
* `id=WORD`: Unique tracking identifier.
* `speed=FLOAT`: Characters per second. **Def:** 8
* `delay=FLOAT`: Delay in seconds before starting. **Def:** 0
* `cursor=CHAR`: Cursor character to display while typing. **Def:** none
Example: `{type_in_id=foo_cursor=\||Text to type}`

**fade**

Opacity transition, left to right.
* `MODE`: `in` or `out`.
* `id=WORD`: Unique tracking identifier.
* `speed=FLOAT`: Characters per second. **Def:** 3
* `trail=FLOAT`: Length of the fade gradient in characters. **Def:** 3
* `delay=FLOAT`: Delay in seconds before starting. **Def:** 0
Example: `{fade_out_id=bar_speed=5|Fade this text out quickly}`

**scale**

Size transition (pop-in/pop-out), left to right.
* `MODE`: `in` or `out`.
* `id=WORD`: Unique tracking identifier.
* `speed=FLOAT`: Characters per second. **Def:** 3
* `trail=FLOAT`: Length of the scaling gradient in characters. **Def:** 3
* `delay=FLOAT`: Delay in seconds before starting. **Def:** 0
Example: `{scale_in_id=buzz_speed=0.1_tail=10|Characters become bigger reaaaaaaaaaaaaaally slowly}`