add: document the prop-being-ignored bug

Author: vytdev

src/ui-handlers.ts

@@ -49,7 +49,24 @@ export function openUI(player: Player, block: Block): void {
       for (const stateName of stateNameList) {
         const validVals = getStateValidValues(stateName);
         const selVal = validVals[r.formValues[i++ + 2] as number];
-        newStateObj[stateName] = selVal;
+        // BUG:
+        //
+        // in some cases where there are two property names referring to
+        // the same thing, like 'cardinal_direction' and 'direction' on doors,
+        // if you set one property but leave the other one unchanged,
+        // whether BlockPermutation.resolve will choose the correct changed
+        // property is undefined. internally, BlockPermutation.resolve might be
+        // preferring the most-recently set key, or the last key letter
+        // on the alphabet, but we dont know that since it's not documented.
+        //
+        // we also can't just blindly rely on this, as what if the player
+        // changed a property but reverted it back to the previous value.
+        // ideally, we must prefer the last property that the player has set,
+        // but unfortunately it's not doable. though checking whether the property
+        // differs from the current one has to be the most natural workaround.
+        //
+        if (selVal != currStates[stateName])
+          newStateObj[stateName] = selVal;
       }
 
       delete newStateObj['waterlogged'];  // temporary