https://docs.wallpaperengine.io

All project scripts are using JSON as a data format, so it's beneficial to have a good grasp of JSON, but it's not required for basic changes. Using an editor like Sublime or Notepad++ is recommended to edit JSON files. Preliminary knowledge about game development or rendering will be required as well for certain parts!

All wallpapers share a common file called project.json in the root directory (use Edit -> Open in Explorer in the wallpaper editor to quickly go there). This file contains common information like the wallpaper title, the scheme color, the type of wallpaper and the main wallpaper file. Scene wallpapers usually name the main file scene.json which you can find right next your project.json.




This file describes your 2D or 3D scene. The most important JSON keys are general, camera and objects. general will contain various general settings, like clear color, ambient color or size of the 2D orthographic projection used. You can change the ideal aspect ratio of changing the size of the orthographic projection, for example. camera contains the position of the camera if it is static or a link to the camera path script, which you can find in the scripts/ directory. objects is an array of items used in your scene, this is what the scene graph panel in the editor contains. Each object has a transformation, stored as angles, origin and scale keys, and a link to the object file, which also defines the type of object. Valid object types are model, image, particle, sprite and light.




3D models will be compiled from .obj or .fbx files into the custom .mdl format. Only the .mdl file is required to use a model in Wallpaper Engine. An optional JSON file can be used to configure how your model is compiled, it needs to have the same filename as your model file, except for the JSON extension (so if you have a truck.fbx, your config file would be truck.json). The following options are possible to control how your model is compiled:

• normals (BOOL): Add "normals": true to your config file to compile normals into your model.
  
• tangentspace (BOOL): Add "tangentspace": true to your config file to add tangent space vectors to your model file (bitangent and tangent vectors).
  
• seconduvchannel (BOOL): Add "seconduvchannel": true to your config file to enable a second UV channel (typically used for lightmaps). This option is only valid for .fbx files. The second set of UVs must be named "lightmapSet". This allows you to use attribute vec4 a_TexCoordVec4 in the shader instead of attribute vec2 a_TexCoord.
  
• materialdirectory (STRING): Add "materialdirectory": "MYPATH" to your config to use a specific material base directory. This allows you to share materials between models more easily.
  
• skins (ARRAY): An array of objects with keys/strings that define multiple materials for a model. Use "skin" in scene.json to select a skin by index.

Material JSON files describe how each material (of your model) is rendered. They link textures and shaders together and control other global rendering options, like alpha blending. All material properties are wrapped in an array called passes. The following properties can be set for each pass of a material:

• blending (STRING): Set "blending" to "translucent" or "additive" to enable translucent or additive blending respectively.
  
• depthtest (STRING): Set "depthtest" to "disabled" to disable depth testing.
  
• depthwrite (STRING): Set "depthwrite" to "disabled" to disable depth writing.
  
• cullmode (STRING): Set "cullmode" to "nocull" to disable culling.
  
• shader (STRING): Set "shader" to any name of a shader that exists in your shader/ directory. A .frag and .vert will be required with this name.
  
• textures (ARRAY of STRINGS): Set "textures" to an array of texture names. The textures will be bound to g_Texture0, g_Texture1, g_TextureX respectively. Special texture names will allow you to access rendertargets: "_rt_FullFrameBuffer", "_rt_Reflection".
  
• constantshadervalues (OBJECT): Defines constant values used by uniforms from the shader.
  
• combos (OBJECT): Defines combo constants (preprocessor) set when compiling the shader. Use this to enable/disables features and build an 'uber shader'.
  
• usershadervalues (OBJECT): Links uniform values to user values, which show up in the wallpaper settings dialog for a user to change.

Textures are compiled from .tga or .png files into the custom .tex format. It is also possible to define a compiler config JSON file to control how your texture is compiled. To do so, use the filename of your texture with the extension .tex.json (so if you have a tire.png, you need to create a tire.tex.json). The following options are available for textures:

• format (STRING): Set "format" to one of these values: "rgba8888", "rgba8888n", "dxt5", "dxt5+", "dxt5n", "dxt5n+" (or dxt3, dxt1 respectively). The 'n' suffix will enable normal map swizzling for compressed normal maps (use the shader utility DecompressNormal to decompress). The '+' suffix will enable a higher quality compression method.
  
• nointerpolation (BOOL): Set "nointerpolation": true to disable bilinear interpolation.
  
• clampuvs (BOOL): Set "clampuvs": true to enable UV clamping.
  
• nomip (BOOL): Set "nomip": true to disable mip map generation and mip mapping for this texture.
  
• nonpoweroftwo (BOOL): Set "nonpoweroftwo": true to allow non power of two dimensions. This will pad the texture with black to fill missing pixels and round up to the next power of two.
  
• croptoaspectratio (FLOAT): Set "croptoaspectratio": 1.0 To crop the texture to a specific aspect ratio, like 1.0 in this example.

2D scenes make it possible to import images directly into the world without requiring a model file. They render the image on a quad that can be configured through an image model script. The following options are possible for image models:

• material (STRING): Set "material": "materials/MYMATERIAL.json" to specify the material for the image model.
  
• height (INT): Set "height": 1024 to specify the height in pixels.
  
• width (INT): Set "width": 1024 to specify the width in pixels.
  
• fullscreen (BOOL): Set "fullscreen": true to create a signed unit quad that you can render as a fullscreen pass. Skip model/view transforms in the shader with e.g. gl_Position = vec4(a_Position, 1.0);

Shaders are written in GLSL version 120 with a few minor exceptions. They are then translated into HLSL dynamically and compiled as shader model 3.0. The attributes or uniforms you can use are either globally predefined or you can expose them into the editor (or even the user, for e.g. tintable colors). Refer to the assets/shaders/readme.txt file in the application to get an up to date list of available uniforms and conventions.

This separate tutorial specifically for shaders will get you started on writing custom shaders for Wallpaper Engine:

http://sp.zhabite.com/sharedfiles/filedetails/?id=770803636

The editor allows you to make changes to some of your project files and will automatically reload them when you save the changes. Currently only material and shader files will be reloaded. For different changes, you will have to re-open the project which you can do through File -> Open recent quickly.