TorquEDIT Eclipse Plugin v0.4 Documentation

J. Alan Atherton

(you can find contact information on my GarageGames profile)

May 10, 2007


Alternatively, you can view this document as a pdf here: torquedit_0_4.pdf


The TorquEDIT plugin is for editing torque script files inside eclipse. The plugin was developed for and tested on Eclipse v3.2, and it might work for v3.0+, but it most likely will not work for anything earlier. So far it has not been tested with the Torque Build Environment (TBE), although it might work. I really don't know anything about TBE, except it exists, and it's eclipse.


The steps you need to follow to get the plugin fully working are:

  1. Copy the plugin to the eclipse plugin folder.

  2. Specify engine source code path(s).

  3. Create a Torque Project.


Beyond that, there are plenty of helpful tips and tricks to really use the power of this plugin. Read on!


1. Install the plugin

The first thing you need to do is download the plugin, and place the file (ends with .jar), in the eclipse plugins folder. Navigate to the eclipse folder (Perhaps
C:\Program Files\eclipse) and put the plugin jar file into the plugins folder. If eclipse is already running, you will need to restart it.


When you start eclipse for the first time, you will have to specify where your workspace is. It is not very important where you put it. I do not recommend to put it where you will be working on your games… it is more of a temporary location.


When you have a workspace, this is the typical view for eclipse (or something similar).



2. Edit preferences

Before anything can happen, you need to edit your preferences. Go to Window->Preferences.




Now find the TorquEDIT section. If it's not there, the plugin isn't installed. For best results, you need to specify a source folder (and check the “Use” box) for at least one of the three engines. This folder should be something like C:\Torque\engine. The plugin will scan these folders to generate its database for intelligent code completion. Without these folders, some code completion will still work, but none of the engine-specific classes and functions will be available. Any classes and functions you specify in your scripting will be available at all times. The next release will likely include the default databases for each engine separately, so if you don't have the source code (mostly for TGB), then you can still have engine-level code completion. Whether they are included depends partly on if GarageGames will allow it. Currently the code completion list will show some classes that actually are not exposed to scripting. It doesn't usually get in the way, and it will be fixed eventually.


The “Popup delay” governs how long the code completion waits before showing the choices for completion. Currently it is best to leave this number relatively high, since the code completion is a little slow, and will cause your typing to “stutter” if set very low. If the stuttering is annoying, increase this number.


The color options are for syntax highlighting. If you want to change the background color (like, black for you vampires), you need to go to the General->Editors->Text Editors section of the preferences.




3. Create a Torque project

Ok, now that preferences are all set, you need to create a project. Go up to New->Project... Then select Torque Project.




Give your project a name, and pick something other than the default location. For best results, you should pick the base folder for your game. By base folder, I mean the mod folder... not the folder with the executable in it. The wizard will automatically add all files and folders that are part of that folder, along with all subfolders. If you choose to use the default location, the files will all be copied into the folder you chose as a workspace, so you will have to move your Torque executables and what not into your workspace as well. Either that or you will have to copy the files from your workspace to the actual project folder. For now it's much better to just specify your actual project folder.


Once your project is created, it will initiate a build. Look in the lower right corner for the build progress (it takes several seconds).



The build process simply scans your script source code and the engine source code to populate the code completion database. It does not actually compile your code.



Tips

If you want to hide .dso files or any other type of file from the project tree (“Package Explorer”), you can setup filters. Click on the little triangle in the Package Explorer, then choose Filters.




Check the “Name filter patterns” box, and specify search patterns separated by commas. If you want to hide all .dso files and .jpg files, type “*.dso, *.jpg”.


If you ever need to rebuild your code completion database, go up to Project->Clean... and choose the appropriate projects. If the code completion doesn't seem to be working right, try a clean. If that doesn't work, then the code completion probably isn't picking something up, and you will have to explicitly define the variable type using the //# special comment. See the examples file/section for details.




You can setup a button to run Torque. Click on the little triangle next to the green button with a little icon that looks like a lock (who knows what it really is...) and pick “External Tools...”



Select “Program”, then click the little paper with a plus on it to create a new configuration. Configure your program (specify where your TGB.exe or Torque.exe or whatever is).


Now you can click on this button (or the arrow next to it) to launch your game.


To find in files, press Ctrl+H, then make sure the “File Search” tab is selected. You can search the entire workspace (all of your projects) or just the project you are currently editing.



Hotkeys

Here are a few hotkeys for using eclipse that I use often.



Future Work


These are more or less in the order of preference.


Really want to do:


Might get around to it:


Examples


Here are some examples for how to use the code completion, as well as special comments. You can download the file, or just look through it here.


Download the file: examples.cs 


// In order for this example to work completely, you need to have
// TGB, along with the TGB source.  In the future, this may not be
// necessary.  But for this example, it is.  

// This file needs to be in a TorqueEDIT project... go to 
// File->New->Project... and select Torque Project from the list.
// For the location, you can specify a folder with your TGB source
// code in it (or this file), or you can leave it as the default.
// If you specify a folder, then you will directly manipulate
// the files there.  Otherwise, you need to import the project files
// into the project, and then you will have to copy the modified files
// from the workspace to where TGB is located.  I recommend specifying
// a project folder.  Note that the TGB project must have already been
// created from inside TGB.

// You also need to go to Window->Preferences->TorquEDIT, and 
// specify the engine source folder for TGB, and make sure the 
// "Use TGB" checkbox is marked.
// 

// You can construct a
// similar example for TGE or TGEA.  The behavior is the same.
// Not all of the classes in the completion list are exposed to 
// scripting... that will be fixed in the future.  For now, if you
// select a class, and then Torque complains about the class not
// existing, then it's a C++-only class.

// On with the examples.


new t2dSceneGraph(sceneGraph) {
        field = "ignored";
};

// Try starting to type sce, then pause for half a second
// A window showing sceneGraph should pop up.  You can use the arrows
// to select a suggestion, then press enter to insert it.  Or you
// can press esc to get rid of the window.

function funcTest(%param1, %param2) {
        // Local variables are only available for completion in the scope
        // They are used or defined.  Only local variables inside a 
        // function are setup for completion (this may change, so local
        // variables outside functions are ok too, even though that's
        // bad programming practice).

        %blah = %param2 + %param1;
        
}

// So now, below this comment, 
// when you start typing %, nothing should show up.


// If you make changes to the document, the autocompletion will not
// be refreshed until you save.  In some cases, you may need to clean
// the project for everything to by correct.  Just go up to 
// Project->Clean... and select the projects to clean.  This will
// fully rebuild the completion structures from the engine source
// code (if available and selected) and from your script source code.


$global = new t2dStaticSprite(anotherGlobal);
// Now $global and anotherGlobal are defined as t2dStaticSprites.
// Type "$global."  That means type $global followed by a period, dot
// tochka, punto, or full stop (depending on where you're from).
// All of the member functions and variables related to 
// t2dStaticSprite pop up for you to choose from.



function grandparent::aMethod(%this, %unknownParameter) {
        // When you start a comment with //# that means a special command follows.  
        // You can comment out the special comment and the parser will ignore it.  
        // That is, you can type ///# or ////# and the parser will treat it as 
        // a normal comment.

        // The particular special comment below defines the class type of the
        // specified variable.  The first line is like saying:
        // "The variable %unknownParameter is a t2dParticleEffect"
        
        //# %unknownParameter t2dParticleEffect
        //# $unknownGlobal myparent
        //# $unknownGlobal.testfield SimGroup
        
        // This is necessary because torqueScript is a typeless language.
        // I extract the class/type whenever possible, but sometimes I
        // can't get it, or it just misses it or something.  So you can
        // define it explicitly when you need to.

        // The implementation of the special comment adds the class to a list of parents,
        // so you can specify several parents.  Keep in mind that this
        // does absolutely NOTHING to do with torque or tgb, it will not
        // change the way your code works.  This is only for code completion
        // purposes.  
        
        // So, try it out.  Below the comments, start typing
        // one of the variables defined (like the first 2 letters), 
        // pause for half a second, then select an item from the list.
        // The bottom example is especially cool... try typing a . at
        // the end of the defined variable.

        %this.grandField = "something";
}

function myparent::lookForMe(%this, %second) {
        // t2dVector is NOT actually a console class.
        // It is something I made up to help with code completion
        // The only way to use it right now is to use the
        // special comment //# to define it
        //# %second t2dVector

        // Now try typing %second. and see what pops up.
        // Then select one of the options.  Neat huh?

        %object = new t2dAnimatedSprite() {

                class = "myparent";
                superclass = "grandparent";
        };

        %this.childField = new ScriptObject();

        // Now notice that %object has childField and grandField in its
        // completion options (grandField is defined above).  It also
        // has aMethod and lookForMe.  
}


// TODO make totally awesome game
// TODO1 High priority
// TODO2 Normal priority (don't really need the 2)
// TODO3 Low priority

// Open up the tasks view.  Window->Show View->Tasks
// Notice the TODO item above.  The syntax is // TODO (can be lowercase), 
// then whatever. The TODO just has to be the first thing in the comment.  
// If a number 1, 2, or 3 follows immediately after the todo, then
// the priority for the task is set.