random perk

# Random Perk

**Every five minutes the dice roll. Whatever comes up, you live with — permanently.**

Random Perk is a lightweight Fabric mod that periodically hands you a draw. Open the draw screen
and you roll twice: once for an **effect**, and once for a **multiplier**. The two are selected
independently, so neither is revealed until both have landed — and you cannot leave the screen
until they have.

Then the result is applied to your character. Immediately. Permanently. Cumulatively.

Roll Attack Damage ×2.0, then roll it again at ×1.5, and you now hit for **×3.0**. Roll Movement
Speed ×0.3 on top of that and you will feel every single step. There is no undo, no refund, and
no mercy: bonuses stack by multiplication, and so do the penalties.

---

## How a draw works

1. **Accrue a charge.** You gain one draw charge every **5 minutes**, up to a maximum of **3**.
   The counter runs only while you are online, and it is yours alone.
2. **Open the screen.** Press **`K`**, or run `/randomperk gui`.
3. **Roll both halves.** The left panel rolls an **effect** — *what* changes. The right panel
   rolls a **multiplier** — *by how much*. Either side can be rolled first.
4. **Apply it.** Once both halves are rolled the perk takes effect instantly. Click **Finish** to
   close the screen.

Because the result is applied the moment the second half lands, closing the game is not an escape
route. A bad roll is yours.

---

## The 16 effects

Each effect has its own weighted probability, and most have their own **independent multiplier
table** — so a single effect can be tuned to roll high most of the time and low only rarely.

| Effect | Chance | What it changes |
| --- | --- | --- |
| **Attack Damage** | 11% | Attack damage × multiplier |
| **Armor** | 11% | Armor value × multiplier, computed from the gear you are actually wearing |
| **Max Health** | 11% | Maximum health × multiplier |
| **Movement Speed** | 11% | Movement speed × multiplier |
| **Jump Height** | 11% | Jump strength × multiplier |
| **Mining Speed** | 10% | How quickly you break blocks |
| Villager Trade | 8% | Grants *Hero of the Village*; villagers charge you less |
| Luck | 8% | Grants the *Luck* effect; better fishing and loot |
| **Mining Drops** | 4% | Items dropped per block × multiplier — **it can reduce them** |
| **Body Size** | 3% | Shrink to 0.5× or grow to 1.3× |
| **Low Gravity** | 3% | Gravity 0.35×–1.0×; jump higher, fall slower, drift further |
| Resistance | 2% | Damage reduction, levels I–IV |
| Regeneration | 2% | Health regeneration, levels I–V |
| **Attack Speed** | 2% | Shorter attack cooldown |
| **Fall Protection** | 2% | Safe fall distance × multiplier |
| **Reach** | 1% | Interact with blocks from further away |

The **12 bolded** effects ship with a dedicated multiplier table, so each can be tuned to roll high
most of the time and low only rarely. The remaining four — Villager Trade, Luck, Resistance and
Regeneration — share the global table at the end of the config file. They are just as configurable:
populate their own `multipliers` array and it takes precedence.

The default distribution leans toward modest results — most rolls land between **1.2× and 3×** —
with a rare **5×** jackpot and a small, deliberate chance of a **0.3× or 0.6× penalty**.

**Mining Drops** is deliberately built differently: it usually rolls **1.1×–1.3×**, occasionally
**0.5×–0.8×**, and carries a flat **1%** chance of a **5×** payout.

Buff effects (Luck, Hero of the Village, Resistance, Regeneration) convert their rolled multiplier
into an **effect level** rather than a raw attribute.

---

## Caps, and why draws never go to waste

Several effects have a ceiling. Once an effect reaches it, it is **removed from the draw pool** —
so a charge is never spent on something that can no longer improve you.

| Effect | Ceiling |
| --- | --- |
| Luck | level V |
| Resistance | level IV (80% damage reduction) |
| Regeneration | level V |
| Body Size | 1.3× |
| Low Gravity | 0.35× |
| **Villager Trade** | **no ceiling** — it keeps stacking indefinitely |

If every effect in the pool has been maxed out, the mod tells you so and **refuses to consume the
charge**.

---

## Multiplayer

Random Perk is fully multiplayer-aware, and **every player is independent**. Charges, timers, and
drawn effects are stored per player UUID, so nothing is shared:

* You cannot be dragged down by somebody else's bad roll.
* You cannot be carried by somebody else's good one.
* Nobody can spend your charges, and you cannot spend theirs.

The mod must be installed on **both** sides — the server resolves every draw, and the client
renders the screen. A player without the mod can still join and play normally; they simply will
not draw anything.

---

## Configuration

Everything is configurable. On first launch the mod writes `config/randomperk.json`:

```json
{
  "enabled": true,
  "chargeIntervalSeconds": 300,
  "maxCharges": 3,
  "showChatMessage": true,
  "showTitle": true,
  "effects": [
    {
      "id": "attack_damage",
      "name": "Attack Damage",
      "enabled": true,
      "weight": 11,
      "multipliers": [
        { "value": 2.0, "weight": 19, "_说明": "about a fifth of all attack rolls" }
      ]
    }
  ]
}
```

* **`weight` is the probability.** The defaults total exactly 100, so each weight reads directly as
  a percentage. Change them freely — the mod normalizes whatever you supply.
* **`enabled: false`** disables an effect without deleting it.
* **`multipliers`** — leave the array empty to fall back to the global table at the end of the file.
* **`name`** — rename any effect. If you do, your custom name is displayed instead of the built-in
  translation.
* Apply changes with **`/randomperk reload`**. No restart required.

> The comment fields (`_说明`, `_note`) and the config's own header text ship in Chinese, and the
> default `name` values are Chinese too — those are translated client-side, so English players see
> English in game. Only edit the fields you actually want to change.

> Back up the file before editing. Invalid JSON causes the mod to regenerate defaults and your
> changes are lost. Note also the config **version field** — the mod rewrites the file when it
> ships updated defaults, so re-apply your tweaks after an update.

---

## Commands

Every command supports **Tab completion**. `<player>` accepts any online player by name.

| Command | Permission | What it does |
| --- | --- | --- |
| `/randomperk` | everyone | Display the help text |
| `/randomperk gui` | everyone | Open the draw screen (identical to pressing `K`) |
| `/randomperk status` | everyone | Show **your own** charges, total draws and active effects as chat text |
| `/randomperk status <player>` | OP 2 | Show **another player's** status |
| `/randomperk charge <amount>` | OP 2 | Grant **yourself** draw charges (1–100). Primarily a testing tool |
| `/randomperk charge <amount> <player>` | OP 2 | Grant charges to **another player** |
| `/randomperk reset` | everyone | Wipe **your own** effects and charges |
| `/randomperk reset <player>` | OP 2 | Wipe **another player's** effects and charges |
| `/randomperk resetall` | OP 2 | Wipe **every** player's effects and charges |
| `/randomperk reload` | OP 2 | Re-read `config/randomperk.json` without restarting |
| `K` (key binding) | everyone | Open the draw screen. Rebinding is available under *Options → Controls → Key Binds → Miscellaneous* |

### A note on permissions

**OP 2** is the same level vanilla requires for `/gamemode`, `/give` and `/time`. In single player
you hold it as soon as cheats are enabled.

This restriction is deliberate. It prevents any ordinary player on a server from topping up their
own charges, wiping another player's progress, or clearing the whole server's perks in one command.

### What the commands actually print

**`/randomperk status`**

```
[Steve] Draws available 2/3, total draws 5; active effects: Attack Damage ×2.00 Luck ×1.50
[Steve] Draws available 3/3, total draws 0; no active effects
[Steve] Draws available 1/3, total draws 2 (one draw is still unfinished); active effects: Movement Speed ×1.30
```

**`/randomperk charge 3 Steve`**

```
Gave Steve 3 draw(s); they now have 3.
```

**`/randomperk reset Steve`**

```
Wiped all effects and charges for Steve.
```

**`/randomperk resetall`**

```
Wiped every player's effects and charges.
```

**`/randomperk reload`**

```
Config reloaded: 16 effects, 8 multipliers, +1 draw every 300 s, max 3
```

**Run from the server console**, a player name is required — for example
`randomperk status Steve`, `randomperk charge 3 Steve`, or `randomperk resetall`. Without one you
will see:

```
Run this in game, or add a player name (e.g. /randomperk status <player>).
```

### Messages the mod sends on its own

These are not commands; they are the notifications you will see while playing.

| When | Message |
| --- | --- |
| A charge is earned | `★ Draw +1 (now 2 / 3)` |
| A draw completes | `★ Rolled: Attack Damage x 2.00 (this perk is now at x 3.00 total)` |
| You press Draw but every effect is maxed | `Every perk is maxed out - nothing left to draw.` |

A draw also flashes a title in the centre of the screen. Both the chat line and the title can be
disabled via `showChatMessage` and `showTitle`.

### Quick start

```
/randomperk charge 3      grant yourself three draws
K                         open the draw screen
Draw → roll both sides → Finish
```

To start over: `/randomperk reset` wipes your own progress; `/randomperk resetall` wipes everyone's.

---

## Requirements

| | |
| --- | --- |
| Minecraft | **1.21.10** (an exact match is required) |
| Mod loader | **Fabric Loader 0.17.0+** |
| Dependency | **[Fabric API](https://modrinth.com/mod/fabric-api)** (required) |
| Java | 21 (bundled with the vanilla launcher) |
| Sides | **Client and server both need the mod** |

Place this jar **and Fabric API** into `.minecraft/mods`, then launch the `fabric-loader-1.21.10`
profile.

---

## Saving and upgrading

State is stored in `<world>/randomperk_state.json`, one entry per player. The two top-level keys are
`_存档版本` (save format version) and `players`:

```json
{
  "_存档版本": 2,
  "players": {
    "<uuid>": { "charges": 2, "totalDraws": 5, "history": [ ] }
  }
}
```

Saves created by older versions — which stored a single world-wide state — are **migrated
automatically**. The entire legacy state is handed to the first player who joins, which in single
player is you. Nothing is lost. A migrated file briefly contains a `legacy` block; it disappears as
soon as it has been claimed.

---

## Known limitations

* **Body Size** can push you past two blocks tall, and you will suffocate inside a two-block-high
  corridor. Lower or zero the weights of the `1.15` and `1.3` entries if you would rather not
  take that risk.
* **Low Gravity** lets you drift a long way. Pair it with Fall Protection unless you enjoy
  surprises.
* **Negative multipliers are permanent too.** If you paint yourself into a corner, `/randomperk
  reset` is the way out.
* **Effect IDs must not be renamed.** The ID is what the history is keyed on; change the `name`
  field instead, or set `enabled` to `false` to retire an effect.

---

## Localisation

The interface ships in **English** and **Simplified Chinese**, and follows your Minecraft language
setting. Effect names are translated too — unless a server owner has deliberately renamed one, in
which case their name is respected.

---

## License

MIT © 2026-10-13 **kraoCry**

You are free to use, modify and redistribute this mod. The MIT License requires that the copyright
notice be retained in all copies, so please leave the author's name in place.