Improvements and lots of bug fixes to new weapon systems.

levels/README.md

@@ -819,5 +819,168 @@ This example demonstrates:
 - **Custom audio** (themed ambience and footsteps)
 - **Strategic design** (safe zones, risk/reward placement)
 
+## Custom Weapons
+
+Level packs can define custom weapons that players can craft and use alongside the standard weapons (1=shovel, 2=broom, 3=nunchucks). Custom weapons are bound to keys 4-0, giving you 7 additional weapon slots.
+
+### Basic Structure
+
+Add a `custom_weapons` array to your level JSON (typically level 1.json):
+
+```json
+{
+    "custom_weapons": [
+        {
+            "key": 4,
+            "name": "weapon_internal_name",
+            "display_name": "Player Visible Name",
+            "damage": 6,
+            "range": 3,
+            "attack_sound": "sound_name",
+            "hit_sound": "sound_name"
+        }
+    ]
+}
+```
+
+### Required Fields
+
+- **`key`** - Key binding (4-9 or 0 for key 10)
+- **`name`** - Internal weapon name (for game logic)
+- **`damage`** - Weapon damage (integer)
+- **`range`** - Attack range in tiles (integer)
+- **`attack_sound`** - Sound when attacking
+- **`hit_sound`** - Sound when hitting enemies
+
+### Optional Fields
+
+- **`display_name`** - Name shown to player (defaults to `name`)
+- **`weapon_type`** - "melee" or "projectile" (defaults to "melee")
+- **`cooldown`** - Milliseconds between attacks (defaults to 500)
+- **`attack_duration`** - Milliseconds attack is active (defaults to 200)
+- **`speed_bonus`** - Movement speed multiplier (defaults to 1.0)
+- **`jump_bonus`** - Jump duration multiplier (defaults to 1.0)
+- **`requires`** - Crafting requirements (defaults to none)
+- **`craft_sound`** - Sound when weapon is crafted
+- **`ammo_type`** - Ammo type for projectile weapons
+- **`ammo_cost`** - Ammo consumed per shot (defaults to 1)
+- **`projectile_speed`** - Speed of projectiles (defaults to 0.2)
+
+### Melee Weapon Example
+
+```json
+{
+    "custom_weapons": [
+        {
+            "key": 4,
+            "name": "bone_hatchet",
+            "display_name": "blood-stained hatchet",
+            "damage": 6,
+            "range": 2,
+            "attack_sound": "player_hatchet_chop",
+            "hit_sound": "player_hatchet_hit",
+            "cooldown": 400,
+            "speed_bonus": 1.1,
+            "requires": {
+                "shin_bone": 3,
+                "hand_of_glory": 1
+            },
+            "craft_sound": "get_hatchet"
+        }
+    ]
+}
+```
+
+### Projectile Weapon Example
+
+```json
+{
+    "custom_weapons": [
+        {
+            "key": 6,
+            "name": "bone_crossbow",
+            "display_name": "cursed crossbow",
+            "weapon_type": "projectile",
+            "damage": 12,
+            "range": 8,
+            "attack_sound": "crossbow_fire",
+            "hit_sound": "crossbow_impact",
+            "cooldown": 1500,
+            "attack_duration": 100,
+            "ammo_type": "shin_bone",
+            "ammo_cost": 3,
+            "projectile_speed": 0.3,
+            "requires": {
+                "shin_bone": 5,
+                "guts": 2
+            },
+            "craft_sound": "get_crossbow"
+        }
+    ]
+}
+```
+
+### Crafting System
+
+Weapons with `requires` are automatically crafted when the player has the necessary materials:
+
+**Supported Ammo/Material Types:**
+- `shin_bone` - Shin bones collected
+- `bone_dust` - Bone dust for extra lives
+- `guts` - Health/crafting items
+- `hand_of_glory` - Collectible items
+- `jack_o_lantern` - Throwable projectiles
+- Any other item type in `collectedItems`
+
+**Crafting Behavior:**
+- Materials are NOT consumed (items keep their original functions)
+- Weapons auto-craft when requirements are met
+- Each weapon can only be crafted once per playthrough
+- Crafting plays the `craft_sound` if specified
+
+### Projectile Weapons
+
+Projectile weapons (`weapon_type: "projectile"`) fire projectiles instead of melee attacks:
+
+- **Ammo Consumption** - Each shot consumes `ammo_cost` of `ammo_type`
+- **Out of Ammo** - Shows themed message: "Not enough candy canes"
+- **Inventory Display** - Press 'c' to see current ammo counts
+- **High Damage** - Usually more powerful than melee weapons
+- **Strategic Cost** - Must balance ammo usage vs. other needs
+
+### Weapon Override Integration
+
+Custom weapons work with the weapon override system. You can theme custom weapons just like standard ones:
+
+```json
+{
+    "weapon_sound_overrides": {
+        "bone_hatchet": {
+            "name": "ice hatchet",
+            "attack_sound": "player_ice_hatchet_chop",
+            "hit_sound": "player_ice_hatchet_hit"
+        }
+    }
+}
+```
+
+### Key Binding Reference
+
+- **1-3**: Reserved for standard weapons (shovel, broom, nunchucks)
+- **4-9**: Custom weapon slots (6 weapons)
+- **0**: Custom weapon slot (key 10, for 7th weapon)
+
+### Design Tips
+
+**Balanced Progression:**
+- Early weapons: Low requirements, moderate power
+- Mid weapons: Medium requirements, good utility
+- Late weapons: High requirements, devastating power
+
+**Ammo Economics:**
+- Cheap ammo: bone_dust (common)
+- Expensive ammo: shin_bone (valuable for lives)
+- Special ammo: guts, hand_of_glory (limited)
+
 Check out the existing Wicked Quest levels for more examples and inspiration!