Skip to content

(SM autoconverted) how to get started developing forge

Jump to bottom Edit New page
add-le edited this page Sep 3, 2022 · 2 revisions

[WARNING!!!]

Page imported from the old SlightlyMagic wiki. To be integrated into other wiki pages and/or README... or deleted.

The Basics

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 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 the Discord or in the forums. 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.

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.

For mobile-dev Mac OS requires the use of the -XstartOnFirstThread JVM argument.

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.

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:

      -   
    [email protected]:Myrd/forge.git

  5. Now check out the project from your client. For example, from the command line this would be:

      -   
    git clone [email protected]: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 your Forge clone page, click "Merge Requests" on the left side and then "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
    [email protected]: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).

  4. Or, you can simply reset your master branch to upstream, losing any local changes via:

      -   
    git fetch upstream
    git checkout master
    git reset --hard upstream/master
    git push origin master --force

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

Code Style

Spaces only.

Sentry

TBD

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.
Add a custom footer

Forge Wiki Home

Clone this wiki locally