user manual

(This is manual for legacy xVision versions 1.02-1.50.
Latest release for xVision 2.00 you can find here).

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.50 and later, if tool will support it.
  • 300+ MBytes on hard drive. SSD recommended.
  • Up to 1.6 GB RAM.
  • 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 X-Plane versions 11.50 and later.

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. xVision is not a standard X-Plane plugin and you needn't install it into Plugins directory of the sim.

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

For X-Plane ver. 11.21-11.26 please use xVision ver 1.02 (archive filename is xVision_102.zip).

For X-Plane ver. 11.30+ please use xVision ver 1.41 (archive filename is xVision_141.zip).

For X-Plane ver. 11.50+ please use xVision ver 1.50 (archive filename is xVision_150.zip).

xVision 1.41 works ONLY WITH X-PLANE 11.30-11.41 and requires separate installation from xVision 1.02 for XP 11.21-11.26. xVision version 1.50 works with X-Plane 11.50 and later and requires separate installation from xVision 1.41 and xVision 1.021
Please do not mix xVision 1.02, 1.41 and 1.50 installations.

Solutions created for xVision 1.02 may be uncompatible with xVision 1.20+.

IMPORTANT NOTE FOR XVISION 1.20-1.41 (FOR X-PLANE 11.30 - 11.41) !Solutions applying take a lot of time. New pre-Vulkan shaders structure have transformed some shader files from one single file in XP 11.26 to thousands of files in 11.30+. That's why solution processing needs more time. We strongly recommend to add the entire X-Plane directory or \Resources\Shaders\ directory and your xVision 1.20+ directory in exceptions list of your antivirus software (including built-in Windows defender).

Each 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.
  • Nordic.xvs - ready "Nordic" solution for using without FlyWithLua plugin installed or for using with FlyWithLua Core edition.
  • Nordic_for_Lua.xvs - ready "Nordic" solution for using with FlyWithLua Complete edition or FlyWithLua NG (Next Generation) Edition plugin.

(for X-Plane 11.30+ solution names have "11.30+" prefix. I.e. 11.30_Classic.xvs (11.50_Classic.xvs), 11.30_Classic_for_Lua.xvs (11.50_Classic_for_Lua.xvs) and so on.

If your X-Plane 11 setup doesn't include FlyWithLua plugin, or yor are using FlyWithLua Core edition, please use "Classic.xvs", "Impressive.xvs" or "Nordic.xvs" solutions. Otherwise - "Classic_for_Lua.xvs", "Impressive_for_Lua.xvs" or "Nordic_for_Lua".

Before starting the tool please make sure that:

  • for X-Plane 11.02-11.41 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.

How to start using xVision in general steps:
1. Start file xVision.exe from this directory.
2. Read EULA and accept it.
3. xVision will ask you about X-Plane directory. Select directory where your X-Plane 11.30+ is installed and press OK button.
4. Put your activation key in xVision activation key (you can also copy-paste it from Simmarket account or e-mail) and press Activate button. You'll get "Activation successful" message.
5. xVision show you a window with the information what resources from X-Plane have been backed up. Close this window.
6. Main xVision window appears. Now you need to apply the desired solution. Press Ctrl-O or Open button on the left sidebar to load it. (Answer No to save initial solution.)
If you are using FlyWithLua plugin in your X-Plane, please open, for example, 11.30_Impressive_for_Lua.xvs solution file, otherwise use files without Lua suffix (11.30_Impressive.xvs as an example). Solution is loaded.
7. Apply loaded solution to sim: press F9 or Apply button on a left sidebar. IMPORTANT: You have to do it when X-Plane IS NOT RUNNING.
8. Please check program log that your solution is applied succesfully (no ERROR messages there).
9. After applying solution start X-Plane.

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\ (xVision 1.02-1.41 only)

  • 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. (xVision 1.02-1.41 only)

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. (for X-Plane 11.21-11.41) (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" (xVision 1.02-1.41 only) 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.
"Fast shaders processing" switch (for xVision 11.20+) is using for shader tweak acceleration. Allows to reduce time and memory usage while applying solutions. This is an experimental option and should work with the most modern GPUs. (But if you get shader errors on X-Plane start or your solutions do not applied (no visual changes) please turn this option off and try again.)

8. Using expressions (xVision 1.02-1.41 only)

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 saturation of the whole scene. You can simply reduce saturation by using BrigthnessContrastSaturation shader in "Global stage post-processing" tweak (0.6 looks fine here):

But in this case scene will be desaturated all the time: at night and at daytime. What if you want to keep default saturation for the daytime and lower it for night? 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 HDR 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.6 at night (when sunlight power becomes 0.0.

To make smooth transition between daytime and night values try linear interpolation expression:
Saturation = 1.0 + (gl_LightSource[0].diffuse.g - 1.0) * (1.0 - 0.6) / (1.0 - 0.0) or
Saturation = 1.0 + (gl_LightSource[0].diffuse.g - 1.0) * 0.4

Put this expression as a parameter of Saturation and apply solution:

Here is a result at the same time and place at night:

9.Appendix A: Detailed list of tweaks with descriptions

Please be advised that list of shader tweaks and parameters is actual only for xVision 1.02-1.41.

Here you can get the list for legacy version of xVision.