# 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 [subtitle] ``` - **ID**：标题 ID（建议字母数字下划线；实现允许 `-` `:`） - **displayname**：显示标题（建议带空格时用引号） - **subtitle**：可选副标题（贪婪字符串）示例： ``` /travelerstitles create A02 "东门" "欢迎来到东门区域" ``` ### 添加区域（3D AABB） ``` /travelerstitles addregion [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 /travelerstitles delete confirm ``` - 删除 **title ID 对象**，但保留所有 `regions`（regionID 不会被删） - 必须在 30 秒内执行确认 ### 删除区域（regionID） ``` /travelerstitles deleteregion /travelerstitles delete confirm ``` ### 删除确认 ``` /travelerstitles delete confirm ``` ### 查看当前位置区域信息 ``` /travelerstitles info ``` - 输出当前位置命中的 **所有 region** 信息（可能同时命中多个） ### 列表 ``` /travelerstitles list /travelerstitles list ``` - **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 [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 [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 /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 /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 ``` - **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.).

Regional Title（DHZ_TravelersTitles）

External resources

Project members

Technical information