The source folder (or the repository's root) holds a mod.txt that says what it is and which version this is. The version is stated once, here, and is what the submission goes in as.

kind    = native
version = 1.0.0

Without kind = native a folder is a Lua mod and is packed and published as one.

A GitHub repository does not need one. MCCP looks at the repository as soon as you have typed its address: if it has a mod.txt at the top, that is used and the panel says which version it states; if not, a box appears holding a mod.txt to edit, filled in to start from, and that is what the version is read from. A repository's own mod.txt always wins over a typed one.

Everything a module needs is one header, mccp_module.h. Nothing to link: MCCP hands the module an interface of virtual functions (mccp::Lua, the LUA in every function), so it never touches Lua's own library and keeps working when MCCP updates its Lua.

MCCP_MODULE_OPEN runs on the first require of the module, not when MCCP starts: build what require returns - usually a table of functions - and return how many values you pushed. MCCP_MODULE_CLOSE is optional and runs once at exit, while Lua is still whole, so references you kept can be freed there. A function Lua can call is a LUA_FUNCTION: read its arguments, push its results, return how many.

Here is the whole way through: Lua passes a frame in, the module reads its pixels in place and answers with a string. Put an OCR library where the comment is and it is a text reader.

// pixels.cpp - built as pixels.dll, dropped in bin/
#include "mccp_module.h"
#include <cstdio>
#include <string>

// pixels.read(frame) -> a string about the frame
LUA_FUNCTION(Read) {
    mccp::Frame f;
    if (!LUA->ToFrame(1, &f)) return LUA->ArgError(1, "frame expected");

    // f.data points at the frame itself: no copy was made. This is where
    // an OCR library would read f.width x f.height pixels, f.pitch apart.
    std::string text = std::to_string(f.width) + "x" + std::to_string(f.height) +
                       " " + f.format + ", first pixels:";
    for (int i = 0; i < 8; ++i) text += " " + std::to_string(f.data[i]);

    LUA->PushString(text.c_str(), text.size());
    return 1;                                     // one value back to Lua
}

MCCP_MODULE_OPEN() {                              // the first require("pixels")
    LUA->CreateTable();
    LUA->PushCFunction(Read);
    LUA->SetField(-2, "read");
    return 1;                                     // what require gives back
}

Build it as a 64-bit DLL (MSVC or clang-cl) with the header on the include path. A DLL your module needs can sit beside it in bin/: its own folder is searched first.

Opens bin/<name>.dll as a module and returns what its open returned (true if it returned nothing). The first call opens it; every later one, from any mod, returns the same value. The name is the DLL's file name without .dll, in any case.

-- addons/reader/lua/autorun/reader.lua
local pixels = require("pixels")                  -- bin/pixels.dll

hook.Add("OnFrameReceived", "reader", function(frame)
    print(pixels.read(frame))
    -- 1920x1080 SDL_PIXELFORMAT_NV12, first pixels: 16 16 16 17 16 16 16 16
end)

Only native modules can be required. Lua files can't: put them in lua/autorun. When there is nothing to open, the error says why - not in bin/, downloaded and waiting for the restart, switched off by the crash guard, not a module, or built for a newer MCCP.

What LUA-> offers. It follows Lua's own C API, so its documentation answers the details.

Only on the thread that called you. LUA is valid during the call it was handed to and nowhere else: never keep it, never use it from a thread of your own. A module function runs while a frame waits for it, so slow work belongs on your own thread, with a function Lua can poll for the result:

// Slow work on your own thread; Lua asks for the answer.
LUA_FUNCTION(Start) { /* copy the pixels you need, hand them to a worker */ return 0; }
LUA_FUNCTION(Poll)  {
    std::string done;
    if (!takeResult(done)) return 0;              // nothing yet: Lua gets nil
    LUA->PushString(done.c_str(), done.size());
    return 1;
}

Frames and buffers are valid only during the call that got them. Copy what a worker thread needs before you return.

Errors from ArgError, Error or a failed Check* end the call with a Lua error once your function returns - nothing jumps out of your code, so its destructors run. A C++ exception that leaves your function is caught and becomes a Lua error too.

Crashes - an access violation, a division by zero, a stack overflow - are caught as well, in every call into a module: open, its functions and close. The mod that called gets a Lua error (pixels.dll crashed (access violation)) and MCCP keeps running. The module is then switched off until MCCP restarts: after a crash its memory can't be trusted, so it is not called again, not even to close. A crash on a thread the module started itself can't be caught - nothing called it, so there is nowhere to return to - and takes MCCP down.

The header, whole. It also ships as docs/mccp_module.h beside this reference. Its interface only grows at the end, and MCCP_MODULE_API counts it: a module built against an older header keeps working with a newer MCCP, and one built against a newer header than the MCCP it runs in is not opened.

// mccp_module.h - write a native module for MCCP. The only file you need.
//
// A native module is a DLL that Lua mods load with require() and call like any
// other function, the way Garry's Mod binary modules work:
//
//     #include "mccp_module.h"
//
//     LUA_FUNCTION(Add) {
//         LUA->PushNumber(LUA->CheckNumber(1) + LUA->CheckNumber(2));
//         return 1;                                  // values returned to Lua
//     }
//
//     MCCP_MODULE_OPEN() {                           // on the first require
//         LUA->CreateTable();
//         LUA->PushCFunction(Add); LUA->SetField(-2, "add");
//         return 1;                                  // what require() gives back
//     }
//
//     MCCP_MODULE_CLOSE() { return 0; }              // optional; at exit
//
// and in a Lua mod:
//
//     local mymod = require("mymod")                 -- bin/mymod.dll
//     print(mymod.add(1, 2))                         -- 3
//
// Nothing to link: MCCP hands the module an interface (mccp::Lua) of virtual
// functions, so a module never touches Lua's own library and keeps working
// when MCCP updates its Lua.
//
// THE RULES
//   * Only on the thread that called you. LUA is valid during the call it was
//     handed to, on that thread, and nowhere else: never keep it, never use it
//     from a thread of your own. Do slow work on your own thread and let Lua
//     ask for the result (a poll function), or the frame waits for you.
//   * Errors: ArgError/Error, or a Check* that fails, end the call with a Lua
//     error once your function returns - they do not jump out of it, so return
//     right away (`return LUA->ArgError(1, "...")`). A C++ exception that
//     leaves your function is caught and becomes a Lua error too.
//   * Frame and Buffer pointers are valid only during the call that got them.
//   * Stack indices work like Lua's: 1 is the first argument, -1 the top.
//
// The interface only ever grows at the end, and MCCP_MODULE_API counts it. A
// module built against an older header keeps working with a newer MCCP; one
// built against a newer header than the MCCP it runs in is not loaded.
#pragma once
#include <cstddef>
#include <cstdint>

#define MCCP_MODULE_API 1

namespace mccp {

// Lua's own type numbers.
enum Type {
    TNONE = -1, TNIL = 0, TBOOL = 1, TLIGHTUSERDATA = 2, TNUMBER = 3, TSTRING = 4,
    TTABLE = 5, TFUNCTION = 6, TUSERDATA = 7, TTHREAD = 8
};

// A captured frame, as OnFrameReceived hands it to Lua. The bytes are the
// frame itself, not a copy: writing them changes what is shown, exactly as
// frame:setByte() does.
struct Frame {
    uint8_t*    data;     // the pixel buffer
    size_t      size;     // bytes in it (on NV12: the luma plane, then chroma)
    int         width;    // pixels
    int         height;   // pixels
    int         pitch;    // bytes per row of the first plane
    const char* format;   // e.g. "SDL_PIXELFORMAT_NV12"
};

// A Lua mod's buffer.new(n): bytes it owns, read and written in place.
struct Buffer {
    uint8_t* data;
    size_t   size;
};

class Lua;
typedef int (*CFunc)(Lua* LUA);

class Lua {
public:
    // ---- the stack ---------------------------------------------------------
    virtual int  Top() = 0;                        // number of values on it
    virtual void Pop(int n = 1) = 0;
    virtual void Push(int idx) = 0;                // a copy of the value at idx

    // ---- types -------------------------------------------------------------
    virtual int         GetType(int idx) = 0;      // a mccp::Type
    virtual const char* GetTypeName(int type) = 0;
    virtual bool        IsType(int idx, int type) = 0;

    // ---- reading -----------------------------------------------------------
    // Get* never fail: the wrong type reads as 0 / nullptr, and GetBool is
    // Lua's truth (only nil and false are false). Numbers read as strings and
    // numeric strings as numbers, as in Lua. GetInteger truncates 2.7 to 2.
    // GetString's pointer lives as long as the value stays on the stack.
    virtual double      GetNumber(int idx) = 0;
    virtual long long   GetInteger(int idx) = 0;
    virtual bool        GetBool(int idx) = 0;
    virtual const char* GetString(int idx, size_t* len = nullptr) = 0;
    // Check* fail the call (see THE RULES) when the type is wrong, and return
    // 0 / "" meanwhile - never nullptr - so the code up to your return is safe.
    virtual double      CheckNumber(int idx) = 0;
    virtual long long   CheckInteger(int idx) = 0;
    virtual const char* CheckString(int idx, size_t* len = nullptr) = 0;

    // ---- pushing -----------------------------------------------------------
    virtual void PushNil() = 0;
    virtual void PushBool(bool v) = 0;
    virtual void PushNumber(double v) = 0;
    virtual void PushInteger(long long v) = 0;
    // Any bytes, zeros included, when len is given; else up to the first zero.
    virtual void PushString(const char* s, size_t len = static_cast<size_t>(-1)) = 0;
    virtual void PushCFunction(CFunc f) = 0;

    // ---- tables ------------------------------------------------------------
    virtual void CreateTable() = 0;
    virtual void GetField(int idx, const char* key) = 0;   // pushes t[key]
    virtual void SetField(int idx, const char* key) = 0;   // t[key] = top; pops it
    virtual void GetTable(int idx) = 0;                    // key on top -> t[key]
    virtual void SetTable(int idx) = 0;                    // t[key] = value; pops both
    virtual void PushGlobals() = 0;                        // the mods' shared _G

    // ---- calling Lua -------------------------------------------------------
    // The function, then nargs arguments, on top. Protected: true and
    // nresults values, or false and the error message.
    virtual bool Call(int nargs, int nresults) = 0;

    // ---- keeping a value between calls (a callback, a table) ---------------
    virtual int  ReferenceCreate() = 0;            // pops the top, returns its ref
    virtual void ReferencePush(int ref) = 0;
    virtual void ReferenceFree(int ref) = 0;

    // ---- errors ------------------------------------------------------------
    // Both return 0 so they can be returned. The call ends in a Lua error.
    virtual int ArgError(int arg, const char* msg) = 0;
    virtual int Error(const char* msg) = 0;

    // ---- MCCP's own values -------------------------------------------------
    virtual bool ToFrame(int idx, Frame* out) = 0;    // false: not a live frame
    virtual bool ToBuffer(int idx, Buffer* out) = 0;  // false: not a buffer
    virtual void Log(const char* text) = 0;           // MCCP's log, under your name

protected:
    ~Lua() = default;   // MCCP owns it; a module never deletes one
};

}  // namespace mccp

#ifdef _WIN32
#define MCCP_EXPORT extern "C" __declspec(dllexport)
#else
#define MCCP_EXPORT extern "C" __attribute__((visibility("default")))
#endif

// A function Lua can call: LUA_FUNCTION(Name) { ...; return <values pushed>; }
#define LUA_FUNCTION(name) static int name(mccp::Lua* LUA)

#define MCCP_MODULE_OPEN()                                          \
    MCCP_EXPORT int mccp_module_api() { return MCCP_MODULE_API; }  \
    MCCP_EXPORT int mccp_module_open(mccp::Lua* LUA)

#define MCCP_MODULE_CLOSE() MCCP_EXPORT int mccp_module_close(mccp::Lua* LUA)

You upload the source, never a DLL. In Upload a mod, pick the folder in addons/ (its .gitignore is honoured the way git would, so build output stays home) or a public GitHub repository (a private one is refused: add the files instead, or make it public). For a repository, the newest commit of the branch in the URL is what is reviewed, and its mod.txt is read at that commit (or typed into the panel, when it has none). A changelog is required: it is the reviewer's first read and the changelog entry once approved.

A reviewer reads the source and builds the DLL themselves. Prebuilt binaries in the source are fine to leave in for them, but expect to be asked where they came from, and to have them rebuilt and replaced. Nobody can download the mod until a build is approved, and you cannot publish it before that. You get an email when it is approved or declined; reviewers get one for every new submission.

A decline comes with a reason. Answer it from the mod's Edit panel: reply in words, reply pointing at the repository's newest commit (GitHub submissions), or submit new source. Once approved, Publish on the same panel makes it public. Submitting a new version starts a new review; until it is approved, the last approved build is what people download, and public stays public.

Native mods live in bin/ beside addons/, never in it. Downloads are checked against the hash of the reviewer's build before anything is kept, then wait as <name>.dll.new until the next start; a DLL in use is never replaced under itself. Uninstalling one that is running removes it at the next start.

Restart. A DLL loads at startup or not at all. A download that brings one restarts MCCP by itself, once, after everything it came with has arrived: the native mod first in the chain, the Lua mods that need it after it, then a single restart.

Crash guard. If MCCP goes down while loading a DLL, the next start leaves that DLL off (bin/<name>.disabled) and says so in the log and in My mods. A new version of it clears that, and so does deleting the file.

Testing your own. Put your build in bin/ by hand and start MCCP. It loads like any other, and the log notes it did not come from the site.