Codex and ConditionalEvents: add guides for per-character data

PLATFORM.md

@@ -76,7 +76,9 @@ consumer set. Source builds must pass clean verification before publication.
 | [BarterShops](projects/BarterShops/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [BirdMessenger](projects/BirdMessenger/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [BreedingBuddies](projects/BreedingBuddies/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
+| [Codex](projects/Codex/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [CompanionPets](projects/CompanionPets/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
+| [ConditionalEvents](projects/ConditionalEvents/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [Cooking](projects/Cooking/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [CoreProtect](projects/CoreProtect/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [DenarEconomy](projects/DenarEconomy/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |

README.md

@@ -50,7 +50,9 @@ Choose a project to open its technical documentation and source repository link.
 | [ActivityTF](projects/ActivityTF/README.md) | Daily activity tasks, weekly progress, and player rewards. |
 | [BirdMessenger](projects/BirdMessenger/README.md) | Bird-delivered letters and interactive mailboxes. |
 | [BreedingBuddies](projects/BreedingBuddies/README.md) | Farm animal ownership, daily care, inherited genetics, and mount breeding. |
+| [Codex](projects/Codex/README.md) | Lore discoveries that each character keeps in its own journal. |
 | [CompanionPets](projects/CompanionPets/README.md) | Companion pet hatching, care, training, and play. |
+| [ConditionalEvents](projects/ConditionalEvents/README.md) | Configured actions for game events, with data per account or per character. |
 | [Games](projects/Games/README.md) | Tabletop games, card games, and wagering. |
 | [GeigerCounters](projects/GeigerCounters/README.md) | Geiger counter treasure hunts with proximity signals and tiered loot. |
 | [Magic](projects/Magic/README.md) | Magic, resonance, artifacts, and shrines. |

projects/Codex/README.md

@@ -0,0 +1,33 @@
+# Codex
+
+[Source repository](https://github.com/TF-Minecraft/Codex) · [All projects](../../README.md)
+
+TFMC's copy of [Ajneb97/Codex](https://github.com/Ajneb97/Codex): a journal of lore discoveries that each roleplay character keeps for itself.
+
+TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](../../PLATFORM.md) for runtime, build and validation conventions.
+
+## Build and dependencies
+
+Run Maven with **JDK 21** from the source checkout. The POM sets `maven.compiler.release=21` and resolves `io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT` with `provided` scope. The plugin descriptor declares `api-version: 1.21.10`. PlaceholderAPI, WorldGuard, WorldEdit, MythicMobs, EliteMobs and Residence come from their public Maven repositories, so Codex has no private build inputs.
+
+Install `me.plugins:tlibs:2.6.1` with the [shared installer](../TLibs/README.md), then build:
+
+```bash
+python3 path/to/TLibs/tools/install-plugins.py --pom pom.xml --mode pinned && mvn clean verify
+```
+
+JaCoCo requires 100% line coverage of `net.tfminecraft.codex.character`, the TFMC character code. Upstream code has no tests.
+
+## Runtime and configuration
+
+The manifest requires TLibs. RPCharacters provides character sessions; it loads after Codex, because it reads Codex for its placeholders. WorldGuard, PlaceholderAPI, MythicMobs and Residence are optional. Categories, discoveries, rewards and menus are configured as in upstream Codex; see the [upstream wiki](https://ajneb97.gitbook.io/codex).
+
+This copy has no MySQL storage, update checker or bStats reporting. Old `mysql_database` and `update_notify` keys in `config.yml` are ignored.
+
+## Guides
+
+- [Behaviour and operations](overview.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/Codex/overview.md

@@ -0,0 +1,29 @@
+# Codex
+
+[Project index](README.md)
+
+## Journals per character
+
+Each character has its own journal in `plugins/Codex/characters/<character>.yml`. Codex opens it when the character's session starts and saves it when the session ends, whether by switching, quitting, death or shutdown. It also saves open journals every `player_data_save` seconds. If a journal cannot be written when its session ends, Codex logs an error, keeps it in memory and retries with every save; the character gets it back if it returns first. A new character starts with an empty journal, so it discovers places and lore again and earns their rewards again, such as the Player EXP for a point of interest.
+
+Between characters, for example in the selection room, a player has no journal. Discoveries and rewards wait until a character is in play, and `/codex` answers `noCharacterInPlay` ("Choose a character to open the Codex.") instead of opening.
+
+## Out-of-character reference
+
+An entry the account found before journals were per character, or that any of its characters has found since (alive or dead), stays unlocked in `/codex`. Its click actions, such as the lore sub-pages on Main, still run, unless the entry sets `click_actions_cooldown`: that cooldown is kept on the character's own entry, so an entry with one runs its click actions only for a character that found it itself. Its hover text then names the living characters who can use it in character, the played character first: "Aldric and Mira can use this in character." If no living character found it itself, for example an entry from before journals were per character, the line reads "No character can use this in character." When the played character has not found the entry itself, a further line says "Aldric knows this only out of character." These three lines are `knownInCharacterBy`, `knownInCharacterByNobody` and `knownOutOfCharacterOnly` in `messages.yml`, and Codex adds them to existing files along with `noCharacterInPlay`.
+
+Codex reads the other journals when a session starts, since they cannot change while the account plays someone else, and again after `/codex resetplayer *`. Category progress, completion rewards and placeholders count only the played character's own discoveries.
+
+A journal file records `owner` (the account UUID), `name` (the account name when last saved) and, for each category, whether it is completed and its discoveries as `id;date;millis`.
+
+## Discoveries from before characters
+
+Upstream Codex kept one journal per account in `plugins/Codex/players/<account>.yml`. Those journals do not record which character found an entry, so no character inherits them: every character, the most-played one included, starts with an empty journal and earns each discovery and its rewards again. The account files stay where they are and feed the out-of-character reference above.
+
+## Staff commands
+
+`/codex resetplayer <player> [category] [discovery]` resets the journal of the character the player is playing now, and the player must be online. `/codex resetplayer * …` resets every character's journal file, every open journal and every account file in `players/`.
+
+## Placeholders
+
+RPCharacters' `codex_percent_` and `codex_holders_` placeholders count character journals; see [character controls](../RPCharacters/docs/character-controls.md#codex-rarity).

projects/ConditionalEvents/README.md

@@ -0,0 +1,34 @@
+# ConditionalEvents
+
+[Source repository](https://github.com/TF-Minecraft/ConditionalEvents) · [All projects](../../README.md)
+
+TFMC's copy of [Ajneb97/ConditionalEvents](https://github.com/Ajneb97/ConditionalEvents): configured actions for Minecraft events, with once-only and cooldown data per character by default, or per account.
+
+TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](../../PLATFORM.md) for runtime, build and validation conventions.
+
+## Build and dependencies
+
+Run Maven with **JDK 21** from the source checkout. The POM sets `maven.compiler.release=21` and resolves `io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT` with `provided` scope. The plugin descriptor declares `api-version: 1.21.10`. exp4j is shaded under `net.tfminecraft.conditionalevents.libs.exp4j`.
+
+ItemsAdder's public API artifact is no longer published, so the build uses the pinned ItemsAdder 4.0.18 jar from ServerAssets. Install `me.plugins:tlibs:2.6.1` with the [shared installer](../TLibs/README.md), prepare the private input, then build:
+
+```bash
+python3 path/to/TLibs/tools/install-plugins.py --pom pom.xml --mode pinned &&
+  (read -rsp 'ServerAssets token: ' GH_TOKEN && echo && export GH_TOKEN &&
+    bash .github/scripts/prepare-release.sh) &&
+  mvn clean verify
+```
+
+JaCoCo requires 100% line coverage of `net.tfminecraft.conditionalevents.character`, the TFMC character code. Upstream code has no tests.
+
+## Runtime and configuration
+
+The manifest requires TLibs. RPCharacters provides character sessions; it is not a load dependency, because SimpleFactions loads after ConditionalEvents and RPCharacters after SimpleFactions. Event types, conditions, actions and variables are configured as in upstream ConditionalEvents; see the [upstream wiki](https://ajneb97.gitbook.io/conditionalevents). This copy has no update checker or bStats reporting, and an old `Config.update_notification` key is ignored.
+
+## Guides
+
+- [Behaviour and operations](overview.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/ConditionalEvents/overview.md

@@ -0,0 +1,31 @@
+# ConditionalEvents
+
+[Project index](README.md)
+
+## Account or character data
+
+`one_time` and `cooldown` remember who has run an event. In this copy that memory belongs to the roleplay character being played. Set `data_scope: account` to keep it per account instead, as upstream:
+
+```yaml
+Events:
+  act1_exp_catchup:
+    type: repetitive
+    one_time: true
+    data_scope: account
+```
+
+The scope only matters for events with `one_time` or a `cooldown` that involve a player. Other events have nothing to keep and run as upstream: join messages, `server_start`, `player_pre_join`, and commands without a cooldown.
+
+An event that keeps per-character data runs only while a character is in play, so not at join before a character is chosen, in the selection room, or after the session has ended on quit. Use `data_scope: account` for join and leave events that keep data. A run belongs to the character it started for: if that character leaves before a delayed action is due, for example during `wait_ticks`, the rest of the actions, including action groups it calls with `execute_action_group`, are dropped, and the run's one-time flag and cooldown are undone so the character can earn it again. The undo skips anything a later run or a staff reset changed since. With `retain_player_data_until_restart: false`, a player who logs out mid-run has already been saved, so the marks stay; Main keeps player data until restart. Any `data_scope` value other than `character` or `account` logs a warning and counts as `character`.
+
+Keep anything a character learns or earns per character, such as Codex unlocks, since [Codex](../Codex/overview.md) keeps a journal per character. Use `data_scope: account` for supporter perks and other account rewards. The supporter EXP booster is `/tfmc booster` in TFMCCore and is per account.
+
+## Stored data
+
+Each account's file, `plugins/ConditionalEvents/players/<account>.yml`, keeps account events under `events` and per-character events under `characters.<character>.events`. Old per-account data does not record which character ran an event, so no character inherits it: events that are per character start fresh for every character, and their old account-level entries stay in the file, unused.
+
+`/ce reset <player> <event|all>` and `/ce reset * <event|all>` clear the account and every character.
+
+## Events on Main
+
+Main has 90 events that keep data. The 87 Codex unlocks in `codex.yml` and `codex_research.yml` and the meditation cooldown in `r_lore.yml` are per character by default, so a second character can earn an achievement, duchy title or research entry its account already has. `act1_exp_catchup` and `act1_exp_catchup_retry` set `data_scope: account`, so the one-off catch-up from before characters had their own progress does not arm again for every character.

projects/RPCharacters/docs/character-controls.md

@@ -52,7 +52,7 @@ The same player must wait 24 hours by default before striking a character again
 
 ## Codex rarity
 
-`%rpcharacters_codex_percent_<category>:<discovery>%` is the nearest whole percent of Codex accounts that have unlocked that entry. `%rpcharacters_codex_holders_<category>:<discovery>%` is the count. An unknown category or entry is blank. The figure refreshes about once a minute from Codex's saved files, using live Codex data for players who are online.
+`%rpcharacters_codex_percent_<category>:<discovery>%` is the nearest whole percent of Codex journals that have unlocked that entry. `%rpcharacters_codex_holders_<category>:<discovery>%` is the count. [TFMC Codex](../../Codex/overview.md) keeps a journal per character, so these count characters; with upstream Codex they count accounts. An unknown category or entry is blank. The figure refreshes about once a minute from Codex's saved files, using live Codex data for characters being played.
 
 ## Armour takes time