Works With
Player DLC API, Better No Escape, Clans, Friends
Building Grades is an all-in-one plugin for upgrading, downgrading, skinning, and wallpapering building blocks. Players can grade single blocks or entire buildings through chat, a hammer HUD, or a settings panel, and pick their preferred building skin per grade tier and wallpaper per surface, applied automatically on every grade change. Compound walls and gates are also supported, swapping between configurable tiers like wood, adobe, stone, and ice. Also includes optional aura mode that grades blocks passively as players walk through their base.
Core Permissions:
Players need permission for each individual grade tier they want to reach. Grant either the specific grade permission or the "all" wildcard.
Section Permissions (VIP Gating):
These permissions are configured under Section Permissions in the config. By default the auto-grade, aura, block filter, skins, and wallpapers sections are open to everyone (blank perm string), but externals is gated behind buildinggrades.vip.externals. Set any section's permission string in the config to lock it behind that permission. See Section Permissions Settings.
Players without a section's required permission see a "Premium feature" overlay on that section in the UI.
Chat commands start with a /, while console commands can be entered directly in the F1 console or server console. Use find <keyword> in console to search for available commands related to the plugin. Parameters in < > are required, while [ ] are optional.
The main chat command defaults to /bg and is configurable (see Chat Command Settings).
These aliases work as standalone chat commands without the /bg prefix. All aliases are configurable.
Code:Copy
bind mouse2 bg.hammerdir<br>bind mouse3 bg.hammermode<br>bind b bg.undo
Settings are stored in the config file found under the config/ directory. You can edit this file manually, then reload the plugin to apply your changes.
JSON:Copy
Skip Grade On Recently-Damaged Blocks -- Refuses to grade blocks that were attacked within the recently-damaged window. Prevents grading during active raids
Enabled -- Master switch. When false, the entire auto-grade section is hidden from the UI and the placement hook is unsubscribed
Blocks Processed Per Frame -- How many blocks the coroutine handles before yielding to the next frame. Lower values keep TPS smooth on large bases at the cost of total completion time
Enabled -- Master switch for the hammer feature
Enabled -- Shows a persistent on-screen button that opens the settings panel
Enabled -- Master switch for the skins section
Enabled -- Master switch for the wallpapers section
Enabled -- Master switch for the externals section
Enabled -- Master switch for the aura section
Main Chat Command -- The root chat command (defaults to bg, so players type /bg)
Refund Resources When Downgrading -- When true, downgrades refund a portion of the original construction cost
Enabled -- When false, no undo records are tracked at all and the undo button is non-functional
Authed Players Can Grade -- Players authed on the dominating tool cupboard can grade. This is the most common access path
JSON:Copy
Only applies when Better No Escape is installed. With the plugin missing, both toggles silently do nothing.
Each section's permission gates access to that section's UI controls and underlying actions. Leave blank to open the section to anyone with buildinggrades.use. Set a non-empty string and the plugin auto-registers the permission and locks the section behind it. Strings without a . are prefixed with buildinggrades. automatically.
JSON:Copy
Block Types -- Dictionary mapping block prefab shortnames to icon sprite paths used in the block filter dropdown. Adding a new entry exposes that block type for filtering; removing one hides it from the UI
Persistent data is saved in the data/ directory. This includes things like saved settings, usage stats, or player progress depending on the plugin. Deleting a data file will reset stored progress or customizations.
JSON:Copy
Each player's settings are saved under their Steam id, covering their grade choices, hammer setup, skin and wallpaper selections, block filter, and external tier targets. Everything is restored automatically when they reconnect.
Language files are located in the lang/ folder. To translate messages, copy the en.json file into your target language folder (e.g. fr, de) and edit the values. Reload the plugin after changes to apply new messages.
JSON:Copy
This section lists public methods exposed by the plugin for use in other plugins. You can call these via the CallHook method. Ensure the plugin is loaded before calling its API to avoid null reference errors.
C#:Copy
Attempts to change a block's grade to targetGrade. Respects all access, cost, and refund logic. Returns true on success.
C#:Copy
Applies a skin to a block, respecting DLC ownership checks and the CanBuildingGradesApplySkin hook. Returns true on success.
C#:Copy
Applies a wallpaper to a block surface. side is 0 (soft) or 1 (hard). Skin id0 or 1 strips existing wallpaper. Returns true on success.
C#:Copy
Grades every block in the building containing anchorBlock toward targetGrade. Returns the number of blocks successfully graded.
C#:Copy
Dictionary<span><</span><span>int</span><span>,</span> <span>int</span><span>></span> <span>API_GetGradeUpgradeCost</span><span>(</span><span>BuildingBlock</span> block<span>,</span> <span>int</span> targetGrade<span>)</span>
Returns the resource cost to upgrade a block to targetGrade, keyed by item ID. Returns an empty dictionary on invalid input.
These are custom hooks that other plugins can listen for. Simply define a method with the same name and expected parameters in your plugin to handle the event. Hooks are triggered at key moments and are useful for extending or reacting to plugin behavior.
C#:Copy
Called when a grade change is about to happen, after access and resource checks but before the block is modified. Return any non-null value to block the grade change, or null to allow it.
C#:Copy
Called when a skin is about to be applied to a block. Return any non-null value to block the skin application, or null to allow it.
C#:Copy
Called when a wallpaper is about to be applied to a block surface (side is 0 for soft side, 1 for hard side). Return any non-null value to block the wallpaper application, or null to allow it.
C#:Copy
Called after a block's grade has been changed by the plugin. Notification-only; no return value is used.
C#:Copy
Called when a bulk grade operation finishes. Notification-only; no return value is used.
Player DLC API, Better No Escape, Clans, Friends
Building Grades is an all-in-one plugin for upgrading, downgrading, skinning, and wallpapering building blocks. Players can grade single blocks or entire buildings through chat, a hammer HUD, or a settings panel, and pick their preferred building skin per grade tier and wallpaper per surface, applied automatically on every grade change. Compound walls and gates are also supported, swapping between configurable tiers like wood, adobe, stone, and ice. Also includes optional aura mode that grades blocks passively as players walk through their base.
- Chat grading - Upgrade/downgrade single blocks or whole buildings via /up, /down, /upall, /downall
- Hammer HUD - Equip a hammer to get an on-screen grade picker with direction, scope, target grade, and undo buttons
- Auto-grade on placement - Newly placed blocks upgrade to the chosen tier automatically with an inactivity timer
- Aura mode - Walk through the base with a hammer and blocks within the radius grade themselves as you pass
- Resource cost preview - See exactly which resources are needed before confirming a whole-building upgrade
- Building skins - Set your favorite skin for each grade tier and have it applied automatically to every block you upgrade, downgrade, or auto-grade
- Container metal coloring - Color palette and randomize option for the Container metal skin
- Wallpapers - Pick a wallpaper for each surface type (walls, floors, ceilings) and have it applied automatically on every grade change
- Compound walls and gates - Swap high external walls and gates between configurable tiers like wood, adobe, stone, and ice with a hammer hit
- Block type filter - Choose which block types are included in bulk operations, like foundations, walls, stairs, or roofs
- Undo system - Reverse the last grade operation within a configurable time window
- Cost refunds on downgrade - Get a configurable percentage of resources back whenever you downgrade a block
- Raid/combat block integration - Optional integration with Better No Escape to block grading during raid or combat
- Access control - Decide who can grade whose base through TC auth, building ownership, teams, Friends, and Clans
- DLC ownership checks - Optional Player DLC API integration to gate skins and wallpapers behind DLC ownership
- Floating settings button - Always-visible on-screen button to open the settings panel without typing
- Per-player preferences - Skins, wallpapers, hammer direction/scope, block filter, and aura radius persist across sessions
Core Permissions:
- buildinggrades.use -- Required for any plugin usage (chat commands, hammer, settings panel)
- buildinggrades.bulk -- Required for /upall, /downall, and Hammer Building scope mode
- buildinggrades.preview -- Required to use the cost preview button in the hammer HUD
- buildinggrades.undo -- Required for the /undo command and the HUD undo button
- buildinggrades.nocost -- Skips resource costs on upgrades and skips refund payouts on downgrades
- buildinggrades.skinbypass -- Bypasses DLC ownership checks for skins and wallpapers
- buildinggrades.admin -- Full access to all features, bypasses TC auth, cooldowns, attack window, and all gate checks
Players need permission for each individual grade tier they want to reach. Grant either the specific grade permission or the "all" wildcard.
- buildinggrades.up.<grade> -- Allows upgrading to a specific grade (e.g., buildinggrades.up.2 for Stone)
- buildinggrades.down.<grade> -- Allows downgrading to a specific grade (e.g., buildinggrades.down.1 for Wood)
- buildinggrades.up.all -- Allows upgrading to any grade
- buildinggrades.down.all -- Allows downgrading to any grade
Section Permissions (VIP Gating):
These permissions are configured under Section Permissions in the config. By default the auto-grade, aura, block filter, skins, and wallpapers sections are open to everyone (blank perm string), but externals is gated behind buildinggrades.vip.externals. Set any section's permission string in the config to lock it behind that permission. See Section Permissions Settings.
Players without a section's required permission see a "Premium feature" overlay on that section in the UI.
Chat commands start with a /, while console commands can be entered directly in the F1 console or server console. Use find <keyword> in console to search for available commands related to the plugin. Parameters in < > are required, while [ ] are optional.
The main chat command defaults to /bg and is configurable (see Chat Command Settings).
- /bg -- Shows the help screen
- /bg help -- Shows the help screen
- /bg up [grade] -- Upgrades the block you're looking at. Omit [grade] to step up one tier
- /bg down [grade] -- Downgrades the block you're looking at. Omit [grade] to step down one tier
- /bg upall [grade] -- Upgrades every block in the building you're looking at
- /bg downall [grade] -- Downgrades every block in the building you're looking at
- /bg undo -- Reverses the last grade operation within the undo time window
- /bg hammer [up/down] -- Toggles the hammer tool. Optional argument sets direction
- /bg settings -- Opens the settings panel
These aliases work as standalone chat commands without the /bg prefix. All aliases are configurable.
- /up, /upgrade -- Same as /bg up
- /down, /downgrade -- Same as /bg down
- /upall, /upgradeall -- Same as /bg upall
- /downall, /downgradeall -- Same as /bg downall
- /undo -- Same as /bg undo
- /hammer -- Same as /bg hammer
- bg.hammer -- Toggles hammer mode
- bg.hammerdir -- Toggles hammer direction between Upgrade and Downgrade. Also clears the target grade if one is locked
- bg.hammermode -- Cycles hammer scope between Single block and whole Building
- bg.undo -- Triggers the undo
- bg.off -- Disables auto-grade
- bg.settings -- Opens/closes the settings panel
- bg.aura <off/wood/stone/metal/hqm> -- Toggles aura mode at the specified grade
- bg.aura radius <int> -- Sets the aura radius in meters
Code:Copy
bind mouse2 bg.hammerdir<br>bind mouse3 bg.hammermode<br>bind b bg.undo
Settings are stored in the config file found under the config/ directory. You can edit this file manually, then reload the plugin to apply your changes.
JSON:Copy
Skip Grade On Recently-Damaged Blocks -- Refuses to grade blocks that were attacked within the recently-damaged window. Prevents grading during active raids
- Recently-Damaged Window Seconds -- How long after an attack a block stays "recently damaged"
- Play Upgrade/Downgrade Effects On Grade Change -- Plays the standard upgrade particle effect on each grade change
- Remember Player Preferences -- Persists per-player settings to disk so they survive disconnects and server restarts
- Chat Command Cooldown Seconds -- Global cooldown applied to single-block and bulk chat commands. Admins bypass
Enabled -- Master switch. When false, the entire auto-grade section is hidden from the UI and the placement hook is unsubscribed
- Auto-Disable Timer Enabled -- When false, auto-grade stays on indefinitely. When true, it shuts off after the timer expires to stop accidental resource drain
- Default Auto-Disable Duration Seconds -- Timer used when a player hasn't set their own duration
- Maximum Allowed Timer Duration Seconds -- Hard cap on the timer duration players can set in the UI
- Allow Players To Edit Timer In Settings UI -- When false, players see the timer value but can't type a new one
Blocks Processed Per Frame -- How many blocks the coroutine handles before yielding to the next frame. Lower values keep TPS smooth on large bases at the cost of total completion time
- Show Progress Messages During Long Operations -- Sends "Processing X/Y blocks" chat messages while a bulk job runs
- Progress Message Interval -- How often progress messages are sent
Enabled -- Master switch for the hammer feature
- Auto-Activate When Hammer Equipped -- Automatically turns on hammer mode when a player equips a hammer
- Custom Hammer Skin Id -- Restricts plugin behavior to hammers with this specific skin ID. Set to 0 to accept any hammer
- Custom Hammer Display Name -- Restricts plugin behavior to hammers with this exact custom name
- Hold Button To Grade -- When set, hits only grade while this button is held. Other hits pass through to vanilla repair. Accepts standard Rust button names like SPRINT, DUCK, RELOAD, USE. Set to blank to always grade on every hit
Enabled -- Shows a persistent on-screen button that opens the settings panel
- Hide While Hammer HUD Is Visible -- Hides the floating button when the hammer HUD is showing to avoid clutter
- Anchor Minimum / Anchor Maximum -- Standard Rust CUI anchor coordinates. 0 0 = bottom-left of screen, 1 1 = top-right
- Offset Minimum Pixels / Offset Maximum Pixels -- Pixel offset from the anchor point. The defaults place a 50x50px button near the bottom-left
- Icon Sprite Path -- Any in-game sprite path.
- Background Color -- Hex color with optional alpha channel.
Enabled -- Master switch for the skins section
- Available Skins-- Dictionary keyed by grade integer (1-4). Each entry is a list of skins available for that grade
- Display Name -- Label shown in the skin dropdown
- Skin Id -- Steam Workshop skin ID. 0 means vanilla/default
- Icon URL -- HTTP(S) URL to a PNG that becomes the dropdown thumbnail. The plugin downloads, center-crops, and caches the image on server start. Leave blank to fall back to a text label
- Apply Player's Skin On Vanilla Upgrade -- When true, the player's preferred skin is also applied when they upgrade through the vanilla hammer UI (not just plugin commands)
- Require Skin Ownership -- When true and PlayerDLCAPI is loaded, only skins the player actually owns are selectable. Locked skins display a lock icon
- Container Skin Color Palette -- Maps display names to Rust's internal color ids (0-16). Only used when the player picks the Container skin (ID 10221) for the Metal grade
Enabled -- Master switch for the wallpapers section
- Re-Apply Wallpaper When Grading A Block -- When a block is graded, the plugin re-runs the wallpaper logic so the player's wallpaper sticks
- Show Ceiling Wallpaper On Underside Of Floors -- When enabled, floors get both a floor wallpaper (top) and a ceiling wallpaper (underside)
- Wallpapers Damageable -- When false, applied wallpapers become invulnerable (can't be shot off). When true, vanilla damage behavior applies
- Play Wallpaper Placement Sound/Effect -- Plays the standard wallpaper placement effect on each application
- Require Wallpaper Ownership -- When true, players need to own the wallpaper skin (checked via PlayerDLCAPI or their Steam inventory) to use it
- Auto-Populate Wallpaper List From Game Items On Load -- On plugin load, scans Rust's wallpaper item definitions and adds any missing skins to the dropdown lists. Useful so new wallpapers from updates appear automatically
- Available Wallpapers -- Dictionary keyed by category (1=Wall, 2=Floor, 3=Ceiling). Skin id 0 is the "None" sentinel (no change), skin id 1 is the "Remove" sentinel (strip existing wallpaper)
Enabled -- Master switch for the externals section
- Allow Hammer Hits To Step Tiers -- When true, hitting an external wall or gate with the plugin's hammer mode swaps it for the next/previous tier in the ladder (direction follows the hammer's Upgrade/Downgrade setting)
- Allow Auto-Upgrade On Placement -- When true, newly placed externals are tier-stepped toward the player's target tier on placement. When false, the per-player toggle is greyed out in the UI
- Wall Tiers/ Gate Tiers-- Ordered list of tiers. Index `0`is the base tier that gets placed by default
- Display Name -- Label shown in the UI dropdown
- Prefab Path -- Full prefab asset path that gets spawned when stepping to this tier
- Item Shortname -- Optional override for which item's blueprint cost is charged when stepping to this tier. If omitted, the cost is derived from the prefab's shortname
Enabled -- Master switch for the aura section
- Default Aura Radius -- Radius used when a player first turns on aura mode
- Maximum Allowed Aura Radius -- Hard cap on the radius players can set in the UI slider
- Scan Interval Seconds -- How often the aura tick fires. Lower values feel more responsive but cost more performance
- Blocks Processed Per Scan -- Caps how many blocks can be processed in a single tick to prevent stalls
- Aura Requires Player Resources -- When false, aura upgrades are free regardless of buildinggrades.nocost permission
- Sphere Opacity -- How many overlapping visual spheres are stacked to represent the aura range. More spheres = more opaque
Main Chat Command -- The root chat command (defaults to bg, so players type /bg)
- Aliases For "/up" Shortcut -- Standalone shortcut commands that act like /bg up. Add or remove to taste
- Aliases For "/down" Shortcut -- Standalone aliases for /bg down
- Aliases For "/upall" Shortcut -- Standalone aliases for /bg upall
- Aliases For "/downall" Shortcut -- Standalone aliases for /bg downall
- Aliases For "/undo" Shortcut -- Standalone aliases for /bg undo
- Aliases For "/hammer" Shortcut -- Standalone aliases for /bg hammer
- Chat Message Prefix -- Prepended to the help screen output
Refund Resources When Downgrading -- When true, downgrades refund a portion of the original construction cost
- Downgrade Refund Percentage -- Percentage of the original cost that gets refunded. 50 refunds half, 100 refunds full cost, 0 disables refunds without touching the toggle above
Enabled -- When false, no undo records are tracked at all and the undo button is non-functional
- Undo Time Window Seconds -- After this many seconds from the last operation, undo data expires and can't be applied
- Maximum Blocks Tracked Per Undo Batch -- Caps memory usage on very large bulk operations. Blocks past the cap can't be undone
Authed Players Can Grade -- Players authed on the dominating tool cupboard can grade. This is the most common access path
- `Building Owner And Allies Can Grade -- The original block owner and their allies (per the toggles below) can grade even without TC auth
- Allow Owner's Friends -- Allies includes Friends-linked friends of the owner
- Allow Owner's Teammates -- Allies includes Rust team members of the owner
- Allow Owner's Clanmates -- Allies includes Clans clanmates of the owner
JSON:Copy
Only applies when Better No Escape is installed. With the plugin missing, both toggles silently do nothing.
- Deny Grade/Skin/Wallpaper Actions While Raid-Blocked -- Refuses all grade, skin, and wallpaper actions when the player is raid-blocked. The HUD shows a countdown
- Deny Grade/Skin/Wallpaper Actions While Combat-Blocked -- Same but for combat block
Each section's permission gates access to that section's UI controls and underlying actions. Leave blank to open the section to anyone with buildinggrades.use. Set a non-empty string and the plugin auto-registers the permission and locks the section behind it. Strings without a . are prefixed with buildinggrades. automatically.
- Auto-Grade Permission -- Locks the auto-grade UI section
- Aura Permission -- Locks aura mode
- Block Filter Permission -- Locks the block type filter
- Building Skins Permission -- Locks all skin selection and the per-grade skin dropdowns
- Wallpapers Permission -- Locks all wallpaper selection
- External Walls Permission -- Locks tier stepping on high external walls and gates. Defaults to buildinggrades.vip.externals
JSON:Copy
Block Types -- Dictionary mapping block prefab shortnames to icon sprite paths used in the block filter dropdown. Adding a new entry exposes that block type for filtering; removing one hides it from the UI
Persistent data is saved in the data/ directory. This includes things like saved settings, usage stats, or player progress depending on the plugin. Deleting a data file will reset stored progress or customizations.
JSON:Copy
Each player's settings are saved under their Steam id, covering their grade choices, hammer setup, skin and wallpaper selections, block filter, and external tier targets. Everything is restored automatically when they reconnect.
Language files are located in the lang/ folder. To translate messages, copy the en.json file into your target language folder (e.g. fr, de) and edit the values. Reload the plugin after changes to apply new messages.
JSON:Copy
This section lists public methods exposed by the plugin for use in other plugins. You can call these via the CallHook method. Ensure the plugin is loaded before calling its API to avoid null reference errors.
C#:Copy
Attempts to change a block's grade to targetGrade. Respects all access, cost, and refund logic. Returns true on success.
C#:Copy
Applies a skin to a block, respecting DLC ownership checks and the CanBuildingGradesApplySkin hook. Returns true on success.
C#:Copy
Applies a wallpaper to a block surface. side is 0 (soft) or 1 (hard). Skin id0 or 1 strips existing wallpaper. Returns true on success.
C#:Copy
Grades every block in the building containing anchorBlock toward targetGrade. Returns the number of blocks successfully graded.
C#:Copy
Dictionary<span><</span><span>int</span><span>,</span> <span>int</span><span>></span> <span>API_GetGradeUpgradeCost</span><span>(</span><span>BuildingBlock</span> block<span>,</span> <span>int</span> targetGrade<span>)</span>
Returns the resource cost to upgrade a block to targetGrade, keyed by item ID. Returns an empty dictionary on invalid input.
These are custom hooks that other plugins can listen for. Simply define a method with the same name and expected parameters in your plugin to handle the event. Hooks are triggered at key moments and are useful for extending or reacting to plugin behavior.
C#:Copy
Called when a grade change is about to happen, after access and resource checks but before the block is modified. Return any non-null value to block the grade change, or null to allow it.
C#:Copy
Called when a skin is about to be applied to a block. Return any non-null value to block the skin application, or null to allow it.
C#:Copy
Called when a wallpaper is about to be applied to a block surface (side is 0 for soft side, 1 for hard side). Return any non-null value to block the wallpaper application, or null to allow it.
C#:Copy
Called after a block's grade has been changed by the plugin. Notification-only; no return value is used.
C#:Copy
Called when a bulk grade operation finishes. Notification-only; no return value is used.
