feat(routing-buckets): add support for routing bucket related features and plugin updates

Author: TomGrobbe

README.md

@@ -71,6 +71,19 @@ Just like vMenu legacy, vMenu Enhanced will be using [MenuAPI (MAPI)](https://gi
 
 vMenu Enhanced can be extended with **plugins**, which are separate FiveM resources that add their own menus inside vMenu. A plugin never patches vMenu, and vMenu does not need to know it exists beforehand. The two introduce themselves to each other while the server runs, in whatever order they happen to start.
 
+### Official plugins
+
+Made and kept up to date alongside vMenu itself. Each one is ready to install, and each is also worth reading as an example of how a plugin is put together.
+
+| Plugin | What it does |
+| --- | --- |
+| [Routing Buckets](https://github.com/TomGrobbe/vMenu.RoutingBucketsPlugin) | Allows you to manage routing buckets on your server. |
+| [Theme Picker](https://github.com/TomGrobbe/vMenu.ThemePicker) | Let's each player choose a theme for vMenu themselves, rather than being forced to use the server theme. |
+| [Custom Themes](https://github.com/TomGrobbe/vMenu.CustomThemesPlugin) | Allows you to easily add new custom themes to vMenu. |
+| [Example Plugin](https://github.com/TomGrobbe/vMenu.ExamplePlugin) | Example plugin, do not use on public servers, use this as a tempalte if you want to make your own plugins. |
+
+### Writing your own
+
 Two NuGet packages are all you need to write one:
 
 | Package | Used by |
@@ -85,7 +98,7 @@ Where to read more:
 - [What plugins are](https://docs.vespura.com/vmenu/enhanced/plugins/), if you have not met one yet
 - [Installing plugins](https://docs.vespura.com/vmenu/enhanced/plugins/installing/), for server owners
 - [Making a plugin](https://docs.vespura.com/vmenu/enhanced/plugins/developing/), for developers
-- [vMenu.ExamplePlugin](https://github.com/TomGrobbe/vMenu.ExamplePlugin), a complete working plugin to copy from
+- The [official plugins](#official-plugins) above, all of them complete working plugins to copy from
 
 A plugin built on these packages is a work based on vMenu, so it carries the same license vMenu does. That means open sourcing it if you hand it to anybody else, free or paid. See [License](#license) below, and the [licensing section of the plugin docs](https://docs.vespura.com/vmenu/enhanced/plugins/developing/#license) for what it asks of you in practice.
 

docs/src/content/docs/admin-menu.md

@@ -27,6 +27,8 @@ Only the staff member who picked somebody up can put them down. If two of you re
 
 "Closest" means the closest player your game actually knows about. On a busy server your game is only told about people near you, so this finds somebody standing in front of you, not somebody on the other side of the map. How far it reaches is set by `vMenu.Enhanced.Admin.ClosestPlayerRange`, which defaults to 5 metres and can go up to 15.
 
+**Return To The Default World** puts you back in the main routing bucket, for when you teleported to someone who was in a different bucket.
+
 **Show Players In NoClip** is the same option that used to live in Miscellaneous Settings. It keeps showing the blip and the name of anybody flying around in noclip, who everybody else has them hidden from.
 
 ### Vehicles
@@ -210,6 +212,7 @@ These go in your `configuration.cfg`. They are all listed in the `configuration.
 | `...Admin.Announce` | Sending an announcement to the whole server |
 | `...Admin.ManageAnnouncements` | Adding and removing scheduled announcements, which writes the config file |
 | `...Admin.RefreshPermissions` | Refreshing everybody's permissions at once |
+| `...Admin.ResetRoutingBucket` | Putting yourself back in the default world |
 
 All of them start with `vMenu.Enhanced.Menus.`, and `...Admin.All` grants the lot. They are listed in the `config/permissions.cfg.example` file your server writes on every start.
 

docs/src/content/docs/plugins/developing.md

@@ -9,8 +9,12 @@ A look at what a tiny JavaScript plugin could look like can be found in the cust
 :::tip[Start from an example]
 [vMenu.ExamplePlugin](https://github.com/TomGrobbe/vMenu.ExamplePlugin) is a complete working plugin that uses every kind of row once. Copy from it.
 
+[vMenu.RoutingBucketsPlugin](https://github.com/TomGrobbe/vMenu.RoutingBucketsPlugin) is a more advanced plugin. This plugin includes server and client side code, both sides talking to each other, server side permission checks on everything, live state pushed out to the menu (live menu updates), rows in [Online Players](#player-actions), and a saved config file of its own.
+
 For theme related plugins, see [vMenu.ThemePicker](https://github.com/TomGrobbe/vMenu.ThemePicker),
 and [vMenu.CustomThemesPlugin](https://github.com/TomGrobbe/vMenu.CustomThemesPlugin), and read [registering themes](#adding-themes-of-your-own) to see how you can make your own themes for your server.
+
+All four are listed on the [plugins page](/vmenu/enhanced/plugins/).
 :::
 
 :::caution[Read the license section]

docs/src/content/docs/plugins/index.md

@@ -18,13 +18,18 @@ Everything a plugin adds uses vMenu's own permissions system. A missing or locke
 
 ## Official plugins
 
-These are made and kept up to date alongside vMenu itself. Each one is a real plugin you can install as it is, and each is also worth reading as an example of how a plugin is put together.
+These are made and kept up to date alongside vMenu itself. Each one is a real plugin you can install
+as it is, and each is also worth reading as an example of how a plugin is put together.
 
 | Plugin | What it does |
 | --- | --- |
-| [Theme Picker](https://github.com/TomGrobbe/vMenu.ThemePicker) | Let your players pick their own theme. |
-| [Custom Themes](https://github.com/TomGrobbe/vMenu.CustomThemesPlugin) | Use this plugin to create and register your own themes inside vMenu. |
-| [Example Plugin](https://github.com/TomGrobbe/vMenu.ExamplePlugin) | An example plugin in C#. You shouldn't use this on your production server, but feel free to use it as a baseline for making your own C# plugin. |
+| [Routing Buckets](https://github.com/TomGrobbe/vMenu.RoutingBucketsPlugin) | Allows you to manage routing buckets on your server. |
+| [Theme Picker](https://github.com/TomGrobbe/vMenu.ThemePicker) | Let's each player choose a theme for vMenu themselves, rather than being forced to use the server theme. |
+| [Custom Themes](https://github.com/TomGrobbe/vMenu.CustomThemesPlugin) | Allows you to easily add new custom themes to vMenu. |
+| [Example Plugin](https://github.com/TomGrobbe/vMenu.ExamplePlugin) | Example plugin, do not use on public servers, use this as a tempalte if you want to make your own plugins. |
+
+Every one of them is GPL-3.0-or-later, same as vMenu, and each publishes a ready to drop in zip on its
+own releases page.
 
 ## Where to go from here
 

docs/src/content/docs/webhook-logging.md

@@ -37,7 +37,7 @@ Everything else a menu can do is deliberately not logged. Opening the about page
 
 If you want something added to this list, open an issue. The list lives in the code, not in a setting.
 
-**Staff**, what a player does to somebody else. Kicking, killing, summoning, messaging, wanted levels, freezing, carrying, lending noclip, deleting vehicles, clearing areas, announcing.
+**Staff**, what a player does to somebody else. Kicking, killing, summoning, messaging, wanted levels, freezing, carrying, lending noclip, deleting vehicles, clearing areas, announcing, and putting themselves back in the default world.
 
 Staff alerts live here too. You get a line when somebody raises one, with their reason, and another when a staff member answers or dismisses it, naming both people. An alert nobody answers before it runs out is logged as well, so a missed call for help leaves a trace.
 

src/Client/vMenu.Enhanced.MenuFramework/Localization/Languages/EnglishStrings.cs

@@ -1362,6 +1362,10 @@ internal static class EnglishStrings
             [Loc.Admin.RefreshPermissions] = "Refresh All Permissions",
             [Loc.Admin.RefreshPermissionsDescription] = "Hand everybody on the server a fresh copy of what they are allowed to do. Use it once you have actually changed somebody's permissions on the server, so their menu catches up without them having to rejoin.",
             [Loc.Admin.RefreshPermissionsDone] = "Refreshed permissions for ~g~{count}~s~ player(s).",
+            [Loc.Admin.ResetRoutingBucket] = "Return To The Default World",
+            [Loc.Admin.ResetRoutingBucketDescription] = "Put yourself back in the world everybody else is in. Teleporting to a player in a separate world takes you along with them, and this is the way back out again.",
+            [Loc.Admin.ResetRoutingBucketDone] = "Moved you out of world ~y~{bucket}~s~ and back into the default world.",
+            [Loc.Admin.ResetRoutingBucketAlready] = "You are already in the default world.",
 
             [Loc.StaffAlerts.Title] = "Staff Alerts",
             [Loc.StaffAlerts.Subtitle] = "{count} waiting",

src/Client/vMenu.Enhanced.MenuFramework/Localization/Loc.Admin.cs

@@ -179,5 +179,13 @@ public static class Admin
         public const string RefreshPermissionsDescription = "admin.refreshpermissions.desc";
 
         public const string RefreshPermissionsDone = "admin.refreshpermissions.done";
+
+        public const string ResetRoutingBucket = "admin.resetroutingbucket";
+
+        public const string ResetRoutingBucketDescription = "admin.resetroutingbucket.desc";
+
+        public const string ResetRoutingBucketDone = "admin.resetroutingbucket.done";
+
+        public const string ResetRoutingBucketAlready = "admin.resetroutingbucket.already";
     }
 }

src/Client/vMenu.Enhanced.Menus/Admin/AdminPlayerActions.cs

@@ -12,6 +12,8 @@ public static class AdminPlayerActions
 {
     private const string On = "1";
 
+    private const string DefaultRoutingBucket = "0";
+
     private static int _carrying;
 
     private static bool _busy;
@@ -124,6 +126,29 @@ public static async Task RefreshEveryonesPermissionsAsync()
             ("count", MenuText.Literal(result.Data[0]))));
     }
 
+    public static async Task ResetRoutingBucketAsync()
+    {
+        var result = await ServerActions.InvokeAsync(ActionIds.Admin.ResetRoutingBucket);
+
+        if (result.Status != ActionStatus.Ok || result.Data.Length < 1)
+        {
+            AdminReport.Show(result);
+
+            return;
+        }
+
+        if (result.Data[0] == DefaultRoutingBucket)
+        {
+            Notifications.Info(MenuText.Key(Loc.Admin.ResetRoutingBucketAlready));
+
+            return;
+        }
+
+        Notifications.Success(MenuText.Key(
+            Loc.Admin.ResetRoutingBucketDone,
+            ("bucket", MenuText.Literal(result.Data[0]))));
+    }
+
     private static RosteredPlayer? Closest()
     {
         var target = AdminTargeting.Closest();

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

@@ -22,7 +22,8 @@ public sealed class AdminMenu : MenuDefinition
     private static MenuGate PlayersGate =>
         MenuGate.Permission(AdminPermissions.FreezePlayer)
         | AdminPermissions.GrabPlayer
-        | AdminPermissions.SeeNoClipPlayers;
+        | AdminPermissions.SeeNoClipPlayers
+        | AdminPermissions.ResetRoutingBucket;
 
     private static MenuGate VehiclesGate =>
         MenuGate.Permission(AdminPermissions.DeleteVehicle)
@@ -62,6 +63,14 @@ protected override void Build(MenuBuilder menu)
             OnSelectedAsync = _ => GrabAsync(menu),
         });
 
+        menu.Entries.Add(new ButtonEntry
+        {
+            Text = MenuText.Key(Loc.Admin.ResetRoutingBucket),
+            Description = MenuText.Key(Loc.Admin.ResetRoutingBucketDescription),
+            Gate = AdminPermissions.ResetRoutingBucket,
+            OnSelectedAsync = _ => AdminPlayerActions.ResetRoutingBucketAsync(),
+        });
+
         menu.Entries.Add(new CheckboxEntry
         {
             Text = MenuText.Key(Loc.Admin.SeeNoClipPlayers),

src/Client/vMenu.Enhanced.Plugins/PluginHost.cs

@@ -262,14 +262,23 @@ private static void Register(string resource, string json)
         // that knows nothing of the menus the player may be standing in right now.
         CloseIfInsideAPluginMenu();
 
+        var firstRegistration = !Plugins.ContainsKey(resource);
+
         Plugins[resource] = state;
         LastPayload[resource] = json;
 
         RebuildRows();
 
         RaiseChanged();
 
-        Log.Info($"[Plugins] Registered '{resource}' with {state.ItemsById.Count} item(s).");
+        if (firstRegistration)
+        {
+            Log.Info($"[Plugins] Registered '{resource}'.");
+        }
+        else
+        {
+            Log.Debug($"[Plugins] '{resource}' re-registered with {state.ItemsById.Count} item(s).");
+        }
 
         Reply(resource, result);