# # Commands

No commands are registered by default. Cmdr ships with a set of default commands, which can be loaded if you so wish by calling `Cmdr:RegisterDefaultCommands()`. See Default Commands for a list.

Custom commands are defined in ModuleScripts that return a single table.

    -- Teleport.lua, inside your commands folder as defined above.
    return {
        Name = "teleport";
        Aliases = {"tp"};
        Description = "Teleports a player or set of players to one target.";
        Group = "Admin";
        Args = {
                Type = "players";
                Name = "from";
                Description = "The players to teleport";
            },
                Type = "player";
                Name = "to";
                Description = "The player to teleport to"
        };

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Check out the [API reference](https://eryn.io/Cmdr/api/Registry.html#commanddefinition) full details.

The implementation should be in a separate ModuleScript. Cmdr will never deliver the server implementation to the client. This module should only return one function. The module must be named the same thing as the definition module as described above, with the word "Server" appended to the end.

It is passed the CommandContext for this command, which is a special object that represents a single command run. The context can be used to get the executing player, send events, reply with additional lines in the console, and more. See CommandContext in the API section below for more details. After the context, any arguments you defined in the command definition will be passed in order.

    -- TeleportServer.lua

    -- These arguments are guaranteed to exist and be correctly typed.
    return function (context, fromPlayers, toPlayer)
      if toPlayer.Character and toPlayer:FindFirstChild("HumanoidRootPart") then
        local position = toPlayer.Character.HumanoidRootPart.CFrame

        for _, player in ipairs(fromPlayers) do
          if player.Character and player.Character:FindFirstChild("HumanoidRootPart") then
            player.Character.HumanoidRootPart.CFrame = position
          end
        end

        return "Teleported players."
      end

      return "Target player has no character."
    end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Take a gander at the [built-in commands](https://github.com/evaera/Cmdr/tree/master/Cmdr/BuiltInCommands) for more examples.

## # Command Data

If you need to gather some data from the client before the command runs, you can create a [`Data`](https://eryn.io/Cmdr/api/Registry.html#commanddefinition) function in your command. This function will run on the client, and whatever is returned from it will be available with `context:GetData()` in the command implementation.

As an example, you might want to know the local player's current mouse world position in a server command. This can be achieved by returning `LocalPlayer:GetMouse().Hit.Position` from the Data function, then using `context:GetData()` to get the Vector3.

`context:GetData()` will work on both client and server commands.

## # Client commands

It is possible to have commands that run on the client exclusively or both.

If you want your command to run on the client, you can add a [`ClientRun`](https://eryn.io/Cmdr/api/Registry.html#commanddefinition) function to the command definition itself. It works exactly like the function that you would return from the Server module.

If using `ClientRun`, having a Server module associated with this command is optional.

  * If your `ClientRun` function returns a string, the command will run entirely on the client and won't touch the server at all (which means server-only hooks won't run).
  * If this function doesn't return anything, it will then execute the associated Server module implementation on the server.

WARNING

If this function is present and there isn't a Server module for this command, it is considered an error to not return a string from this function.

## # Execution order

Including [Hooks](https://eryn.io/Cmdr/guide/Hooks.html), the full execution order is:

  1. `BeforeRun` hook on client.
  2. `Data` function on client.
  3. `ClientRun` function on client.
  4. `BeforeRun` hook on server. *
  5. Server command implementation returned from Server module. *
  6. `AfterRun` hook on server. *
  7. `AfterRun` hook on client.

* Only runs if `ClientRun` isn't present or `ClientRun` returns `nil`.

## # Default Commands

If you run `Cmdr:RegisterDefaultCommands()`, these commands will be available with the following `Group`s:

Group: `DefaultAdmin`: `announce` (`m`), `bring`, `kick`, `teleport` (`tp`), `kill`, `respawn`, `to`

Group: `DefaultDebug`: `blink` (`b`), `thru` (`t`), `position`, `version`, `fetch`, `get-player-place-instance`, `uptime` Group: `DefaultUtil`: `alias`, `bind`, `unbind`, `run` (`>`), `runif`, `echo`, `hover`, `replace` (`//`, `gsub`), `history`, `me`, `var`, `var=`, `json-array-encode`, `json-array-decode`, `resolve`, `len`, `pick`, `rand`, `edit`, `goto-place`

Group: `Help`: `help`

### # Registering a subset of the default commands

If you only want some, but not all, of the default commands, you can restrict the commands that you register in two ways.

  1. Pass an array of groups to the RegisterDefaultCommands function: `Cmdr:RegisterDefaultCommands({"Help", "DefaultUtil"})`
  2. Pass a filter function that accepts a CommandDefinition and either returns `true` or `false`:

    Cmdr:RegisterDefaultCommands(function(cmd)
        return #cmd.Name < 6 -- This is absurd... but possible!
    end)

1
2
3

## # Argument Value Operators

Instead of typing out an entire argument, you can insert the following operators as a shorthand.

Operator | Meaning | Listable types only
---|---|---
`.` | Default value for the type | No
`?` | A random value from all possible values | No
`*` | A list of all possible values | Yes
`**` | All possible values minus the default value. | Yes
`?N` | N random values picked from all possible values | Yes

"All possible values" is determined automatically by using the values that are displayed in the autocomplete menu when you haven't typed anything for that argument yet.

If you want Cmdr to interpret the operator as literal text, you can escape these operators by inserting a `\` before them. For example: `\*` will be interpreted as a literal `*`.

### # Example

For the `players` type, this is the meaning of the operators:

Operator | Meaning
`.` | "me", or the player who is running the command.
`?` | A random single player.
`*` | All players.
`**` | "others", or all players who aren't the player running the command.
`?N` | N random players.

So: `kill *` kills all players, while `kill **` kills all players but you.

### # `resolve` command

The `resolve` command can be used to retrieve the true value of these operators as a list. It takes a type and an operator as arguments, and returns the list as a string.

Examples:

Input | Output
`resolve players .` | `Player1`
`resolve players *` | `Player1,Player2,Player3,Player4`
`resolve players **` | `Player2,Player3,Player4`
`resolve players ?` | `Player3`

## # Prefixed Union Types

An argument can be allowed to accept a different type when starting with a specific prefix. The most common example of this is with the `players` type, which when prefixed with % allows the user to select players based on team, rather than name.

These can be defined on a per-argument basis, so that your commands can accept many types of arguments in a single slot. Under the Args section of command definition, each argument has a `Type` key. For arguments that accept only a single type, it would look like `Type = "string"`. If we also wanted to accept a number when the user prefixes the argument with `#`, we could change it to: `Type = "string # number"`. Then, if the user provided `#33` for this argument, your function would be delivered the number value `33` in that position.

This is infinitely expandable, and you can include as many prefixed union types as you wish: `Type = "string # number @ player % team"`, etc. Remember that there must be a space between the symbol and the type.

Some default types automatically have a prefixed union type applied to them, because they would both resolve to the same type in the end. For example, whenever you define an argument of type `players`, under the hood this is perceived as `players % teamPlayers`. (`teamPlayers` is a type that matches based on team name, but resolves to an array of Players: the same thing that the normal `players` type would resolve with.)

Here is a list of automatic prefixed union types:

Type | Union
`players` | `players % teamPlayers`
`playerId` | `playerId # integer`
`playerIds` | `playerIds # integers`
`brickColor` | `brickColor % teamColor`
`brickColors` | `brickColors % teamColors`
`color3` | `color3 # hexColor3 ! brickColor3`
`color3s` | `color3s # hexColor3s ! brickColor3s`

← [ Setup ](https://eryn.io/Cmdr/guide/Setup.html) [ Types ](https://eryn.io/Cmdr/guide/Types.html) →


# Dispatcher

The Dispatcher handles parsing, validating, and evaluating commands. Exists on both client and server.

## Properties

### # `Cmdr`

`Dispatcher.Cmdr: `````[Cmdr](https://eryn.io/Cmdr/api/Cmdr.html#cmdr) | [CmdrClient](https://eryn.io/Cmdr/api/CmdrClient.html#cmdrclient)``````

A reference to Cmdr. This may either be the server or client version of Cmdr depending on where the code is running.

## Instance Methods

### # `Run` client only

`Dispatcher.``Run(...: ``string``) → ``string`````

This should be used to invoke commands programmatically as the local player. Accepts a variable number of arguments, which are all joined with spaces before being run. This function will raise an error if any validations occur, since it's only for hard-coded (or generated) commands.

#### Parameters

Name | Type | Required |
---|---|---|---
`...` | ```string``` |  ✔  |

#### Returns

Type |
```string``` |

### # `EvaluateAndRun`

`Dispatcher.``EvaluateAndRun(

commandText: ``string``,
executor?: ``Player?``,
options?: `{`

Data: `````any?`````

IsHuman: `````boolean`````

) → ``string`````

Runs a command as the given player. If called on the client, only text is required. Returns output or error test as a string.

#### Parameters

Name | Type | Required |
---|---|---|---
`commandText` | ```string``` |  ✔  |
`executor` | ```Player?``` |  ✘  |
`options` |  ### # `` `{``Data: `````any?````` IsHuman: `````boolean```````}` |  ✘  | If `Data` is given, it will be available on the server with [CommandContext.GetData](https://eryn.io/Cmdr/api/CommandContext.html#getdata)

#### Returns

Type |
```string``` |

### # `GetHistory` client only

`Dispatcher.``GetHistory() → ``array<string>`````

Returns an array of the user's command history. Most recent commands are inserted at the end of the array.

#### Returns

Type |
```array<string>``` |

← [ CommandContext ](https://eryn.io/Cmdr/api/CommandContext.html) [ Registry ](https://eryn.io/Cmdr/api/Registry.html) →


# # Meta-Commands

The `bind`, `alias`, and `run` commands make use of _command strings_. A command string is raw text made up of a command name and possibly predefined arguments that is run in the background as a command itself. Before these command strings are run, they are preprocessed, replacing arguments (in the format `$1`, `$2`, `$3`, etc.) and embedded commands with their textual values.

## # Embedded commands

Sub-commands may be embedded inside command strings, in the format `${command arg1 arg2 arg3}`. These sub-commands are evaluated just before the command string is run, and are run every time the command string runs. They evaluate to whatever the command returns as output.

Embedded commands are nestable: `run echo ${run echo ${echo hello}!}` (displays `"hello!"`). We use `run` here instead of just running `echo` directly, because embedded commands are only evaluated in the preprocess step of commands that use _command strings_ (which is only `run`, `alias`, and `bind`).

By default, if the evaluated command output has a space in it, the return value will be encapsulated in quote marks so that the entire value is perceived as one argument to Cmdr. In cases where it's desirable for Cmdr to parse each word as a separate argument, you can use use a literal syntax: `run teleport ${{"echo first second"}}` (in this example, "first" and "second" would then become the first and second arguments to the `teleport` command, instead of the first argument being "first second")

## # Run

Run is the simplest of the bunch, and does right what it says on the tin. It runs whatever text you give it immediately as a command. This is useful, because it evaluates embedded commands within the command string before running.

    run ${{"echo kill me"}}

1

Commands can contain more than one distinct command, delimited by `&&`. This can be escaped by adding an additional ampersand, for example: `&&&`. You can escape an additional level by adding more. `&&&&` is a two level deep escape.

When using `&&`, you can access the previous command's output by using the `||` slot operator. For example

`run echo evaera && kill ||` (evaera dies)

The `run` command has a single-character alias, `>`, which can also be used to invoke it.

## # Bind

Bind is a command that allows you to run a certain command string every time some event happens. The default bind type is by user input (mouse or keyboard input), but you can also bind to other events.

This is very powerful: You could define a command, like `cast_ability`, which casts a certain move in your game. Then, you could have a keybindings menu that allows the user to rebind keys, and whenever they do, it runs `CmdrClient:Run("bind", keyCode.Name, "cast_ability", abilityId)` in the background. By separating the user input from our hypothetical ability code, our code is made more robust as we can now trigger abilities from a number of possible events, in addition to the bound key.

If you prefix the first argument with `@`, you can instead select a player to bind to, which will run this command string every time that player chats. You can get the chat text by using `$1` in your command string.

In the future, you will be able to bind to network events as described in the previous section by prefixing the first argument with `!`.

The `unbind` command can be used to unbind anything that `bind` can bind.

## # Alias

The alias command lets you create a new, single command out of a command string. Alias commands can contain more than one distinct command, delimited by `&&`. You can also accept arguments from the command with `$1` through `$5`.

    alias farewell announce Farewell, $1! && kill $1

1

Then, if we run `farewell evaera`, it would make an announcement saying "Farewell, evaera!" and then kill the player called "evaera".

As another example, you could create a command that killed anyone your mouse was currently hovering over like so:

    alias pointer_of_death kill ${hover}

1

### # Types and Descriptions

You can optionally provide types, names, and descriptions to your alias arguments, like so: `$1{type|Name|Description here}`. For example:

    alias goodbye kill $1{player|Player|The player you want to kill.}

1

Name and Description are optional. These are all okay:

  * `alias goodbye kill $1{player}`
  * `alias goodbye kill $1{player|Player}`
  * `alias goodbye kill $1{player|Player|The player you want to kill.}`

Additionally, you can supply a description for the command itself:

    alias "goodbye|Kills a player." kill $1{player|Player|The player you want to kill.}

1

← [ Network Event Handlers ](https://eryn.io/Cmdr/guide/NetworkEventHandlers.html) [ ArgumentContext ](https://eryn.io/Cmdr/api/ArgumentContext.html) →


# Registry

The registry handles registering commands, types, and hooks. Exists on both client and server.

## Types

### # `TypeDefinition`

`interface ``TypeDefinition {``

DisplayName: `````string`````

Optionally overrides the user-facing name of this type in the autocomplete menu. If omitted, the registered name of this type will be used.

Prefixes: `````string`````

String containing default [Prefixed Union Types](https://eryn.io/Cmdr/guide/Commands.html#prefixed-union-types) for this type. This property should omit the initial type name, so this string should begin with a prefix character, e.g. `Prefixes = "# integer ! boolean"`.

Transform: ````````nil``` | ```function(

rawText: ``string``,
executor: ``Player``

) → ``T``````````

Transform is an optional function that is passed two values: the raw text, and the player running the command. Then, whatever values this function returns will be passed to all other functions in the type (`Validate`, `Autocomplete`, and `Parse`).

Validate: ````````nil``` | ```function(value: ``T``) → ``boolean``, ``string?``````````

The `Validate` function is passed whatever is returned from the Transform function (or the raw value if there is no Transform function). If the value is valid for the type, it should return `true`. If it the value is invalid, it should return two values: false, and a string containing an error message.

If this function isn't present, anything will be considered valid.

ValidateOnce: ````````nil``` | ```function(value: ``T``) → ``boolean``, ``string?``````````

This function works exactly the same as the normal `Validate` function, except it only runs once (after the user presses Enter). This should only be used if the validation process is relatively expensive or needs to yield. For example, the PlayerId type uses this because it needs to call `GetUserIdFromNameAsync` in order to validate.

For the vast majority of types, you should just use `Validate` instead.

Autocomplete: ````````nil``` | ```function(value: ``T``) → ``array<string>``, `````nil``` | `{``

IsPartial: `````boolean?`````

If `true`, pressing Tab to auto complete won't continue onwards to the next argument.

``}```````````

Should only be present for types that are possible to be auto completed. It should return an array of strings that will be displayed in the auto complete menu. It can also return a second value, which can be a dictionary with options such as `IsPartial` as described above.

Parse: `````function(value: ``T``) → ``any```````

Parse is the only required function in a type definition. It is the final step before the value is considered finalized. This function should return the actual parsed value that will be sent to the command functions.

Default: ````````nil``` | ```function(player: ``Player``) → ``string``````````

The `Default` function is optional and should return the "default" value for this type, as a **string**. For example, the default value of the `players` type is the name of the player who ran the command.

Listable: `````boolean?`````

If you set the optional key `Listable` to `true` in your table, this will tell Cmdr that comma-separated lists are allowed for this type. Cmdr will automatically split the list and parse each segment through your Transform, Validate, Autocomplete, and Parse functions individually, so you don't have to change the logic of your Type at all.

The only limitation is that your Parse function **must return a table**. The tables from each individual segment's Parse will be merged into one table at the end of the parse step. The uniqueness of values is ensured upon merging, so even if the user lists the same value several times, it will only appear once in the final table.

### # `CommandArgument`

`interface ``CommandArgument {``

Type: ````````string``` | ```TypeDefinition````````

The argument type (case sensitive), or an inline TypeDefinition object

Name: `````string`````

The argument name, this is displayed to the user as they type.

Description: `````string`````

A description of what the argument is, this is also displayed to the user.

Optional: `````boolean?`````

If this is present and set to `true`, then the user can run the command without filling out this value. The argument will be sent to your commands as `nil`.

Default: `````any?`````

If present, the argument will be optional and if the user doesn't supply a value, your function will receive whatever you set this to. Default being set implies Optional = true, so Optional can be omitted.

### # `CommandDefinition`

`interface ``CommandDefinition {``

Name: `````string`````

The name that's in auto complete and displayed to user.

Aliases: `````array<string>`````

Aliases that are not in the autocomplete, but if matched will run this command just the same. For example, `m` might be an alias of `announce`.

Description: `````string`````

A description of the command which is displayed to the user.

Group: `````any?`````

Optional, can be be any value you wish. This property is intended to be used in hooks, so that you can categorize commands and decide if you want a specific user to be able to run them or not.

Args: `````array<CommandArgument | function(context) → CommandArgument>`````

Array of `CommandArgument` objects, or functions that return `CommandArgument` objects.

Data: ````````nil``` | ```function(

context: ``[CommandContext](https://eryn.io/Cmdr/api/CommandContext.html#commandcontext)``,
...: ``any``

) → ``any``````````

If your command needs to gather some extra data from the client that's only available on the client, then you can define this function. It should accept the CommandContext for the current command as an argument, and return a single value which will be available in the command with [CommandContext.GetData](https://eryn.io/Cmdr/api/CommandContext.html#getdata).

ClientRun: ````````nil``` | ```function(

context: ``[CommandContext](https://eryn.io/Cmdr/api/CommandContext.html#commandcontext)``,
...: ``any``

) → ``string?``````````

If you want your command to run on the client, you can add this function to the command definition itself. It works exactly like the function that you would return from the Server module.

  * If this function returns a string, the command will run entirely on the client and won't touch the server (which means server-only hooks won't run).
  * If this function doesn't return anything, it will fall back to executing the Server module on the server.

WARNING

If this function is present and there isn't a Server module for this command, it is considered an error to not return a string from this function.

AutoExec: `````array<string>`````

A list of commands to run automatically when this command is registered at the start of the game. This should primarily be used to register any aliases regarding this command with the built-in `alias` command, but can be used for initializing state as well. Command execution will be deferred until the end of the frame.

## Properties

### # `Cmdr`

`Registry.Cmdr: `````[Cmdr](https://eryn.io/Cmdr/api/Cmdr.html#cmdr) | [CmdrClient](https://eryn.io/Cmdr/api/CmdrClient.html#cmdrclient)``````

A reference to Cmdr. This may either be the server or client version of Cmdr depending on where the code is running.

## Instance Methods

### # `RegisterTypesIn` server only

`Registry.``RegisterTypesIn(container: ``Instance``) → ```

Registers all types from within a container.

#### Parameters

Name | Type | Required |
---|---|---|---
`container` | ```Instance``` |  ✔  |

#### Returns

Type |

### # `RegisterType`

`Registry.``RegisterType(

name: ``string``,
typeDefinition: ``TypeDefinition``

) → ```

Registers a type. This function should be called from within the type definition ModuleScript.

#### Parameters

Name | Type | Required |
---|---|---|---
`name` | ```string``` |  ✔  |
`typeDefinition` | ```TypeDefinition``` |  ✔  |

#### Returns

Type |

v1.3.0+

### # `RegisterTypePrefix`

`Registry.``RegisterTypePrefix(

name: ``string``,
union: ``string``

) → ```

Registers a [Prefixed Union Type](https://eryn.io/Cmdr/guide/Commands.html#prefixed-union-types) string for the given type. If there are already type prefixes for the given type name, they will be **concatenated**. This allows you to contribute prefixes for default types, like `players`.

#### Parameters

Name | Type | Required |
---|---|---|---
`name` | ```string``` |  ✔  |
`union` | ```string``` |  ✔  | The string should omit the initial type name, so this string should begin with a prefix character, e.g. `"# integer ! boolean"`.

#### Returns

Type |

v1.3.0+

### # `RegisterTypeAlias`

`Registry.``RegisterTypeAlias(

name: ``string``,
union: ``string``

) → ```

Allows you to register a name which will be expanded into a longer type which will can be used as command argument types. For example, if you register the alias `"stringOrNumber"` it could be interpreted as `"string # number"` when used.

#### Parameters

Name | Type | Required |
---|---|---|---
`name` | ```string``` |  ✔  |
`union` | ```string``` |  ✔  | The string should _include_ the initial type name, e.g. `"string # integer ! boolean"`.

#### Returns

Type |

### # `GetType`

`Registry.``GetType(name: ``string``) → ``TypeDefinition?`````

Returns a type definition with the given name, or nil if it doesn't exist.

#### Parameters

Name | Type | Required |
---|---|---|---
`name` | ```string``` |  ✔  |

#### Returns

Type |
```TypeDefinition?``` |

v1.3.0+

### # `GetTypeName`

`Registry.``GetTypeName(name: ``string``) → ``string`````

Returns a type name taking aliases into account. If there is no alias, the `name` parameter is simply returned as a pass through.

#### Parameters

Name | Type | Required |
---|---|---|---
`name` | ```string``` |  ✔  |

#### Returns

Type |
```string``` |

### # `RegisterHooksIn` server only

`Registry.``RegisterHooksIn(container: ``Instance``) → ```

Registers all hooks from within a container on both the server and the client. If you want to add a hook to the server or the client only (not on both), then you should use the [Registry.RegisterHook](https://eryn.io/Cmdr/api/Registry.html#registerhook) method directly by requiring Cmdr in a server or client script.

#### Parameters

Name | Type | Required |
---|---|---|---
`container` | ```Instance``` |  ✔  |

#### Returns

Type |

### # `RegisterCommandsIn` server only

`Registry.``RegisterCommandsIn(

container: ``Instance``,
filter?: ``function(command: ``CommandDefinition``) → ``boolean````

) → ```

Registers all commands from within a container.

#### Parameters

Name | Type | Required |
---|---|---|---
`container` | ```Instance``` |  ✔  |
`filter` |  ```function(command: ``CommandDefinition``) → ``boolean````` Details #### Parameters | Name | Type | Required |
---|---|---|---
`command` | ```CommandDefinition``` |  ✔  |

#### Returns

Type |
```boolean``` |

✘  | If present, will be passed a command definition which will then only be registered if the function returns `true`.

#### Returns

Type |

### # `RegisterCommand` server only

`Registry.``RegisterCommand(

commandScript: ``ModuleScript``,
commandServerScript?: ``ModuleScript?``,
filter?: ``function(command: ``CommandDefinition``) → ``boolean````

) → ```

Registers an individual command directly from a module script and possible server script. For most cases, you should use [Registry.RegisterCommandsIn](https://eryn.io/Cmdr/api/Registry.html#registercommandsin) instead.

#### Parameters

Name | Type | Required |
---|---|---|---
`commandScript` | ```ModuleScript``` |  ✔  |
`commandServerScript` | ```ModuleScript?``` |  ✘  |
`filter` |  ```function(command: ``CommandDefinition``) → ``boolean````` Details #### Parameters | Name | Type | Required |
---|---|---|---
`command` | ```CommandDefinition``` |  ✔  |

#### Returns

Type |
```boolean``` |

✘  | If present, will be passed a command definition which will then only be registered if the function returns `true`.

#### Returns

Type |

### # `RegisterDefaultCommands` server only

1. `Registry.``RegisterDefaultCommands(groups: ``array<string>``) → ```

2. `Registry.``RegisterDefaultCommands(groups: ``array<string>``) → ```

3. `Registry.``RegisterDefaultCommands(groups: ``array<string>``) → ```

4. `Registry.``RegisterDefaultCommands(groups: ``array<string>``) → ```

5. `Registry.``RegisterDefaultCommands(groups: ``array<string>``) → ```

6. `Registry.``RegisterDefaultCommands(groups: ``array<string>``) → ```

7. `Registry.``RegisterDefaultCommands(filter: ``function(command: ``CommandDefinition``) → ``boolean````) → ```

Registers the default set of commands.

📚 Showing overload 1 of 7

#### Parameters

Name | Type | Required |
---|---|---|---
`groups` | ```array<string>``` |  ✔  | Limit registration to only commands which have their `Group` property set to thes.

#### Returns

Type |

### # `GetCommand`

`Registry.``GetCommand(name: ``string``) → ``CommandDefinition?`````

Returns the CommandDefinition of the given name, or nil if not registered. Command aliases are also accepted.

#### Parameters

Name | Type | Required |
---|---|---|---
`name` | ```string``` |  ✔  |

#### Returns

Type |
```CommandDefinition?``` |

### # `GetCommands`

`Registry.``GetCommands() → ``array<CommandDefinition>`````

Returns an array of all commands (aliases not included).

#### Returns

Type |
```array<CommandDefinition>``` |

### # `GetCommandNames`

`Registry.``GetCommandNames() → ``array<string>`````

Returns an array of all command names.

#### Returns

Type |
```array<string>``` |

### # `RegisterHook`

`Registry.``RegisterHook(

hookName: ``"BeforeRun" | "AfterRun"``,
callback: ``function(context: ``[CommandContext](https://eryn.io/Cmdr/api/CommandContext.html#commandcontext)``) → ``string?````,
priority?: ``number?``

) → ```

Adds a hook. This should probably be run on the server, but can also work on the client. Hooks run in order of priority (lower number runs first).

#### Parameters

Name | Type | Required |
---|---|---|---
`hookName` | ```"BeforeRun" | "AfterRun"``` |  ✔  |
`callback` |  ```function(context: ``[CommandContext](https://eryn.io/Cmdr/api/CommandContext.html#commandcontext)``) → ``string?````` Details #### Parameters | Name | Type | Required |
---|---|---|---
`context` | ```[CommandContext](https://eryn.io/Cmdr/api/CommandContext.html#commandcontext)``` |  ✔  |

#### Returns

Type |
```string?``` |

✔  |
`priority` | ```number?``` |  ✘  |

#### Returns

Type |

### # `GetStore`

`Registry.``GetStore(name: ``string``) → ``table`````

Returns a table saved with the given name. This is the same as [CommandContext.GetStore](https://eryn.io/Cmdr/api/CommandContext.html#getstore)

#### Parameters

Name | Type | Required |
---|---|---|---
`name` | ```string``` |  ✔  |

#### Returns

Type |
```table``` |

← [ Dispatcher ](https://eryn.io/Cmdr/api/Dispatcher.html) [ Util ](https://eryn.io/Cmdr/api/Util.html) →


# # Network Event Handlers

Some commands that run on the server might need to also do something on the client, or on every client. Network event handlers are callback functions that you can set to run when a server command sends a message back to the client. Only one handler can be set to a certain event at a time, so it's possible to change the handler for a specific event without needing to re-implement the entire command yourself.

For example, consider the default `announce` command, which creates a message on every player's screen. By default, this creates a system chat message with the given text, because Cmdr has a default event handler for the `"Message"` event, which the `announce` command broadcasts,

If you wanted to display announcements some other way, you could just override the default event handler:

    CmdrClient:HandleEvent("Message", function (text, player)
        print("Announcement from", player.Name, text)
    end)

1
2
3

You can send events from your own commands on the server (or to the local player if in a client-only command) by using `context:SendEvent(player, ...)` and `context:BroadcastEvent(...)`. The built-in `context:Reply(text)` method actually uses `SendEvent` under the hood, whose default handler on the client is set to just add a new line to the console window with the given text.

← [ Hooks ](https://eryn.io/Cmdr/guide/Hooks.html) [ Meta-Commands ](https://eryn.io/Cmdr/guide/MetaCommands.html) →


DevForum: https://devforum.roblox.com/t/gradien-parallelized-machine-deep-learning/4055552

Wally: https://wally.run/package/imezx/gradien


🚀

## Parallel-first Compute

Heavy numeric operations (matrix multiplication, element-wise math) are dispatched to parallel threads, unlocking performance impossible in serial Luau.


# Getting Started

Welcome to **Gradien**. This guide will help you set up the library and train your first neural network.

## Installation

### `Method 1: Wally` Recommended

If you use [Wally](https://wally.run/) for dependency management, add Gradien to your `wally.toml`.

wally.tomlTerminal

toml

    [dependencies]
    Gradien = "eternitydevs/gradien@1.4.0-rc5"

bash

    wally install

### `Method 2: RBXM`

  1. Download the latest release from the [GitHub Releases](https://github.com/imezx/Gradien/releases) page.
  2. Drag and drop the `.rbxm` file into **ReplicatedStorage** in Roblox Studio.

## Your First Training Loop

Let's create a simple model that learns to approximate a linear function.

### `Step 1: Setup`

Require the library and define a basic dataset.

lua

    local Gradien = require(game.ReplicatedStorage.Gradien)

    -- Create dummy data: Inputs (X) and Targets (Y)
    -- Shape: {Features=2, Batch=5}
    local X = Gradien.Tensor.fromArray({
        1, 2, 3, 4, 5,
        1, 2, 3, 4, 5
    }, {2, 5})

    local Y = Gradien.Tensor.fromArray({
        2, 4, 6, 8, 10
    }, {1, 5})

### `Step 2: Define Model`

We will use a `Sequential` container with `Linear` layers and `ReLU` activations.

lua

    local model = Gradien.NN.Sequential({
        Gradien.NN.Linear(2, 8),             -- Input -> Hidden
        function(_, x) return Gradien.NN.Activations.ReLU(x) end,
        Gradien.NN.Linear(8, 1)              -- Hidden -> Output
    })

### `Step 3: Trainer`

Use the `Trainer` class to handle the training loop, backpropagation, and optimization automatically.

lua

    local trainer = Gradien.Trainer.new({
        model = model,
        optimizerFactory = function(params)
            return Gradien.Optim.Adam(params, 1e-2)
        end,
        loss = Gradien.NN.Losses.mse_backward,
        metric = function(pred, target)
            -- Custom metric logic here
            return 0
        end
    })

    -- Start training for 100 epochs
    trainer:fit(function()
        -- Dataloader generator
        return function() return X, Y end
    end, { epochs = 100 })


# Tensor Core

The `Tensor` is the fundamental data structure in Gradien. It represents a multi-dimensional array and supports automatic differentiation.

## Constructors

### `.zeros` Parallel

Creates a new tensor filled with zeros.

Definition

lua

    (shape: {number}, dtype: "f32"|"f64"|"i32"?, requiresGrad: boolean?) -> Tensor

### `.ones` Parallel

Creates a new tensor filled with ones.

Definition

lua

    (shape: {number}, dtype: "f32"|"f64"|"i32"?, requiresGrad: boolean?) -> Tensor

### `.fromArray`

Creates a tensor from a flat table.

Definition

lua

    (data: {number}, shape: {number}, dtype: "f32"|"f64"?, requiresGrad: boolean?) -> Tensor

### `.randn` Parallel

Creates a tensor with random numbers from a normal distribution (mean 0, std 1).

Definition

lua

    (shape: {number}, dtype: "f32"|"f64"?, requiresGrad: boolean?) -> Tensor

### `.empty`

Creates an uninitialized tensor (allocated but not zeroed).

Definition

lua

    (shape: {number}, dtype: "f32"|"f64"?, requiresGrad: boolean?) -> Tensor

## Methods

### `:reshape`

Returns a new tensor with the same data but a different shape.

Definition

lua

    (self: Tensor, newShape: {number}) -> Tensor

### `:expand` Parallel

Returns a new view of the tensor with singleton dimensions expanded to a larger size.

Definition

lua

    (self: Tensor, newShape: {number}) -> Tensor

### `:transpose` Parallel

Permutes two dimensions of the tensor.

Definition

lua

    (self: Tensor, dim1: number?, dim2: number?) -> Tensor

### `:slice` Parallel

Extracts a sub-tensor from the given dimension.

Definition

lua

    (self: Tensor, dim: number, startIdx: number, endIdx: number?, step: number?) -> Tensor

### `:narrow`

Returns a new tensor that is a narrowed version of the input tensor along dimension `dim`.

Definition

lua

    (self: Tensor, dim: number, startIdx: number, length: number) -> Tensor

### `:sum` Parallel

Returns the sum of all elements in the input tensor.

Definition

lua

    (self: Tensor, dim: number?) -> Tensor

### `:contiguous`

Returns a contiguous in memory tensor containing the same data as self tensor.

Definition

lua

    (self: Tensor) -> Tensor

### `:is_contiguous`

Returns True if the tensor is contiguous in memory in C order.

Definition

lua

    (self: Tensor) -> boolean

### `:detach`

Returns a new Tensor, detached from the current graph. The result will never require gradient.

Definition

lua

    (self: Tensor) -> Tensor

### `:noGrad`

Disables gradient recording for this specific tensor instance.

Definition

lua

    (self: Tensor) -> ()


# Porting PyTorch to Gradien Example

This show you examples bridging **PyTorch** (running on a Python server) with **Gradien** (running on Roblox). This allows you to run massive models (LLMs, heavy RL policies) on a GPU and send the results to your Roblox game in real-time.

dependenciesserverscriptmodelbridge

bash

    pip install torch fastapi uvicorn

python

    import torch
    import torch.nn as nn
    from fastapi import FastAPI, HTTPException, Request
    from fastapi.exceptions import RequestValidationError
    from fastapi.responses import JSONResponse
    from pydantic import BaseModel
    from typing import List
    import uvicorn

    app = FastAPI()

    DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
    HOST = "0.0.0.0"
    PORT = 8000
    DTYPE = torch.bfloat16

    print(f"Device: {DEVICE}")
    print(f"Waiting for requests on http://{HOST}:{PORT}...")

    class SingleInput(BaseModel):
        id: str
        data: List[float]

    class BatchRequest(BaseModel):
        shape: List[int]
        batch: List[SingleInput]

    class ProductionModel(nn.Module):
        def __init__(self):
            super().__init__()
            # ex: input 10 -> output 5
            self.net = nn.Sequential(nn.Linear(10, 64), nn.ReLU(), nn.Linear(64, 5))

        def forward(self, x):
            return self.net(x)

    model = ProductionModel().to(DEVICE).to(dtype=DTYPE)
    model.eval()

    @app.exception_handler(RequestValidationError)
    async def validation_exception_handler(request: Request, exc):
        print(f"Error details: {exc.errors()}")
        return JSONResponse(status_code=422, content={"detail": exc.errors()})

    @app.get("/")
    def home():
        return {"status": "online", "message": "Gradien Bridge is Running"}

    @app.post("/predict_batch")
    async def predict_batch(req: BatchRequest):
        if not req.batch:
            return {"results": []}
        try:
            batch_data = [item.data for item in req.batch]
            input_tensor = (
                torch.tensor(batch_data, dtype=torch.float32).to(DEVICE).to(dtype=DTYPE)
            )
            if len(req.shape) > 1:
                true_shape = [-1] + req.shape
                input_tensor = input_tensor.view(*true_shape)
            with torch.no_grad():
                output_tensor = model(input_tensor)
            results = []
            output_data = output_tensor.to(dtype=torch.float32).cpu().numpy()
            for i, item in enumerate(req.batch):
                results.append({"id": item.id, "data": output_data[i].flatten().tolist()})
            return {"shape": list(output_tensor.shape[1:]), "results": results}
        except Exception as e:
            print(f"Error: {e}")
            raise HTTPException(status_code=500, detail=str(e))

    if __name__ == "__main__":
        uvicorn.run(app, host=HOST, port=PORT)

lua

    local RemoteModel = require(script.Parent.Model)
    local Gradien = require(game.ReplicatedStorage.Gradien)
    local Tensor = Gradien.Tensor

    local brain = RemoteModel.new({10})

    brain.event.Event:Connect(function(outputTensor)
        if outputTensor then
            print("Server Output:", outputTensor._storage)
        end
    end)

    while true do
        task.wait()
        local data = table.create(10, 0)
        for i=1,10 do data[i] = math.random() end
        local input = Tensor.fromArray(data, {1, 10})
        brain:forward(input)
    end

lua

    local BridgeService = require(script.Parent.ModuleScript)
    local Gradien = require(game.ReplicatedStorage.Gradien)

    local Model = {}
    Model.__index = Model

    function Model.new(inputShape)
        local self = setmetatable({}, Model)
        self.inputShape = inputShape
        self.event = Instance.new("BindableEvent")
        return self
    end

    function Model:forward(inputTensor)
        local event = self.event
        local flatData = inputTensor._storage
        if not flatData then
            warn("inputTensor._storage is missing.")
            flatData = inputTensor.data
        end
        assert(flatData, "Model: Cannot send request. Tensor data is missing.")
        BridgeService.Predict(flatData, self.inputShape, function(resultData, resultShape)
            if not resultData then
                warn("inference failed.")
                event:Fire(nil)
                return
            end
            local outputTensor = Gradien.Tensor.fromArray(resultData, resultShape)
            event:Fire(outputTensor)
        end)
    end

    return Model

lua

    local HttpService = game:GetService("HttpService")
    local RunService = game:GetService("RunService")

    local BridgeService = {}
    BridgeService.__index = BridgeService

    local CONFIG = {
        URL = "http://localhost:8000/predict_batch",
        BATCH_WINDOW = 0.05,
        MAX_BATCH_SIZE = 64,

    local queue = {}
    local pendingCallbacks = {} -- Map<ID, Function>
    local lastSendTime = 0
    local isSending = false

    local function generateGUID(): string
        return HttpService:GenerateGUID(false):gsub("-", "")
    end

    local function flushQueue()
        if #queue == 0 or isSending then return end
        lastSendTime = os.clock()
        isSending = true
        local currentBatch = queue
        queue = {}
        local cleanBatch = {}
        for i, item in ipairs(currentBatch) do
            cleanBatch[i] = {
                id = item.id,
                data = item.data
        end
        local payload = {
            shape = currentBatch[1].shape,
            batch = cleanBatch
        task.spawn(function()
            local success, response = pcall(function()
                return HttpService:PostAsync(
                    CONFIG.URL,
                    HttpService:JSONEncode(payload),
                    Enum.HttpContentType.ApplicationJson,
                    false
                )
            end)
            if success then
                local decoded = HttpService:JSONDecode(response)
                for _, result in ipairs(decoded.results) do
                    local reqId = result.id
                    local callback = pendingCallbacks[reqId]
                    if callback then
                        callback(result.data, decoded.shape)
                        pendingCallbacks[reqId] = nil
                    end
                end
            else
                warn(`HTTP Failed: {response}`)
                for _, item in ipairs(currentBatch) do
                    local cb = pendingCallbacks[item.id]
                    if cb then cb(nil, "Server Error") end
                    pendingCallbacks[item.id] = nil
                end
            end
            isSending = false
            if #queue > 0 then
                task.delay(CONFIG.BATCH_WINDOW, flushQueue)
            end
        end)
    end

    function BridgeService.Predict(inputData, inputShape, callback)
        local id = generateGUID()
        pendingCallbacks[id] = callback
        table.insert(queue, {
            id = id,
            data = inputData,
            shape = inputShape
        })
        if #queue >= CONFIG.MAX_BATCH_SIZE then
            flushQueue()
        end
    end

    RunService.PostSimulation:Connect(function()
        if #queue > 0 and (os.clock() - lastSendTime > CONFIG.BATCH_WINDOW) then
            flushQueue()
        end
    end)

    return BridgeService


# Math Operations Parallel

Located in `Gradien.Ops.Math` and `Gradien.Ops.BLAS`. These operations are parallelized.

## Element-wise

All element-wise operations support broadcasting semantics implicitly if implemented in the kernel.

### `.add`

Definition

lua

    (A: Tensor, B: Tensor) -> Tensor

### `.sub`

Definition

lua

    (A: Tensor, B: Tensor) -> Tensor

### `.mul`

Definition

lua

    (A: Tensor, B: Tensor) -> Tensor

### `.scalarAdd`

Adds a scalar value `s` to every element of `A`.

Definition

lua

    (A: Tensor, s: number) -> Tensor

### `.scalarMul`

Multiplies every element of `A` by scalar `s`.

Definition

lua

    (A: Tensor, s: number) -> Tensor

## Linear Algebra

### `.matmul`

Performs Matrix Multiplication.

Definition

lua

    (A: Tensor, B: Tensor) -> Tensor


# Tokenizers

The `Gradien.Tokenizers` module provides a comprehensive toolkit for text tokenization, inspired by the Hugging Face Tokenizers library. It supports Byte-Pair Encoding (BPE), normalization, pre-tokenization, and post-processing.

## Tokenizer Class

The main entry point is the `Tokenizer` class, which coordinates the tokenization pipeline.

### Constructor

Definition

lua

    Tokenizer.new(model: Model) -> Tokenizer

Creates a new Tokenizer with the specified model (e.g., BPE).

### Methods

#### `:encode`

Encodes a text (and optional pair text) into a sequence of tokens/IDs.

Definition

lua

    (text: string, pair: string?) -> Encoding

Returns an `Encoding` object containing:

  * `ids`: List of token IDs.
  * `tokens`: List of token strings.
  * `attention_mask`: Mask identifying valid tokens (1) vs padding (0).
  * `special_tokens_mask`: Mask identifying special tokens.
  * `type_ids`: Segment IDs (if pair is provided).
  * `offsets`: (Currently empty/reserved).

#### `:decode`

Decodes a list of IDs back into a string.

Definition

lua

    (ids: {number}) -> string

#### `:train_from_iterator`

Trains the tokenizer model using an iterator that yields strings.

Definition

lua

    (iterator: () -> string?, trainer: Trainer) -> ()

#### Pipeline Configuration

You can customize the tokenizer pipeline using the following setters:

  * `:set_normalizer(n: Normalizer)`
  * `:set_pre_tokenizer(pt: PreTokenizer)`
  * `:set_post_processor(pp: PostProcessor)`
  * `:set_decoder(d: Decoder)`

#### Serialization

Save and load the tokenizer configuration.

DumpLoad

lua

    :dump() -> table

lua

    Tokenizer.from_dump(data: table) -> Tokenizer

## Components

### Models

  * **BPE**: Byte-Pair Encoding model.

### Normalizers

  * **NFKC**: Unicode normalization form KC.

### Pre-Tokenizers

  * **ByteLevel**: Splits on bytes.
  * **Whitespace**: Splits on whitespace.

### Decoders

  * **BPEDecoder**: Decodes BPE tokens.

### Processors

  * **ByteLevel**: Post-processing for byte-level BPE.

## Example Usage

lua

    local Tokenizers = Gradien.Tokenizers
    local BPE = Tokenizers.models.BPE
    local Tokenizer = Tokenizers.Tokenizer

    -- Create a BPE model
    local model = BPE.new()
    local tokenizer = Tokenizer.new(model)

    -- Setup pipeline
    tokenizer:set_normalizer(Tokenizers.normalizers.NFKC.new())
    tokenizer:set_pre_tokenizer(Tokenizers.pre_tokenizers.ByteLevel.new())
    tokenizer:set_decoder(Tokenizers.decoders.BPEDecoder.new())

    -- Train (simplified example)
    local trainer = Tokenizers.trainers.BpeTrainer.new({
        vocab_size = 1000,
        min_frequency = 2,
        special_tokens = {"<unk>", "<s>", "</s>"}
    })

    local data = {"Hello world", "Hello universe"}
    local idx = 0
    local function iterator()
        idx += 1
        return data[idx]
    end

    tokenizer:train_from_iterator(iterator, trainer)

    -- Encode
    local encoding = tokenizer:encode("Hello world")
    print(encoding.tokens)
    -- Output: {"Hello", "Ġworld"} (example)

    -- Decode
    local text = tokenizer:decode(encoding.ids)
    print(text)
    -- Output: "Hello world"


# The Trainer Loop Feature

Writing custom training loops can be repetitive. The `Trainer` class abstracts the boilerplate of zeroing gradients, forward passes, loss calculation, backpropagation, and optimization steps.

## Basic Usage

ConfigFit

lua

    local trainer = Gradien.Trainer.new({
        model = myModel,
        optimizerFactory = function(params) return Gradien.Optim.Adam(params) end,
        loss = Gradien.NN.Losses.mse_backward,

        -- Optional
        metric = function(pred, target) return 0 end,
        reportEvery = 10,
        callbacks = {
            onStep = function(ctx) print(ctx.loss) end
    })

lua

    trainer:fit(function()
        -- Return a function that returns (X, Y) batches
        return MyDataLoader()
    end, {
        epochs = 50,
        stepsPerEpoch = 100
    })

## Classification Trainer

For classification tasks, `Trainer.newClassification` provides sensible defaults (Cross Entropy Loss and Accuracy metric).

lua

    local clsTrainer = Gradien.Trainer.newClassification({
        model = myModel,
        optimizerFactory = myOptFactory,
        callbacks = myCallbacks
    }, {
        smoothing = 0.1 -- Label smoothing
    })

## Callbacks

The trainer supports a rich callback system to hook into the training process.

lua

    callbacks = {
        onStep = function(ctx)
            -- ctx: { epoch, step, loss, metric, model, optimizer }
        end,
        onEpochEnd = function(ctx)
            print("End of epoch:", ctx.epoch)
        end,
        onBest = function(ctx)
            print("New best metric:", ctx.metric)
        end


# Autograd (Tape) Core

The `Tape` module records operations and manages the backward pass.

## Functions

### `.backwardFrom` Parallel

Computes the gradient of current tensor w.r.t. graph leaves.

DefinitionExample

lua

    (y: Tensor, grad: Tensor) -> ()

lua

    Tape.backwardFrom(loss, Tensor.ones(loss._shape))

### `.grad`

Computes and returns the sum of gradients of outputs with respect to the inputs.

Definition

lua

    (f: (...any) -> Tensor, inputs: {Tensor}) -> {Tensor?}

### `.noGrad`

Disables gradient tracking for the duration of the function `fn`. Useful for inference.

DefinitionExample

lua

    (fn: () -> ()) -> ()

lua

    Tape.noGrad(function()
        -- Operations here won't be recorded
        local pred = model:forward(input)
    end)

### `.makeNode`

Internal function used to register a new operation in the computation graph.

Definition

lua

    (out: Tensor, parents: {Tensor}, back: (grad: Tensor) -> ()) -> Tensor


# Core Concepts

## Tensors Core

The `Tensor` is the fundamental data structure in Gradien. It is a multi-dimensional array that supports automatic differentiation and parallelized operations.

## Autograd (The Tape)

Gradien uses a **Tape-based** autograd system. Operations on tensors that have `requiresGrad = true` are recorded in a graph. When you call `Tape.backwardFrom`, gradients flow backwards through this graph.

lua

    local x = G.Tensor.fromArray({2, 3}, {2, 1}, "f32", true)
    local W = G.Tensor.ones({2, 2}, "f32", true)

    -- Forward pass
    local y = G.Math.matmul(W, x)

    -- Backward pass
    local grad = G.Tensor.ones(y._shape)
    G.Autograd.Tape.backwardFrom(y, grad)

    -- Access gradients
    print(W._grad)


# Learning Rate Schedulers Utils

Located in `Gradien.Optim.Schedulers`. These functions return a callback `(step) -> newLr`.

## Standard

### `step`

Decays LR by `gamma` every `stepSize`.

lua

    local sched = Schedulers.step(lr, 0.9, 100)

### `cosine`

Cosine annealing from `lr` down to `lrMin` over `T` steps.

lua

    local sched = Schedulers.cosine(1e-3, 1e-6, 1000)

### `cosineRestarts` Parallel

Cosine annealing with warm restarts. `T0` is initial period, `Tmult` scales period after restart.

lua

    local sched = Schedulers.cosineRestarts(1e-3, 100, 2.0)

## Advanced

### `warmupCosine`

Linearly warms up from 0 to `lr`, then decays via cosine.

lua

    local sched = Schedulers.warmupCosine(1e-3, 100, 1000)

### `oneCycle`

1-Cycle policy. rapid increase to `lrMax` then decay.

lua

    local sched = Schedulers.oneCycle(maxLr, minLr, warmupSteps, totalSteps)


# QIMHNN Experimental

**Quantum-Inspired Metaheuristic Neural Network**

This module implements a neural network architecture inspired by quantum mechanics concepts (Superposition, Interference, and Entanglement) to potentially escape local minima and improve generalization.

## Constructor

Located in `Gradien.Experimental.Models.QIMHNN`.

DefinitionConfigurationExample

lua

    (config: QIMHNNConfig) -> Module

lua

    type QIMHNNConfig = {
        inputDim: number,
        outputDim: number,
        hiddenDims: {number}?,     -- e.g. {64, 64}

        -- Quantum Features
        useSuperposition: boolean?, -- Default: true
        useInterference: boolean?,  -- Default: true
        useEntanglement: boolean?,  -- Default: true
        quantumAmplitude: number?,  -- Amplitude factor for |z| (default 0.1)

        -- Standard Features
        activation: string?,       -- Default activation (e.g. "ReLU")
        finalActivation: string?,  -- Output activation
        dropout: number?,          -- Dropout probability
        layerNorm: boolean?        -- Apply LayerNorm

lua

    local model = Gradien.Experimental.Models.QIMHNN({
        inputDim = 10,
        outputDim = 2,
        hiddenDims = {32}, -- depth: 1
        useSuperposition = true,
        useInterference = true
    })

## Concepts

  * **Superposition**: Weights utilize both real and imaginary components. The output incorporates a magnitude term `|z|`.
  * **Interference**: Scales the output based on the phase difference between real and imaginary parts, simulating wave interference.
  * **Entanglement**: Adds a dense connection `E` that mixes state information across the layer, simulating particle entanglement.


# Optimizers Optimization

Gradien includes a wide variety of optimizers for different use cases.

## Adaptive Methods

### `Adam`

Adaptive Moment Estimation. Good default. Supports L2 weight decay (applied to gradients).

ConstructorExample

lua

    (params: {Tensor}, lr: number, b1: num?, b2: num?, eps: num?, weight_decay: num?) -> Optimizer

lua

    local opt = Gradien.Optim.Adam(params, 0.001, 0.9, 0.999, 1e-8, 0.01) -- with weight decay

**Note:** Adam with `weight_decay` applies L2 regularization by modifying gradients. For decoupled weight decay, use `AdamW` instead.

### `AdamW` Modern

Adam with decoupled weight decay. Often generalizes better than Adam.

Constructor

lua

    (
        params: {Tensor},
        lr: number,
        wd: number, -- Weight Decay
        b1: number?,
        b2: number?,
        eps: number?
    ) -> Optimizer

### `Lion` New

Evolved Sign Momentum. Memory efficient and often faster than Adam.

Constructor

lua

    (
        params: {Tensor},
        lr: number,
        beta1: number?, -- default 0.9
        beta2: number?, -- default 0.99
        weightDecay: number?
    ) -> Optimizer

### `Adafactor`

Memory-efficient adaptive optimization. Can operate in 2D factored mode to save memory on large matrices.

Constructor

lua

    (
        params: {Tensor},
        lr: number,
        beta2: number?,
        eps: number?,
        clipThreshold: number?,
        weightDecay: number?
    ) -> Optimizer

### `RMSProp`

Maintains a moving average of the squared gradient.

Constructor

lua

    (params: {Tensor}, lr: number, decay: number?, eps: number?) -> Optimizer

### `Adagrad`

Adapts learning rates based on the frequency of parameters updates.

Constructor

lua

    (params: {Tensor}, lr: number, eps: number?) -> Optimizer

## Stochastic Methods

### `SGD`

Stochastic Gradient Descent with Momentum and Nesterov acceleration.

Constructor

lua

    (params: {Tensor}, lr: number, momentum: number?, nesterov: boolean?) -> Optimizer


# How to Create a Neural Network Tutorial

This guide will walk you through creating, configuring, and training a simple model to learn a mathematical pattern.

We will teach the model the function: **`y = 2x`**.

## 1. Require the Library

Start by requiring the Gradien module.

lua

    local Gradien = require(game.ReplicatedStorage.Gradien)

## 2. Prepare Your Data

We will generate training data for numbers 1 through 20.

  * **Inputs (X)**: The numbers 1, 2, 3...
  * **Targets (Y)**: The answers 2, 4, 6...

Data Generation

lua

    -- Generate 20 data points
    local count = 20
    local inputTable = {}
    local targetTable = {}

    for i = 1, count do
        inputTable[i] = i
        targetTable[i] = i * 2 -- The rule we want to learn
    end

    -- Create Tensors {Features, BatchSize}
    local X = Gradien.Tensor.fromArray(inputTable, {1, count})
    local Y = Gradien.Tensor.fromArray(targetTable, {1, count})

## 3. Build the Model

For a simple linear relationship like `y = 2x`, a single **Linear Layer** is perfect. It learns a weight (`m`) and a bias (`c`) to solve `y = mx + c`.

Why no Hidden Layers?

Complex networks with activation functions (like ReLU) are great for complex patterns but struggle to **extrapolate** simple math to numbers they haven't seen before. A single Linear layer extrapolates perfectly to infinity.

lua

    local model = Gradien.NN.Sequential({
        -- Input: 1 feature (the number)
        -- Output: 1 feature (the prediction)
        Gradien.NN.Linear(1, 1)
    })

## 4. Setup the Trainer

The `Trainer` handles the training loop.

Script Timeout

We add a **callback** to yield (`task.wait`) every few epochs. Without this, Your Roblox will crash.

lua

    local trainer = Gradien.Trainer.new({
        model = model,

        -- Optimizer: AdamW often converges faster than standard Adam
        optimizerFactory = function(params)
            return Gradien.Optim.AdamW(params, 1e-2, 1e-4) -- LR: 0.01
        end,

        loss = Gradien.NN.Losses.mse_backward,
        reportEvery = 50, -- Print less often to reduce spam

        callbacks = {
            onEpochEnd = function()
                task.wait() -- Yield to prevent crash
            end
    })

## 5. Run Training

Use the `:fit()` method to start the training loop.

lua

    print("Starting training...")

    trainer:fit(function()
        -- Return our full dataset batch
        return function() return X, Y end
    end, {
        epochs = 500,   -- 500 iterations is enough for this simple task
        stepsPerEpoch = 15
    })

    print("Training complete!")

## 6. Test the Model

Now let's test it on a number it has **never seen**, like 100!

lua

    local testVal = 100 -- lets try with 100!
    local testInput = Gradien.Tensor.fromArray({testVal}, {1, 1})

    -- Forward pass
    local prediction = model:forward(testInput)
    local result = prediction._storage[1]

    print("Input:", testVal)
    print("Prediction:", string.format("%.2f", result))
    print("Expected:", testVal * 2)


# Layers Module

Layers are the building blocks of neural networks. They store learnable parameters (`weights` and `biases`).

## `NN.Linear`

Applies a linear transformation to the incoming data: `y = x * W^T + b`.

DefinitionExample

lua

    (
        inFeatures: number,
        outFeatures: number,
        initializer: ((fanIn, fanOut) -> number)?
    ) -> Module

lua

    local layer = Gradien.NN.Linear(128, 64)

## `NN.Sequential`

A container that chains modules together. Data flows through them in the order they are defined.

DefinitionExample

lua

    (layers: { Module | (Tensor)->Tensor }) -> Module

lua

    local model = Gradien.NN.Sequential({
        Gradien.NN.Linear(10, 20),
        Gradien.NN.Linear(20, 5)
    })

## `NN.Conv2d`

Applies a 2D convolution over an input signal composed of several input planes.

DefinitionExample

lua

    (C_in: number, C_out: number, KH: number, KW: number) -> Module

lua

    local conv = Gradien.NN.Conv2d(3, 64, 3, 3) -- 3 input channels, 64 output, 3x3 kernel

## `NN.MaxPool2d`

Applies a 2D max pooling over an input signal.

DefinitionExample

lua

    (KH: number, KW: number, stride: number) -> Module

lua

    local pool = Gradien.NN.MaxPool2d(2, 2, 2) -- 2x2 kernel, stride 2

## `NN.AvgPool2d`

Applies a 2D average pooling over an input signal.

DefinitionExample

lua

    (KH: number, KW: number, stride: number) -> Module

lua

    local pool = Gradien.NN.AvgPool2d(2, 2, 2) -- 2x2 kernel, stride 2

## `NN.ConvTranspose2d`

Applies a 2D transposed convolution operator over an input image composed of several input planes.

DefinitionExample

lua

    (C_in: number, C_out: number, KH: number, KW: number) -> Module

lua

    local convT = Gradien.NN.ConvTranspose2d(64, 3, 3, 3) -- 64 input channels, 3 output, 3x3 kernel

## `NN.GroupNorm`

Applies Group Normalization over a mini-batch of inputs. Divides channels into groups and normalizes within each group independently.

DefinitionExample

lua

    (num_groups: number, num_channels: number, eps: number?) -> Module

lua

    local gn = Gradien.NN.GroupNorm(8, 64) -- 8 groups, 64 channels

**Parameters:**

  * `num_groups` (number): Number of groups to divide channels into. Must divide `num_channels` evenly.
  * `num_channels` (number): Number of channels expected in the input.
  * `eps` (number, optional): Small value added to variance for numerical stability. Default: `1e-5`.


# Gradient Clipping Parallel

Located in `Gradien.GradClip`. Used to prevent exploding gradients, especially in RNNs or deep networks.

## Functions

### `.clipValue`

Clips gradient values element-wise to be within `[-clip, clip]`.

Definition

lua

    (params: {Tensor}, clip: number) -> ()

### `.clipNorm`

Scales gradients so that their total norm does not exceed `maxNorm`. This preserves the direction of the gradient.

Definition

lua

    (params: {Tensor}, maxNorm: number) -> ()


# Feudal Networks

Implementation of Feudal Reinforcement Learning agent hierarchy.

## Feudal Agent

Creates a hierarchical agent with Manager and Worker levels.

lua

    local Feudal = Gradien.Experimental.RL.Feudal

    local agent = Feudal({
        inputDim = 32,
        actionDim = 4,
        hiddenDim = 64,
        goalDim = 64, -- Optional, defaults to hiddenDim
        horizon = 10, -- Manager update horizon
    })

### Configuration

  * `inputDim` (number): Dimension of input state
  * `actionDim` (number): Number of discrete actions
  * `hiddenDim` (number): Hidden dimension for LSTM/Linear layers
  * `goalDim` (number, optional): Dimension of goal vectors
  * `horizon` (number, optional): Steps between Manager goal updates
  * `gammaW` (number, optional): Worker discount factor
  * `gammaM` (number, optional): Manager discount factor
  * `lr` (number, optional): Learning rate
  * `optimizerFactory` (function): Factory function to create optimizer

### Methods

  * `reset(batchSize)`: Reset agent state
  * `act(state)`: Select action and current goal
  * `observe(transition)`: Store transition in buffers
  * `trainStep()`: Perform training update (placeholder)


# Experimental Optimizers Experimental

Located in `Gradien.Experimental.Optim`. These optimizers use population-based metaheuristics rather than (or in addition to) standard backpropagation.

## `SwarmPSO`

**Particle Swarm Optimization**. This is a gradient-free optimizer that maintains a swarm of model variations ("particles"). It requires an evaluation function to score each particle.

Usage

Because PSO evaluates multiple variations of the model, it does not use the standard `backward()` pass. Instead, you provide a function that calculates loss for the current state.

ConstructorConfig

lua

    (params: {Tensor}, config: SwarmPSOConfig) -> Optimizer

lua

    type SwarmPSOConfig = {
        swarmSize: number,       -- Number of particles (models)
        evalFn: (p: number) -> number, -- Callback to evaluate particle 'p' and return loss

        inertia: number?,        -- Velocity retention (default 0.7)
        cognitive: number?,      -- Attraction to personal best (default 1.5)
        social: number?,         -- Attraction to global best (default 1.5)
        lr: number?,             -- Velocity scaling factor
        mutationRate: number?,   -- Prob of random mutation
        mutationStrength: number?

## `Metaheuristic`

A hybrid optimizer that combines gradient descent with swarm-like behavior. Unlike SwarmPSO, this **does** use gradients (`param._grad`) to guide the particles, but also maintains personal/global bests to escape local minima.

ConstructorConfig

lua

    (params: {Tensor}, config: MetaheuristicConfig) -> Optimizer

lua

    type MetaheuristicConfig = {
        lr: number,              -- Learning rate
        swarmSize: number?,      -- (Internal simulation size)
        gradScale: number?,      -- Weight of the gradient signal
        inertia: number?,
        cognitive: number?,
        social: number?,
        mutationRate: number?


# Mamba

Implementation of the Mamba state space model architecture.

## MambaBlock

Creates a Mamba block with selective scan mechanism.

lua

    local MambaBlock = Gradien.Experimental.NN.MambaBlock

    -- Args: dModel, dState (default 16), dConv (default 4), expand (default 2)
    local block = MambaBlock(64, 16, 4, 2)
    local output = block:forward(input)

### Parameters

  * `dModel` (number): Model dimension
  * `dState` (number, optional): State dimension. Default: 16
  * `dConv` (number, optional): Conv kernel size. Default: 4
  * `expand` (number, optional): Expansion factor. Default: 2

### Returns

Returns a module table with:

  * `forward(self, input)`: Forward pass
  * `parameters(self)`: Returns list of parameters


# Model Tools Utils

Located in `Gradien.Util`. These tools help you inspect, profile, and modify models.

## `ModelStats`

Utilities to calculate parameter counts and memory usage.

### `.summary`

Prints or returns a summary of the model size.

DefinitionExample

lua

    (model: Module, printOut: boolean?) -> (number, string)

lua

    -- Prints: params=1250 (~10.00 KB)
    local count, sizeStr = Gradien.Util.ModelStats.summary(model, true)

### `.count`

Returns raw parameter count and byte size.

Definition

lua

    (model: Module) -> (number, number)

## `Profiler`

A lightweight instrumentation profiler to measure performance bottlenecks in your training loop.

### Usage

lua

    local Profiler = Gradien.Util.Profiler

    -- Wrap the whole training loop in a profiler scope
    local function step()
        -- ... code
    end
    Profiler.withEnabled(true, function()
        Profiler.scope("train_loop", function()
            for _ = 1, 500 do
                Profiler.scope("train_step", step)
            end
        end)
    end)

    -- Print a report
    Profiler.report()

### Methods

  * **`start(name)`**: Pushes a marker onto the stack.
  * **`stop(name?)`**: Pops the marker and records time.
  * **`scope(name, fn, ...)`**: Runs `fn` inside a named profile scope.
  * **`report(opts)`**: Prints a formatted table of timings.

## `Hooks`

Allows you to inject custom logic into the forward pass of any module.

### `.addForwardHook`

Attaches a function that runs _after_ the module's forward pass.

DefinitionExample

lua

    (module: Module, fn: (self, output) -> ()) -> ()

lua

    Gradien.Util.Hooks.addForwardHook(layer, function(self, out)
        print("Layer output shape:", out._shape)
    end)

### `.removeForwardHook`

Removes the attached hook from the module.

Definition

lua

    (module: Module) -> ()


# Activations Parallel

Activation functions introduce non-linearity to the network. Located in `Gradien.NN.Activations`.

## Standard

Function| Definition
**`ReLU(x)`**| `max(0, x)`
**`Sigmoid(x)`**| `1 / (1 + exp(-x))`
**`Tanh(x)`**| `(exp(x) - exp(-x)) / (exp(x) + exp(-x))`

## Probability

### `Softmax`

Converts a vector of values to a probability distribution. The elements of the output vector are in range (0, 1) and sum to 1.

DefinitionExample

lua

    (logits: Tensor) -> Tensor

lua

    local probs = Gradien.NN.Softmax.forward(logits)

## Advanced

### `GELU`

Gaussian Error Linear Unit. Often used in Transformers.

Definition

lua

    (x: Tensor) -> Tensor

### `LeakyReLU`

ReLU with a small slope for negative values to prevent dead neurons.

Definition

lua

    (x: Tensor, alpha: number?) -> Tensor -- alpha defaults to 0.01

### `ELU`

Exponential Linear Unit.

Definition

lua

    (x: Tensor, alpha: number?) -> Tensor -- alpha defaults to 1.0

### `SwiGLU`

Swish-Gated Linear Unit. Requires two inputs.

Definition

lua

    (a: Tensor, b: Tensor) -> Tensor

### `SwiGLUSplit`

Splits the input tensor into two halves and applies SwiGLU.

Definition

lua

    (x: Tensor, hidden: number?) -> Tensor

### `SiLU` (Swish)

`x * sigmoid(x)`

Definition

lua

    (x: Tensor) -> Tensor

### `Mish`

`x * tanh(ln(1 + exp(x)))`

Definition

lua

    (x: Tensor) -> Tensor

### `SeLU`

Scaled Exponential Linear Unit.

Definition

lua

    (x: Tensor, alpha: number?, lambda: number?) -> Tensor


# Loss Functions Parallel

Located in `Gradien.NN.Losses`. Loss functions measure how far the model's predictions are from the targets.

## Regression

### `mse_backward`

Mean Squared Error.

Definition

lua

    (pred: Tensor, target: Tensor) -> (number, Tensor)

### `l1_backward`

Mean Absolute Error (L1).

Definition

lua

    (pred: Tensor, target: Tensor) -> (number, Tensor)

### `huber_backward`

Less sensitive to outliers than MSE.

Definition

lua

    (pred: Tensor, target: Tensor, delta: number?) -> (number, Tensor)

## Classification

### `cross_entropy_backward`

Combines Softmax and Cross Entropy. Expects raw logits.

Definition

lua

    (logits: Tensor, targetIndices: {number}, smoothing: number?) -> (number, Tensor)

### `bceWithLogits_backward`

Binary Cross Entropy with Sigmoid built-in.

Definition

lua

    (logits: Tensor, targets: {number}) -> (number, Tensor)

### `focal_backward`

Focuses training on hard examples. Useful for class imbalance.

Definition

lua

    (logits: Tensor, targetIdx: {number}, alpha: number?, gamma: number?) -> (number, Tensor)

### `kl_div_backward`

Kullback-Leibler divergence.

Definition

lua

    (pred: Tensor, target: Tensor, fromLogits: boolean?) -> (number, Tensor)


# Optimization Wrappers Advanced

These modules wrap an existing optimizer (the "base") to add functionality like averaging or accumulation.

## `Lookahead`

Improves stability by keeping a set of "slow weights" that interpolate with the "fast weights" trained by the base optimizer.

ConstructorExample

lua

    (
        params: {Tensor},
        base: Optimizer, -- Existing optimizer instance
        k: number?,      -- Sync every k steps (default 5)
        alpha: number?   -- Interpolation factor (default 0.5)
    ) -> Optimizer

lua

    local base = Gradien.Optim.Adam(params, 1e-3)
    local opt = Gradien.Optim.Lookahead(params, base, 5, 0.5)

## `Accumulated`

Simulates a larger batch size by accumulating gradients over multiple steps before updating.

Constructor

lua

    (
        opt: Optimizer,
        steps: number,      -- Steps to accumulate
        params: {Tensor}?,  -- Needed if normalize=true
        normalize: boolean? -- Average grads instead of sum
    ) -> Optimizer

## `EMA` (Exponential Moving Average)

Maintains a shadow copy of model parameters that updates smoothly. Often used for inference or target networks in RL.

ConstructorMethods

lua

    (params: {Tensor}, decay: number) -> EMA_Handler

lua

    ema:update(params)  -- Call after opt:step()
    ema:apply(params)   -- Swap weights to EMA for eval
    ema:restore(params) -- Swap back to training weights


# Data Pipeline Utils

Tools for loading, scaling, and encoding data. Located in `Gradien.Preprocess`.

## Data Loading

### `DataLoader`

Creates an iterator that yields batches of data from a dataset.

Definition

lua

    (
        dataset: Dataset,
        batchSize: number,
        shuffle: boolean,
        generator: { randint: (a,b)->number }?,
        drop_last: boolean?
    ) -> Iterator

## Scaling & Normalization

### `StandardScaler` Parallel

Standardizes features by removing the mean and scaling to unit variance.

Formula: `z = (x - mean) / std`

ConstructorMethods

lua

    () -> StandardScaler

lua

    scaler:fit(X: Tensor)
    local transformed = scaler:transform(X: Tensor)

### `MinMaxScaler` Parallel

Scales features to a specific range (default 0 to 1).

Formula: `x_scaled = (x - min) / (max - min)`

ConstructorMethods

lua

    (min: number?, max: number?) -> MinMaxScaler

lua

    scaler:fit(X: Tensor)
    local transformed = scaler:transform(X: Tensor)

### `RunningNorm` Stream

Maintains a running mean and variance for scalar streams. Useful in Reinforcement Learning where the full dataset isn't available upfront.

ConstructorMethods

lua

    (eps: number?) -> RunningNorm

lua

    norm:update(x: number)      -- Updates stats with new value
    norm:normalize(x: number)   -- Returns (x - mean) / std
    norm:var()                  -- Current variance
    norm:std()                  -- Current standard deviation

## Encoders & Transformers

### `OneHot` Parallel

Creates a function that converts a list of class indices into a One-Hot encoded batch.

DefinitionExample

lua

    (numClasses: number) -> (indices: {number}) -> Tensor

lua

    local encoder = Gradien.Preprocess.OneHot(10)
    -- Batch of 3 samples with classes 1, 5, and 9
    local batch = encoder({1, 5, 9})
    -- Result: Tensor of shape {10, 3}

### `PCA` (Principal Component Analysis) Parallel

Performs dimensionality reduction by projecting data onto its principal components.

ConstructorMethods

lua

    (X: Tensor, K: number, iters: number?) -> PCA_Model

lua

    -- Projects new data X onto the K principal components found during init
    local reduced = pca:transform(X_new)

### `SinusoidalPE` Parallel

Adds Sinusoidal Positional Embeddings to a sequence tensor. Crucial for Transformer models to understand order.

DefinitionExample

lua

    (x: Tensor, sequenceLength: number) -> Tensor

lua

    -- x: {EmbeddingDim, Batch * SeqLen}
    local output = Gradien.Preprocess.SinusoidalPE(x, 128)


# Debugging & Metrics Tools

## Metrics Parallel

Located in `Gradien.Metrics`.

  * **`accuracy(logits, targets)`**: Returns classification accuracy (0.0 - 1.0).
  * **`topk(logits, targets, k)`**: Returns top-k accuracy.
  * **`mse(pred, target)`**: Mean Squared Error.
  * **`prf1(pred, target, C)`**: Returns Precision, Recall, and F1 Score.
  * **`confusion(pred, target, C)`**: Returns a Confusion Matrix `{ {number} }`.

## Debug Tools

Located in `Gradien.Debug` and `Gradien.Util.Anomaly`.

### `Anomaly`

Low-level checks for numerical stability.

  * **`hasNaN(t)`**: Returns true if tensor contains `NaN`.
  * **`hasInf(t)`**: Returns true if tensor contains `Inf`.
  * **`hasBadValues(t)`**: Returns true if `NaN` or `Inf`.

### `GradStats`

Analyzes gradients across an entire model. Useful for diagnosing vanishing/exploding gradients.

DefinitionStatTable

lua

    GradStats.forModel(model: Module) -> { [Tensor]: StatTable }

lua

        min: number,
        max: number,
        mean: number,
        std: number,
        n: number

### `Debug.wrapOptimizer`

Creates a wrapper around an optimizer that automatically performs gradient clipping and NaN checks before every step.

Definition

lua

    (
        opt: Optimizer,
        params: {Tensor},
        cfg: {
            maxGradNorm: number?,
            clipValue: number?,
            warnOnNaN: boolean?,
            label: string?
    ) -> WrappedOptimizer


# RL Agents Module

Gradien provides a unified API for Reinforcement Learning agents.

## Agent Types

### `DQL` & `DoubleDQN` Off-Policy

Deep Q-Learning algorithms. `DoubleDQN` reduces overestimation bias.

Config

lua

        actionDim: number,
        batchSize: number,
        gamma: number,
        epsilonStart: number?,
        epsilonEnd: number?,
        epsilonDecay: number?,
        modelFactory: () -> Module,
        optimizerFactory: (params) -> Optimizer,
        replay: ReplayBuffer?,
        targetSyncInterval: number?,
        tau: number? -- Soft update factor

### `PPO` On-Policy

Proximal Policy Optimization. Stable and efficient.

Config

lua

        policy: Module,
        value: Module,
        gamma: number,
        lam: number,
        clip: number,
        epochs: number,
        minBatch: number?,
        maxBuffer: number?,
        optimizerFactory: (params) -> Optimizer

### `A2C` On-Policy

Advantage Actor-Critic.

Config

lua

        policy: Module,
        value: Module,
        gamma: number,
        minBatch: number?,
        optimizerFactory: (params) -> Optimizer

## Common Interface

### `:act`

Definition

lua

    (state: Tensor, stepIndex: number?) -> number

### `:observe`

Definition

lua

    (transition: {state: Tensor, action: number, reward: number, nextState: Tensor, done: boolean}) -> ()

### `:trainStep` Parallel

Definition

lua

    () -> { loss: number, avgReturn: number? }?

### `:getPolicy`

Definition

lua

    () -> Module

### `:loadParameters` (DQN only)

Definition

lua

    (snapshot: any, strict: boolean?) -> ()


# Visualization Tools

## `Visual3D.render`

Renders the neural network into the 3D workspace using Parts and Beams.

DefinitionOptionsExample

lua

    (model: Module, origin: CFrame, options: RenderOptions?) -> RenderHandle

lua

        layerSizeHints: {number}?,
        maxNeuronsPerLayer: number?,
        maxBeamsPerEdge: number?,
        layerSpacing: number?,
        boxDepth: number?,
        unitHeight: number?,
        updateInterval: number?,
        mode: "weights" | "grads",
        palette: {Color3}?,
        name: string?,
        getActivations: ((model) -> {{number}})?,
        showNeuronValues: boolean?,
        valueEvery: number?,
        valueDecimals: number?,
        valueColor: Color3?,
        valueSize: Vector2?,
        sparsity: number?

lua

    Gradien.Util.Visual3D.render(networkOrAgent, CFrame, {
        layerSizeHints = {#States, HIDDEN, HIDDEN, HIDDEN, #Actions}, -- depth 3
        maxNeuronsPerLayer = 48,
        maxBeamsPerEdge = 256,
        layerSpacing = 10,
        unitHeight = 0.12,
        updateInterval = 1,
        mode = "weights", -- or "grads"
        getActivations = getActivations, -- or nil?
        showNeuronValues = true,
        valueEvery = 1,
        valueDecimals = 2,
    })

## `Visual2D.render`

Renders the network onto a UI layer.

DefinitionOptionsExample

lua

    (model: Module, parent: Instance, options: RenderOptions?) -> RenderHandle

lua

        size: UDim2?,
        position: UDim2?,
        anchorPoint: Vector2?,
        mode: "weights" | "grads",
        palette: {Color3}?,
        -- ... (similar to 3D options)

lua

    Gradien.Util.Visual2D.render(networkOrAgent, SurfaceGui, {
        layerSizeHints = {#States, HIDDEN, HIDDEN, HIDDEN, #Actions}, -- depth 3
        mode = "weights", -- or "grads"
        maxNeuronsPerLayer = 48,
        maxLinesPerEdge = 256,
        showLayerBoxes = true,
        updateInterval = 1,
    })


# Initializers Parallel

Located in `Gradien.Init`. Functions to initialize tensor weights.

Function| Description
`xavierUniform(W)`| Uniform initialization for Sigmoid/Tanh layers.
`kaimingUniform(W)`| Uniform initialization for ReLU layers (He Init).
`heUniform(W)`| Alias for `kaimingUniform`.
`heNormal(W)`| Normal distribution for ReLU layers.
`lecunUniform(W)`| Efficient backprop initialization.
`lecunNormal(W)`| Normal distribution variant of LeCun.
`zeros(W)`| Fills tensor with zeros.


# Experimental Neural Networks Experimental

Located in `Gradien.Experimental.NN`. These are experimental neural network architectures and layers.

## `KAN` (Kolmogorov-Arnold Network)

A Kolmogorov-Arnold Network layer that uses learnable univariate functions (approximated via Radial Basis Functions) instead of fixed linear transformations.

DefinitionExample

lua

    (in_features: number, out_features: number, grid_size: number?, spline_order: number?) -> Module

lua

    local kan = Gradien.Experimental.NN.KAN(128, 64, 5, 3)
    local output = kan:forward(input)

**Parameters:**

  * `in_features` (number): Number of input features
  * `out_features` (number): Number of output features
  * `grid_size` (number, optional): Number of grid points for RBF approximation. Default: `5`
  * `spline_order` (number, optional): Spline order (currently unused, reserved for future use). Default: `3`

**Returns:** Returns a module table with:

  * `forward(self, input: Tensor)`: Forward pass through the KAN layer
  * `parameters(self)`: Returns list of learnable parameters

**Architecture:** The KAN layer combines:

  * A base linear transformation with SiLU activation
  * A spline-based transformation using RBF (Radial Basis Function) approximation
  * The final output is the sum of both paths


# State Management Important

Since Roblox games rely on `DataStoreService` for persistence, Gradien provides utilities to serialize models and optimizers into simple tables that can be saved directly.

## Models

### Dumping

Converts the model's parameters into a serializable Snapshot format.

lua

    local snapshot = Gradien.State.dump(model:parameters())
    -- Returns: { { shape={...}, dtype="f32", data={...} }, ... }

### Loading

Restores parameters from a snapshot. This modifies the model in-place.

lua

    Gradien.State.load(model:parameters(), snapshot)

## Binary Serialization (Buffer) Recommended

For maximum storage efficiency, you can serialize snapshots into binary buffers. This significantly reduces the data size compared to JSON tables.

### `State.toBuffer`

Converts a snapshot table into a compact buffer.

lua

    local snapshot = Gradien.State.dump(model:parameters())
    local binaryData = Gradien.State.toBuffer(snapshot)

    -- Save binaryData to DataStore
    -- (Ensure your DataStore implementation supports buffer or encode to base64)

### `State.fromBuffer`

Restores a snapshot from a binary buffer.

lua

    local snapshot = Gradien.State.fromBuffer(binaryData)
    if snapshot then
        Gradien.State.load(model:parameters(), snapshot)
    end

## Optimizers

Optimizers contain state (like momentum buffers in Adam) that must be saved to resume training effectively.

lua

    -- Save
    local optState = Gradien.State.dumpOptimizer(optimizer)

    -- Load
    Gradien.State.loadOptimizer(optimizer, optState)

## Full Trainer Checkpoint

You can save the entire state of a `Trainer` instance, including the model, optimizer, current epoch, and best metric.

lua

    local checkpoint = Gradien.State.dumpTrainer(trainer)

    -- Save to DataStore
    DataStore:SetAsync("TrainingCheckpoint", checkpoint)

    -- Load later
    Gradien.State.loadTrainer(trainer, checkpoint)