Log in

Forge:How to Get Started Developing Forge

Contents

The Basics

This wiki is probably a bit out of date. Please don't use Eclipse, and make sure you have access to Git. We'll either remove or update soonish (maybe?)

Bleeding Edge Build Instructions

Ants in your pants? House on fire? Coffee getting cold? Crank out a build right away:

Project Overview

Welcome to the development wiki for the Forge project. This document aims to answer questions about Forge building and testing. There's something everyone can help with:

  • Game Testers: Testers simply play the game, but take the time to report bugs so the developers can fix them.
Startup suggestion: Here's how to report bugs quickly and easily.
  • Code Contributors: Contributors are comfortable modifying/creating card files and fixing minor bugs.
Startup suggestion: After you complete your build, you may want to look at the card scripting API.
  • Java Developers: Developers work with the Java source directly, implementing game features and publishing changes.
Startup suggestion: The Forge team recommends these plugins at present.

Whatever your interest, the first step is to register/login on the slightlymagic.net forum.

About this document

Licensing

This document is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License.

Discussion/Editing

Discussion and comments at Discussion area or in the forum. It is good practice to discuss changes before they become permanent.

Editing directions using the Mediawiki syntax can be found here.

Sections to be edited are marked "Section Incomplete", "TODO", or similar.

Testing Notes

The Windows portions of these instructions have been tested with Windows XP. Versions of Windows older than XP may not accept forward slashes ( / ) in folder paths; in that case, you must use backslashes ( \ ) instead. There may be other variations.

The Mac OS portions of these instructions have been tested on Mac OS X Snow Leopard by Chris H. They may also work with Lion or later.

Contributors

Special thanks go (in alphabetical order) . . .

  • to Doublestrike who restructured and updated this document for better usability.
  • to Chris H., who provided Mac OS specific instructions and corrections.
  • to jeffwadsworth who provided corrections.
  • to Rob Cashwalker, who provided the first draft of what became this document.
  • to everyone else who edited this document on the wiki at slightlymagic.net.


Installations

This section deals with installation details for the various software used in the common development environment.

Java

Java is the programming language which Forge is written in. It's got its own runtime environment that allows the same program to be run on any operating system. For development, it is best to install a Java Development Kit, or JDK, instead of a JRE or other JVM if possible.

Windows-Specific Instructions

Download Java from this site. If you want 64-bit Java, you must visit the site with a 64-bit browser (currently Internet Explorer is the most popular option).

There's many tutorials on the Net that do a great job of explaining this install. Basically, run the installer.

Testing

You can test your install from the command line by entering java -version. You should get something like:

java version "1.6.0_27-ea"
Java(TM) SE Runtime Environment (build 1.6.0_27-ea-b03)
Java HotSpot(TM) Client VM (build 20.2-b03, mixed mode, sharing)

If you've run the installer, but the test doesn't work, you'll need to show your computer where to look for the Java compiler. Find your system environment variables and append ;path-to-java-install/bin to the end of the PATH variable. You may need to log off/on before it works.

Portability (Optional)

Both flavors of Java (x86 and x64) can be installed to a USB drive to move your dev environment between operating systems. A batch file must be created to (temporarily) modify the PATH variable of the host machine, with this line of code included:

SET path=path-to-jdk-folder\bin;!path!

A GOTO block can be set to test for OS architecture using the following line:

if %processor_architecture:86=%==%processor_architecture%

Macintosh-Specific Instructions

Java comes pre-installed on versions of Mac OS X Snow Leopard (10.6) and earlier. To run Forge on Lion (10.7) or newer, Java (specifically the JDK) version 7 is required. This can be downloaded here.

Open the package file to launch the installer. Follow the installer instructions.

Testing

You can test your install from the Terminal.app application that is located in your /Applications/Utilities/ folder by entering java -version into the terminal window. You should get something like:

java version "1.6.0_26"
Java(TM) SE Runtime Environment (build 1.6.0_26-b03-383-11A511c)
Java HotSpot(TM) 64-Bit Server VM (build 20.1-b02-383, mixed mode)

Helpful Links

Although we officially recommend a JDK, the curious may be interested in how the softwares differ. See JRE vs. JDK vs. JVM.

Maven

Maven is a tool used for publishing versions of Forge for public release. It automates and standardizes the process so best practices are followed and project structure is consistent.

You do not need to install Maven unless you plan on being part of this process. Otherwise, skip ahead to m2e Plugin.

Windows Instructions

  1. Download the zip file here.
  2. Unpack the file to your preferred location on your hard drive.
  3. Find your system environment variables and append ;path-to-maven-install/bin to the end of the PATH variable.
    • You may need to log off/on before it works.

Testing

From the command line, mvn --version should produce something similar to

Apache Maven 3.0.3 (r1075438; 2011-03-01 01:31:09+0800)
Maven home: C:\path-to-maven\bin\..
Java version: 1.6.0_27-ea, vendor: Sun Microsystems Inc.
Java home: C:\path-to-jdk-folder\jre
Default locale: en_US, platform encoding: Cp1252
OS name: "windows 7", version: "6.1", arch: "x86", family: "windows"

Portability (Optional)

Maven can be run from a USB drive. Change the JAVA_HOME variable, and add the \bin to the PATH variable. Add the following lines to your batch file:

SET java_home=path-to-jdk-folder
SET path=%java_home%\bin;!path!

Mac OS Instructions

Maven should already be installed.

Testing

From the Terminal application, mvn --version should produce something similar to

Apache Maven 3.0.3 (r1075438; 2011-03-01 01:31:09+0800)
Maven home: C:\path-to-maven\bin\..
Java version: 1.6.0_27-ea, vendor: Sun Microsystems Inc.
Java home: C:\path-to-jdk-folder\jre
Default locale: en_US, platform encoding: Cp1252
OS name: "windows 7", version: "6.1", arch: "x86", family: "windows"

Helpful Links

Installation Instructions

IDE

You will need an editor to modify the Java code. We recommend IntelliJ as described below.

IntelliJ

IntelliJ

It comes in two versions:

  • Community Edition: free to download and enough for this project (it is not a trial version that expires);
  • Ultimate Edition: paid version that has support for various frameworks (that we don't need);

On the official website can be found versions for Windows/Linux/OSX.

You will not need to install any plugins.

Working with the project

Switchover to Git

We've recently switched to Git. The new workflow for getting the code and submitting patches is as follows:

  1. First, sign up for a GitLab account at:
    https://git.cardforge.org/
  2. Once you're signed in, go to the main Forge project here:
    https://git.cardforge.org/core-developers/forge
  3. Click on the [Fork] button to create your own fork of the project.
  4. Navigate to your forked project and copy its git URL, for example:
    git@git.cardforge.org:Myrd/forge.git
  5. Now check out the project from your client. For example, from the command line this would be:
    git clone git@git.cardforge.org:Myrd/forge.git
  6. Edit some code and commit your changes:
    git commit -a
  7. Push the changes so they're reflected in the web UI:
    git push
  8. Now on the main Forge project (https://git.cardforge.org/core-developers/forge), click the [+] on the right and select [New Merge Request] and select your Fork project and the branch (e.g. master) and select "Compare branches and continue", from where you will be presented with UI to create the merge request.
  9. Once the merge request is created, someone from the Forge project can review it and merge it in.

To keep your Git fork up to date, do the following:

  1. First, add the upstream project locally (do this only once)
    git remote add upstream git@git.cardforge.org:core-developers/forge.git
  2. Now, you can sync it to your fork's master:
    git fetch upstream
    git merge upstream/master
  3. If there are merge conflicts, resolve them and commit the changes (and push).

For more git usage, but less focus on forge's project organisation, take a look here.

Typical Development Usage

This section details the use of Maven to generate published builds released in the Forge forums.

Team Synchronizing Perspective

(Section incomplete.)


Executing Maven Commands

Using the included Maven Commands

  1. Java Applet
  2. Java Application
  3. Maven build
  4. Maven build...
  5. Maven clean
  6. Maven generate-sources
  7. Maven install
  8. Maven test

Several example are provided below.

  1. The Java Applet menu command is used to run Java Applets. Currently not needed in forge.
  2. The Java Application menu command will let you run the forge game. The first time you use this command you may have a java heap space error. Quit forge and then select the Run -> Run Configurations menu command. Select the (x) = Arguments tab and add -Xmx1024m to the VM arguments checkbox.
  3. The JUnit Test menu command is used to run JUnit tests. The Run Configurations window can be used to configure this option.
  4. The Maven build command will build the forge jar-with-dependencies file in your /git/cardforge/target/ folder. This version of the Maven build command does not open the window labeled Edit Configuration. Use the Maven build... command instead if you want to enter a goal.
  5. The Maven build... menu command will give you a window labeled Edit Configuration. You enter the goal into the Goals: text box. Click Apply. Then click Run.
    1. The goal -U -B clean -P osx,windows-linux install will build the jar-with-dependencies file and packages this jar with the necessary files to produce two archives. A windows and unix specific archive and a Mac specific archive. This goal does not upload these archives to a site for distribution.
    2. The goal -U -B clean -P windows-linux install will build a snapshot package build of the Windows/Linux package only.
    3. The goal -U -B clean -P osx install will build a snapshot package build of the Mac OSX package only.
    4. The goal -U -B clean -P osx,windows-linux install release:clean release:prepare release:perform will build the jar-with-dependencies file and packages this jar with the necessary files to produce two archives. A windows and unix specific archive and a Mac specific archive. This goal also uploads these archives to a site for distribution.
    5. The goal -U -B clean install will build the forge jar-with-dependencies file in your /git/cardforge/target/ folder. The Maven install menu command should do the same thing. Full build, package, no uploads. Good for testing.
  6. The Maven clean menu command will remove the various files and folders that were added to the target folder as part of the build process. When finished, there will be two empty folders named classes and test-classes located inside of the target folder.
  7. The Maven generate-sources command will run the build-helper-maven-plugin. Does not appear to do anything of notice.
  8. The Maven install command will build the forge jar-with-dependencies file in your /git/cardforge/target/ folder.
  9. The Maven test command will run the TestSuite that is part of the Maven build process.

Releases

Currently handled by Blacksmith a bot on the Discord channel

Nightly Builds

Currently handled by Blacksmith a bot on the Discord channel

Troubleshooting

I am getting an error about "invalid LOC header (bad signature)"

This could mean you have a corrupt miglayout jar. Starting at your home folder, try removing the .m2/repository/com/miglayout folder. Then run 'mvn -U clean install' to redownload it. (You may have to install a command-line version of maven to do this.)

I am getting an error about "Fix the build path" or "The type ... cannot be resolved."

  1. Right click your Forge project (default name is Forge [trunk], choose Maven, then Update dependencies. The Update Maven Dependencies window opens.
  2. Make sure your Forge project(s) have check marks, then click OK.

Archived

The Forge team has used several methods of project tracking and distribution in the past. This section stores notes from these adventures. This section also stores non-generic extra pieces of information that are not necessarily helpful to everyone.

These instructions are included only for experimentation only.

Environment Variables (Windows)

You'll often need to modify your system environment variables to develop in Java. How to do it?

  1. Click on the Start menu, then the Control Panel.
  2. Double click the System icon. If you do not see this icon, you may need to first Switch to Classic View.
  3. The System Properties window appears. Click the Advanced tab.
  4. Click the Environment Variables button.

Setting Cygwin Variables (Windows)

Cygwin is used by some developers to simulate a Linux environment in Windows.

  1. Open the Environment Variables dialog.
  2. If you have a variable named HOME in the User variables section, you're already finished.
    • Click Cancel, Cancel to exit.
  3. Otherwise, click the New button just underneath the list of User variables. The New User Variable window appears.
  4. For the Variable name, type HOME.
  5. For the Variable value, type the Windows path to your Cygwin root folder (usually C:/cygwin), followed by /home/ and your Windows user name. For example, C:/cygwin/home/Jordan.
  6. Click OK three times in the three different windows that you recently opened.

Batch File Basics (Windows)

If you have a portable environment, a batch file can speed things up considerably by setting variables automatically.

To make a batch file, simply make a new text file and rename the extension to .bat. Right-click the file to edit.

Tips

  • When modifying a variable more than once, use !var! to call the variable.
    • This uses the modified (new) value instead of the original (old) value: path=some-folder\bin;!path!
  • The current drive letter can be represented by %_d0

Google SVN Repository

Referenced in several threads: http://cardforge.googlecode.com/svn/src/

This repository is very out of date. Please use the repository on git.cardforge.org