Create Your Own Module

1. The EMCCV Mindset

The EMCCV is a viewer for modules, just like a word processor is a viewer for documents. It displays modules, offers tools for working with them, and generates the whole interface for you: the tabs, the checkboxes for turning things on and off, the style options and the colour pickers.

A module (in KiSS terms: a “doll”) consists of two things:

• Graphic files, usually all matching a theme or concept — for SailorXv3, that's Sailor Moon.
• A config file (config.xml) that tells the EMCCV how to display those graphics: their order, position, colour, which options to offer and much more.

The final image is made of many semi-transparent, individually coloured images layered on top of each other. You decide how they are layered — and the EMCCV does the rest.

2. What You Need

• A plain text editor, ideally with syntax highlighting for XML — for example Sublime Text or Visual Studio Code.
• Your graphic files — more on these below.
• A little patience — your first module can be tiny, and you can grow it step by step.

The faster your computer, the more complex you can make your module.

3. The Module Folder

Each module lives in its own folder inside the EMCCV modules folder. A module folder contains:

modules/
  MyModule/
    config.xml      the config file
    data/           all graphic files (use as many subfolders as you like)
    entities/       saved characters (an .xml and a .png preview for each)
    images/         exported images

Only config.xml and data are needed to get started; the EMCCV fills the other folders as you save characters and export images.

4. Preparing Your Graphics

• Use PNG or GIF files with transparency. PNG supports semi-transparent pixels, so soft edges and shading look great. GIF works too — handy if your artwork already exists as GIFs — but a GIF pixel is either fully transparent or fully opaque. Make sure the file names in your config file match your files, including the extension (.png or .gif).
• Draw everything on the same canvas size if you can. Then every file lines up automatically. If you crop files instead, write down their offsets — you'll need them as x and y coordinates in the config file.
• Split your artwork into the smallest consistent parts. Draw the body once and the hands separately, rather than drawing the whole body again for every hand pose. This keeps your module small and makes it easy to add options later.
• Organise files in folders such as body/hand/open.png. Short, self-explanatory file names in a clear folder structure are much easier to find — also for people who want to mod your module.

5. The Building Blocks

A config file is written in XML, a simple language for storing data. If you've ever seen HTML, it will look familiar: data is described with tags in pointy brackets, like <aspect>, and attributes like title="leotard". Every tag you open must be closed again, either with a closing tag (</aspect>) or by ending it with a slash (<file />).

An EMCCV module uses five tags, always nested in this order:

• module — the root element. It holds the information about your module: its ID, title, author and image size.
• set — a group of aspects, shown as a tab in the EMCCV. You need at least one.
• aspect — one part of the whole: body, hair, eyes, leotard, skirt… An aspect appears in the sidebar with a checkbox (to show or hide it) and a colour picker.
• style — the options for an aspect, e.g. a short, medium or long skirt. Only one style per group can be selected at a time. If an aspect has more than one style, the user gets a style menu for it.
• file — a graphic file. A file is drawn only if its style is selected and its aspect is visible.

Example: the file leotard/standard.png is only drawn when the style “standard” is selected and the aspect “leotard” is checked.

Two optional extras help you organise larger modules: <aspectgroup> groups aspects within a tab (shown with a divider line), and style groups split an aspect's styles into several independent groups — for example, “length” and “cut” for the same skirt. Wrap the styles of each group in a <stylegroup> element with its own id (unique, like every ID) and a short title such as “length”. Styles in an aspect that aren't in any style group form one more group, shown without a title.

6. Your First Module, Step by Step

Step 1: The module

Every config file starts with the same line, which simply declares the XML version. Then comes the module element. Everything else goes inside it.

<?xml version="1.0"?>
<module id="SailorXv3"
        title="Sailor X Generator"
        version="3"
        author="Diana"
        width="600"
        height="1016">
</module>

The width and height are the size of the final image. The version is usually a number — you could call it “LUNA” if you really wanted, but numbers are easier. ;)

Hooray, we have a module! It doesn't show anything yet, though. Let's add some content.

Step 2: A set and an aspect

For SailorXv3 I started with the body, because everything else is positioned relative to it. The body is an aspect — but an aspect always lives inside a set, otherwise the EMCCV wouldn't know which tab to put it in. So we add both, each with an id and a title:

<?xml version="1.0"?>
<module id="SailorXv3" title="Sailor X Generator">
  <set id="setBody" title="BODY">
    <aspect id="aBody" title="body">
    </aspect>
  </set>
</module>

To focus on what's new, the examples keep the module attributes short from here on — but you should always include all of them.

Loaded into the EMCCV, this gives us a tab called “BODY” with an aspect called “body”. We can check it and change its colour — but we won't see anything yet, because there are no graphic files.

Step 3: A style and a file

A file lives inside a style, which lives inside the aspect:

<?xml version="1.0"?>
<module id="SailorXv3" title="Sailor X Generator">
  <set id="setBody" title="BODY">
    <aspect id="aBody" title="body" visible="true">
      <style id="sBodyStandard" title="standard">
        <file src="body/standard.png" />
      </style>
    </aspect>
  </set>
</module>

W00t! A fully functional module! Now the body is drawn on the canvas, and changing the aspect's colour recolours it. Because we added visible="true", the body is shown straight away when the module loads — by default, aspects start hidden.

The file tag is the smallest building block. Nothing goes inside it, so it closes itself with a slash. Files don't need an ID; the only thing they must have is src, the location of the graphic inside the data folder.

Step 4: More styles

Let's say we have an open hand and a fist. That means two styles — each with its own files:

<aspect id="aBody" title="body" visible="true">
  <style id="sBodyHandOpen" title="open">
    <file src="body/standard.png" />
    <file src="body/hand/open.png" />
  </style>
  <style id="sBodyHandFist" title="fist">
    <file src="body/standard.png" />
    <file src="body/hand/fist.png" />
  </style>
</aspect>

WHOA! This is a whole different game. :) Both styles use the same body file, but different hand files. The first style is selected by default, and the user can switch between them in the style menu.

7. Choosing Good IDs

The id attribute uniquely identifies everything in your config file (except files). No two elements in a module may share the same ID, and no two modules may share the same module ID.

It quickly gets tedious to keep inventing unique IDs, so here's what helps:

• Use prefixes that tell you the type of element: set for sets, a for aspects, s for styles — e.g. setBody, aLeotard, sLeotardStandard.
• Keep them readable but short. When something goes wrong, the log names the ID of the element involved, and you'll want to recognise it immediately.
• Use letters and numbers only, without spaces.

8. Layers and Positions

Layers

Files are drawn from the lowest layer number to the highest, so higher layers end up on top. The default is 0 — typically the main part of your image, like the body.

• Negative numbers are allowed and great for backgrounds (e.g. layer="-100").
• Decimals let you squeeze something in between: layer="1.1" is drawn above layer 1 but below layer 2.
• Files on the same layer are drawn in the order they appear in the config file.

Positions and sizes

By default a file is drawn at the top left corner of the canvas (x="0" y="0") at its original size. Use x and y to move it, w and h to resize it, and relx/rely to shift it relative to an inherited position.

Inheritance saves time

Many attributes are inherited down the hierarchy: if a file doesn't define a layer, it uses its style's layer, which falls back to its <stylegroup>'s (if it has one), then the aspect's, then the set's. So instead of repeating layer="5" on twenty files, put it on their aspect once. The reference below shows which attributes are inherited.

9. Making Things Depend on Each Other

Parent conditions

The parent attribute makes an aspect, style or file depend on other elements. For example, high heels should only be available when shoes are visible:

<aspect id="aHeels" title="heels" parent="aShoes">

An aspect or style with an unmet parent condition can't be selected; a file with an unmet condition isn't drawn. Conditions can combine several IDs:

Example: gloves that follow the hand pose

Remember our body with an open hand and a fist? Now we want gloves — and of course the glove has to match the hand pose. There are two ways to do this, and both work.

Version 1: one glove style per hand pose. Each glove style has the matching hand style as its parent:

<aspect id="aGlove" title="glove">
  <style id="sGloveOpen" title="open" parent="sBodyHandOpen">
    <file src="clothes/gloves/standard_open.png" />
  </style>
  <style id="sGloveFist" title="fist" parent="sBodyHandFist">
    <file src="clothes/gloves/standard_fist.png" />
  </style>
</aspect>

This works, but the user has to pick the matching glove style themselves: switch the hand to a fist while the “open” glove is selected, and the glove disappears until they select the “fist” glove too. It also multiplies quickly: three glove designs for two hand poses already means six styles.

Version 2: parent conditions on the files (recommended). One style per glove design, with one file per hand pose:

<aspect id="aBody" title="body" visible="true">
  <style id="sBodyHandOpen" title="open">
    <file src="body/body.png" />
    <file src="body/hand/open.png" />
  </style>
  <style id="sBodyHandFist" title="fist">
    <file src="body/body.png" />
    <file src="body/hand/fist.png" />
  </style>
</aspect>

<aspect id="aGlove" title="glove">
  <style id="sGloveStandard" title="standard">
    <file src="clothes/gloves/standard_open.png" parent="sBodyHandOpen" />
    <file src="clothes/gloves/standard_fist.png" parent="sBodyHandFist" />
  </style>
</aspect>

Now the glove simply follows the hand: whichever pose is selected, the right file is drawn, and the user only chooses the glove's design. This version is more flexible and future-proof: a new glove design is just one more style, and a new hand pose is one more file in each glove style — nothing else needs to change.

Borrowing colour and opacity

colormaster="aHead" makes an element use the colour of another aspect. SailorXv3 uses this so the eyelids keep matching the skin, even when the eyes are coloured blue. Put it on the aspect, and the aspect won't get its own (useless) colour picker. opacitymaster works the same way for transparency — AFH uses one “shading” aspect to control all shading files.

Mirroring

Many things come in matching pairs or sets: shoulders, eyes, earrings — whatever your module needs. To let users edit them all at once, give the matching aspects the same mirror value, and give their matching styles the same mirror value, too. This example is from SailorXv3:

<aspect id="aBorderShoulderLeft" title="BORDER (shoulder, left)" mirror="BorderShoulder">
  <style id="sBorderShoulderThinLeft" title="thin" mirror="BorderShoulderThin">…</style>
  <style id="sBorderShoulderThickLeft" title="thick" mirror="BorderShoulderThick">…</style>
</aspect>
<aspect id="aBorderShoulderRight" title="BORDER (shoulder, right)" mirror="BorderShoulder">
  <style id="sBorderShoulderThinRight" title="thin" mirror="BorderShoulderThin">…</style>
  <style id="sBorderShoulderThickRight" title="thick" mirror="BorderShoulderThick">…</style>
</aspect>

When the user turns on the Mirror Link tool, showing, hiding or recolouring one shoulder border does the same to the other, and selecting “thick” on one selects it on the other as well. With the tool off, each can be edited separately.

10. Attribute Reference

“Inherited” means the value is taken from the parent element if you don't set it.

Module

Set, aspect, stylegroup, style and file

Reserved for the future

These attributes are part of the EMCCV plans. The current version ignores them, so you can already add them to your module and it will be ready when they arrive:

11. Testing Your Module

Load your module often while you work — small steps make mistakes easy to find. When something doesn't look right:

• Open the Debug Log (Window → Show Debug Log). It shows how the EMCCV reads your config file, including any errors and the ID of the element involved.
• Use Refresh (File → Refresh in the desktop version) to reload your graphics after editing them.
• Check the usual suspects: a typo in a src path, two elements with the same ID, or a tag that was opened but never closed.

12. Sharing Your Module

Created something you're proud of? I'd love to see it! Get in touch and tell me about your module. In the future, EMCCV.com will have a directory where you can publish your modules for others to discover — and until then, you'll find community creations on the Modules & Credits page.