Making a Mod

Making a Mod

A mod is a package: a folder with a resource.toml and your files. This page makes a small one that replaces a board's texture and draws a line on the screen while you ride, tries it in the game, and packs it for others.

1. The folder

neon-board/
  resource.toml
  textures/neon_board.png
  client/hello.luau

resource.toml:

[resource]
name = "neon-board"
version = "1.0.0"
title = "Neon board"
authors = ["Your Name"]
description = "Elise's first board in neon green, and a line on the screen while you ride."
api = 1
type = "mod"

[override]
"ssx:texture/character/textures/elise_board_00_diffuse" = "textures/neon_board.png"

[scripts]
client = ["client/*.luau"]

The texture is a PNG you made (here 512 × 512). Replacing a texture keeps the game's mapping, so paint over the original's layout. Texture ids are on Content IDs and Kinds.

client/hello.luau:

local tricks = 0

addEventHandler("onClientTrick", root, function(name, points)
    tricks += 1
    print("neon-board: " .. name .. " for " .. points)
end)

addEventHandler("onClientRender", root, function()
    draw.text("Neon board on: " .. tricks .. " tricks", 640, 24, tocolor(40, 255, 200), { size = 22, align = "center", shadow = true })
end)

2. Try it while you work

Start the game with your folder mounted:

avalanche-game --mod-dev path/to/neon-board

• The folder is loaded as the last of your mods (in place of an installed copy of the same name).

• The game watches it. What you see and hear is loaded again within a second of a save, while you play: textures, sounds and music, skies, lighting, post-FX, particles, menu screens, strings, fonts and the rider's look; scripts restart. What changes the ride (tuning, scoring, events, collision) takes effect at the next level.

• An edit that breaks the package (a manifest error, a texture that does not decode) is refused and the last good state stays; the overlay in the bottom right corner says why.

• The overlay also lists your mods, what each replaces, and conflicts with their winner. After saving the PNG during a ride it read:

  MOD-DEV  neon-board 1.0.0  (…/neon-board)
  reload 2: 23 s ago 1 id changed in 0.05 s
  mods (weakest first, * in development): neon-board*
  overrides of the game: neon-board 1
  conflicts: 0
  

• The scripts' monitor (F9; shown from the start with --mod-dev) gives each package's time, errors and stops. print output goes to the game's log: the terminal you started it from, or game.log in your Project Avalanche folder when the launcher started it.

On Windows run it from the game's folder: .\avalanche-game.exe --mod-dev C:\Mods\neon-board.

3. Pack and share

Zip the folder with any zip tool: the package may be at the zip's root or in its only top folder (neon-board.zip holding neon-board/resource.toml …). Others install it on the launcher's Mods page (Installing Mods): "Installed Neon board 1.0.0 (3 files) and switched it on."

What the install checks

• The tree: no links or special files, names every system spells the same, the limits.
• resource.toml: every key known, every value in its range (Resource Packages).
• Every file an entry names: present, its extension one of its kind's, and decoded as the game would (a texture that does not decode or a glTF that breaks the rules of its kind is an error), with the file and line of each problem.

What it cannot know until the game loads the mod:

• an override of an id that does not exist (the Mods page lists it under Ids nothing below them has);
• a script's compile error or a require that does not resolve (the game's log and the scripts' monitor, F9, show it).

Ship your own work only, never files of the game.

Next

• Making a Map, Making a Gamemode
• Scripting Overview
• Load Order and Priorities