Rust Wipe Plugins: Map Wipe and Force Wipe Checklist for Oxide and Carbon

On a Rust wipe, update the game server first, then Oxide or Carbon, then watch the console for failed plugins, reset the data files that belong to the old map, adjust configs, and test plugins before opening the server. Permissions and groups stay as they are unless you change them.

Map wipe vs force wipe

A map wipe creates a new world save. Plugin data that refers to entities, bases, positions or one-time claims from the old map becomes stale. Plugins and Oxide itself do not change.

A force wipe comes with a new Rust build. Besides the stale data, plugins can break because game code changed. Treat force wipe as a software update first and a wipe second.

Step 1: Update Rust, then Oxide or Carbon

The order matters. Oxide and Carbon patch game methods inside the Rust server files, so they must match the installed build.

1. Stop the server and back up oxide/ (or carbon/): plugins, config, data, lang.
2. Update the Rust dedicated server files.
3. Install the Oxide or Carbon build made for that Rust version, over the fresh files. See installing Oxide and Oxide vs Carbon if you are unsure which you run.
4. Start the server and run oxide.version to confirm the framework loaded. Carbon accepts the same oxide.* commands.

If you start the server with an old Oxide on a new Rust build, hooks may not fire at all, and plugins can appear loaded while doing nothing. Do not debug plugins until the framework version is correct.

Step 2: Read the console

After startup, run oxide.plugins to list loaded plugins and compare it with the files in oxide/plugins. A missing plugin did not load. Then scan the console and oxide/logs for these messages:

• Error while compiling <PluginName>: followed by numbered messages like [1] ... at 42:17. The plugin is skipped; others still load. Common causes after an update are renamed members. See fix Rust plugins after an update and CS1061.
• Failed to call hook '<Hook>' on plugin ... means the plugin compiled but throws at runtime. See NullReferenceException in hooks.
• Failed to initialize plugin means Init or Loaded threw, often from a corrupt data or config file. See failed to initialize plugin.
• Calling '<Hook>' on '<Name>' took <N>ms means a slow hook. Wipe day brings many players and fresh entities, so slow hooks hurt more. See performance warnings.

A successful load prints Loaded plugin <Title> v<Version> by <Author>. There is no separate "compiled successfully" line, so count loaded plugins against files.

Step 3: Handle removed or changed hooks

A new Rust build can remove or change the method a hook is attached to. Typical symptoms: a plugin loads with no errors but its feature never triggers, or a hook warns that it is deprecated. Work through it like this:

1. Check the monthly update reports on this site for hook changes in the new build.
2. Look up the hook's page for its current signature, for example CanBuild or OnEntityTakeDamage.
3. If the plugin's author has not updated it, compare the plugin's hook method signatures with the current ones. A changed parameter type makes Oxide skip the call, because it only calls a method when every argument is an instance of the declared parameter type.
4. For deprecated hooks, see deprecated hook will stop working.

Plugins that rely on ownership, damage or looting are the most exposed. Test them directly rather than assuming they work because they loaded. Oxide hooks explained covers how dispatch works.

Step 4: Reset per-wipe data

Data files live in oxide/data (carbon/data on Carbon). Sort them into three groups:

• Reset on every map wipe: homes, warps tied to bases, claimed one-time kits, clan or team base locations, raid logs, entity limits counters, bounties tied to the old map.
• Keep: bans and mutes, player reports, VIP records, lifetime statistics, persistent balances.
• Decide per server: playtime, kill streaks and leaderboards, depending on whether you run seasonal or lifetime rankings.

Back up before deleting. Plugins recreate a missing data file on next load, but a half-deleted set can leave inconsistent data. Stop or unload the plugin before removing its file, otherwise it writes the old data back on the next save. See plugin data files.

Detecting a wipe in code

The OnNewSave hook fires when the server creates a new save file, which is what happens on a map wipe. Plugins can use it to reset their own data. Because a plugin may load after the new save is created, the example also stores a map identifier and compares it in OnServerInitialized as a fallback. The example keeps a wipe counter and a per-wipe claims table.

using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;

namespace Oxide.Plugins
{
    [Info("Wipe Data Reset", "RustPluginGenerator", "1.0.0")]
    [Description("Resets per-wipe plugin data when a new map is created")]
    public class WipeDataReset : RustPlugin
    {
        private const string PermAdmin = "wipedatareset.admin";
        private const string DataName = "WipeDataReset";

        private PluginConfig config;
        private StoredData data;

        private class PluginConfig
        {
            [JsonProperty("Reset data on new map")]
            public bool ResetOnNewMap = true;
        }

        private class StoredData
        {
            public string MapKey = "";
            public int WipeCount;
            public string LastWipeUtc = "";
            public Dictionary<ulong, bool> ClaimedWipeKit = new Dictionary<ulong, bool>();
        }

        protected override void LoadDefaultConfig() => config = new PluginConfig();

        protected override void LoadConfig()
        {
            base.LoadConfig();
            try
            {
                config = Config.ReadObject<PluginConfig>();
                if (config == null) throw new Exception();
            }
            catch
            {
                PrintWarning("Configuration file is invalid, using defaults");
                LoadDefaultConfig();
            }
            SaveConfig();
        }

        protected override void SaveConfig() => Config.WriteObject(config);

        protected override void LoadDefaultMessages()
        {
            lang.RegisterMessages(new Dictionary<string, string>
            {
                ["NoPermission"] = "You do not have permission to use this command.",
                ["Info"] = "Wipe number {0}, last reset {1} UTC."
            }, this);
        }

        private string Msg(string key, string userId = null, params object[] args) =>
            string.Format(lang.GetMessage(key, this, userId), args);

        private void Init()
        {
            permission.RegisterPermission(PermAdmin, this);
            try
            {
                data = Interface.Oxide.DataFileSystem.ReadObject<StoredData>(DataName);
            }
            catch
            {
                data = null;
            }
            if (data == null) data = new StoredData();
        }

        private void OnNewSave(string filename)
        {
            if (config.ResetOnNewMap) ResetData("new save file");
        }

        private void OnServerInitialized(bool initial)
        {
            string key = ConVar.Server.seed + "_" + ConVar.Server.worldsize;
            if (string.IsNullOrEmpty(data.MapKey))
            {
                data.MapKey = key;
                SaveData();
            }
            else if (data.MapKey != key && config.ResetOnNewMap)
            {
                ResetData("map identifier changed");
            }
        }

        private void ResetData(string reason)
        {
            int count = data.WipeCount + 1;
            data = new StoredData
            {
                MapKey = ConVar.Server.seed + "_" + ConVar.Server.worldsize,
                WipeCount = count,
                LastWipeUtc = DateTime.UtcNow.ToString("yyyy-MM-dd HH:mm")
            };
            SaveData();
            Puts("Per-wipe data reset (" + reason + ").");
        }

        private void OnServerSave() => SaveData();

        private void Unload() => SaveData();

        private void SaveData() => Interface.Oxide.DataFileSystem.WriteObject(DataName, data);

        [ChatCommand("wipeinfo")]
        private void CmdWipeInfo(BasePlayer player, string command, string[] args)
        {
            if (player == null) return;
            if (!permission.UserHasPermission(player.UserIDString, PermAdmin))
            {
                player.ChatMessage(Msg("NoPermission", player.UserIDString));
                return;
            }
            player.ChatMessage(Msg("Info", player.UserIDString, data.WipeCount, data.LastWipeUtc));
        }
    }
}

The same pattern fits plugins like one-per-wipe kits and the wipe day kit: store claims in the data object and clear them in the reset method.

Step 5: Adjust configs per wipe

Configs live in oxide/config/<PluginName>.json. Things commonly changed each wipe:

• Gather, loot and farming multipliers, for example gather rate and loot multiplier, if you run rate changes by wipe week.
• Raid timing: no raiding after wipe, raid schedule.
• Kit contents and cooldowns.
• Wipe countdown dates (wipe countdown) and announcement text.

Edit configs while the plugin is unloaded or reload it afterward with oxide.reload <Name>. A config with invalid JSON makes the plugin fall back to defaults or fail, so validate edits. See plugin config files and failed to load config. Language files in oxide/lang are separate; see localization.

Permissions on wipe day

Permissions and group membership persist through map and force wipes. Nothing about them needs resetting. Use that to your advantage: VIP and admin setups carry over.

Things to do on purpose:

• Revoke wipe-only or event permissions: oxide.revoke user <name|id> <perm>.
• Verify a plugin's permissions exist after an update with oxide.show perms.
• If a plugin changed its permission names in a new version, grant the new names to the same groups.

More in permissions and groups and Oxide console commands.

Testing order

Test in dependency order so you can tell what is causing a problem.

1. Framework and libraries: oxide.version, then plugins others depend on (economy, clan or chat libraries). Plugins that reference them handle a missing dependency only if written to; see calling other plugins.
2. Server-wide plugins: permissions, chat, restarts, wipe countdown.
3. Gameplay rules: building, damage, raiding, PvE, vehicles. Test with a normal and an admin account.
4. Economy and rewards: gather, loot, kits, shops.
5. UI plugins: open each panel once; an error like AddUI unknown parent shows only when it is drawn.
6. Join the server fresh: a new character exercises spawn, starter kit and welcome hooks such as OnPlayerConnected and OnPlayerRespawned.

If you find a broken plugin, unload it with oxide.unload <Name> so it stops spamming the console, then continue. More on tracing problems in debugging Rust plugins.

Wipe day checklist

• Back up plugins, config, data and lang.
• Update Rust, then Oxide or Carbon.
• Check oxide.plugins against the plugin folder.
• Read errors, fix or unload broken plugins.
• Check /updates for hook changes.
• Reset per-map data, keep long-term data.
• Apply per-wipe config changes.
• Test in dependency order with a fresh account.
• Open the server.