Copr. Mitachi

Pros:
- This follows the Ymir logic, there used to be a system that gave basic items to Chinese players, though it was never really used.
- You can spawn with the items already equipped and specify any slot number you want for each item.
- You can also set up count, bonuses and stones(sockets, so also duration) in the starter equipment.
- Since it happens during character creation, there's no risk of doing it before CItem or QuestManager is properly initialized, indeed, we don't even use them here.
- The function is called during PlayerCreate, so you don't need a quest flag to prevent giving items twice. It only triggers on character creation.
- It supports a lightweight reload (core based), so you can hot test or run a starter boost event without shutting down the server.

Cons:
- The only annoying part is having to specify the exact slot indexes where items go, even for equipment. But hey, you only need to do it once.


USAGE:
  The structure of the JSON file is straightforward. If you're not familiar with it, feel free to ask https://chat.openai.com.
  Not in the mood to use it? No problem. I’ve already used it to generate a README for you, scroll down

# Starter Items System – `give_basic_weapon.json` Usage Guide

This file defines the initial equipment and items given **at character creation**, organized into three sections.

## `common`
These items are given to **all characters**, regardless of race or job.

```json
{ "vnum": 27003, "pos": 0, "equip": false }
```

| Field     | Description                                                                        |
|-----------|------------------------------------------------------------------------------------|
| `vnum`    | The item ID (vnum) to give                                                         |
| `pos`     | Inventory slot index                                                               |
| `equip`   | If true, the item is placed in the equipment slot                                  |
| `count`   | (Optional) Item quantity. Defaults to 1.                                           |
| `sockets` | (Optional) List of socket values — default is 3, but this depends on ITEM_SOCKET_MAX_NUM in your source code.                                                                                     |
| `attrs`   | (Optional) List of attribute structs                                               |

---

## `shared`
These items are given to all characters but are **intended to be equipped**, such as accessories or armor.

```json
{ "vnum": 15009, "pos": 2, "equip": true }
```

- Must specify a valid equipment position (e.g., 2 = wrist, 3 = shoes).
- `equip: true` places the item in the `EQUIPMENT` window.

---

## `jobs`
Job-specific equipment (e.g., armor, weapons), indexed by job ID:

| Job ID | Job     |
|--------|----------|
| `0`    | Warrior  |
| `1`    | Ninja    |
| `2`    | Sura     |
| `3`    | Shaman   |

Example:
```json
{
  "vnum": 11209,
  "pos": 0,
  "equip": true,
  "sockets": [0, 0, 0],
  "attrs": [
    { "type": 1,  "value": 500 },
    { "type": 53, "value": 30 }
  ]
}
```

---

## Notes

- All positions (`pos`) must be **manually specified**.
- Equipment positions follow the same logic as Metin2's `EQUIPMENT` window.
- `sockets` must contain 0–2 (default is 3, but this depends on your `ITEM_SOCKET_MAX_NUM`) integers, eg. `[0, 0, 0]`.
- `attrs` must contain objects with:
  - `type`: bonus ID (e.g. `1` = Max HP)
  - `value`: bonus value

---

## Reloading

To reload the JSON without restarting the server, use the GM command:

```
/reload give_basic_weapon
```
---

## Equipment Slot Index Reference

To determine the correct `pos` value for items marked as `"equip": true`, refer to the slot indices defined in `common/length.h`:

This is an example but check yours, last wear indexes may be different.

```cpp
enum EWearPositions
{
    WEAR_BODY           = 0,
    WEAR_HEAD           = 1,
    WEAR_FOOTS          = 2,
    WEAR_WRIST          = 3,
    WEAR_WEAPON         = 4,
    WEAR_NECK           = 5,
    WEAR_EAR            = 6,
    WEAR_UNIQUE1        = 7,
    WEAR_UNIQUE2        = 8,
    WEAR_ARROW          = 9,
    WEAR_SHIELD         = 10,

    WEAR_ABILITY1       = 11,
    WEAR_ABILITY2       = 12,
    WEAR_ABILITY3       = 13,
    WEAR_ABILITY4       = 14,
    WEAR_ABILITY5       = 15,
    WEAR_ABILITY6       = 16,
    WEAR_ABILITY7       = 17,
    WEAR_ABILITY8       = 18,
    WEAR_COSTUME_BODY   = 19,
    WEAR_COSTUME_HAIR   = 20,

    WEAR_COSTUME_MOUNT  = 21, // if ENABLE_MOUNT_COSTUME
    WEAR_COSTUME_ACCE   = 22, // if ENABLE_ACCE_COSTUME
    WEAR_COSTUME_WEAPON = 23, // if ENABLE_WEAPON_COSTUME
    WEAR_RING1          = 24,
    WEAR_RING2          = 25,
    WEAR_BELT           = 26,

    WEAR_MAX            = 32,
};
```

Use the corresponding `WEAR_XXX` value as the `pos` index for your equipment items in the JSON.

---

## Json Errors?

If you got some errors, use https://jsonformatter.org/, past the code and Validate.
It fill fix the file for you