STU Ward

Simple Tidy and Unique Ward to protect your base efficiently on your server

It adds a clone of vanilla ward but with more server-side features such as diverse protections, permission control, guild integration, ward count limits, and compatibility handling for common utility mods.

Registration is same with vanilla ward.
There is blacklist config to block certain items inside ward area.

Ward Settings UI

Ward area cannot be overlapped unless there is guild or one player built all the wards.

Good old auto closing door inside ward area

What It Blocks

Inside a foreign enabled Ward, unauthorized players are blocked from:

• Interacting with containers, doors, carts, ships, signs, item stands, beehives, crafting stations, fermenters, sap collectors, traps, portals, and tamed creatures
• Building, repairing, and removing pieces
• Modifying terrain
• Damaging or destroying protected structures and objects
• Picking up items, including auto-pickup
• Using or equipping blocked item prefabs configured by the server
• Using creature-catching items on tamed animals inside the ward
• Using TargetPortal map teleport and portal toggle mode on protected portals
• Pulling crafting materials from protected containers through supported crafting mods
• Damaging protected trees (TreeBase)
• No push players feature

Optional Compatibility

If installed, STUWard adds extra integration or blocking for:

• Guilds (guild-based trust and overlap behavior)

Following mod's feature would be blocked on other's wards

• TargetPortal
• AzuCraftyBoxes
• kg_TameableCollector
• PortablePals

How To Use

1. Select Ward with the hammer and place it.
2. A newly placed ward starts with an actual radius of 8m.
3. Look at your ward and use the default shortcut Alt+E to open Ward Settings.
4. Adjust radius, range display settings, and door auto-close delay.
5. Player registration works like vanilla wards:
   • turn the ward off
   • the player to be registered interacts with it using E

While placing a ward, the placement preview shows the current maximum configurable radius.

Permission Model

A player is treated as trusted inside a ward if they are:

• The ward owner
• In the same guild as the ward owner (The mod Guild is required)
• Listed under Registered players

Notes:

• Guild trust and registered-player access are similar for most interactions, but they are not fully identical
• Ward overlap trust behaves more like a guild/shared-group rule than a simple registered-player rule
• Being in the same guild usually grants the same practical interaction access as being registered, but guild membership is treated more like a shared trust group for ward-to-ward behavior
• A registered player can use a ward they are allowed in, but registration alone does not make separate wards behave like shared guild wards

Misc

• By default, each Steam/platform account can place up to 3 wards. (Set to -1 for unlimited)
• Specific accounts can override ward limit withBepInEx/config/STUWard.WardNumberOverride.yml
• If an account is listed in this file, that value overrides Max Wards Per Steam ID.
• command stuw_wardreport generates BepInEx/config/STUWard.WardCountReport.yml
• Admin in debugmode have acess to any ward

Localization

• There should be STUWard.English.yml in BepInEx/plugins/STUWard.
  
• Translate it to your language and name the file STUWard.YourLanguageName.yml and put it in plugins folder.

Config

• Check also STUWard.WardNumberOverride.yml and STUWard.ItemPrefabs.yml in the config folder

[1 - General]

## If on, the configuration is locked and can be changed by server admins only. Synced with server.
# Setting type: Toggle
# Default value: On
# Acceptable values: Off, On
Lock Configuration = On

## Maximum number of managed Wards allowed per Steam/platform account. Set to -1 for unlimited. Synced with server.
# Setting type: Int32
# Default value: 3
Max Wards Per Steam ID = 3

## Maximum configurable Ward radius. Valid range: 8 to 64. Synced with server.
# Setting type: Single
# Default value: 32
Max Ward Radius = 32

## Pickup rule inside a foreign enabled ward. BlockAllExceptWhitelist blocks every item pickup except pickup_whitelist. AllowAllExceptBlacklist allows item pickup except pickup_blacklist. Synced with server.
# Setting type: PickupBlockRule
# Default value: BlockAllExceptWhitelist
# Acceptable values: BlockAllExceptWhitelist, AllowAllExceptBlacklist
Pickup Block Mode = AllowAllExceptBlacklist

## If on, building pieces inside an enabled ward ignore damage from MonsterAI-controlled attackers while no trusted player is nearby. Synced with server.
# Setting type: Toggle
# Default value: On
# Acceptable values: Off, On
Protect Unattended Ward Structures From Hostile Creatures = On

## Additional distance beyond the ward radius used when checking for nearby trusted players before hostile-creature structure protection turns off. Synced with server.
# Setting type: Single
# Default value: 16
Unattended Ward Trusted Player Range Buffer = 16

## How long a ward keeps counting as attended after the last nearby trusted player leaves. Synced with server.
# Setting type: Single
# Default value: 10
Unattended Ward Trusted Presence Grace Seconds = 10

## How often nearby trusted-player attendance is recalculated for unattended hostile-creature structure protection. Synced with server.
# Setting type: Single
# Default value: 0.5
Unattended Ward Presence Refresh Interval = 0.5

## If on, the vanilla guard_stone build recipe is removed from the Hammer piece table while STUWard remains available. Synced with server.
# Setting type: Toggle
# Default value: On
# Acceptable values: Off, On
Disable Vanilla Guard Stone Recipe = On

## STUWard recipe override. Format: ItemPrefab:Amount[:Recover], ... Synced with server.
# Setting type: String
# Default value: GreydwarfEye:1,BoneFragments:3,Flint:5,Wood:7
STUWard Recipe = GreydwarfEye:1,BoneFragments:3,Flint:5,Wood:7

[2 - Client]

## Shortcut used to open the ward settings UI while looking at your ward. Example values: LeftAlt + E, F7 Not synced with server.
# Setting type: KeyboardShortcut
# Default value: E + LeftAlt
Ward Settings Shortcut = E + LeftAlt

[3 - Debug]

## Local-only diagnostic logging for ward ownership/toggle flows. Use Failures for rejection paths only, or Verbose for request and state tracing. Enable separately on each client/server instance you want logs from. Not synced with server.
# Setting type: DiagnosticLogMode
# Default value: Off
# Acceptable values: Off, Failures, Verbose
Ward Diagnostic Logging = Off

Role Definitions

Legend

Unified Permission Matrix

Notes For △ And *

Self-registration by interaction

Add or remove self from permitted list by interacting with the ward is △ because:

• the ward must be disabled
• if the player has control rights, interaction goes through the enabled-toggle path instead

This means:

• Registered: can remove self while the ward is disabled
• Guild Member: can use the same self-toggle path while the ward is disabled
• Outsider: can self-register while the ward is disabled

Item pickup

Manual and auto pickup are △ for Outsider because pickup is also gated by:

• Pickup Block Mode
• pickup whitelist
• pickup blacklist

So outsider pickup is not simply always blocked or always allowed.

Adjacent placement

Place a managed ward adjacent to another ward in the same trusted group is △ for Registered and Guild Member because the overlap exemption depends on trusted-group logic, not just basic access.

In practice, the exemption is based on:

• shared owner identity, or
• shared guild identity

The permitted list by itself is not the same as trusted-group overlap exemption.

Protected structure damage

Damage ordinary protected structures inside an enabled ward is * because this path is not governed only by the simple access matrix.

There is an additional building-damage protection path for:

• friendly ward protection
• unattended monster AI building damage
• source-specific validation

Treat this as a separate damage system, not as a direct mirror of ordinary access/build permissions.

Important Clarifications

Owner identity

• Ownership is based on the ward creator player id.
• Account id is used for count, grouping, reporting, and metadata, but not as the direct owner-control test.

Registered vs Guild Member

• Both pass normal ward access checks.
• Neither can control the ward itself.
• Both may use the self-permitted add/remove path while the ward is disabled.

Admin+Debug

• Admin+Debug is the effective global override role for managed wards.
• It can control foreign managed wards, toggle them, change settings, remove the ward itself, and view all ward pins.

Behavior Sequences

1. Owner opens settings UI and changes radius

1. The player hovers the ward and presses the ward settings shortcut.
2. WardGuiController.TryOpenHoveredWardUi() checks WardAccess.CanConfigureWard(...).
3. Owner passes because direct owner control is allowed.
4. The UI opens and edits are sent through the ward settings RPC.
5. The server resolves the requester id and checks CanControlWard(...).
6. The radius change is applied, clamped, stored in ZDO, and replicated back.

Result:

• Owner: succeeds
• Admin+Debug: also succeeds
• everyone else: denied on the server

2. Outsider presses E on an enabled foreign ward

1. The player interacts with the ward.
2. Interaction logic determines that the player does not have control rights.
3. Because the ward is enabled, the self-permitted toggle path is not available.
4. No enabled toggle is granted.

Result:

• Outsider: blocked
• Registered and Guild Member: still have access, but not control

3. Outsider presses E on a disabled foreign ward

1. The player interacts with the ward.
2. The player does not have control rights.
3. Because the ward is disabled, the self-permitted path is used.
4. The ward adds or removes that player from the permitted list.

Result:

• Outsider: can self-register or self-unregister
• Registered: can remove self
• Guild Member: can also use the same self-toggle path

4. Guild member tries to build inside the ward area

1. The player enters the build placement flow.
2. STUWard access checks run against the placement point.
3. Access evaluation sees matching guild id.
4. Placement is allowed if no other placement-specific rule blocks it.

Result:

• Guild Member: allowed
• this does not grant control over the ward itself

5. Admin+Debug toggles a foreign ward

1. The player has effective admin-debug control.
2. Interaction enters the control path.
3. The vanilla toggle RPC is sent.
4. The server resolves the authoritative requester id.
5. CanControlManagedWard(...) passes because Admin+Debug is treated as a controller.
6. The ward enabled state is toggled.

Result:

• Admin+Debug: succeeds on any managed ward

6. Owner or same-guild player places a ward next to another trusted ward

1. The player starts managed ward placement.
2. STUWard checks ward-limit and access rules for the placement point.
3. Overlap logic evaluates nearby managed wards.
4. If the nearby ward is treated as part of the same trusted group, it is not treated as a foreign-overlap blocker.
5. Placement continues if no foreign ward blocks the radius.

Result:

• Owner: can place adjacent to trusted wards
• Guild Member: may place adjacent when the trusted-group exemption applies
• Outsider: cannot use this exemption against foreign wards

7. Outsider tries to auto-pick up an item inside a foreign enabled ward

1. Auto-pickup gathers candidate wards near the player.
2. STUWard computes denied managed ward candidates once for that tick.
3. For each item, pickup policy is checked.
4. If the item is policy-blocked and is inside a denied ward, auto-pickup is skipped.

Result:

• Outsider: blocked only for policy-blocked items
• Registered, Guild Member, Owner, and Admin+Debug: not blocked by the ward access layer

8. Registered player tries to remove the managed ward itself

1. The player targets the ward piece for removal.
2. The removal path detects that the target is the managed ward itself.
3. Removal requires ward control, not just ordinary access.
4. Registered status is not enough.

Result:

• Registered: denied
• Guild Member: denied
• Owner: allowed
• Admin+Debug: allowed