From 52af3c95fe4de5815363d3034bb03f0d79b59b52 Mon Sep 17 00:00:00 2001
From: Bartosz Taudul <wolf@nereid.pl>
Date: Fri, 9 Oct 2026 01:46:43 +0200
Subject: [PATCH] Add a zone annotation achievement.

---
 profiler/CMakeLists.txt                        |  1 +
 profiler/src/achievements/AnnotateZones.md     | 18 ++++++++++++++++++
 profiler/src/profiler/TracyAchievementData.cpp |  8 ++++++++
 profiler/src/profiler/TracyView_ZoneInfo.cpp   |  4 ++++
 4 files changed, 31 insertions(+)
 create mode 100644 profiler/src/achievements/AnnotateZones.md

diff --git a/profiler/CMakeLists.txt b/profiler/CMakeLists.txt
index e616dd87..4258e241 100644
--- a/profiler/CMakeLists.txt
+++ b/profiler/CMakeLists.txt
@@ -206,6 +206,7 @@ add_custom_command(
 Embed(PROFILER_FILES Manual manual/tracy.md TEXT BUILD)
 
 Embed(PROFILER_FILES Text100Million src/achievements/100Million.md TEXT)
+Embed(PROFILER_FILES TextAnnotateZones src/achievements/AnnotateZones.md TEXT)
 Embed(PROFILER_FILES TextConnectToClient src/achievements/ConnectToClient.md TEXT)
 Embed(PROFILER_FILES TextFindZone src/achievements/FindZone.md TEXT)
 Embed(PROFILER_FILES TextFrameImages src/achievements/FrameImages.md TEXT)
diff --git a/profiler/src/achievements/AnnotateZones.md b/profiler/src/achievements/AnnotateZones.md
new file mode 100644
index 00000000..7170fc8a
--- /dev/null
+++ b/profiler/src/achievements/AnnotateZones.md
@@ -0,0 +1,18 @@
+# Annotate zones
+
+Zones can carry more than just timing. Use the `ZoneText(txt, size)` macro to attach a contextual note to the current zone (the name of the file being opened, the id of the entity being processed) or `ZoneValue(value)` to report a number without paying the cost of converting it to a string. For printf-style formatting, use `ZoneTextF(fmt, ...)`.
+
+```c++
+void LoadTexture( const std::string& path )
+{
+    ZoneScoped;
+    ZoneText( path.data(), path.size() );
+    // ...
+}
+```
+
+The annotation shows up wherever the zone is displayed: in the tooltip when you hover over it on the timeline, and in the Zone info window. A `ZoneValue` is reported as a text note of the `1024 [0x400]` style. If you want to replace the zone's displayed name instead, use `ZoneName(txt, size)`, but note that such a per-call name is not used when zones are grouped for statistics.
+
+Zones can be colored, too: `ZoneScopedC(color)` sets a constant color at compile time, while `ZoneColor(color)` overrides it per call.
+
+Now add an annotation to one of your instrumented functions, profile your application, and click the zone on the timeline to open the Zone info window, your note will be waiting on the `User text:` line. Try it out!
diff --git a/profiler/src/profiler/TracyAchievementData.cpp b/profiler/src/profiler/TracyAchievementData.cpp
index 51c9bb0f..6c1f3a39 100644
--- a/profiler/src/profiler/TracyAchievementData.cpp
+++ b/profiler/src/profiler/TracyAchievementData.cpp
@@ -2,6 +2,7 @@
 #include "TracyEmbed.hpp"
 
 #include "data/Text100Million.hpp"
+#include "data/TextAnnotateZones.hpp"
 #include "data/TextConnectToClient.hpp"
 #include "data/TextFindZone.hpp"
 #include "data/TextFrameImages.hpp"
@@ -57,10 +58,17 @@ AchievementItem ai_findZone = {
     .text = Unpack( TextFindZone )
 };
 
+AchievementItem ai_annotateZones = {
+    .id = "annotateZones",
+    .name = "Annotate zones",
+    .text = Unpack( TextAnnotateZones )
+};
+
 AchievementItem* ac_instrumentationIntroItems[] = {
     &ai_100million,
     &ai_instrumentationStatistics,
     &ai_findZone,
+    &ai_annotateZones,
     nullptr
 };
 
diff --git a/profiler/src/profiler/TracyView_ZoneInfo.cpp b/profiler/src/profiler/TracyView_ZoneInfo.cpp
index ece6bf94..c78e3f37 100644
--- a/profiler/src/profiler/TracyView_ZoneInfo.cpp
+++ b/profiler/src/profiler/TracyView_ZoneInfo.cpp
@@ -1974,6 +1974,10 @@ void View::DrawGpuInfoChildren( const V& children, int64_t ztime )
 
 void View::ShowZoneInfo( const ZoneEvent& ev )
 {
+    if( s_config.achievements && m_worker.HasZoneExtra( ev ) && m_worker.GetZoneExtra( ev ).text.Active() )
+    {
+        Achieve( "annotateZones" );
+    }
     if( m_zoneInfoWindow && m_zoneInfoWindow != &ev )
     {
         m_zoneInfoStack.push_back( m_zoneInfoWindow );