From 795260bec7962330ce7f2c4e697267e4995c9d6b Mon Sep 17 00:00:00 2001 From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com> Date: Sat, 3 Oct 2026 22:36:56 +0000 Subject: [PATCH] docs(activitytf): add the activity descriptions guide Moved from the ActivityTF source repository's ACTIVITY-LORE.md: description placeholders, the description update tool, and what each of Main's audited activities counts. Changelog-style audit notes are reworded as current behaviour. Co-Authored-By: Claude Opus 5.5 (1M context) --- projects/ActivityTF/ACTIVITY-LORE.md | 85 ++++++++++++++++++++++++++++ projects/ActivityTF/README.md | 1 + 2 files changed, 86 insertions(+) create mode 100644 projects/ActivityTF/ACTIVITY-LORE.md diff --git a/projects/ActivityTF/ACTIVITY-LORE.md b/projects/ActivityTF/ACTIVITY-LORE.md new file mode 100644 index 0000000..05fe144 --- /dev/null +++ b/projects/ActivityTF/ACTIVITY-LORE.md @@ -0,0 +1,85 @@ +# Activity descriptions + +[ActivityTF](README.md) ยท [All projects](../../README.md) + +Activity `description` lines support three local placeholders: + +| Placeholder | Config value | Meaning | +| --- | --- | --- | +| `%every%` | `every` | Count required for one completion/award | +| `%points%` | `points` | Points earned per completion | +| `%daily-cap%` | `daily-cap` | Maximum awards per day; zero means uncapped | + +Values come from the loaded activity definition whenever the GUI renders. +After changing settings, reload ActivityTF and reopen the menu. Single strings +and lists both work; colours and unknown placeholders retain their existing +behaviour. These placeholders do not require PlaceholderAPI. + +`every` uses the tracked activity's unit: minutes for playtime, Denar for market +sales/card profit, XP for professions, output items for vanilla crafting, +and completed recipes for MMOItems stations. Station output stack sizes do +not affect credit. Configured `station-actions` aliases retain their credit +amounts (for example, the bulk Coal recipe counts as 16 standard crafts). + +The daily cap limits awards, not raw actions or points. The shared daily bar, +voting share and weekly bar may limit the points actually credited further. +Tasks must be revealed before their actions count. + +## Existing server configs + +The plugin does not overwrite existing descriptions. To prepare the audited +wording for an existing config, install PyYAML and run +[`tools/update-activity-descriptions.py`](https://github.com/TF-Minecraft/ActivityTF/blob/main/tools/update-activity-descriptions.py) +from the source checkout: + +```sh +python3 tools/update-activity-descriptions.py config.yml config-updated.yml +``` + +Review the resulting diff before deployment. This writes a separate file and +changes only active activity descriptions, preserving commented-out activities, +other settings, rewards and state. It refuses unknown activity types rather +than inventing instructions. Rerunning it is safe, but replaces custom active +descriptions with the audited templates. Its tests run with +`python3 -m unittest discover -s tools -p 'test_*.py'`; CI does not run them. + +## What Main's activities count + +The audited templates describe Main's 37 active activities, checked on 2026-09-30 +against their event handlers and the live MMOItems recipes. Commented-out +activities are not covered. Recheck this table when activities or recipes change. + +| Activities | Correct explanation/unit | +| --- | --- | +| vote | Real votes; `/vote` links remain | +| playtime | Active minutes; idle minutes excluded when AFK checks are enabled | +| geiger | Collect the source with a Trace Detector; finding it alone does not count | +| archaeology_find | Recover finds, rather than merely start/finish a project | +| instrument | Notes played | +| market_sale | Denar earned, per award | +| casino_win | Positive card-game profit above stake before tax | +| ic_chat | Substantial in-character messages; short/repetitive/OOC chat excluded | +| injured | Receive an injury as the target, rather than injure someone else | +| vehicle_build | Finished vehicles at construction stations | +| battle_joined | Participation credited when a faction battle ends | +| advcraft_item | Completed Advanced Crafting items or alloys; five per award, two awards/day | +| cook_dish | Finished dishes at pots/stations/boards; trough feed is separate | +| profession_upgrade | Purchased profession upgrades | +| profession_crafter, profession_forager, profession_herborist | Profession XP | +| ingot_flint, ingot_coal | Standard recipe crafts at a Blast Furnace; bulk Coal aliases still count | +| tool_iron_pickaxe, tool_iron_axe, tool_iron_hoe, tool_iron_shovel | Named recipe crafts at a Crafting Table | +| forester_arrow, forester_oak_log, forester_spruce_log | Named recipe crafts at a Fletching Table | +| alchemy_coal, alchemy_powder | Named recipe crafts at a Brewing Stand | +| instrument_lute | Lute recipe crafts at a Jukebox | +| research_scribe_paper | Unknown Research Paper recipe crafts at a Cartography Table | +| medicine_herb_mixture, medicine_splint | Willow-Bark Tincture/Splint recipe crafts at a Medicine Station | +| engineer_fuel | Arcane Fuel recipe crafts at an Engineer Station | +| fishing_rod | Basic Fishing Rod recipe only; other rods do not count | +| fishing_iron_hook | Iron Hook recipe crafts at a Fishing Station | +| animal_universal_feed | Collect finished trough feed, with an empty-hand right click | +| animal_llama | Llama Spawn Egg recipe crafts at an Animal Station | + +Descriptions count recipe crafts rather than output totals: Flint/Coal produce +four per standard craft, forester recipes produce 64, powder produces two, +tincture/splint produce eight and fuel produces 16. Placeholder craft counts +remain correct if those outputs change. diff --git a/projects/ActivityTF/README.md b/projects/ActivityTF/README.md index 04fb61e..34c0690 100644 --- a/projects/ActivityTF/README.md +++ b/projects/ActivityTF/README.md @@ -15,6 +15,7 @@ Install the shared Maven plugin dependencies selected by the POM, then supply th Optional runtime integrations are declared as `softdepend` in `src/main/resources/plugin.yml`; those declarations do not remove their compile-time JAR requirements. `ActivityPlugin` registers hooks for installed plugins, `ActivityManager` owns task progress and rewards, and `/activity` opens the GUI or runs permitted admin actions. - [Reward pools and operator checks](REWARD-POOLS.md) +- [Activity descriptions, placeholders and config updates](ACTIVITY-LORE.md) ## Builds and releases