DHZ_TravelersTitles（Fabric 1.20.1）

基于 区域触发 的“旅行者标题”模组：用指令创建标题对象，再把一个或多个 3D AABB 区域绑定到某个标题 ID。当玩家进入该标题 ID 的任意区域时，在客户端以 Travelers-Titles 同款 HUD 标题 UI 显示。

---

功能概览

• 标题对象管理
  • 创建/更新标题（显示名 + 可选副标题）
  • 删除标题 ID（仅删除标题对象，不删区域）
• 区域（Region）管理
  • 添加 3D AABB 区域到指定标题 ID（支持同 ID 多区域）
  • 删除单个 regionID
  • 进入方向限制（可选）：仅从指定面进入才触发
• 进入触发逻辑
  • 玩家进入区域时触发显示
  • 同一个标题 ID 的多个区域无缝跨越时不会重复触发
• 查看/列出
  • 查看当前位置命中的所有 region 详情（info）
  • 列出所有标题或某标题下所有区域（list）
• 安全删除
  • 所有删除操作需要二次确认（30 秒有效）
• TAB 补全
  • addregion 的 entry_direction 支持方向词补全（可多方向，自动避免重复）
• 数据存储
  • 所有标题/区域/客户端 UI 参数存储在 JSON 配置文件中，保证可读性
• UI（同款 Travelers-Titles）
  • 服务端只负责“何时触发”
  • 客户端通过自定义网络包接收并播放 HUD 标题动画（淡入/停留/淡出、缩放、背景块混色、可配置）

---

指令（/travelerstitles）

默认需要 OP 权限（permission level 2）。

创建/更新标题对象

/travelerstitles create <ID> <displayname> [subtitle]

• ID：标题 ID（建议字母数字下划线；实现允许 - :）
• displayname：显示标题（建议带空格时用引号）
• subtitle：可选副标题（贪婪字符串）

示例：

/travelerstitles create A02 "东门" "欢迎来到东门区域"

添加区域（3D AABB）

/travelerstitles addregion <ID> <pos1> <pos2> [regionID] [entry_direction]

• pos1/pos2：方块坐标（如 47 75 15 或 ~ ~ ~）
• regionID：可选；若留空则自动生成。要求全局唯一
• entry_direction：可选；仅从指定方向进入才触发
  • 支持：north,south,west,east,up,down
  • 分隔符：, 或 | 或空格
  • TAB 补全：输入方向/多方向时可补全并避免重复

示例（只允许从东侧进入才触发）：

/travelerstitles addregion A02 47 75 15 56 69 21 east_gate east

删除标题 ID（保留区域）

/travelerstitles deleteID <ID>
/travelerstitles delete confirm

• 删除 title ID 对象，但保留所有 regions（regionID 不会被删）
• 必须在 30 秒内执行确认

删除区域（regionID）

/travelerstitles deleteregion <regionID>
/travelerstitles delete confirm

删除确认

/travelerstitles delete confirm

查看当前位置区域信息

/travelerstitles info

• 输出当前位置命中的 所有 region 信息（可能同时命中多个）

列表

/travelerstitles list
/travelerstitles list <ID>

• list：列出所有标题 ID 与 displayName
• list ：列出该标题 ID 下所有 region（regionID、维度、AABB、entry_direction）

---

进入触发与进入方向（entry_direction）规则

触发条件（同 ID 不重复）

• 每 tick 检测玩家是否位于任意区域内
• 若玩家处于某标题 ID 的任一区域内，则认为“处于该标题 ID”
• 只有当玩家从“上一刻不处于该标题 ID”变为“这一刻处于该标题 ID”时，才触发显示
• 因此：同一个 ID 绑定多个 AABB 且无缝跨越时，不会重复显示标题

进入方向判定（线段刺穿指定面）

当配置了 entry_direction 时，仅在满足以下条件才触发：

• 上一刻位置在盒子外，且这一刻位置在盒子内
• 用“上一刻位置 → 这一刻位置”画线段
• 若线段 刺穿区域立方体的指定面（如 east 面为 (x=maxX+1) 的平面），且交点落在该面矩形范围内，则判定为从该方向进入

这套判定可避免取整/跳步造成的方向误判。

---

UI（Travelers-Titles 同款 HUD 标题）

工作方式

• 服务端：决定“何时触发显示”（区域进入逻辑）
• 客户端：收到自定义网络包后，用 HUD 渲染播放标题动画

同款效果细节

• 淡入/停留/淡出计时
• 居中/缩放
• 阴影开关
• 背景块：使用“文字背景色 × 文本颜色”的 ARGB 逐通道乘法混色（同款）

---

配置文件

路径

config/dhz_travelerstitles.json

结构说明（核心字段）

• ui：客户端 HUD 标题 UI 参数（同款可配置全套）
• titles：标题对象表（key 为标题 ID）
• regions：区域表（key 为 regionID）

ui（客户端 UI 可配置项）

这些字段会在 客户端启动时读取并应用（多人环境下，每个玩家用自己的本地配置）。

• enabled：是否启用 UI
• textFadeInTime / textDisplayTime / textFadeOutTime：淡入/停留/淡出（tick）
• textColor：标题颜色（16 进制 RGB 字符串，如 "ffffff"）
• textSize：标题缩放（如 2.1）
• renderShadow：是否阴影
• textXOffset / textYOffset：文字偏移
• centerText：是否居中
• subtitleEnabled / subtitleTextSize / subtitleTextYOffset / subtitleBackdropYOffset：副标题相关
• backdropEnabled / backdropYOffset：背景块相关

titles

每个标题对象：

• id
• displayName
• subtitle（可选）

regions

每个区域对象：

• regionId
• titleId
• dimension（如 "minecraft:overworld"）
• minX/minY/minZ 与 maxX/maxY/maxZ
• entryDirections：进入方向列表（空表示任意方向）

---

开发/构建

在项目根目录执行：

./gradlew build

---

参考

本项目的 HUD 标题 UI 参考并对齐了 Travelers-Titles-1.20 的渲染实现细节（淡入淡出、缩放、背景块混色等）。

==================================================

DHZ_TravelersTitles (Fabric 1.20.1)

A region‑triggered "Travelers Titles" mod: create title objects via commands, then bind one or more 3D AABB regions to a title ID. When a player enters any region of that title ID, the Travelers‑Titles style HUD title UI is displayed on the client.

---

Feature Overview

• Title Object Management
  • Create/update titles (display name + optional subtitle)
  • Delete a title ID (only the title object is removed, regions stay)
• Region Management
  • Add a 3D AABB region to a specified title ID (multiple regions per ID supported)
  • Delete a single regionID
  • Entry‑direction restriction (optional): trigger only when entering from a specified face
• Entry‑Trigger Logic
  • Title is shown when a player enters a region
  • Seamless crossing between multiple regions of the same title ID does NOT re‑trigger
• View / Listing
  • Show details of all regions hit at the current position (info)
  • List all titles or all regions under a specific title (list)
• Safe Deletion
  • All delete operations require a second confirmation (valid for 30 seconds)
• TAB Completion
  • addregion’s entry_direction supports directional word completion (multiple directions allowed, duplicates automatically avoided)
• Data Storage
  • All titles/regions/client UI parameters are stored in a JSON configuration file, ensuring readability
• UI (Same as Travelers‑Titles)
  • Server only decides when to trigger
  • Client receives a custom network packet and plays the HUD title animation (fade‑in/stay/fade‑out, scaling, backdrop color blending, configurable)

---

Commands (/travelerstitles)

Requires OP permission by default (permission level 2).

Create / Update a Title Object

/travelerstitles create <ID> <displayname> [subtitle]

• ID: Title ID (alphanumeric + underscore recommended; implementation also allows - and :)
• displayname: Display title (use quotes if it contains spaces)
• subtitle: Optional subtitle (greedy string)

Example:

/travelerstitles create A02 "East Gate" "Welcome to the East Gate area"

Add Region (3D AABB)

/travelerstitles addregion <ID> <pos1> <pos2> [regionID] [entry_direction]

• pos1/pos2: Block coordinates (e.g., 47 75 15 or ~ ~ ~)
• regionID: Optional; if omitted, an ID is auto‑generated. Must be globally unique.
• entry_direction: Optional; trigger only when entering from the specified face(s)
  • Supported: north, south, west, east, up, down
  • Separators: ,, |, or space
  • TAB completion: directional words can be completed and duplicates are avoided

Example (trigger only when entering from the east side):

/travelerstitles addregion A02 47 75 15 56 69 21 east_gate east

Delete a Title ID (Regions Remain)

/travelerstitles deleteID <ID>
/travelerstitles delete confirm

• Deletes the title ID object, but keeps all its regions (regionIDs are not removed)
• Must be confirmed within 30 seconds

Delete a Region (regionID)

/travelerstitles deleteregion <regionID>
/travelerstitles delete confirm

Confirm Deletion

/travelerstitles delete confirm

Show Region Information at Current Position

/travelerstitles info

• Outputs details of all regions that the current position hits (may hit multiple simultaneously)

Listing

/travelerstitles list
/travelerstitles list <ID>

• list: Lists all title IDs and their displayNames
• list : Lists all regions under that title ID (regionID, dimension, AABB, entry_direction)

---

Entry Trigger & Entry‑Direction Rules

Trigger Condition (No Duplicates for Same ID)

• Every tick checks whether the player is inside any region
• If the player is inside any region of a title ID, they are considered "inside that title ID"
• The title is shown only when the player changes from "not inside that title ID last tick" to "inside that title ID this tick"
• Therefore: Seamless crossing between multiple AABBs bound to the same ID will NOT re‑display the title

Entry‑Direction Detection (Segment Piercing a Specified Face)

When entry_direction is configured, triggering occurs only if:

• Last‑tick position was outside the box, and this‑tick position is inside the box
• Draw a segment from "last‑tick position → this‑tick position"
• If the segment pierces the specified face of the region cube (e.g., the east face is the plane (x = maxX + 1)) and the intersection point lies within the rectangle of that face, the entry is judged to be from that direction

This detection avoids misjudgments caused by rounding/step‑jumping.

---

UI (Travelers‑Titles Style HUD Title)

How It Works

• Server: Decides when to trigger (region‑entry logic)
• Client: Receives a custom network packet and renders the title animation via HUD

Same‑Effect Details

• Fade‑in / stay / fade‑out timing
• Centering / scaling
• Shadow toggle
• Backdrop block: uses ARGB per‑channel multiplication blending of "text‑background color × text color" (same as the original)

---

Configuration File

Path

config/dhz_travelerstitles.json

Structure Overview (Key Fields)

• ui: Client HUD title UI parameters (full set configurable, same as original)
• titles: Title object table (key is title ID)
• regions: Region table (key is regionID)

ui (Client‑Side UI Configurable Items)

These fields are read and applied when the client starts (in multiplayer, each player uses their own local configuration).

• enabled: Whether UI is enabled
• textFadeInTime / textDisplayTime / textFadeOutTime: Fade‑in / stay / fade‑out (ticks)
• textColor: Title color (hex RGB string, e.g., "ffffff")
• textSize: Title scale (e.g., 2.1)
• renderShadow: Whether to render shadow
• textXOffset / textYOffset: Text offset
• centerText: Whether to center text
• subtitleEnabled / subtitleTextSize / subtitleTextYOffset / subtitleBackdropYOffset: Subtitle‑related
• backdropEnabled / backdropYOffset: Backdrop‑related

titles

Each title object:

• id
• displayName
• subtitle (optional)

regions

Each region object:

• regionId
• titleId
• dimension (e.g., "minecraft:overworld")
• minX/minY/minZ and maxX/maxY/maxZ
• entryDirections: List of entry directions (empty means any direction)

---

Development / Building

In the project root directory, run:

./gradlew build

---

References

The HUD title UI of this project references and aligns with the rendering implementation details of Travelers‑Titles‑1.20 (fade‑in/out, scaling, backdrop color blending, etc.).