Lua Plugin

[DizzasTeR]

Major Release - v3.0

VCMP-Lua 3.0 is a rebuild of the plugin. Scripts can no longer crash the server, the libraries are built in, and each platform gets a single binary with nothing else to install.
An important note from me

The project was started as a learning curve for me, I learned alot and had alot of fun as well. But the plugin was always in a state that wasn't satisfactory, atleast to me because of the obvious quality issues, build issues and lack of functionality that shouldn't have been something to manually maintain in the first place.

I don't like leaving projects in half baked states and eventually I do come back to them whenever possible, that story applies to this plugin as well. VCMP may not be in its glory days, and nobody likely uses this plugin either but I still had a wish to leave it in a state that I could look back to happily.

With no time on my hands and AI being good enough, I took the time to properly redo the whole plugin from scratch with the standards I had strived for using Claude. This is the end result and I'm happy with it atleast as a draft before marking it stable.

Full details below but I think this is how it should've been if I had the right C++ knowledge during the time I worked on this.
Why

The 2.x plugin had problems that a patch could not fix:

• A client could crash the server. Client script data was copied into a fixed 4096-byte stack buffer without a size check.
• MySQL, HTTP and threads used the Lua state from worker threads. A Lua state is single-threaded, so that use crashed (the "5–10 queries" MySQL crash).
• Entity handles pointed into vectors or were owned by the garbage collector. Handles dangled, an unstored vehicle vanished at the next collection, and a destructor could delete another plugin's entity.
• The build was unreproducible. It mixed copied sources, a patched submodule, ~100 MB of prebuilt libraries and premake. The Linux .so had unresolved symbols, and the Windows DLL needed extra DLLs.

What changed

• Runtime. One owner has an explicit shutdown order, and only the main thread touches Lua. Every server callback is noexcept. Events use stable dispatch, and cancel applies to the innermost event. Timers use 64-bit time. Arguments are checked, and errors read like Lua's own.
• Entities. The server owns entity lifetime. Handles are validated on every use ("vehicle no longer exists"). The same entity is always the same handle, so == and table keys work.
• Batteries. These are built in and load with require:
  • LuaSQL (SQLite, PostgreSQL, MySQL/MariaDB), lua-cjson, LuaSocket, Copas, LuaFileSystem and inspect.lua;
  • A non-blocking http module over libcurl;
  • Hash (the 2.x digests plus PBKDF2, scrypt, HMAC and random bytes);
  • sql.format.
• Config. luaconfig.lua replaces luaconfig.ini.
• Build.
  • CMake with vcpkg (pinned) and tarballs pinned by SHA256.
  • Linux is built in a manylinux228 image. Each binary exports only VcmpPluginInit and needs only system libraries, which CI checks.
• Tests.
  • doctest and Lua unit tests, also run under ASan + UBSan.
  • A plugin host that loads the built binary.
  • Integration tests against the real VC:MP 0.4 Linux server with Postgres 17, MySQL 8.4, MariaDB 11 and a local TLS server.
  • A real-client test on Windows.
• Docs. README, API reference (docs/api), docs/configuration.md, the migration guide (docs/MIGRATION-v3.md), docs/internals.md and examples/.
• Release. A v* tag builds and tests both platforms and drafts a release with one zip per platform plus SHA256SUMS.

Breaking changes

All of them are listed in docs/MIGRATION-v3.md. The main ones:

• Config file. luaconfig.ini becomes luaconfig.lua.
• Entity lifetime. Entities live until :destroy(), not until the garbage collector runs.
• Removed globals. MySQL, SQLite, Remote, JSON, Thread, Lanes and dbg are gone. Using one raises an error that names its replacement.
• Async database queries will come once LuaSQL releases its non-blocking API.

Downloads
- Available as zip for Windows/Linux x64 at Releases