Improve event system article readability and add link to Script security article (TODO)

Author: Fernando-A-Rocha

web/src/pages/articles/Script_security.astro

@@ -0,0 +1,13 @@
+---
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+---
+
+<StarlightPage frontmatter={{
+    template: 'doc',
+    title: 'Script security',
+    tableOfContents: false,
+}}>
+
+TODO
+
+</StarlightPage>

web/src/pages/reference/Event_System.astro

@@ -8,73 +8,112 @@ import { Code } from '@astrojs/starlight/components';
   tableOfContents: false,
 }}>
 <p>
-The event system is at the core of MTA scripting. Events work closely in conjunction with the element tree. Events are triggered when something happens - a player enters a marker, an element is clicked on etc. Each event has a source element, this is the element that performed the action.
+The event system is a fundamental part of MTA scripting. It works closely with the <a href="/reference/Element_tree">element tree</a> to allow scripts to respond to things that happen in the game — for example, when a player enters a marker or clicks an element. Every event has a <strong>source</strong> element: the element where the event originated.
 </p>
 
-<h2 id="event-handlers">Event handlers</h2>
+<h2 id="event-handlers">Event Handlers</h2>
 <p>
-To use the event system, you attach event handlers to elements in the element tree using <a href="/reference/addEventHandler">addEventHandler</a>. When you do this, your function will get triggered for all the events triggered on that element, its parents (and their parents, etc.) and its children (and their children). As such, an event handler attached to the <em>root</em> element will be triggered when an event occurs for any element. As a consequence you should generally use as specific a handler as you can. If you wish to just see when the player enters a specific marker, just attach the event handler to that marker.
+To react to events, you attach event handlers to elements using <a href="/reference/addEventHandler">addEventHandler</a>. Once attached, your handler will respond to events triggered by:
 </p>
-
-<p>Each event handler has three 'hidden' variables:</p>
 <ul>
-<li><strong>source</strong>: This is the element that the event originated from.</li>
-<li><strong>this</strong>: This is the element that the handler is being triggered on (i.e. the one you attached it to with <a href="/reference/addEventHandler">addEventHandler</a>).</li>
-<li><strong>eventName</strong>: This is the string of the name of the event that was called upon (i.e. the event name that was added with <a href="/reference/addEventHandler">addEventHandler</a>).</li>
+  <li>The element itself</li>
+  <li>Its parent elements (and their parents, recursively)</li>
+  <li>Its child elements (and their children, recursively)</li>
 </ul>
 
-<p>Additionally, the server-side event system also has one more 'hidden' variable:</p>
+<p>
+Because of this, attaching a handler to the <em>root</em> element will catch every event in the entire element tree. However, this is rarely needed — you should generally attach handlers to the most specific element possible. For example, if you only care when a player enters a certain marker, just attach your handler to that marker.
+</p>
+
+<h3>Handler Context Variables</h3>
+<p>
+Every event handler automatically receives some useful variables:
+</p>
 <ul>
-<li><strong>client</strong>: This is the client that triggered the event using <a href="/reference/triggerServerEvent">triggerServerEvent</a>. This is not set if the event was not triggered from a client.</li>
+  <li><strong>source</strong>: The element where the event originated.</li>
+  <li><strong>this</strong>: The element the handler is attached to.</li>
+  <li><strong>eventName</strong>: The name of the triggered event.</li>
 </ul>
 
 <p>
-The <em>source</em> variable is the most important one for most handlers. You almost always will want to reference this variable to tell what element triggered the event. The <em>this</em> variable has some uses for ensuring that an event was emitted by the element that you attached the handler to.
+On the server side, there's an extra variable:
 </p>
+<ul>
+  <li><strong>client</strong>: The client that triggered the event with <a href="/reference/triggerServerEvent">triggerServerEvent</a>, if applicable.</li>
+</ul>
 
 <p>
-It is <strong>important</strong> to note that events follow the element hierarchy. All events are initially triggered on the <em>source</em> element, followed by all the parent and children elements. This has few important implications:
+Read the <a href="/articles/Script_security">Script security</a> article for more information on how to use events securely and effectively.
 </p>
 
+<h3>Event Propagation</h3>
+<p>
+Events propagate through the element tree: they start at the <em>source</em> element, and then bubble up to parent elements and down to children. This has some implications:
+</p>
 <ul>
-<li>An event triggered on the root element will be triggered on every element in the element tree. This should be avoided where possible.</li>
-<li>All events anywhere in the element tree will be triggered on the root element. This means you can easily catch every event of a type by attaching a handler to the root element. Only do this if you genuinely want every event of that type, otherwise attach it somewhere more specific in the element tree.</li>
-<li>You can attach an event handler to your resource's root element to get all the events triggered by elements your resource contains.</li>
-<li>You can create 'dummy' elements to catch events from a group of child elements.</li>
-<li>
-    You can use dummy elements specified in a .map file (e.g. "flag") and create 'real' representations for them (e.g. objects) and make these real elements children of the dummy element. Event handlers can then be attached to the dummy element and it will receive all the events of the real elements.
-    This is useful for when one resource manages the representation of the element (creating the objects, for example), while another wants to handle special events. This could be a map resource that wants to handle a flag being captured in a specific way - the map resource would (generally) not be aware of the way the flag is represented.
-    This doesn't matter as it can just attach handlers to its dummy flag element while the other gamemode resource can handle the representation.
-</li>
+  <li>Triggering an event on the <em>root</em> element will also trigger it on every element in the tree — usually not recommended.</li>
+  <li>Handlers on the <em>root</em> element will catch every event — use this only when necessary.</li>
+  <li>You can attach a handler to your resource's root element to catch all events from elements your resource created.</li>
+  <li>You can create "dummy" elements to act as containers for groups of child elements and attach your handler to the dummy.</li>
+  <li>
+    You can define dummy elements in a <code>.map</code> file (e.g. a "flag") and dynamically create "real" objects as their children.
+    This allows one resource to manage the representation (e.g. the object model) while another handles game logic. For example, a map resource can define the flag, and a gamemode resource can listen for capture events on it.
+  </li>
 </ul>
 
+<h3>Event Parameters</h3>
 <p>
-The function you attached to an event gets called and passed a bunch of arguments. These arguments are event-specific. Each event has specific parameters, for instance <a href="/reference/onClientGUIClick">onClientGUIClick</a> has 4 parameters, which are:
+Event handlers also receive specific parameters depending on the event. For example, the <a href="/reference/onClientGUIClick">onClientGUIClick</a> event provides the following parameters:
 </p>
 
 <Code code="string button, string state, int absoluteX, int absoluteY" lang="lua" />
 
 <p>
-The function you attached to this event will be passed these parameters as arguments. You must remember that each event has different parameters.
+When writing a handler, be sure to check the documentation to see what arguments are passed for each event — they vary from one event to another.
 </p>
 
-<h2 id="built-in-events">Built in events</h2>
+<h2 id="built-in-events">Built-in Events</h2>
 <p>
-MTA has a number of built in events. These are listed on the pages <a href="/reference/Client_Scripting_Events">Client Scripting Events</a> and <a href="/reference/Server_Scripting_Events">Server Scripting Events</a>.
+MTA provides a wide range of built-in events, which are listed here:
 </p>
+<ul>
+  <li><a href="/reference/Client_Scripting_Events">Client Scripting Events</a></li>
+  <li><a href="/reference/Server_Scripting_Events">Server Scripting Events</a></li>
+</ul>
 
-<h2 id="custom-events">Custom events</h2>
+<h2 id="custom-events">Custom Events</h2>
 <p>
-You can create your own events that can be triggered across all resources. This is an important way to communicate with other resources and allow them to hook into your code. To add your own custom event, just call the <a href="/reference/addEvent">addEvent</a> function. You can then use the <a href="/reference/triggerEvent">triggerEvent</a> function to trigger that event any time you want - either using a timer, or based on a more general event.
+You can define and trigger your own custom events to communicate between different parts of your code — or even different resources. To define a custom event, use <a href="/reference/addEvent">addEvent</a>. You can then trigger it using <a href="/reference/triggerEvent">triggerEvent</a>.
 </p>
 
 <p>
-For example, you could be making a Capture the Flag game mode and want to trigger an event when a player captures the flag. You could do this by attaching a event handler to the standard MTA <a href="/reference/onMarkerHit">onMarkerHit</a> event and checking that the player entering the marker has the flag. If they do, you can then trigger your more specific <em>onFlagCaptured</em> event and other resources could handle this as they please.
+For instance, in a Capture the Flag game mode, you could trigger an <a href="/reference/onFlagCaptured">onFlagCaptured</a> event when a player captures a flag:
+</p>
+<ol>
+  <li>Attach a handler to the <a href="/reference/onMarkerHit">onMarkerHit</a> event.</li>
+  <li>Check if the player has the flag.</li>
+  <li>If yes, trigger the custom <a href="/reference/onFlagCaptured">onFlagCaptured</a> event.</li>
+</ol>
+
+<p>
+This allows other resources to react to your event however they want.
+</p>
+
+<h2 id="canceling">Canceling Events</h2>
+<p>
+You can cancel certain events using <a href="/reference/cancelEvent">cancelEvent</a>. This stops the default action from occurring. For example:
+</p>
+<ul>
+  <li>Canceling <a href="/reference/onPickupUse">onPickupUse</a> stops the player from picking up the item.</li>
+  <li>Canceling <a href="/reference/onVehicleStartEnter">onVehicleStartEnter</a> stops the player from entering the vehicle.</li>
+</ul>
+
+<p>
+To check if an event has already been canceled, use <a href="/reference/wasEventCancelled">wasEventCancelled</a>.
 </p>
 
-<h2 id="canceling">Canceling</h2>
 <p>
-Events can be canceled with <a href="/reference/cancelEvent">cancelEvent</a>. This can have a variety of effects, but in general this means that the server will not perform whatever action it would usually do. For example, canceling <a href="/reference/onPickupUse">onPickupUse</a> would prevent a player being given what they tried to pick up, canceling <a href="/reference/onVehicleStartEnter">onVehicleStartEnter</a> would prevent the player entering the vehicle. You can check if the currently active event has been canceled using <a href="/reference/wasEventCancelled">wasEventCancelled</a>. It's important to note that canceling an event <strong>does not</strong> prevent other event handlers being triggered.
+Note: Canceling an event does <strong>not</strong> stop other event handlers from being triggered.
 </p>
 
 </StarlightPage>