SMEdit is an offline tool for ships in StarMade originally coded by Joe Jaquinta jjaquinta. Joe has stopped development of the application and the tool is now being developed by Bobbybighoof Bobbybighoof. You can find the application and the development on the smedit main url at smedit.co.
- 1 Install and Running
- 2 Features
- 3 Video Tutorials
- 4 Gallery
- 5 Tips and Tricks
- 6 Troubleshooting
- 7 File Formats
- 8 Writing Plugins for SMEdit
- 9 Help and Feature Requests
- 10 External Links
- 11 References
Install and Running
The primary SMEdit jar file can be downloaded from here. SMEdit requires registration to the support forum to download It. You will find all you need to run the application from the main site.
The objective of SMEdit is to provide a tool that does things that are very hard to do in the in-game editor. It is designed to complement the in-game editor, not replace it. The features developed for that reflect this.
- Move and rotate core. People often make regrettable decisions when placing their ship's core. Or end up building the ship facing the wrong way. Correcting this is virtually impossible in the in-game editor. SMEdit lets you move the core, or rotate the ship around the core.
- Paint and style. Giving a ship a color scheme has to be thought out in advance in the in-game editor. Specific quantities of specific hull elements have to be bought in advance. SMEdit lets you "paint" an existing design. So you can concentrate on designing in the game, and paint it later. There are tools to selectively replace colors across the whole ship or a selection of the ship. Another tool lets you paint a variety of "stripes" on the ship. Yet another one lets you add lettering from any font installed on your computer.
- Import standard models. SMEdit can import ships designed for other systems. It supports OBJ files, but it is a little fragile to deviations from the OBJ spec. The binvox tool does a very good job at converting OBJ and other formats to its' own binvox format. And SMEdit is very good at importing binvox files. SMEdit can also import Schematic files. Conversion of Minecraft IDs to StarMade IDs is user configurable.
- Basic hull generation and filling. You can generate hulls in a number of basic shapes such as spheres, cylinders, boxes, etc. You can then fill them proportionally with thrusters, weapons, etc. This is a quick way to flesh out a basic ship.
- Planetary generation. You can create new and unique planets through several steps. First you determine the basic shape. You can choose one shape for the top, and a different one for the bottom, if you don't want the standard flat bottom. Then you choose composition. You might want to choose a basic composition (e.g. Mars-like) and then maybe something like adding minerals. Next you can add vegetation to the surface, and finally buildings. The design goal is that these plugins can be used in headless mode in the actual game to enhance planetary generation once the game is ready for it.
SMEdit has the ability to record and playback macro commands. If you find yourself doing a common set of tasks multiple times, you might consider creating a macro.
Recording a Macro Selecting Edit -> Macro -> Record starts the recording process. You should specify the information that you want to identify the macro with. The name is what will appear on the menu. The placement indicates which menu it will appear on. Note the Generation and Modification macros both appear on the Mods menu. The Paint macros appear on the Mods button on the paint bar. The Enablement field lets you scope the macro to a specific model type. Lastly the priority will let you specify the placement in the menu. Low numbers are towards the top, high numbers are towards the bottom. The items are grouped into multiples of ten. To see what priorities are there for existing feature, you can use Edit -> Plugin Report to list them. Subsequent commands you issue will be recorded in the macro. When you select Edit -> Macro -> Stop Recording, the macro is saved. It will then appear in a menu, and when you select it, all the commands you recorded will be run on the current model.
Deleting a Macro If you made a mistake, or no longer need a macro, you can use Edit -> Macro -> Delete to remove any recorded macro.
Running Unregistered Macros For convenience, recorded macros are saved in the system. You may choose to relocate these elsewhere, or write ones from scratch in a different location. If so, you can choose Edit -> Macro -> Run to pick these other files and execute them. Debug messages, print, and println commands are printed on the console. You have to be running SMEdit from the command line to see them.
Some things that were created with SMEdit:
SMEdit's main Gallery is located on the main support site.
Tips and Tricks
A selection may be initiated by holding down Shift and left-dragging the mouse over a region. The selection box is indicated by colored sides. Bright red is the +X side, dark red the -X side, bright green the +Y side, dark green the -Y side, bright blue the +Z side, dark blue the -Z side. Since a ship is three dimensional, and the mouse operates on two dimensions, this is seldom the final selection you want. The selection may be adjusted in a number of ways. Typing WASD(QE) will move the entire selection along the main axis. Shift+WASD(QE) will move the high part of the selection, Ctrl+WASD(QE) will move the low part of the selection. Through a combination of these (and a lot of trial and error until your fingers get used to it) you can create a rectangular selection anywhere you want. The Edit -> Select All menu option is a shortcut to select the entire ship.
Specific Block Deletion
Sometimes you just want to get rid of a specific type of block. You can do that with the block replace tool. For the target block, choose "Air". Then only that block will be removed. If you only want to remove blocks from a specific portion of your ship, draw a select box around that portion before doing the replace. Then only the matching blocks within the selection will be replaced.
Easy Trial Runs
If you are iteratively working on a object, say you are experimenting with hull generation, coloration, or model import, you may find it easier to edit a Your Ship object, that create a blueprint and use it to create a new ship. Launch StarMade and create or select a ship you don't care about. Remember it's name. Exit StarMade and in SMEdit File -> Open that ship from the Your Ships twistie. Now do the operation you are testing and click File -> Save. Run StarMade again and you should be next to the altered ship. You can repeat this for different trials. You need to exit StarMade each time, but you don't need to exit SMEdit.
My Modify menu is blank
If the Modify menu is blank it can mean one of three things:
- The object you have selected has no plugins associated with it. Turrets generally do not have any plugins, so nothing will come up.
- There are no plugins there. JoFileMods.jar (and any other plugin jars) must be in the jo_plugins directory in your StarMade directory. Running SMEdit.jar should put files in the correct place, but check anyway.
- A fault has occurred during plugin loading that caused all subsequent plugins to fail. This can happen if there is a bad plugin in the bunch. Try running from the command line or with the console window open. If you see an exception please report it in the forum.
Wrong StarMade Directory
If you have StarMade installed in multiple locations, SMEdit may get confused about which directory is the one you want.
In the home folder on your machine (~ on Mac or Linux, %USERPROFILE% on Windows) there is a
.josm file. This file contains all the persistent information that SMEdit stores between executions. There is a
starmade.home entry there which contains what it think is you actual StarMade directory. If this isn't what you think it should be, you can change it to the right value. Note that on Windows : and \ need to be escaped. For example
Out of Memory
If you are working with a large ship or object, SMEdit may freeze or fail unexpectedly. If you are running with a console displaying you might see a "Java Heap Exception" error. There is also a small memory meter in the lower left corner of the screen. This displays the free memory. (Hovering over it will give a more complete account.) If this runs out, a crash like the above will happen.
Java allocates a certain amount of memory to your program by default. It does not automatically grab memory as needed. This is a security feature to prevent a rogue program from hogging all the system resources. To change this default value, you need to invoke Java from the command line and add an argument to specify how much memory to use. If you invoke SMEdit from the command line with
java -jar SMEdit.jar, then you could use
java -Xmx1g -jar SMEdit.jar to tell it to give one gig of memory. You should see the change reflected in the memory meter. The amount of memory you can allocate depends on your hardware. Experiment with different values. You will get an "Invalid maximum heap size" error if you pick a value too large. Note: if your machine has 8GB of memory installed, that does not necessarily mean that there is that much free at any given time to allocate to a single program. The operating system takes a big chunk of memory, and each other running process (of which there are lots) takes its own fair share. Experiment with different values to see what works best.
In addition to improving the memory, computers that use 64-bit operating systems, can download and install 64-bit Java, which will allow the use of the
-d64 modifier, for example,
java -d64 -Xmx1g -jar SMEdit.jar. For 64-bit systems, this should allow a far longer maximum heap size, and dramatically improve performance with large objects.
If the program hits an unexpected error, it will usually print a message on the console. If you are running from the GUI, you will not see this. To be able to see console messages, you need to run the tool from the command line.
Launch the command line (CMD on Windows, Terminal on Mac/Linux). Change (cd) to your StarMade directory. Then type
java -jar SMEdit.jar. The program will run normally, but messages will be produced in the console window.
Creating .bat Files For Command Line Usage
To simplify running SMEdit using command line modifications, you can create a text file with the file extension ".bat" (for example, SMEdit.bat). Doing so will turn the file into a form of script that will both open the program and set the modifiers by simply running the .bat file like how you would a program. Once created, open the .bat file in Notepad. For the average computer with 8GB memory, adding a single line with the code
java -d64 -Xmx4g -jar SMEdit.jar should suffice for both memory and troubelshooting needs. The .bat file should be located in the same folder as SMEdit. If there are any problems with getting SMEdit to launch using the .bat file, or are looking to track SMEdit's console for troubleshooting, add
pause as a second line in the .bat file, so that way the window stays open before closing, so you can determine the problem, for example:
java -d64 -Xmx4g -jar SMEdit.jar
Extensions to SMEdit are placed in the jo_plugins directory. These may be in the form of plugins (mods) or data files.
The feature that allows you to filter in or out certain blocks on your ship may be controlled by the ViewFilters.xml data file. The basic format of the file is like this:
<filters author="Jo Jaquinta"> <filter title="Power" description="View power blocks" priority="20"> <block type="POWER_COIL_ID"/> <block type="POWER_ID"/> <block type="CORE_ID"/> </filter> </filters>
You can have as many <filter> tags and <block> tags as you like. The "priority" attribute on the <filter> tag controls menu position. The "type" attribute on the <block> tag may be the actual ID number, or the text ID defined in the BlockTypes.properties file.
The default ViewFilters.xml file is embedded in the JoFileMods.jar file. You can examine and extract it with a ZIP archive viewer. You may have to copy the file to a new name that ends with .zip.
The feature that allows you to import Schematic files needs to map the Minecraft IDs to StarMade IDs. It does this using the schematic_map.xml file. You can supply your own map by placing a file in the right format in the jo_plugins directory. The basic format of the file is like this:
<blockMap default="HULL_COLOR_GREY_ID"> <block mcBlock="Air" smBlock="-1"/> <block mcBlock="Stone" smBlock="HULL_COLOR_GREY_ID"/> <block mcBlock="Wool" mcData="0" smBlock="HULL_COLOR_WHITE_ID"/> </blockMap>
You can have as many <block> tags as you like. The "default" attribute on the <blockMap> tag indicates what StarMade ID to use if it is not covered by the map. The "mcBlock" attribute of the <block> tag is the Minecraft ID that this tag defines the map for. Some Minecraft block types have a secondary data field. If you want to distinguish based on this, you can fill in the "mcData" attribute. The "smBlock" attribute gives the StarMade ID to map this block to.
Minecraft IDs may be the name of the block, or the number. StarMade IDs may be the actual ID number, or the text ID defined in the BlockTypes.properties file.
The default schematic_map.xml file is embedded in the JoFileMods.jar file. You can examine and extract it with a ZIP archive viewer. You may have to copy the file to a new name that ends with .zip.
You can use an early version of of the map file written by Tomino Sama from Mushroom Fleet. It is fully commented so can be easily modified, simply by changing the ID number for a Block to the desired type rather than the one in the .xml
You can Download it here: http://www.mediafire.com/download/qyxai28hxz5g9c2/schematic_map.xml
- open your Starmade folder (where you installed SMedit)
- open the jo_plugins folder
- put this file "schematic_map.xml" in here.
When you open Smedit to import a schematic it will use the values in the .xml to convert block types.
There are several generated plugins to let you alter the composition of a planet. These are driven through the MaterialComposition.xml file. You can supply your own definitions by placing a file in the right format in the jo_plugins directory. The basic format of the file is like this:
<compositions author="Jo Jaquinta"> <composition title="Composition/Mars Like" description="Mars like material" priority="10"> <oldBlock type="*" percent="100" low="0%" high="100%"/> <newBlock type="TERRAIN_MARS_TOP" percent="10" low="-4" high="100%"/> <newBlock type="TERRAIN_MARS_ROCK" percent="10" low="0%" high="-8"/> </composition> </compositions>
You can have as many <composite>, <oldBlock> and <newBlock> tags as you like. The "author" attribute on the <compositions> or <composition> tag lets you specify your name as the owner of this feature. On the <composition> tag, the "title" attribute is the menu name, the "description" attribute the tool tip text, and the "priority" attribute controls menu position.
The <oldblock> tags indicate what terrain is subject to replacement. The "type" attribute may be the actual block ID number, or the text ID defined in the BlockTypes.properties file. A "*" may be used to indicate all blocks. The "percent" attribute indicates the probability that this block will be replaced when encountered. "100" means it is always replaced, "75" would me three times out of four, etc. The "low" and "high" attributes may further scope replacement by a range. If the number is a percentage, (has a % at the end) then the value is set to the current height within the stack being examined. If the value is a positive number, it represents that many blocks above the bottom. If it is a negative number, it is that many blocks below the top. For example,
low="0%" high="100%" will always replace all blocks, no matter their altitude.
low="-4" high="100%" will replace from four below the top, to the top. I.e. the surface most layer.
The <newblock> tags are defined the same way as the <oldblock> tags. However the value for "percent" is interpreted differently. When it is determined that an old block is to be replaced, the new block table is examined. Each new block entry that meets the altitude criteria is considered. The "percent" values are added up, and a block is picked proportionately. So the percent values do not represent true percentages, but rather relative weights.
The default MaterialComposition.xml file is embedded in the JoFileMods.jar file. You can examine and extract it with a ZIP archive viewer.
There are several generated plugins to let you place vegetation on a planet. These are driven through the SurfaceVegetation.xml file. You can supply your own definitions by placing a file in the right format in the jo_plugins directory. The basic format of the file is like this:
<vegetations author="Jo Jaquinta"> <vegetation title="Vegetation/Mars Like" description="Mars like material" priority="10" density="100"> <vegetable type="TERRAIN_MARSTENTACLES_SPRITE" percent="10"/> <vegetable type="TERRAIN_REDSHROOM_SPRITE" percent="10"/> <vegetable type="TERRAIN_CACTUS_ID" percent="10"/> </vegetation> </vegetations>
You can have as many <vegetation> and <vegetable> tags as you like. The "author" attribute on the <vegetations> or <vegetation> tag lets you specify your name as the owner of this feature. On the <vegetation> tag, the "title" attribute is the menu name, the "description" attribute the tool tip text, and the "priority" attribute controls menu position. The "density" value controls what proportion of the surface is covered with vegetation. This can be of two forms. If it is a floating point value less than 1, this represents the percentage coverage. E.g. a value of ".5" will cover half the surface, a value of ".01" will cover one percent of the surface. If the value is greater than 1, it represents the number of empty blocks, on average, per filled block. For example "100" means that one block in one hundred (i.e. one per 10x10 area) will be covered.
The <vegetable> tag is defined similarly to the <newblock> tag in the MaterialComposition.xml file. The only differences is that if any altitude bounds are set, the values are with respect to the total height and depth of the planet, not just the current stack. (Vegetation always is placed on top of the current stack.)
The default SurfaceVegetation.xml file is embedded in the JoFileMods.jar file. You can examine and extract it with a ZIP archive viewer.
Writing Plugins for SMEdit
In addition to the XML files above, SMEdit can be modified by writing additional plugins. A plugin for SMEdit is developed in Java and delivered as a jar file to be placed in the jo_plugins directory. Presently these plugins only work in SMEdit, but the hope is that when StarMade is open for modding, that we can write a simple bridge that will let them be used in StarMade itself.
There are two types of plugins: functional plugins, and factory plugins. Many examples of these can be found in the JoFileMods.jar plugin that ships with SMEdit.
A function plugin is a Java class that implements the
jo.sm.mods.IBlocksPlugin interface. It is included in the jar file and declared in the
MANIFEST.MF file with a
BlocksPlugins tag. There are a number of informational methods that return the name, description, author and category of the plugin. The main functional entry point takes in a
SparseMatrix<Block> argument representing the current model. If the model is to be changed, a similar object is returned.
A factory plugin is a Java class that implements the
jo.sm.mods.IStarMadePluginFactory interface. It is included in the jar file and declared in the
MANIFEST.MF file with a
PluginFactories tag. It has a single interface which returns a list of IBlocksPlugin. This is most often used when groups of similar plugins are generated by a user supplied XML file.
Help and Feature Requests
The development of SMEdit is being tracked in a thread on the StarMade forum. When reporting a bug for SMEdit, please include the following:
- Step by step, what you did
- What actually happened
- What you expected to happen
- Any and all files needed to recreate the steps given
If possible, record a macro of the steps you use.