Material Library

The Material Library creates resizable and recolorable pixel buttons, frames, and panels. A material does not scale one full image. It rebuilds the PNG from JSON slice rules, so its four corners retain their original pixel style.

Use a material#

1. Click Materials in the Pixel Editor toolbar.
2. Choose a built-in material or import a JSON definition.
3. After inserting it, edit X/Y, width, height, and the primary color in the Material Layer section on the right.
4. To paint directly on the layer, choose Rasterize Material Layer first. Rasterized layers no longer retain editable material parameters.

Material layers are saved inside the .kmstudio project together with their source PNG, so they do not depend on the original material folder.

Create a material visually#

You do not need to handwrite JSON. Open Materials, click New Material, then:

1. Choose a PNG source image.
2. Drag the four blue slice guides on the left to define the fixed left, top, right, and bottom edges. The center retains at least 1px.
3. Set a preview size in the middle and verify that corners stay intact while edges and the center repeat as intended.
4. Configure the region fill modes, minimum size, and content padding.
5. For outline, shadow, body, or highlight colors that should follow the primary color, enable the role and either sample the source image or choose its template color in the picker.
6. Saving automatically creates <material ID>.png and <material ID>.material.json in the user material directory, ready to insert into the Pixel Editor.

Material IDs may contain letters, numbers, underscores, and hyphens. Saving an existing ID updates that user material.

Material files#

An external material uses a PNG and JSON file in the same directory:

stone_button.png
stone_button.material.json

image must be a relative PNG path inside the JSON directory. The first release supports PNG source images only.

{
  "format": "kamenu-ui-material",
  "version": 1,
  "id": "stone_button",
  "name": "Stone Button",
  "image": "stone_button.png",
  "category": "buttons",
  "slice": { "left": 4, "top": 3, "right": 5, "bottom": 4 },
  "regions": { "top": "tileX", "bottom": "tileX", "left": "tileY", "right": "tileY", "center": "tile" },
  "minimumWidth": 16,
  "minimumHeight": 12,
  "defaultPrimaryColor": "#4C8BFFFF",
  "palette": [
    { "sourceColor": "#202020", "role": "outline", "transform": "darken", "amount": 0.78 },
    { "sourceColor": "#606060", "role": "shadow", "transform": "darken", "amount": 0.44 },
    { "sourceColor": "#A0A0A0", "role": "body", "transform": "primary" },
    { "sourceColor": "#E0E0E0", "role": "highlight", "transform": "lighten", "amount": 0.38 }
  ]
}

The four slice values can be different and are not fixed at 3px. Corners retain their size; top and bottom tile horizontally; left and right tile vertically; the center tiles in both directions. A final incomplete repetition is pixel-cropped, never blurred.

Color rules#

palette replaces only explicitly declared template RGB values and preserves the source pixel alpha channel.

• primary: uses the selected primary color.
• darken: mixes the primary color toward black.
• lighten: mixes the primary color toward white.
• fixed: uses fixedColor and ignores the primary color.

Do not declare the same template RGB value twice. Decorative pixels that must remain unchanged should use a color that is not declared by palette.

Region modes#

• fixed: draw once.
• tile: repeat on both axes.
• tileX: repeat horizontally.
• tileY: repeat vertically.
• fill: fill with the region's top-left pixel.
• stretch: nearest-neighbor stretching; use only when intentional.
• none: do not draw the region.