About SimplePVESphere
SimplePVESphere is a Rust plugin for Oxide modding that allows developers to easily create and manage temporary, spherical PVE (Player Versus Environment) zones for their custom events. It provides a visual sphere, a trigger collider for player access control, and an API to integrate with other plugins.
The core idea is to define an area where PVE rules apply, typically controlled by an event owner. Unauthorized players are ejected, and ownership can be dynamically assigned, for example, when a player kills an NPC within the zone.
Core Features
1. Dynamic Sphere Creation:
* Create spheres programmatically with a specific position, radius, and visual opacity.
* The visual sphere is rendered at twice the functional trigger radius to give players a clear visual warning before they enter the active PVE zone.
2. Trigger-Based PVE Zone:
* A `SphereCollider` acts as the functional boundary of the PVE zone.
* Manages player entry and automatically ejects unauthorized players. Ejection logic is designed to safely move players (and their vehicles, if mounted) to a ground position just outside the sphere.
3. Ownership and Access Control:
* Owner-Based Access**: If a sphere has an owner (a `BasePlayer`), only the owner and their Rust teammates are allowed inside.
* No Owner: If a sphere has no owner, all players can enter by default.
* Ejection: Unauthorized players attempting to enter or found within the sphere are automatically ejected.
4. Automatic Ownership via NPC Kill:
* A key feature is the ability for a sphere to automatically assign ownership.
* If a player kills a `HumanNPC` or `ScientistNPC` (that is not also a real player with a SteamID) inside a sphere *that currently has no owner*, that player will automatically become the owner of that specific sphere.
* When this happens, `SimplePVESphere` calls a global hook: `OnSimplePveOwnerAssigned(string eventName, BasePlayer ownerPlayer)`.
5. Admin Handling:
* **Global Setting**: A global configuration `IgnoreAdmins` (in `oxide/config/SimplePVESphere.json`, default: `false`) can allow admins to bypass PVE rules.
* Per-Sphere Override: When creating a sphere, an `eventDebugMode` flag (boolean, defaults to `false`) can be passed.
* If `eventDebugMode` is `true` for a sphere, the global `IgnoreAdmins` setting is ignored for *that specific sphere*, and admins will be treated like regular players (subject to PVE rules).
* If `eventDebugMode` is `false`, the global `IgnoreAdmins` setting applies as usual.
6. Performance:
* The plugin dynamically subscribes to the server-wide `OnEntityDeath` hook only when at least one PVE sphere is active. It unsubscribes when the last sphere is removed, minimizing performance impact when the plugin is not actively managing any zones.
Configuration
The plugin has one main configuration option, found in `oxide/config/SimplePVESphere.json`:
{ "IgnoreAdmins": false }
* `IgnoreAdmins` (boolean):
* If `true`, players with admin flags will generally ignore the PVE restrictions (unless overridden by `eventDebugMode` on sphere creation).
* If `false` (default), admins are subject to the PVE rules like other players (unless `eventDebugMode` is true for that sphere).
API Usage
To use `SimplePVESphere` in your plugin, you first need a reference to it.
[PluginReference] private Plugin SimplePVESphere;
Then, you can call its API methods:
1. `CreateSphere`
Creates a new PVE sphere.
void CreateSphere(string eventName, Vector3 position, float radius, int opacity, BasePlayer owner = null, bool eventDebugMode = false)
* Parameters:
* `eventName` (string): A unique name for this sphere. This is used to identify the sphere for removal or owner updates (e.g., your event's name or a unique ID).
* `position` (Vector3): The world coordinates for the center of the sphere.
* `radius` (float): The functional radius of the PVE trigger zone. The visual sphere will appear at `radius * 2`.
* `opacity` (int): Determines the number of visual sphere layers. More layers can make the sphere more opaque.
* `owner` (BasePlayer, optional): The initial owner of the sphere. Defaults to `null` (no owner).
* `eventDebugMode` (bool, optional): If `true`, the global `IgnoreAdmins` config is bypassed for this sphere, and admins are treated as normal players. Defaults to `false`.
* Example:
if (SimplePVESphere != null) { Vector3 eventCenter = new Vector3(0, 100, 0); float eventRadius = 50f; int sphereOpacity = 3; string myEventName = "MyAwesomeEvent_1"; bool treatAdminsAsPlayersForThisEvent = true; SimplePVESphere.Call("CreateSphere", myEventName, eventCenter, eventRadius, sphereOpacity, null, treatAdminsAsPlayersForThisEvent); Puts($"SimplePVE sphere for {myEventName} created."); } else { PrintError("SimplePVESphere plugin not loaded!"); }
2. `RemoveSphere`
Removes an existing PVE sphere. This should always be called when your event ends or the PVE zone is no longer needed to clean up resources.
void RemoveSphere(string eventName)
* Parameters:
* `eventName` (string): The unique name of the sphere to remove (must match the name used in `CreateSphere`).
* Example:
if (SimplePVESphere != null) { string myEventName = "MyAwesomeEvent_1"; SimplePVESphere.Call("RemoveSphere", myEventName); Puts($"SimplePVE sphere for {myEventName} removed."); }
3. `SetSphereOwner`
Updates or sets the owner of an existing PVE sphere.
void SetSphereOwner(string eventName, BasePlayer newOwner)
* Parameters:
* `eventName` (string): The unique name of the sphere to update.
* `newOwner` (BasePlayer): The player to set as the new owner. Can be `null` to remove ownership.
* Example:
BasePlayer somePlayer = GetPlayerById("somePlayerSteamId"); // Your method to get a player if (SimplePVESphere != null && somePlayer != null) { string myEventName = "MyAwesomeEvent_1"; SimplePVESphere.Call("SetSphereOwner", myEventName, somePlayer); Puts($"Ownership of {myEventName} sphere transferred to {somePlayer.displayName}."); }
Listening for Hooks
`SimplePVESphere` calls a hook when a player automatically becomes an owner by killing an NPC inside an unowned sphere. Your plugin can listen for this hook to react to ownership changes.
OnSimplePveOwnerAssigned
Called by `SimplePVESphere` *after* a player has been automatically assigned as the owner of a sphere due to an NPC kill.
void OnSimplePveOwnerAssigned(string eventName, BasePlayer ownerPlayer)
* Parameters:
* `eventName` (string): The name of the sphere for which the owner was assigned.
* `ownerPlayer` (BasePlayer): The player who was assigned as the owner.
* Example (in your event plugin):
// In your plugin (e.g., MyEventPlugin.cs) private void OnSimplePveOwnerAssigned(string eventNameOfSphere, BasePlayer newOwner) { // Check if it's an event this plugin cares about if (eventNameOfSphere == "MyAwesomeEvent_1") { Puts($"Player {newOwner.displayName} has become the owner of the '{eventNameOfSphere}' PVE zone via NPC kill!"); // Add your custom logic here, e.g., announce to the player, update UI, etc. SendPlayerMessage(newOwner, "You have conquered the PVE zone!"); } }
Typical Integration Scenario
1. Event Start:
* Your event plugin starts.
* It determines the event location and desired PVE radius.
* It calls `SimplePVESphere.Call("CreateSphere", "MyEventName", center, radius, opacity, null, false);`
* Typically, the initial owner is `null` if you want NPC kills to determine the first owner.
* Set `eventDebugMode` based on whether admins should be subject to PVE rules for this specific event.
2. During Event:
* `SimplePVESphere` handles player ejections based on ownership.
* If a player kills an NPC inside the sphere (and it's unowned), `SimplePVESphere` assigns them as owner.
* `SimplePVESphere` then calls `OnSimplePveOwnerAssigned("MyEventName", newPlayerOwner)`.
* Your plugin, listening to this hook, can then:
* Update its internal state for the event.
* Notify the new owner.
* Potentially change event objectives or UI.
3. Event End:
* Your event plugin concludes.
* It **must** call `SimplePVESphere.Call("RemoveSphere", "MyEventName");` to clean up the PVE sphere and its associated GameObjects.
This provides a robust and straightforward way to add PVE zone management to your events without needing to implement the complex sphere and trigger logic yourself.
