Ephemeral Traces · 浮生迹

Version 1.2 | Platform Minecraft 1.20.1 · Forge 47.x | Author 陨莫 (@Dzwmhyk) | Mod ID ephemeral_traces

English Version

📖 Introduction

Ephemeral Traces is a chronicle that quietly tallies your deaths, your kills, and your time alive.
Every fall is a footprint left in the sand; every battle, an echo of your will; every second, a stroke in the canvas of your journey.
This mod logs your death count, hostile kills, and total survival time, then presents them in a clean leaderboard – for you to compare, reflect, and remember.
Because numbers are never just numbers; they are the traces you leave behind in a world that remembers.

✨ Core Features

• Three tracked stats: Deaths, hostile kills, and survival time (resets after each death).
• Weighted leaderboard – death (50%) + survival (30%) + kills (20%), normalised and combined into a single score.
• Top‑3 titles with coloured prefixes – gold / silver / bronze – displayed on nameplates, in chat, and in the tab list; prestige visible everywhere.
• Smart hostile detection – not just vanilla monsters; any mob currently attacking you or your pet counts as hostile (modpack‑friendly).
• Pet credit – kills made by your tamed wolves, cats, parrots (and modded pets) are credited to you, even when you are offline.
• World‑persistent storage – all data saved per world, survives game restarts.
• Tab Leaderboard UI – view the leaderboard directly in the player list (Tab screen).
• Bottom-left Rank HUD – real-time display of your current rank and key stats in the bottom-left corner.
• H key toggle – press H to show/hide the bottom-left rank HUD.
• Ephemeral Journal – a book-style item. Right-click to open a vanilla-style book GUI showing recent player join/leave records.
• Recent player activity log – records player name, timestamp, and whether they entered or left the server. Stored per world, up to 100 entries.
• Pagination – the journal shows 10 records per page, with previous/next page navigation.
• Conflict-friendly recipe – Book + Paper + Feather, designed to avoid common vanilla recipe conflicts.
• No chat spam – join/leave records are shown in a clean book interface instead of flooding the chat.
• Compatible with existing systems – the journal is an independent log feature and does not affect leaderboard stats, titles, kill/death/survival tracking, Tab UI, or HUD.

🎮 How to Use

Commands (type in chat, available to all players):

Shortcuts & Items:

Scoring formula: Score = 0.5 × (1 - myDeaths / maxDeaths) + 0.3 × (mySurvival / maxSurvival) + 0.2 × (myKills / maxKills)

The result is multiplied by 100 and shown as a percentage with one decimal place.
Fewer deaths, longer survival, more kills → higher rank.

Top‑3 titles:

Titles refresh every 5 seconds, and also update immediately on login / death – your rank changes in real‑time.

What counts as a "hostile kill":

• ✅ Killed by you directly, with a bow, or thrown weapons.
• ✅ Your pet (wolf, cat, parrot, or modded pets) kills a hostile mob – credit goes to you.
• ✅ Hostile mobs = vanilla monsters + any creature currently attacking you or your pet.
• ❌ PvP kills, passive mobs (cows, sheep, etc.), or pet kills on passive mobs do not count.

Survival time: Only accumulates while alive (spectator/dead pauses), resets to zero upon death, and restarts when you respawn. Displayed as X days X hours X min X sec on the leaderboard.

📦 Installation

1. Install Minecraft 1.20.1 and Forge 47.x.
2. Put the Ephemeral Traces JAR into your .minecraft/mods folder.
3. Launch the game and type /etraces to see the leaderboard.

⚙️ Notes

• Core stat tracking, titles, and the join/leave log work server-side; the Tab leaderboard UI and bottom-left rank HUD require the mod on the client.
• The Ephemeral Journal opens a vanilla-style book GUI, so clients without the mod can still read it.
• Titles use vanilla scoreboard teams, so clients without the mod can still see them.
• Data is stored per world – different saves do not interfere.

中文版本

📖 简介

浮生迹，是一册为你记录生死、杀戮与时光的编年史。
每一次倒下，都是尘世的一次驻足；每一场厮杀，都是存在的一声回响；每一刻流逝，都是旅途的一行注脚。
模组默默追踪你的死亡次数、击杀敌数、存活时长，并将这些数字凝成一座可随时翻阅的排行榜——既照见自己的征途，也望见他人的轨迹。
让数据不只是数据，而是你在方块世界中，活过的证据。

✨ 核心功能

• 三项数据追踪：死亡次数、击杀敌对生物数、生存时间（死亡后重置）。
• 加权排行榜：死亡 50% + 生存 30% + 杀敌 20%，归一化后综合评分排名。
• 前三名称号与配色：金 / 银 / 铜，称号常驻显示在头顶名字牌、聊天栏名字前、Tab 玩家列表——无论在哪都是身份的象征。
• 灵活敌对判定：兼容整合包，不只认原版怪物，任何正在攻击玩家或玩家宠物的生物都算数。
• 宠物记功：你驯服的狼、猫、鹦鹉（及模组宠物）击杀敌对生物，功劳记在主人名下，主人离线也照记。
• 随世界持久化：数据存进世界存档，重开游戏不丢失。
• Tab 排行榜 UI：在玩家列表（Tab 界面）中直接查看排行榜。
• 左下角排名 HUD：屏幕左下角实时显示自己的当前排名与关键数据。
• H 键快速开关：按 H 随时显示/隐藏左下角排名 HUD。
• 浮生手札：新增一本原版书本风格的物品，右键打开书页界面，查看最近玩家进入 / 离开记录。
• 最近进出记录：记录玩家名称、时间戳、进入或离开服务器，保存在世界存档中，最多 100 条。
• 分页浏览：每页 10 条，支持上一页 / 下一页翻看更早历史。
• 安全合成配方：书 + 纸 + 羽毛，避免与大量原版常见配方冲突。
• 不再刷屏聊天栏：记录以书本界面展示，体验更自然、更符合原版风格。
• 兼容现有系统：手札是独立的日志附加功能，不影响排行榜统计、称号系统、杀敌 / 死亡 / 生存记录、Tab UI 与 HUD。

🎮 使用方法

指令（聊天栏输入，所有玩家可用）：

快捷键与物品：

计分规则： 评分 = 0.5 × (1 - 我的死亡 / 全场最多死亡) + 0.3 × (我的生存 / 全场最长生存) + 0.2 × (我的击杀 / 全场最多击杀)

以百分制显示（×100，保留 1 位小数）。死亡越少、生存越久、击杀越多 → 排名越高。

前三名称号：

称号每 5 秒自动刷新，并在玩家 登录 / 死亡 时即时更新，名次变动会实时同步到头顶与聊天栏。

什么会被计入“击杀”：

• ✅ 你亲手 / 用弓箭 / 投掷武器击杀敌对生物
• ✅ 你的宠物（狼、猫、鹦鹉及模组宠物）击杀敌对生物 → 记给你
• ✅ 敌对生物 = 原版怪物 + 任何正在攻击玩家或玩家宠物的生物
• ❌ 击杀玩家（PvP）、击杀被动生物（牛、羊等）、宠物误杀被动生物

生存时间： 仅在存活状态下累加（旁观 / 死亡不计），死亡后清零、重生重新计时，排行榜中显示为「X天X小时X分X秒」。

📦 安装

1. 安装 Minecraft 1.20.1 与 Forge（47.x）。
2. 将 Ephemeral Traces 的 JAR 文件放入 .minecraft/mods 文件夹。
3. 启动游戏，输入 /etraces 即可查看排行榜。

⚙️ 说明

• 核心数据追踪、称号与进出记录为服务端逻辑；Tab 排行榜 UI 与左下角排名 HUD 需要客户端安装本模组才能显示。
• 浮生手札使用原版书本界面，未安装模组的客户端也能正常阅读。
• 称号借助原版计分板队伍前缀实现，未安装模组的客户端也能看到。
• 数据按世界独立存储，不同存档互不影响。

— 让每一次冒险都留下痕迹。Let every adventure leave its trace.