This page describes the Mystery Gift system in Essentials.
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.
IMPORTANT NOTE: Mystery Gifts can only be downloaded from a web page beginning "http", not "https". It is now much harder to find and make use of such a web address, meaning the Mystery Gift system is much less usable than it once was.
Receiving a Mystery Gift
The first step is to allow the player to check for Mystery Gifts. They can only do this if
$Trainer.mysterygiftaccess=true (it is
false by default). When this is set, there should also be an explanation 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
$Trainer.mysterygift. 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 allow 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 PScreen_MysteryGift (plus a few lines of code in PScreen_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 the old Essentials wiki. You should find somewhere else to upload your file, though (e.g. Dropbox), somewhere secure where the file cannot be tampered with.
As mentioned above, you can only use a url which begins with "http", not "https".
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 options to customise the Pokémon to your liking (items can't be customised, of course).
Once you have a Pokémon/item you want to turn into a Mystery Gift, you should use the "Make Mystery Gift" debug option for it. 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 option, 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 option (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. You won't need to use this option for gift items.
- 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.