# lockpick

**Repository Path**: he666zz/lockpick

## Basic Information

- **Project Name**: lockpick
- **Description**: lockpick mod
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-12
- **Last Updated**: 2026-11-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lockpick

A Forge mod for **Minecraft 1.20.1** that adds a lockpicking minigame and real container protection.

Locked containers found in the world refuse to open until you crack them. Hold a screwdriver and a pin, sweep the dial to find the hidden sweet spot, and turn the lock before the timer runs out. You can also lock containers you placed yourself and decide whether teammates may open them.

- Source: <https://gitee.com/he666zz/lockpick>
- Issues: <https://gitee.com/he666zz/lockpick/issues>
- License: MIT (see [LICENSE](LICENSE))
- Version: `1.0.0`

---

## Requirements

| | |
|---|---|
| Minecraft | `1.20.1` (`[1.20.1,1.21)`) |
| Mod loader | Forge `47+` (built and tested against `47.4.28`) |
| Java | 17 |
| Side | **Both** — install on the client and on the dedicated server |

> The networking protocol is version **2**. The client and the server must run the **same jar version**; a mismatched pair is rejected at handshake instead of failing silently.

## Installation

1. Install Forge 47 or newer for Minecraft 1.20.1.
2. Put `lockpick-1.0.0.jar` into `mods/` on **both** the client and the server.
3. **Fully restart** the game. Do not replace the jar while the game is running — Forge loads classes lazily and an overwritten jar causes `ClassNotFoundException` in unrelated callbacks.

## Picking a lock

1. Right-click a locked chest, trapped chest, barrel or shulker box.
2. The dial opens. Press **Space** to start the timer; the needle sweeps a **half turn (180°)**, shown by a gold progress arc.
3. Use **Left Mouse** to strike at the angle you think is the sweet spot. A thin guide line shows the exact needle angle.
4. **Right Mouse** abandons the attempt.

Every strike costs one durability point on the tool. When the tier's probe budget is used up, the pin snaps and the attempt fails. All validation is done server-side.

### Lock tiers (default values)

| Tier | Spawn chance | Sweet-spot tolerance | Turn threshold | Probes | Time |
|---|---|---|---|---|---|
| Normal | 15% | 1.0° | 32.5° | 24 | 20 s |
| Silver | 8% | 0.6° | 24.0° | 16 | 16 s |
| Reinforced | 3% | 0.4° | 16.0° | 10 | 12 s |

Total chance for a container to spawn locked is **26%**. All values are configurable.

A double chest is **one container**: both halves share a single lock, both are protected, and opening either half opens the whole chest.

## Locking your own containers

Containers you place yourself are never auto-locked. Open one and use the draggable lock button beside the container window to:

- lock / unlock it;
- toggle whether **teammates may open** it.

A locked container cannot be broken by players or blown open by explosions. Only the player who placed it can manage its lock.

## Tools

| Item | Durability | Notes |
|---|---|---|
| Screwdriver | 3 | Turns the lock |
| Big Screwdriver | 40 | Longer-lasting wrench |
| Pin | 4 | Probes the sweet spot |
| Advanced Lockpick | 6 | Sturdier pin |
| Pin Box | — | Right-click to pull out pins, **20 per box** |

The four damageable tools stack up to **16** while undamaged. All five items use real 3D models built from vanilla-style `elements`, with textures in the mod's own `lockpick:` namespace — resource packs that retexture vanilla items cannot override them.

## Loot and the starter kit

- **Loot injection** (default on): the five tools are added to every chest loot table, including tables contributed by other mods. Default roll chance `0.65`, `1–3` of each tool.
- **Starter kit** (default on): on first spawn each player receives a guide book, a Pin Box and a Big Screwdriver — once per player per world. It is not repeated on reconnect or respawn.
- The guide book has **English and Simplified Chinese** pages. Pages are stored as translation keys and resolved on the client, so the same book shows text in the reader's own game language.

## Configuration

Edit `config/lockpick-common.toml`, or open the in-game config screen (Forge **Mods → Lockpick → Config**, or bind `key.lockpick.config` in Options → Controls — unbound by default).

| Option | Default | Meaning |
|---|---|---|
| `lockableBlocks` | `minecraft:chest,minecraft:trapped_chest,minecraft:barrel,minecraft:shulker_box` | Allow-list of blocks that may be locked/protected. Processing blocks (brewing stands, furnaces, …) are excluded on purpose. |
| `manualLocks` | empty | `blockId:tier` entries that are always locked at a fixed tier |
| `injectLoot` | `true` | Enable loot-table injection |
| `lootInjection.chance / minCount / maxCount` | `0.65 / 1 / 3` | Roll chance and tool counts |
| `giveStarterKit` | `true` | Enable the first-spawn kit |
| per-tier `probability / tolerance / threshold / durationTicks / maxAttempts` | see table above | Difficulty per lock tier |

Existing config files are migrated **once** when shipped defaults change. Anything you set after that migration is kept, and a custom `durationTicks` is never overwritten. If you want a completely fresh config, delete the toml and let it regenerate.

## Commands

Requires permission level 2 (operator). Look at a container while running the command.

```
/lockpick lock [normal|silver|reinforced]
/lockpick unlock
```

## Key binds

All are rebindable in **Options → Controls → Key Binds** under the Lockpick category.

| Action | Default |
|---|---|
| Start attempt | Space |
| Strike | Left Mouse |
| Give up | Right Mouse |
| Open config screen | unbound |

## Building from source

Requires JDK 17. The first build needs network access to resolve the Forge toolchain.

```bash
./gradlew build
```

Output: `build/libs/lockpick-1.0.0.jar`.

Helper scripts in `tools/` (Python 3 + Pillow):

| Script | Purpose |
|---|---|
| `tools/gen_item_models.py` | Generates the 3D item models, textures and an isometric preview; validates geometry and texture namespaces |
| `tools/preview_lockpick_tools.py` | Renders the dial layout preview and asserts no overlap at several resolutions |
| `tools/verify_double_chest.py` | Regression checks for double-chest lock normalization |
| `tools/verify_3d_tools.py` | Cross-file checks for the 3D tools, release compliance and jar contents |
| `tools/gen_sounds.py` | Synthesises the four original sound effects from scratch and self-verifies the OGG output |
| `tools/gen_logo_400.py` | Regenerates the 400×400 project avatar from the frozen source drawing |

## Implementation notes

- All shipped assets are original. `CREDITS.md` documents their provenance and is packaged in the jar; the four sound effects are generated by `tools/gen_sounds.py` with no third-party samples.

- The lock state is server-authoritative and persisted per world.
- Double-chest halves are normalized to a single canonical position inside the lock store, so every caller (events, packets, commands) gets consistent behaviour. Old saves where only one half was recorded are healed lazily on first access.
- The dial sweep is `180°`; `angleDiff` is linear in that range (0° and 180° are **not** neighbours).
- Localization: `assets/lockpick/lang/en_us.json` and `zh_cn.json` (74 keys each, kept in sync).

---

## 中文说明

这是适用于 **Minecraft 1.20.1 / Forge 47+** 的撬锁模组，需客户端与服务端同时安装，且两端 jar 版本必须一致（网络协议 v2）。

- 世界生成的箱子可能自带锁（普通 15% / 银 8% / 加固 3%），右键触发半圈撬锁小游戏：空格开始、左键敲击、右键放弃；工具每次消耗 1 点耐久，次数用尽别针断裂。
- 自己放置的箱子不会被自动上锁，可在容器界面旁的锁按钮里上锁并设置队友权限；上锁后无法被破坏或炸开。
- 首次出生会发一本指南书（**中英文随客户端语言自动切换**）、一盒别针（可取 20 根）和一把大螺丝刀。
- 所有配置在 `config/lockpick-common.toml` 或游戏内配置界面修改；OP 可用 `/lockpick lock` 与 `/lockpick unlock`。
- 完整源码与问题反馈：<https://gitee.com/he666zz/lockpick/issues>

## License

MIT — Copyright (c) 2026 HE666zz. See [LICENSE](LICENSE).