Clarify by renaming Priority to CancelPriority

Hemlock/StatusInstance.cs

@@ -30,10 +30,10 @@ public int Value {
 			}
 		}
 		/// <summary>
-		/// Priority is important only during cancellation.  When a status is cancelled, its StatusInstances are removed
-		/// one at a time, in order of priority - lowest first.
+		/// When a status is cancelled, its StatusInstances are removed one at a time, in order of priority - lowest first.
+		/// This can be useful to ensure a specific ordering for value changes during cancellation.
 		/// </summary>
-		public int Priority { get; set; }
+		public int CancelPriority { get; set; }
 		/// <summary>
 		/// Test whether this StatusInstance's status is a valid value for the type of the "status" argument.
 		/// If so, load its value into "status" and return true.
@@ -101,7 +101,7 @@ public StatusInstance<TObject> Clone(int? value = null, int? priority = null, In
 		public StatusInstance(TBaseStatus status, int value = 1, int priority = 0, InstanceType type = InstanceType.Feed, int? overrideSetIndex = null) {
 			Status = status;
 			internalValue = value;
-			Priority = priority;
+			CancelPriority = priority;
 			InstanceType = type;
 			this.overrideSetIndex = overrideSetIndex;
 		}
@@ -110,8 +110,8 @@ protected StatusInstance(StatusInstance<TObject> copyFrom, int? value = null, in
 			Status = copyFrom.Status;
 			if(value == null) internalValue = copyFrom.internalValue;
 			else internalValue = value.Value;
-			if(priority == null) Priority = copyFrom.Priority;
-			else Priority = priority.Value;
+			if(priority == null) CancelPriority = copyFrom.CancelPriority;
+			else CancelPriority = priority.Value;
 			if(type == null) InstanceType = copyFrom.InstanceType;
 			else InstanceType = type.Value;
 			if(overrideSetIndex == null) this.overrideSetIndex = copyFrom.overrideSetIndex;

Hemlock/StatusTracker.cs

@@ -173,7 +173,7 @@ private void SerializeStatusInstances(InstanceType type, System.IO.BinaryWriter
 					writer.Write(instance.Status);
 					writer.Write((int)instance.InstanceType);
 					writer.Write(instance.Value);
-					writer.Write(instance.Priority);
+					writer.Write(instance.CancelPriority);
 					if(instance.OverrideSetIndex == null){
 						writer.Write(false);
 					}
@@ -350,7 +350,7 @@ public bool RemoveStatusInstance(StatusInstance<TObject> instance) {
 		/// (This will return the value of this status to zero, unless other statuses are feeding this one.)
 		/// </summary>
 		public void Cancel(TBaseStatus status) {
-			foreach(var instance in statusInstances[InstanceType.Feed][status].OrderBy(x => x.Priority)) {
+			foreach(var instance in statusInstances[InstanceType.Feed][status].OrderBy(x => x.CancelPriority)) {
 				RemoveStatusInstance(instance);
 			}
 			foreach(TBaseStatus extendingStatus in rules.statusesThatExtend[status]) Cancel(extendingStatus);

README.md

@@ -384,6 +384,13 @@ For example, you might want to prevent Burning for any creature that is currentl
 This is useful for prevention conditions, because (unlike suppression and cancellation) prevention only matters at the exact moment when a status instance is added.
 
 
+### Cancel priority
+Normally, when a status is canceled, all the StatusInstances for that status are removed in insertion order, with the value being recalculated as each is removed.
+
+Occasionally, it might be useful to have more control over the order in which instances are removed, especially for a boolean status, and especially if each instance prints a different message (through use of the override set feature).
+
+You can set the CancelPriority property on a StatusInstance to control this behavior: StatusInstances will be removed in order of CancelPriority, lowest to highest (while preserving insertion order for instances with the same priority).
+
 
 ## How does the parser work?