Documentation

Quick Start

New to EMCCV? Here's how to create your first character in under a minute:

1. Launch the app — open the web app in your browser.
2. Pick a character — select a module from the dashboard (currently featuring SailorXv3).
3. Customize — use the set tabs and sidebar to toggle features on and off and change their colors.
4. Get inspired — click and in the toolbar to generate random combinations.
5. Export — click or press Cmd/Ctrl+E to save a PNG of your design.

Core Concepts

Understanding these terms will help you get the most out of EMCCV. Everything in the app is built on a simple hierarchy:

Modules

A module is a self-contained character template. It defines the canvas size, the available visual elements, and how they relate to one another. Think of it as a complete art kit for a specific character type. Each module is loaded from an XML configuration file that describes its structure and points to the image assets.

Currently available: SailorXv3 (magical girl theme). More modules are in development.

Sets

Within a module, elements are organized into sets — the top-level grouping categories that appear as tabs above the canvas. For example, a character module might have sets named Body, Hair, Clothing, Accessories, and so on. Each set contains one or more aspects.

Aspects

An aspect represents a single customizable feature within a set — for instance, Hair Front, Left Eye, or Skirt. Each aspect has:

• Visibility — toggled with the checkbox in the sidebar. Controls whether this feature is shown on the canvas.
• Color — the tint applied to this feature's images. Click the color swatch in the sidebar to change it.
• Style groups & styles — visual variations of the feature (see below).

Some aspects have special properties:

• Always On — the aspect is always visible and its checkbox cannot be unchecked.
• Color Controlled — the aspect's color is controlled by another aspect (via a colormaster attribute). Its color swatch is hidden because the color changes automatically when the controlling aspect's color changes.
• Parent Conditions — some aspects (and styles) have prerequisites that must be met before they become available. For example, a Hair Bow aspect might require the Long Hair style to be active. When a parent condition is not met, the aspect appears disabled (grayed out) in the sidebar. See also Collapse View, which can hide these unavailable aspects entirely.

Style Groups & Styles

Each aspect can contain one or more style groups. A style group holds a set of mutually exclusive styles — visual variations of the same feature. For example, a Hair aspect might have two style groups: one for length (with styles like Short and Long) and another for texture (with styles like Wavy and Straight).

Click the icon next to an aspect in the sidebar to expand it and reveal its available styles. Selecting a different style within a group immediately replaces the currently active one on the canvas.

If an aspect has multiple style groups, each group is listed separately and each one can have its own selected style. This allows for complex combinations — e.g., a Shirt aspect could have one style group for the shirt design and another for the collar style.

Entities

An entity is a saved character design. It stores all of your customization choices — which aspects are visible, their colors, and which styles are selected — in an XML file. You can save an entity and load it later to continue editing, or share it with others who have the same module installed.

Entities are module-specific: loading an entity requires the module it was created with to be available.

The Interface

The EMCCV interface is composed of several areas that work together. Here's a tour from top to bottom:

Menu Bar

The very top of the app features a traditional menu bar with File, Edit, View, Window, and Help menus. This is where you'll find all available actions and settings, including those not exposed in the toolbar. See the Menu Reference for a complete breakdown.

On the right side of the menu bar, you'll see the EMCCV branding: five colored squares representing the app's identity. Click them to open the EMCCV.com homepage.

Toolbar

Below the menu bar sits the toolbar — a row of icon buttons for quick access to the most common actions. From left to right, the default toolbar includes:

• Open — open a module or entity file (Cmd/Ctrl+O)
• Save — save the current entity (Cmd/Ctrl+Shift+S)
• Export — export the canvas as a PNG image (Cmd/Ctrl+E)
• Undo (Cmd/Ctrl+Z) & Redo (Cmd/Ctrl+Y)
• Reset — reset the module to its default state (Cmd/Ctrl+Shift+R)
• Global Mode — extends the scope of link and randomization tools to all sets (default: on)
• Color Link — keeps aspects with matching colors in sync (default: on)
• Chain Link — manually link aspects into a chain group (default: off)
• Mirror Link — synchronizes mirrored aspect pairs like left/right eyes (default: on)
• Random Visibility (Cmd/Ctrl+Shift+V)
• Random Colors (Cmd/Ctrl+Shift+C)
• Shift Colors (Cmd/Ctrl+Shift+X)
• Zoom In (Cmd/Ctrl++) & Zoom Out (Cmd/Ctrl+−)
• Reset View — reset zoom and pan to default (Cmd/Ctrl+0)
• Collapse View — hide aspects whose parent conditions aren't met (default: on)
• Close — close the current module and return to the dashboard (Cmd/Ctrl+W)

The toolbar can be hidden via Window → Show Toolbar (Cmd/Ctrl+Shift+T). Its size is configurable in the View menu (Small / Normal / Large).

Set Tabs

Directly below the toolbar, you'll see the set tabs — one tab for each set in the current module. Click a tab to switch the sidebar to that set's aspects. You can also navigate between tabs with the ← and → arrow keys.

Set tabs remain visible even when the sidebar is hidden, so you always have access to navigation.

Sidebar

The sidebar on the left is your main editing panel. It shows all aspects for the currently selected set. For each aspect, you'll see:

• Checkbox — toggles aspect visibility. Grayed out if the aspect is always-on or if a parent condition is not met.
• Color swatch — a small colored square showing the aspect's current tint color. Click it to open the color picker. Hidden when a colormaster attribute is controlling the color from another aspect.
• Title — the aspect name. Dimmed when the aspect is unavailable (parent condition not met).
• Expand button — reveals the style groups and styles for this aspect.
• Link icon — appears only when Chain Link mode is active. Click to toggle this aspect into the chain group.

Aspects can be visually grouped by the module author. Groups are separated by subtle spacing in the sidebar.

The sidebar can be hidden via Window → Show Sidebar (Cmd/Ctrl+Shift+B).

Canvas

The large area to the right of the sidebar is the canvas — where your character is rendered in real time. What you see here is exactly what your exported image will look like. The canvas supports zooming and panning.

Footer

At the bottom of the app is a contextual footer bar. It shows helpful descriptions when you hover over toolbar buttons and other interactive elements. On the right side, it displays information about the currently loaded module (name, version, and author).

Debug Log Panel

Below the sidebar sits the debug log panel, hidden by default. When enabled via Window → Show Debug Log (Cmd/Ctrl+Shift+D), it shows real-time logging information about what the application is doing: parsing, rendering, color changes, parent condition evaluations, and more.

The log panel has its own set of controls:

• Settings — configure log level (All / Info / Warning / Error) and choose which element types and attributes to log.
• Full Width / Full Screen — expand the log panel for easier reading.
• Copy / Clear — copy log contents to clipboard or clear them.

This is primarily a debugging and troubleshooting tool. It can also be useful for understanding how the module's internal logic works.

Colors

Color is central to EMCCV. Every colorizable aspect has a tint color that is applied to its images on the canvas. This section covers how to pick, manage, and coordinate colors.

Color Picker

Click any color swatch in the sidebar to open the color picker. The picker provides several ways to choose a color:

• HSB Sliders — three sliders for Hue (0–360°), Saturation (0–100%), and Brightness (0–100%). Each slider has a live gradient preview, and the current color is shown in a large preview area at the top.
• Palette Swatches — pre-built color palettes appear as rows of clickable swatches. Click any swatch to apply that color instantly. The default palettes are Pure Colors, Precious Metals, and Skin Tones — plus any custom palettes you've added.
• Colors In Use — a special section that automatically shows all colors currently in use across the module. This makes it easy to reuse colors from other aspects without remembering the exact HSB values. You can also export these colors as a palette file using the button.

Each palette section has a button to hide it from the picker.

Changes are applied in real time as you adjust the sliders or click swatches. Click the close button in the picker header or press Esc to close it.

Palettes

A palette is a curated collection of colors stored in a simple text file. Colors are written as hex codes separated by semicolons (e.g., #FF5599;#33AA77;#0066CC;). The file can also include a title and description in the header lines. EMCCV ships with three default palettes:

• Pure Colors — a set of bright, saturated hues.
• Precious Metals — gold, silver, bronze, and copper tones.
• Skin Tones — a range of natural skin colors.

You can add your own custom palettes via File → Preferences → Palettes. Custom palettes are imported from .txt files and appear alongside the default palettes in the color picker. Each palette can be shown or hidden, reordered, and removed.

Eyedropper

In the color picker, click the eyedropper button to pick a color directly from the canvas. Your cursor changes to a crosshair — click anywhere on the canvas to sample that pixel's color and apply it to the current aspect.

Link Tools

Link tools let you keep colors synchronized across multiple aspects. There are three link tools, each with a different strategy. They can be used individually or combined for powerful workflows.

Color Link

Shortcut: Cmd/Ctrl+Shift+L · Default: On

When Color Link is active, aspects that share the same color are linked. Changing the color of one aspect will automatically update all other aspects (in the current set, or all sets if Global Mode is on) that had the same color.

This is useful for maintaining color harmony: if your character's hair and eyebrows share the same brown, changing one changes both. The linkage is based on matching the old color, so only aspects that actually matched before the change are updated.

Chain Link

Shortcut: Cmd/Ctrl+Shift+H · Default: Off

Chain Link is a manual linking tool. When activated, a small link icon appears next to each eligible aspect in the sidebar. Click the link icon on any aspects you want to connect into a chain group.

Once chained, those aspects will all update together when any one of them has its color changed. Unlike Color Link (which links by shared color), Chain Link lets you connect aspects that currently have different colors.

Chain selections persist even when Chain Link mode is turned off — so you can set up your chains once and toggle the mode on and off as needed. The link icons are only visible while the mode is active, but the underlying connections remain. Toggle the icon on an aspect to add or remove it from the chain group.

Mirror Link

Shortcut: Cmd/Ctrl+Shift+M · Default: On

Mirror Link synchronizes aspects that are defined as mirrors of each other in the module configuration — typically left/right pairs like Left Eye and Right Eye, or Left Earring and Right Earring.

When Mirror Link is active, changing the visibility, color, or style of one mirrored aspect automatically applies the same change to its counterpart. This ensures symmetrical designs stay symmetrical.

Turn Mirror Link off if you want to customize left and right sides independently.

Global Mode

Shortcut: Cmd/Ctrl+Shift+G · Default: On

Global Mode is a modifier that changes the scope of other tools. It doesn't do anything on its own — it extends the reach of the tools that respect it.

When Global Mode is ON, the following tools affect all sets in the module (not just the currently visible tab):

• Randomize Visibility — randomizes features across all sets.
• Randomize Colors — generates new colors across all sets.
• Shift Colors — shuffles colors across all sets.
• Color Link — links matching colors across all sets.
• Chain Link — propagates chain color changes across all sets.
• Mirror Link — syncs mirrors across all sets.

When Global Mode is OFF, the above tools only operate on the aspects within the currently selected set tab.

💡 Tip: Global Mode is perfect for sweeping changes. Turn it on, hit Randomize Colors, and your entire character gets a fresh color scheme in one click.

Randomization

EMCCV provides three randomization tools. Each one can operate on the current set or on all sets, depending on whether Global Mode is on. All three respect the link tools when active.

Randomize Visibility

Shortcut: Cmd/Ctrl+Shift+V

Randomly toggles the visibility of aspects and randomly selects styles within each visible aspect's style groups. Aspects that are always-on are not affected, and aspects with unmet parent conditions are skipped.

Each aspect has an internal probability value (set by the module author, defaulting to 75%) that controls how likely it is to appear during randomization. An aspect with 100% probability will always be shown; one with 30% will appear only about a third of the time.

Randomize Colors

Shortcut: Cmd/Ctrl+Shift+C

Assigns a new random color to every colorizable aspect (those whose color is not controlled by a colormaster).

The link tools affect how colors are distributed:

• Color Link on: aspects that currently share a color will all receive the same new random color.
• Chain Link on: aspects in the chain group all receive one shared random color.
• Mirror Link on: mirrored aspects receive the same random color.

Shift Colors

Shortcut: Cmd/Ctrl+Shift+X

Shuffles the existing colors among the visible, colorizable aspects. Unlike Randomize Colors, this doesn't generate new colors — it redistributes the ones already in use (the “Colors In Use” palette), producing a different look while keeping the same overall color scheme.

The link tools affect how the shuffle is grouped: linked aspects share one entry in the pool and move together.

Saving & Exporting

Save / Load Entities

To save your current character design:

• Save Entity As… (Cmd/Ctrl+Shift+S) — enter a name and download the entity as an XML file. In the web version, a dialog also offers the entity's thumbnail image for separate download.
• Save Entity Desktop (Cmd/Ctrl+S) — quick-save to the same file path used previously. This overwrites the file on disk without a dialog.

To load a previously saved entity:

• File → Open Entity (Cmd/Ctrl+O) — select an XML entity file from your device.
• File → Load recent Entity Desktop — pick from a list of recently loaded entities.

Entity files are module-specific. When loading an entity, EMCCV checks whether it matches the currently loaded module. If there is a mismatch, a warning is shown (this can be configured in Preferences → Startup).

Export Image

To export a PNG image of your character:

• Click in the toolbar, or press Cmd/Ctrl+E, or go to File → Export Image.

The exported image is a high-quality PNG with a transparent background at the module's native resolution — perfect for use in other projects.

Canvas Controls

You can zoom and pan the canvas to inspect details or get an overview:

• Zoom in / out — use the scroll wheel, pinch-to-zoom on trackpad, or click / in the toolbar (Cmd/Ctrl++ and Cmd/Ctrl+−). Zooming is centered on the mouse position.
• Pan — click and drag on the canvas to move it around.
• Reset View — click in the toolbar or press Cmd/Ctrl+0 to fit the canvas back to its default position and zoom level.

Preferences

Open Preferences via File → Preferences (Cmd/Ctrl+,). The dialog has four tabs:

Startup

Configure dashboard behavior and warning dialogs:

• Dashboard — set the thumbnail size (50–250px), choose whether to show info boxes on cards, group by module, and set the sort order (by date, title, or filename).
• Warnings — toggle individual warning dialogs: warn when loading legacy .txt entities, warn before global reset, and warn when loading an entity into a potentially mismatched module.

Logging Configuration

Fine-grained control over the debug log output. Also accessible from Help → Logging Configuration or the button in the log panel. Options include:

• Log Level — All, Info, Warning, or Error.
• Element Filters — choose which element types to log (sets, aspects, style groups, styles, files).
• Attribute Filters — choose which attributes to log (visibility, parent conditions, color, opacity, position, randomize).
• Special Options — Layer Order logging, Current Tab Only filter, Module Debug mode.

Palettes

Manage which palettes appear in the color picker:

• Built-in palettes — toggle the visibility of Pure Colors, Precious Metals, and Skin Tones.
• Custom palettes — import .txt palette files, give them a name and description, reorder them, toggle visibility, or remove them entirely.

Palette files use semicolons to separate hex color codes (e.g., #FF5599;#33AA77;#0066CC;). The file can include header lines for title and description.

Environment

General application settings:

• Recent History Length — how many recent modules and entities to remember (1–50).
• Directories Desktop — configure default directories for modules, entities, images, and palettes.

Dashboard

The dashboard is the landing screen when no module is loaded. It shows your recent entities as a grid of thumbnail cards, grouped by module. From here you can:

• Click a card to load that entity and jump straight into editing.
• Collapse / expand module groups by clicking the group header.
• Open a module or entity via File → Open (Cmd/Ctrl+O).

Dashboard display settings can be configured in Preferences → Startup: thumbnail size, sort order (by date, title, or filename), and whether to group by module.

View Options

Customize the appearance of the interface via the View and Window menus:

Toolbar Size (View menu)

Choose between Small, Normal, and Large toolbar icon sizes to suit your screen and preference.

Text Size (View menu)

Switch between Normal and Large text for the sidebar and other UI elements.

Collapse View (View menu)

When enabled, aspects whose parent conditions are not met (i.e., they are currently unavailable) are automatically hidden from the sidebar. This keeps the sidebar clean and focused on what's currently relevant. When disabled, all aspects are shown, but unavailable ones appear dimmed.

Compact View (View menu)

Toggles between a spacious sidebar layout and a tighter, more condensed view with reduced spacing between elements.

Show / Hide Panels (Window menu)

• Show Toolbar (Cmd/Ctrl+Shift+T) — toggle toolbar visibility.
• Show Sidebar (Cmd/Ctrl+Shift+B) — toggle sidebar visibility. Set tabs remain visible.
• Show Debug Log (Cmd/Ctrl+Shift+D) — toggle the log panel below the sidebar.

Keyboard Shortcuts

All shortcuts use Cmd on macOS and Ctrl on Windows/Linux.

Web vs Desktop

EMCCV is available as a free web app and as a desktop application (coming soon for macOS and Windows). The core creative tools are identical on both platforms, but there are some differences:

In the web version, desktop-only features are either hidden entirely or shown as disabled with a “Desktop Only” label in the menus.

Menu Reference

A complete listing of every menu item, organized by menu. Items marked with Desktop are only available in the desktop version.

File

Edit

View

Window

Help