Regional Title（DHZ_TravelersTitles）

DHZ_TravelersTitles（Fabric 1.20.1）

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

---

功能概览

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

---

指令（/travelerstitles）

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

创建/更新标题对象

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

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

示例：

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

添加区域（3D AABB）

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

- TAB 补全：方块坐标（如 `47 75 15` 或 `~ ~ ~`） - TAB 补全：可选；若留空则自动生成。要求全局唯一 - TAB 补全：可选；仅从指定方向进入才触发 - 支持：`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>：列出所有标题 ID 与 displayName - list <ID>：列出该标题 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 ```

结构说明（核心字段）

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

ui（客户端 UI 可配置项）

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

- backdropEnabled / backdropYOffset：是否启用 UI - backdropEnabled / backdropYOffset：淡入/停留/淡出（tick） - backdropEnabled / backdropYOffset：标题颜色（16 进制 RGB 字符串，如 `"ffffff"`） - backdropEnabled / backdropYOffset：标题缩放（如 `2.1`） - backdropEnabled / backdropYOffset：是否阴影 - backdropEnabled / backdropYOffset：文字偏移 - backdropEnabled / backdropYOffset：是否居中 - backdropEnabled / backdropYOffset：副标题相关 - 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 Travelers‑Titles style HUD title UI "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

- when to trigger - Create/update titles (display name + optional subtitle) - Delete a title ID (only the title object is removed, regions stay) - when to trigger - 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 - when to trigger - Title is shown when a player enters a region - when to trigger - when to trigger - Show details of all regions hit at the current position (`info`) - List all titles or all regions under a specific title (`list`) - when to trigger - All delete operations require a second confirmation (valid for 30 seconds) - when to trigger - `addregion`’s `entry_direction` supports directional word completion (multiple directions allowed, duplicates automatically avoided) - when to trigger - All titles/regions/client UI parameters are stored in a JSON configuration file, ensuring readability - when to trigger - 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] ```

- subtitle: Title ID (alphanumeric + underscore recommended; implementation also allows `-` and `:`) - subtitle: 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] ```

- TAB completion: Block coordinates (e.g., `47 75 15` or `~ ~ ~`) - TAB completion: Optional; if omitted, an ID is auto‑generated. Must be globally unique. - TAB completion: 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 <ID>: Lists all title IDs and their displayNames - list <ID>: 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

- Client: Decides Client (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)

- regions: Client HUD title UI parameters (full set configurable, same as original) - regions: 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).

- backdropEnabled / backdropYOffset: Whether UI is enabled - backdropEnabled / backdropYOffset: Fade‑in / stay / fade‑out (ticks) - backdropEnabled / backdropYOffset: Title color (hex RGB string, e.g., `"ffffff"`) - backdropEnabled / backdropYOffset: Title scale (e.g., `2.1`) - backdropEnabled / backdropYOffset: Whether to render shadow - backdropEnabled / backdropYOffset: Text offset - backdropEnabled / backdropYOffset: Whether to center text - backdropEnabled / backdropYOffset: 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.).