Merge pull request #1476 from deadsurgeon42/tristate-player-hooks

Turn the player hooks into a tristate #1470

CHANGELOG.md

@@ -4,6 +4,7 @@ This is the rolling changelog for TShock for Terraria. Use past tense when addin
 
 ## Upcoming Changes
 
+* API: Changed `PlayerHooks` permission hook mechanisms to allow negation from hooks (@deadsurgeon42)
 * Updated OpenTerraria API to 1.3.5.3 (@DeathCradle)
 * Updated Terraria Server API to 1.3.5.3 (@WhiteXZ, @hakusaro)
 * Updated TShock core components to 1.3.5.3 (@hakusaro)

TShockAPI/DB/ItemManager.cs

@@ -201,8 +201,9 @@ namespace TShockAPI.DB
 			if (ply.HasPermission(Permissions.usebanneditem))
 				return true;
 
-			if (PlayerHooks.OnPlayerItembanPermission(ply, this))
-				return true;
+			PermissionHookResult hookResult = PlayerHooks.OnPlayerItembanPermission(ply, this);
+			if (hookResult != PermissionHookResult.Unhandled)
+				return hookResult == PermissionHookResult.Granted;
 
 			var cur = ply.Group;
 			var traversed = new List<Group>();

TShockAPI/DB/ProjectileManager.cs

@@ -206,8 +206,9 @@ namespace TShockAPI.DB
 			if (ply.HasPermission(Permissions.canusebannedprojectiles))
 				return true;
 
-			if (PlayerHooks.OnPlayerProjbanPermission(ply, this))
-				return true;
+			PermissionHookResult hookResult = PlayerHooks.OnPlayerProjbanPermission(ply, this);
+			if (hookResult != PermissionHookResult.Unhandled)
+				return hookResult == PermissionHookResult.Granted;
 
 			var cur = ply.Group;
 			var traversed = new List<Group>();

TShockAPI/DB/TileManager.cs

@@ -206,8 +206,9 @@ namespace TShockAPI.DB
 			if (ply.HasPermission(Permissions.canusebannedtiles))
 				return true;
 
-			if (PlayerHooks.OnPlayerTilebanPermission(ply, this))
-				return true;
+			PermissionHookResult hookResult = PlayerHooks.OnPlayerTilebanPermission(ply, this);
+			if (hookResult != PermissionHookResult.Unhandled)
+				return hookResult == PermissionHookResult.Granted;
 
 			var cur = ply.Group;
 			var traversed = new List<Group>();

TShockAPI/Hooks/PlayerHooks.cs

@@ -143,7 +143,7 @@ namespace TShockAPI.Hooks
 	/// <summary>
 	/// EventArgs used for the <see cref="PlayerHooks.PlayerPermission"/> event.
 	/// </summary>
-	public class PlayerPermissionEventArgs : HandledEventArgs
+	public class PlayerPermissionEventArgs
 	{
 		/// <summary>
 		/// The player who fired the event.
@@ -155,6 +155,11 @@ namespace TShockAPI.Hooks
 		/// </summary>
 		public string Permission { get; set; }
 
+		/// <summary>
+		/// <see cref="PermissionHookResult"/> of the hook.
+		/// </summary>
+		public PermissionHookResult Result { get; set; }
+
 		/// <summary>
 		/// Initializes a new instance of the PlayerPermissionEventArgs class.
 		/// </summary>
@@ -164,13 +169,14 @@ namespace TShockAPI.Hooks
 		{
 			Player = player;
 			Permission = permission;
+			Result = PermissionHookResult.Unhandled;
 		}
 	}
 
 	/// <summary>
 	/// EventArgs used for the <see cref="PlayerHooks.PlayerItembanPermission"/> event.
 	/// </summary>
-	public class PlayerItembanPermissionEventArgs : HandledEventArgs
+	public class PlayerItembanPermissionEventArgs
 	{
 		/// <summary>
 		/// The player who fired the event.
@@ -182,22 +188,28 @@ namespace TShockAPI.Hooks
 		/// </summary>
 		public ItemBan BannedItem { get; set; }
 
+		/// <summary>
+		/// <see cref="PermissionHookResult"/> of the hook.
+		/// </summary>
+		public PermissionHookResult Result { get; set; }
+
 		/// <summary>
 		/// Initializes a new instance of the PlayerItembanPermissionEventArgs class.
 		/// </summary>
 		/// <param name="player">The player who fired the event.</param>
-		/// <param name="permission">The permission being checked.</param>
+		/// <param name="bannedItem">The banned item being checked.</param>
 		public PlayerItembanPermissionEventArgs(TSPlayer player, ItemBan bannedItem)
 		{
 			Player = player;
 			BannedItem = bannedItem;
+			Result = PermissionHookResult.Unhandled;
 		}
 	}
 
 	/// <summary>
 	/// EventArgs used for the <see cref="PlayerHooks.PlayerProjbanPermission"/> event.
 	/// </summary>
-	public class PlayerProjbanPermissionEventArgs : HandledEventArgs
+	public class PlayerProjbanPermissionEventArgs
 	{
 		/// <summary>
 		/// The player who fired the event.
@@ -209,6 +221,11 @@ namespace TShockAPI.Hooks
 		/// </summary>
 		public ProjectileBan BannedProjectile { get; set; }
 
+		/// <summary>
+		/// <see cref="PermissionHookResult"/> of the hook.
+		/// </summary>
+		public PermissionHookResult Result { get; set; }
+
 		/// <summary>
 		/// Initializes a new instance of the PlayerProjbanPermissionEventArgs class.
 		/// </summary>
@@ -218,13 +235,14 @@ namespace TShockAPI.Hooks
 		{
 			Player = player;
 			BannedProjectile = checkedProjectile;
+			Result = PermissionHookResult.Unhandled;
 		}
 	}
 
 	/// <summary>
 	/// EventArgs used for the <see cref="PlayerHooks.PlayerTilebanPermission"/> event.
 	/// </summary>
-	public class PlayerTilebanPermissionEventArgs : HandledEventArgs
+	public class PlayerTilebanPermissionEventArgs
 	{
 		/// <summary>
 		/// The player who fired the event.
@@ -236,6 +254,11 @@ namespace TShockAPI.Hooks
 		/// </summary>
 		public TileBan BannedTile { get; set; }
 
+		/// <summary>
+		/// <see cref="PermissionHookResult"/> of the hook.
+		/// </summary>
+		public PermissionHookResult Result { get; set; }
+
 		/// <summary>
 		/// Initializes a new instance of the PlayerTilebanPermissionEventArgs class.
 		/// </summary>
@@ -245,6 +268,7 @@ namespace TShockAPI.Hooks
 		{
 			Player = player;
 			BannedTile = checkedTile;
+			Result = PermissionHookResult.Unhandled;
 		}
 	}
 
@@ -439,60 +463,79 @@ namespace TShockAPI.Hooks
 		/// Fires the <see cref="PlayerPermission"/> event.
 		/// </summary>
 		/// <param name="player">The player firing the event.</param>
-		/// <returns>True if the event has been handled.</returns>
-		public static bool OnPlayerPermission(TSPlayer player, string permission)
+		/// <returns>Event result if the event has been handled, otherwise <see cref="PermissionHookResult.Unhandled"/>.</returns>
+		public static PermissionHookResult OnPlayerPermission(TSPlayer player, string permission)
 		{
 			if (PlayerPermission == null)
-				return false;
+				return PermissionHookResult.Unhandled;
 
 			var args = new PlayerPermissionEventArgs(player, permission);
 			PlayerPermission(args);
-			return args.Handled;
+
+			return args.Result;
 		}
 
 		/// <summary>
 		/// Fires the <see cref="PlayerItembanPermission"/> event.
 		/// </summary>
 		/// <param name="player">The player firing the event.</param>
-		/// <returns>True if the event has been handled.</returns>
-		public static bool OnPlayerItembanPermission(TSPlayer player, ItemBan bannedItem)
+		/// <returns>Event result if the event has been handled, otherwise <see cref="PermissionHookResult.Unhandled"/>.</returns>
+		public static PermissionHookResult OnPlayerItembanPermission(TSPlayer player, ItemBan bannedItem)
 		{
 			if (PlayerItembanPermission == null)
-				return false;
+				return PermissionHookResult.Unhandled;
 
 			var args = new PlayerItembanPermissionEventArgs(player, bannedItem);
 			PlayerItembanPermission(args);
-			return args.Handled;
+
+			return args.Result;
 		}
 
 		/// <summary>
 		/// Fires the <see cref="PlayerProjbanPermission"/> event.
 		/// </summary>
 		/// <param name="player">The player firing the event.</param>
-		/// <returns>True if the event has been handled.</returns>
-		public static bool OnPlayerProjbanPermission(TSPlayer player, ProjectileBan bannedProj)
+		/// <returns>Event result if the event has been handled, otherwise <see cref="PermissionHookResult.Unhandled"/>.</returns>
+		public static PermissionHookResult OnPlayerProjbanPermission(TSPlayer player, ProjectileBan bannedProj)
 		{
 			if (PlayerProjbanPermission == null)
-				return false;
+				return PermissionHookResult.Unhandled;
 
 			var args = new PlayerProjbanPermissionEventArgs(player, bannedProj);
 			PlayerProjbanPermission(args);
-			return args.Handled;
+
+			return args.Result;
 		}
 
 		/// <summary>
 		/// Fires the <see cref="PlayerTilebanPermission"/> event.
 		/// </summary>
 		/// <param name="player">The player firing the event.</param>
-		/// <returns>True if the event has been handled.</returns>
-		public static bool OnPlayerTilebanPermission(TSPlayer player, TileBan bannedTile)
+		/// <returns>Event result if the event has been handled, otherwise <see cref="PermissionHookResult.Unhandled"/>.</returns>
+		public static PermissionHookResult OnPlayerTilebanPermission(TSPlayer player, TileBan bannedTile)
 		{
 			if (PlayerTilebanPermission == null)
-				return false;
+				return PermissionHookResult.Unhandled;
 
 			var args = new PlayerTilebanPermissionEventArgs(player, bannedTile);
 			PlayerTilebanPermission(args);
-			return args.Handled;
+
+			return args.Result;
 		}
+
 	}
+
+	/// <summary>
+	/// Defines the possible outcomes of <see cref="PlayerHooks.PlayerPermission"/> handlers.
+	/// </summary>
+	public enum PermissionHookResult
+	{
+		/// <summary>Hook doesn't return a result on the permission check.</summary>
+		Unhandled,
+		/// <summary>Permission is explicitly denied by a hook.</summary>
+		Denied,
+		/// <summary>Permission is explicitly granted by a hook.</summary>
+		Granted
+	}
+
 }

TShockAPI/TSPlayer.cs

@@ -1265,8 +1265,10 @@ namespace TShockAPI
 		/// <returns>True if the player has that permission.</returns>
 		public bool HasPermission(string permission)
 		{
-			if (PlayerHooks.OnPlayerPermission(this, permission))
-				return true;
+			PermissionHookResult hookResult = PlayerHooks.OnPlayerPermission(this, permission);
+
+			if (hookResult != PermissionHookResult.Unhandled)
+				return hookResult == PermissionHookResult.Granted;
 
 			if (tempGroup != null)
 				return tempGroup.HasPermission(permission);