rework readme

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Improve README.
+
 ## [0.4.0] - 2024-05-29
 
 ### Added

README.md

@@ -2,7 +2,7 @@
 
 [Valheim](https://store.steampowered.com/app/892970/Valheim/) mod that allows precise control over sharing pins via **cartography tables**.
 Supports **private pins**, **public pins**, and **guild pins**.
-Supports `NoMap` worlds.
+Supports `NoMap` runs, giving **cartography tables** a purpose in `NoMap`.
 
 ## Video showcase
 
@@ -22,7 +22,7 @@ https://github.com/nbusseneau/BetterCartographyTable/assets/4659919/e13e6267-88a
 <summary>Real-time collaboration</summary>
 
 Astrid and Brynhild are planning their next expedition.
-Thanks to **Better™️ Cartography Table**, they can collaborate in real time on the cartography table.
+Thanks to **Better™️ Cartography Table**, it will be a great success, as they can collaborate and prepare it in real time on the public cartography table.
 
 https://github.com/nbusseneau/BetterCartographyTable/assets/4659919/e535a301-994f-4129-b9ec-3e51685bab2c
 
@@ -31,63 +31,74 @@ https://github.com/nbusseneau/BetterCartographyTable/assets/4659919/e535a301-994
 <details>
 <summary><b>Guild pins</b></summary>
 
-Thanks to **Better™️ Cartography Table**, guilds can privately share pins amongst members.
-Brynhild is a member of The Ground Shakers guild, and Astrid does not have access to their cartography table.
-Astrid creates The Mushroom Enjoyers guild so that she can share a Super Secret Hideout with other mushroom enjoyers, which Brynhild will never know about.
+Astrid and Brynhild are members of rival guilds (The Mushroom Enjoyers and The Ground Shakers), and neither wants their archnemesis to know about their secret hideout.
+Thanks to **Better™️ Cartography Table**, their rivalry is fueled, as guild members can share guild-only pins on their guild-restricted cartography table.
 
 https://github.com/nbusseneau/BetterCartographyTable/assets/4659919/421e90b4-f00f-4047-b9ce-3839ac499035
 
 </details>
 
 ## Features
 
-- Pins are **private** by default, and can be individually shared on a **public cartography table**.
+- Pins are **private** by default, and can be individually shared to **cartography tables**.
   - You can now safely go ham and pin all those nice berries / copper veins / whatever floats your boat, without worrying about cluttering another player's map.
-- When multiple players are interacting with the same **cartography table**, changes are reflected in real time for all of them.
+- When multiple players interact with the same **cartography table** at the same time, all changes are reflected in real time.
   - This allows collaborating over the map in real time, especially useful when planning the next expedition.
 - **Cartography tables** can be **public** (default) or **restricted to a guild** (if [**Guilds**](https://thunderstore.io/c/valheim/p/Smoothbrain/Guilds/) is installed).
   - For when you want to share super secret guild hideouts with your mates. Not that it ever happens. Definitely don't look for super secret guild hideouts on your servers. Nope...
-- If using the `NoMap` world modifier, map will be accessible only through a cartography table.
+- If using the `NoMap` world modifier, the map will be accessible through **cartography tables** (but only when directly interacting with them).
 
 ## But why?
 
-The vanilla **cartography table** is quirky and often leads to frustration on multiplayer servers: it only stores the pins of the last player that wrote to the table, completely replacing what was previously recorded.
+The vanilla **cartography table** is extremely quirky.
+This often leads to frustration on multiplayer servers when multiple players interact with the table on a regular basis, as shared pins seem to disappear / reappear constantly, and crossing off shared pins does not update the table.
 
-This often results in situations where shared pins seem to disappear / reappear constantly when multiple players interact with the table on a regular basis (and it also never updates cross off status...).
+On top of that, since the vanilla **cartography table** is "all or nothing", some players might refrain from engaging altogether.
+This is typically the case for those that like to meticulously pin all berries / copper veins / etc. but don't want others to yell at them for cluttering the table, or those that do not want to share some super secret pins they would prefer to keep private.
 
-On top of that, since the **cartography table** is "all or nothing" both ways, some players might refrain from interacting with the table (e.g. when someone is meticulously pinning all berries / copper veins / etc., or when they do not want to share some super secret pins they would prefer to keep private).
-
-And of course, the vanilla cartography table is completely useless in `NoMap` runs.
+And of course, the vanilla **cartography table** has no purpose in `NoMap` runs.
 
 ## Vanilla cartography tables, but Better™️
 
-The goal is to stick close to the vanilla experience and keep **cartography tables** relevant (or in the case of `NoMap` runs, give them a purpose). We are not bypassing **cartography tables**: sharing map data (both pins and exploration) still requires players to interact with the same **cartography table** on a regular basis to synchronize progress.
+The goal of this mod is to stick as close as possible to the vanilla experience.
+We keep **cartography tables** relevant for sharing both pins and map exploration, same as in vanilla: players must still interact with the same **cartography table** on a regular basis to synchronize progress with other players.
+For `NoMap` runs, the goal is to give **cartography tables** a purpose.
 
-How it works:
+<details>
+<summary>How it works in details <b>(click to show details)</b></summary>
 
+- When opening the map without interacting with a **cartography table**:
+  - **Private pins** can be interacted with, same as in vanilla.
+  - **Public** or **guild pins** previously retrieved from a **cartography table** can be shown or hidden (akin to vanilla shared pins), but cannot be interacted with (cannot cross off, cannot remove).
+  - In `NoMap` runs, the map will still refuse to open: it can only open by interacting with a **cartography table**.
 - When interacting with a **cartography table**:
-  - Synchronize map exploration (same as vanilla).
-  - Retrieve **table pins** currently stored on the table.
+  - Synchronize map exploration, same as in vanilla.
+  - Retrieve **public** or **guild pins** currently shared to the table.
   - Open the map:
-    - **Private pins** can be interacted with, and can additionally be stored on the table, becoming **table pins** (either **public** or **guild pins**, depending on the table mode).
-    - **Table pins** can be interacted with, and can additionally be unstored from the table, becoming **private** pins. If multiple players are currently interacting with the same **cartography table**, changes to **table pins** are reflected in real time for all of them.
-- When opening the map without interacting with a **cartography table**:
-  - **Private pins** can be interacted with.
-  - **Public** or **guild pins** previously retrieved from a **cartography table** can be displayed / hidden, but cannot be interacted with.
+    - **Private pins** can be interacted with, same as in vanilla, but can additionally be shared to the table (becoming **public** or **guild pins**).
+    - **Public** or **guild pins** can be crossed off / removed akin to vanilla, or unshared from the table (becoming **private pins**).
+    - When multiple players interact with the same **cartography table** at the same time, all changes to **public** or **guild pins** are reflected in real time.
+- If [**Guilds**](https://thunderstore.io/c/valheim/p/Smoothbrain/Guilds/) is installed, **cartography tables** can be switched between **public mode** (default) or **guild mode**. When a table is in **guild mode**, only its guild members can interact with it.
+
+</details>
+
+### Compatibility with vanilla clients
+
+**Public** and **guild pins** are stored separately from vanilla shared pins in the **cartography table**, thus both modded and vanilla clients can interact with the same **cartography tables** without conflict.
+Additionally, modded clients will copy **public pins** to vanilla shared pins, allowing vanilla clients to receive them seamlessly.
+However, vanilla clients are not able to contribute back: modded clients can only receive pins from other modded clients.
 
-### Compatibility with non-modded vanilla clients
+### Compatibility with other mods
 
-**Table pins** are stored in a custom ZDO key under the **cartography table**'s ZNetView's ZDO, thus non-modded vanilla clients and modded clients can both interact with the same **cartography tables** without conflict.
-Limited one-way sharing is provided, as modded clients also write public pins to the vanilla shared data, allowing non-modded vanilla clients to receive public pins seamlessly.
-However, non-modded vanilla clients are not able to contribute back: modded clients can only receive pins from other modded clients.
+**Better™️ Cartography Table** tries to play nice with other mods by isolating its behaviour as much as possible, and failing that by trying to ensure the other mods will contribute pins in a compatible way. Nevertheless, there might be instances where other mods interacting with pins will result in incompatiblities. Feel free to [report any issue you find](https://github.com/nbusseneau/BetterCartographyTable/issues/new).
 
 ## Install
 
-This is technically a client-side mod, and is not strictly required server-side.
-Yet, **it is strongly recommended to install the mod server-side** so as to enforce that all clients have the mod.
+This is technically a client-side mod, but **it is strongly recommended to also install the mod server-side** for the best experience.
+If installed on the server, it will enforce all clients to have the mod installed.
 
 Exception: do not install the mod on servers intended for Xbox crossplay, otherwise Xbox players will not be able to join anymore.
-Note that non-modded vanilla clients will not be able to share any of their pins with modded clients ([see above for details](#compatibility-with-non-modded-vanilla-clients)).
+If you do allow crossplay, note that vanilla clients will not be able to share any of their pins with modded clients ([see above for details](#compatibility-with-vanilla-clients)).
 
 ### Thunderstore (recommended)
 

thunderstore.toml

@@ -6,7 +6,7 @@ schemaVersion = "0.0.1"
 namespace = "nbusseneau"
 name = "Better_Cartography_Table"
 versionNumber = "0.4.0"
-description = "Allows precise control over sharing pins via cartography tables. Supports private pins, public pins, and guild pins. Supports NoMap worlds."
+description = "Allows precise control over sharing pins via cartography tables. Supports private pins, public pins, and guild pins. Supports NoMap runs, giving cartography tables a purpose in NoMap."
 websiteUrl = "https://github.com/nbusseneau/BetterCartographyTable"
 containsNsfwContent = false