TownyUtils RENEWED

---

🌐 Client-side Diplomacy Management & Combat Analytics

TownyUtils is a high-performance hitbox coloring and combat analytics mod designed to maximize situational awareness in chaotic SiegeWar environments.

This mod is designed for players who struggle to tell who they are hitting in extremely crowded SiegeWar environments and who want to maximize their efficiency in SiegeWars. TownyUtils is not a cheat mod; it is a QoL mod that reduces visual clutter and provides real-time performance data.

---

⚔️ NEW: SiegeWar Statistics Engine

The most powerful addition to TownyUtils is the real-time combat analytics engine.

• Real-time K/D Tracking: Monitor your own and your team's kills and deaths as they happen.
• Live Leaderboards: Dynamic rankings showing the top performers in the current battle.
• Multi-Town Support: Automatically separates data for different towns during multi-objective sieges.

When I first started working on this system, I thought it would be simple. However, many factors that emerged later such as combatlog plugins, command outputs varying significantly from server to server, and different plugins being used across servers have limited this feature to working only on the MaviBuğday Towny server.

Unfortunately, due to these factors, support for other servers will not be added.

You can view your MaviBuğday SiegeWar statistics by joining our Discord server, where you can see both the besieged towns and the overall nation and player rankings.

---

📊 Performance data-blocked: Real Battle Results

Actual SiegeWar Statistics

In a siege battle that took place today (February 22, 2026), we compared performance between players using TownyUtils and players without:

Team	Players	Mod Usage	Voice Comms	Total Kills	Kills/Player	Performance
Pangea Alliance	~15-20	❌ No Mod	✅ Yes	16 kills	0.8 kills/player	Baseline
TownyUtils Users	4	✅ With Mod	✅ Yes	18 kills	4.5 kills/player	5.6x better

Context: Both teams had equal skill levels (HT5-LT4-HT4-LT3-HT3), equal equipment, same position. Both teams had voice coordination within their respective groups.

Why Such a Dramatic Difference?

Factor	Without TownyUtils	With TownyUtils	Improvement
Target Selection Time	~2.0 seconds	~0.2 seconds	10x faster
Target Accuracy	~60% correct target	~95% correct target	+58% accuracy
Wasted Actions	40% wrong targets	5% wrong targets	87% reduction
Combat Cycle	2.5 sec/attack	0.7 sec/attack	3.5x faster

Mathematical Analysis: The 5.6x performance factor is derived from the combination of faster target acquisition (3.5x) and increased accuracy (1.58x), which translates to 5.53x theoretical performance gain, almost perfectly reflecting actual battle results.

---

⚙️ Core Architecture

TownyUtils is built on three main background data-processing engines:

1. Command Parsing (Primary)

• The client listens in real time to the outputs of /n online, /n allylist, /n enemylist sent by the server, as well as to scoreboard data.

2. Nametag Reader (Secondary)

• By reading TextDisplayEntity and Nametag data, it detects players' nations before they are rendered and classifies them as friendly or enemy.

3. Siege Log Analytics (New)

• Parses incoming chat logs in real-time to update the Siege Statistics dashboard and leaderboards.

---

📡 Tactical Intelligence (Radar)

🎯 Actionbar Radar (Enemy Detection)

• By pressing the O key, you can activate the real-time proximity radar. It displays the exact count of nearby Enemies and Allies right on your actionbar, preventing clans from bluffing about their numbers during battle.

---

🛠️ Usage & Configuration

After downloading and installing TownyUtils, you additionally need to install Mod Menu to manage TownyUtils. You can open the TownyUtils menu on any server either by searching for TownyUtils in Mod Menu or by pressing the Insert key.

• Mod Status – Allows you to enable or disable the mod's primary data-processing engines.
• Interactive Tutorial (New) – Opens an animated 10-step guide to help you get started with the mod's features.
• Siege Statistics (New) – Opens the real-time combat analytics dashboard featuring VS cards and Leaderboards.
• Hitboxes – Lets you toggle TownyUtils' colored hitboxes based on ally–enemy diplomacy.
• Name Tags – Disables nametags, which are the main FPS killer on bad GPUs in Towny sieges, and helps you see more clearly in chaotic environments.
• Auto Setup Wizard – Automatically classifies your current nation's enemies and allies as hostile or friendly.
• Start Manual Detection – Automatically activates the primary data-processing engine (Command Parsing).
• Detection – Lets you choose which data-processing engine to use for detection.
• Auto Setup Target – If you go to help an allied nation instead of your own, this sets the target nation for the Auto Setup Wizard so you can define its enemies and allies.
• Data Management – Allows you to review, backup, or reset your locally stored towny statistics and diplomatic data.
• Enemy Detection (Radar) – Can be toggled with the O key to show nearby player counts on the actionbar.

---

🕵️ Data Privacy

Why is data collected?

In TownyUtils, the data-processing engine with the highest accuracy and compatibility across servers is the command-parsing engine that parses Towny commands. This engine may work incorrectly or not work at all due to the different formats and languages used by each Towny server. For this reason, only the outputs of the commands /n online, /n allylist, and /n enemylist from the command-parsing engine that you start automatically or manually are sent to us. This helps us improve the mod's cross-server compatibility.

⚠️ PRIVACY GUARANTEE

❌ No Personal Data: Your chat logs, passwords, or private messages are NEVER accessed or collected.

✅ Command Output Only: Only the structure of towny commands is analyzed for compatibility.

Your data sharing preference can be toggled ON/OFF at any time in the settings. Your data is never shared with third parties. Data is transmitted to a private endpoint controlled by the developer. The endpoint URL is not public. During command parsing, messages within a short capture window may be transmitted to ensure compatibility across servers with different formats.

---

📜 Disclaimer & FAQ

All Rights Reserved. Unauthorized use of the source code, reverse engineering, or redistribution is prohibited.

❓ Does this mod provide an unfair advantage?

No. This mod is a client-side visual enhancement tool (QoL). It does not send packets or transmit any unauthorized data to the server.

This mod is not designed to provide an unfair advantage; on the contrary, it is designed to maximize competitiveness and enjoyment in SiegeWars.

❓ Why doesn't the Nametag Reader work?

The secondary data-processing engine, the Nametag Reader, has a very low success rate and is not guaranteed to work on every server. This is because nametags are restructured differently on each server, and in some cases they may not even include nation names. However, on servers where it does work, both data-processing engines run successfully, so there are no delays in diplomacy detection and updates.

❓ Why doesn't the mod work on the server I play on?

Since the mod has so far been tested only on Turkish servers, it is not guaranteed to work on servers with different language formats. In general, the primary data engine has worked successfully on all Turkish servers I tested. Likewise, it has also worked on foreign geopolitical servers such as EarthMC. However, it is not guaranteed to work on every foreign server.

---

TÜRKÇE

---

TownyUtils RENEWED

---

🌐 Towny İçin Diplomasi Yönetimi ve Savaş Analitiği

TownyUtils, kaotik SiegeWar ortamlarında durumsal farkındalığı ve performansı zirveye taşımak için tasarlanmış bir vuruş kutusu (hitbox) renklendirme ve canlı istatistik modudur.

Bu mod, özellikle aşırı kalabalık SiegeWar ortamlarında kime vurduğunu ayırt etmekte zorlanan, SiegeWar savaşlarından maksimum verim veya keyif alamayan oyuncular için tasarlanmıştır. TownyUtils bir hile modu değildir; görsel karmaşayı azaltan ve gerçek zamanlı performans verileri sunan bir Yaşam Kalitesi (QoL) modudur.

---

⚔️ YENİ: SiegeWar İstatistik Motoru

TownyUtils'e eklenen en güçlü özellik gerçek zamanlı savaş analitiği motorudur.

• Anlık K/D Takibi: Savaş sırasında kendinizin ve ekibinizin skorlarını saniyelik takip edebilirsiniz.
• Canlı Liderlik Tablosu: Mevcut savaşta en çok fark yaratan oyuncuları listeleyen dinamik sıralama.
• Çoklu Kasaba Desteği: Çok hedefli kuşatmalarda verileri farklı kasabalar için otomatik olarak ayırır.

Bu sistemi geliştirmeye başladığımda kolay olacağını düşünmüştüm. Ancak sonradan ortaya çıkan birçok farklı etken (CombatLog eklentileri, komut çıktılarının sunucudan sunucuya büyük ölçüde farklılık göstermesi ve sunucularda farklı eklentilerin kullanılması) nedeniyle bu özellik yalnızca MaviBuğday Towny sunucusunda çalışacak şekilde kalmıştır.

Maalesef bu sebeplerden dolayı başka sunucular için destek eklenmeyecektir.

---

📊 Performans Verileri: Gerçek Savaş Sonuçları

Gerçek SiegeWar İstatistikleri

Bugün gerçekleşen bir kuşatma savaşında (22 Şubat, 2026), TownyUtils kullanan ve kullanmayan oyuncuların performanslarını karşılaştırdık:

Takım	Oyuncu	Mod Kullanımı	Sesli İletişim	Toplam Kill	Kill/Oyuncu	Performans
Pangea İttifakı	~15-20	❌ Mod Yok	✅ Evet	16 kill	0.8 kill/oyuncu	Temel seviye
TownyUtils Kullanıcıları	4	✅ Mod Var	✅ Evet	18 kill	4.5 kill/oyuncu	5.6x daha iyi

Bağlam: Her iki takım da eşit yetenek seviyesine (HT5-LT4-HT4-LT3-HT3), eşit ekipmana, aynı pozisyona sahipti. Her iki takım da kendi grupları içinde sesli koordinasyona sahipti.

Neden Bu Kadar Dramatik Bir Fark?

Faktör	TownyUtils Olmadan	TownyUtils İle	İyileşme
Hedef Seçim Süresi	~2.0 saniye	~0.2 saniye	10x daha hızlı
Hedef Doğruluğu	~%60 doğru hedef	~%95 doğru hedef	+%58 doğruluk
Boşa Giden Eylemler	%40 yanlış hedef	%5 yanlış hedef	%87 azalma
Savaş Döngüsü	2.5 sn/saldırı	0.7 sn/saldırı	3.5x daha hızlı

Matematiksel Analiz: 5,6 katlık performans faktörü, daha hızlı hedef tespitinin (3,5 kat) ve artan isabet oranının (1,58 kat) birleşiminden türetilmiştir; bu durum, teorik olarak 5,53 katlık bir performans artışına tekabül ederek gerçek SiegeWar sonuçlarını neredeyse kusursuz bir şekilde yansıtmaktadır.

---

⚙️ Çekirdek Mimarisi

TownyUtils, arka planda çalışan üç ana veri işleme motoru üzerine kurulmuştur:

1. Komut Ayrıştırma (Birincil)

• İstemci; sunucu tarafından gönderilen /n online, /n allylist, /n enemylist çıktılarının yanı sıra skor tablosu (scoreboard) verilerini de gerçek zamanlı olarak dinler.

2. İsim Etiketi Okuyucu (İkincil)

• TextDisplayEntity ve Nametag verilerini okuyarak, oyuncuların uluslarını onlar henüz renderlanmadan algılar ve onları dost veya düşman olarak sınıflandırır.

3. Kuşatma Log Analitiği (Yeni)

• Chat loglarını gerçek zamanlı ayrıştırarak Kuşatma İstatistikleri panelini ve liderlik tablolarını günceller.

---

📡 Taktiksel İstihbarat (Radar)

🎯 Actionbar Radarı (Düşman Tespiti)

• O tuşuna basarak gerçek zamanlı yakınlık radarını aktif edebilirsiniz. Actionbar üzerinde en yakın Düşman ve Dost sayısını göstererek, klanların savaş içinde "rakam sallamasını" (sayı uydurmasını) önler ve size net tabloyu gösterir.

---

🛠️ Kullanım & Yapılandırma

TownyUtils'i indirip kurduktan sonra, TownyUtils'i yönetebilmek için ek olarak Mod Menu modunu kurmanız gerekir. TownyUtils menüsünü herhangi bir sunucudayken Mod Menu içinde TownyUtils'i aratarak veya Insert tuşuna basarak açabilirsiniz.

• Mod Status (Mod Durumu) – Modun ana veri işleme motorlarını etkinleştirmenizi veya devre dışı bırakmanızı sağlar.
• İnteraktif Rehber (Yeni) – Modun özelliklerini tanımanıza yardımcı olacak 10 adımlık animasyonlu bir rehber açar.
• Kuşatma İstatistikleri (Yeni) – VS kartları ve Liderlik panosunu içeren gerçek zamanlı savaş analitiği panelini açar.
• Hitboxes (Vuruş Kutuları) – Müttefik-düşman diplomasisine dayalı olarak TownyUtils'in renkli vuruş kutularını açıp kapatmanızı sağlar.
• Name Tags (İsim Etiketleri) – Towny kuşatmalarında kötü ekran kartlarında ana FPS düşürücü olan isim etiketlerini devre dışı bırakır ve kaotik ortamlarda daha net görmenize yardımcı olur.
• Auto Setup Wizard (Otomatik Kurulum Sihirbazı) – Mevcut ulusunuzun düşmanlarını ve müttefiklerini otomatik olarak düşman veya dost olarak sınıflandırır.
• Start Manual Detection (Manuel Tespiti Başlat) – Birincil veri işleme motorunu (Komut Ayrıştırma) otomatik olarak etkinleştirir.
• Detection (Tespit) – Algılama için hangi veri işleme motorunun kullanılacağını seçmenizi sağlar.
• Auto Setup Target (Otomatik Kurulum Hedefi) – Kendi ulusunuz yerine müttefik bir ulusa yardıma giderseniz, bu seçenek Otomatik Kurulum Sihirbazı için hedef ulusu ayarlamanızı sağlar, böylece o ulusun düşmanlarını ve müttefiklerini tanımlayabilirsiniz.
• Veri Yönetimi – Yerel olarak saklanan towny istatistiklerini ve diplomatik verileri incelemenize, yedeklemenize veya sıfırlamanıza olanak tanır.
• Düşman Tespiti (Radar) – O tuşu ile açılıp kapatılabilir, actionbar üzerinde yakındaki oyuncu sayılarını gösterir.

---

🕵️ Veri Gizliliği

Veriler neden toplanıyor?

TownyUtils içinde, sunucular arasında en yüksek doğruluğa ve uyumluluğa sahip veri işleme motoru, Towny komutlarını ayrıştıran komut ayrıştırma motorudur. Bu motor, her Towny sunucusunun kullandığı farklı formatlar ve diller nedeniyle hatalı çalışabilir veya hiç çalışmayabilir. Bu nedenle, otomatik veya manuel olarak başlattığınız komut ayrıştırma motorundan gelen yalnızca /n online, /n allylist ve /n enemylist komutlarının çıktıları bize gönderilir. Bu, modun sunucular arası uyumluluğunu geliştirmemize yardımcı olur.

⚠️ GİZLİLİK GARANTİSİ

❌ Kişisel Veri Yok: Sohbet kayıtlarınıza, şifrelerinize veya özel mesajlarınıza ASLA erişilmez veya bunlar toplanmaz.

✅ Sadece Komut Çıktısı: Uyumluluk sağlamak amacıyla yalnızca towny komutlarının yapısı analiz edilir.

Veri paylaşımı tercihiniz ayarlardan istediğiniz zaman AÇIK/KAPALI (ON/OFF) olarak değiştirilebilir. Verileriniz 3. taraflarla paylaşılmaz. Veriler, geliştiriciye ait özel bir uç noktaya gönderilir. Uç nokta adresi herkese açık değildir. Farklı sunucu formatları nedeniyle, kısa bir yakalama penceresi içindeki mesajlar uyumluluk için iletilebilir.

---

📜 Yasal Uyarı & SSS

Tüm Hakları Saklıdır. Kaynak kodunun izinsiz kullanımı, tersine mühendislik işlemi veya yeniden dağıtımı yasaktır.

❓ Bu mod haksız avantaj sağlıyor mu?

Hayır.* Bu mod, istemci taraflı bir görsel iyileştirme aracıdır (QoL). *Sunucuya paket göndermez veya herhangi bir yetkisiz veri iletmez.

Bu mod haksız avantaj sağlamak için değil; aksine SiegeWar savaşlarında rekabeti ve keyfi en üst düzeye çıkarmak için tasarlanmıştır.

❓ İsim Etiketi Okuyucu (Nametag Reader) neden çalışmıyor?

İkincil veri işleme motoru olan İsim Etiketi Okuyucu, çok düşük bir başarı oranına sahiptir ve her sunucuda çalışması garanti edilmez. Bunun nedeni, isim etiketlerinin her sunucuda farklı şekilde yapılandırılması ve bazı durumlarda ulus isimlerini bile içermemesidir. Ancak çalıştığı sunucularda, her iki veri işleme motoru da başarılı bir şekilde çalışır, böylece diplomasi algılamasında ve güncellemelerinde gecikme yaşanmaz.

❓ Mod neden oynadığım sunucuda çalışmıyor?

Mod şimdiye kadar sadece Türk sunucularında test edildiğinden, farklı dil formatlarına sahip sunucularda çalışacağı garanti edilmez. Genel olarak birincil veri motoru, test ettiğim tüm Türk sunucularında başarılı bir şekilde çalışmıştır. Aynı şekilde, EarthMC gibi yabancı jeopolitik sunucularda da çalışmıştır. Ancak, her yabancı sunucuda çalışacağının garantisi yoktur.