ForgeClass

Classes for ForgeScript: fields, methods, constructors, inheritance, private members and typed params.

Contents

1. Installation
2. Quick start
3. Functions
4. How it works
5. Modifiers
6. Class files
7. Keeping instances

1. Install the package.

   From npm - the stable release:

   npm i forge.class

   From GitHub:

   npm i github:Daaisukidayo/ForgeClass#main

   It needs ForgeScript 1.4.0 and Node.js 22 or newer.

2. Here's an example of how your main file should look:

   const { ForgeClient } = require("@tryforge/forgescript")
   const { ForgeClass } = require("forge.class")
   
   const client = new ForgeClient({
       ...options, // Change that to the options you currently have
       extensions: [
           new ForgeClass(),
           // Add other extensions you installed here
       ]
   })
   
   client.login("YourToken")

$class[Player;
    $field[name]
    $field[hp;100]
    $constructor[$setField[this;name;$env[name]];name]
    $method[damage;
        $setField[this;hp;$math[$getField[this;hp]-$env[amount]]]
        $return[$getField[this;hp]]
    ;amount]
]

$new[p;Player;Steve]
$callMethod[p;damage;30]   → 70
$getField[p;hp]            → 70
$instanceOf[p;Player]      → true

Declaring a class

All but $class work only inside its body.

| Function | What it does | |---|---| | $class[name;body] | Declares a class. The body outputs nothing. | | $field[name;default?] | Declares a field. The default is code run for every new instance, empty without one. | | $method[name;code;...params] | Declares a method. | | $constructor[code;...params] | Declares the constructor, which $new runs. | | $extends[parent] | Sets the parent class. | | $param[name;type;required?;rest?] | Declares a typed param, among the params of $method or $constructor. |

Working with instances

| Function | Returns | What it does | |---|---|---| | $new[variable;class;...args] | — | Creates an instance in a variable. | | $callMethod[variable;method;...args] | what the method returns | Calls a method. | | $super[method;...args] | what the method returns | Inside a method, calls the parent class's one on the same instance. $super[constructor;...] runs the parent's constructor. | | $getField[variable;field] | the value | Reads a field. | | $setField[variable;field;value] | — | Sets a field the class declares. | | $hasField[variable;field] | boolean | Whether the class declares the field. | | $hasMethod[variable;method] | boolean | Whether $callMethod can call the method. | | $instanceFields[variable] | JSON object | The fields, without __class. | | $className[variable] | string | The class of the instance. | | $instanceOf[variable;class] | boolean | Whether it is of that class or of one extending it. | | $isInstance[variable] | boolean | Whether the variable holds an instance. |

Static members

| Function | Returns | What it does | |---|---|---| | $getStatic[class;field] | the value | Reads a static field. | | $setStatic[class;field;value] | — | Sets a static field. | | $callStatic[class;method;...args] | what the method returns | Calls a static method. |

Classes

| Function | Returns | What it does | |---|---|---| | $classExists[class] | boolean | Whether the class is declared. | | $classFields[class] | JSON array | Its fields, inherited ones included. | | $classMethods[class] | JSON array | Its methods, inherited ones included, without the constructor. | | $classParent[class] | string | The class it extends, empty when none. | | $deleteClass[class] | boolean | Deletes the class unless another one extends it. Says whether there was one. |

Instances are plain objects in a variable, with the class name in a __class field that can't be changed.

Field values are stored as numbers, true, false or JSON when they are one, and as text otherwise. A number that wouldn't read back the same, like a Discord ID or 007, stays text, so IDs stay exact.

Methods

• The instance is this: $getField[this;hp], $callMethod[this;other].
• Arguments are read with $env[param]. A plain param gets the text as it is, a $param one is converted the way ForgeScript converts its own functions' arguments:

  $method[give;$return[$env[target;username] gets $arrayJoin[items;, ]];$param[target;User];$param[items;String;false;true]]

  The type is any ForgeScript arg type but Enum. An optional param may be left out, and a rest one takes the remaining arguments as an array.
• A method returns what $return gives, or else what it outputs.

Inheritance

• Fields and methods come from every parent up the chain.
• A field declared again keeps its place, with the child's default.
• A class without a constructor uses its parent's.

Words before a field or method name:

$class[Account;
    $field[private balance;0]
    $field[protected owner]
    $field[readonly id;$authorID]
    $field[static count;0]
    $method[static create;...]
]

• private members are reached only from the methods of their class, protected ones from its children too.
• readonly fields are set by their defaults or in the constructor. $super[constructor] works only in a constructor.
• static members belong to the class and have no this. They live until the bot restarts or the class is declared again.
• $classFields, $classMethods and, outside the class, $instanceFields list public members only.

A # before the name makes a member private as in JavaScript instead:

$class[Wallet;
    $field[#pin;1234]
    $method[#check;$if[$env[pin]==$getField[this;#pin];true;false];pin]
    $method[unlock;$callMethod[this;#check;$env[pin]];pin]
]

$new[w;Wallet]
$callMethod[w;unlock;1234]   → true
$getField[w;#pin]            → error

• Only the methods of the class that declares it reach it, on any instance of that class. A child class doesn't, and neither does $super.
• A parent's #x and a child's #x are different members, and #x and x can live side by side.
• It isn't kept on the instance, so $env, $instanceFields, $classFields and $classMethods don't show it.

For classes used everywhere, load them from a folder before the client logs in:

client.classes.load("./classes")

A file exports one class or an array of them:

module.exports = {
    name: "Player",
    extends: "Entity",
    fields: { hp: 100, name: "", items: [] },
    methods: {
        constructor: {
            params: ["name"],
            code: `
                $setField[this;name;$env[name]]
            `,
        },
        damage: {
            params: [{ name: "amount", type: "Number" }],
            code: `
                $setField[this;hp;$math[$getField[this;hp]-$env[amount]]]
            `,
        },
        greet: "Hi, $getField[this;name]!",
    },
}

Or the same object wrapped in ForgeClassBuilder:

const { ForgeClassBuilder } = require("forge.class")

module.exports = new ForgeClassBuilder({ name: "Player", ... })

Every string in a field default is code, even inside an array or object: stats: { best: 0, by: "$authorID" }. The rest, like 100, [] or null, is kept as it is. Every instance gets its own copy.

A param is either a name or a { name, type, required, rest } object, with type written as "Number" or ParamType.Number. client.classes.add() takes objects and builders alike. When one class can't be used, it throws and none of them is added.

An instance lives as long as the command, but it comes back from its own JSON. Save $env[p] anywhere and load it in another command:

$jsonLoad[p;the saved JSON]
$callMethod[p;greet]   → Hi, Steve!

Private # fields aren't in the JSON.