Blue Mars Sandbox Cloth Editor

From Blue Mars Developer Guidebook

Jump to: navigation, search
There are security restrictions on this article




Sandbox Cloth Editor is a tool for creating wearable assets: cloth, hairstyles, shoes, jewelry and other items, that can be attached to an avatar.

Quick start

How to...

Recently added or changed features:

  • Added "No depth bias" check-box, for precise placements of attachments.
  • Added "Single pin attachment" check-box for rigid objects.
  • Allowed multiple "Check in Blue Mars" command, without restarting the client.
  • For complete list of new features, please see Release notes.


    Cloth Editor converts a geometry model of a static object (for example, a piece of cloth) into a deformable wearable entity, called an attachment. Cloth Editor requires the input model to be in Collada format, with .DAE extension. The output attachment pack will consist of three files, located in the same folder as the input .DAE file. These files will have the same base name as the .DAE file. The extensions and meanings of the output files are:

    • .CHR -- a geometry model of the wearable item, in binary format;
    • .MTL -- material information file in XML formal;
    • .CHE -- binary data, needed for binding attachment to the avatar.

    Once these files are created, the attachment can be placed on the avatar.

    Sandbox Cloth Editor Commands

    Cloth Editor has two groups of specific commands, "Cloth" menu and "Cloth Editor" dialog window, shown in the image below. All other menu elements ("File", "Edit", "Display", etc.) are nearly identical to Item Editor and are explained in great detail in this page.

    Cloth Editor

    Menu commands

    Cloth Editor menu commands outline the general process of making, previewing and uploading new cloth items.

    • Make cloth...
      Opens the "Cloth Editor" dialog window, which provides controls for making and testing cloth and other attachments. This is where the most work is done. These controls are explained in detail in Dialog Commands section of this page and illustrated using this example.

    • Pack cloth for upload...
      This command creates a zipped archive file, called, that can be uploaded to Blue Mars for testing and distribution.

    • Capture icon
      Creates a 512x512 icon.jpg file with the current view, required for uploading your data. Before calling this command, make sure that the cloth item is clearly visible and centrally located. This command can be repeated multiple times. The icon.jpg file will be overwritten.

    • Check cloth in Blue Mars...
      Once a wearable cloth item is created, it can be previewed in-game using the Blue Mars client. Important: when you login into Blue Mars, make sure that you are using an avatar of correct gender!

    • Open upload page...
      Open developr page After login, you can upload your newly created and the icon.jpg for testing and distribution. During uploading process, please make sure you to select "WEARABLE" category for your submission. Technical limitations on the uploaded content are described in detail on this page.

    Cloth Editor Dialog Commands

    Cloth Editor dialog commands provide detailed control over the cloth-making process, starting from the source geometry files in Collada format, ending with wearable assets in Blue Mars format.

    • Model
      "Model" specifies the geometry model file in Collada format. Two examples are provided with the installation, located in <Game/Objects/MyData/test_cloth/> folder. The cloth geometry must contain only polygons. Skins, skeletons, morphs are not allowed. Other requirements: (a) max triangle count 5000; (b) max material count 30. During cloth making process, the input model will be triangulated automatically, if needed. However, it is recommended to do triangulation before exporting the model into a Collada file, especially if the model contains complex vertices.

    • Avatar
      Select an avatar type: female or male. All cloth in Blue Mars is gender specific.

    • Asset
      Select an asset type: cloth, hair, shoes, etc.

    • Style
      For selected asset type, select a style, that most closely matches geometry of the model. In other documents, styles are also referred as "cages". Styles are generalized forms for different types of garments: pants, shorts, T-shirt, etc. For male and female avatars, style selections differ, in all asset categories.

    • Create And Attach
      Once the model, avatar, asset and style parameters are selected, "Create And Attach" command can be used to make the cloth. Making cloth is a multi-stage process, which may take between several seconds and up to a few minutes to complete, depending on the complexity of the cloth model. The Jacket_Wearable.dae model, provided as an example, can be processed on a 3 GHz PC under 4 seconds. This model has 1,353 triangles. When the cloth is created, Cloth Editor will load an avatar and puts the new cloth on.

    • Step-by-step
      Commands in this group do the same job as Create And Attach, in three separate steps: create, load avatar, attach. Also, they allow to attach previously created items and examine the content of the project folder.

      • "Create" command creates cloth, from Collada model into Blue Mars asset. On error, a dialog window will pop up, offering to view log files. Log files should be used for diagnostics, troubleshooting and error reports. These files have .LOG extension and are located in the same folder as the source model file. On success, a message will be displayed in the status bar "Attachment files created". Hint: keep status bar open, by using "View -> Show status bar" menu command. "Create" command has a "Create material file" option (default ON), which can be switched off, in case you want to keep your customized material file, created earlier. Otherwise, the material file will overwritten, as specified in Collada source model file.

      • NEW! "Single pin attachment" option is provided for creating rigid attachments, such as swords, medals, pins, labels and other wearable objects that should remain undeformed. When this option is enabled, Cloth Editor will search for the closest triangle in the cage shape and will bind the whole cloth items to that single triangle. Note, that some cages may have large triangles that *may* deform during avatar animations. Thus, it is always a good idea to check the results with provided default animations, in "Animations" group of buttons.

      • NEW! No depth bias
        Use this option to disable depth-bias in game, for this cloth item only. By default, uploaded cloth items will be be offset from the avatar skin at small distances, randing from 1cm to 3cm, to minimize unwanted cloth/skin penetrations. This feature is called depth-bias, and it only happens in the viewing direction. Disabling depth bias may be a good idea for those attachments that must appear "as is". For instance, facial attachments (beauty marks and similar), should be submitted with this option checked.

      • "Load avatar" brings a fresh avatar with default clothing to the scene.

      • "Attach" command places the newly built cloth item onto the avatar. The avatar will be loaded automatically, if not loaded yet. On success, "Attachment processed successfully" pop-up window will appear and ASSET.XML file will be created in the project folder. This file contains information about avatar gender and type of attachment.

      • "Force visivility" command is useful when you click "Create And Attach" and can not see the newly created cloth. Very often, this happens due to incorrect or unwanted material settings, such as 0% opacity. This command resets all materials and sub-materials to default values (100% opacity, gray diffuse color, single white diffuse texture, 2-sided), reloads the model and sets the camera focus on the model. Warning: the model material file will be overwritten!

      • "Open folder" allows to examine the content of the directory, where the source Collada MODEL.DAE is located. When cloth-making command is finished, three new files should appear in this folder: MODEL.CHR, MODEL.CHE and MODEL.MTL. All error log files will also be stored in this folder. These files will have .LOG extension.

      • "Attach more" command allows to attach additional cloth (hair, shoes, etc....) items to the avatar. You will be prompted to select an "asset.xml" file, located in some other folder, where previously created item is stored. This command is useful for testing inter-penetrations between multiple cloth items. Multiple attachments are also supported in Blue Mars developers' client, launched by "Cloth -> Check cloth in Blue Mars" menu command.

    • Detach
      Commands in this group remove cloth from the avatar. "Single detach" removes one item at a time, according to current selection of asset and style. "Detach everything" removes all cloth items, hair, shoes, etc., leaving a bare manikin.

    • Animation
      These commands trigger seven different animations that will run in looping mode and one static T-pose. Use these buttons for testing how new cloth deforms with the avatar body.

    • Facial expressions
      Similar to "Animation" group, these commands start various facial expressions. They should be used for testing facial attachments: ear-rings, piercing, etc. Facial animations run once per click (non-looping).

    • Look at camera
      When this option is selected, the avatar will turn his/her head towards the camera during playback. This option takes effect when a new animation or facial expression is played.

    • Custom speed
      This option allows to run animations and facial expressions at custom speed. Similar to "look at camera" option, new speed value will take effect when a new animation or facial expression is played.

    • Timeline slider
      This slider allows to set the animation time manually, using the left mouse button or mouse wheel. After the button is released, the animation is paused.

    • Rotate avatar
      To help examining the model, an avatar can be set spinning, at various speed values, using "<" and ">" buttons. Multiple clicks on the same button will increase the speed, clicking on the opposite button slows down rotation. "Capture" button save the current view as "screenshot_000N.jpg" file. This button is a shortcut to "Tools -> User commands -> Screen capture" menu command.

    • Other commads
      Commands in this group allow to use a customized body for testing your cloth items and take a full-screen snapshot of the current view.

    Example 1: creating and testing sample cloth

    In this example, we will create and wear two cloth items: a white tank-top and a green jacket. You can also find a more detailed tutorial on creating cloth in the Tutorials page.

    • Start the Cloth Editor, by clicking this icon:

    • Use "Cloth -> Make Cloth" menu command to open up "Cloth Editor" dialog window.

    • Use "Browse" button and select "MyData/test_cloth/Tanktop.dae" Collada file. Set the other parameters as follows:
      Avatar = Female00,
      Asset = Cloth,
      Style = InnerTops_v02

    • Click "Create And Attach" button, answer "Yes" to confirm file overwrite. The cloth-making process will take a few seconds. Then, a female avatar will appear, wearing a new tanktop.

    • Run test animations to check the new tanktop: walk, run, jump. This step is needed to make sure that the selected style fits the current cloth model. For tanktop model, "InnerTops_v02" style is the best match, for other garments, you may need to experiment with different styles, especially if the model has large areas that loosely follow body movements, as in skirts or long dresses. When satisfied with the results, the cloth is ready for packing and shipping, using "Cloth -> Pack cloth for upload..." menu command.

    Example 2: creating and testing hair

    In Blue Mars, hair is attached to an avatar and dynamically simulated, using the same mechanisms as for cloth. However, creating believable hair is somewhat more complicated, because there are more effects that must be captured and represented. Unlike cloth, many hair styles have volume. Also, hair is expected to split at ends, which is difficult to represent geometrically. Finally, long hair moves differently at different lengths from the scalp. All of these features call for special modeling/texturing techniques. We provided three women's hair styles and one men's hair style, which produce acceptable results. In the following example, we will show how to model and texture short female hair, shown below:


    For this exercise, download this zipped file: File:Test, place it into "MyData" folder and unzip. Please make sure that your unzipper didn't add an extra "Test_hair" folder. After unzipping, you should have the following files, located in "MyData/test_hair/clare/" folder:

    • Hair3.dae -- geometry model in Collada format (no materials!)
    • Hair3.chr -- geometry model in BM format
    • Hair3.che -- binding file
    • Hair3.mtl -- manually edited material file with the following textures:
    • -- diffuse map
    • -- specular map
    • -- detail map

    To load and attach this hair model, please follow these steps closely, because they differ slightly from the previous examples:

    • Start the Cloth Editor.
    • Use "Cloth -> Make Cloth" menu command to open up "Cloth Editor" dialog window.
    • Click "Browse" and select "MyData/test_hair/clare/Hair3.dae". By doing so, we set the project folder to "MyData/test_hair/clare/".
    • Set Avatar = Female00, Asset=Hair, Style=ShortHair_Bangs.
    • Click "Attach". A female avatar will appear, wearing new hair, as shown in the image above.

    Note: for this example, both .CHR and .CHE files are already provided, so there is no need to use "Create and Attach" or "Create" button. A simple "Attach" command will be enough. You can experiment using "Create and Attach" button, in order to generate the .CHE and .CHR files with different hair styles. If you do so, please save a copy of provided .MTL file, or unselect "Create material file" check-box. The material file provided for this example was manually edited, after processing the source Collada file, so it's a good idea to save it.

    Hair geometry model

    Image:cloth_editor__clare_hair_model.png Image:cloth_editor__clare_cage.png

    As the left image shows, the hair geometrical model contains two monolithic plates (Maya screenshot). The outer plate covers the whole head and is placed slightly above the skin surface, to indicate some volume. The lower inner plate starts at approximately ears' level and extends down. The mesh has a low polygon count and is bound to the "ShortHair_Bangs" cage (right image, Cloth Editor). The upper part of the cage is pinned to the avatar head, to prevent the hair from sliding off the head. The lower parts of both plates are hanging free.

    Hair materials and textures

    Material parameters are presented in the image below.


    A few comments on the choice of parameters and their values, from top to bottom:

    Material Settings
    Ar_metal shader is used, because it allows anisotropic shading effect.

    Opacity Settings
    In order to show split hair ends, the transparency map was stored in the alpha channel of the diffuse map. The 99 value of opacity makes the hair practically opaque everywhere, except for ends (see textures below). The cut-off value for the "AlphaTest" value is set to 6 (very low). This value must be tuned up manually, for the transparency map.

    Lighting Settings
    The diffuse map itself is greyscale, so the hair color comes from the "Diffuse Color" field, in this case, dark brown. Same for the specular map. Reminder: the Material Editor bakes the specularity level into the "Specular color" values.

    Texture Maps
    The grayscale diffuse map has also a transparency map in its alpha-channel, which allows to show split hair at the edges of the hair plates. To enable alpha-channel, the "Opacity" value has to be less than 100%. In this example, 99 value is used, which is enough to trigger transparency at the ends and still keep the hair almost opaque everywhere else. The diffuse map is blurred at the roots of the hair. More details are added with specular map (also grayscale) and detail map. All three maps, combined together, sufficiently simulate hair volume. Detail maps, in general, scale well with distance, which allows to avoid detail-popping artefacts, during camera zoom.


    Diffuse, specular and detail maps

    Shade Params
    "Specular multiplier" and "Anisotropy shape" parameters specify the shape and contrast of the highlight of the hair surface. "Detail tiling" allows to make individual hairs look thinner/thicker.


    Varying "Detail tiling U" values: : 1 (left, thick hair), 5 (right, thinner hair)

    Shader Generation Params
    To allow anisotropic and detail bump mapping, check the corresponding boxes.

    Avoid penetrations with avatar skin

    The following guidelines were collected from many cloth designers during, who kindly shared their experience (many thanks!) and from Avatar-Reality artists as well. Some of these guidelines are illustrated in this video-tutorial. The narration script is here: File:2010 cloth tutorial voice narration script.doc.

    • Use reference avatar model.
      Always check your cloth model against the reference avatar model (the render mesh). Do not use cage shapes for reference: some cage shapes penetrate the avatar's skin, even in the neutral pose. An example: load a reference mode from Template/Avatar/Female00/Model/Female0000/Body/Female0000_Body.dae then add Template/Avatar/Female00/Assets/Cloth/FullBodySuits/FullBodySuits.dae. Observe how full body suit goes under female skin: if this cage is used "as is" to make a nanosuit, there will be bad penetrations on the chest area. Thus, always check the cloth with the render mesh for penetrations.

    • Match vertex positions.
      Whenever possible, try to place vertices of your cloth model right above the vertices of the reference skin model, especially in high-curvature areas, such as elbows and knees.

    • Use higher density mesh in such areas.

    • Use appropriate cages for desired cloth types.
      Make sure that the selected cage covers your cloth model completely. Uncovered parts will not be deformed properly, which will make these cloth areas move as a rigid object.

    • Use reasonable offsets for cloth.
      We recommend to place the cloth surface at 3.5 mm away from the skin, or farther. With this offset, most cloth items don't show penetration artifacts, even with conservative rendering settings ("Depth Bias" flag turned off). In the Blue Mars client, the Depth Bias is turned on, for extra protection. Depth bias moves vertices on the cloth model towards the camera, by additional 1-2 mm. This often helps to hide some penetration artifacts, but not all. You may move cloth a little closer to skin (perhaps, make it as tight as 2 mm), but these settings are risky and will likely result in visible cloth/skin penetration, especially around the edges.

    • Test in the Editor.
      After attaching cloth in the editor, test carefully for penetrations, using old and new existing features in cloth editor:

      • use "conservative" rendering mode, which shows true geometry deformations (turn "Display -> Depth bias" OFF)
      • use camera spin and capture buttons to create snapshots of problematic areas
      • slow-motion animation playback

    • Always test cloth in Blue Mars.
      Before packing cloth for uploading, test it in the Client, using "Cloth -> Test cloth in Blue Mars". In 7/1/2010 release, Blue Mars client supports multiple attachments, thus, you can dress your avatar as you wish in the Cloth Editor and preview all these cloth items in the client. That applies to all attachment categories: cloth, hair, shoes, accessories.

    Error messages

    The process of creating wearable attachments consists of 6 steps, starting from the cloth model in Collada format. Most of these processes use logging to report errors and warnings, and the Cloth Editor will offer you to examine the appropriate log file, if something goes wrong during the cloth creation. The following list explains the meaning of these messages, at every stage:

    Step 1: Merging geometries. At this stage, Cloth Editor checks how many geometry elements there are in the input collada model. If multiple geometries are found, they are merged into one. Possible error messages:

     (1) "Error opening COLLADA file"
           The file can not be found at specified location.  
           This may happen when the source Collada file name is typed in manually into "Model" control 
           in the "Make cloth" dialog window.  
     (2) "Error in file.dae: no root element found"
           Meaning: the collada document is corrupt and/or incomplete.  
           What to do: re-export your model.
     (3) "Error in file.dae: unsopported version N." 
           Meaning: the collada document is too old or too new.  Presently, the Blue Mars converter supports 
           Collada versions 1.4 and 1.4.1.  
           What to do: re-export your data using tools with supported version.

    Step 2: "Adding skeleton to the model". The pre-processed collada, created on the previous stage, gets a special-purpose skeleton added to the geometry model. Possible error messages are:

     (1) "Error: model already has a skeleton or morph targets"
           Meaning: the collada source file has a skeleton and/or morph shapes. 
           What to do:  re-export your cloth model again, making sure that joints, skin, or morph shapes are not selected.  
           In some situations, you might need to copy your model into a temp file, and remove all unwanted elements before 
           exporting data into a collada document.
     (2) "Error: failed to get controller library"  or
         "Error: COLLADA document has no geometry"
           Meaning: collada document is corrupt.  Re-export, as described above.
     (3) "Error: COLLADA document has no geometry library".  
           Meaning: empty document.  Check your source data.
     (4) "Error: COLLADA document has multiple geometry libraries" or
         "Error: COLLADA document has multiple geometries"
           Meaning: the preprocess failed to merge multiple geometry nodes into one.  
           What to do: merge all your geometries manually in your modeling tool and re-export.
     (5) "Error: Geometry not found"
         "Error: Geometry primitives not found"
         "Error: Vertex position accessor not found"
         "Error: Accessor data retrieval failed"
           Meaning: corrupt or empty collada document.  Re-export.

    Step 3: Importing Collada model. The actual conversion is performed. Possible errors:

      (1) "Error: No filename arguments specified"
            Meaning: no argument is given.  Should never happen in Cloth Editor, 
            because this error is detected at step 1.
      (2) "Error: Unsupported file extension"
            Meaning: the output file is requested to have other format, than .CHR, .CGF or .CAF.   
            For Cloth Editor, only .CHR files must be created.  That error should not show up in Cloth Editor log files, 
            because output file names and extensions are generated automatically.  This error may be seen only if
            bmImportCmd.exe is used directly, outside of Cloth Editor (not recommended).
      (3) "Error: Name fix failed"
            Meaning: the converted failed to create unique names for nodes in the Collada document.  
            What to do: make sure your source file has no objects with "exotic" names, even if supported by the modeling tool.
      (4) "Warning: No HitMesh objects found"
            Meaning: the model does not contain HitMesh, a reserved geometry element for skeletal-based model.  
            This message has meaning only for older version of MAX Collada export plugin and can be safely ignored.
            What to do: ignore
      (5) "Error: Default materials generation failed"
            Meaning: the importer failed to generate a default material.  
            What to do: delete all unused materials in your model and re-export. 
      (6) "Error: Cannot open file for writing" 
            Meaning: the importer failed to save either material or geometry file.  
            What to do: make sure you have write permission in the project folder.  

    Step 4: Binding vertices. Possible errors:

      (1) "Error: Error in file.chr: vertex accessor not found." or 
          "Error in file.chr: illegal number of vertices."
            Meaning: corrupted file.  Should never happen at this stage.  
      (2) "Error: Error: failed to load cage subdivision file cage_name."
            Meaning: the Cloth Editor is missing one of the standard system files.  
            What to do: re-install Cloth Editor.

    In some cases, Cloth Editor may produce geometry file with unexpected look, for example, discolored patches at seemingly random places, or other shading artefacts. It is recommended to examine the surface normals using "Display -> Draw sub-object elements -> Normals". During conversion, the source collada model is triangulated automatically, but the triangulation algorithm is not very sophisticated and may miss / ignore / mistreat certain features that should not exist in the first place: multiple normals, poles, degenerate edges. Thus, if you are having unexpected results, please double check that your source model is "clean" before export, and, if, possible, triangulated.


    Cloth Editor is designed as a general tool for creating all wearable assets. However, its functionality and usefulness are defined by a set of pre-built models (shown as styles in the icon preview window, and also known as "cages"), that are shipped with the Editor. In this release (04.13.2010), there are over a dozen of female clothing styles and a few styles for men cloth. Shoes and hair styles are also provided and one female shoulder bag is shipped as an example of "other" type of wearable asset. More variety will be provided in upcoming releases.

    There is one known issue with cloth, that some developers may find objectionable. Presently, the attachment system in Blue Mars is designed with the intention to minimize penetrations between the cloth and the avatar's skin. However, multiple cloth items may occasionally penetrate each other. A jacket can penetrate a tanktop in the upper body area, a shirt and pants can cross each other in the waist area. We are aware of this feature and are working on it. At the moment, we suggest an interim solution for cloth designers: create and test cloth not as individual items, but as complete sets (for example: shirt, pants, jacket, scarf), which are meant to be worn together. This is similar to what happens in real life, when fashion designers create and present their collections.

    As all Blue Mars assets, submitted cloth items must satisfy technical limitations, such as max number of used materials, number of polygons and the total size of the submission pack. More details can be found on this page



    Several cloth styles were replaced by newer version (v2), with better cloth/body deformations. As with earlier updated, we provided backward compatibility with older styles. Clothing items that have been built and released in Blue Mars, will continue to be supported in Blue Mars client. Thus, players that already purchased and downloaded such items, will still be able to wear them in Blue Mars. However, if you plan to edit and/or resubmit such items, you will be prompted to rebuild your models, using the currently available styles.


    To post a discussion topic, or report a bug, please use the Blue Mars Developer Forum page. Please be as specific as possible, use screen capture of troublesome cloth cases and debug output from "Make Cloth" command, as described above.

    Problems with this wiki page? Contact us either by: Support Email or Support Ticket System

    Blue Mars Guidebook Privacy Policy
    Blue Mars Guidebook Community Guidelines

  • Personal tools