# Usage

{% stepper %}
{% step %}

### Global Christmas Tree

Location is set via `Config.Tree.coords`.

#### Interactions (via target)

* **Open Christmas calendar**\
  Label: `Open Christmas calendar` (`target_open_calendar`)\
  → Tries to open the Advent Calendar NUI for today’s window.
* **Donate ornaments**\
  Label: `Donate ornaments` (`target_donate`)\
  → Consumes one donation item from `Config.DonationItems` and adds XP to the tree.

#### Rules

* Each donation:
  * Consumes *one* ornament item from the player’s inventory.
  * Adds XP to **global tree** and to the player’s personal total.
* Donating is limited by `Config.DonationsPerDay` per player per real day.
* Tree stage changes automatically based on total XP and `Config.Tree.stages`.
  {% endstep %}

{% step %}

### Santa Spots (local trees & gifts)

Santa spots are defined in `Config.SantaSpots`.

At each spot:

* A small decorative tree is spawned.
* Several `3m_xmas_gift` props are placed around it.
* Using target on a gift:
  * Prompts the player to **pick up the gift**.
  * Attaches a carry prop defined by `Config.CarryGiftModel`.
  * Player can only carry one gift at a time.
* The player must walk to the **main Christmas tree** and use the gift target:
  * The script turns the gift in and rewards:
    * A **random ornament item** (configured server-side).
    * XP is not directly added here; instead ornaments can be donated to the tree.
* Each player can receive only `Config.SantaSpotDailyLimit` rewards per real day.
  {% endstep %}

{% step %}

### Advent Calendar

The calendar is opened from the main tree (first target option).

#### Requirements

* The global event must be active (date within `Config.TimeWindow` or `Config.Debug.ForceActive = true`).
* The player must have the **calendar key item** defined by `Config.CalendarKeyItem` for the current event day.
* The player must not have already claimed that day’s reward.

#### UI Behaviour

* Shows 25 windows:
  * Locked / available / claimed states per day.
* On claim:
  * Server validates eligibility.
  * Rewards items defined in `Config.CalendarRewards[day]`.
  * Marks the day as claimed and updates NUI.
    {% endstep %}

{% step %}

### Santa Delivery Quest

The quest is controlled by `Config.Quest`.

#### Flow

* **Talk to the Santa NPC**
  * NPC is spawned at `Config.Quest.NPC.coords`.
  * Target label: `Help Santa Claus` (`target_santa_work`).
  * The player can start the quest once per event day.
* **Receive the van**
  * Vehicle spawns at `Config.Quest.Vehicle.coords`.
  * Keys are handled by `Config.Keys.provider`.
* **Deliver gifts**
  * There are multiple delivery points in `Config.Quest.Deliveries`.
  * At each point:
    * Player drives into the radius.
    * Leaves the van, picks up a gift from the van (prompt / target).
    * Walks to the exact drop point and delivers the package.
* **Return phase**
  * After all deliveries, the objective switches to returning the van.
  * Player must park inside `Config.Quest.Vehicle.returnRadius` near `returnCoords`.
  * Once done, the quest completes.
* **Rewards**
  * Global tree XP: `Config.Quest.TreeXP`.
  * Random reward items: `Config.Quest.RewardItems`.
  * Chance to receive `Config.Quest.KeyReward.item` (calendar key) with `chance` %.

Quest progress and daily completion are stored in the `xmas_players` table.
{% endstep %}

{% step %}

### Toys (placeable props)

Configured under `Config.Toys`.

#### Using a toy (example: `snowball`)

* When used (via inventory / QBCore usable item / your own code), client event `xmas:toys:UseFromInventory` runs.
* If `interactive = true`, the player enters **placement mode**:
  * Controls:
    * Arrow keys – move the previewed prop.
    * `Q` / `R` – rotate.
    * `PageUp` / `PageDown` – adjust height.
    * `ENTER` – confirm placement.
    * `BACKSPACE` – cancel (prop is removed and item refunded).
* On confirm, a server-side record of the prop is stored so it can be cleaned up properly.
* When interacting with a placed toy (e.g. snowman), the player can pick it up to get the item back.
  {% endstep %}

{% step %}

### Shoulder Plush Toys

Ped toys configured via `Config.PedToys`.

#### Behaviour

* When the player uses a plush item (e.g. `xmas_plush_elf`):
  * If no plush is active:
    * A prop is attached to a shoulder bone with configured offset/rotation.
  * If the same plush is already active:
    * It is removed from the shoulder.
  * If a different plush is active:
    * A notification is shown (“you already have a plush equipped”) and nothing changes.

State is cleaned up when the player disconnects or the resource stops.
{% endstep %}

{% step %}

### Weather

If `Config.ChangeWeather.enabled = true`:

* When the event is active:
  * Server locks weather to `Config.ChangeWeather.weatherType`.
  * Time freeze / dynamic weather / blackout are handled based on the provider.
* Clients ask the server for the current weather status on join (`xmas:server:Weather_RequestSync`).

If you don’t want weather to be affected, set:

{% code title="config.lua" %}

```lua
Config.ChangeWeather.enabled = false
-- or:
Config.ChangeWeather.provider = 'none'
```

{% endcode %}
{% endstep %}
{% endstepper %}

<details>

<summary>Developers / integrations</summary>

For scripting integrations (XP hooks, custom buffs for cookies/candy cane, custom UI, etc.) see:\
<https://3mstudio.github.io/3MStudioDocs/3M\\_Christmas/Developers.html>

</details>