Skip to main content

Getting Started - Client

This guide provides information on creating mods for the client. For creating custom servers, take a look at the server documentation

Steps​

Install Visual Studio Code​

Download from the official website

Open the Mods Folder in VS Code​

You can open your mods folder in VS Code by right clicking on the folder and selecting Open with Code or by using File -> Open Folder within VS Code.

Open Folder Dropdown Option

The mods folder can be found in Documents/My Games/Hub OS on Windows. You can find your mods folder by using Open Mods Folder in the config menu, or customize where the mods folder is by launching with --data-folder flag.

Open Mods Folder Option

Install Extensions​

You'll want at minimum the Lua extension by sumneko, as it will provide syntax highlighting and autocomplete for Lua:

Sumneko Extension

Add Type Definitions File​

You can add our client type definitions file to your project / mods folder: Client Type Definitions

It should look like this inside of VS Code:

Type Definitions File

Understanding the Mods Folder​

Each category of mod has a specific folder it should exist in. Some categories may share a folder, such as library and pack / mod packs.

You can read more details about where each category of mod belongs and what is expected in Packages.

At minimum a mod must contain a package.toml file for meta information such as the category, name, and package ID.

Minimal Mod

Your First Mod​

The best way to learn is to add your own changes to simple mods from others before trying from scratch.

Some starter mods (Note: some mods have dependencies that can be automatically installed by downloading through the client):

  • Chips:
    • MiniBomb
      • Features: BombLib, beast jump positioning (Check tags)
    • Shotgun
      • Features: Attachments, projectiles, artifacts, collision callbacks
    • WideSword
      • Features: SwordLib, beast jump positioning (Check tags)
    • TomahawkMan
      • Features: ChipNaviLib, NAVI tag (Check tags)
  • Navis:
    • Man
      • Features: Simple forms, basic attacks.
    • Bass
      • Features: Emotions, custom actions, chip charging, intro.
    • ProtoMan
      • Features: Emotions, custom actions, chip charging, special attack, fixed cards, reusing cards as attacks.

If you want to start from scratch take a look at the Packages page for the base requirements of each type of mod.

Utilizing Types​

If you provide correct type information for your function parameters, the Lua extension can provide in-editor documentation and code suggestions from the type definitions file.

Proper annotations for script entry functions can be found in the Packages page (Ctrl+F for entry.lua).

More details on Sumneko Lua's Annotations

An example of how this works, see how the button variable receives suggestions and documentation from only adding ---@param player Entity:

Autocomplete