New BeamNG.drive Documentation

The documentation unfortunatly isnt very up to date. It also lacks a lot of details about vehicles.

 

NOTTHE LAND SALE

 

One suggestion, if I´m free to do so:
The Documentation needs in my opinion a better material section. I think it misses important things, like how to create PBR materials, what problems could occur, when setting then up, along with with possible solutions for that problems. That would be very helpful to newbies and people, who want to create custom textures for their mods. Maybe, after the Blender JBeam plugin, this would be a nice thing. But PLEASE, don´t make modding entire vehicles too easy or the forums will be overflown by mid quality vehicle mods...

 

I didn’t find anything in the documentation so as a suggestion and also a question, is it possible to increase the spawn-radius around the players vehicle? If so, how can I do this?

To increase the development time of the documentation, would it be a good idea to let the community upload articles for review? Maybe it’s easier to edit them as writing from scratch.

 

Hi, first of all thanks for the efforts in keeping the documentation up to date! I have found it very helpful so far, but one piece of information that is missing and that might also be of interest to regular players is how to create thumbnails for car configurations in the same style as the original ones.

After searching through the forums I eventually found out that the tools needed to do so seem to be shipped with BeamNG.drive itself and I am providing the list of steps needed to create thumbnails in the same visual style as the base game below. In doing so, I hope that people looking for that kind of information will at least find this post until the official documentation is updated.

1. In the main menu select Freeroam. Then make sure to check "Include auxiliary debug content". You should now be able to load a map called "Showroom".
2. After loading the map, click on the button called "Thumbnail Generator" in the "Showroom Tools" window, which should automatically open once the map has loaded.
3. In the "Output" tab, select thumbnail under "Common Resolution". Personally, I also set Supersampling to 16. That will enlarge the screenshot size by four times in each direction and improves anti-aliasing quality when downsampling afterwards.
   
4. In the "Vehicle" tab, select the vehicle(s) you wish to generate thumbnails for or "Player Vehicle" to set it to the vehicle that the player is currently in.
5. Press the Run icon to start generating thumbnails for the selected vehicle(s). Note that it is not possible to select specific configurations for the selected vehicle(s), so you will have to wait until processing the configuration(s) you wanted to created thumbnails for has finished if you want to use the Stop button to end thumbnail generation early.
6. If you set a Supersampling value greater than 1, you then need to open the corresponding vehicles folder in your custom user files folder (see https://documentation.beamng.com/support/userfolder/) and manually downsize the created image(s) to the thumbnail resolution used by the game.

Things to note: It seems that the thumbnails for the in-game vehicles/configurations are created with the engine off as the running lights are not turned on. If you want to have thumbnails similar to the original ones, make sure that vehicles spawn with the engine turned off (unless already set so in the Options) while generating thumbnails. That being said, even then there will be some visual differences compared to the original thumbnails, at least on my system. I suspect that this is due to some graphics settings and hope that the official documentation is able to clarify how to reproduce the thumbnails exactly.

Updated 2024-01-02:
As of 0.31, a Supersampling value of 16 results in an eight times oversampled image.

 

I also have a remark for and would like to suggest two additions to the documentation on how to create a UI app at https://documentation.beamng.com/modding/ui/app_creation/.

First of all, the example towards the end states that apps can store data via a controller that is available as a fourth argument to the link function. In practice that does not seem to work as I am getting errors when trying to follow the example. Can you please update that piece of documentation (and maybe provide an up-to-date alternative?)

Finally, I would strongly suggest that you mention in the documentation that you can reload the in-game UI by pressing F5 (or Shift-F5) after making changes to the JavaScipt file outside of the game. Knowing this rapidly accelerated my develop-test-debug cycle. You should also point out that you can bring up (Chrome's?) Web Developer Tools by pressing CTRL-u, which not only offers a DOM inspector but also a JavaScipt console and debugger. I found that information here on the forums (https://www.beamng.com/threads/how-do-i-reload-the-system-for-ui-app-creation.46865/) when searching for it via Google, but I think that such useful information should be included in the official documentation for UI app modding.

Thanks in advance for considering my input!

 

Hi, I have some more input for the documentation after my recent exploits in modding BeamNG.drive.

First of all, I really appreciated the elaborate documentation of the Input system when I was working on creating a custom keybinding. But while creating a Lua function that I wanted the Input System to trigger, I really struggled with the currently very sparse Lua section of the documentation and recommend that you expand this section:

• I would have definitely appreciated an explanation of the folder structure that I eventually found in the old Lua:Reference wiki page.
• I would also like to see an explanation behind the extensions subfolder in both lua/vehicle and lua/ge. I intuitively assumed that mods should be placed somewhere in the extensions subfolder, but would like to have some confirmation on whether that's correct. If there are any other "important" subfolders that modders should be aware of that information should also be included in the documentation.
• The information on the modScript.lua and, if that's still up-to-date, also the mainLevel.lua files (see section Specific Lua files) should also be migrated to the new documentation.
• When creating modules for the Lua engine running the vehicle code knowing that the script files in a mod's lua\vehicle\extensions\auto folder will be loaded automatically was crucial to me for getting things to work. That information should definitely be added to the Lua documentation as I only found it when a Google search eventually led me to this forum post from 2016.

I also noticed that the release notes sometimes provide important information on the Lua subsystem such as the most recent 0.31 release notes. Information like the note in the big yellow box should probably also be included in the documentation itself, as I doubt that people are likely to find it otherwise.

Finally, I have some remarks regarding the Skin Tutorial.

I understand that you want people to use the material editor instead of editing the files manually as this allows you to keep the "internals" of the files an implementation detail so that you have a lot less documentation overhead. But the material editor section can definitely be improved upon:

• First of all, please be more precise as to where the files saved in the material editor are stored. There are three possible locations that I know of: %LOCALAPPDATA%\BeamNG.drive\<Version>\mods\unpacked\<ModDirectory>\vehicles, %LOCALAPPDATA%\BeamNG.drive\<Version>\temp\vehicles, and %LOCALAPPDATA%\BeamNG.drive\<Version>\vehicles. I initially assumed that it would simply overwrite the file it read the properties from, but it seems to use %LOCALAPPDATA%\BeamNG.drive\<Version>\vehicles instead, which ironically was the last location that I checked when editing materials from an unpacked mod of mine.
• A lot of times the screenshots contain additional information that is not available in the written text. That's bad for multiple reasons:
  1. I can search text, but I can't search screenshots.
  2. The text in the material editor UI is small and the layout is very compact, so it's even worse to read on screenshots than it is in-game.
  Screenshots should only illustrate what the written text says, not be the sole source of information. An example where this caused quite some frustration for me (because I could not find what I was looking for) is the documentation for color palette map in the Fully colorable skin section: I spent way too much time looking for that property in the material editor until I eventually realized in a screenshot that they are located in an "Advanced Properties" drop-down. The fact that it's called "color palette map" in the documentation but "BaseColor Palette Map" in the material editor also did not help.

I was very happy to read about the texture cooker, in particular because I was struggling to convert my textures manually such that they were compatible with the game. (Even though I was using BC7 compression, the game had issues reading them.) However, when modding an existing skin one will typically also want to convert from DDS back to PNG. After some searching, I finally found a still maintained and vendor independent solution, namely Microsoft's DirectXTex project. The texconv utility available from their binary releases is fairly straight-forward to use, provided that you read their Texconv wiki page, which explains the command-line parameters better than the command-line help accessible via `texconv.exe /?`. In my case converting DDS back to PNG was as simple as `texconv.exe -ft png <Input>`. You should definitely consider adding this piece of information to the documentation. (The image processing software that I have access to, which is Gimp and Affinity Photo, were not able to open BC7 compressed DDS files on their own, so overcoming that obstacle was pretty important to me.)

As always, thanks in advance for considering my input!

 

I have more input for the User Interface documentation after I spent the last days of the holiday season with modifying an UI app I had previously created.

The changes were prompted by me discovering that the User Interface of BeamNG.drive is apparently being ported from AngularJS to Vue.js and I would have appreciated it if the following information was available directly on the User Interface page:

• While the BeamNG.drive is currently built on AngularJS, the game already also integrates an instance of the Vue.js framework.
• To query the framework versions the game is currently using, you can use `angular.version` and `Vue.version`, respectively, in the Console provided by the CEF Devtools. (At the time of writing the game is shipped with AngularJS 1.5.8 and Vue.js 3.3.4.) That's important to make sure that I am looking at the correct version of the documentation, particularly for Vue.js, where the name has not changed when they transitioned from major version 2 to major version 3.

On the Creating an app page, I would have found the following information to be helpful, as I had to search the entire ui subfolder of the game's folder to find it:

• While BeamNG.drive UI apps are also using the AngularJS framework it is possible to use Vue.js by creating a Vue app using the Options API of Vue on the fly in the `link` function of the AngularJS directive. The game already ships apps that are using this technique, see for example SimpleDigSpeedo and SimpleDigSpeedoAir in ui\modules\apps.
• When your app is not using data from any stream in particular but should still react on an update of the streams (the SimpleTime app is written like this, for example), then it's important to know that there is a bridge between AngularJS and Vue.js: ui\ui-vue\src\bridge\libs\Hooks.js contains the line `window.vueEventBus && window.vueEventBus.emit("onStreamsUpdate", oldFormat)`, which translates AngularJS events into Vue.js events. If we look inside ui\lib\int\vueService.js we can see that BeamNGBaseAppMixin.mounted() will automatically register any method that starts with 'on' with the event system: `if(k.substr(0, 2) === 'on' && k.length > 2) window.vueEventBus.on(k, this[k])`. So having a Vue.js app that reacts on an update of the streams is as simple as defining a method named onStreamsUpdate() in it:
  
  Code:

  methods: {
    onStreamsUpdate() {
      // Your Code here...
    }
  }
  

One of the benefits of Vue.js is a caching mechanic that can prevent unnecessary updates of the DOM by introducing reactive state. While transforming the SimpleTime app into a Vue app embedded into the AngularJS framework as an exercise, I have noticed that when computed properties are being used any update to the associated reactive state will cause the associated computed property to be re-computed, even if the value of the reactive state did not change. You can set a breakpoint inside the computed property to verify this. (The DOM only seems to be updated when the computed property actually differs, though.)

It therefore makes sense—at least for properties that are expensive to compute—to introduce an updateData() method that would only update the reactive state when its value changes and use it when reacting on events that might not necessarily change the value of the reactive state.

I am attaching my Vue.js-in-AngularJS version of SimpleTime in case anyone is curious.

Finally, I noticed that a copy of the work-in-progress version of the Vue.js port is already included with the game inside the ui\ui-vue\src subfolder of the game's folder with instructions on how to get it running in-game available from ui\ui-vue\README.md. I can already see a lot of native Vue apps inside ui\ui-vue\src\modules\apps, so I am guessing that significant progress has already been made. But I'm not sure by how much that code is still subject to change prior to it being fully finished. I can already tell, however, that the native Vue apps seem to be using the Compositions API of Vue instead.

While the documentation might not necessarily be the proper place to communicate this, would it be possible to get a heads-up one or two versions in advance before the Vue.js port becomes the new default UI? That way people who made their own UI apps would have a transition period that would allow them to port their apps over to Vue so their apps are already working with the new system once it drops. As someone who does not get to play the game very often, I would definitely appreciate this as that way I will have enough time to prevent being greeted by my own UI apps not working when I launch the game after the switch to Vue goes live.

 

Under the "Driver Safety and Electronics" section, there is no data on ESC parameters. Aside from the self-explanatory slipThreshold and the three PID variables elaborated upon in another thread, there is effectively nothing to shed light on what values like skewStiffnessFront, skewStiffnessRear, integralInCoef, and integralOutCoef do or what acceptable thresholds they have, short of dissecting vanilla cars' ESC systems. Regardless, ESC tuning is still largely a series of stabs in the dark for those not involved with the development of such systems on vanilla vehicles.

 

I may be wrong, but it seems that "extensions.load" is deprecated, and when it is used, information about it is displayed in the console. (At least in GE)
https://documentation.beamng.com/modding/programming/extensions/#using-an-extension

--- Post updated ---

To clarify, "extensions.load" is deprecated when used in "/scripts/modScript.lua" (GElua)

But if it is used in another module (loaded via "setExtensionUnloadMode"), everything will be fine

--- Post updated ---
An important nuance which in my opinion should be clarified, use "setExtensionUnloadMode" need or:
1. Passing the path to the file in the format "scripts_tearingMetal_extensions", for example:

Code:

setExtensionUnloadMode('scripts_tearingMetal_extensions', 'manual')

or
2. Skip through "extensions.luaPathToExtName":

Code:

setExtensionUnloadMode(extensions.luaPathToExtName('scripts/tearingMetal/extensions'), 'manual')

Otherwise, when using

Code:

setExtensionUnloadMode('scripts/tearing Metal/extensions', 'manual')

the module will be loaded, but due to an error in the game code it will still be unloaded. Despite the seemingly set "manual" mode.
--- Post updated ---
In simple words, the error is that the existence of the module in the "manualUnloadExtensions" array is checked by the "converted" name, but the array contains the original path passed by the user.
load:

unload:
​

 

Since v0.30 there is an option for automatic transmissions to have partial lockup but the variables are not mentioned in the documentation. In the files i only found: "torqueConverterHasPartialLockup" and "torqueConverterMinPartialLockupRatio" but i don't know how to use them. Can you explain how can i set when partial lockup activates and by how much?
Also there are more jbeam variables missing that im finding in game files and mods, can you please add everything regarding engines and automatic transmissions

 

Please add a section for available data streams similar to the old wiki page.

The old wiki has this outdated page: https://wiki.beamng.com/Streams.html

but I do not see anything in the current documentation.

 

That makes sense, thanks for the reply!

In the future it would be great to see a command that runs through the whole project and lists out all the current data streams, then on the docs site you can list out the available commands for the users.

Not sure how practical that is but would be but it would be great for people like me new to the beamNG development space.

 

Hope it will be improved, I would like some colors to separate easier the brands between them and something like a brochure for each vehicle as the Scintilla got in 0.25.

 

Can we get the measurements in Imperial units?
Y'know, a lot of us forums members are just dumb Americans.

 

looks great

i wish someone had the time to add the lore the wiki had