Fractal Softworks Forum

Please login or register.

Login with username, password and session length

Author Topic: Eclipse modding tutorial (lots of pictures)  (Read 9941 times)

TJJ

  • Admiral
  • *****
  • Posts: 1800
    • View Profile
    • Email
Eclipse modding tutorial (lots of pictures)
« on: September 12, 2012, 11:36:46 AM »

There's already a netbeans tutorial, but none for Eclipse.
As Eclipse is my IDE of choice I figured I'd contribute one.
Logged

TJJ

  • Admiral
  • *****
  • Posts: 1800
    • View Profile
    • Email
Re: Eclipse modding tutorial (lots of pictures)
« Reply #1 on: September 12, 2012, 11:36:59 AM »

This tutorial has been written using Windows 7 x64; other platforms will vary slightly.

  • 1) Download Eclipse

    The latest release of Eclipse is 4.2 "Juno", however this release has been somewhat controversial. (massive changes to the user interface, and some major performance regressions)

    For this tutorial I will be using Eclipse 3.7 "Indigo".
    Eclipse 3.7 can be downloaded from here:

    http://www.eclipse.org/downloads/packages/release/indigo/sr2

    The package you want is "Eclipse IDE for Java Developers".

  • 2) Do you have a Java Runtime Environment (JRE) installed?

    If you have anything inside the folders "C:\Program Files\Java", or "C:\Program Files (x86)\Java", then you have a recent JRE installed.
    If you don't have a JRE installed, then you MUST follow step (3).
    If you do have a JRE installed, then you may skip step (3).

  • 3) (optional) Download the Java Runtime Environment (JRE), or Java Development Kit (JDK) appropriate to your platform.

    For modding Starfarer all that is required is access to a JRE.
    However some of Eclipse's more advanced features require access to a full JDK nor just a JRE.

    Java downloads can be found here:

    http://www.oracle.com/technetwork/java/javase/downloads/index.html

    At time of writing the latest version is Java 7 update 7. (Java SE 7u7)

    (optional) You might also find the JDK Documentation (javadoc) to be useful.
    The JDK 7 documentation can be downloaded here:
    http://www.oracle.com/technetwork/java/javase/documentation/java-se-7-doc-download-435117.html
    Or browsed online here:
    http://docs.oracle.com/javase/7/docs/api/

  • 4) If you downloaded the JDK (or JRE) in step (3) install it now.
    I strongly recommend you install to the default locations.

  • 5) extract the Eclipse binaries that you downloaded in step (1).

    Eclipse does not provide an installer, it's just a simple copy/paste of the 'eclipse' folder found within the zip archive.
    I recommend you extract it to the root of a drive, so you end up with a nice simple path like "c:\eclipse".

  • 6) Create a shortcut to the eclipse executable (c:\eclipse\eclipse.exe), and run it!

  • 7) Select your workspace.

    Spoiler
    [close]

    For our purposes the default location will be fine, as we won't be saving source files here anyway.

  • 8 ) The welcome screen.

    Spoiler
    [close]

    Close it.

  • 9) The workbench.

    Spoiler
    [close]

    First, a quick overview of how the workbench is organised.

    Views:
    The Eclipse workbench is made up of "Views".
    These are child windows that can be docked/undocked/rearranged as you desire. Each view shows specific information.
    If you close a view, you can restore it from the "Window->Show View" menu option.
    The default workbench state has a fairly sensible arrangement of the most commonly used views:

    "Package Explorer": Provides a file-browser view of the projects within your currently open workspace and their contents.
    "Problems": This gives you a list of errors and warnings that the Eclipse compiler has detected in the source code of your open projects.
    "Javadoc": Shows you the javadoc of the currently selected source element (if available). I don't usually use it .
    "Declaration":
    "Outline": Outlines the member variables & methods of the currently selected source element.
    "Task List": Close it, you won't need it for now.

    Perspectives:

    For different tasks you usually want a different selection & arrangement of views. This is where perspectives come in.
    The default Perspective is "Java". The intended activity in this perspective is the editing of source files.
    Another common perspective is "Debug"; Eclipse will automatically switch to this perspective when you run a java program in debug mode.
    There are lots of other less frequently used Perspectives; for examples have a look in the "Window->Open Perspective->Other..." menu option.

  • 10) Creating and configuring your first project

    - Right click anywhere in the Package Explorer view, and select "New->Java Project". This will bring up the project wizard.
    Spoiler
    [close]
    - Enter a Project name. Leave everything else as-is, and click "Finish". For my example I'll be creating a project for editing Uomoz's Corvus mod.
    Spoiler
    [close]

    You've now created your new project.
    Now to set up the project for Starfarer modding.

    - Delete the "src" folder; we won't be using it.
    Spoiler
    [close]
    - Right click the Project's root folder, and select "New->Folder". This will bring up the "New Folder" wizard.
    Spoiler
    [close]
    - Click "Advanced >>", select "Link to alternate location ('Linked Folder')", and then click "Browse...".
    Spoiler
    [close]
    - Browse to the Starfarer root directory (default is "C:\Program Files (x86)\Fractal Softworks\Starfarer") and click "OK", then "Finish".

    You've now created a Linked Folder; this is a virtual link to a folder outside the Project's workspace.
    Now to set up the class path.

    - Within the Starfarer/starfarer-core folder control-click the files "lwjgl_util.jar" and "starfarer.api.jar" to multi-select them.
    - Right click, and select "Build Path->Add to Build Path"
    Spoiler
    [close]

    These code libraries have now been added to the compiler's class path.
    Now to add the game & mod code to the build path.

    - Right click the "Starfarer/starfarer-core" folder, and select "Build Path->Use as Source Folder".
    Spoiler
    [close]
    - Right click the "Starfarer/mods/*YourMod*" folder, and select "Build Path->Use as Source Folder".
    Spoiler
    [close]

    One more thing, then you're done!

    - Right click "Referenced Libraries/starfarer.api.jar", and select "Build Path->Configure Build Path..."
    Spoiler
    [close]
    - Select "starfarer.api.jar/Source attachment: (None)", and click "Edit..."
    Spoiler
    [close]
    - Click "Workspace...", and point it at the file "Starfarer/starfarer-core/starfarer.api.zip", then Click "OK", and "OK" again.
    Spoiler
    [close]

    Now when you browse the starfarer.api.jar classes you'll be shown the source files, rather than the decompiled method signatures.

  • 11) Plugins

    Eclipse hosts an enormous plugin library; some cost money, most are free.
    The two I've found useful for Starfarer modding are:

  • 11a) CSV Edit

    - Click the "Help->Eclipse Marketplace..." menu item.
    - Search for "CSV Edit"
    - Click Install; accept the license agreement, ignore the unsigned warning, and finally "Restart Now".
    - Now, whenever you open a .csv file in the Package Explorer it'll open it using this Eclipse plugin.

  • 11b) json Editor

    Slightly different installation process for this plugin, as it isn't available on the marketplace.

    - Click the "Help->Install New Software..." menu item.
    - IMPORTANT. Uncheck the "Group items by category" option
    - In the "Work with:" field, enter the following URL and then press enter: http://eclipsejsonedit.svn.sourceforge.net/viewvc/eclipsejsonedit/trunk/Json Editor Plugin
    - Check the package "Json Editor Plugin", click Next, accept license agreement, etc etc.
    - Wait for the "Installing Software" dialogue to complete. (it seems to take ages for this plugin)

    The plugin is now installed, and will be used when opening all .json files.
    However,  Eclipse needs to be told to use the plugin for opening Starfarer's other json format files that have custom extensions. (".system", ".variant", ".ship", ".wpn", ".proj", ".faction" etc).

    - select "Window->Preferences" menu.
    - In the Preferences window browse to "General->Editors->File Associations"
    For each of the custom file types you want the json editor to be used with:
    - click "Add...", type the extension prepended with an asterisk. (e.g. *.system)
    - Select the newly added file type in the list, click the lower "Add..." button, and select "Json Editor".

« Last Edit: September 12, 2012, 02:09:37 PM by TJJ »
Logged

TJJ

  • Admiral
  • *****
  • Posts: 1800
    • View Profile
    • Email
Re: Eclipse modding tutorial (lots of pictures)
« Reply #2 on: September 12, 2012, 12:00:34 PM »

Reserved for other useful Eclipse hints & tips.
Logged

nomadic_leader

  • Admiral
  • *****
  • Posts: 725
    • View Profile
Re: Eclipse modding tutorial (lots of pictures)
« Reply #3 on: July 01, 2017, 03:19:47 AM »

Well, the pics are gone. The thread title is fake news.

Would it be ok if I added some new pics and some info for mac? Plus info about creating a simple jar and building for java 7 (starsector needs this one) vs java 8 (I guess starsector hates this one) since the latest version of eclipse insists you have java 8.

I don't actually understand any of this, but I did get it to make a simple jar that correctly affects the game, so I probably make some appropriate pics and instructions if someone else doublechecks for me.
Logged