user manual

table of contents

1. System requirements

  • Windows 7 (64-bit version) or later. Mac OS or Linux are not supported.
  • Installed X-Plane 11.21 (, 11.25 (, 11.26 (, and later, if tool will support it.
  • 300+ MBytes on hard drive.
  • Internet connection. (Please make sure your firewall and antivirus software are not blocking X-Plane and xVision internet access.)
All shaders adjustments and tweaks are unavailable for unsupported X-Plane versions.

2. How to install

xVision is a standalone portable application and doesn't require specific installation procedure. Just unzip the distribution archive into a separate directory which does not require administrative privilegies.

IMPORTANT! Please not start tool directly from archive. You should extract files first!

The distribution package is a zip archive containing the following files:

  • XVision.exe - application.
  • EULA.txt - End User License Agreement text.
  • Classic.xvs - ready "Classic" solution for using without FlyWithLua plugin installed or for using with FlyWithLua Core edition.
  • Classic_for_Lua.xvs - ready "Classic" solution for using with FlyWithLua Complete edition or FlyWithLua NG (Next Generation) Edition plugin.
  • Impressive.xvs - ready "Impressive" solution for using without FlyWithLua plugin installed or for using with FlyWithLua Core edition.
  • Impressive_for_Lua.xvs - ready "Impressive" solution for using with FlyWithLua Complete edition or FlyWithLua NG (Next Generation) Edition plugin.
If your X-Plane 11 setup doesn't include FlyWithLua plugin, or yor are using FlyWithLua Core edition, please use "Classic.xvs" or "Impressive.xvs" solutions. Otherwise - "Classic_for_Lua.xvs" or "Impressive_for_Lua.xvs".

Before starting the tool please make sure that:

  • you have all original X-Plane 11 shaders in sim. Tweaked or modified shaders can't be used by xVision and will be ignored (warnings will be displayed in the program log). In this case just put the original version of shader in sim and tool will catch them at next start.
  • Your firewall and antivirus software are not blocking xVision internet access.

3. Initial sim resources backup

The first time you run the tool, it will ask you the main X-Plane installation directory, automatically detect target X-Plane version, find the appropriate resources, shaders, plugins and shaders cache directory and create an initial backup of main visual resources and shaders. This backup folder is created in main xVision directory and named "BACKUP".

What resources will be backed up:

  • all files from \X-Plane 11\Resources\bitmaps\skycolors\ directory will be copied to \xVision\BACKUP\Resources\bitmaps\skycolors\
  • all files from \X-Plane 11\Resources\bitmaps\world\ - to \xVision\BACKUP\Resources\bitmaps\world\
  • all original shaders from \X-Plane 11\Resources\shaders\ - to \xVision\BACKUP\Resources\shaders\

  • If you have FlyWithLua plugin installed:

  • all files from \X-Plane 11\Resources\plugins\FlyWithLua\Scripts\ - to \xVision\BACKUP\Resources\plugins\FlyWithLua\Scripts\
  • all files from \X-Plane 11\Resources\plugins\FlyWithLua\Scripts (disabled)\ - to \xVision\BACKUP\Resources\plugins\FlyWithLua\Scripts (disabled)\

The results of initial backup procedure will be displayed in a special window:

The results of initial backup procedure for shaders will be displayed in a program log:

Please do not delete or modify contents of BACKUP directory in your xVision installation! Or you will loose ability to restore original sim files!

4. Uninstalling

Since the xVision tool makes changes to visual resources and shaders of X-Plane it's important to restore them to original state before tool uninstall.

1. Use "Restore from backup..." menu command. Choose switches according to your need (all switches have the appropriate hints) and press "Do restore" button.

2. Delete xVision directory.

Keep in mind that xVision will restore the selected resources to the state in which they were first started. Resources manually installed later can be lost.

Before restoring resources and shaders from backup you should close X-Plane.

5. Upgrading notes

When you upgrade or downgrade version of your X-Plane, the tool should detect this and ask for your permission to delete outdated shaders files from the backup. If you select YES, outdated shader backups will be deleted and recreated from the new (upgraded) X-Plane version. But PLEASE MAKE SURE THAT YOU HAVE THE ORIGINAL SHADERS IN SIM!

Please note that the list of available tweaks/parameters may vary for different versions of the X-Plane. xVision has server-based logic for most of the tweaks and adjustments: all required settings for the current version of the simulator should be made by the tool automatically (intenet connection required).

In some cases, you may need to upgrade the tool itself (install package). When a new version released, compatibility issues and upgrade procedure are described on the Release history page of the site.

6. What are solutions?

If you have ever developed your X-Plane visuals, you are well aware that good results can be achieved by using a)good textures b)FlyWithLua plugin (a real masterpiece in the X-Plane world!). xVision offers you a fast and convenient way to control these resources without manually editing/copying files or any other confusing rubbish.

And in addition, the tool allows you to make adjustments to X-Plane shaders. (Shaders are programs running on GPU which tell a computer how to draw something in a specific and unique way.) xVision modifies X-Plane shaders which are used by sim to render scene. These modifications become active only at next start of sim, so changes can't be visible "on-the-fly").

Thus, each xVision solution consists of three interrelated parts that affect the visual component of virtual flights: textures, Lua scripts and shader tweaks.

All three components could be understood as a coherent whole (package). You can download a solution from the/a file, save, rename, make your own packages and share your work with community.

Each solution is a single file, not a bunch of different files that should be installed in different directories with different conditions.

xVision tool distribution package contains a couple of ready-made solutions. So you may start using it very easily: open solution (file with *.xvs extension), and apply it. Just two clicks :)

You don't need start xVision tool every time you start virtual flight. After applying solution the tool makes persistent modifications in shader files and resources which are used by X-Plane later. But keep in mind that every time you need to use new solution, you need to close sim, apply solution with the tool and then start X-Plane.

7. xVision user interface. Working with solutions.

All basic commands are grouped in the main menu on the left side of the tool window. There are three main interface sections: "INFO", "SHADERS", "RESOURCES & SCRIPTS" which can be accessed using the corresponding buttons in the title bar of the main window.

The program log, which contains text messages, is located at the bottom of "INFO" section. This section also contains a comment section and three illustrations/screenshots. Put your notes on the solution here and download the screenshots to illustrate this.

Command "Check solution" allows to validate tweaks parameter values and resources installation paths (see below).

Command "Restore from backup" allows you to restore resources and shaders to the state they were at first tool start. Please see chapter 4. Uninstalling for details.

"SHADERS" a section allows you to manage all shaders, post-processing tweaks and custom patches. Activation of each tweak is performed by its checkbox in the left tweaks listbox. If checkbox is not checked, the tweak is not applied.

All tweaks and tweak parameters have a detailed description and many of tweaks are illustrated. Use "Images" button to get tweak illustration online (internet connection required).

Tweak parameters which are in most cases are real numbers, can be edited manually or by using mouse wheel or Ctrl+mouse wheel (increasing/decreasing values). Use "Reset parameters" button to set all tweak parameters to default values.

Post-processing tweaks are containers that group different post-process effects. If you want to add these post-processing effects to sim, activate the post-process tweak itself and check desired effects in its list. The order of effects activation could be important: you can set the order by using Up, Down buttons. Each effect is documented and has its own parameters that can be restored to default values.

In addition to the existing xVision built-in tweaks you can also create your own tweaks (custom patches). Use this feature if you have some manual corrections that need to be applied to the shader files. Add a new patch to the list, give it a name, select the required shader file and specify the code block to be replaced by your code. These edits will be applied immediately after built-in tweaks in order specified in the list.

Untick the checkbox to deactivate custom tweak. Use [Find] button to check the presence of block to be replaced in a selected shader file.

IMPORTANT! There is no error detection provided! Use custom patches on your own risk! Wrong syntax or errors in your code can result in X-Plane malfunction (you will get shaders error at sim start).

Section "RESOURCES & SCRIPTS" allows you to manage scripts and resources that will be installed to X-Plane when solution is applied.

The list contains four columns:
- activation checkbox,
- resource name,
- installation path and comment.
Deactivated positions exclude from solution applying.
Name is an arbitrary name used to identify resource.
Install path contains the directory and file name (relative to main X-Plane directory) where resource will be installed.
For example: if resource path is "\Resources\plugins\FlyWithLua\Scripts\xVnatural.lua" and your sim is imstalled to "D:\X-Plane", file xVnatural.lua will be installed to "D:\X-Plane\Resources\plugins\FlyWithLua\Scripts\xVnatural.lua".

Toolbar at the top of section includes commands to
- add multiple files by directories browsing;
- download resource to selected position from file;
- upload resource from selected position in solution to file;
- cut/copy/paste/delete resources;
- view resource in solution (if they are texts/lua scripts or pictures);

You can select multiple positions in resource list by using Shift+arrows keys or Ctrl + mouse click.

"Check resources" command button allows to validate resources list. xVision can detect duplicates error (when different resources installed to the same file) and cases when resources will be installed to the directories that not backed up by tool.

In such cases you'll get warnings in log like this:

Resources validation results:
	ERROR: resource [xVnatural - summary script] has the same install path
	WARNING: resource/script [lights.txt] will be installed in a directory that is not backed up by the xVision
WARNING: Resources have some problems. Please see the log

Resources selected in list can be installed to sim separately from the whole solution. (Use "Install selected resources" button.)

"Activate scripts in exclusive mode" switch (if it's ON) allows you to disable all existing FlyWithLua scripts before solution applying.

Disabled scripts still remain in FlyWithLua script catalog, but their extensions change from "lua" to "~lua" (and FlyWithLua plugin ignores them).
To predict what will happen with already installed Lua scripts after solution applying, use "View details" button on the right next to the "Activate scripts in exclusive mode" switch.

There is an "Options" button next to "RESOURCES & SCRIPTS" section on the titlebar of main tool window.
Options section allows to change UI skin and turn on/off errors sound and updates notifications.

8. Using expressions

Note: this section is for real nerds :)

IMPORTANT NOTE BEFORE YOU TRY! There is no error detection provided! Use expressions in tweak parameters on your own risk! Wrong syntax or errors in your code can result in X-Plane malfunction (you will get shaders error at sim start). You've been warned :)

Usually the tweak parameters are numbers. It's quite enough for the most cases. But sometimes the fine tuning requires dynamically changing parameters depending on certain conditions. For instance you want to reduce the direct sunlight saturation (which colors the objects in red at sunset). You can simply reduce saturation in "Sunlight adjustments" tweak (0.7 looks fine here):

But in this case sunlight will slightly desaturated all the time: you may get some cold tint at daytime or early evening. The better way is to desaturate sunlight only at evening/morning. There is no information about time of the day in shaders so let's use the sort of "sun power" to determine when sunlight should be desaturated. (Another trick can be used: when Red component of sunlight become much more Green component or so..).

I will use gl_LightSource[0].diffuse.rgb variable to get the sun power (it works in scattering shader context). To be more precise I'll get green component of this variable gl_LightSource[0].diffuse.g. At afternoon it’s strong and equals ~1.0, at night ~0.0). For example, I want sunlight desaturation stays at default value (1.00) at noon and starts smoothly decreasing down to 0.7 at twilight (when sunlight power becomes lower than 0.3. I.e. when sunpower=0.3 or greater, saturation=1.0; when sunpower=0.0, saturation=0.7.

To make smooth transition try linear interpolation expression:
Saturation = 1.0 + (0.7 - 1.0)/(0 - 0.3) * (SunPower - 0.3) or
Saturation = 1.0 + (SunPower - 0.3)

To prevent cases when calculations of Saturation value lower than 0.7 or greater than 1.0, use GLSL clamp function. So the final expression for saturation parameter will be
clamp(1.0 + (gl_LightSource[0].diffuse.g - 0.3), 0.7, 1.0)

Put it in expression box and apply solution with this parameter.

Here is a result at the same time and place:

9.Appendix A: Detailed list of tweaks with descriptions

Please be advised that list of actual tweaks and parameters may vary depending on X-Plane and xVision versions.

Here you can get the actual list.