add new chapter on loops

Author: x87

astro.config.mjs

@@ -75,7 +75,7 @@ export default defineConfig({
 					],
 				},
 				{
-					label: 'Chapter II: Loops',
+					label: 'Chapter II: Introducing Loops',
 					items: [
 						{ label: 'Variables', slug: 'variables' },
 						{ label: 'WAIT command', slug: 'wait' },
@@ -103,6 +103,16 @@ export default defineConfig({
 						{label: 'Debug Messages', slug: 'debug-messages'},
 
 					]
+				},
+				{
+				label: "Chapter V: Advanced Loops",
+				items: [
+						{ label: 'Constants', slug: 'constants' },
+						{ label: 'FOR Loop', slug: 'for-loop' },
+						{ label: 'REPEAT..UNTIL Loop', slug: 'repeat-until' },
+						{ label: 'Continue and Break', slug: 'continue-break' },
+						{ label: 'Hands-on: Bonus Counter', slug: 'script-bonus-counter' },
+					]
 				}
 			],
 		}),

src/content/docs/ch00/03-sanny-builder.mdx

@@ -4,7 +4,7 @@ description: How to compile and disassemble scripts using Sanny Builder
 slug: sanny-builder
 ---
 
-In essense, a CLEO _script_ is a set of instructions. It's original text form is called _source code_. Sanny Builder is the tool that reads the source and encodes each instruction into a format the game understands. It outputs a binary file, usually with a file extension `.cs` or `.scm`. This process is called _compilation_. The game reads the compiled script and executes the instructions in order, one at a time.
+In essence, a CLEO _script_ is a set of instructions. It's original text form is called _source code_. Sanny Builder is the tool that reads the source and encodes each instruction into a format the game understands. It outputs a binary file, usually with a file extension `.cs` or `.scm`. This process is called _compilation_. The game reads the compiled script and executes the instructions in order, one at a time.
 
 Sanny Builder can be downloaded from [https://sannybuilder.com](https://sannybuilder.com).
 

src/content/docs/ch01/05-comments.mdx

@@ -19,7 +19,13 @@ Or:
 terminate_this_script // End of script
 ```
 
-Block comments start with `/*` and end with `*/`. They can span multiple lines:
+There are two ways to write block comments. The first is using curly braces `{` and `}`:
+
+```sb
+wait {comments here} 0
+```
+
+The second is using `/*` and `*/`, similar to C++. They can span multiple lines:
 
 ```sb
 /*
@@ -34,6 +40,10 @@ Or used in the middle of the code:
 set_time_of_day /* hours */ 12 /* minutes */ 30
 ```
 
+:::note
+`{}` comments may look similar to directives like `{$CLEO .cs}` which we will learn about next. The difference is that directives always start with `{$`. Everything else inside `{}` is treated as a comment.
+:::
+
 Block comments can not be nested. For example, the following code is invalid:
 
 ```sb

src/content/docs/ch02/03-while.mdx

@@ -6,7 +6,7 @@ slug: while
 
 Many things in the game are extended in time or depend on the player feedback. A car driving to a destination, a model file loading from the disk, a button awaiting to be pressed all require a specific condition to become true. Did the car reach the point, was the specific button pressed, is the model available for use? If not, wait and check again later. 
 
-We can validate certain condition continuosly, each frame, or with some delay. To achieve this in the code, a special construct exists: a loop.
+We can validate certain condition continuously, each frame, or with some delay. To achieve this in the code, a special construct exists: a loop.
 
 The most common type of loop is a while loop. It will execute a block of code as long as the condition is true.
 

src/content/docs/ch02/04-while-true.mdx

@@ -6,7 +6,7 @@ slug: while-true
 
 `while true` is an infinite loop. It ends only with the `break` command or when the script is ended (e.g. using `terminate_this_script`).
 
-It is often used to create a main body of a CLEO script, which contantly awaits for a key press to trigger some action.
+It is often used to create a main body of a CLEO script, which constantly awaits for a key press to trigger some action.
 
 ```sb
 while true

src/content/docs/ch04/03-text-draws.mdx src/content/docs/ch04/04-text-draws.mdxsrc/content/docs/ch04/03-text-draws.mdx renamed to src/content/docs/ch04/04-text-draws.mdx

@@ -0,0 +1,59 @@
+---
+title: Constants
+description: Using constants to name fixed values in CLEO scripts
+slug: constants
+---
+
+So far, we've been using raw numbers directly in the code. For example, in the [vehicle spawning script](/script-spawn-vehicle), the model number `415` appeared several times. If you wanted to change the vehicle, you'd have to find and update every occurrence. This is error-prone and makes the code harder to read.
+
+A _constant_ solves this problem. It is a named value that the compiler replaces with the actual value during compilation. Unlike a variable, a constant cannot be changed at runtime.
+
+To declare a constant, use the `const` keyword:
+
+```sb
+const MODEL = 415
+```
+
+Now, `MODEL` can be used anywhere in the code instead of `415`:
+
+```sb
+const MODEL = 415
+
+request_model MODEL
+
+while not has_model_loaded MODEL
+    wait 0
+end
+
+Car vehicle = create_car MODEL at 2488.6963 -1660.1608 13.3359
+mark_model_as_no_longer_needed MODEL
+```
+
+If you decide to switch from a Cheetah to a different car, you only need to update one line.
+
+You can declare multiple constants on a single line, separated by commas:
+
+```sb
+const KEY_F5 = 116, KEY_F6 = 117
+```
+
+Or use a `const..end` block for better readability:
+
+```sb
+const
+    KEY_F5 = 116
+    KEY_F6 = 117
+    BONUS = 100
+end
+```
+
+Constants can hold string values too:
+
+```sb
+const GREETING = "Hello!"
+const GXT_HELP = 'SAN_AND'
+```
+
+:::tip
+Use constants for values that appear more than once or have a non-obvious meaning. A name like `KEY_F5` is much clearer than the raw number `116`.
+:::

src/content/docs/ch05/01-constants.mdx

@@ -0,0 +1,86 @@
+---
+title: FOR Loop
+description: Counting iterations with the FOR loop
+slug: for-loop
+---
+
+In [Chapter II](/while), we learned about the `while` loop which repeats as long as a condition is true. But what if you know exactly how many times you want to repeat something? The `for` loop is designed for exactly that.
+
+## Syntax
+
+```sb
+for <variable> = <start> to <end>
+    <body>
+end
+```
+
+The loop variable starts at `<start>` and increases by `1` after each iteration until it passes `<end>`.
+
+For example, to add money to the player 5 times:
+
+```sb
+int i
+for i = 1 to 5
+    add_score 0 100
+    wait 250
+end
+```
+
+The variable `i` will take values `1`, `2`, `3`, `4`, `5`, and the loop body will execute 5 times. After the loop, the player has $500 more.
+
+## Counting Backwards with DOWNTO
+
+To count in the opposite direction, use `downto` instead of `to`. The loop variable decreases by `1` after each iteration:
+
+```sb
+int i
+for i = 5 downto 1
+    print_formatted_now "Countdown: %d" 1000 i
+    wait 1000
+end
+
+print_string_now "Go!" 2000
+```
+
+This displays `5`, `4`, `3`, `2`, `1` and then `Go!`.
+
+## Custom Step
+
+By default, the loop variable changes by `1` on each iteration. You can change this with the `step` keyword:
+
+```sb
+int i
+for i = 0 to 100 step 10
+    print_formatted_now "Value: %d" 500 i
+    wait 500
+end
+```
+
+This displays `0`, `10`, `20`, `30`, ..., `100`.
+
+`step` works with `downto` as well:
+
+```sb
+int i
+for i = 100 downto 0 step 25
+    print_formatted_now "Value: %d" 500 i
+    wait 500
+end
+```
+
+## Using Constants with FOR
+
+Constants pair nicely with `for` loops to make the code easy to configure:
+
+```sb
+const MAX_ROUNDS = 10
+const REWARD = 50
+
+int round
+for round = 1 to MAX_ROUNDS
+    add_score 0 REWARD
+    wait 500
+end
+```
+
+Changing `MAX_ROUNDS` or `REWARD` at the top of the script instantly adjusts the loop behavior.

src/content/docs/ch05/02-for-loop.mdx

@@ -0,0 +1,66 @@
+---
+title: REPEAT..UNTIL Loop
+description: A loop that always executes at least once
+slug: repeat-until
+---
+
+The `while` loop checks its condition _before_ each iteration. If the condition is false from the start, the body never runs at all. Sometimes that's not what you want -- you need the body to execute at least once, and only then decide whether to keep going.
+
+The `repeat..until` loop does exactly that. It runs the body first, then checks the condition. If the condition is true, the loop stops. If it's false, the loop repeats.
+
+## Syntax
+
+```sb
+repeat
+    <body>
+until <condition>
+```
+
+Compare this with `while`:
+
+| | Checks condition | Guaranteed to run at least once? |
+| --- | --- | --- |
+| `while` | Before each iteration | No |
+| `repeat..until` | After each iteration | Yes |
+
+## Example
+
+Here is a simple `repeat..until` loop that waits for the player to press `F5`:
+
+```sb
+repeat
+    wait 0
+until is_key_pressed 116
+```
+
+The `wait 0` always executes at least once, giving the game a chance to process input before the first check. Compare it with the equivalent `while` version:
+
+```sb
+while not is_key_pressed 116
+    wait 0
+end
+```
+
+Both achieve the same result, but notice how the condition is inverted: `while` needs `not is_key_pressed` (keep going while the key is _not_ pressed), whereas `repeat..until` uses `is_key_pressed` directly (stop when the key _is_ pressed).
+
+## Practical Example
+
+This script counts how many seconds the player waits before pressing `F5`:
+
+```sb
+int seconds = 0
+
+repeat
+    wait 1000
+    seconds += 1
+    print_formatted_now "Waiting... %d seconds" 1000 seconds
+until is_key_pressed 116
+
+print_formatted_now "You waited %d seconds!" 3000 seconds
+```
+
+Because `repeat..until` always runs the body first, the counter starts at `1` even if the player presses `F5` immediately.
+
+:::tip
+Use `repeat..until` when you need the loop body to execute at least once -- for example, displaying a prompt before checking the player's response. Use `while` when the body should be skipped entirely if the condition is already false.
+:::

src/content/docs/ch05/03-repeat-until.mdx

@@ -0,0 +1,71 @@
+---
+title: Continue and Break
+description: Controlling loop execution with Continue and Break
+slug: continue-break
+---
+
+We briefly saw `break` in [Chapter II](/while-true) where it was used to exit an infinite `while true` loop. Let's look at `break` and its counterpart `continue` in more detail.
+
+## Break
+
+The `break` command immediately stops the current loop and moves execution to the first command after the loop:
+
+```sb
+int i
+for i = 1 to 100
+    if i == 6
+    then
+        break
+    end
+    print_formatted_now "i = %d" 500 i
+    wait 500
+end
+
+// execution continues here after break
+print_string_now "Loop stopped" 2000
+```
+
+This displays values `1` through `5`. When `i` becomes `6`, the `break` command exits the loop and the script displays `"Loop stopped"`. It works the same way in `while` and `for` loops.
+
+## Continue
+
+The `continue` command skips the rest of the current iteration and moves on to the next one:
+
+```sb
+int i
+for i = 1 to 5
+    if i == 3
+    then
+        continue
+    end
+    print_formatted_now "i = %d" 500 i
+    wait 500
+end
+```
+
+This displays `1`, `2`, `4`, `5`. The value `3` is skipped because `continue` jumps to the next iteration before `print_formatted_now` is reached.
+
+## Practical Example
+
+Here is a more practical use of `break`. This script gives the player money every second, but stops early if the `F6` key is pressed:
+
+```sb
+const KEY_F6 = 117
+
+int i
+for i = 1 to 10
+    if is_key_pressed KEY_F6
+    then
+        break
+    end
+    add_score 0 100
+    print_formatted_now "+$100 (round %d of 10)" 1000 i
+    wait 1000
+end
+```
+
+Without `break`, the only way to achieve this would be a `while` loop with a more complex condition. `break` gives you a clean way to exit early when something unexpected happens.
+
+:::note
+`break` and `continue` work in all loop types: `while`, `while true`, `for`, and `repeat..until`.
+:::