add OOP classes

Fernando-A-Rocha · Fernando-A-Rocha · commit 96727f810b6c · 2025-05-22T17:21:01.000+01:00
diff --git a/.github/workflows/validate.yaml b/.github/workflows/validate.yaml
@@ -6,12 +6,14 @@ on:
       - 'elements/**/*.yaml'
       - 'events/**/*.yaml'
       - 'functions/**/*.yaml'
+      - 'classes/**/*.yaml'
       - 'schemas/**/*.yaml'
   pull_request:
     paths:
       - 'elements/**/*.yaml'
       - 'events/**/*.yaml'
       - 'functions/**/*.yaml'
+      - 'classes/**/*.yaml'
       - 'schemas/**/*.yaml'
   workflow_dispatch:
 
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -3,5 +3,6 @@
         "schemas/function.yaml": "/functions/**/*",
         "schemas/element.yaml": "/elements/**/*",
         "schemas/event.yaml": "/events/**/*",
+        "schemas/class.yaml": "/classes/**/*",
     }
 }
diff --git a/classes/Matrix/Matrix.yaml b/classes/Matrix/Matrix.yaml
@@ -0,0 +1,4 @@
+name: 'matrix'
+description: |
+  Matrices are one of the most powerful features of MTA [OOP](/OOP). We did have a presence of Matrices before with [getElementMatrix](/getElementMatrix), but we were given an ugly disgusting table to play with. Now, with the new Matrix class, we can make and magically manipulate Matrices.
+
diff --git a/classes/Vector/Vector2.yaml b/classes/Vector/Vector2.yaml
@@ -0,0 +1,4 @@
+name: 'vector2'
+description: |
+  This is a 2D [Vector](/Vector) class.
+
diff --git a/classes/Vector/Vector3.yaml b/classes/Vector/Vector3.yaml
@@ -0,0 +1,4 @@
+name: 'vector3'
+description: |
+  This is a 3D [Vector](/Vector) class.
+
diff --git a/classes/Vector/Vector4.yaml b/classes/Vector/Vector4.yaml
@@ -0,0 +1,4 @@
+name: 'vector4'
+description: |
+  This is a 4D [Vector](/Vector) class.
+
diff --git a/schemas/class.yaml b/schemas/class.yaml
@@ -0,0 +1,16 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: class.yaml
+title: OOP Class schema
+type: object
+required:
+  - name
+  - description
+properties:
+  name:
+    type: string
+    description: Lowercase name of the OOP class.
+  description:
+    type: string
+    description: Description of the OOP class.
+  see_also:
+    $ref: 'common-defs.yaml#/$defs/see_also'
diff --git a/tools/validate.cmd b/tools/validate.cmd
@@ -11,3 +11,7 @@ for /r "elements" %%f in (*.yaml) do (
 for /r "events" %%f in (*.yaml) do (
     .\tools\yajsv.exe -s schemas/event.yaml -r schemas/common-defs.yaml "%%f"
 )
+
+for /r "classes" %%f in (*.yaml) do (
+    .\tools\yajsv.exe -s schemas/class.yaml -r schemas/common-defs.yaml "%%f"
+)
diff --git a/tools/validate.sh b/tools/validate.sh
@@ -3,3 +3,4 @@
 find 'functions/' -name '*.yaml' -type f -print0 | xargs -0 -I {} tools/yajsv -s schemas/function.yaml -r schemas/common-defs.yaml {}
 find 'elements/' -name '*.yaml' -type f -print0 | xargs -0 -I {} tools/yajsv -s schemas/element.yaml -r schemas/common-defs.yaml {}
 find 'events/' -name '*.yaml' -type f -print0 | xargs -0 -I {} tools/yajsv -s schemas/event.yaml -r schemas/common-defs.yaml {}
+find 'classes/' -name '*.yaml' -type f -print0 | xargs -0 -I {} tools/yajsv -s schemas/class.yaml -r schemas/common-defs.yaml {}
diff --git a/web/astro.config.mjs b/web/astro.config.mjs
@@ -72,6 +72,14 @@ export default defineConfig({
 								{label: 'Server events', link: 'Server_Scripting_Events'},
 							]
 						},
+						{
+							label: 'OOP',
+							items: [
+								{label: 'About OOP', link: 'OOP'},
+								{label: 'OOP Introduction', link: 'OOP_Introduction'},
+								{label: 'OOP Classes', link: 'OOP_Classes'},
+							]
+						},
 						{
 							label: 'Elements',
 							items: [
diff --git a/web/src/content.config.ts b/web/src/content.config.ts
@@ -32,4 +32,14 @@ export const collections = {
 			}
 		})
 	}),
+	classes: defineCollection({
+		loader: glob({
+			pattern: "**/*.yaml",
+			base: "../classes",
+			generateId: ({ entry }) => {
+				// Extract the file name without the folder
+				return ((entry.split('/') || []).pop() || '').replace(/\.yaml$/, '');
+			}
+		})
+	}),
 };
diff --git a/web/src/pages/OOP.mdx b/web/src/pages/OOP.mdx
@@ -0,0 +1,88 @@
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+import { getSeeAlsoLinksFromList } from '@src/utils/general';
+import SeeAlsoSection from '@src/components/SeeAlsoSection.astro';
+
+<StarlightPage frontmatter={{
+    template: 'doc',
+    title: 'OOP',
+    tableOfContents: false,
+}}>
+
+Object Orientated Programming was introduced in MTA:SA 1.4 and comes with special utility classes like [Vector](/Vector) and [Matrix](/Matrix). This page contains general information about the OOP functions and provides useful links.
+
+### Turning it on
+
+By default, OOP is disabled (however, vectors and matrices are always available) - this is mainly because the vast majority of servers will prefer to stick to what they know - procedural programming. In fact, functions are still available even when OOP is enabled. Enabling OOP is as simple as adding the following line to the resource meta file:
+
+```xml
+<oop>true</oop>
+```
+
+### Vectors and Matrices
+
+[Vectors](/Vector) and [Matrices](/Matrix) make it easier to drop the complex maths and go straight ahead with fun part of maths. As mentioned above, OOP does not have to be enabled in the server config for this to be enabled. 
+
+### Tutorial and Introduction
+
+Read the [OOP Introduction](/OOP_Introduction) tutorial to learn about OOP and how to use it.
+
+### OOP Metatable Structure (Advanced)
+
+You will understand this if you're proficient with Lua and have a decent understanding of metatables. Understanding this section is not necessary to use OOP.
+
+```lua
+-- Exposed to global environment
+Element = {
+    Element = createElement,
+    setPosition = setElementPosition,
+    ...
+}
+
+Vehicle = {
+    Vehicle = createVehicle,
+    setColor = setVehicleColor,
+    ...
+}
+
+-- Hidden in lua registry, applied to userdata
+ElementMT = {
+    __index = CLuaClassDefs::Index,
+    __newindex = CLuaClassDefs::NewIndex,
+    __class = Element,
+    __call = __class.create,
+    __set = {
+        type = CLuaClassDefs::ReadOnly,
+        health = setElementHealth,
+        ...
+    },
+    __get = {
+        type = getElementType,
+        health = getElementHealth,
+        ...
+    },
+}
+
+VehicleMT = {
+    __index = CLuaClassDefs::Index,
+    __newindex = CLuaClassDefs::NewIndex,
+    __class = Vehicle,
+    __parent = ElementMT,
+    __call = __class.create,
+    __set = {
+        damageProof = setVehicleDamageProof
+        ...
+    },
+    __get = {
+        damageProof = isVehicleDamageProof
+        ...
+    },
+}
+```
+
+<SeeAlsoSection seeAlsoLinks={getSeeAlsoLinksFromList([
+    'article:OOP_Introduction',
+    'classes:any:Vector',
+    'classes:any:Matrix'
+])} currentId='' />
+
+</StarlightPage>
diff --git a/web/src/pages/OOP_Classes.astro b/web/src/pages/OOP_Classes.astro
@@ -0,0 +1,34 @@
+---
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+import { getOOPClassesByCategory } from '@src/utils/classes';
+const classesByCategory = getOOPClassesByCategory();
+---
+<StarlightPage frontmatter={{
+    template: 'doc',
+    title: 'OOP Classes',
+    tableOfContents: false,
+}}>
+    <p>This page lists all <strong><a href="/OOP">OOP</a> Classes</strong> available in the <a href="/lua-api">Lua API</a> organized by category.</p>
+
+    
+    {Object.entries(classesByCategory).map(([category, oopClasses]) => (
+        <section>
+            <details>
+                <summary>{category} classes</summary>
+                <ul>
+                    {oopClasses.map(oopClass => (
+                        <li><a href={`/${oopClass.id}`}>{oopClass.id}</a></li>
+                    ))}
+                </ul>
+            </details>
+        </section>
+    ))}
+</StarlightPage>
+
+<script>
+    document.querySelectorAll('.side-type-color').forEach(el => {
+        const type = el.textContent || '';
+        el.classList.add(`side-${type.toLowerCase()}`);
+    });
+
+</script>
diff --git a/web/src/pages/OOP_Introduction.mdx b/web/src/pages/OOP_Introduction.mdx
@@ -1,6 +1,8 @@
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 import { Image } from 'astro:assets';
 import imageDiagram from '../../../assets/oop_intro_diagram.png';
+import { getSeeAlsoLinksFromList } from '@src/utils/general';
+import SeeAlsoSection from '@src/components/SeeAlsoSection.astro';
 
 <StarlightPage frontmatter={{
     template: 'doc',
@@ -152,4 +154,10 @@ The documentation for the OOP syntax intends to be very simplistic and is suppor
 * Methods can either start like `player:` or `Player.` — the former is only for a function on an instance (like `setPlayerHealth`) and the latter is a static method (like `getRandomPlayer`).
 * The counterpart section allows you to see at a glance how the variable can be used. In most cases, this can be inferred from the function page.
 
+<SeeAlsoSection seeAlsoLinks={getSeeAlsoLinksFromList([
+    'article:OOP',
+    'classes:any:Vector',
+    'classes:any:Matrix'
+])} currentId='' />
+
 </StarlightPage>
diff --git a/web/src/pages/Vector.mdx b/web/src/pages/Vector.mdx
@@ -0,0 +1,26 @@
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+import { getSeeAlsoLinksFromList } from '@src/utils/general';
+import SeeAlsoSection from '@src/components/SeeAlsoSection.astro';
+
+<StarlightPage frontmatter={{
+    template: 'doc',
+    title: 'OOP Vector',
+    tableOfContents: false,
+}}>
+
+A vector represents a <a href="https://en.wikipedia.org/wiki/Euclidean_vector" target="_blank">Euclidean vector</a>, which can be used to work with positions or directions in a 2D plane or 3D space. The classes of vectors available in MTA are:
+
+- [Vector2](/Vector2)
+- [Vector3](/Vector3)
+- [Vector4](/Vector4)
+
+**Tip**: if you are using vectors a lot, you can use `collectgarbage("setpause",100)` to tell Lua to garbage collect intermediary vectors frequently. Run that once per resource (or just in the resource you need it for). This has other performance implications as Lua will be stopping the world more frequently. 
+
+<SeeAlsoSection seeAlsoLinks={getSeeAlsoLinksFromList([
+    'article:OOP',
+    'article:OOP_Introduction',
+    'classes:any:Vector',
+    'classes:any:Matrix'
+])} currentId='' />
+
+</StarlightPage>
diff --git a/web/src/pages/[element].astro b/web/src/pages/[element].astro
@@ -2,7 +2,7 @@
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 import { getCollection } from 'astro:content';
 import { marked } from 'marked';
-import { getPageSeeAlsoLinks } from '@src/utils/general';
+import { getSeeAlsoLinksForItem } from '@src/utils/general';
 
 import SeeAlsoSection from '@src/components/SeeAlsoSection.astro';
 
@@ -21,11 +21,11 @@ element.data.niceName = element.data.name.charAt(0).toUpperCase() + element.data
 ---
 <StarlightPage frontmatter={{
   template: 'doc',
-  title: element.data.name,
+  title: element.data.niceName,
   tableOfContents: false,
 }}>
   <Fragment set:html={marked(element.data.description)} />
 
-  <SeeAlsoSection seeAlsoLinks={getPageSeeAlsoLinks(element)} currentId={element.id} />
+  <SeeAlsoSection seeAlsoLinks={getSeeAlsoLinksForItem(element)} currentId={element.id} />
 </StarlightPage>
 
diff --git a/web/src/pages/[event].astro b/web/src/pages/[event].astro
@@ -6,7 +6,7 @@ import fs from "fs";
 import path from "path";
 import { Code } from '@astrojs/starlight/components';
 import '@src/styles/function-page.css';
-import { getPageSeeAlsoLinks } from '@src/utils/general';
+import { getSeeAlsoLinksForItem } from '@src/utils/general';
 
 import NoteBox from '@src/components/NoteBox.astro';
 import type { NotesType } from '@src/utils/types';
@@ -119,6 +119,6 @@ if (Array.isArray(event.data.notes) && event.data.notes.length > 0) {
             </div>
         )}
 
-        <SeeAlsoSection seeAlsoLinks={getPageSeeAlsoLinks(event)} currentId={event.id} />
+        <SeeAlsoSection seeAlsoLinks={getSeeAlsoLinksForItem(event)} currentId={event.id} />
     </StarlightPage>
 </div>
diff --git a/web/src/pages/[func].astro b/web/src/pages/[func].astro
@@ -2,7 +2,7 @@
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 import { getCollection } from 'astro:content';
 import { getFunctionInfo, parseFunctionSyntaxes } from '@src/utils/functions';
-import { renderInlineMarkdown, getPageSeeAlsoLinks } from '@src/utils/general';
+import { renderInlineMarkdown, getSeeAlsoLinksForItem } from '@src/utils/general';
 import { marked } from 'marked';
 import fs from "fs";
 import path from "path";
@@ -186,6 +186,6 @@ let funcSyntaxes = parseFunctionSyntaxes(func.id, func.data);
             </div>
         )}
 
-        <SeeAlsoSection seeAlsoLinks={getPageSeeAlsoLinks(func)} currentId={func.id} />
+        <SeeAlsoSection seeAlsoLinks={getSeeAlsoLinksForItem(func)} currentId={func.id} />
     </StarlightPage>
 </div>
diff --git a/web/src/pages/[oopclass].astro b/web/src/pages/[oopclass].astro
@@ -0,0 +1,30 @@
+---
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+import { getCollection } from 'astro:content';
+import { marked } from 'marked';
+import { getSeeAlsoLinksForItem } from '@src/utils/general';
+
+import SeeAlsoSection from '@src/components/SeeAlsoSection.astro';
+
+export async function getStaticPaths() {
+  const classes = await getCollection('classes');
+  return classes.map(oopclass => ({
+    params: { oopclass: oopclass.id },
+    props: { oopclass },
+  }));
+}
+
+const { oopclass } = Astro.props;
+oopclass.data.itemType = 'class';
+
+---
+<StarlightPage frontmatter={{
+  template: 'doc',
+  title: oopclass.id,
+  tableOfContents: false,
+}}>
+  <Fragment set:html={marked(oopclass.data.description)} />
+
+  <SeeAlsoSection seeAlsoLinks={getSeeAlsoLinksForItem(oopclass)} currentId={oopclass.id} />
+</StarlightPage>
+
diff --git a/web/src/utils/classes.ts b/web/src/utils/classes.ts
@@ -0,0 +1,24 @@
+import { getCollection } from 'astro:content';
+import path from 'path';
+
+type OOPClassItem = Awaited<ReturnType<typeof getCollection>>[number];
+
+type OOPClassesByCategory = {
+    [folder: string]: OOPClassItem[];
+};
+
+const oopClassesCollection = await getCollection('classes');
+let classesByCategory: OOPClassesByCategory = {};
+
+for (let oopClass of oopClassesCollection) {
+    const normalizedPath = path.normalize(oopClass.filePath || '');
+    const folder = path.basename(path.dirname(normalizedPath));
+    if (!classesByCategory[folder]) {
+        classesByCategory[folder] = [];
+    }
+    classesByCategory[folder].push(oopClass);
+}
+
+export function getOOPClassesByCategory(): OOPClassesByCategory {
+    return classesByCategory;
+}
diff --git a/web/src/utils/general.ts b/web/src/utils/general.ts

Original file line number	Diff line number	Diff line change
`@@ -3,5 +3,6 @@`
`3`	`3`	`"schemas/function.yaml": "/functions/*/",`
`4`	`4`	`"schemas/element.yaml": "/elements/*/",`
`5`	`5`	`"schemas/event.yaml": "/events/*/",`
	`6`	`+ "schemas/class.yaml": "/classes/*/",`
`6`	`7`	`}`
`7`	`8`	`}`
Original file line number	Diff line number	Diff line change
`@@ -11,3 +11,7 @@ for /r "elements" %%f in (*.yaml) do (`
`11`	`11`	`for /r "events" %%f in (*.yaml) do (`
`12`	`12`	`.\tools\yajsv.exe -s schemas/event.yaml -r schemas/common-defs.yaml "%%f"`
`13`	`13`	`)`
	`14`	`+`
	`15`	`+for /r "classes" %%f in (*.yaml) do (`
	`16`	`+ .\tools\yajsv.exe -s schemas/class.yaml -r schemas/common-defs.yaml "%%f"`
	`17`	`+)`