HOWTO: Add custom cards and set to Forge

[RumbleBBU]

HOWTO: Add custom cards and set to Forge

I think one of the coolest things, among many others, about Forge is its customizability. You can customize your playing experience through the various in-game settings, avatars, skins, opponent decks, game worlds...and yes, even add custom cards and sets! The same exact functionality that makes it possible to quickly add new official sets also makes it possible to add new unheard-of sets and dream cards that never actually existed.

Of course this is no news to most of you - unless you've somehow managed to miss the sticky Custom Cards thread ( viewtopic.php?f=26&t=16205 ). But that particular thread does not contain actual how-to instructions that are suitable for beginners. And as it happens, I needed new cards for some specific quest opponents in one of my custom worlds, and I took notes as I went. Since I imagine other people might be interested in doing the same or in scripting their personal dream sets, I'm sharing my notes here.

Basically, to add a new playable card to Forge, you really only need to do 3 things:

1) Design the card. Magic Set Editor ( http://magicseteditor.sourceforge.net/ ) is free and good for making the image.
2) If you want, add the card to an existing set or create a new set for it.
3) Script the card and place it in res/cardsfolder/cardsfolder.zip.


It is very simple, in principle. But it can get hairy if the card you are trying to script is complicated.

Let's go through these steps in more detail...

I'm using one of my own custom cards as an example. I made this particular card because I needed a replacement for Dark Ritual. Many strong black decks relied on that card and the AI had no idea how to play it. On the other hand, I observed that the AI knew how to use a Black Lotus. So I thought, how about a replacement, an enchantment that works more or less like the Dark Ritual and can be used by the AI? And I came up with this card...

Oh yes, I know there is an existing MtG card with almost the same name (Forbidden Ritual). That doesn't bother me. I won't confuse the two (and neither will the AI), and what's more, I can be pretty confident that Wizards probably won't be using the name of my custom card for a later official card, which is a big plus.



1. Design the card

I used the Magic Set Editor and a random image for the card. You can download the editor at http://magicseteditor.sourceforge.net/

It is really simple to use. Just one important caution: Do not, I repeat, do NOT install MSE under Program Files. Install it somewhere else, in a user-writable directory.
Quoting the site: "There is a problem with Windows XP Service Pack 3 and any version of Windows thereafter treating the Program Files as read-only. Please install Magic Set Editor somewhere other than Program Files, e.g. your desktop, to avoid potential errors."



2. Add the card to a set

Generally, a card needs to be in a set or it will not function correctly in Forge. You can either add it to an existing set, or you can make a new custom set for your custom cards. I prefer the latter option. I do not like the idea of messing up the official sets, and any changes I make to them will be undone anyway when download and update to a new Forge version.

Set definitions

The set definitions can be found in the /res/editions/ folder.

A set definition file look will look like this:

Code: Select all

[metadata]
Code=ARB
Date=2009-04-30
Name=Alara Reborn
Code2=ARB
MciCode=arb
Type=Expansion
BoosterCovers=3
Booster=10 Common, 3 Uncommon, 1 RareMythic, 1 BasicLand ALA

(followed by the list of cards)

It is pretty much self-explanatory. The codes (Code, Code2, MciCode) are important. The set code is how Forge will internally recognize your set. It will also determine the images subdirectory for the card art of this set. Obviously, you want the 3-letter code to be unique! (And not likely to clash with any future sets Wizards could release - although changing the set code afterwards is not a big deal, just keep in mind the places where it is used.)

The Date has some effect on the game, for example, in deck editor, if you order cards by the set (date) column. It also affects their order in the Quest custom cardpool dialog.

The Name is, obviously enough, the display name of your new set.

The Type describes the set type. It can be Core, Expansion, or Other. I recommend you give your custom sets the type "Other". They will be listed in the last paragraph in the Quest custom cardpool dialog.

BoosterCovers tells how many different-looking covers there are for boosters in your new set.

The Booster line tells what it is a booster. The format is simply "(amount) (rarity)", comma-separated, as you can see.

Notes:
- If you include "BasicLand", you can also specify the set code for basic lands, e.g., "1 BasicLand 4ED", to use 4th Edition basic lands in these boosters.
- "RareMythic" means a "Rare or Mythic Rare card". If there are no Mythic Rares in your set, use "Rare" instead.
- If you specifically want to include a Mythic Rare in every booster pack, use "Mythic".
- "UncommonRare" means "an Uncommon or Rare card", relevant for some older sets.
- "Special" means a Special rarity card.
- "TimeShifted" is a time-shifted card.
- "dfc" means a dual-faced card.

You can also control the generation of random foils in your set by adding a "Foil=(value)" to your edition header. The possible values are "oldstyle", "classic" (these two do the same thing), "newstyle", "modern" (so do these two), and "notsupported". For example, if you don't want any random foils in your set, just put a "Foil=NotSupported" line there.

After this header section, there is simply the list of cards in alphabetical order, the section beginning with "[cards]".

Here's a sample line, an entry for a card:

Code: Select all

33 U Anathemancer

The first value is the card id number. It is actually optional, old sets (like Alliances) did not even use card numbering.

The other two values are obligatory. The first is the card rarity in this edition (C = Common, U = Uncommon, R = Rare, M = Mythic Rare, S = Special Rarity).

Note: If you want to have alternate art for cards (e.g., 5 different versions of each basic land), each alternate card version must be listed separately, for example like this:

Code: Select all

303 L Forest
303 L Forest
303 L Forest
303 L Forest
303 L Forest

Note that the card id# is the same for the different art versions.

For the purposes of this howto, I added a set called "Astral". In case you didn't know where the name came from, it is from the Microprose game. I'm using that set for storing cards like specifically tailored AI-friendly versions of existing cards, special cards for specific AI opponents, and some special Quest rewards. And that's where my Forbidden Rite will be going as well.

Adding a new set

To add a new set, just add a new .txt file to the res/editions/ folder.

You don't even need to create any new cards for your new set if you don't want to. It can be simply a collection of your favorite cards you want in a single set. To do that, you need nothing more than a set definition file containing the header metadata and the list of cards in the set (and their rarities). Of course if you want to get fancy, you could still design custom card art for your collection set.

Adding art

Place the card art for your new set in the cardPicsDir, defined in your forge.profile.properties, in a new subfolder named after the set code. Otherwise Forge will not use it. Important note: The format Forge uses for card art is "cardname.full.jpg". Don't forget the ".full." part, otherwise Forge will not display your images.

If you have different art versions of a card, the should named "cardname1.full.jpg", "cardname2.full.jpg", etc. (Also remember to add several entries for the card in the set definition file.)

The pictures of booster and box covers will go in your cacheDir (defined in your forge.profile.properties), in the subdirectories boosterboxes, boosters, and fatpacks, named after the set code. If you have more than one more than one booster art available, use the format "(set code)_(number).jpg", e.g. "ARB_1.jpg", "ARB_2.jpg", etc.

Custom sets in limited games

For limited games, you probably want to give your new set a draft ranking. Otherwise the AI will build monumentally bad limited decks.
The file you want to edit is res/draft/rankings.txt

Just add the draft ranking for your new set to the end of the file. The format for each line is:

Code: Select all

#(rank)|(cardname)|(rarity code)|(set code)

For example, "#19|Saheeli's Artistry|R|KLD"

The rank number (the first value) tells how desirable the card is in a limited game, in relation to the other cards in the set. The smaller the number, the better. Cards with large numbers are usually not very useful in limited games.

Also, to make your new set selectable in limited formats, you need to edit the res/blockdata/fantasyblocks.txt

After that, it can be selected for draft and sealed deck games under "Fantasy Block".


Custom sets in Quest games

For Quest games, you probably want to adjust the booster and card prices for your new set. Otherwise, default prices will be used, and they might not be realistic.

The booster prices can be found in res/quest/booster-prices.txt
Just add the lines for your new set.

The individual card prices can be found in a huge "all-prices.txt" file, which is in the db subdirectory of your cacheDir (specified in forge.profile.properties).

The format for card prices is simply, "(cardname)|(edition code)=(price)", for example:

Code: Select all

Evolving Wilds|DDK=19

3. Script the Card

This part could get a bit complex, especially if your card has some fancy functionality. Since there is already a lot of documentation on the wiki ( http://www.slightlymagic.net/wiki/Forge_API ), I will just cover the basics. The other good source of information is the collection of cards that have already scripted - if you know there already is a card that does almost what you need, it is a good idea to study the script of that card (with the help of the wiki) and use it as a base for your new card. Or if you are Java literate and absolutely must know how things work, there is nothing better than the actual Java source code: http://svn.slightlymagic.net/

The card scripts are stored in the huge cardsfolder.zip that you can find in res/cardsfolder/

CAVEAT: Before you start modifying this zip, it is a very good idea to make a backup of it! I've had Windows 7 Explorer break it, so I prefer to use 7-Zip to store my custom cards in it.

Currently the cardsfolder is in alphabetical order, so you should save your cards under the correct alphabet.

This is what my Forbidden Rite script looks like:

Code: Select all

Name:Forbidden Rite
ManaCost:B
Types:Enchantment
A:AB$ Mana | Cost$ Sac<1/CARDNAME> | Produced$ B | Amount$ 3 | SpellDescription$ Add {B} {B} {B} to your mana pool.
Oracle:Sacrifice Forbidden Rite: Add {B} {B} {B} to your mana pool.

It's a pretty simple spell which makes it a good starting example. Here's what the lines mean/do:

Name: The name of the spell. Well, duh, Captain Obvious. Note that this must match exactly the name used in the set definition file and the image filename.

ManaCost: The regular mana cost of the spell. Use numbers for generic mana (0 for a free spell), and letters W, U, B, R, G in any combination, e.g., "Manacost:10 W U U U U R G G". (Note the spaces between the symbols.)

Types: Card types. More than one type can be listed here, e.g., "Types:Legendary Creature Goblin Knight Horror".

The next line is the crucial one. It is the script for the actual card functionality. In this case, it is an "ability", more specifically a mana ability, introduced with the "A:AB$ Mana". The script parts are delimited with the "|" symbol.
The next part of this line is the cost required to activate the ability. In this case "Cost$ Sac<1/CARDNAME>" is read roughly as follows: "Cost: to activate this ability, you must sacrifice 1 of this card". There is a whole wiki page explaining what kind of costs you can have: http://www.slightlymagic.net/wiki/Forge_AbilityCost
Then there is the ability effect. "Produced$" specifies the color of mana produced (W U B R G or 1 for colorless mana), "Amount$" obviously enough the amount. The "SpellDescription" part is ability description displayed within Forge.

Then there is the Oracle text (Oracle:). I'm not sure this is even required for custom cards since Forge seems to derive its spell descriptions from the actual script. I don't think I've ever seen the Oracle texts I've written for my custom cards.

For creatures, there would be some more lines, most notably a "PT:(number)/(number)" for the creature's "printed" power and toughness (e.g., "PT:1/1"), and the various keyword lines beginning with "K:", e.g., "K:Trample" to give the creature trample.

For more information, see the API documentation:
http://www.slightlymagic.net/wiki/Forge_API

Official cards also have an image download link line. You can safely omit that line since you will be providing your own card images for you custom cards.

Great! So now we have a working Forbidden Rite! I've tested it, yes, and I can confirm that the AI can and does use it. Just ran into a turn two Spiritmonger ...ouch!
So if you have this awesome black deck that AI cannot use properly, just use the above instructions to add Forbidden Rite to your copy of Forge. It's a good exercise anyway. (And an easy one at that.)

I'm not saying that Forbidden Rite is a great card, it's merely a stopgap measure for a specific AI shortcoming. In an actual MtG game, Forbidden Rite would be problematic.
- It cannot be cast at instant speed, which severely limits its versatility.
- It is an enchantment, so it can be disenchanted (and also can be countered like the regular DR).
- OTOH, it actually gives you more mana on turn 2 than a Dark Ritual would (see the Spiritmonger example above). It will also stack more effectively than a DR, you can leave several on the board...for, say, on turn 2. And finally, since it is not called "Dark Ritual", you could 4 have copies of Forbidden Rite and 4 copies of Dark Ritual in the same deck (where legal), allowing for some really obscene mana ramping.

So yes, I believe there is a reason Wizards didn't do a "Seal of Dark Might" in the Masques block.

Final Words

If you are designing a complete new set, I heartily recommend reading Mark Rosewater's "Nuts & Bolts" article series on magic.wizards.com (if you haven't already):

http://magic.wizards.com/en/articles/ar ... 2016-02-15

Even if you don't necessarily always agree with him, this will give you a lot of insight why Magic sets are constructed as they are. Also, keep in mind you are not writing a custom set for public commercial release. You are writing it for your own enjoyment. This is a computer game, not a DCI tournament. Which gives you a lot more freedom.

For one thing, I find that the "block" thinking is not really relevant here. The size of your custom set is not set in stone, nor are even its contents, since there is no "deadline" when it goes to "print". You can keep modifying the set as you go, add new cards, and remove or modify ones that don't work that well (or work TOO well).


Was this 'howto' useful to you? Did I get something majorly wrong? Did I forget something crucial?

[Hanmac]

Also keep in mind that Forge is still in Flow and Hanmac (me ;P ) does like to rewrite old stuff.
That means that custom cards which worked before might not work in later versions.

[RumbleBBU]

I've scripted quite a few custom cards now, and would like to add a couple of comments based on my experiences.

Firstly and most importantly, contrary to what I wrote above, I'm actually finding it useful to do things in the exact opposite order, i.e., first script the card, then add it to a set, finally design the card image. Why? Mainly because it has happened sometimes that I'd designed a great card and then simply forgot to script it! If I had done it the other way around, I would have noticed the missing card art immediately. I also sometimes need to make changes to the card when scripting it - either there's something wrong with the concept (maybe over/undercosted) or it turns out that the Forge engine does not fully support the intended behavior.
Plus, it's more rewarding to do things this way - the tedious part (scripting) first, the fun part (card art design) last.

Secondly, if you want to have random functionality in your cards, I suggest you take a look how Master of the Wild Hunt Avatar is scripted. The same principle can be adapted to a lot of things. I have successfully scripted several Microprose cards based on that example, including Gem Bazaar, Rainbow Knights and Necropolis of Azar (although there is a slight cosmetic difference in how my implementation of Rainbow Knights works compared to the original - and I also made the Necropolis activation cost instead of , I thought it was simply not worth it at ).

And finally, there was an obvious (repeated) typo in my instructions above. Of course, if you want to script a creature, you need to say "P/T:2/2", not "PT 2/2". But this was obvious to you already if you scripted a single creature. Sorry about the missing colon!

By the way, I've also finally successfully compiled the current forge with NetBeans. Only...I haven't had tried coding much recently. I'm having way too much fun scripting my fantasy cards! Currently doing two sets, the aforementioned Astral set, which is a mish-mash of just about everything official Magic releases lack and my own Quest mode special cards, and a second one, which is a bit more designed (balanced) private standalone set.

[friarsol]

And finally, there was an obvious (repeated) typo in my instructions above. Of course, if you want to script a creature, you need to say "P/T:2/2", not "PT 2/2". But this was obvious to you already if you scripted a single creature. Sorry about the missing colon!

Uhh this is still wrong..

The Wiki has all of the basic info about scripting -- http://www.slightlymagic.net/wiki/Forge_API

"PT:2/2" not "P/T:2/2" and not "PT 2/2"

[RumbleBBU]

And finally, there was an obvious (repeated) typo in my instructions above. Of course, if you want to script a creature, you need to say "P/T:2/2", not "PT 2/2". But this was obvious to you already if you scripted a single creature. Sorry about the missing colon!

Uhh this is still wrong..

The Wiki has all of the basic info about scripting -- http://www.slightlymagic.net/wiki/Forge_API

"PT:2/2" not "P/T:2/2" and not "PT 2/2"

Well yes, you are correct.

Chalk my last entry up to "The worst errata ever".

I've now errata'ed the original post accordingly.

[Steve44]

I've spent hours tonight trying to get Forge to open with my custom set in /res. Without my set, it opens fine. With my set, it doesn't throw an error or anything, it just never gets past "Welcome to Forge."

The set file is attached. I've gotten this to work a couple of years ago on an older version, but currently nothing will work. Can anyone see what I am obviously screwing up?

[friarsol]

I've spent hours tonight trying to get Forge to open with my custom set in /res. Without my set, it opens fine. With my set, it doesn't throw an error or anything, it just never gets past "Welcome to Forge."

The set file is attached. I've gotten this to work a couple of years ago on an older version, but currently nothing will work. Can anyone see what I am obviously screwing up?

Can you check your forge.log file?

[Steve44]

I've spent hours tonight trying to get Forge to open with my custom set in /res. Without my set, it opens fine. With my set, it doesn't throw an error or anything, it just never gets past "Welcome to Forge."

The set file is attached. I've gotten this to work a couple of years ago on an older version, but currently nothing will work. Can anyone see what I am obviously screwing up?

Can you check your forge.log file?

Looks like this is all I get:

Language 'java.util.PropertyResourceBundle@a570f' loaded successfully.
(ThreadUtil first call): Running on a machine with 8 cpu core(s)
main > java.lang.NullPointerException
at forge.util.FileSection.parse(FileSection.java:97)
at forge.card.CardEdition$Reader.read(CardEdition.java:280)
at forge.card.CardEdition$Reader.read(CardEdition.java:246)
at forge.util.storage.StorageReaderFolder.readAll(StorageReaderFolder.java:90)
at forge.util.storage.StorageBase.<init>(StorageBase.java:42)
at forge.card.CardEdition$Collection.<init>(CardEdition.java:360)
at forge.StaticData.<init>(StaticData.java:43)
at forge.model.FModel.initialize(FModel.java:148)
at forge.Singletons.initializeOnce(Singletons.java:53)
at forge.view.Main.main(Main.java:48)

[Steve44]

Even stranger - I deleted all but one card from my set, tried to start Forge, and it failed.

Next, I simply deleted everything in the [cards] section of an existing set (I chose Beta) and replaced it with the cards from my custom set, and everything booted up fine.

I've gone over my header formatting a million times - am I missing something obvious? If not, why might Forge freak out simply by virtue of adding one more set than it "expects?"

[History303]

Did anyone ever figure out how to fix the issue Steve44 was having? I'm having the exact same issue: .txt file in editions looks formatted properly, Forge won't go past "Welcome to Forge".

[rotarygxp]

I'm trying to script some creature cards with phyrexian mana symbols and dual mana symbols but what should I use for the mana cost instead of the usual W, U, B, G, R?