docs: expand release examples and reference coverage

Author: Elektryk-Andrzej

Example Scripts/914Effects.ser

@@ -1,6 +1,7 @@
 # Disabled by default: remove # from the filename to enable this script.
 # this script applies different effects for players in SCP-914
 # depending on the current setting of the knob
+# Requires SafeScripts: false so IsAllowed can change the 914 output in time.
 
 !-- OnEvent ProcessingPlayer
 -- require @evPlayer $evKnobSetting
@@ -31,4 +32,4 @@ elif $evKnobSetting is "Fine"
 elif $evKnobSetting is "VeryFine"
     GiveEffect @evPlayer MovementBoost 20s 10
     GiveEffect @evPlayer AntiScp207 10s
-end
+end

Example Scripts/chaosCoin.ser

@@ -1,5 +1,6 @@
 # Disabled by default: remove # from the filename to enable this script.
 # this script adds a fully functioning coin with custom behaviors
+# Requires SafeScripts: false so IsAllowed can cancel a coin flip in time.
 
 !-- OnEvent FlippingCoin
 

Example Scripts/friendlyFireGuard.ser

@@ -0,0 +1,18 @@
+# Disabled by default: remove # from the filename to enable this script.
+# Stops direct damage between players on the same team and tells the attacker why.
+# Environmental damage and self-damage are left unchanged.
+# Requires SafeScripts: false so IsAllowed can cancel the damage in time.
+
+!-- OnEvent Hurting
+-- require @evPlayer @evAttacker
+
+if {Overlapping @evPlayer @evAttacker}
+    stop
+end
+
+if {@evPlayer -> team} isnt {@evAttacker -> team}
+    stop
+end
+
+IsAllowed false
+Hint @evAttacker 3s "<color=#ffb86c>Friendly fire is disabled for your team.</color>"

Example Scripts/limitScp173Movement.ser

@@ -1,6 +1,7 @@
 # Disabled by default: remove # from the filename to enable this script.
 # this script limits when scp 173 can teleport
 # depending on how many players are looking at him
+# Requires SafeScripts: false so IsAllowed can cancel the teleport in time.
 
 !-- OnEvent Teleporting
 -- require @evPlayer
@@ -39,4 +40,4 @@ wait {ToDuration {Random 1 $observerCount} seconds}
 SetPlayerData @evPlayer can_teleport true
 
 # inform about the ability to move
-Hint @evPlayer 2s "<color=green><b>You can now move!</b></color>"
+Hint @evPlayer 2s "<color=green><b>You can now move!</b></color>"

Example Scripts/roundReport.ser

@@ -0,0 +1,28 @@
+# Disabled by default: remove # from the filename to enable this script.
+# Sends a small Discord report after each round.
+# Create Custom Configs/round-report.yml inside the SER config directory:
+# webhook_url: "https://discord.com/api/webhooks/..."
+
+!-- OnEvent RoundEnded
+-- require $evLeadingTeam
+
+*settings = Config.Read "round-report"
+if {*settings -> isInvalid}
+    Error "Round report was not sent. Create Custom Configs/round-report.yml and add webhook_url."
+    stop
+end
+
+$webhookUrl = Config.GetOption *settings "webhook_url" ""
+if {$webhookUrl -> length} is 0
+    Error "Round report was not sent. Set webhook_url in Custom Configs/round-report.yml."
+    stop
+end
+
+$content = "Round ended. Leading team: {$evLeadingTeam}. Players online: {AmountOf @all}."
+*message = Discord.CreateMessage $content
+
+attempt
+    Discord.SendMessage $webhookUrl *message
+on_error with $message
+    Error "Round report could not reach Discord: {$message}"
+end

VS Code Extension/out/ser-language.json

@@ -7613,10 +7613,10 @@
     },
     "IsAllowed": {
       "syntax": "IsAllowed isAllowed",
-      "description": "Sets whether or not the event is allowed to run.",
+      "description": "Allows or cancels the event that started this script.",
       "subgroup": "Event",
       "essential": false,
-      "additionalDescription": "In order for it to have any impact, the script in which the method is used must be triggered by an event, and that event must be cancellable.",
+      "additionalDescription": "This only works in a cancellable event, before any Wait or other pause. It cannot cancel the current event while SafeScripts is enabled because the safety pause lets the event continue first.",
       "requiredFramework": null,
       "returns": null,
       "arguments": [

VS Code Extension/out/visual-editor.html

@@ -12,6 +12,8 @@ old releases.
 | Create a player command | [`selfHealCommand.ser`](../../Example%20Scripts/selfHealCommand.ser) |
 | Put several handlers in one file | [`multiSectionHandlers.ser`](../../Example%20Scripts/multiSectionHandlers.ser) |
 | Track round state | [`killStreak.ser`](../../Example%20Scripts/killStreak.ser) |
+| Block damage between teammates | [`friendlyFireGuard.ser`](../../Example%20Scripts/friendlyFireGuard.ser) |
+| Send a round result to Discord | [`roundReport.ser`](../../Example%20Scripts/roundReport.ser) |
 | Build a timed event | [`hotPotato.ser`](../../Example%20Scripts/hotPotato.ser) |
 | Store persistent-style data | [`coinTracker.ser`](../../Example%20Scripts/coinTracker.ser) |
 | Create custom roles | [`customRoles.ser`](../../Example%20Scripts/customRoles.ser) |

docs/guides/examples.md

@@ -84,7 +84,18 @@ end
 ```
 
 `IsAllowed false` changes the game event. `stop` prevents later SER
-instructions in this section from running.
+instructions in this section from running. Put `IsAllowed` before any `Wait` or
+other pause.
+
+:::warning SafeScripts and event cancellation
+
+`IsAllowed` cannot cancel the current event while SafeScripts is enabled. The
+safety pause lets the game continue the event before the script can change it.
+Keep SafeScripts enabled for general scripts. If a script must cancel an event,
+turn it off only after checking every active script for loops that can freeze the
+server.
+
+:::
 
 ## ProjectMER events
 

docs/guides/flags-events-and-commands.md

@@ -167,6 +167,9 @@ end
 ```
 
 Keep `attempt` blocks small so it is obvious which instruction failed.
+`attempt` handles errors caused by script input or game state. The `stop`
+keyword still stops the script, and an internal SER failure still receives an
+identifier in the server console instead of being hidden by `on_error`.
 Unexpected internal SER failures are presented with a short identifier; full
 technical details remain in the server console.