[{"data":1,"prerenderedAt":29},["ShallowReactive",2],{"doc-en-beammp-server-lua-plugin":3},{"path":4,"slug":5,"title":6,"description":7,"category":8,"subcategory":9,"icon":10,"date":11,"author":12,"order":13,"image":14,"tags":15,"keywords":19,"docGroup":26,"docGroupIcon":26,"link_fr":27,"bodyHtml":28},"\u002Fdocs\u002Fen\u002Fgaming\u002Fbeammp\u002Fbeammp-server-lua-plugin","beammp-server-lua-plugin","How to Install a Lua Plugin on Your BeamMP Server","Install a server-side Lua plugin on your BeamMP server at Winheberg, in Resources\u002FServer, and check that it loads in the console.","jeux","beammp","tabler:code","2026-11-01","Winheberg",101,"\u002Fstatics\u002Fimages\u002Fdocs\u002Fen\u002Fgaming\u002Fbeammp\u002Fbeammp-server-lua-plugin.webp",[9,16,17,18],"plugin","lua","resources server",[20,21,22,23,24,25],"beammp plugin","beammp lua plugin","beammp resources server","beammp server script","beammp lua error","install beammp plugin","","\u002Fdocs\u002Fbeammp\u002Fplugin-lua-serveur-beammp","\u003Ch2>Context\u003C\u002Fh2>\n\u003Cp>Want to add features to your \u003Cstrong>BeamMP server\u003C\u002Fstrong> at Winheberg, such as a welcome message, admin commands or a racing system? All of that runs through \u003Cstrong>server-side Lua plugins\u003C\u002Fstrong>, which execute on your server rather than on your players&#39; machines.\u003C\u002Fp>\n\u003Cp>This guide explains \u003Cstrong>where to put a plugin\u003C\u002Fstrong>, how to \u003Cstrong>check that it loads\u003C\u002Fstrong> and what to do if the console shows an error like this one.\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-bash\">[LUA ERROR] Failed: &quot;Resources\u002FServer\u002FMyPlugin\u002Fmain.lua&quot;: [string &quot;Resources\u002FServer\u002FMyPlugin\u002Fmain.lua&quot;]:3: &#39;)&#39; expected (to close &#39;(&#39; at line 2) near &#39;end&#39;\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch2>Prerequisites\u003C\u002Fh2>\n\u003Cp>Before you start, make sure you have the following.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>An active \u003Cstrong>BeamMP server\u003C\u002Fstrong> on your Winheberg gaming panel\u003C\u002Fli>\n\u003Cli>The \u003Cstrong>plugin\u003C\u002Fstrong> you want to install, as \u003Ccode>.lua\u003C\u002Fcode> files or as an archive extracted on your computer\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cdiv class=\"markdown-alert markdown-alert-warning\">\u003Cspan class=\"alert-icon\">\u003Csvg xmlns=\"http:\u002F\u002Fwww.w3.org\u002F2000\u002Fsvg\" width=\"16\" height=\"16\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\u003Cpath d=\"M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z\"\u002F>\u003Cline x1=\"12\" y1=\"9\" x2=\"12\" y2=\"13\"\u002F>\u003Cline x1=\"12\" y1=\"17\" x2=\"12.01\" y2=\"17\"\u002F>\u003C\u002Fsvg>\u003C\u002Fspan>\u003Cdiv class=\"markdown-alert-body\">\u003Cp>A server plugin runs code on your server. Only download plugins \u003Cstrong>from trusted sources\u003C\u002Fstrong> (official BeamMP forum, the GitHub repository of a well-known creator) and read the README that comes with the plugin before installing it.\u003C\u002Fp>\n\u003C\u002Fdiv>\u003C\u002Fdiv>\n\u003Ch2>Server plugin or client mod?\u003C\u002Fh2>\n\u003Cp>BeamMP splits resources into two kinds, each in its own folder.\u003C\u002Fp>\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Folder\u003C\u002Fth>\n\u003Cth>Content\u003C\u002Fth>\n\u003Cth>Run by\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>\u003Ccode>Resources\u002FClient\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>.zip\u003C\u002Fcode> mods (cars, maps)\u003C\u002Ftd>\n\u003Ctd>Each player&#39;s game, which downloads them on connect\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>Resources\u002FServer\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Lua plugins, one subfolder per plugin\u003C\u002Ftd>\n\u003Ctd>Your server only\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\n\u003Cp>This guide only covers the \u003Ccode>Resources\u002FServer\u003C\u002Fcode> folder. For mods, see our guides \u003Cstrong>&quot;How to add modded cars to your BeamMP server&quot;\u003C\u002Fstrong> and \u003Cstrong>&quot;How to Install a Modded Map on Your BeamMP Server&quot;\u003C\u002Fstrong>.\u003C\u002Fp>\n\u003Ch2>1. Create the plugin folder\u003C\u002Fh2>\n\u003Cp>Each plugin needs \u003Cstrong>its own folder\u003C\u002Fstrong> inside \u003Ccode>Resources\u002FServer\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Col>\n\u003Cli>Log in to your \u003Cstrong>Winheberg gaming panel\u003C\u002Fstrong> and select your \u003Cstrong>BeamMP server\u003C\u002Fstrong>\u003C\u002Fli>\n\u003Cli>In the side menu, click \u003Cstrong>Files\u003C\u002Fstrong>\u003C\u002Fli>\n\u003Cli>Open the \u003Cstrong>\u003Ccode>Resources\u003C\u002Fcode>\u003C\u002Fstrong> folder, then \u003Cstrong>\u003Ccode>Server\u003C\u002Fcode>\u003C\u002Fstrong>\u003C\u002Fli>\n\u003Cli>Click \u003Cstrong>Create Directory\u003C\u002Fstrong> and name the folder after the plugin, for example \u003Ccode>WelcomeMessage\u003C\u002Fcode>\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Cimg src=\"\u002Fstatics\u002Fimages\u002Fdocs\u002Fen\u002Fgaming\u002Fbeammp\u002Fbeammp-server-lua-plugin-1793494976681-0a7be731b90d3686d973998d.webp\" alt=\"Resources\u002FServer folder and Create Directory button in Files\" width=\"770\" \u002F>\n\n\u003Ch2>2. Add the plugin files\u003C\u002Fh2>\n\u003Cp>Open the folder you just created and send the plugin&#39;s \u003Ccode>.lua\u003C\u002Fcode> files into it with the \u003Cstrong>Upload\u003C\u002Fstrong> button. If the plugin has several files or subfolders, keep exactly the layout its creator provided.\u003C\u002Fp>\n\u003Cimg src=\"\u002Fstatics\u002Fimages\u002Fdocs\u002Fen\u002Fgaming\u002Fbeammp\u002Fbeammp-server-lua-plugin-1793494977020-76d5913c91bcc450a1d1a3a4.webp\" alt=\"main.lua file inside the plugin folder\" width=\"770\" \u002F>\n\n\u003Cp>The final path should look like this.\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-bash\">Resources\u002FServer\u002FWelcomeMessage\u002Fmain.lua\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cdiv class=\"markdown-alert markdown-alert-important\">\u003Cspan class=\"alert-icon\">\u003Csvg xmlns=\"http:\u002F\u002Fwww.w3.org\u002F2000\u002Fsvg\" width=\"16\" height=\"16\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\u003Cpath d=\"M12 22c5.523 0 10-4.477 10-10S17.523 2 12 2 2 6.477 2 12s4.477 10 10 10z\"\u002F>\u003Cpath d=\"M12 8v4\"\u002F>\u003Cpath d=\"M12 16h.01\"\u002F>\u003C\u002Fsvg>\u003C\u002Fspan>\u003Cdiv class=\"markdown-alert-body\">\u003Cp>BeamMP automatically loads the \u003Ccode>.lua\u003C\u002Fcode> files placed \u003Cstrong>directly\u003C\u002Fstrong> in the plugin folder, in alphabetical order. Files in a subfolder are only loaded if the plugin pulls them in itself with \u003Ccode>require()\u003C\u002Fcode>. A \u003Ccode>main.lua\u003C\u002Fcode> stored in \u003Ccode>Resources\u002FServer\u002FWelcomeMessage\u002FWelcomeMessage\u002F\u003C\u002Fcode> will therefore never run.\u003C\u002Fp>\n\u003C\u002Fdiv>\u003C\u002Fdiv>\n\u003Ch2>3. Restart and check the console\u003C\u002Fh2>\n\u003Cp>A new plugin is only picked up when the server starts.\u003C\u002Fp>\n\u003Col>\n\u003Cli>Go back to your server&#39;s main page\u003C\u002Fli>\n\u003Cli>Click \u003Cstrong>Restart\u003C\u002Fstrong>\u003C\u002Fli>\n\u003Cli>Watch the \u003Cstrong>console\u003C\u002Fstrong> during startup\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Cp>Messages written by your plugins show up with the \u003Ccode>[LUA]\u003C\u002Fcode> prefix. If the plugin prints a message when it loads, you will see it right after the \u003Ccode>PluginMonitor started\u003C\u002Fcode> line.\u003C\u002Fp>\n\u003Cimg src=\"\u002Fstatics\u002Fimages\u002Fdocs\u002Fen\u002Fgaming\u002Fbeammp\u002Fbeammp-server-lua-plugin-1793495108746-590b08163356e84d7c93c28c.webp\" alt=\"LUA WelcomeMessage plugin loaded line in the console\" width=\"540\" \u002F>\n\n\u003Ch2>Example, a welcome plugin\u003C\u002Fh2>\n\u003Cp>To try it out without downloading anything, you can write a small plugin yourself. In the \u003Ccode>Resources\u002FServer\u002FWelcomeMessage\u003C\u002Fcode> folder, click \u003Cstrong>New file\u003C\u002Fstrong>, paste the following code and save it as \u003Ccode>main.lua\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-lua\">-- WelcomeMessage: greets every player who joins the server\n\nfunction onInit()\n    print(&quot;WelcomeMessage plugin loaded&quot;)\nend\n\nfunction onPlayerJoin(player_id)\n    local name = MP.GetPlayerName(player_id)\n    MP.SendChatMessage(-1, &quot;Welcome &quot; .. name .. &quot; to the server!&quot;)\nend\n\nMP.RegisterEvent(&quot;onInit&quot;, &quot;onInit&quot;)\nMP.RegisterEvent(&quot;onPlayerJoin&quot;, &quot;onPlayerJoin&quot;)\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>After a restart, the console shows \u003Ccode>[LUA] WelcomeMessage plugin loaded\u003C\u002Fcode>, and every player who joins is greeted in the chat. The full list of available functions and events is in BeamMP&#39;s official documentation, in the server scripting section.\u003C\u002Fp>\n\u003Ch2>If you run into trouble\u003C\u002Fh2>\n\u003Cp>Here are the most common situations with Lua plugins.\u003C\u002Fp>\n\u003Ch3>❌ The console shows LUA ERROR Failed\u003C\u002Fh3>\n\u003Cp>The file mentioned contains a \u003Cstrong>Lua syntax error\u003C\u002Fstrong>. The message gives the file, the line number and what is missing.\u003C\u002Fp>\n\u003Cimg src=\"\u002Fstatics\u002Fimages\u002Fdocs\u002Fen\u002Fgaming\u002Fbeammp\u002Fbeammp-server-lua-plugin-1793495109122-840b04783ff54b64e0b1e129.webp\" alt=\"LUA ERROR Failed message in the console\" width=\"740\" \u002F>\n\n\u003Cul>\n\u003Cli>Open the file mentioned and go to the \u003Cstrong>line given\u003C\u002Fstrong> (here line 3, with an unclosed parenthesis on line 2)\u003C\u002Fli>\n\u003Cli>If you did not write the plugin, download it again, the file may have been damaged during the upload\u003C\u002Fli>\n\u003Cli>Check that the plugin is compatible with your BeamMP version, shown in the console at startup (\u003Ccode>BeamMP Server v3.9.3\u003C\u002Fcode> for example)\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cdiv class=\"markdown-alert markdown-alert-note\">\u003Cspan class=\"alert-icon\">\u003Csvg xmlns=\"http:\u002F\u002Fwww.w3.org\u002F2000\u002Fsvg\" width=\"16\" height=\"16\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\u003Ccircle cx=\"12\" cy=\"12\" r=\"10\"\u002F>\u003Cline x1=\"12\" y1=\"16\" x2=\"12\" y2=\"12\"\u002F>\u003Cline x1=\"12\" y1=\"8\" x2=\"12.01\" y2=\"8\"\u002F>\u003C\u002Fsvg>\u003C\u002Fspan>\u003Cdiv class=\"markdown-alert-body\">\u003Cp>An error in a plugin \u003Cstrong>does not stop the server\u003C\u002Fstrong>. It keeps running and the other plugins load normally, which is why reading the console after each install matters.\u003C\u002Fp>\n\u003C\u002Fdiv>\u003C\u002Fdiv>\n\u003Ch3>❌ No LUA line shows up for my plugin\u003C\u002Fh3>\n\u003Cul>\n\u003Cli>Check that the plugin is in \u003Ccode>Resources\u002FServer\u003C\u002Fcode> and \u003Cstrong>not\u003C\u002Fstrong> in \u003Ccode>Resources\u002FClient\u003C\u002Fcode>\u003C\u002Fli>\n\u003Cli>Check that it has \u003Cstrong>its own subfolder\u003C\u002Fstrong> and that its \u003Ccode>.lua\u003C\u002Fcode> files are not stored one level too deep\u003C\u002Fli>\n\u003Cli>Keep in mind that some plugins print nothing at startup, check their README to see how to confirm they work\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch3>❌ The plugin also needs a client-side file\u003C\u002Fh3>\n\u003Cp>Some plugins ship with a \u003Ccode>.zip\u003C\u002Fcode> archive meant for players (interface, sounds, etc.). That archive goes into \u003Ccode>Resources\u002FClient\u003C\u002Fcode>, and the Lua part into \u003Ccode>Resources\u002FServer\u003C\u002Fcode>. Follow the instructions in the plugin&#39;s README.\u003C\u002Fp>\n\u003Ch2>Best practices\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>\u003Cstrong>Install one plugin at a time\u003C\u002Fstrong> and read the console after each restart, you will know right away which one causes trouble\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Create a backup\u003C\u002Fstrong> from the \u003Cstrong>Backups\u003C\u002Fstrong> tab before installing a plugin that changes your server&#39;s data\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Delete the folder\u003C\u002Fstrong> of a plugin you no longer use instead of leaving it in place\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Keep a copy\u003C\u002Fstrong> of your plugins&#39; configuration files before updating them\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2>Need help?\u003C\u002Fh2>\n\u003Cp>If your plugin does not load despite these checks, our team is here to help. Open a ticket with the \u003Cstrong>Technical\u003C\u002Fstrong> department from your client area, fill in the \u003Cstrong>Related Product\u003C\u002Fstrong> field with the server concerned and attach the startup logs.\u003C\u002Fp>\n\u003Cp>Your BeamMP server is ready for your plugins, enjoy the ride 🛣️\u003C\u002Fp>\n",1794526351669]