xd

Author: bleonheart

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
         with:
-          path: optional_modules
+          path: modules
       - uses: leafo/gh-actions-lua@v8.0.0
         with:
           luaVersion: 5.2
@@ -42,7 +42,7 @@ jobs:
             --no-global --no-self \
             --no-max-line-length --no-max-code-line-length \
             --no-max-string-line-length --no-max-comment-line-length
-        working-directory: optional_modules
+        working-directory: modules
 
   bump-version:
     needs: linter
@@ -224,7 +224,7 @@ jobs:
             mod=${d#extracted_}
             doc_dir=$(find "$d" -type d -iname docs -maxdepth 2 -print -quit || true)
             [ -z "$doc_dir" ] && continue
-            dest="documentation/docs/optional_modules/${mod}"
+            dest="documentation/docs/modules/${mod}"
             mkdir -p "$dest"
             find "$doc_dir" -maxdepth 1 -type f -name '*.md' -exec cp {} "$dest/" \;
           done
@@ -238,7 +238,7 @@ jobs:
           if [ -f documentation/modules.json ]; then
             jq -c '.[]' documentation/modules.json | while read -r mod; do
               id=$(echo "$mod" | jq -r '.public_uniqueID')
-              dest="documentation/docs/optional_modules/${id}"
+              dest="documentation/docs/modules/${id}"
               mkdir -p "$dest"
               {
                 echo "# $(echo "$mod" | jq -r '.name')"
@@ -268,8 +268,8 @@ jobs:
           fi
       - name: clean-obsolete-docs
         run: |
-          rm -rf documentation/docs/hooks/optional_modules
-          rm -rf documentation/docs/libraries/optional_modules
+          rm -rf documentation/docs/hooks/modules
+          rm -rf documentation/docs/libraries/modules
       - uses: actions/setup-node@v3
         with:
           node-version: 16

generate_about_md.js

@@ -25,7 +25,7 @@ if (!Array.isArray(modules)) {
 for (const mod of modules) {
   const id = mod.public_uniqueID || '';
   if (!id) continue;
-  const dest = path.join(__dirname, 'documentation', 'docs', 'optional_modules', id);
+  const dest = path.join(__dirname, 'documentation', 'docs', 'modules', id);
   fs.mkdirSync(dest, { recursive: true });
 
   const lines = [];

sampledocs/hooks.md

@@ -0,0 +1,208 @@
+# Class Hooks
+
+Classes can implement lifecycle hooks to control access, initialize settings, and respond to events such as joining, leaving, spawning, or being transferred.
+
+Define these functions inside your class definition files (`schema/classes/*.lua`).
+
+All hooks are optional; unspecified hooks fall back to default behaviour.
+
+---
+
+### OnCanBe
+
+**Purpose**
+
+Determines whether a player is allowed to switch to this class.
+
+**Parameters**
+
+* `client` (`Player`): The player attempting to switch.
+
+**Realm**
+
+`Server`
+
+**Returns**
+
+* `boolean?`: Return `false` to deny the change.
+
+**Example Usage**
+
+```lua
+function CLASS:OnCanBe(client)
+    -- Only allow admins or players that own the "V" flag.
+    if client:IsAdmin() then
+        return true
+    end
+
+    local char = client:getChar()
+    if char and char:hasFlags("V") then
+        return true
+    end
+
+    -- Returning false prevents the switch.
+    return false
+end
+```
+
+---
+
+### OnLeave
+
+**Purpose**
+
+Runs on the previous class after a player successfully changes classes.
+
+**Parameters**
+
+* `client` (`Player`): The player who has left the class.
+
+**Realm**
+
+`Server`
+
+**Returns**
+
+* `nil`: This function does not return a value.
+
+**Example Usage**
+
+```lua
+function CLASS:OnLeave(client)
+    -- Strip any class-specific weapons.
+    client:StripWeapon("weapon_pistol")
+
+    -- Restore the player's previous model before the class change.
+    local char = client:getChar()
+    if char and self.model then
+        char:setModel(char:getData("model", char:getModel()))
+    end
+
+    -- Reset movement speeds back to the config defaults.
+    client:SetWalkSpeed(lia.config.get("WalkSpeed"))
+    client:SetRunSpeed(lia.config.get("RunSpeed"))
+end
+```
+
+---
+
+### OnSet
+
+**Purpose**
+
+Executes immediately after a player joins this class.
+
+**Parameters**
+
+* `client` (`Player`): The player who has joined the class.
+
+**Realm**
+
+`Server`
+
+**Returns**
+
+* `nil`: This function does not return a value.
+
+**Example Usage**
+
+```lua
+function CLASS:OnSet(client)
+    local char = client:getChar()
+
+    -- Apply the class model and give a starter pistol.
+    if char and self.model then
+        char:setModel(self.model)
+    end
+    client:Give("weapon_pistol")
+
+    -- Initialize base stats from the class definition.
+    if self.health then
+        client:SetHealth(self.health)
+        client:SetMaxHealth(self.health)
+    end
+    if self.armor then
+        client:SetArmor(self.armor)
+    end
+end
+```
+
+---
+
+### OnSpawn
+
+**Purpose**
+
+Runs each time a member of this class respawns.
+
+**Parameters**
+
+* `client` (`Player`): The player who has just spawned.
+
+**Realm**
+
+`Server`
+
+**Returns**
+
+* `nil`: This function does not return a value.
+
+**Example Usage**
+
+```lua
+function CLASS:OnSpawn(client)
+    -- Apply the class load-out and stats every respawn.
+    client:SetMaxHealth(self.health or 150)
+    client:SetHealth(client:GetMaxHealth())
+    client:SetArmor(self.armor or 50)
+
+    for _, wep in ipairs(self.weapons or {}) do
+        client:Give(wep)
+    end
+
+    if self.runSpeed then
+        client:SetRunSpeed(self.runSpeed)
+    end
+    if self.walkSpeed then
+        client:SetWalkSpeed(self.walkSpeed)
+    end
+end
+```
+
+---
+
+### OnTransferred
+
+**Purpose**
+
+Fires when a player is moved into this class from another.
+
+**Parameters**
+
+* `client` (`Player`): The player who was transferred.
+* `oldClass` (`number`): Index of the previous class.
+
+**Realm**
+
+`Server`
+
+**Returns**
+
+* `nil`: This function does not return a value.
+
+**Example Usage**
+
+```lua
+function CLASS:OnTransferred(client, oldClass)
+    local char = client:getChar()
+    if char and self.model then
+        -- Swap the model to match the new class.
+        char:setModel(self.model)
+    end
+
+    -- Record the previous class so we can switch back later if needed.
+    char:setData("previousClass", oldClass)
+end
+```
+
+---

sampledocs/libraries.md

@@ -0,0 +1,79 @@
+# Attributes Library
+
+This page documents the functions for working with character attributes.
+
+---
+
+## Overview
+
+The attributes library loads attribute definitions from Lua files, keeps track of character values, and provides helper methods for modifying them. Each attribute is defined on a global `ATTRIBUTE` table inside its own file. When `lia.attribs.loadFromDir` is called the file is included **shared**, default values are filled in, and the definition is stored in `lia.attribs.list` using the file name (without extension or the `sh_` prefix) as the key. The loader is invoked automatically when a module is initialized, so most schemas simply place their attribute files in `schema/attributes/`.
+
+For details on each `ATTRIBUTE` field, see the [Attribute Fields documentation](../definitions/attribute.md).
+
+
+### lia.attribs.loadFromDir
+
+**Purpose**
+
+Loads attribute definitions from every Lua file in the given directory and registers them in `lia.attribs.list`.
+
+**Parameters**
+
+* `directory` (*string*): Path to the folder containing attribute Lua files.
+
+**Realm**
+
+`Shared`
+
+**Returns**
+
+* *nil*: This function does not return a value.
+
+**Example Usage**
+
+```lua
+-- schema/attributes/strength.lua
+ATTRIBUTE.name = "Strength"
+ATTRIBUTE.desc = "Determines melee damage."
+ATTRIBUTE.startingMax = 20
+ATTRIBUTE.maxValue = 50
+
+function ATTRIBUTE:OnSetup(client, value)
+    client:SetMaxHealth(100 + value)
+end
+
+-- Load all attribute files once at startup
+lia.attribs.loadFromDir("schema/attributes")
+```
+
+---
+
+### lia.attribs.setup
+
+**Purpose**
+
+Initializes and refreshes attribute data for a player's character, invoking any `OnSetup` callbacks defined by individual attributes.
+
+**Parameters**
+
+* `client` (*Player*): The player whose character attributes should be set up.
+
+**Realm**
+
+`Server`
+
+**Returns**
+
+* *nil*: This function does not return a value.
+
+**Example Usage**
+
+```lua
+-- After modifying a character attribute, run setup again so any
+-- OnSetup hooks update the player's stats.
+local char = client:getChar()
+char:updateAttrib("strength", 5)
+lia.attribs.setup(client)
+```
+
+---