project.json Structure

project.json is the manifest file in the root of every wallpaper package. It describes the wallpaper’s type, entry file, preview image, metadata, and customizable properties. Mirage reads it to identify and render the wallpaper.

Top-Level Fields

Field	Type	Description
type	string	Wallpaper type: scene, web, video, application, etc.
file	string	Entry file: scene.json / scene.pkg for scenes, the HTML for web, the video file name for video
preview	string	Preview image file name (such as preview.jpg / preview.gif)
title	string	Wallpaper title
description	string?	Wallpaper description
author	string?	Author (many wallpapers omit this field)
tags	string[]?	Tags such as Anime or Nature
contentrating	string?	Content rating: Everyone, Questionable, Mature
approved	bool?	Whether it is “widely acclaimed”
visibility	string?	Visibility
version	int?	Version number
workshopid	int or string?	Steam Workshop item ID
workshopurl	string?	Workshop link
general	object?	General configuration, including the user properties
dependency	int or string?	The ID of the base wallpaper a preset depends on (preset-only)
preset	object?	The property values of a preset (preset-only)

Note

The three levels of contentrating — Everyone / Questionable / Mature — correspond to “Everyone” / “Mild nudity” / “Mature” in the filter panel. workshopid may be a number or a string in different wallpapers, and Mirage can parse both.

Inferring the Author

Many project.json files have no author field. In that case, Mirage tries to infer the author name from brackets like [name] or 【name】 in the title, or from text such as 作者：X, by X, or author: X in the description.

User Properties: general.properties

general.properties describes the adjustable options a wallpaper exposes to users. Mirage builds sidebar controls from it, and your changes are saved as propertyOverrides. Each property roughly contains:

Field	Description
type	Property type (see the table below)
value	Current value (boolean, number, or string)
text	Display label (may be a ui_ localization key)
order / index	Sort order
options	Combo box options (label + value + optional condition)
min / max / step / fraction	Slider range and precision
condition	Display condition
mode	Additional mode

The supported property types (type) include:

bool        boolean toggle
slider      numeric slider
color       color
combo       drop-down combo box (used with options)
textinput   text input
text        plain-text description
group       group
file        file
directory   directory
scenetexture scene texture
usershortcut shortcut

Property labels may be localization keys with a ui_ prefix. Mirage resolves them using Wallpaper Engine’s official ui_* glossary matched to the current language; when a key cannot be resolved, it falls back to a humanized version of the key name. The wallpaper’s own metadata, such as its title and description, is not translated.

Minimal Example

A wallpaper package generated by video conversion writes a minimal project.json:

{
  "type": "video",
  "file": "我的视频.mp4",
  "preview": "preview.jpg",
  "title": "我的视频"
}

A scene wallpaper with user properties might look like this:

{
  "type": "scene",
  "file": "scene.json",
  "preview": "preview.jpg",
  "title": "Aurora",
  "tags": ["Abstract", "Nature"],
  "contentrating": "Everyone",
  "general": {
    "properties": {
      "brightness": {
        "type": "slider",
        "text": "ui_browse_properties_brightness",
        "value": 1.0,
        "min": 0.0,
        "max": 2.0,
        "step": 0.01,
        "order": 0
      },
      "showtext": {
        "type": "bool",
        "text": "Show text",
        "value": true,
        "order": 1
      }
    }
  }
}

For how to adjust these properties in the interface, see Playback Controls and Custom Properties.