Mystery Gift

This page describes the **Mystery Gift** system in Essentials.

## Overview

The Mystery Gift system allows players to download special gift Pokémon or items from the Internet. There is no limit on how many gifts they can download at once, nor on how many gifts are available at once. The game's creator may periodically change which gifts are available.

## Receiving a Mystery Gift

The first step is to allow the player to check for Mystery Gifts. They can only do this if `$player.mystery_gift_unlocked` is TRUE (it is FALSE by default). When this is set, there should also be an explanation given to the player of what it means.

Once this is set, the option "Mystery Gift" will appear in the Continue/New Game screen. By selecting this option, the game will check online to see if there are any gifts available which the player has not already downloaded. If so, then the player will be given the opportunity to download them.

All Mystery Gifts (downloaded and received) are stored in the array `$player.mystery_gifts`. Gifts which have been received are simply recorded as their unique ID number, while ones which have been downloaded but not received yet have more information saved.

To receive a downloaded Mystery Gift, you should first check whether there are any available. The method `pbNextMysteryGiftID` will return the ID number of the first downloaded gift which has not been received yet (or 0 if there are none). Then, the method `pbReceiveMysteryGift(id)` will give the player the gift with the given ID number.

There are examples of how to effectively set up Mystery Gift events (one to enable checking for gifts, and one to deliver gifts) in the example maps (the Poké Marts).

## Creating a Mystery Gift

The scripts relating to the Mystery Gift system are all in the script section **UI\_MysteryGift** (plus a few lines of code in **UI\_Load**).

At the top of this script section is the only thing you will need to edit, which is the URL of the Mystery Gift file for your game. It is important that you change this URL *before* you release your game, because you can't change it afterwards. By default, it points to an example file uploaded to Pastebin. You should find somewhere secure to upload your file.

The uploaded gift file can be blank, if you don't want any gifts to be available.

Creating a gift file for uploading involves two main steps.

### Step 1: Creating a gift

A Mystery Gift can be either a Pokémon in your party or an item in the Bag. The idea is that you create the Pokémon/item separately first, using various debug features to customise the Pokémon to your liking (items can't be customised, of course), and then insert it into a Mystery Gift.

Once you have a Pokémon/item you want to turn into a Mystery Gift, you should use the "Make Mystery Gift" debug feature for it (which appears when you interact with it in the party/Bag). This will *not* immediately export its information to a file for uploading, but will instead export that information to the file "MysteryGiftMaster.txt" in the game's folder (the Master file). The Master file records every gift you make for your game, and while it is possible to delete gifts from this record, you probably won't ever need to.

When using the "Make Mystery Gift" debug feature, you will be asked to give the gift a unique ID number and a name. Also, if the gift is a Pokémon, you can choose a phrase to be used as the obtain location (there are a couple of default choices), or if the gift is an item, you can choose how many of that item are to be included in the gift (if more than 1, then you can also set a "plural" form of the item's name).

### Step 2: Manage your gifts

Once you have at least one Mystery Gift defined, you can manage them. To do this, go into the main debug menu and choose "Manage Mystery Gifts".

Essentials will first check online to see if there is a Mystery Gift file already uploaded. If there is, then it makes a note of the unique IDs of the gifts in that already-uploaded file.

You will then be given a list of all the gifts in the Master file, with the already-uploaded ones marked. For each gift, you can do the following:

* Toggle whether the gift should be uploaded.
* Edit the gift's details. These are the same details as described above when using the "Make Mystery Gift" debug feature (i.e. the ID/name/obtain phrase/quantity/plural).
* Immediately receive the gift from the Master file. This allows you to edit the gift Pokémon if you need to. Note that you will need to create a new gift with the modified Pokémon afterwards, as you cannot replace the Pokémon in an existing gift. You won't need to use this option for gift items (because items cannot be modified).
* Delete the gift from the Master file.

Once you have selected all the gifts you want to be uploaded, choose the "Export selected to file" option. This will create a second file in the game's folder called "MysteryGift.txt". This file will contain only the selected gifts, and is the file you should upload to the Internet.