dev.md

The dev UI

fiverunner dev runs your project in your browser: its server, with its console and its resources, and players that connect to it, each with a screen that shows the frames of its NUI. No GTA V, no FXServer.

npx fiverunner dev

It tells you where the dev UI is, which is http://fiverunner.localhost:30120/ unless that port is taken, then the next free one. Open it in Chrome, Edge or Firefox: browsers that take the names under localhost for your machine, as the dev UI and the frames of NUI each have one. Stop it with Ctrl+C.

The project is the same as for fiverunner test: a resource, when the directory has an fxmanifest.lua or a __resource.lua, which the server ensures, or a server, when the directory has a resources directory, whose server.cfg the server runs. Test files are not part of it.

Options

Option	What it does
-p, --port <n>	Listens on port n, or on the next free one. 30120 by default.
-h, --help	Shows the help.

The server

The console shows what the server prints, with the colors of ^1 to ^9, its Lua warnings, and what FiveRunner noticed of how your resources use FiveM. The box under it runs commands on the server console, as FXServer's console runs them: restart bank, ensure bank, set and the commands of your resources. The arrow keys go back through the commands you ran.

The resources list shows each resource of the server and its state, with buttons that start, stop and restart it.

Resources that use oxmysql run on FiveRunner's database, in memory, which starts anew with the project, with the tables of its .sql files, as the differences from FiveM tell.

Events

The events panel shows the events that the server and the clients send each other, as they get them: those of TriggerServerEvent and TriggerClientEvent, latent ones too, and those that FiveM sends of its own, such as onPlayerJoining, each with where it came from, where it went, and its arguments, written as Lua would write them.

The form under it triggers an event as the network would: on the server, as a player does with TriggerServerEvent, so that source is the player, or on the client of a player, or of every player, as the server does with TriggerClientEvent. Give the arguments as a JSON array, such as [100, "cash"]. Handlers get the event at the next tick, and only those of RegisterNetEvent take it, as in FiveM.

State bags

The state bags panel shows the state bags of the server that have keys, such as global, which GlobalState sets, and player:<id>, which Player(id).state sets, with the values of their keys, as they change.

Inspector

The inspector shows what a process has: the server, or the client of a player, which the list next to its title picks.

• Resources: each resource of the process, with the milliseconds that its scripts take each tick, as resmon shows them, which leave out the calls that they make of other resources. Clicking one shows what it has: its exports, the events that it handles, its NUI callbacks, its commands, the keys that it bound them to on the client of a player, and its KVP.
• Convars: the convars of the process, with their values, which the box above them filters.
• Code: the box under them runs Lua in the resource that is picked, as one of its scripts would, so it sees its globals and may call its natives and Wait, or JavaScript if the resource has no Lua. An expression prints what it gives on the console of the process, such as GetNumResources(), and the arrow keys go back through what ran.

Map

The map shows the world of the server on a grid of metres, with the north up: the entities of its game state, where their owners last synced them, the peds of players as arrows that turn as they do, with their names, and the blips that the scripts of the players put on their maps, with the circles and areas of those around coordinates, and lines to those that show routes. There is no map of GTA V under them, whose pictures are Rockstar's, but the blips of garages, shops and jobs draw the city well enough. The map fits what is on it as it changes, until the wheel zooms it, dragging moves it or a player is dragged on it, and Fit has it fit again, clear of what its style draws over its edges. The names of blips show as the map zooms in, where they have room, clear of each other and of what the map draws, and the names of players always show. Hovering a blip or an entity tells of it.

• Dragging the ped of a player puts it where it is dropped, at the height it had, with the vehicle it is in, as a script of the client would with SetPedCoordsKeepVehicle, which its client syncs to the server. Dropped on a blip, it goes where the blip is, at its height, as the blips of garages, shops and jobs are where players use them.
• A double click sets the waypoint of a player there, as the map of the game does: that of the player whose blips the map shows, or of the first that joined.

The map has three styles, of which it starts with the cartoon, and the dev UI keeps the one that you pick for the next time:

• Classic: dots, arrows and a grid, on the dark of the dev UI.
• Cartoon: a meadow with trees, bushes and flowers under drifting clouds, where little people face the way they go, walk there, breathe and blink, cars seen from above puff as they drive, blips are the tokens of a board game, on sand, and the waypoint is a flag that waves. Players stand in rings of their colours, dressed as their peds are: their skins are those of the parents of their heads, their hair has the colour that SetPedHairColor gives it, and their tops, legs and shoes the colours that FiveRunner gives the drawables and textures of components 11, 4 and 6, as it has none of the clothes of GTA V to see. The cursor lifts the player that it drags, and a compass and a scale stand in a corner.
• GTA: the style of the pause menu of GTA V: its header, with the players of the session, glyphs outlined in black on the dark of a sea and the lines of its depths, players as arrows with cones of sight and the tags of their names, magenta routes with chevrons that run along them, a legend that counts the blips of each name, and the buttons that the map takes. Map image puts an image of the world of your own under it, from your computer, with the coordinates of the world at its edges, which the dev UI keeps for the next time, but not the image.

FiveRunner has no image of the map of GTA V, whose pictures are Rockstar's, nor of its blips: the icons of the styles are FiveRunner's own, for the sprites of garages, shops, liquor stores, hardware stores, clothes, barbers, tattoos, surgeons, guns, banks, hospitals, medicine, police, fuel, houses, cars, customs, crafting, impounds, boats, airports, diving and canteens, and the first letter of their names, or a dot, for others. Its colours are FiveRunner's own too, near those that GTA V names for the colours of blips.

Players

Connect a player runs the server until it has been up for 3 seconds, as players of FiveM reach servers that are up, whose scripts set what clients read as they load, then starts a client and connects it to the server with the name in the box, and a license of the name, license: and the SHA-1 of the name, as players of FiveM have the license of their Rockstar account, which frameworks such as QBox and ESX keep their characters by. It joins as a FiveM client does: the server's playerConnecting handlers and deferrals run, then the client downloads its resources and starts them. While deferrals present an adaptive card, the player shows it, with a box for the JSON that its Action.Submit would give, which Submit card submits. Disconnect quits the client, as the player leaving the game does.

Each player has a console of its own, with what its client prints, and a screen: the game window of the client, 1920 by 1080 pixels, scaled to fit, which pages are laid out in. Enlarge has the screen take the whole width, and Shrink gives it back its place. Under the frames of NUI, where FiveM draws the game, the screen shows the world round the ped of the player, near the street, in the style of the map, which follows the ped where it goes, and the dresses of the cartoon change as scripts dress the ped. It fades to black as the game does, as DoScreenFadeOut and DoScreenFadeIn fade it, and blurs as TriggerScreenblurFadeIn blurs it, under the frames, which FiveM draws over both too.

While the screen of a player has the focus, which a click gives it, and NUI does not, W, A, S and D run the player where they say, with the north up, and shift sprints. At the wheel of a car, they drive it. Its keys go to the game of the client: they press the controls of GTA V that they press, such as E for INPUT_CONTEXT, which IsControlJustReleased(0, 38) sees, and run the commands that resources bound to them with RegisterKeyMapping, +command as they go down and -command as they go up. Keys that are held go up as the screen loses the focus. Under the screen, the keys of the keyboard that resources bound show with what they do, such as F5 Opens the bank, and a click presses one, so you see what a resource does without reading its scripts first.

NUI

The screen of a player shows the frames of its resources as FiveM's NUI shows them: one for each resource with a ui_page, once its scripts loaded, in the order they came, the focused one on top, each hidden until its page loads.

• SendNUIMessage posts messages to the frames, which pages get as message events, as in FiveM. Messages sent before a page listens are lost, as they are in FiveM.
• SetNuiFocus(hasFocus, hasCursor) gives the frames the keyboard while NUI has the focus, and the mouse while it shows the cursor. Without the cursor, the mouse goes to the game, which there is none of, and GetNuiCursorPosition follows it over the screen.
• Pages call callbacks as in FiveM: fetch('https://<resource>/<callback>', ...), with GetParentResourceName, reach the callbacks of RegisterNUICallback, RegisterNuiCallback and RegisterRawNuiCallback, which answer them at the end of the next tick of the client. Strict mode, the Origin of frames and the headers of responses are FiveM's.
• Pages load the files of their resources by relative URLs, and those of any resource that started at https://cfx-nui-<resource>/. Requests to other hosts go to the web, such as those for fonts and libraries of CDNs.

Each frame is at an origin of its own, for each resource and each player, as in FiveM, where each is at https://cfx-nui-<resource>: pages keep their storage to themselves, and keep it as the project runs anew.

Changes

As files of a resource change, the dev UI restarts it, as restart does, if it runs: the players stay, and their clients start it anew, with its frames. As a manifest, a .sql file or a file of no resource changes, such as server.cfg, it runs the project anew: a new server, with a new database and the players it had, who connect again in the order they came. The Restart button does the same.

What it does not do

There is no game: the natives of GTA V that FiveRunner does not implement, such as most of those of the HUD and of the tasks of peds, do nothing and return zero values, as they do in tests, and FiveRunner tells you of the first time a resource calls each. Those that have nothing to do without a game, such as the density of the population, do nothing without telling. Clients have the ped of their player and the entities and players near it, and the server the entities that scripts create, which stay where scripts put them, and it has clients run the natives that FiveM's server has them run, as the differences from FiveM tell. The PerformHttpRequest of the server sends real requests, through the dev server, where tests send none.

differences.md lists where FiveRunner differs from FiveM, the dev UI too.

How it works

The dev UI runs FiveRunner's engine in a web worker of its page, with the files of the project, which it reads of the dev server as the engine needs them. Each origin of frames has a service worker, which answers the requests of their pages: it asks the engine, through a frame of the origin that the dev UI loads first, for the files of resources and what callbacks answer, and gives the documents of frames what FiveM's NUI gives them before their own scripts, such as GetParentResourceName.