Getting started

An addon is a folder of Lua that lives under addons/. Every .lua file inside addons/<name>/lua/autorun/ is run once at startup, in alphabetical order. A downloaded mod arrives instead as a single addons/<name>.ccmod file — a plain ZIP, mounted in place and never unpacked, so it stays obvious which mods are yours (folders) and which came from the site (packages). Worker scripts load from inside the package too; a loose folder with the same name out-ranks a package of that name.

layoutaddons/<modname>/lua/autorun/*.lua

All addons run in one shared sandbox: a global you set in one addon is readable in every other addon, functions can be called across mods, and hook events fired by one mod reach listeners in another. Four things are per-addon: data (your private storage folder), MOD_NAME (your folder name), MOD_VERSION and MOD_SOURCE.

A minimal addon — a pinned FPS-style HUD plus a button:

-- addons/hello/lua/autorun/hello.lua
log("hello loaded as " .. MOD_NAME)

-- A free-form HUD element, always on screen (mode = "pinned")
overlay.add("hello.clock", {
    mode = "pinned",
    paint = function(d)
        d:rect(d:w() - 150, 16, 130, 34, 0, 0, 0, 150)
        d:text(d:w() - 138, 24, os.date("%H:%M:%S"), 20, 255, 255, 255)
    end,
})

-- A button in the overlay menu (Shift+Tab)
overlay.add("hello.hi", {
    mode = "menu",
    button = { label = "Say hi", onClick = function() log("hi!") end },
})

One page of the MCCP modding reference. Every section is its own document; search covers all of them.