# items/weapons.ron

> Melee weapons and guns: damage, reach, timing, wear.

<!-- Generated by `zombye-server --docs`. Do not edit: change the game and generate again. -->

**Melee weapons and guns: damage, reach, timing, wear.** Read by the game's rules: a change here changes how the game plays, and a world remembers the content it was made with.

File: `assets/data/items/weapons.ron`

## About this file

Melee weapons. Schema: zombye_sim::items::WeaponDef (validated on load).

Zombies have about 100 hit points (85-115). Distances in metres (range is measured to the zombie's body), times in seconds, chances and endurance in 0..1. Endurance below half makes swings slower and weaker; walking gives back 0.05 a second, so endurance_cost / swing_seconds above that wears you down (about ten seconds of flat-out bat swinging). All numbers are our own, tuned for feel and readability:

```text
  knives   fast, short, one target, crit-happy (go for the back)
  blunt    short ones stagger, long ones sweep a wide arc, hit several and knock down
  axes     slow, heavy, tiring; two hits or one good one
```

Wear (zombye_sim::wear): `durability` is the knocks a weapon takes before it breaks, `wear_chance` the chance a swing that hits something adds one, so it lasts about durability / wear_chance such swings (a plank 20, a golf club 36, a knife 50, a bat 80, a pan 100, an axe 140, a hammer 165, a crowbar 400), longer in practised hands. With a quarter of its life left it is battered and hits weaker. Left out: it never wears (bare hands, guns). `close_range`: a target whose body is nearer than this (bodies touch 0.3 m apart; a lone zombie striking you stands 0.4-0.6 m off, a crowd presses them closer) is too close for a full swing of a long weapon and takes 0.6 of the damage: shove them back first. Exactly one weapon must be Unarmed: what a player swings with empty hands (never placed). `skill` is the skill it trains and that makes it better, by how it hits: Bludgeon for blunt weapons, Edged for knives and axes, Brawl for bare hands. Every weapon of a category names the same one; left out, it is the category's.


## Fields

The file is a list of `WeaponDef`, each in round brackets.

One melee weapon. Distances in metres (reach is measured to the target's body), times in seconds, chances in 0..1. All numbers are ours.

| Field | Type | What it is |
|---|---|---|
| `id` | `String` |  |
| `name` | `String` |  |
| `category` | `WeaponCategory` |  |
| `skill` | `Option<Skill>` | The skill it trains and that makes it better: Bludgeon, Edged or Brawl. Left out, its category's (`WeaponCategory::skill`); every weapon of a category must name the same one. |
| `damage` | `(f32, f32)` | Damage per hit, rolled uniformly (zombies have about 100 hit points). |
| `range` | `f32` | Reach from the player's centre to the edge of a zombie's body. |
| `arc_degrees` | `f32` | Width of the swing in front of the player. |
| `windup_seconds` | `f32` | From starting the swing to the moment it lands. |
| `swing_seconds` | `f32` | From starting the swing until the next action can start (≥ windup). |
| `max_targets` | `u32` | Zombies one swing can hit, nearest first. |
| `knockback` | `f32` | How far a hit pushes a zombie back. |
| `stagger_chance` | `f32` |  |
| `knockdown_chance` | `f32` |  |
| `crit_chance` | `f32` |  |
| `crit_multiplier` | `f32` |  |
| `endurance_cost` | `f32` | Endurance (0..1) one swing costs. |
| `noise_radius` | `f32` | Radius of the noise a swing makes. |
| `spawn_weight` | `f32` | Relative chance of being placed in a house (0 = never). |
| `found_in` | `Vec<String>` | Room types (`kitchen`, `bedroom`, ...) where it's three times as likely to turn up. |
| `length` | `f32` | Grey-box look: length in metres and colour (linear-ish RGB 0..1). |
| `color` | `(f32, f32, f32)` |  |
| `ranged` | `Option<crate::ranged::RangedDef>` | A gun's numbers: what it is loaded with, how far and how true it shoots. With it the weapon shoots instead of swinging (see `crate::ranged::RangedDef` for what the fields above mean then). Exactly the `Firearm` weapons have it. |
| `durability` | `u8` | Wear: how many knocks it takes before it breaks (see `crate::wear`). 0: it never wears (bare hands, guns). How worn one is rides on its stack (`ItemStack::used`). |
| `wear_chance` | `f32` | Chance (0..1) that a swing that hits something knocks it one step nearer breaking. A weapon lasts about `durability / wear_chance` such swings in unpractised hands. |
| `close_range` | `f32` | Too close for a full swing: a target whose body is nearer than this takes a cramped blow (`crate::CombatTuning::cramped_damage`). 0: none. |

### `WeaponCategory`

What kind of weapon it is: how it hits, which decides its skill and its swing animation.

| Value | What it means |
|---|---|
| `Unarmed` | Bare hands. Exactly one weapon must be this; it's what a player without a weapon uses. |
| `ShortBlade` |  |
| `ShortBlunt` |  |
| `LongBlunt` |  |
| `Axe` |  |
| `Firearm` | A gun: its `ranged` numbers say how it shoots (`crate::ranged`). Last, so the categories before it keep their numbers in saves and on the wire. |

### `Skill`

One of the skills.

| Value | What it means |
|---|---|
| `Fitness` |  |
| `Strength` |  |
| `Bludgeon` |  |
| `Edged` |  |
| `Brawl` |  |
| `Stealth` |  |
| `FirstAid` |  |
| `Scavenging` |  |
| `Handiwork` | Crafting (#12; this module only keeps its XP and level). |

### `RangedDef`

What makes a weapon a gun. Distances in metres, times in seconds, angles in degrees. Ours.

| Field | Type | What it is |
|---|---|---|
| `ammo` | `String` | The item one round of it is (an id in `items.ron`). |
| `capacity` | `u8` | Rounds it holds. |
| `magazine` | `Option<String>` | The item its detachable magazine is, if it has one: a carried one is swapped in whole. |
| `reload_seconds` | `f32` | Swapping a magazine. |
| `round_seconds` | `f32` | Pushing one loose round in. |
| `range` | `f32` | How far a bullet flies. |
| `spread_degrees` | `f32` | Each pellet goes up to this far off the aim, sideways and up or down, standing still. |
| `move_spread_degrees` | `f32` | Added to it while moving. |
| `pellets` | `u8` | Pellets a shot (a shotgun's; one round either way). |
| `far_damage` | `f32` | The share of its damage a pellet still does at the end of its range (falling off evenly). |

## As shipped

13 entries. Columns are the fields short enough for a table; the rest are in the file below.

| `id` | `arc_degrees` | `category` | `close_range` | `color` | `crit_chance` | `crit_multiplier` | `damage` | `durability` | `endurance_cost` | `found_in` | `knockback` |
|---|---|---|---|---|---|---|---|---|---|---|---|
| "fists" | 60 | "Unarmed" | 0 | [0.8, 0.65, 0.5] | 0.05 | 1.5 | [4, 7] | 0 | 0.025 | [] | 0.15 |
| "kitchen_knife" | 40 | "ShortBlade" | 0 | [0.75, 0.78, 0.82] | 0.22 | 2.6 | [17, 25] | 6 | 0.03 | ["kitchen", "dining"] | 0.05 |
| "claw_hammer" | 55 | "ShortBlunt" | 0 | [0.35, 0.22, 0.12] | 0.15 | 2 | [22, 31] | 10 | 0.05 | ["laundry", "hall"] | 0.3 |
| "frying_pan" | 80 | "ShortBlunt" | 0 | [0.12, 0.12, 0.13] | 0.08 | 1.6 | [13, 20] | 8 | 0.055 | ["kitchen"] | 0.5 |
| "baseball_bat" | 110 | "LongBlunt" | 0.38 | [0.72, 0.55, 0.32] | 0.1 | 1.8 | [26, 37] | 8 | 0.085 | ["bedroom", "hall"] | 0.6 |
| "golf_club" | 90 | "LongBlunt" | 0.4 | [0.6, 0.62, 0.66] | 0.18 | 2 | [19, 28] | 5 | 0.07 | ["hall", "living"] | 0.45 |
| "wooden_plank" | 120 | "LongBlunt" | 0.4 | [0.55, 0.42, 0.26] | 0.04 | 1.5 | [15, 24] | 4 | 0.09 | ["laundry", "living"] | 0.55 |
| "crowbar" | 70 | "LongBlunt" | 0 | [0.55, 0.1, 0.08] | 0.15 | 2 | [29, 39] | 12 | 0.07 | ["laundry"] | 0.4 |
| "hatchet" | 60 | "Axe" | 0.3 | [0.5, 0.36, 0.22] | 0.15 | 2 | [30, 42] | 10 | 0.07 | ["shed", "garage"] | 0.3 |
| "fire_axe" | 75 | "Axe" | 0.38 | [0.75, 0.12, 0.08] | 0.15 | 2 | [52, 72] | 10 | 0.15 | ["laundry"] | 0.5 |
| "pistol" | 10 | "Firearm" | 0 | [0.16, 0.16, 0.18] | 0 | 2.6 | [34, 46] | 0 | 0.004 | [] | 0.1 |
| "hunting_rifle" | 10 | "Firearm" | 0 | [0.36, 0.24, 0.14] | 0 | 2 | [85, 115] | 0 | 0.01 | [] | 0.3 |
| "shotgun" | 10 | "Firearm" | 0 | [0.2, 0.18, 0.16] | 0 | 1.6 | [16, 24] | 0 | 0.015 | [] | 0.5 |

## The file

<details>
<summary>The whole file as shipped</summary>

```ron
// Melee weapons. Schema: zombye_sim::items::WeaponDef (validated on load).
//
// Zombies have about 100 hit points (85-115). Distances in metres (range is measured to the
// zombie's body), times in seconds, chances and endurance in 0..1. Endurance below half makes
// swings slower and weaker; walking gives back 0.05 a second, so endurance_cost / swing_seconds
// above that wears you down (about ten seconds of flat-out bat swinging). All numbers are our
// own, tuned for feel and readability:
//   knives   fast, short, one target, crit-happy (go for the back)
//   blunt    short ones stagger, long ones sweep a wide arc, hit several and knock down
//   axes     slow, heavy, tiring; two hits or one good one
// Wear (zombye_sim::wear): `durability` is the knocks a weapon takes before it breaks, `wear_chance`
// the chance a swing that hits something adds one, so it lasts about durability / wear_chance such
// swings (a plank 20, a golf club 36, a knife 50, a bat 80, a pan 100, an axe 140, a hammer 165, a
// crowbar 400), longer in practised hands. With a quarter of its life left it is battered and
// hits weaker. Left out: it never wears (bare hands, guns).
// `close_range`: a target whose body is nearer than this (bodies touch 0.3 m apart; a lone zombie
// striking you stands 0.4-0.6 m off, a crowd presses them closer) is too close for a full swing
// of a long weapon and takes 0.6 of the damage: shove them back first.
// Exactly one weapon must be Unarmed: what a player swings with empty hands (never placed).
// `skill` is the skill it trains and that makes it better (#46), by how it hits: Bludgeon for blunt
// weapons, Edged for knives and axes, Brawl for bare hands. Every weapon of a category names the
// same one; left out, it is the category's.
[
    (
        id: "fists",
        name: "Bare hands",
        category: Unarmed,
        skill: Some(Brawl),
        damage: (4.0, 7.0),
        range: 0.6,
        arc_degrees: 60.0,
        windup_seconds: 0.15,
        swing_seconds: 0.45,
        max_targets: 1,
        knockback: 0.15,
        stagger_chance: 0.25,
        knockdown_chance: 0.03,
        crit_chance: 0.05,
        crit_multiplier: 1.5,
        endurance_cost: 0.025,
        noise_radius: 3.0,
        spawn_weight: 0.0,
        length: 0.0,
        color: (0.8, 0.65, 0.5),
    ),
    (
        id: "kitchen_knife",
        name: "Kitchen knife",
        category: ShortBlade,
        skill: Some(Edged),
        damage: (17.0, 25.0),
        range: 0.65,
        arc_degrees: 40.0,
        windup_seconds: 0.12,
        swing_seconds: 0.4,
        max_targets: 1,
        knockback: 0.05,
        stagger_chance: 0.15,
        knockdown_chance: 0.0,
        crit_chance: 0.22,
        crit_multiplier: 2.6,
        endurance_cost: 0.03,
        noise_radius: 2.5,
        spawn_weight: 3.0,
        found_in: ["kitchen", "dining"],
        length: 0.3,
        durability: 6,
        wear_chance: 0.12,
        color: (0.75, 0.78, 0.82),
    ),
    (
        id: "claw_hammer",
        name: "Claw hammer",
        category: ShortBlunt,
        skill: Some(Bludgeon),
        damage: (22.0, 31.0),
        range: 0.75,
        arc_degrees: 55.0,
        windup_seconds: 0.22,
        swing_seconds: 0.65,
        max_targets: 1,
        knockback: 0.3,
        stagger_chance: 0.45,
        knockdown_chance: 0.12,
        crit_chance: 0.15,
        crit_multiplier: 2.0,
        endurance_cost: 0.05,
        noise_radius: 5.0,
        spawn_weight: 2.5,
        found_in: ["laundry", "hall"],
        length: 0.33,
        durability: 10,
        wear_chance: 0.06,
        color: (0.35, 0.22, 0.12),
    ),
    (
        id: "frying_pan",
        name: "Frying pan",
        category: ShortBlunt,
        skill: Some(Bludgeon),
        damage: (13.0, 20.0),
        range: 0.8,
        arc_degrees: 80.0,
        windup_seconds: 0.24,
        swing_seconds: 0.7,
        max_targets: 2,
        knockback: 0.5,
        stagger_chance: 0.65,
        knockdown_chance: 0.2,
        crit_chance: 0.08,
        crit_multiplier: 1.6,
        endurance_cost: 0.055,
        // The clang carries.
        noise_radius: 9.0,
        spawn_weight: 3.0,
        found_in: ["kitchen"],
        length: 0.45,
        durability: 8,
        wear_chance: 0.08,
        color: (0.12, 0.12, 0.13),
    ),
    (
        id: "baseball_bat",
        name: "Baseball bat",
        category: LongBlunt,
        skill: Some(Bludgeon),
        damage: (26.0, 37.0),
        range: 1.25,
        arc_degrees: 110.0,
        windup_seconds: 0.32,
        swing_seconds: 0.9,
        max_targets: 3,
        knockback: 0.6,
        stagger_chance: 0.6,
        knockdown_chance: 0.33,
        crit_chance: 0.1,
        crit_multiplier: 1.8,
        endurance_cost: 0.085,
        noise_radius: 6.0,
        spawn_weight: 0.6,
        found_in: ["bedroom", "hall"],
        length: 0.85,
        durability: 8,
        wear_chance: 0.1,
        close_range: 0.38,
        color: (0.72, 0.55, 0.32),
    ),
    (
        id: "golf_club",
        name: "Golf club",
        category: LongBlunt,
        skill: Some(Bludgeon),
        damage: (19.0, 28.0),
        range: 1.3,
        arc_degrees: 90.0,
        windup_seconds: 0.27,
        swing_seconds: 0.8,
        max_targets: 2,
        knockback: 0.45,
        stagger_chance: 0.5,
        knockdown_chance: 0.25,
        crit_chance: 0.18,
        crit_multiplier: 2.0,
        endurance_cost: 0.07,
        noise_radius: 5.0,
        spawn_weight: 1.0,
        found_in: ["hall", "living"],
        length: 1.0,
        durability: 5,
        wear_chance: 0.14,
        close_range: 0.4,
        color: (0.6, 0.62, 0.66),
    ),
    (
        id: "wooden_plank",
        name: "Wooden plank",
        category: LongBlunt,
        skill: Some(Bludgeon),
        damage: (15.0, 24.0),
        range: 1.35,
        arc_degrees: 120.0,
        windup_seconds: 0.36,
        swing_seconds: 1.0,
        max_targets: 3,
        knockback: 0.55,
        stagger_chance: 0.55,
        knockdown_chance: 0.28,
        crit_chance: 0.04,
        crit_multiplier: 1.5,
        endurance_cost: 0.09,
        noise_radius: 5.5,
        spawn_weight: 3.0,
        found_in: ["laundry", "living"],
        length: 1.1,
        durability: 4,
        wear_chance: 0.2,
        close_range: 0.4,
        color: (0.55, 0.42, 0.26),
    ),
    (
        id: "crowbar",
        name: "Crowbar",
        category: LongBlunt,
        skill: Some(Bludgeon),
        damage: (29.0, 39.0),
        range: 0.95,
        arc_degrees: 70.0,
        windup_seconds: 0.28,
        swing_seconds: 0.8,
        max_targets: 1,
        knockback: 0.4,
        stagger_chance: 0.55,
        knockdown_chance: 0.2,
        crit_chance: 0.15,
        crit_multiplier: 2.0,
        endurance_cost: 0.07,
        noise_radius: 6.0,
        spawn_weight: 0.3,
        found_in: ["laundry"],
        length: 0.7,
        durability: 12,
        wear_chance: 0.03,
        color: (0.55, 0.1, 0.08),
    ),
    // A small axe for wood: quick and light, and it fells a tree (its item chops, see
    // zombye_sim::trees), in more swings than the fire axe.
    (
        id: "hatchet",
        name: "Hatchet",
        category: Axe,
        skill: Some(Edged),
        damage: (30.0, 42.0),
        range: 0.8,
        arc_degrees: 60.0,
        windup_seconds: 0.28,
        swing_seconds: 0.8,
        max_targets: 1,
        knockback: 0.3,
        stagger_chance: 0.4,
        knockdown_chance: 0.12,
        crit_chance: 0.15,
        crit_multiplier: 2.0,
        endurance_cost: 0.07,
        noise_radius: 5.0,
        spawn_weight: 0.6,
        found_in: ["shed", "garage"],
        length: 0.38,
        durability: 10,
        wear_chance: 0.08,
        close_range: 0.3,
        color: (0.5, 0.36, 0.22),
    ),
    (
        id: "fire_axe",
        name: "Fire axe",
        category: Axe,
        skill: Some(Edged),
        damage: (52.0, 72.0),
        range: 1.15,
        arc_degrees: 75.0,
        windup_seconds: 0.55,
        swing_seconds: 1.4,
        max_targets: 2,
        knockback: 0.5,
        stagger_chance: 0.5,
        knockdown_chance: 0.3,
        crit_chance: 0.15,
        crit_multiplier: 2.0,
        endurance_cost: 0.15,
        noise_radius: 7.0,
        spawn_weight: 0.1,
        found_in: ["laundry"],
        length: 0.9,
        durability: 10,
        wear_chance: 0.07,
        close_range: 0.38,
        color: (0.75, 0.12, 0.08),
    ),

    // ---- Guns (#72; zombye_sim::ranged) -----------------------------------------------------------
    // A `Firearm` shoots: `ranged` says what it is loaded with (items in items.ron), how far a
    // bullet flies, how far off the aim it may go (degrees, standing and extra on the move), how
    // many pellets a shot and what is left of their damage at the end of the range. Of the numbers
    // above it uses: damage (each pellet's), windup_seconds (trigger to shot), swing_seconds (shot
    // to shot), max_targets (bodies one bullet goes through), crit_multiplier (a hit to the head),
    // knockback, stagger_chance, knockdown_chance, endurance_cost (the recoil) and noise_radius
    // (up to 300 m: a shot wakes the street and draws the far horde over the next minutes).
    // range, arc_degrees and crit_chance aren't read. Never on a floor: loot tables only, rare.
    //   pistol   quick, twelve in a magazine, a head shot or three to the body
    //   rifle    one zombie a round at any distance, through two in a line; slow bolt, loudest
    //   shotgun  eight pellets: everything close in front of you, little past 20 m
    (
        id: "pistol",
        name: "Pistol",
        category: Firearm,
        damage: (34.0, 46.0),
        range: 1.0,
        arc_degrees: 10.0,
        windup_seconds: 0.05,
        swing_seconds: 0.35,
        max_targets: 1,
        knockback: 0.1,
        stagger_chance: 0.5,
        knockdown_chance: 0.08,
        crit_chance: 0.0,
        crit_multiplier: 2.6,
        endurance_cost: 0.004,
        noise_radius: 120.0,
        length: 0.22,
        color: (0.16, 0.16, 0.18),
        ranged: Some((
            ammo: "pistol_rounds",
            capacity: 12,
            magazine: Some("pistol_magazine"),
            reload_seconds: 1.8,
            round_seconds: 0.7,
            range: 45.0,
            spread_degrees: 1.2,
            move_spread_degrees: 3.0,
            far_damage: 0.6,
        )),
    ),
    (
        id: "hunting_rifle",
        name: "Hunting rifle",
        category: Firearm,
        damage: (85.0, 115.0),
        range: 1.0,
        arc_degrees: 10.0,
        windup_seconds: 0.05,
        swing_seconds: 1.3,
        max_targets: 2,
        knockback: 0.3,
        stagger_chance: 0.8,
        knockdown_chance: 0.35,
        crit_chance: 0.0,
        crit_multiplier: 2.0,
        endurance_cost: 0.01,
        noise_radius: 180.0,
        length: 1.1,
        color: (0.36, 0.24, 0.14),
        ranged: Some((
            ammo: "rifle_rounds",
            capacity: 5,
            round_seconds: 0.9,
            range: 110.0,
            spread_degrees: 0.35,
            move_spread_degrees: 4.0,
            far_damage: 0.85,
        )),
    ),
    (
        id: "shotgun",
        name: "Shotgun",
        category: Firearm,
        damage: (16.0, 24.0),
        range: 1.0,
        arc_degrees: 10.0,
        windup_seconds: 0.05,
        swing_seconds: 0.9,
        max_targets: 1,
        knockback: 0.5,
        stagger_chance: 0.6,
        knockdown_chance: 0.1,
        crit_chance: 0.0,
        crit_multiplier: 1.6,
        endurance_cost: 0.015,
        noise_radius: 160.0,
        length: 1.0,
        color: (0.2, 0.18, 0.16),
        ranged: Some((
            ammo: "shotgun_shells",
            capacity: 5,
            round_seconds: 0.6,
            range: 28.0,
            spread_degrees: 4.5,
            move_spread_degrees: 2.0,
            pellets: 8,
            far_damage: 0.35,
        )),
    ),
]
```

</details>