# 我的维度

[English](README.md) | 简体中文

适用于 Minecraft 1.20.1 / Forge 的心境维度模组，添加裂罅、五种心境、双向心境传送门，以及可选的机械动力列车兼容。

## 环境与依赖

- Minecraft 1.20.1。
- Forge 47.x（项目开发配置为 47.4.0）。
- 机械动力（Create）不是必需依赖；未安装时不影响模组的其他功能。
- 明确支持 Minecraft 1.20.1 上的机械动力 0.5.1 与 6.x；检测到受支持版本时会自动启用列车传送门兼容。

## 主要内容

### 裂罅

- 手持裂罅时，按住 Shift 并右键打开动作轮盘。
- 在轮盘中选择动作后，普通右键执行当前动作。
- 可前往私有或共享心境、传送生物、设置心境锚点，以及访问已获授权的其他玩家心境。
- 使用同一把裂罅再次离开所选心境时，会返回这把裂罅记录的出发点。
- “设置锚点”只能在心境内执行，并且只决定之后使用裂罅传送生物时的落点，不影响玩家或传送门的落点。
- 复制共享心境内容的操作仅限创造模式玩家，并会覆盖私有心境中当前坐标附近 `3×3` 区块的方块，操作前请确认目标区域。

### 心境维度

| 心境 | 地形概述 |
| --- | --- |
| 空灵心境 | 超平坦维度：60 层石头、3 层泥土、3 层石英块。 |
| 镜之心境 | 使用与主世界相同的地形生成配置和世界种子。 |
| 水之心境 | 超平坦水域：20 层石头、5 层砂砾、50 层水。 |
| 自然心境 | 草原超平坦：50 层石头、9 层泥土、1 层草方块，并启用自然特征。 |
| 翱翔心境 | 由多种主世界生态组成的大型悬浮岛屿。 |

心境维度内不会自然生成生物。处于心境中的玩家不能被其他玩家通过 `/tp` 或 `/teleport` 强制传送。

### 心境传送门

心境传送门可在主世界和目标心境之间双向通行。门面使用紫色、品红色和少量青色粒子构成动态视差效果，进入传送门时的屏幕过渡也会继续流动和闪烁。

1. 在主世界竖直搭建一个 `5×6` 的心境门框外框，内部留出 `3×4` 空间。
2. 手持裂罅，通过动作轮盘选择一个“前往”类心境目标，或已获授权的其他玩家心境。传送生物、复制和设置锚点动作不能用于绑定传送门。
3. 使用裂罅右键任意一个心境门框方块以激活传送门。
4. 模组会在目标心境的安全位置自动生成配对传送门。
5. 玩家连续接触门面约 2 秒后完成传送；目标端可以原路返回主世界，传送后约有 4 秒冷却。

门框示意如下，其中 `F` 表示心境门框，`.` 表示内部空间：

```text
F F F F F
F . . . F
F . . . F
F . . . F
F . . . F
F F F F F
```

一座主世界入口共需要 18 个心境门框。传送门的创建者可以重新选择裂罅目标并再次右键门框来更新连接；创造模式玩家不受所有者限制。门面只会自动传送玩家，普通生物需要通过裂罅的“传送生物”动作移动。

### 机械动力列车兼容

安装受支持版本的机械动力后，需要在两个传送门端点都铺设铁轨，并让铁轨沿垂直于门面的方向紧邻门面接入。门面沿 X 轴展开时铁轨沿 Z 轴接入；门面沿 Z 轴展开时铁轨沿 X 轴接入。配对传送门会自动生成，但目标端铁轨不会自动生成。

完成两端铺轨后，列车即可像穿越下界传送门一样在主世界与心境之间双向通行。

兼容层会在检测到机械动力时自动注册，同时支持 Minecraft 1.20.1 上机械动力 0.5.1 与 6.x 使用的传送门轨道 API。模组没有对机械动力类进行静态引用，因此未安装机械动力时仍可正常启动和游玩。

## 合成表

### 裂罅

| 左 | 中 | 右 |
| --- | --- | --- |
| 玻璃 | 末影珍珠 | 玻璃 |
| 末影珍珠 | 时钟 | 末影珍珠 |
| 玻璃 | 末影珍珠 | 玻璃 |

- 材料：玻璃 ×4、末影珍珠 ×4、时钟 ×1。
- 产出：裂罅 ×1。
- 数据配方：[rift.json](src/main/resources/data/mydimension/recipes/rift.json)。

### 心境门框

| 左 | 中 | 右 |
| --- | --- | --- |
| 紫水晶碎片 | 下界石英 | 紫水晶碎片 |
| 下界石英 | 哭泣的黑曜石 | 下界石英 |
| 紫水晶碎片 | 下界石英 | 紫水晶碎片 |

- 材料：紫水晶碎片 ×4、下界石英 ×4、哭泣的黑曜石 ×1。
- 产出：心境门框 ×6。
- 数据配方：[mind_portal_frame.json](src/main/resources/data/mydimension/recipes/mind_portal_frame.json)。

完整搭建一座 `5×6` 传送门外框需要合成 3 次，共消耗紫水晶碎片 ×12、下界石英 ×12、哭泣的黑曜石 ×3，正好得到 18 个心境门框。心境传送门方块本身没有独立合成配方，而是在激活门框时自动生成。

## 筑境权杖与共鸣供材锚

筑境权杖可在任意维度进行连片铺层、拆层和蓝图施工；主手持有时方块交互距离按服务端配置提升（默认 64 格），但不会增加实体攻击距离。铺层的八邻域遍历只沿准星命中方向上真正可见的连续表面扩展，被地面、背板或其他完整方块遮住的地下部分不会再被预览或施工。`Shift+中键` 打开五页工具菜单，中键切换建造/拆除，`Ctrl+右键` 选择蓝图两端点，`Ctrl+Z`/`Ctrl+Y` 撤销或重做。箱子、按钮、供材锚及其他可交互方块会优先接收普通右键且不显示表面预览；按住 `Shift` 才会显示预览并由右键执行权杖施工。按住 `Ctrl` 时蓝框实时显示候选点；同一次按住期间滚动滚轮后会切换为空气选点，滚轮调整沿视线的距离，松开 `Ctrl` 即重置。部署蓝图时也可用同样方式指定空中锚点。全部快捷操作在菜单中也有入口。

- 建造按“绑定锚点 → 主背包 → 快捷栏 → 副手”取材；材料不足的位置保留黄色虚影，右键聚焦任一虚影继续补齐。准星射线进入黄色方格或蓝色选区/部署框的边线与内部体积都会取得唯一焦点并加粗；相连缺料格按 26 邻接视为一组并整体加粗，焦点粗框宽度以约 160 毫秒平滑过渡到普通框的四倍。部署框优先，其余对象按入射距离选择最近者；左键只取消当前焦点，取消部署不会清除源选区。普通建造预览仅显示绿色框，不渲染具体方块；黄色缺料与蓝图投影使用更实的半透明模型，并通过轻微内缩避免相邻投影面共面闪烁。大型预览按 16³ 分区缓存实体 QUADS 线框和投影模型，六面蓝紫裂罅波纹只用于黄色缺料投影；预览距离至少 160 格并随客户端渲染距离提高到最多 512 格，128 格外自动保留完整框架与缺料波纹 LOD，避免近中距离缺块及大型蓝图瞬时烘焙卡顿。
- 手动铺层/拆层在一次交互中立即执行本次设定上限，不再拆成跨 tick 的施工队列。作业页提供每把权杖独立的“历史记录”开关，默认关闭；关闭时不会创建撤销事务、方块实体前后镜像或物资账，从而避开批量施工最重的序列化开销，此时新操作不可撤销/重做。开启后才保留完整事务语义。入口仍会合并拒绝同一时刻的重复快速点击，避免重复射线、BFS 与供材扫描；蓝图自动施工继续使用自身的队列与建造上限。
- 拆除只有在副手工具类型和等级均合格时才保留正常掉落；每个成功拆除的方块消耗一次工具耐久，不生成经验。副手为空或工具类型不匹配时直接无粒子删除，不走原版 `2001` 破坏特效，也不创建掉落列表。每次批量操作只播放一个代表方块音效：建造使用该方块的放置音效，拆除使用拆前方块的破坏音效。
- 共鸣供材锚潜行贴附在容器面上使用。它优先访问目标面的 Forge 物品 Capability，并兼容 `WorldlyContainer`、普通 `Container` 和可配置的无侧面 Capability 回退；普通非容器表面会拒绝放置且不扣物品，容器消失或第三方旁路产生非法锚时会正常掉落并保留 UUID/ACL。跨区块重验使用目标区块反向索引唤醒，不扫描方块、不强制加载区块也不常驻 tick。锚点默认私有，可设置公开或白名单。主手持权杖时，只为当前这把权杖有序绑定、且位于当前维度的供材锚绘制紫色方框；客户端用权杖绑定 UUID 与服务端轻量索引快照求交，不扫描附近区块。换物品、换权杖、解绑、换维度或退出世界都会立即清理或重算缓存。
- 蓝图保存在客户端全局目录 `<游戏目录>/mydimension/blueprints/`，文件扩展名为 `.mindbp`，可跨存档和服务器导入、导出。复制与部署不再限制单轴长度、选区体积或非空气方块数；源区块仍须已加载，世界建造边界及编码传输/内存分配安全预算仍然生效。自动施工每 tick 使用权杖当前“建造上限”作为处理预算；已加载目标跨区块合并成一次供材扫描与历史提交，未加载目标按区块稳定分组并临时租赁，避免以旧的 64 格节流或在区块间逐行往返。服务器会重新验证世界边界、权限、材料、目标方块及完整方块实体 NBT。
- 按住 `Alt` 会立即显示裂罅风格的暗紫径向轮盘；十项操作全部使用独立图标（翻转轴、旋转、偏移、重置、复制选区和保存），选中扇区使用青紫辉光，中央只放大当前图标，并在轮盘外显示当前动作提示。松开后按原状态机关闭或确认调整。完整源选区存在时始终保留复制与保存图标；取消移动中的复制预览后，可直接用“复制选区”从保留的蓝色源选区重新生成预览。服务端选区不再按空闲时间过期，只在重新框选、明确取消、换权杖/维度、退出或停服时清理。保存弹窗将方块状态策略独占第一行、保存与取消并排放在第二行；保存后在同一弹窗等待服务端捕获并直接写入本地蓝图库，不再跳转到第二个保存界面。
- 服务端配置位于 `[builder]`；`enabled=false` 会停用配方、创造栏入口、增距、施工、绑定、远程容器访问和临时区块加载，但不会删除物品、NBT、历史或客户端蓝图库。
- 权杖与供材锚均使用裂罅风格的原生 3D 模型。权杖采用黑灰虚空石、紫蓝裂晶、扭曲杖身和断裂晶簇，不再使用黄铜、齿轮或扳手机械造型；物品栏以约 45° 斜向展示，第一人称模型缩小并右移以保留视野。模式切换只替换悬浮核心的青蓝/紫蓝反向漩涡动画，本体几何和材质不会整体刷新。供材锚的物品视图为 3D 侧视图，世界模型使用非遮挡几何，避免内缩模型裁掉相邻方块表面。

默认合成表：

| 筑境权杖 | 中 | 右 |
| --- | --- | --- |
| 回响碎片 | 下界之星 | 回响碎片 |
| 下界合金锭 | 裂罅 | 下界合金锭 |
| 哭泣的黑曜石 | 烈焰棒 | 哭泣的黑曜石 |

| 共鸣供材锚 | 中 | 右 |
| --- | --- | --- |
| 回响碎片 | 末影之眼 | 回响碎片 |
| 漏斗 | 末影箱 | 漏斗 |
| 心境门框 | 磁石 | 心境门框 |

模组提供 `mydimension:construction_protected` 与 `mydimension:transaction_unsafe` 两个数据包标签。第三方机器若会修改外部网络、全局 `SavedData`、异步任务或自定义实体，应通过兼容适配器或 `transaction_unsafe` 标签排除；Forge 没有能够通用撤销这类模组外部副作用的接口。

## 构建

```powershell
.\gradlew.bat build
```

构建完成后的 jar 位于 `build/libs/`：

- `mydimension-<版本>.jar`：完整版本，包含私有心境、共享心境、组队入口与复制功能。
- `mydimension-<版本>-no-private.jar`：仅保留共享心境，不包含私有心境、组队入口和复制共享心境功能。