Blue Mars Sandbox Item Editor
From Blue Mars Developer Guidebook
Sandbox Item Editor is a 3D geometry model viewer and material editor for Blue Mars Project. The primary purpose of this tool is to convert 3D models in Collada format into a Blue Mars internal data format, examine the results visually and edit material properties of converted models as desired. Sandbox Item Editor uses CryENGINE2 for rendering; thus, it displays objects almost exactly as they will appear in the game (subject to lighting conditions, that vary in different locations on Blue Mars). The following manual provides a detailed description of menu commands and special functions of the Item Editor. Note: in some images and documents, linked to this page, the Item Editor is also called Sandbox Viewer, which is the old name of this tool.
Recently added or changed features:
- Added Flow Graph commands in "Edit" menu group: "Open flow graph", "Remove flow graph", "Add avatar trigger".
- Added support for animated models in CGA format.
- Added preview mode, "File -> Preview" command for viewing animated items.
- Enabled wet and frozen material layers.
- For complete list of new features, please see Release notes
- Avoid dramatic color changes in uploaded models
- Export a model from MAX in collada format, video and narration scipt File:2010 item tutorial voice narration script.doc.
- Load a model for viewing
- Adjust model material
- Create itemdata.zip
- Upload itemdata.zip to Blue Mars
- Reuse existing data items
Using Sandbox Item Editor
When started, Sandbox Item Editor automatically loads a predefined level file, with a textured terrain and a single 1m x 1m x 1m cube placed in the origin, to provide scaling. If a geometry file name is given in the command line, Item Editor will load the file. In Windows, Item Editor can be associated with the following types: CGF (native Blue Mars geometry format), and DAE (Collada data files). After doing so, one can view these file types by clicking on them in Windows Explorer.
Once a model file is loaded, Sandbox Item Editor allows to
- move, rotate and scale the model;
- display on-screen model information;
- move the camera freely in the environment;
- adjust camera parameters, such as near clipping plane and angle of view;
- change lighting conditions from morning to day to night time or use free-form time-of-day lighting tool;
- use a set of 3 light sources for local illumination ("indoor" lighting mode);
- toggle high dynamic range rendering mode;
- toggle rendering of the sky, terrain and the ocean (ocean is not present in the current version of the predefined level file);
Navigation in Sandbox Item Editor
The basic navigation controls in the Item Editor are common for all other content creation Editors (Cloth, Body, Animation, Shop , Furniture, Interior). Shop Editor and Interior Editor have a few extra commands, described in "Other navigation commands and options" section below.
- Use arrow keys or W, A, S, D keys to move the camera on the plane forward, left, backward, right.
- Press and hold middle mouse button and move the mouse to move in left-right and up-down directions.
- Roll the mouse wheel to move forward-backward. Same as Alt+RightMouseButton.
- Press and hold Shift key to move faster.
- To adjust moving speed, use "Speed" control at the middle of the bottom tool bar.
- Press and hold right mouse button to rotate around the current camera position.
- Press and hold middle mouse button, with Alt key pressed, to rotate around the hit-point, obtained by intersecting the ray fired from the camera through the mouse cursor.
- To orbit around selected object(s), set "Edit -> Orbit mode" option, select the object(s) and press the right mouse button. If nothing is selected, rotation will occur around the camera location.
- To tilt the camera, use Control+ArrowLeft and Control+ArrowRight. Tilted view may be used to taking promotional snapshots of the screen (Control+P).
Other navigation commands and options:
- To relocate to select object(s), select desired objects and use "Edit -> Go to selection" command, shortcut "F" (stands for "focus"). The camera will relocate towards the selection. If noting is selected, the camera will jump towards the last loaded object on scene.
- Another way to relocate to a single object: open "Select Object" dialog window ("Edit -> Open view pane -> Select Objects" menu command, shortcut Control+T), and double-click on the object name in the list. (Note: in Sept 26 release, you also need to have "Auto Select" option turned on. This extra flag will not be needed in later releases, for relocating on double-click).
- In Shop and Interior Editors, additional "Edit -> Re-center" command is provided to relocate to the center of working area, shortcut Control+F.
- To enable/disable collisions with the ground plane, use "Terrain collision" icon on the bottom tool bar, next to the speed control. When collisions are disabled, the icon turns yellow and you move camera underground, using any of the camera controls, described above.
Camera angle and clipping plane.
- To change camera viewing angle (field of view), use Control+ArrowUp and Control+ArrowDown.
- To change camera near clipping plane, use Control+NumPadPlus and Control+NumPadMinus.
- To reset camera to default values (viewing range 0.01 - 1024.0 meters, view angle 45.0 degrees), press Control+Home.
Sandbox Item Editor Menu Commands
- New (Control+N)
New command removes all objects from the scene and re-loads the default viewing level. It also resets most viewing parameters, such as camera position and viewing angle.
- Open (Control+O)
Open command displays a dialog for choosing a file to be loaded. In the example below, "Objects/MyData" folder is shown, which contains "test_collada" and "test_viewer" locations. A hang-glider model is loaded from "test_viewer".
After the model is loaded, it can be viewed under different angles and lighting conditions, as shown below:
Files with .CGF extensions, such as "hang_glider.cgf" from "test_viewer" folder shown above, are loaded into the Item Editor directly. The editor can also load models in Collada format. These files are expected to have .DAE extension. If a .DAE file is selected for loading, a "COLLADA Converter Tool" dialog window will pop up, providing various options for data conversion. The dialog window has two modes, Simple and Expert. In most cases, Simple mode should be sufficient. In Simple mode, all conversion-related options are set to standard values. These values can be also set explicitly using the Expert mode, if needed. Example of converting a Collada model, step-by-step.
Once a Collada model is converted, it can be loaded for viewing. Every time the "Open" command is called, the previously loaded geometry model is removed from the scene. In other words, "Open" command is not incremental and allows to view models one at a time. When a new model is loaded, its material properties are automatically saved into a .MTL~ file, located in the same folder as the model file, for backup purposes.
- Import (Control+I)
Import command allows to add a geometry model to the scene, without removing previously loaded object[s]. Each newly loaded object is automatically selected, to make it easier to move it on the scene.
- Open project folder
Opens the folder where the item is stored on user computer.
- Exit (Control+Q)
This is the standard way to exit the Item Editor.
Commands in this menu allow to pack object models into a single item, a zip archive with geometry and texture files. Once an item is created, it can be uploaded to the server.
- Pack folder for upload...
Pack all models, materials and textures in the project folder into a single itemdata.zip file. The itemdata.zip file will be created in the same folder. A snapshot of the screen is taken and stored as a 400x400 JPEG image file icon.jpg, in the same folder. Also, a Display.xml file is created, which contains a list of packed objects. You can overwrite the icon file, using "Tools -> User commands -> Icon capture" command. This command is enabled when an object is loaded using "File -> Open" command, which specifies the current folder.
- Capture icon
Captures the current view in 400 x 400 resolution and saves as "icon.jpg" in the project folder. This file is required for uploading data to Blue Mars, along with the itemdata.zip archive. If the project folder is not set, the image is saved in Game/ScreenShots/HiRes folder. Consecutive calls overwrite the "icon.jpg" file.
- Check item in Blue Mars...
The Blue Mars game client is pre-programmed to automatically load a data item, specified in Game/Objects/MyData/Display.xml file. By using this command, the newly created Display.xml data item is copied to Game/Objects/MyData and the Blue Mars client is launched. The objects packed in the data item will be displayed on the start-up level, after user logs into the game.
- Open upload page...
Opens the Blue Mars Developer MyPage where you can upload your data, check the status of previous submissions and manage your account.
- Delete (Del)
Delete currently selected object(s).
- Clone (Control+C)
Clone (duplicate) currently selected object(s).
- Select all (Control+A)
Selects all objects on scene. The default 3-point light source, used for indoors illumination (keyboard shortcut Alt+4), is not selected. Should you need to select this special object, please use "Select Objects" tool (Control+T).
- Go to selection (F)
Goto selection command positions the camera at the optimal viewing distance from the object. Also, the viewing angle is reset to default value of 45 degrees. Keyboard shortcut "f" stands for "focus", similar to Maya UI command.
- Orbit mode
This camera control option allows to orbit selected object(s), by pressing the right mouse button and moving the mouse. This option is set to "true" at start-up. When set to "false", the camera rotates about its own position.
- Editing Mode
Editing modes specify what happens on a left-click over the loaded model. The default action is Select(4), when the object is selected. Selecting an object is required for performing any operation on the object, such as changing its surface properties with the Material Editor. Besides simple select, there are three additional modes: Move(1), Rotate(2) and Scale(3), which provide the basic transformations for the object. The numbers in brackets show the keyboard shortcuts for these commands.
- Wireframe (F3)
Toggles rendering between solid and wire-frame modes.
- Information (I)
Toggles on-screen information about the current camera settings and rendering statistics.
- Debug draw(b, B)
Debug Draw Next(b) and Debug Draw Previous(B) change the debug information mode, which ranges from 0 to 15. Value of 0 turns debug display off. Debug modes show memory usage, number of materials, triangles, and other information on the loaded object.
- Show/hide helpers(Shift+Space)
Helpers are small text labels and icons, attached to the object. They provide more information about the object, such as it's registered name and type.
- Toggle proxy (Shift+P)
Toggles display of geometric objects between visible shapes and their approximate simplified shapes, called proxy. Proxies are used in processing collisions.
- Render settings
Allows to turn rendering of Sky, Terrain and Water on and off. By default, all the settings are on, although there is no Water present in the scene. With the Terrain and Sky switched off, the loaded model will appear on black background.
The editor has 3 preset outdoor lighting conditions: Morning(Alt+1), Day(Alt+2) and Night(Alt+3), and one artificial light setup with 3 local light sources, called Indoor(Alt+4). In addition, HDR (H) command enables High Dynamic Range rendering mode, which simulates many visual effects, such as blooming and eye adaptation delay. HDR mode significantly improves rendering realism for scenes with extreme lighting.
- Camera view angle
The default field of view for Sandbox Item Editor camera is 45 degrees, which can be changed with commands in this menu group. Wide (Contol Up Arrow) increases the viewing angle. The object appears farther away and perspective distortions become more noticeable. Zoom (Contol Down Arrow) decreases the viewing angle. Standard (Control Home)resets the viewing angle to its default value of 45 degrees. Camera settings can also be reset by using Goto Selection command (F).
- Draw sub-objects elements
Toggles display of normal vectors, tangent vectors and bi-normal vectors on and off. Use these commands to examine your model and check if polygons are oriented consistently.
This menu allows to quickly switch between predefined quality settings.
- Very high
This option gives is the best rendering quality, but may cause noticeable drop in frame rate on some computers.
This is the default setting, same as in Blue Mars client program.
- Screen capture (Control + P)
Captures the current view in full resolution and saves as snapshot_000N.jpg in the project folder. If project folder is not set, the captured image is stored in MyData/ folder. Consecutive calls increment N-value (files are not overwritten).
- Copy textures to project folder
A project folder points at the location of the last object, loaded with "File -> Open" command. (Note: "File -> Import" command does not change the value of "project folder"!). "Copy textures" command verifies that all texture files, referenced in the material file of the selected object, are located in the project folder. If some texture files are found to reside outside the project folder, they will be copied into the project folder and their material files will be adjusted accordingly. "Copy textures" command requires exactly one object to be selected.
- Force visible
If a loaded model does not appear on the screen, "Force visible" command may help. Select the model in question (for example, using "Select Object" dialog, Control+T command) and use "Force visible" menu command. All object's materials and sub-materials will be set to default failsafe values (100% opacity, double sided, standard diffuse texture) and the camera will point at the object. Control+Z (undo) will restore the initial material(s), however, backing up the material file is recommended.
- Open view pane
Gives access to different view panes, listed below.
- Time of day (Alt+T)
Shows Time-of-Day control panel for setting and animating outdoors lighting conditions, including various atmospheric effects. Also, that control panel allows to import .TOD files from other levels (aka Blue Mars Cities), for precise tuning of material properties of objects intended for usage in these cities.
- Select object (Control+T)
This command brings up the "Select Objects" dialog window with a list of all selectable objects on scene. Objects can be selected by double-clicking their names.
- Material editor (M)
Material editor allows to specify all parameters of the selected object's material. All changes are automatically saved into an .MTL file, located in the same folder as the object model file. On loading a model, a backup material file is created.
- Time of day (Alt+T)
- Show status bar
Toggles the status bar at the bottom of the main viewing window, which displays the results of the most recent user action, such as loading a model, changing camera parameters, etc. By default, the status bar is enabled.
- Show Rollup bar (E)
Opens the RollUp Bar, a tool that allows to display and edit properties of currently selected object.
This menu provides quick links to Web resources.
- Web help
Opens Item Editor page in the Blue Mars Developer Guidebook (you are reading this page now).
- Web forum
Opens Blue Mars Developer Forum page.
- Web developers
Opens Blue Mars Developer MyPage.
Shows credits and release version.
Example of converting a Collada model, step-by-step
In this example, we use a test model of a jacket, located in <BlueMars install location>/Game/Objects/MyData/test_collada/ folder, which contains the Collada document and two texture files in TIFF format.
In order to do the following steps. You MUST have write permission on MyData folder.
Model conversion step
Use File->Open command and select the Collada file Jacket_Static.dae. A conversion dialog window will appear, shown below. Set Output type selector to "Geometry" and click "Convert" button. A small window will pop-up, asking for overwrite confirmation. Click "Overwrite". The file will be converted in a separate command window which will appear and stay active for the duration of conversion process. After the window disappears, click "Load" button to load the newly converted model now or "Close" to exit the "COLLADA Convert Tool" window. You can load this model later, as shown below.
Loading converted file
Repeat the File->Open command (or use Control+O keyboard shortcut). Set "Files of types" to "Geometry files (*.cgf)" and select Jacket_Static.cgf. This file is the result of conversion, performed in the previous step.
Click "Open" to load the file into Sandbox Item Editor.
If you examine the content of "test_collada" folder, you will find the following new files:
- Jacket_static.cgf -- the geometry file
- Jacket_static.mtl -- material description file
- Jacket_static.mtl~ -- back-up of the material file, created at the moment the model was loaded.
- *.dds - texture files in .DDS format, automatically converted from the original .TIF files by CryEngine when the model was loaded into the Item Editor.
How to avoid dramatic color changes in uploaded models
Although all Blue Mars editors use the CryENGINE2 rendering engine, some changes in objects' appearance should be expected after uploading models to Blue Mars. The following guidelines were suggested by several external developers and Avatar-Reality artists, to minimize the difference.
- Set "Config Specs -> High".
In 7/12/2010 release of tools (version 0.0.9782.0), there is a mismatch between default values of config specification between the client and the Cloth Editor: in-game, the settings are set to "High" and the Editor uses "Very High". This may contribute to shading differences in the editor and in the client, when started by "Check in Blue Marse" command. Although we were not able to reproduce the difference, set the Editor to "High", just to be on a safe side. In the next release, the config settings will be better synchronized.
- Check HDR option.
In the Editor, check how the model in question looks in "HDR-on" and "HDR-off" settings, which corresponds to Client "high" and "low" rendering settings. To toggle HDR on and off, hit 'H' key. Keep in mind that in all Editors, HDR is off at start-up, and in the Client, default rendering mode is "high", that is HDR is on.
- Check in Blue Mars command.
Always use "Check in Blue Mars" command, before packing the model for upload. Note, that if you plan to use compression for packing, use the same compression options for "Check in BM" command as well, for previewing. In some cases, texture quality can be severely affected by compression, including loss of detail and/or change in overall color.
- Lighting in Welcome Area is synchronized with the Editor
. Starting from 7/1/2010 release, the "Welcome Area" in Blue Mars will have the same Time-of-Day settings (TOD) as the Viewer level, used in Item/Cloth/Body/Shop/Furniture Editors. These TOD settings are recommended by AR artists for use with Blue Mars cities. (Note, the Beach City has different TOD settings!). Thus, objects should look similarly in all these editors and in the Welcome Area, adjusting for presence of geometry close to the camera, which may affect the HDR rendering.
- Follow good modeling practice in material editor:
- use mid-range values for diffuse color (for example, 127, 127, 127), to avoid washed-out colors under bright lights;
- use mid-range values for specular colors, too, to prevent over-sized specular highlights;
- Use TOD files, if available.
If you know the destination city for your creations, where they will be installed or worn as attachments, and you want to tune up their materials for that city, contact the city owner and ask him/her for a TimeOfDay settings file (say, "interesting_city.tod" file). This file can be exported using the CityEditor, by opening "View -> Open ViewPane -> TimeOfDay" tool and clicking "Save" button. Starting from 7/12/2010 release, all editors inclide TimeOfDay tool. Use it to import "interesting_city.tod" to your Item/Cloth/Body... editor. This is the closest you can get to the final destination settings.
- Flush Material Editor cache. Material Editor sometimes fails to flush its cached values even if the materil parameters have changed. The only way to force cache update is to close and re-open the Editor. Do this before packing and uploading, to make sure that you see what other people will see when your item is released in Blue Mars.
- Point-of-Sale lighting. When an item is released in game and set up for sale, players can preview it by clicking on this item in a shop. When that happens, the item is illuminated by 3 local lights only, which are standard for all cities, shops and shelves. City-specific TOD settings do not affect this "pre-sale" viewing mode. To check how your item will look at point of sale, use "Display -> Lighting -> Indoor" (keyboard shortcut Alt+4). Also, do not forget to turn HDR on.
Using Material Editor, step-by-step
Using expert mode for trouble shooting
When using the COLLADA Converter Tool, if a .dae file is not converting properly, then you may need to use the options found under the Expert tab.
- Check to see if your Input file and Output file are looking in the correct directories for the .dae and .cgf file locations.
- Make sure "Prepend path to texture file names in .MTL file" is checked and that the path listed in the text box is pointing to the location of the .dae file and texture files relative to the Blue Mars Online/Game directory.
- Under the Step-by-step conversion section you can check the process of converting your .dae file to .cgf to see where problems occur.
- Select Import to create the .cgf and .mtl files
- Select Check to see a report of the import command
- Select RC
- Select Check to see a report of the resource compiler
- The Single-click conversion section allows you to convert the .dae model using the processes from Step-by-step conversion.
- Selecting the Convert button will generate the .cgf and .mtl files, and run the resource compiler.
- The Check button shows the reports from the previous conversion.
- The Close button will close the converter tool, and the Load button loads the last .cgf file created by the COLLADA Converter Tool, or closes the converter tool if no .cgf file has been generated.
If no error messages are displayed in reports created by the Step-by-step conversion method, and the .cgf is not loading or being generated, then try importing the .dae file into the modeling software that was used for exporting. If the .dae opens correctly in the modeling software, then try re-exporting the original model to the COLLADA (.dae) format.
- If using 3ds Max to export, then make sure to Reset Xform on the model before exporting.
How to reuse existing data items
In particular, two tasks are of special interest:
(1) How to take an existing MyData model with materials and create an entirely independent version of it;
(2) How to start a new model, and then apply materials from a pre-existing model to it, without tweaking any files relating to the previous model.
- Open the City or Block Editor.
- Go to View -> Open view pane -> Asset Browser
- In the Asset Browser, navigate to the MyData Directory and create a new folder for the duplicate item. (Right Click in the Asset Browser's file view area and select create new folder)
- Open a regular Window's Explorer window and navigate to the directory that contains the items to duplicate.
- Select the items that need to be duplicated, and then drag and drop them into the new folder created in the Asset Browser. If the .cgf (.chr for cloth items), .mtl, and texture files are all moved into the asset browser in the same operation, then all of the file paths in the .cgf and .mtl will be updated to reflect the new file locations.
- Using the asset browser again, drag and drop files that are going to be reused into the new item's directory. This will fix the file paths for the textures in the material file.
- Generate the material for the new item using the Item, Cloth or Furniture Editor.
- Open the material editor in the City or Block Editor and navigate to the directory of the copied .mtl and the newly generated .mtl. This step could be done in another editor, but the City and Block Editors allow access to material files without having to open the .cgf or .chr that uses that material.
- Right click a sub-material of the duplicated .mtl and select copy.
- Right click a sub-material of the new .mtl and select paste, and then select cancel when asked to save.
Please see this page for alternative solutions and discussion.
To post a discussion topic, or report a bug, please use Blue Mars Developer Forum page.