Update 058-player-flags.rst (#53)

EmosewaMC · web-flow · commit 0eaf1c0d852e · 2022-12-13T12:28:01.000+01:00
diff --git a/docs/components/004-character.rst b/docs/components/004-character.rst
@@ -41,12 +41,13 @@ Relevant Game Messages
 
 Server received
 _______________
+| :gm:server:`SetTooltipFlag`
 | :gm:server:`ModifyPlayerZoneStatistic`
 | :gm:server:`UpdatePlayerStatistic`
 | :gm:server:`SetEmotesEnabled`
 
 Component XML Format
-............................
+....................
 
 |   :samp:`char` - Character Component data
 |   :samp:`attr acct` - account ID
@@ -147,3 +148,8 @@ Character Statistics Format
 | RacingSmashablesSmashed
 | RacesFinished
 | FirstPlaceRaceFinishes
+
+Tooltip flags
+.............
+
+.. todo:: bitmask?
diff --git a/docs/components/058-player-flags.rst b/docs/components/058-player-flags.rst
@@ -1,7 +1,11 @@
 Player Flags Component (58)
 ---------------------------
 
-This component likely manages the player flags.
+This component manages the player flags.  See :doc:`../game-mechanics/flag-system` for the list of all known flags.
+
+.. note::
+
+    Tooltip flags are unrelated to this component.  See :doc:`004-character` for information regarding these.
 
 Relevant Database Tables
 ........................
@@ -10,24 +14,85 @@ This component uses the following tables:
 
 * :doc:`../database/PlayerFlags`
 
-Relevant Game Messages:
-.......................
+Relevant Game Messages
+......................
+
+* :gm:server:`SetFlag`
+* :gm:client:`NotifyClientFlagChange`
+
+Component XML Format
+....................
+
+| :samp:`flag` - Player Flag Component data
+|     :samp:`f` - Player flag
+|     :samp:`attr id` - This flags index
+|     :samp:`attr v` - This flags value
+|     :samp:`s` - Session flag
+|     :samp:`attr si` - Session flag Id as a literal number (ex. 114).  Each session flag gets its own :samp:`s` element.
+
+Flags are always saved as blocks of 64 bits.
+When a flag is set, its index in the flags list is the flag id divided by 64, truncated to an int.
+The position at the index calculated above is the flag id modulo 64.
+
+Example code to set a player flag:
+
+.. code-block:: python
+
+    player_flags = {}
+    def set_player_flag (flag_id, turn_flag_on):
+        # First calculate the index, in this case it equals 17
+        flag_index = int(flag_id / 64)
+        # Then calculate the position, which is also 17, and set the bit at that position.
+        flag_value_shifted = 1 << flag_id % 64
+        # Then check if we already have flags at this flag index
+        flag_to_update = player_flags.get(flag_index)
+        if flag_to_update != None:
+            if turn_flag_on == True:
+                # Turn the bit at flag_value_shifted in flag_to_update to True
+                flag_to_update = flag_to_update | flag_value_shifted
+            else:
+                # Turn the bit at flag_value_shifted in flag_to_update to False by inverting the binary
+                # value of flag_value_shifted and ANDing with flag_to_update
+                flag_to_update = flag_to_update & ~flag_value_shifted
+            player_flags[flag_index] = flag_to_update
+        else:
+            # Create the new flag value and insert it into the dictionary of flags
+            new_flag_value = flag_value_shifted
+            player_flags[flag_index] = new_flag_value
+
+    # Turns player flag 1105 on
+    set_player_flag(1105, True)
+    # {17: 131072}
+    print(player_flags)
+    # Does nothing since player flag 1105 is already on
+    set_player_flag(1105, True)
+    # {17: 131072}
+    print(player_flags)
+    # Turns player flag 2 on
+    set_player_flag(2, True)
+    # {17: 131072, 0: 4}
+    print(player_flags)
+    # Turns player flag 1105 off
+    set_player_flag(1105, False)
+    # {17: 0, 0: 4}
+    print(player_flags)
 
-* :gm:`SetTooltipFlag`
-* :gm:`SetFlag`
-* :gm:`NotifyClientFlagChange`
+Here is how flag changes are communicated between the client and the WorldServer:
 
-XML Serialization :samp:`<flag>`
-................................
+.. uml::
 
-This component is serialized to XML to store its data.
+    @startuml
+    skinparam sequenceMessageAlign center
+    group Client sets a flag
+        Client -> WorldServer: [<b>Game Message SetFlag</b>]
+    end
 
-Flags :samp:`<f>`
-'''''''''''''''''
+    WorldServer -> Client: [<b>Game Message NotifyClientFlagChange</b>]
+    @enduml
 
-Flags are serialized as blocks of 64 bit. The ID of such a block is
-the common prefix you get when shifting all flags indices to the right
-by 6 bits.
+If a flag is a session flag, it should be set for the duration of a session and when the player changes character
+or logs out, these flags should be cleared.  A session flag can be found by querying the :doc:`../database/PlayerFlags`
+table and if the :samp:`SessionOnly` boolean is set to true, the flag is set for the session.
 
-:id: The ID of the flag group
-:v: The value of 64 flags
+There are two flags in live, flags :samp:`1110` and :samp:`2099` which have :samp:`SessionZoneOnly` set to true.
+The use of :samp:`SessionZoneOnly` is guessed to be to detect if a player has done something in a zone this session.
diff --git a/docs/database/LevelProgressionLookup.rst b/docs/database/LevelProgressionLookup.rst
@@ -5,7 +5,7 @@ This table contains a level and the uscore required to be that level.
 All :samp:`BehaviorEffect` columns are empty.
 
 .. list-table ::
-   :widths: 15 30
+   :widths: 15 15 30
    :header-rows: 1
 
    * - Column
diff --git a/docs/database/PlayerFlags.rst b/docs/database/PlayerFlags.rst
@@ -3,13 +3,24 @@ PlayerFlags
 
 Configuration for the :doc:`../game-mechanics/flag-system`.
 
-==================================================  ==========
-Column                                              Type      
-==================================================  ==========
-id                                                  INTEGER   
-SessionOnly                                         BOOLEAN   
-OnlySetByServer                                     BOOLEAN   
-SessionZoneOnly                                     BOOLEAN   
-==================================================  ==========
-
-512 Slots
+.. list-table ::
+   :widths: 15 15 20
+   :header-rows: 1
+
+   * - Column
+     - Type
+     - Description
+   * - id
+     - INTEGER
+     - A flag id.
+   * - SessionOnly
+     - BOOLEAN
+     - Whether or not this flag is set only for a play session.
+   * - OnlySetByServer
+     - BOOLEAN
+     - Whether or not this flag is only set by the server.
+   * - SessionZoneOnly 
+     - BOOLEAN
+     - Whether or not this flag is only set for the session in the current zone(?)
+
+Allocated space: 512 Slots
diff --git a/docs/game-mechanics/flag-system.rst b/docs/game-mechanics/flag-system.rst
@@ -205,6 +205,7 @@ Known Flags
     1107, AG Launch Binoc Intro, 1.1.18 client
     1108, AG Launch Binoc Bison, 1.1.18 client
     1109, AG Launch Binoc Shark, 1.1.18 client
+    1110, Set when a player has dug once on a property, 1.10.64 client
     1201, NS Binoc Concert Transition, 1.1.18 client
     1202, NS Binoc Race Place Transition, 1.1.18 client
     1203, NS Binoc Brick Annex Transition, 1.1.18 client
@@ -340,6 +341,7 @@ Known Flags
     1975, Paradox Pet, 1.4.49 client
     1976, Paradox Assembly Spy, 1.4.49 client
     1977, Paradox Venture Spy, 1.4.49 client
+    2099, Player has the Sensei wu daily dragon mission, 1.10.64 client
     11001, SS Plaque 1, 1.1.18 client
     11002, SS Plaque 2, 1.1.18 client
     11003, SS Plaque 3, 1.1.18 client
