Working with Text chapter

Author: x87

astro.config.mjs

@@ -92,6 +92,17 @@ export default defineConfig({
 						{ label: 'Negating Conditions', slug: 'negating-conditions' },
 						{ label: 'Multiple Conditions', slug: 'multiple-conditions' },
 					],
+				},
+				{
+					label: "Chapter IV: Working with Text",
+					items: [
+						{label: 'Text Types', slug: 'text-types'},
+						{label: 'Basic Messages', slug: 'basic-messages'},
+						{label: 'Formatted Messages', slug: 'formatted-messages'},
+						{label: 'Text Draws', slug: 'text-draws'},
+						{label: 'Debug Messages', slug: 'debug-messages'},
+						
+					]
 				}
 			],
 		}),

public/img/ch-04-01.png

@@ -0,0 +1,21 @@
+---
+title: Text Types
+description: Displaying text messages on the screen
+slug: text-types
+---
+
+Text messages play an important role in many scripts. They can appear as part of the user interface, for example, in menus, or serve as subtitles, gameplay instructions, or debugging information.
+
+The game provides several built-in methods for displaying text on screen:
+
+- [Help box](/basic-messages#help-boxes) – a small black rectangle in the top-left corner, often used to provide contextual help
+
+- [Mission text](/basic-messages#mission-text) – large, centered, or bottom-screen text, typically used for mission objectives or subtitles.
+
+- [Text Draw](/text-draws) – short text elements displayed at specific coordinates, commonly used for showing information such as player position or debug values.
+
+CLEO 5 introduces an additional display type: the yellow [trace message](/debug-messages), shown on the left side of the screen. It is especially useful for debugging and logging script behavior.
+
+Most text messages remain visible for a fixed duration — from a single frame to several seconds — though they can also be shown repeatedly in a loop to stay visible longer.
+
+

public/img/ch-04-02.png

@@ -0,0 +1,65 @@
+---
+title: Basic Messages
+description: Showing different types of messages
+slug: basic-messages
+tableOfContents: true
+---
+
+## Help Boxes
+
+In the base game, text commands require a GXT key - an 8-character string referencing one of the predefined text entries in the active GXT file (for example, `american.gxt` when the game language is set to English).
+
+For example, to display a help box with the text 'San Andreas', you need to use the command `PRINT_HELP` with the key `'SAN_AND'`:
+
+```sb
+PRINT_HELP {key} 'SAN_AND'
+```
+
+<img src="/img/ch-04-01.png" alt="Help box example" />
+
+:::tip
+How one could find what key refers to what text? There is an online tool
+that lets you navigate all standard game messages and their keys:
+https://public.sannybuilder.com/GXT/search/?game=SA%20PC. It supports all
+available languages and can work with user-provided GXT files.
+:::
+
+Sometimes you need custom text that doesn’t exist in the original GXT files. There are two easy ways to do this:
+
+1. CLEO supports custom text dictionary format called `FXT`, which allows you to define new keys and messages without having to edit GXT files. FXT files are loaded automatically from the `CLEO_TEXT` folder.
+
+Each FXT file contains a list of plain text entries in the following format:
+
+```
+<KEY> <TEXT>
+```
+
+2. Use CLEO commands that accept strings directly, without using a GXT key. For example, to display the same help box use:
+
+```sb
+PRINT_HELP_STRING {text} "San Andreas"
+```
+
+Notice that because the text is longer than 8 characters, you need to use double quotes.
+
+## Mission Text
+
+Here is some other message commands and their CLEO counterpart:
+
+**PRINT_NOW**
+
+| Native Command                                        | CLEO Command                                            |
+| ----------------------------------------------------- | ------------------------------------------------------- |
+| `PRINT_NOW {key} 'SAN_AND' {duration} 3000 {style} 1` | `PRINT_STRING_NOW {text} "San Andreas" {duration} 3000` |
+
+<img src="/img/ch-04-02.png" alt="PRINT_NOW Example" />
+
+**PRINT_BIG**
+
+| Native Command                                        | CLEO Command                                                      |
+| ----------------------------------------------------- | ----------------------------------------------------------------- |
+| `PRINT_BIG {key} 'SAN_AND' {duration} 3000 {style} 1` | `PRINT_BIG_STRING {text} "San Andreas" {duration} 3000 {style} 1` |
+
+<img src="/img/ch-04-03.png" alt="PRINT_BIG Example" />
+
+To find more information about each command and different styles, visit [the Text class](https://library.sannybuilder.com/#/sa/script/classes/Text) in Sanny Builder Library.

public/img/ch-04-03.png

@@ -0,0 +1,47 @@
+---
+title: Formatted Messages
+description: Showing different types of formatting
+slug: formatted-messages
+tableOfContents: true
+---
+
+## Native Formatting
+
+The game allows the use of special tokens to highlight different parts of text. They usually appear like a specific character surrounded by `~`, e.g. `~b~` or `~y~`. [This page](https://gtamods.com/wiki/GXT#Symbols_and_colors) describes each token in detail.
+
+For example, the GXT key `STOCK` references the message `~r~out of stock` (`~r~` means red), which in the game looks like this:
+
+```sb
+PRINT_HELP {key} 'STOCK'
+```
+
+<img src="/img/ch-04-04.png" alt="Help box with red text" />
+
+Some messages include placeholders for numbers, represented as ~1~. Regardless of their position and total number of placeholders, the token is always ~1~.
+
+For example, the message displayed when you pick up a horseshoe is `Horseshoes ~1~ out of ~1~`, referenced by the key HO_ONE. To display it in the game, use one of the commands that include `WITH_NUMBER` in it. For two numbers, for example, use `PRINT_WITH_2_NUMBERS_NOW` or `PRINT_WITH_2_NUMBERS_BIG`:
+
+```sb
+PRINT_WITH_2_NUMBERS_BIG {key} 'HO_ONE' {num1} 5 {num2} 50 {duration} 3000 {style} 1
+```
+
+<img src="/img/ch-04-05.png" alt="Formatted message with two numbers" />
+
+## CLEO Formatting
+
+CLEO supports C++-like inline formatting with placeholders that can be replaced with actual values at runtime. The syntax is similar to C++'s `printf` function. These commands have [`FORMATTED`](https://library.sannybuilder.com/#/sa/script?q=print%20formatted) in their name. For example, the following command would display the same message as above.
+
+```sb
+PRINT_BIG_FORMATTED  {format} "Horseshoes %d out of %d" {time} 3000 {style} 1 {args} 5 50
+```
+
+You can combine native and CLEO formatting for richer visual effects:
+
+```sb
+PRINT_BIG_FORMATTED  {format} "~r~Horseshoes %d out of %d" {time} 3000 {style} 1 {args} 5 50
+```
+
+<img
+	src="/img/ch-04-06.png"
+	alt="CLEO Formatted message with two numbers in red"
+/>