Setup for adding cards into a simulator

Generally, a card needs three components in order to be correctly implemented into the simulator: an entry in the card database, an image, and a script. Once a card's data have been inserted into the database, said card will already be visible in the Deck Edit menu, and can be freely added to the Main, Extra, or Side Deck. If a card does not have an associated image, the simulator will use a grey placeholder to replace the missing picture in the game. Of course, you will not be able to effectively use your custom cards during a Duel if you do not provide them the required scripts.

This page contains various information regarding the preparation of each of the aforementioned component, including instructions on how to correctly implement your files, and what programs you need to use in order to create them.

Card databases
Card databases contain data on each card present into the simulator. You can recognise these files by their extension (.cdb). In order to create and/or open a .cdb, you need to use specific programs, such as SQLiteStudio or DataEditorX. Any SQL editor a perfectly valid choice, but DataEditorX (often shortened to DEX) is arguably the best option, due to its user-friendly interface, ease of use, and its compatibility with other programs that will be introduced later; therefore, this section of the page will concentrate exclusively on how to use DEX.

DataEditorX
You can download DEX here: https://github.com/247321453/DataEditorX. If you intend to script for EdoPRO, it is also suggested to download the cardinfo_english.txt file from this fork (https://github.com/NaimSantos/DataEditorX) and place it inside your local DataEditorX / data folder.

Changing default language
Once you start the application, you can change the language used by the interface. The default option is Chinese, but you can switch to English by following the path showed in the picture below.

Create and open card databases
To create a cdb, click on File in the Menu bar at the top of the window, and select the New option. After that, choose the folder where you want to save your .cdb, and assign it a name. After doing this, the program will ask you if we want to open the newly created file: select Yes. If you want to open an already existing .cdb, click on File, select the Open option, and navigate to the file that you want to access. DEX also keeps a history of the latest databases you accessed: if you hover on, you can quickly open one of the databases that appears on the list.

Card name
Insert the card's name inside the bar at the top of the window.

Rule
Simulators categorize the cards accordingly, depending on the format in which they can be used. In the Deck Edit menu of your simulator, you will find your custom card in the correspondent category you selected.
 * If you are scripting for KoishiPRO, select the Anime option for your customs.
 * If you are scripting for EdoPRO, and downloaded the cardinfo_english.txt file from the fork, select the Custom option, instead. Otherwise, you can select Anime.

Card Types
You can set the type of your card by ticking the corresponding checkboxes. Multiple selection is allowed. Some checkboxes can enable/disable certain fields: for example, by ticking the Link checkbox, the Link Markers field is enabled, whereas the DEF box is disabled.

Attribute, Level, and Race
Select the Attribute, Level (Rank if you are adding an Xyz Monster, Link Rating if you are adding a Link Monster), and Monster Type (e.g. Warrior, Fairy, etc.) of the card. If the card you're adding is not a monster, leave these fields blank.

Archetypes
DEX allows you to assign your card to up to four different archetypes. - If you want to assign your card to an official TCG/OCG archetype, click on the button labelled No Archetype and select the desired option from the list. The contents of this list depend on the content of your local  file. - Alternatively, you can digit an hexadecimal code (ranging from  to  ) in the small fields on the right. You can only use codes that have up to 3 digits, unless you want to assign your card to a subarchetype, in which case you will have to use a code with 4 digits. If the code you selected is already found in the  file, the name of the archetype associated with that code will appear on the button at the left; otherwise, DEX will show the label Custom.

Link Markers
If you are adding a Link Monster, select its original Link Arrows.

PScale
You can assign the Pendulum Scales of your card (the left field determines the left scale, and the same principle applies for the right one). You are allowed to set different scales, and to also assign scales to non-Pendulum cards.

ATK/DEF
Write the ATK and DEF printed on the card. You can either insert a non-negative integer, or a single question mark (?). The number  is equivalent to.

Card Code
This box must contain a positive integer, which represents the original ID of your card (offically called "passcode"). Official TCG/OCG cards have IDs with up to 8 digits, thus it is recommended to choose a 9-digit integer for your ID in order to avoid conflicts. If you are scripting for EdoPRO, you should also avoid the ranges specified below, as they are reserved for certain types of cards.
 * In KoishiPRO, the range of possible numbers to choose from goes from 1 up to 268 435 455. Technically, it is possible to exceed this range (up to 232 - 1, which is 4 294 967 295) but doing so can cause an overflow of the integers that are linked to the description strings and "Once per Turn" restrictions. This means that the text of these strings will be displayed as  in-game, and the turn limitations of some effects will not work as intended.
 * In EdoPRO, the range of possible numbers to choose from goes from 1 up to 4 294 967 295, without incurring in the issues presented before.
 * Passcodes with 9 digits in the 10ZXXXYYY range are reserved for pre-release TCG/OCG cards
 * Passcodes with 9 digits in the 100XXXYYY range are reserved for Video Game cards.
 * Passcodes with 9 digits in the 160XXXYYY range are reserved for Rush cards.
 * Passcodes with 9 digits in the 300XXXYYY range are reserved for skill cards.
 * Passcodes with 9 digits in the 5ZZXXXYYY and 200XXXYYY ranges are reserved for anime/manga cards.

Alias
In the TCG/OCG, there exist some cards that are always treated as having a name that is different from the one printed on them. For instance, the name of the card "Cyber Harpie Lady" is always treated as "Harpie Lady" due to a name condition specified in its effect text. This rule applies not only during Duels but also while constructing a Deck. Due to the fact that you are restricted to having a total of three copies of "Harpie Lady" in your Main, Extra, and Side Decks combined, if you already have three copies of the original "Harpie Lady", you cannot include "Cyber Harpie Lady" in your Deck. (You can still play both cards as long as their combined number in your Main, Extra, and Side Deck does not exceed 3.)

If you want your card to be treated as having a name that is different from its printed one, fill the Alias box with the ID associated with the desired name. From now on, we will use the following definitions: the number in the Card Code box will be the original ID of the card, whereas the number in the Alias box will be the alias ID of the card. For example, the original ID of "Cyber Harpie Lady" is 80316585, while its alias ID is 76812113, which is the same as the original ID of the "Harpie Lady".

Since we are still working with IDs, the same rules explained in the previous section also apply here. In addition, you also have to follow these instructions: Failing to comply with the above instructions can cause unexpected errors during a Duel since functions like  return different values depending on the difference between the alias ID and the original ID.
 * If the card you are adding to the database is meant to be an alternative artwork of an already-existing card, then the difference between the IDs in the Card Code and Alias boxes must not exceed 9. For instance, if the original artwork card has an ID of X, the alias ID of the alternative artwork card must be between X-9 and X+9, inclusive.
 * If the card you are adding to the database is always treated as having the same name as already-existing card, but is not an "alternative artwork" of the latter, then the difference between the IDs in the Card Code and Alias boxes must exceed 9.

Description
The large box that occupies the bottom part of the window is meant to contain the card's text (either the effect's text, or the flavour text in case of Normal Monsters).

Categories
By ticking the various checkboxes, you can assign the correspondent tags to your cards. In the Deck Edit menu of your simulator, you can then search cards based on these tags. These tags have no impact on gameplay, so assigning them is completely optional.

Tips Texts
The blank space at the bottom-right corner of the windows comprises 16 empty fields (not visible in the image). You can selected these fields by clicking on them: the selected field will be highlighted, and you can start filling it with text by typing in the wide box underneath. Each string inserted into these fields has its own ID. While writing a card script, you can access these strings by their ID, which can be generated by invoking the  function. You must pass 2 arguments when invoking this function: the first is the original ID of the card that contains the string in its database entry, the second is an integer that goes from 0 (which represents the top string in the Tips Texts section of the card with that original ID in DEX, starting from the top) to 15 (which represents the bottom string).

Adding a card to the current database
Once you have entered the appropriate values in each field, you may add the card to the current database by clicking the Add button located in the bottom-right corner of the window. Alternatively, you can add the card immediately after entering the original ID in the Card Code box and update the entry at a later time. If you attempt to add a card without entering the original ID, an error will occur. Furthermore, you cannot add a card with the same original ID as another card in the current database.

Database Pages
After a card has been added to the database, its entry will appear in the column at the left of the window. This column is akin to a "page" of a book: these pages show a list of all card entries present in the current database. Each page contains a limited number of entries and you can switch between them using the arrow buttons at the bottom. To navigate to a specific page, you can input the page number in the box next to the left arrow button and hit Enter.

Modifying a card of the current database
By clicking on a card entry listed in the left column, all the data fields will be automatically filled with the values associated with the selected card. If you edit the values in any of these fields and then click the Modify button, the changes will be applied to the entry of the database. If you edit the original ID of a card and then click Modify, DEX will first ask you whether you want to create a new entry with the new ID or directly overwrite the current one. If you select Yes, the entry with the "old" ID will not be deleted, and a new entry with the inputted ID is created. If you select No, no new entry is created, and the "old" ID of the modified entry is simply replaced by the new one.

Resetting the data fields
If you click on the Reset button, all the data fields will be cleared. This action does not delete an entry you were currently selecting. Resetting the data fields is a fast and safe method to start the creation of a new entry from scratch

Searching an entry in the database
If you set certain values in any data field, and then click the Search button, DEX will generate a list of all entries in the current database that match the values you inserted and displays it in the left column. If you want to return to the full list of entries, click Reset and then Search.

Deleting a card of the current database
If you select a card entry from the left column and then click the Delete button, the selected entry will be deleted. DEX will always send you a message of confirmation before performing this operation, in case you inadvertently clicked the button. If you want to retrieve a deleted entry, you can click the Undo button.

Reverting changes
If you wish to undo the changes made to the database, you can click on the Undo button. This functionality also allows you to retrieve deleted entries. However, you should exercise caution when performing this action since you might unintentionally erase card entries that were added recently, or cancel the latest modifications.

Managing multiple open databases
Once you have opened a cdb, its name will be displayed in the Database bar, located directly beneath the Menu bar. It is possible to have multiple databases open at the same time, with each new database name appearing to the right of the last one. The name of the database you are currently viewing will be highlighted. To navigate from a database to another, simply click on the name of the database you want to view.

You may rearrange the order of the databases displayed in the Database bar by clicking-and-dragging a name to a new position.

Additionally, when you click-and-drag the name of a database, nine icons will appear on the screen: four at the edges of the window (one for each edge), and the remaining five at the center placed in a cross pattern; by dragging the database name to one of these icons, the window will split, and the dragged database will occupy the section of the window indicated by the selected icon. Once the window is split into different sections, you can modify the size of each section by clicking at its edge and dragging the new edge (represented by a bold black line that will appear on the screen) to a new position. The purpose of each icon is described in this list:
 * The four icons surrounding the central one will always split the current section of the window in half, as evidenced by the shaded area that appears when hovered over.
 * The icons located at the edges behave similarly to the previous ones, but instead of always splitting in half, they remember the size assigned to the section you assigned to the latest section you created with them. A shaded area will appear when you hover over these icons, and shows you a preview of the size of the section that it is going to be created.
 * If you want to move a database from a section to another, click on the name of the database you want to move and drag it to the central icon (or to the Database bar) of the section you want to move it in. If you move the last remaining name of a section to another one, the two sections will merge.

If you drag a name from the Database bar to an empty space, DEX will create a new window showing the selected database only. You can move databases from a window to another, split these new windows into sections, and merge them with other windows.

Keep in mind that the Database bar is present only on the main section of the main window. If a database is moved to a different section or window, its name will appear either at the top or bottom of that section or window, and can be clicked and dragged accordingly.

Copying and pasting entries from a database to another
If you select a card entry from the left column of the window, you can click  to copy that entry. After that, if you move to a different database, you can paste the copied entry by clicking. You can determine the amount of entries that will be pasted by looking at the number that appears next to.

Selecting multiple card entries at once
If you want to select multiple cards entries, you can follow various methods. The selected cards can then be deleted all at once, or copy-pasted to other databases.
 * 1) Click on an unoccupied row of the column at the left of the window, hold down the left mouse button and slide the cursor over the items you want to select. Once the button is released, the selected cards will be highlighted in blue.
 * 2) Hold down the   key and click once on each entry you want to select. Once the selection is complete, release the   key. This method allows you to select multiple card entries that are not adjacent to each other in the list.
 * 3) Click on an entry in the list, then click on another entry while holding down the   key. This way, all the entries located between the first and second items (included) will be selected.

Card images
A card needs an image in order to be easily identifiable by the players. Card images are acceptable in either the .JPG or .PNG file format. The recommended dimensions are 177x254, or 421x614. The name of the image file must be the original ID of the card it represents. (For example, if a card has 12345678 as original ID, its image will be named  or  ). Simulators also allow Field Spells to have an additional image that acts as the field's background while they are active in the Field Zone: the recommended dimensions for these images are 512x512. As for the name of these images, follow the same rule as before.

In order to generate images of your custom cards, you can either look for an online card maker site, or use programs such as Magic Set Editor (which is also compatible with DEX).

Card scripts
A card needs its own script in order to be played within the simulator (unless the card is a non-Pendulum Normal Monster, in which case a script is not required). Card scripts are  files, written using Lua as scripting language. The name of the script must start with the lowercase letter, followed by the original ID of the card it is linked to. (For example, if a card has 12345678 as original ID, its script will be named ).

Since card scripts are simple text files, they can be created, opened, or edited with any text editor, even with the basic Notepad app bundled with your OS. That said, it is heavily recommended to use programs that provide syntax highlighting for the LUA Language, such as Notepad++.

Where to allocate your files
In the root folder of your simulator, create a folder named expansions (if it does not already exist). Open that folder and create the pics and script subfolders inside it. If you want to add background images for Field Spells, you can also create a field subfolder inside. Keeping all your custom files in the expansions folder makes them easier to manage, and also eliminates the risk of them getting overwritten and/or deleted by the automatic updater of your simulator (that goes especially for EdoPRO).
 * Card databases (.cdb files) go into
 * Card images go into . Background artworks for Field Spells go into
 * Card scripts go into