Skip to content

Commit a9ef23a

Browse files
phoenixlzxphoenixlzx
committed
Rewrite docs: focus on lock logic, setup, config, and admin/player usage; add Chinese README
1 parent 40dfad5 commit a9ef23a

File tree

2 files changed

+319
-18
lines changed

2 files changed

+319
-18
lines changed

‎README.md‎

Lines changed: 157 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -8,26 +8,165 @@
88
All versions can be found at [Nyaa CI server](https://ci.nyaacat.com/job/LockettePro/)
99
For the newest build on main branch, click [here](https://ci.nyaacat.com/job/LockettePro/job/main/lastSuccessfulBuild/)
1010

11-
### LockettePro - A much better Lockette plugin for Bukkit
11+
### Version history
12+
- 2.9.15 : Minecraft 1.21, downloadable from [github actions](https://github.com/NyaaCat/LockettePro/actions/workflows/autobuild.yml)
13+
- 2.9.x-1.15.1: Minecraft 1.15.1, since build 10
14+
- 2.9.x-1.14.4: Minecraft 1.14.4, until build 9
1215

13-
LockettePro is a block-protection plugin based on Lockette (https://github.com/Acru/Lockette), the code base is entirely re-written. It is 100% compatable with original Lockette, and the plugin behaviors are also 100% same.
16+
English documentation: `README.md`
17+
中文说明: `README.zh.md`
1418

15-
### LockettePro has a lot of enhancements compared to Lockette:
19+
## What LockettePro does
20+
LockettePro protects blocks by validating ownership and access before players, hoppers, mobs, explosions, and redstone can interact with them.
1621

17-
1. Much better codebase and performance, fixed a lot of issues and glitches.
18-
2. Real UUID support.
19-
3. All blocks can be set to lockable or not. You can even prevent players from locking a chest.
20-
4. Unlimited [Private], [More Users], [Timer:x] signs format.
21-
5. Alert messages are editable, and UTF-8 characters are supported.
22-
6. Lock expircy feature, locks can expire after a certain amount of time.
22+
It supports two lock models:
2323

24-
### Links
25-
Spigot release page: https://www.spigotmc.org/resources/lockettepro.20427/
26-
Bukkit release page: http://dev.bukkit.org/bukkit-plugins/lockettepro/
27-
MCBBS release page: http://www.mcbbs.net/thread-567962-1-1.html
28-
MC 1.6~1.7 Port: https://github.com/connection-lost/LockettePro/releases/tag/v1.9.4
24+
- Sign lock (classic Lockette behavior): a wall sign near the protected block defines owner/users/tags.
25+
- PDC lock (container-only): lock data is stored inside the container PersistentDataContainer (no visible sign required).
2926

30-
### Version history
31-
- 2.9.15 : Minecraft 1.21, downloadable from [github actions](https://github.com/NyaaCat/LockettePro/actions/workflows/autobuild.yml)
32-
- 2.9.x-1.15.1: Minecraft 1.15.1, since build 10
33-
- 2.9.x-1.14.4: Minecraft 1.14.4, until build 9
27+
Both models are available at the same time.
28+
29+
## Core runtime logic
30+
For containers (chest, barrel, hopper, furnace, etc.):
31+
32+
1. If LockettePro PDC lock data exists, LockettePro uses PDC permissions directly.
33+
2. If no PDC lock data exists, LockettePro falls back to sign scanning.
34+
3. Effective container lock state is mirrored to a configurable key (`locked-container-pdc-key`, default `lockettepro:locked_container`) for plugin/server integration.
35+
36+
For non-container lockables (for example doors or decorative lockables such as `DIAMOND_BLOCK`), protection remains sign-based.
37+
38+
This means:
39+
40+
- PDC locks are fast and do not require nearby signs.
41+
- Sign locks still work for every configured lockable, including non-container blocks.
42+
- Containers with PDC lock data skip sign lookup for permission checks.
43+
44+
## Installation (Admin)
45+
1. Download the plugin jar.
46+
2. Put it in `plugins/`.
47+
3. Start or restart the server.
48+
4. Edit `plugins/LockettePro/config.yml` as needed.
49+
5. Run `/lock reload` after changes.
50+
51+
Optional integrations (soft-depend):
52+
53+
- Vault
54+
- WorldGuard
55+
- ProtocolLib
56+
- CoreProtect
57+
58+
## Configuration guide (Admin)
59+
Main options in `config.yml`:
60+
61+
- `enable-quick-protect`: quick-lock mode (`true`, `false`, `sneak`).
62+
- `lockables`: what can be protected.
63+
- `lockables` supports both material names and block tags such as `minecraft:doors`.
64+
- Prefix with `-` in `lockables` to exclude a material/tag from the current set.
65+
- `block-item-transfer-in` / `block-item-transfer-out`: block hopper-like transfer into/out of locked containers.
66+
- `block-item-transfer-cooldown-ticks`: cooldown added to blocked hoppers to reduce retry spam.
67+
- `container-bypass-sign-tags`: tags (for example `[hopper]`) that make container transfer restrictions bypassable.
68+
- `everyone-signs`: tags that make access open to everyone (for example `[everyone]`).
69+
- `locked-container-pdc-key`: PDC key used as an external "effectively locked container" marker.
70+
- `permission-groups-file`: persistent file for permission groups (default `permission-groups.json`).
71+
- `permission-groups-autosave-seconds`: autosave interval for permission groups.
72+
73+
## Player usage
74+
### Sign lock workflow
75+
- Quick protect: right-click a lockable block with a sign item (if enabled by config).
76+
- Manual protect: place a wall sign with `[Private]` on line 1.
77+
- Add extra users/tags: use `[More Users]` sign.
78+
- Common tags: `[everyone]` (everyone can use), `[hopper]` (container transfer bypass tag).
79+
- Edit lock sign text: right-click a lock sign to select it, then run `/lock <1|2|3|4> <text>`.
80+
81+
### PDC lock workflow (container only)
82+
- `/lock on`
83+
Lock the targeted container and set yourself as owner.
84+
- If the container is currently sign-locked and you are owner, this creates PDC lock data and future access checks prefer PDC data.
85+
- Existing sign text is not auto-imported into PDC permissions.
86+
87+
- `/lock info`
88+
Show current owners, permission entries, and `locked_container` state of targeted container.
89+
90+
- `/lock rename <new name>`
91+
Rename targeted PDC-locked container (owner only). Supports color format such as `&#rrggbb`.
92+
93+
- `/lock permission <node>`
94+
Edit targeted container permissions (owner only).
95+
96+
Permission node format:
97+
98+
- `<mode>:<subject>`
99+
- modes: `xx` (owner), `rw` (read/write), `ro` (read-only), `--` (remove)
100+
- subjects: player UUID or player name (online names normalize to UUID), `[tag]`, `#entity`, or `[g:GroupName]`
101+
- tag examples: `[everyone]`, permission group tags, scoreboard team tags
102+
- entity example: `#hopper`
103+
104+
Examples:
105+
106+
- `xx:AdminPlayer`
107+
- `rw:FriendA`
108+
- `ro:[everyone]`
109+
- `rw:#hopper`
110+
- `rw:[g:BaseMembers]`
111+
- `--:FriendA`
112+
113+
### Permission clone tool
114+
- `/lock clone` gives a special item containing current container permissions (+ custom name).
115+
- Right-click another container with that item to copy permissions quickly.
116+
- Target rules: unlocked container (allowed), PDC-locked container (owner required), sign-locked container (owner required)
117+
118+
## Permission groups (Player-owned)
119+
Permission groups reduce long permission lists in PDC locks.
120+
121+
- Each player can own one group.
122+
- Group name must be unique server-wide.
123+
- Only the owner can edit/delete the group.
124+
- Group file is loaded on startup and autosaved periodically.
125+
126+
Commands:
127+
128+
- `/lock group create <groupName>`
129+
- `/lock group delete <groupName>`
130+
- `/lock group add <groupName> <subject>`
131+
- `/lock group remove <groupName> <subject>`
132+
- `/lock group info <groupName>`
133+
- `/lock group list`
134+
135+
Use group in container permission:
136+
137+
- `/lock permission rw:[g:<groupName>]`
138+
139+
## Permissions
140+
Common permission nodes:
141+
142+
- `lockettepro.command`: use `/lock` base command
143+
- `lockettepro.lock`: create sign locks / quick lock
144+
- `lockettepro.edit`: sign edit workflow (`/lock 1..4`)
145+
- `lockettepro.pdc.on`
146+
- `lockettepro.pdc.info`
147+
- `lockettepro.pdc.rename`
148+
- `lockettepro.pdc.permission`
149+
- `lockettepro.pdc.clone`
150+
- `lockettepro.pdc.group`
151+
- `lockettepro.pdc.*`: includes all PDC/group sub-permissions
152+
- `lockettepro.reload`: reload config
153+
- `lockettepro.version`: view plugin version
154+
155+
Additional admin/legacy nodes used by runtime checks:
156+
157+
- `lockettepro.lockothers`
158+
- `lockettepro.noexpire`
159+
- `lockettepro.admin.edit`
160+
- `lockettepro.edit.admin`
161+
- `lockettepro.admin.break`
162+
- `lockettepro.admin.use`
163+
- `lockettepro.admin.interfere`
164+
165+
For survival/RPG/adventure setups, explicitly grant PDC permissions only to roles that are allowed to create and manage virtual locks.
166+
167+
## Notes and compatibility
168+
- Quick-lock sign placement now fires placement event checks, so region/anti-grief plugins can block it consistently.
169+
- Blocked hopper transfers apply a cooldown to reduce repeated checks.
170+
- PDC lock currently applies to containers only.
171+
- Non-container lockables remain sign-only by design.
172+
- Sign lock and PDC lock can coexist in the same server; container access checks prefer PDC when present.

‎README.zh.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# LockettePro [![Build Status](https://ci.nyaacat.com/job/LockettePro/job/main/badge/icon?style=flat-square)](https://ci.nyaacat.com/job/LockettePro/job/main/)
2+
3+
> [!CAUTION]\
4+
> ***Minecraft 1.21 版本目前仍未完全测试。***
5+
> 如果你遇到问题，请提交 issue。谢谢。
6+
7+
所有构建可在 [Nyaa CI server](https://ci.nyaacat.com/job/LockettePro/) 下载。
8+
main 分支最新成功构建请点 [here](https://ci.nyaacat.com/job/LockettePro/job/main/lastSuccessfulBuild/)。
9+
10+
### Version history
11+
- 2.9.15 : Minecraft 1.21, downloadable from [github actions](https://github.com/NyaaCat/LockettePro/actions/workflows/autobuild.yml)
12+
- 2.9.x-1.15.1: Minecraft 1.15.1, since build 10
13+
- 2.9.x-1.14.4: Minecraft 1.14.4, until build 9
14+
15+
## 插件做什么
16+
LockettePro 用“权限校验 + 事件拦截”的方式保护方块，避免未授权玩家、漏斗、红石、生物、爆炸等破坏或访问被锁内容。
17+
18+
当前支持两套锁机制：
19+
20+
- 牌子锁：经典 Lockette 逻辑，权限写在方块旁边的牌子上。
21+
- PDC 锁（仅容器）：权限写入容器本体的 PersistentDataContainer，不需要外部牌子。
22+
23+
## 核心判定逻辑
24+
对于容器（箱子、木桶、熔炉、漏斗等）：
25+
26+
1. 如果存在 LockettePro 的 PDC 锁数据，优先使用 PDC 权限判定。
27+
2. 如果不存在 PDC 锁数据，回退到牌子锁判定。
28+
3. 有效锁状态会同步到 `locked-container-pdc-key`（默认 `lockettepro:locked_container`），便于与其他插件或服务端逻辑联动。
29+
30+
对于非容器可锁方块（例如门、`DIAMOND_BLOCK`）：
31+
32+
- 继续走牌子锁逻辑，不使用 PDC 锁。
33+
34+
## 安装（管理员）
35+
1. 下载插件 jar。
36+
2. 放入 `plugins/` 目录。
37+
3. 启动/重启服务器。
38+
4. 修改 `plugins/LockettePro/config.yml`。
39+
5. 配置修改后执行 `/lock reload`。
40+
41+
可选软依赖：
42+
43+
- Vault
44+
- WorldGuard
45+
- ProtocolLib
46+
- CoreProtect
47+
48+
## 配置重点（管理员）
49+
`config.yml` 常用项：
50+
51+
- `enable-quick-protect`：快捷上锁模式（`true`、`false`、`sneak`）。
52+
- `lockables`：可锁方块列表。
53+
- `lockables` 支持材质名与方块标签，如 `minecraft:doors`。
54+
- `lockables` 中前缀 `-` 可从当前集合里移除一个材质/标签。
55+
- `block-item-transfer-in` / `block-item-transfer-out`：是否阻止对锁容器的自动传输。
56+
- `block-item-transfer-cooldown-ticks`：阻止传输后给漏斗加冷却，减少无效重试。
57+
- `container-bypass-sign-tags`：容器传输绕过标签（如 `[hopper]`）。
58+
- `everyone-signs`：全员访问标签（如 `[everyone]`）。
59+
- `locked-container-pdc-key`：容器有效锁状态标记 key。
60+
- `permission-groups-file`：权限组持久化文件名（默认 `permission-groups.json`）。
61+
- `permission-groups-autosave-seconds`：权限组自动保存间隔。
62+
63+
## 玩家用法
64+
### 牌子锁
65+
- 快捷上锁：手持牌子右键可锁方块（取决于 `enable-quick-protect`）。
66+
- 手动上锁：在墙牌首行写 `[Private]`。
67+
- 添加额外权限：使用 `[More Users]` 牌子。
68+
- 常用标签：`[everyone]`（允许所有玩家访问）、`[hopper]`（允许容器自动传输绕过限制）。
69+
- 修改牌子文本：先右键选中锁牌，再执行 `/lock <1|2|3|4> <text>`。
70+
71+
### PDC 锁（仅容器）
72+
- `/lock on`
73+
给当前准星容器上锁，并把自己设为 owner。
74+
- 如果该容器原本是牌子锁且你是 owner，后续会优先按 PDC 权限判定。
75+
- 现有牌子文本不会自动导入 PDC 权限，需要用 `/lock permission` 或 `/lock clone` 重新整理。
76+
77+
- `/lock info`
78+
查看当前容器 owner、权限列表、`locked_container` 状态。
79+
80+
- `/lock rename <新名称>`
81+
修改容器名字（仅 owner）。支持 `&#rrggbb` 颜色格式。
82+
83+
- `/lock permission <节点>`
84+
修改容器权限（仅 owner）。
85+
86+
权限节点格式：
87+
88+
- `<mode>:<subject>`
89+
- `mode`：`xx` owner、`rw` 可读写、`ro` 只读、`--` 删除该 subject 权限
90+
- `subject`：玩家 UUID/玩家名、`[tag]`、`#entity` 或 `[g:组名]`
91+
- `tag` 示例：`[everyone]`、权限组标签、计分板队伍标签
92+
- `#entity` 示例：`#hopper`
93+
94+
示例：
95+
96+
- `xx:AdminPlayer`
97+
- `rw:FriendA`
98+
- `ro:[everyone]`
99+
- `rw:#hopper`
100+
- `rw:[g:BaseMembers]`
101+
- `--:FriendA`
102+
103+
### 快速复制权限
104+
- `/lock clone` 会给你一个“权限复制工具”物品（带容器名称和权限数据）。
105+
- 用这个物品右键其他容器，可快速覆盖权限。
106+
- 目标容器规则：未上锁（可直接应用）、PDC 已上锁（需 owner）、牌子已上锁（需 owner）。
107+
108+
## 权限组（玩家自有）
109+
权限组用于减少单容器上写大量权限节点的需求。
110+
111+
- 每位玩家默认只能拥有一个组。
112+
- 组名全服唯一。
113+
- 只有组拥有者可修改/删除。
114+
- 数据在服务器启动时加载进内存，并按配置周期自动落盘。
115+
116+
命令：
117+
118+
- `/lock group create <groupName>`
119+
- `/lock group delete <groupName>`
120+
- `/lock group add <groupName> <subject>`
121+
- `/lock group remove <groupName> <subject>`
122+
- `/lock group info <groupName>`
123+
- `/lock group list`
124+
125+
在容器权限中使用组：
126+
127+
- `/lock permission rw:[g:<groupName>]`
128+
129+
## 权限节点（管理员）
130+
常用节点：
131+
132+
- `lockettepro.command`
133+
- `lockettepro.lock`
134+
- `lockettepro.edit`
135+
- `lockettepro.pdc.on`
136+
- `lockettepro.pdc.info`
137+
- `lockettepro.pdc.rename`
138+
- `lockettepro.pdc.permission`
139+
- `lockettepro.pdc.clone`
140+
- `lockettepro.pdc.group`
141+
- `lockettepro.pdc.*`
142+
- `lockettepro.reload`
143+
- `lockettepro.version`
144+
145+
运行期还会用到的附加节点（偏管理/兼容）：
146+
147+
- `lockettepro.lockothers`
148+
- `lockettepro.noexpire`
149+
- `lockettepro.admin.edit`
150+
- `lockettepro.edit.admin`
151+
- `lockettepro.admin.break`
152+
- `lockettepro.admin.use`
153+
- `lockettepro.admin.interfere`
154+
155+
如果你的服务器是 RPG/冒险模式，建议只给特定角色发放 `lockettepro.pdc.*` 或其子节点，避免玩家在不需要放置牌子的场景里滥用虚拟锁。
156+
157+
## 兼容与注意事项
158+
- 快捷上锁会触发放置事件，区域保护/反破坏插件可正常拦截。
159+
- 漏斗被锁阻止时会施加冷却，降低高频无效查询开销。
160+
- PDC 锁目前仅支持容器。
161+
- 门和普通方块仍然使用牌子锁。
162+
- 同时存在牌子锁和 PDC 锁时，容器权限判定优先使用 PDC 数据。

0 commit comments

Comments
 (0)