This is the user's guide to the GOM Editor, the offical SWars game editor. The GOM Editor allows you to build and modify SWars .swx game files.
Table of contents
Authors of this document:
Please email the author(s) with feedback.
Revision history:
[2001-05-14] -
mjg:
Added metanode and node editing sections
[2001-05-06] -
mjg:
Created document.
The GOM Editor, as it's name suggests, is an editor for the SWars Game Object Model (GOM). The editor allows you to edit and create new game universes for SWars. The GOM is a very flexable model and that is refelected in the editor, very few constraints are placed on what you can do. For this reason it is best to be familiar with the GOM (a good place to start is An Introduction to the Game Object Model) and should have a look at existing game files before you launch into creating a new one from scratch.
The editor reads and writes SWarsXML (.swx) files. You can load any valid .swx file into the editor or start your game afresh. When saving, ensure your game's file name ends with .swx so it is recognised by the editor and SWars.
Without a functioning client or server, there's not much you can use your nicely edited .swxs for, except of course, loading them back into the editor. Once a functioning client or server is ready, you will be able to load your game files in and see them in their full glory.
To run the editor, you will need the following items:
The editor is included in the standard SWars development distribution. You should get the latest version from the downloadables area.
A Java 2 Runtime Enviroment (JRE) is needed to run the editor. Any version from 1.2 or later should work, but version 1.3 will work the best. You can get a copy of a JRE for Linux, Solaris or Windows from Sun's Java site or your favorite vendor. Sun has links to other ports for other opertaing systems available from the Java site as well. The JRE is included with the Java 2 SDK's, so if you have a copy of a J2SDK already installed, you don't need to download a JRE.
If you have to install a JRE, follow the instructions from where-ever you downloaded it from to install it.
To install the editor, simpily expand the archive containing the SWars distribution into a directory. You do not need to run an installer and you can install it where ever you want on your machine (assuming you have permission to do so).
In the distribution directory, you will find a JAR file called editor.jar. This file contains the editor itself. Do not expand it; this is an executable JAR. You can run the editor from a command line using the following command from the distribution:
java -jar editor.jar [-d] [game-file.swx]
The optional -d argument will cause debugging information to be printed to your system's standard error stream, it it has one. You can also optionally specify the path to an existing saved game which the editor will load upon starting.
Some graphical systems support double-clicking on editor.jar to run the editor. Try it out, you may be lucky.
The editor uses a tree pane on the left hand side of the window to display the GOM tree. You can select nodes or metanodes in the tree by clicking on them. When you select an item in the tree, the detail pane on the right shows more information about the selected item.
You can use drag and drop to directly manipulate items in the tree. Use your platform's standard modifiers to move, copy and link items in the tree. As you drag an item over another, you can drop the item using the current operation (move, copy or link) if the item below the cursor is highlighted. See the sections below for the effects of drag and drop for the various tree items.
The menu-bar along the top of the editor window contains two menus, File and Selected. The File menu is always available, but the Selected menu is only available when an item is selected in the tree pane.
The File menu contains all the standard file commands, to allow you to open, save, and create new games. It also lets you to set some advanced output options, but you probably won't need to change them.
Warning! The editor only lets you have one game open at a time and will close an existing open game, without saving it, if you open another. Hopefully, this will change in the future.
The Selected menu contains commands relevant to the currently selected icon in the tree pane, and so will change depending on the selected item. See the sections below for more information.
The Selected menu is also available as a pop-up menu on items in the tree pane. Use your platform's pop-up trigger (right-hand mouse click on Un*x and Windows) over the desired item to activate it.
Metanodes specify a node's type, and all nodes must have a type. Thus before you create any nodes, you need to create some metanodes first. Metanodes are designated in the tree pane as tree items with an icon containing a blue 'm' in a circle.
The hierachy of metanodes in the tree pane follows the metanode class hierachy. Child metanodes of a metanode in the tree represent subclasses of the parent metanode.
To add a new subclass to a metanode, use the Selected menu or pop-up menu for that metanode. Select the New submenu and then the Subclass... menu item. You will be prompted for the new subclass's name and whether the new metanode is abstract. The name is mandatory and must not be the same as any other metanode name. Metanode names should only contain alpha-numeric characters and hyphens: '-'. Click the Okay button to creat the new subclass.
Metanodes can be rearragned in the tree using drag and drop. Metanodes cannot be copied, however, as metanode names must be unique. To delete a metanode, use the Selected menu or pop-up menu for that metanode. Select the Delete metanode menu item to delete the metanode.
When a metanode is selected in the tree pane, the detail pane provides more in-depth information about the selected metanode.
The top of the detail pane displays the Metanode's class name and whether the metanode is abstract. Abstract metanodes cannot be used as a node's type, but can are useful as super classes of metanodes which share common attributes or capabilities.
The bottom of the metanode detail pane contains several tabbed tables. These tabbed panes contains tables with further information about the metanode as described below. You can manipulate these tables by bringing up the pop-up menu for them. Use your platform's default pop-up gesture to do this.
The Def attribute and Def capabilities detail pane tabs contain tables listing all of the default attributes and capabilities for the currently selected metanode. Note that it only includes the defaults listed by this metanode, it does not list the defaults a node of this type will inherit from this metanode's super-classes.
To add a new default attribute to a metanode, use the Selected menu or pop-up menu for that metanode. Select the New submenu and then the Default attribute... menu item. You will be prompted for the new attribute's name, type, value and, if you select object as the type, a classname. All fields are mandatory and the value must be appropriate for the type specified. Click the Okay button to add the attribute.
The values for attributes can be edited by double-clicking on the value of the appropriate attribute in the value column.
To add a new default capability to a metanode, again use the Selected menu or pop-up menu for that metanode. Select the New submenu and then the Default capability... menu item. You are presented a list of available capibilities, select one and click the Okay button to add the capability.
The Node children tab in the metanode detail pane lists all allowed or disallowed node children for a node of this type. The first column displays the type of child node. The second column displays whether this entry is for a structural or lateral child. The third column displays whether these nodes are allowed or disallowed.
To add a new allowed or disallowed node child type, you must drag and drop the metanode of the desired child type onto the target metanode, using the link drag and drop modifier. On UNIX and Windows machines, this means holding down Ctrl and Shift during the drag and drop. Once you have dropped the child type onto the target, a dialog will be displayed prompting you to decide if this is for a structural or lateral child and if the child is allowed or disallowed. Click the Okay button to add child type.
The All structural and All lateral tabs in the metanode detail pane display lists summarizing all of the allowed types of child nodes for structural and lateral relations, respectively. Keep in mind that when allowing or disallowing a child type, you also allow or disallow every subclass of that type. These lists provide a quick overview of every allowed child type.
Warning! Modifing the list of child types when a number of nodes have already been created may cause the existsing nodes to become invalid children of their parents. This will not get picked up by the editor and so it is strongly suggested that you do not edit metanodes after adding nodes to the game.
Nodes represent objects in the game universe, so everything in the game will need to have a node to represent it. Nodes are designated in the tree pane as tree items with an icon containing a black 'n' in a circle. All nodes are children or descendants of the Game object, designated with an icon containing a black 'G' in a circle. Game objects are specialized kinds of nodes, so you can edit the game object in the same way as you would a node.
The hierachy of nodes in the tree pane follows the node's structural child hierachy. The child nodes of a node in the tree represent structural children of the parent node.
To add a new structural child to a node, use the Selected menu or pop-up menu for that node. Select the New submenu and then the Structural child... menu item. You will be prompted for the new child's name and type. The name is mandatory and may be the same as other nodes. Node names should only contain alpha-numeric characters and hyphens: '-'. Select a type from the combo box, they are the complete list of valid child types for this node, and are identical to the contents of the list under the All structual metanode detail pane tab. Click the Okay button to create the new child.
Nodes can be rearragned in the tree using drag and drop. Nodes can be copied, using the copy drag and drop modifier. This means holding down Ctrl while performing the drag and drop. Newly copied nodes are the same type, have the same name, attributes and capabilities as the source node, but do not have copies of any structural or lateral child relations that the source node may have. To delete a node, use the Selected menu or pop-up menu for that node. Select the Delete node menu item to delete the node.
When a node is selected in the tree pane, the detail pane provides more in-depth information about the selected node.
The top of the detail pane displays the node's name, GOM Identifier (gid) and type (metanode name).
The bottom of the node detail pane contains several tabbed tables. These tabbed panes contains tables with further information about the node as described below. You can manipulate these tables by bringing up the pop-up menu for them. Use your platform's default pop-up gesture to do this.
The Attributes detail pane tabs contains a table listing all of the attributes (including default attributes) that the node has. The first column lists the name of the attribute. The second column lists the type of the attribute. The third lists the value of the attribute. The values may be edited by double clicking on the value in the thrid column, and pressing Return or Enter when done. The value must be a valid value for the attribute's type.
To add a new attribute to a node, use the Selected menu or pop-up menu for that node. Select the New submenu and then the Attribute... menu item. You will be prompted for the new attribute's name, type, value and, if you select object as the type, a classname. All fields are mandatory and the value must be appropriate for the type specified. Click the Okay button to add the attribute.
The Capabilities detail pane tabs contains a table listing all of the capabilities (including default capabilities) that the node has. The first column lists the capability's fully qualified class name. The second column lists capability's human-readable display name.
To add a new capability to a node, use the Selected menu or pop-up menu for that node. Select the New submenu and then the Default capability... menu item. You are presented a list of available capabilities, select one and click the Okay button to add the capability.
The Lateral children tab, in the node detail pane, lists all lateral child relations for the node. The first column displays the precise type of the relation. The second column displays the name and gid of the lateral child.
To add a new lateral child relation, you must drag and drop the desired lateral child node onto the target node, using the link drag and drop modifier. On UNIX and Windows machines, this means holding down Ctrl and Shift during the drag and drop. Once you have dropped the child onto the target, a dialog will be displayed prompting you to decide what type of relation you are creating. Click the Okay button to create the new relation.