Skip to content

Ballest plugin docs

The Ballest plugin manager lets anyone add features to Ballest of Them All with small scripts called plugins. A timer, replay controls, extra track editor tools: each is a plugin. Players install them from inside the game (footer plugins > browse, with a search that filters as you type), and they start straight away, with no restart.

Plugins are written in AngelScript, a small scripting language that looks like C++ or C#. You don't need a compiler, Visual Studio or any engine tools. A text editor is enough.

  • Your first plugin: a plugin that shows a window, in about ten minutes.
  • How plugins run: callbacks, the time budget, and what happens when something goes wrong.
  • Guides: windows and widgets, settings, saving data, debugging, publishing, drawing in the world.
  • API reference: every function, each with an example.

What a plugin looks like

A folder in the game's plugins folder with two files:

[meta]
name = "Hello World"
version = "0.1.0"
author = "you"
description = "Says hello."

[script]
files = ["main.as"]

void Main()
{
    Log::Info("hello from a plugin");
}

Examples to read

  • Hello World: the smallest plugin.
  • Grind Timer: a movable window, settings, saved totals.
  • Replay Manager: replay controls with a slider, dropdowns and keyboard input.
  • Create Extensions: track editor tools (drag to select, groups, rotate modes, Shift/Ctrl+click to deselect, rotated copies), a toolbar dropdown and key list rows in the editor's own style, and a section docked in the editor's details panel.
  • Cosmetic Kit and Example Cosmetics: one plugin offering functions to others, and one depending on it to add custom balls, hats and a goal explosion, with models: shapes described in text, and 3D model files from Blender (an animated T-rex and skeleton running inside clear balls, a baseball cap).
  • Monkey Balls: characters that run inside clear balls, with limbs that swing from their joints and keep time with the ball.
  • Fit Window: a few lines that maximize the game's window at startup when it doesn't fit the screen.
  • Plugin Manager: the plugin browser, settings pages and console, built with cards and a tab header. This is the largest example.