Documentation · 中文 · User guide · Canvas editing · Implementation notes (Chinese) · Layout manifest
Layout lets you arrange parts in the project first and generate the rig afterwards. After generating you can keep adding images and changing tags, then generate again; the edits you have already made are kept.
- From an empty canvas: on the Start page pick Layout project (File → New → New Layout project… opens it too), choose a common size or type the width and height in the properties panel, and click Create Layout Project or double-click a size. The new project has no rig yet and switches to the Layout workspace.
- From a PSD: import the PSD as usual. The project generates the rig straight away, and every PSD layer also appears in the Materials panel, linked to its layer on the canvas.
- From a Layout manifest: a Layout manifest written by an external tool (such as AI part splitting) - a JSON, or a zip holding it at its root - opens the way a PSD does, or by dropping it on the window. The layers are arranged as the manifest says: position, stacking order, groups, tags and variants are set, and small parts keep more pixels than the canvas would give them; the project has no rig yet and switches to the Layout workspace.
- Any workspace can open the Materials panel from the Windows menu.
The Layout workspace: the Materials panel on the left, the edit canvas (Object mode) in the middle, the hierarchy tree and the layer table on the right.
- Import: click Import to choose files, Import folder… to choose a whole folder, or drop files and folders on the panel (dropping on a folder or on one level of the path bar imports there). A folder is imported with its nesting intact: every level of subfolder becomes a material folder, and files are ordered by the numbers in their names (arm2 before arm10); hidden files and folders (such as .git) and unsupported files are skipped. Supported are PNG, BMP, TIFF, WebP (lossy too), JPEG, PSD, the ArtMesh images in a CMO3, and SVG. A PSD becomes a folder, its layer groups become subfolders, and each layer remembers its place in the PSD.
- Browsing: on the left is a compact material tree (folders and the images in them, all expanded by default; the tree button on the toolbar collapses it; images in the tree can likewise be dragged onto the canvas or double-clicked to open), and on the right the contents of the current folder: folders first, then materials, as a grid or a list. The divider between the two columns can be dragged to change their widths; the slider at the bottom right sets the grid's thumbnail size (materials with a lot of transparent margin show only the part with content). Double-click a folder to enter it; go back with the tree, the ↑ in the path bar above, or any of its levels; search looks through every folder. The number at an item's top right is how many layers use it.
- Sources: a folder imported from a PSD or a CMO3 shows as a file icon with a "PSD" / "CMO3" band, a page stacked behind it, and its item count and an arrow at the bottom right, meaning it opens with a double-click; hover to see the source file name.
- Organizing: drag a material or folder onto another folder (in the grid, the tree or on one level of the path bar) to move it in. The context menu opens where you click, like the canvas context menu; the menus of the tree's top level and of folders can create a folder and import files or folders there. Right-click blank space in the grid or list to create or import into the current folder, or switch the grid, list and folder tree views; blank space in the tree creates or imports at the library root. Entry menus can rename, edit tags, move up a folder and delete. Separate tags with commas; leave them empty to clear them. Folder tags support search and are inherited by materials when placed. Materials used by layers or reference images cannot be deleted, nor can folders containing them; the menu shows the usage count. Delete uses the warning color, and editing actions are disabled while the workspace is busy.
- Default reference layers: right-click a material or folder and toggle Place as a reference layer by default to change the default when dragging its materials onto the canvas. A folder applies this to materials in all its subfolders. Place on canvas explicitly creates model layers; Add as reference > In the layer stack explicitly creates reference layers.
- Materials are the layers' one source: every layer shows a material, registered on its own when you import a PSD, a CMO3 or images, split a layer or paint past a mesh. A material only one layer uses follows that layer's edits; when layers share a material, painting any of them paints the material and the others follow; to change one alone, right-click Make material its own. In older projects, layers without a material are offered Add to library at the top of the panel.
- SVG: right-click Texture resolution… and enter, say,
512x256. The resolution decides the pixels that go into the texture atlas; the size on the canvas does not change, and layers already placed update with it. - Export PSD: right-click a folder and choose Export folder as PSD….
Double-clicking a material (or right-click Open in material window) opens it in a separate window that can be resized freely and moved to another screen. While the window is open, clicking another material in the panel switches the window to it.
- Viewing: the wheel zooms, the middle button or Space + drag pans; the bottom right switches between checkerboard / white / black background, Fit (F) and 1:1 (Home). At 2× and above it shows pixels as they are.
- Painting: the window is the canvas's paint mode - the toolbar on the left, the options bar at the bottom, the paint session bar at the top (undo, redo, discard, apply), the context menu, the brush tip and colour-picker display and every shortcut are the same as in paint mode, only it paints the material's own pixels. Colours and settings such as each tool's size come over from the current canvas and go back when the window closes.
- Applying: as in paint mode, strokes stay in the session first; Apply (Enter) writes them into the material as one history step and Discard drops them; switching to another material or closing the window applies them automatically. While painting you can go on editing other things in the main window.
- Adjusting: the Adjust menu at the top left flips horizontally or vertically and adjusts hue, saturation, lightness and contrast; dragging a slider previews first, and Apply writes it. With unapplied strokes, apply or discard them first.
Every layer that places this material updates with it, keeping its position and size on the canvas. An SVG material becomes a bitmap at its current resolution once painted or adjusted.
A layer placed from a material (and a layer from an imported PSD) is linked to it: the layer shows the material's pixels, and the material is their only source.
- Painting such a layer in paint mode paints the material itself, and every layer using the material changes with it; the session bar says Painting material "…" · shown by N layer(s). The whole canvas can be painted: on apply, what falls on the layer's mesh is written into the material, and what falls outside the mesh is split off into a new layer placed right above it, which also goes next to the original material as a new material.
- In the layer table a linked layer has a chain mark after its name; hover to see the material name and how many layers share it. Click it to Open in material window or Unlink from material.
- After unlinking, the layer's pixels are its own, and painting it no longer affects the material or other layers. Other edits that make a layer's pixels differ from its material (such as splitting, or replacing it with another image) unlink it automatically too.
- Replace selected layer's image with another material links the layer to that material instead.
Materials are saved with the project, and every change can be undone.
- Drag a material or a whole folder onto the canvas to place it where it drops; right-click Place on canvas does it too. Materials in a folder keep their relative positions, and subfolders become source groups.
- Dropping files and materials: files dragged from your computer and materials dragged from the Materials panel share one set of targets; where you let go decides what happens, and the label by the pointer says so first. On the Materials panel files import as materials (on a folder, into it); images dropped on the hierarchy go under a deformer, or in front of or behind a mesh by its upper or lower half; over an edit canvas big options appear at its bottom - the three places for a reference (background, layer stack, foreground, each saying whether it is in the model), replacing the selected layer's image, and only adding to the material library (files only) - and letting go anywhere else on the canvas places a layer there. Projects, PSDs, CMO3s and layout manifests dropped anywhere else open. A place that takes nothing does not drop and shows no error.
- Materials from a PSD go back to their place in the PSD by default: the PSD's canvas as a whole sits in the middle of the project canvas, scaled down proportionally when it is larger; when the two are the same size, it is the original place. Other materials are placed in the middle of the canvas at "1 material pixel = 1 canvas unit", scaled down automatically when they would extend past the canvas.
- Canvas units are the model's coordinates: exported to Cubism they are the pixels of the model canvas, and they decide the model's size and proportions, not its sharpness. Sharpness comes from the material's own pixels - placing and scaling do not resample, so the smaller a layer is placed the denser its texture; on export the textures must also fit the atlas budget (the page size and page count in the Texture workspace), and when they do not fit the tiles shrink together.
- In Object mode the transform box moves, scales and mirrors layers. Pixels are not resampled: scale a 600×600 eye down to a 64×64 area of the canvas and the atlas still keeps it at 57CA 600×600 density (within the atlas budget).
- Stacking order: newly placed layers go on top, and placing a whole folder keeps the folder's original stacking order. With layers selected, use Bring Forward and Send Backward on the layer table's toolbar, or press Ctrl+] / Ctrl+[ on the canvas to move them forward or backward one step, and Ctrl+Shift+] / Ctrl+Shift+[ to bring them to the front or send them to the back. The layer table lists layers back to front, the lower the further forward, matching Cubism's draw order. Any layer not generated yet can be reordered; after generating, the order of generated layers is adjusted with draw order, while layers placed since can still be reordered until the next generation, and until then they show in front.
- References: pictures to compare against, such as the original art, a character sheet or a sketch, are a kind of member of the hierarchy (with the reference icon), as many as you like. Each shows in one of three places, and the place decides whether it is in the model: Background (not in the model; under the whole model, in the editor only), In the layer stack (in the model: a four-corner rectangular ArtMesh, created without tracing pixels or generating a full mesh, among the layers by drawing order, which can hang under a deformer and deform with it; exports treat it as a guide-image part, written only with Export guide image parts checked) or Foreground (not in the model; over the whole model, in the editor only). A reference in the layer stack is an editable rectangular ArtMesh immediately, before semantic generation too. Add one by dragging a picture or a material onto an edit canvas and choosing a place among the big options at its bottom, with the reference button on the hierarchy toolbar or in the canvas display bar (it goes to the foreground), or with a material's Add as reference. Click a background or foreground reference in the hierarchy and its handles appear on the edit canvas: drag inside to move it, a corner to scale it about its centre, the knob above to turn it, one history step when you let go; one in the layer stack takes the transform box like any ArtMesh. Right-click a reference: Shows as moves it between the three places (each marked with whether it is in the model; material, place, visibility and pin carry over), and it can be shown or hidden, faded and locked (background, foreground), given back to the model (layer stack) or removed. Alt+R shows or hides the background and foreground references on the current canvas.
- Making a layer a reference: a layer the generator has not read (any layer before the first generation, a layer placed since) or an imported image becomes a reference in the layer stack with Use as Reference on the layer table toolbar or Ctrl+Alt+R; the canvas context menu has a Use as Reference switch too. A reference layer shows a reference icon after its name; click it to make it a model layer again - one already in the model keeps its mesh as an ordinary layer. Layers a layout manifest marks
referenceopen as references in the layer stack. Generated layers cannot become references. - Pin to keyform: references of different angles (front, side, looking up…) can share one place and each show only at its keyforms, one reference at several if you like, in any of the three places. Right-click a reference: Pin to Keyform at the bottom of the menu lists the parameters the model has keyforms on in the parameter panel's shapes - a track with keyform dots for a single parameter, a 2D pad for a pair. Click a keyform dot to put a point there (filled), click it again to take it away; the reference shows at any of its points (every parameter of the point within 0.5% of its range) and hides at other poses. The grey marker is the current pose. Unpin clears every point. The canvas context menu's submenu of that name is the same panel. Pins only decide when the editor shows a reference; they are not exported.
- Replacing an image: select the layer first, then right-click a material and choose Replace selected layer's image. The layer's position and size on the canvas stay; only its pixels and atlas tile change. Replacing from the context menu in the atlas view works the same way.
Every layer in the layer table has a Tags cell; click it to edit:
- Part and side words tell the generator what the layer is: for example "hair + front" is front hair, "eye + pupil + left" is the left pupil, "mouth + open" is an open mouth. Parts and sides can be picked directly below the menu.
- The input box takes words from the vocabulary, and also common layer names (such as "前发" or "eye-l"), which are converted to the matching words; any other text becomes a tag of your own, for organizing and search only, with no effect on generation.
- Role words say what a layer is within its part:
highlight,pupil,lower(lower lash),lid(double-eyelid line),shadow,blush,side(side lock),ahoge,ponytail,braid,animal(animal ears),ribbon,pendant(pendants, tassels),rigid(buttons, badges and other hard accessories),sleeve,skirt, and for a mouth drawn in layersupperlip,lowerlip(a lip with the skin about it),upperline,lowerline(a lip's edge line). Generation guesses them from the layer name, its folder and where it sits among the layers, and shows them in the tags; correct a wrong one by retyping it, and once you remove a guessed role it is no longer guessed. Roles only affect the modules under Rig modules, never the original generation. - Toggle and switch variants are not tags; they are set in the Variant column next to them.
- Tags added to a material or a material folder are carried by the layers placed from it.
The generate bar at the top right of the edit canvas shows what is still waiting:
- Not generated: a new Layout project. Every layer has an editable mesh immediately. Meshes, deformers, parameters and hierarchy can be edited and exported, including in an empty workspace. Click Generate to fit automatic bindings from the tags.
- N waiting: layers placed after generating, and layers whose tags or classification changed. Newly placed layers immediately support ordinary editing and export; the next generation adds automatic bindings. A changed classification does not affect the rig until the next generation (the layer table outlines it in the accent colour).
- Clicking Regenerate merges these into the rig. The keyforms, deformers, physics, swing, bones and Glue you made are kept; whatever cannot carry over cleanly is listed in the quality check.
- A layer whose image was replaced gets a new mesh from its new pixels by default; to keep its old mesh, choose Generate, keeping replaced images' meshes in the generate button's drop-down.
Generation keeps existing mesh topology and fits bindings and parameters from tags. Explicit geometry refresh retraces replaced artwork.
Agents follow the same flow with the same operations: project_create, project_import_layout, material_import, layer_place, layer_tag, layer_reorder, rig_generate and so on; see the materials and Layout section of MCP_AUTHORING.md.