fix(natives): fix broken natives and document things, this also fixed vehicle spawner needing an external resource temporarily.

Author: TomGrobbe

docs/src/content/docs/getting-started.md

@@ -11,6 +11,30 @@ vMenu Enhanced is in early alpha. Installation and configuration steps are not f
 
 - A FiveM **Enhanced** server.
 
+## Installation
+
+### Filesystem permissions
+
+vMenu Enhanced writes files into its own resource folder (saved vehicles, outfits, and other
+persistent data). FiveM Enhanced blocks resources from writing to disk unless you explicitly
+grant permission, so add the following line to your `server.cfg` **before** the line that starts
+vMenu Enhanced:
+
+```cfg
+add_filesystem_permission vMenu.Enhanced write vMenu.Enhanced
+ensure vMenu.Enhanced
+```
+
+Both names in that command are resource names: the first is the resource being granted access
+(vMenu Enhanced), the second is the resource whose folder it may write to (its own). If you renamed
+the resource folder, use your own folder name in both places.
+
+:::danger[Order matters]
+The permission must be set before the resource starts. If `ensure vMenu.Enhanced` comes first,
+vMenu Enhanced will not be able to save anything and you will see filesystem errors in the server
+console.
+:::
+
 ## Where things stand
 
 Setup instructions, configuration, and permissions documentation will land here as vMenu Enhanced becomes usable. 

src/Client/vMenu.Enhanced.BrokenNatives/NativeFixer.cs

@@ -0,0 +1,23 @@
+using CitizenFX.Base;
+using CitizenFX.FiveM.Client;
+
+namespace vMenu.Enhanced.BrokenNatives;
+
+/// <summary>
+/// Natives that are broken in the API get fixed here.
+/// </summary>
+public static class NativeFixer
+{
+    internal static NativeApi nativeApi = BaseEntrypoint.NativeApi;
+
+    /// <summary>
+    /// Replacement call for <see cref="Native.GetAllVehicleModels" /> because that return type is <pre>byte[]</pre>
+    /// </summary>
+    /// <returns></returns>
+    public static string[] GetAllVehicleModels()
+    {
+        nativeApi.ResetContext();
+        nativeApi.Invoke(3612546629uL, "GetAllVehicleModels");
+        return nativeApi.GetResObject(0).DeserializeTo<string[]>();
+    }
+}

src/Client/vMenu.Enhanced.BrokenNatives/vMenu.Enhanced.BrokenNatives.csproj

@@ -0,0 +1,5 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <ItemGroup>
+    <PackageReference Include="CitizenFX.FiveM.Client" />
+  </ItemGroup>
+</Project>

src/Client/vMenu.Enhanced.Menus/VehicleSpawnerMenu.cs

@@ -1,5 +1,3 @@
-using System.Text;
-
 using CitizenFX.Base;
 using CitizenFX.FiveM.Client;
 using CitizenFX.FiveM.Client.Extensions;
@@ -14,7 +12,7 @@ namespace vMenu.Enhanced.Menus;
 /// </summary>
 public sealed class VehicleSpawnerMenu
 {
-
+    internal static NativeApi nativeApi = BaseEntrypoint.NativeApi;
 
 
     public async Task<Menu> GetMenu()
@@ -26,18 +24,12 @@ public async Task<Menu> GetMenu()
         MenuController.MainMenu.AddMenuItem(linkBtn);
         MenuController.BindMenuItem(MenuController.MainMenu, menu, linkBtn);
 
-        API.Log.Info("Calling something.GetVehicleList now");
-        var data = API.Exports["something"].Call<string>("GetVehicleList");
+        var vehicles = BrokenNatives.NativeFixer.GetAllVehicleModels();
 
-        // This is broken due to crash: https://github.com/citizenfx/rfc/discussions/328
-        //var vehicles = System.Text.Json.JsonSerializer.Deserialize<string[]>(data);
 
-        API.Log.Info("Got vehicle list data: " + data);
-        var vehicles = data.Replace("[", "").Replace("]", "").Replace("\"", "").Split(',');
 
         if (vehicles is null)
         {
-            API.Log.Warn("Vehicle list is null");
             return menu;
         }
 
@@ -47,10 +39,6 @@ public async Task<Menu> GetMenu()
             .OrderBy(vehicle => vehicle)
             .GroupBy(vehicle => Native.GetVehicleClassFromName(API.Hash(vehicle)));
 
-        API.Log.Info("Vehicle list categorized and cleaned up");
-
-
-
         foreach (var cat in vehicleSperCategory)
         {
             var submenu = new Menu("Class: " + cat.Key.ToString(), "Vehicle Spawner Menu");
@@ -61,8 +49,10 @@ public async Task<Menu> GetMenu()
 
             submenu.OnItemSelect += Submenu_OnItemSelect;
             MenuController.AddSubmenu(menu, submenu);
+
             var btn = new MenuItem("Veh Class: " + cat.Key.ToString());
             menu.AddMenuItem(btn);
+
             MenuController.BindMenuItem(menu, submenu, btn);
             API.Log.Info("Added submenu for vehicle class: {0}", cat.Key.ToString());
         }
@@ -73,7 +63,23 @@ public async Task<Menu> GetMenu()
 
     private async void Submenu_OnItemSelect(Menu menu, MenuItem menuItem, int itemIndex)
     {
-        var veh = await API.Vehicles.RequestAndCreate(API.Hash(menuItem.Text), API.Players.Local.Ped!.Position, (int)API.Players.Local.Ped.Heading, true, true, true);
+        var hash = API.Hash(menuItem.Text);
+
+        // Manually checking and requesting model because API.Vehicles.RequestAndCreate uses datetime which is currently broken and crashes the game.
+        // https://github.com/citizenfx/rfc/discussions/328
+        if (!Native.IsModelValid(hash))
+        {
+            return;
+        }
+
+        Native.RequestModel(hash);
+
+        while (!Native.HasModelLoaded(hash))
+        {
+            await API.Delay(0);
+        }
+
+        var veh = await API.Vehicles.RequestAndCreate(hash, API.Players.Local.Ped!.Position, (int)API.Players.Local.Ped.Heading, true, true, true);
         if (veh is not null)
         {
             API.Players.Local.Ped.SetPedIntoVehicle(veh!.Handle, -1);

src/Client/vMenu.Enhanced.Menus/vMenu.Enhanced.Menus.csproj

@@ -2,4 +2,7 @@
   <ItemGroup>
     <PackageReference Include="MenuAPI.FiveM.Enhanced" />
   </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\vMenu.Enhanced.BrokenNatives\vMenu.Enhanced.BrokenNatives.csproj" />
+  </ItemGroup>
 </Project>

src/Server/vMenu.Enhanced.BrokenNatives.Server/NativeFixer.cs

@@ -0,0 +1,22 @@
+using CitizenFX.Base;
+
+namespace vMenu.Enhanced.BrokenNatives.Server;
+
+/// <summary>
+/// Natives that are broken in the API get fixed here.
+/// </summary>
+public static class NativeFixer
+{
+    internal static NativeApi nativeApi = BaseEntrypoint.NativeApi;
+
+    public static bool SaveResourceFile(string resource, string file, string buffer)
+    {
+        nativeApi.ResetContext();
+        nativeApi.PushArg(resource);
+        nativeApi.PushArg(file);
+        nativeApi.PushArg(buffer);
+        nativeApi.PushArg(-1);
+        nativeApi.Invoke(2694741627uL, "SaveResourceFile");
+        return nativeApi.GetResBool(0);
+    }
+}

src/Server/vMenu.Enhanced.BrokenNatives.Server/vMenu.Enhanced.BrokenNatives.Server.csproj

@@ -0,0 +1,5 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <ItemGroup>
+    <PackageReference Include="CitizenFX.FiveM.Server" />
+  </ItemGroup>
+</Project>

src/Server/vMenu.Enhanced.Core.Server/Placeholder.cs

@@ -13,5 +13,8 @@ public void Initialize()
     {
         API.Log.Info("Resource Loaded");
         //Native.SaveResourceFile()
+        Native.SetConvar("add_filesystem_permission", "vMenu.Enhanced write vMenu.Enhanced");
+
+        BrokenNatives.Server.NativeFixer.SaveResourceFile("vMenu.Enhanced", "test.txt", "Hello world");
     }
 }

src/Server/vMenu.Enhanced.Core.Server/vMenu.Enhanced.Core.Server.csproj

@@ -2,4 +2,7 @@
   <ItemGroup>
     <PackageReference Include="CitizenFX.FiveM.Server" />
   </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\vMenu.Enhanced.BrokenNatives.Server\vMenu.Enhanced.BrokenNatives.Server.csproj" />
+  </ItemGroup>
 </Project>

vMenu.Enhanced.slnx

@@ -13,6 +13,7 @@
   </Folder>
   <Folder Name="/src/Client/">
     <File Path="src/Client/Directory.Build.props" />
+    <Project Path="src/Client/vMenu.Enhanced.BrokenNatives/vMenu.Enhanced.BrokenNatives.csproj" />
     <Project Path="src/Client/vMenu.Enhanced.Configuration/vMenu.Enhanced.Configuration.csproj" />
     <Project Path="src/Client/vMenu.Enhanced.NoClip/vMenu.Enhanced.NoClip.csproj" />
     <Project Path="src/Client/vMenu.Enhanced.Core/vMenu.Enhanced.Core.csproj" />
@@ -21,6 +22,7 @@
   </Folder>
   <Folder Name="/src/Server/">
     <File Path="src/Server/Directory.Build.props" />
+    <Project Path="src/Server/vMenu.Enhanced.BrokenNatives.Server/vMenu.Enhanced.BrokenNatives.Server.csproj" />
     <Project Path="src/Server/vMenu.Enhanced.Configuration.Server/vMenu.Enhanced.Configuration.Server.csproj" />
     <Project Path="src/Server/vMenu.Enhanced.Core.Server/vMenu.Enhanced.Core.Server.csproj" />
     <Project Path="src/Server/vMenu.Enhanced.Permissions.Server/vMenu.Enhanced.Permissions.Server.csproj" />