BA development guide

[FranAvalon]

Overview
==================================================

This page will help you get started on adding new cards and modifying old cards in the BotArena project. You will be able to test your additions and changes before posting the new code in the forum.

Tools
==================================================

You will need:

• Visual Studio 2010 Standard, Professional or Team (not the free Express version)
• Install Visual Studio 2010 SP1
• Apply all Visual Studio related Windows Updates. You may need to do multiple rounds of updates to get all of them.
• TortoiseSVN from http://tortoisesvn.tigris.org/. This software will help you to download and upload source files from our code repository. Note that this free software modifies your Windows shell to show additional information about files. You may be able to turn off that feature only. It also installs command line tools ‘svn’ so you can also use it from command line only.
• (Optional) AnkhSVN from http://ankhsvn.open.collab.net/. You do not need TortoiseSVN if you install this one. AnkhSVN integrates into your Studio environment and so you can update and commit changes easier. However from my limited testing of it, it is buggy (but still free.) In my opinion TortoiseSVN is a lot more stable.
• (Optional) VisualSVN from http://www.visualsvn.com/. This is good product and it integrates with TortoiseSVN and Studio.
• (Optional) 7-zip (to upload zipped DLLs for other card developers to use)

Files and Versions
==================================================

You will need to download the following files:

* Download the latest BotArena release and install the msi file.
* ‘Checkout’ the latest code from the ‘trunk’ ‘head’:
1. Decide a location in your hard disk where you want to code, e.g. C:\BotArena
2. Right click on the folder, choose 'SVN checkout'
3. In the URL field, enter 'http://svn.xp-dev.com/svn/BAOS/trunk'
• In the Checkout directory, enter 'C:\BotArena'
• Checkout depth should be 'Fully Recursive'
• Revision should be 'HEAD'
4. It will ask for you user name and password if you haven't entered it already. It will then download all the source code.

The BotArena installer will install the following essential files:

• MagicCore.dll - Core logic and rules
• EpochLib.dll - Misc code not specific to MTG
• BotArena.exe - UI code
• Six.dll, Ten.dll, etc - Expansion components allowing dynamic creation of cards

It is important to match the card project's core dll file versions with those used by the BotArena.exe:

You downloaded BotArena 1.44.1 -> You created a new six.dll by using the source from XP-Dev at the revision of 1.44.1 -> OKAY to use the new six.dll with BotArena 1.44.1

I released a new BotArena 1.44.1 -> You created a new six.dll by using the source from XP-Dev at the revision of 1.43.1 -> NOT OKAY to use the new six.dll with BotArena 1.44.1, only okay with BotArena 1.43.1

Modifying Cards and Fixing Bugs
==================================================
To open the whole project you must open the file "MagicWand.sln" which can found on "Magic/magicwand" folder.

In each card expansion project, you will find a few essential files:



The .cpp file has all the card code for each card, e.g.:



The .h file ‘declares’ the card code:



The String table in the resource view has all the card text:



To fix a simple typo of a card, all you need to do is to modify the card’s corresponding text in the string table above.

To fix a broken card’s code, locate and modify the card code in the .cpp file.

Now if you edit any file in Studio which is tracked by TortoiseSVN, you should see the green check mark in Windows Explorer change to a red exclamation mark.

After you have made all the changes, remember to modify the version number of the module so that you can tell where a card module dll file is from. To do that, double click the magiccore.rc2 file here:



You will see the following file in the Visual Studio:



Modify the third number (‘4’ in this case) to a higher number. Note that doing so will cause all card expansion modules’ version number to be changed, not just the card project you are working on.

There are two project configuration types to control what kind of code to use:

• Release – lean and fast code for release
• Debug – fat and slow code for runtime debug purpose

At this stage you may want to stick with the ‘Release’ configuration because runtime debugging may be too involved if you just started C++ programming. To make sure you are using the release configuration:



After you have done the above, you are ready to let the computer to do all the hard work of compiling your project. To do that, on Solution window, right click on "BotArena Setup" and select the "build" option. Of course you can compile only a dll file, in the same way.

In some rare occasions when your changes are not taking effect or the project is acting weird, you may need to use the ‘Rebuild Solution’ option instead to clean the system for damaged files etc.

If there are no errors in your changes, you will see the following message in the output window:



To find the finished card file, go to the release sub-directory in the card project directory:



To double check the version number of the dll, right click the file and select properties, go to the version tab:



Now just copy the new dll file and overwrite the one installed by BotArena and you should be able to test the change.

After you have done all your changes, you can right click on your working folder e.g. 'C:\BotArena' and select 'SVN commit'. Wait for the system to find all the changes you have done since your last commit. Enter a comment in the top box, e.g. 'Added Serra Angel card'. Click OK and the changes will be uploaded to XP-Dev and ready for download by other members.

Adding New Cards
==================================================
Again, in each card expansion project, you will find a few essential files:



In the case that all you want is to add a new card text for an already supported card, you just need to put the new card text into the string table. For example, if you want to add Eager Cadet into the BOA expansion, just add this line into the string table:



Note that since Eager Cadet’s code is already defined in Seven’s project, this is all you need to do.

One important thing is that you must make sure the IDs used in the new card text is the NEXT highest number from the last one. In this example, the number ‘3431’ is important. The reason is that the core engine stops searching cards once an ‘empty’ slot is found in the card project. So if you put down ‘3432’ and ‘3431’ is empty, the new card will not be found.

After this, follow the compilation steps listed in the ‘Modifying Cards’ section to test the new module.

Now to add a completely brand new card, follow the above steps to add the new card text. After that, you will need to add a new card ‘declaration’ to the .h file:



Usually these 3 lines of code is all you need to add in the .h file but the ‘: public CCard’ part may need to be changed to match the card’s purpose, e.g. ‘: public CCreatureCard’ for creature cards. Technical: You are defining a new C++ class and this declaration tells the system that the new card class is ‘derived’ from another existing class.

Note that the convention for a new card ‘class’ name is:

C{CardName}Card

The {CardName} part should be the new card’s name without any space and each starting character of a word in the name should be capitalized (including ‘of’, ‘and’, etc.) Hyphenated words count as one word and apostrophes are removed (e.g. Ur-Golem's Eye -> CUrgolemsEyeCard.)

In the .cpp file, you will put the new card code at the end of the file:



After that, add a new line to allow the core to find the code in the CreateCard() function at the beginning of the .cpp file:



Note that to keep the list organized, the cards in this list is sorted.

After this, you are all set and again follow the steps in ‘Modifying Cards’ section to compile and test the new card file.

Special note about the MTG module: this module contains the basic land code plus the token code and token card text. To add new tokens, you can follow the card creation process described above but all tokens must ‘derives’ from ‘CTokenCreature’ and the token must be listed in CreateToken() instead of CreateCard() at the beginning of the .cp file:





Note that token class names should end with ‘Token’ instead of ‘Card.’

Creating New Card Modules
==================================================

I have created a sample project to use as a template to create new card projects.

Download New Set files

Unzip the zip file into the Magic directory like so:



Follow these steps to rename the project into the desired expansion name. As an example, I will name my new expansion ‘Star Ship’.

1. Rename the ‘NewExpansion’ directory to ‘StarShip’ (no space)
2. Rename all files in the directory with names containing ‘NewExpansion’ to ‘StarShip’, e.g. CardNewExpansion.cpp to CardStarChip.cpp.
3. Double-click the CardStarShip.cpp file, find and replace all ‘NewExpansion’ to ‘StarShip’
4. (Optional) Edit the .ico files. You can use GIMP which is a free application to create icons and graphic files.
5. Right-click on the .rc file (DO NOT double-click on the file), select ‘Open with’ and ‘Notepad’:



o Once inside Notepad, find and replace all ‘NewExpansion’ with ‘StarShip.’ Then replace all ‘New Expansion’ with ‘Star Ship.’
o Find this section of code in the rc file:



o Most of the fields in the section is easy to understand. The IDS_FIRST_CARD, IDS_MODULE_ICON_ID and IDS_MODULE_LARGE_ICON_ID fields need a bit more explanation. All cards in BotArena have an internal ID. The ID is global among all card expansions so you need to make sure the ID you use is not already used by another expansion. Here are an example of the existing IDs used:

MTG – 220 – 249 (cards)
Six – 300 – 649 (cards), 650 (icon), 651 (large icon)
Seven – 700 – 1049 (cards), 1050 (icon), 1051 (large icon)
Unlimited – 1100 – 1401 (cards), 1450 (icon), 1451 (large icon)
Eight – 1500 – 1861 (cards), 1862 (icon), 1863 (large icon)
Nine – 2000 – 2358 (cards), 2359 (icon), 2360 (large icon)
Planar Chaos – 2500 – 2664 (cards), 2665 (icon), 2666 (large icon)
Ten – 3001 – 3383 (cards), 3398 (icon), 3399 (large icon)
BotArena – 3401 – 3499 (cards), 3500 (icon), 3501 (large icon)

In this case I can keep the default 4000 in the IDS_FIRST_CARD field because that is not used. The icon ID field is just the next ID available. In this case 4000 + 300 cards = 4300. The large icon ID is the next ID available also (4301.)

o After you made all the changes in the rc file, save it in notepad and exit
6. Again using right-click, open the .vcproj file in notepad. Find and replace all ‘NewExpansion’ with ‘StarShip.’ Save and exit.
7. Double-click Resource.h file and change the IDS_MODULE_ICON and IDS_MODULE_LARGE_ID fields with the numbers used in the .rc file:
a.
b. Save and close the file in studio after the change.
8. Open the CardProjects.sln file in studio
9. Right-click on the top solution node in the Solution Explorer window, select ‘Add’ and then ‘Existing Project’:
a.
b. Browse to the StarShip.vcproj folder and select it to add to the solution.
10. Finally you are done. Follow the ‘Adding New Cards’ section above to start adding cards to the new expansion.

Getting Changes from Other Members
==================================================

Now if other members have some changes you want to use:

1. Right click on 'C:\BotArena', select 'SVN update'
2. It should find all the changes since your last checkout. Note that if a file is changed by you and someone else, TortoiseSVN may say the file has 'conflicts'. Don't panic and you can fix the conflict by opening up the conflict editor. You should be able to see what needs to be merged, e.g. you and another person changed the exact same line.
3. Now you have the most up-to-date source code.

Before each major release, me or someone from the card team will branch the trunk head to the ‘branches’ URL, e.g. 'http://svn.xp-dev.com/svn/BAOS/branches/1.43.1'. That way I can easily sync all card changes into my own projects. It also provides a fixed reference just in case we need to go back to look at a release’s source code.


--------------------------------------------------------------------
Here is a downloadable tutorial for development. here is the link:

Download tutorial

[FranAvalon]

Update the first post.

[FranAvalon]

I forgot to say how to open the whole project, so I've updated the tutorial:

"To open the whole project you must open the file "MagicWand.sln" which can found on "Magic/magicwand" folder."

[bahrep]

I'd like to make a note: VisualSVN (Visual Studio extension mentioned in the initial post) is free. I.e. it works on non-domain machines without paid license (Community license activates if you are not in domain)

[FranAvalon]

Thx. Edited first post

[isochron]

I am trying to build Botarena and noticed that QT is required. Which version of QT does it need? This is not mentioned in the documentation.

[FranAvalon]

Currently we are trying to upgrade the UI, and Korry chose QT to improve it. However we have some important problems and this way is stopped now.
Actually, QT is not requered at all, so just open the magicwand.sln file that you can found on Magic/MagicWand folder and that will open the whole project. After that,you can compile the game right clicking on "BotArena Setup" and selecting the "build" option.

In case that you want to try QT, you can download it from here if you are using a 32bits OS:

download.qt-project.org/official_releases/qt/5.0/5.0.2/qt-windows-opensource-5.0.2-msvc2010_32-x86-offline.exe

However, as I said you before, QT version (aka BotArena2) doesn't compile, which could be fixed by us, at least by the moment. Can someone help us here?

[isochron]

Thank you,

The code has successfully built. 0 Errors, 0 Messages, 0 warnings

However when I run the .exe the game window appears without graphics (table top background etc.) and some of the icons are missing (ie the turn stages icons (Untap, upkeep etc are missing from the form) Also the cards are not appearing to build decks with.

Do I have to install on my machine my newly built code? To see graphics and cards?

Unfortunately I am not a QT person so I am happy to hear the software does not need it.

Thank you for your continued support,

Regards

[FranAvalon]

Which S.O. are you using? Try to set the app to compatibility mode with XP Sp3 and try if this help. Currently I am using Win XP SP3 and Win8 64bits (compatibility mode XP SP3) and all is ok.

[isochron]

I am running Vista. Botarena the official release works on my machine. I changed the compatibility mode to XP Sp2 on my newly built exe and still the same problem. It appears that my built botarena is not finding some of the graphics resources.

I will try a clean build and let you know

[FranAvalon]

Let me know your try. I remember that some people had problems on Vista. I can't tell you because I never try that O.S., but if official releases works, that is weird

[isochron]

After building the game how do you run the game? From an exe or installing the msi? IS it from Visual Studio? Also where is the point you run it from located?

[FranAvalon]

I install de msi file and run the botarena.exe

[isochron]

What was causing my issue was, I did not have any Botarena installed on my machine so when I ran my new build code from Visual C++ in Coreapp.h some of the paths in the code below were defaulting to C:\Program Files\EpochSoft\BotArena which did not exist and other paths defaulted to where my code was built (M:\BAOS Latest Build). Therefore only some assets were found.

Code: Select all

CString GetModuleFileName() const   { return m_strModuleFileName; }
   CString GetModulePath() const      { return m_strModulePath; }
   CString GetCardModulePath() const   { return m_strCardModulePath; }
   CString GetMtgModulePath() const   { return m_strMtgModulePath; }
   CString GetBitmapPath() const      { return m_strBitmapPath; }
   CString GetAppDataPath() const      { return m_strAppDataPath; }


At the moment it is working. I installed my newly built .msi onto C:\Program Files\EpochSoft. This means when I write new code to see the change in the app I have to manually copy the involved dll to C:\Program Files\EpochSoft

[FranAvalon]

I think that I know whre is your problem.
Probably, you installed first BA on the epoch folder and now you have selected another folder, but the register points to the first folder. If you delete all entries for BA on the register, and reinstall BA where you want, I think that your problem will be gone.