Docs / Entrenamiento: scripts FiveM (GTA V)
Create an interface (NUI)
Show a web interface in the game and make it talk to your scripts, with a complete example.
Por ahora esta documentación solo está en inglés y en francés.
Training on GTA V: this page covers FiveM, the GTA V roleplay platform. No tool to create a GTA 6 server has been announced: what you learn here is the best preparation.
On FiveM, server interfaces (phone, inventory, menus, HUD) are web pages: HTML, CSS and JavaScript, displayed by a browser built into the game. This is called NUI.
How it works
| Direction | Script side (Lua) | Page side (JavaScript) |
|---|---|---|
| Script → page | SendNUIMessage({ ... }) |
window.addEventListener('message', ...) |
| Page → script | RegisterNUICallback('name', ...) |
fetch('https://<resource>/name', ...) |
| Mouse and keyboard | SetNuiFocus(true, true) |
The page receives clicks and keys |
The game's native interfaces (big messages, GTA V menus) use another system, scaleforms, which scripts can also call.
1. The structure
idcard/
├── fxmanifest.lua
├── client.lua
└── html/
├── index.html
├── style.css
└── app.js
2. The manifest
fx_version 'cerulean'
game 'gta5'
lua54 'yes'
ui_page 'html/index.html'
files { 'html/index.html', 'html/style.css', 'html/app.js' }
client_script 'client.lua'
ui_page sets the page to load; every interface file must be listed in files.
3. The client script
client.lua: opens and closes the card with a key players can change in their settings.
local open = false
local function setOpen(state)
open = state
SetNuiFocus(state, state)
SendNUIMessage({ action = 'toggle', visible = state, name = GetPlayerName(PlayerId()) })
end
RegisterCommand('+idcard', function() setOpen(not open) end, false)
RegisterCommand('-idcard', function() end, false)
RegisterKeyMapping('+idcard', 'Open my ID card', 'keyboard', 'F7')
-- Called by the page when the player closes the card
RegisterNUICallback('close', function(data, cb)
setOpen(false)
cb('ok')
end)
4. The page
html/index.html:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<link rel="stylesheet" href="style.css">
</head>
<body>
<div id="card" hidden>
<h1>ID card</h1>
<p id="name"></p>
<button id="close">Close</button>
</div>
<script src="app.js"></script>
</body>
</html>
html/style.css: the background must stay transparent, otherwise the page hides the game.
html, body { margin: 0; background: transparent; font-family: sans-serif; }
#card { position: absolute; right: 40px; bottom: 40px; padding: 20px 24px;
border-radius: 14px; background: rgba(10, 20, 29, .9); color: #fff; }
html/app.js:
const card = document.getElementById('card');
// Messages sent by SendNUIMessage
window.addEventListener('message', (e) => {
if (e.data.action !== 'toggle') return;
card.hidden = !e.data.visible;
document.getElementById('name').textContent = e.data.name || '';
});
// Tells the Lua script (RegisterNUICallback 'close')
function closeCard() {
fetch(`https://${GetParentResourceName()}/close`, {
method: 'POST',
headers: { 'Content-Type': 'application/json; charset=UTF-8' },
body: '{}'
});
}
document.getElementById('close').addEventListener('click', closeCard);
window.addEventListener('keydown', (e) => { if (e.key === 'Escape') closeCard(); });
Add ensure idcard to server.cfg, then press F7 in game.
5. Test without launching the game
Open index.html in your browser and simulate a message in the console:
window.postMessage({ action: 'toggle', visible: true, name: 'Test player' });
This way you work on the layout in seconds, without restarting the resource. In game, the nui_devtools command in the F8 console opens the NUI developer tools.
Good practices
- Write text with
textContent, notinnerHTML: a player name can contain code. WithinnerHTML, anyone could run it in other players' interfaces. - Never trust the page: everything it sends (amounts, items) must be checked server-side, like an event.
- Always give control back: every
SetNuiFocus(true, true)needs itsSetNuiFocus(false, false). Otherwise the player stays stuck with the mouse. - Think about performance: hide the interface when it is not in use, avoid continuous animations and big files. Measure with
resmon. - Keep a shared style: same colours, fonts and buttons for every interface on the server, in a shared CSS file.
- Think about controllers: an interface usable without a mouse (big buttons, arrow navigation) will be a real advantage.
- Keep texts separate: all texts in a translation file, not hard-coded.
What about GTA 6?
To be confirmed: we don't know how GTA 6 server interfaces will be built, or whether a web NUI will exist. To be ready, separate your interface from the game: one small layer does the bridging (here SendNUIMessage and fetch), and the rest of the interface does not depend on it. If the way to communicate changes, you only rewrite that layer. See Prepare your server for GTA 6.
