RTD entries for OpenMW-VR

docs/source/conf.py

@@ -147,7 +147,7 @@ html_theme = 'sphinx_rtd_theme'
 #html_css_files = 'figures.css'         use this once Sphinx 1.8 is released!!!
 
 def setup(app):
-    app.add_stylesheet('figures.css')
+    app.add_css_file('figures.css')
 
 
 # The name for this set of Sphinx documents.  If None, it defaults to

docs/source/manuals/index.rst

@@ -4,5 +4,6 @@ User Manuals
 .. toctree::
     :maxdepth: 2
 
+    openmw-vr/index
     openmw-cs/index
     installation/index

docs/source/manuals/installation/index.rst

@@ -8,5 +8,6 @@ In order to use OpenMW, you must install both the engine and the game files for
 	:maxdepth: 2
 
 	install-openmw
+	install-openmw-vr
 	install-game-files
 	common-problems

docs/source/manuals/installation/install-openmw-vr.rst

@@ -0,0 +1,47 @@
+=================
+Install OpenMW-VR
+=================
+
+OpenMW-VR is not yet a part of official OpenMW and must be installed separately.
+
+	.. note::
+		OpenMW-VR is currently a development fork separate from OpenMW, and is without
+		an official release schedule. You will be installing development builds. Tags,
+		for those who know what that is, are intermittent and semi-arbitrary, and no
+		official "release" has been made.
+
+	.. note::
+		Installing OpenMW (the non-VR version) is not required. If you have not run the
+		openmw installer, simply run the wizard included with the OpenMW-VR install.
+
+Windows Binaries
+================
+
+If you're not sure what any of the different methods mean, you should probably stick to this one.
+Simply download the latest build from the following link:
+`https://gitlab.com/madsbuvi/openmw/-/jobs/artifacts/openmw-vr/download?job=Windows_Ninja_Engine_Release <https://gitlab.com/madsbuvi/openmw/-/jobs/artifacts/openmw-vr/download?job=Windows_Ninja_Engine_Release>`_
+and extract the archive into a new/empty folder. If you have not run the OpenMW install wizard in the past, run the extracted openmw_wizard.exe. Now you can run the extracted openmw-vr.exe to launch the game.
+
+	.. note::
+		There is no need to uninstall previous builds, but extract each build into a **new or empty** folder and **do not** extract two builds to the same folder.
+
+Linux
+=====
+
+Linux users will have to build from source.
+
+	.. note::
+		Unlike OpenMW, OpenMW-VR has bumped the version requirement of OSG to 3.6.5. On some distros,
+		this means you'll have to roll your own OSG instead of using what's in the official repos.
+
+	.. note::
+		I do not maintain this fork on linux, other than fixing compilation errors caught by the CI. 
+		I depend on others to make PRs for anything specific to Linux. 
+
+From Source
+===========
+
+Visit the `Development Environment Setup <https://wiki.openmw.org/index.php?title=Development_Environment_Setup>`_
+section of the Wiki for detailed instructions on how to build the engine.
+
+Clone the OpenMW-VR repo at https://gitlab.com/madsbuvi/openmw instead of the regular OpenMW repo, and checkout the branch openmw-vr (this should get checked out by default).

docs/source/manuals/openmw-vr/common-problems.rst

@@ -0,0 +1,78 @@
+###############
+Common Problems
+###############
+
+Bad performance
+###############
+
+:Symptoms:
+	OpenMW-VR plays with a very low framerate.
+
+:Cause:
+	OpenMW-VR is based on OpenMW which is not super well optimized, and is being used to render very poorly optimized
+        assets. VR on top of this can be extremely slow when heavy features like shadows and water reflections are enabled.
+
+:Fix:
+	Reduce shadow complexity or disable shadows altogether. Reduce water shader complexity or disable it altogether.
+        Make sure "Use shared shadow maps" is enabled in the launcher (launcher->advanced->VR).
+
+My Controller doesn't work
+##########################
+
+:Symptoms:
+	OpenMW-VR appears in my headset but my motion controllers do nothing or have extremely limited functionality.
+        Unable to complete even basic gameplay.
+
+:Cause 1:
+	No profile exists for that controller. Check xrcontrollersuggestions.xml and see if there is a profile entry for it.
+        If there is none, then OpenMW-VR has not added support for your controller yet.
+
+:Fix 1:
+    Write your own profile. Consult the openxr spec for the exact interction profile Path, extension name, and available
+    action paths. Feel free to send me this profile, either in an issue or a MR.
+
+:Fix 2:
+    Open an issue at the gitlab and i'll add a profile. Not that i don't have your controller and may write a suboptimal profile.
+
+:Cause 2:
+    You are using an openxr runtime that does not support your controllers. For example, last I checked SteamVR did not
+    support the vive cosmos controllers. If this is the cause then a line in openmw.log will state ``Configuring interaction profile '/interaction_profiles/vendor/controller' (Controller Name)``.
+    followed by ``Required extension 'XR_#' not supported. Skipping interaction profile.``.
+
+:Fix:
+	Make sure your runtime is up to date. Try switching to your headset/controller's native runtimes, as opposed to a
+        non-native runtime like SteamVR.
+
+The menu button and thumbsticks don't work.
+###########################################
+
+:Symptoms:
+	Motion controllers work but thumbsticks and the menu button do nothing.
+
+:Cause:
+	Known bug in SteamVR.
+
+:Fix:
+	Use your headset's native runtimes instead of SteamVR.
+
+Audio does not go to my VR Headset
+##################################
+
+:Symptoms:
+	Audio is not automatically playing in your VR headset instead of your default speakers.
+
+:Cause:
+	OpenMW explicitly selects an audio device at startup and sticks with it. By default this is the default speaker.
+
+:Fix:
+	Either set your default audio to the VR headset, or configure openmw to use it. To do this, add the following lines
+        to the end of settings.cfg.
+
+        ::
+
+            [Sound]
+            device = #
+
+        Where # is the identifier of your device. You can find the correct identifier by reading openmw.log, look for
+        the line ``Enumerated output devices:`` where devices are enumerated.
+

docs/source/manuals/openmw-vr/controls.rst

@@ -0,0 +1,108 @@
+Controls
+########
+
+TODO: It would be useful to include a **brief** gameplay video demonstrating the VR interface here.
+
+Default Bindings
+****************
+
+Default bindings exist for the following controllers:
+ - Oculus Touch Controllers
+ - Index Knuckles
+ - Vive Wands
+ - Microsoft Motion Controllers
+ - Hp Mixed Reality Controllers
+ - Huawei Controllers
+ - Vive Cosmos Controllers
+
+Oculus Touch controllers default bindings:
+    .. image:: ../../../controller_graphics/Oculus_Touch.png
+       :width: 600
+Valve Index controllers default bindings:
+    .. image:: ../../../controller_graphics/Valve_Index.png
+       :width: 600
+
+Similar graphics for other controllers will be added if people with those bindings contribute any.
+Default controls for other controllers are written to be similar to the touch and index controls.
+
+Rebinding
+*********
+Currently there is no user friendly rebinding system available.
+Some OpenXR runtimes may offer their own rebinding service similar to what SteamVR already offers for OpenVR applications.
+
+If you can't rely on that, you'll have to edit
+the bindings manually. To do so find the *xrcontrollersuggestions.xml* file in your openmw root folder **and copy it to
+documents/my games/openmw/** or your platform's equivalent, and edit the new copy.
+The file itself contains a brief explanation for how to edit the file.
+
+    .. note:: You are kindly requested not to edit the xrcontrollersuggestions.xml file that resides in the installation folder. If you do you will not receive any support until you restore the original by reinstalling.
+
+    .. note:: If your OpenXR runtime sports its own rebinding service, it's possible that changes to xrcontrollersuggestions.xml will have no effect and you'll be forced to use that service.
+
+Actions Sets
+************
+
+Actions are divided into two bindable sets: Gameplay, and GUI.
+
+The GUI action set is active whenever you are in a menu and gameplay is paused.
+The gameplay action set is active whenever not in a menu. Bindings may therefore overlap between the two.
+
+Gameplay:
+ - reposition_menu (aka recenter)
+ - meta_menu
+ - sneak
+ - always_run
+ - jump
+ - spell (aka ready_spell)
+ - weapon (aka ready_weapon)
+ - rest
+ - inventory
+ - activate
+ - activate_touched
+ - auto_move
+ - use
+ - move_left_right
+ - move_forward_backward
+ - look_left_right
+
+GUI:
+ - menu_up_down
+ - menu_left_right
+ - menu_select
+ - menu_back
+ - use
+ - game_menu
+ - reposition_menu
+
+Most of these actions are self-explanatory with a few exceptions.
+
+:activate_touched:
+    Whenever this control is active, pointer mode is enabled and your finger will point at stuff. Realistic combat is
+    disabled in this mode, so avoid bindings that are easy to activate unintentionally.
+
+:use:
+    The Use action in VR combines the Active and Use action of pancake OpenMW. When pointer mode is active, Use will
+    activate whatever you are pointing at. When pointer mode is not active, Use will use the readied tool/spell in the
+    direction you are orienting it.
+		
+:Recenter:
+    The special action Recenter is by default assigned the same button as "Meta Menu". To activate recentering, you must **press and hold** the assigned button.
+    The recenter action has differing behaviour depending on whether you are currently in a menu, seated play, or standing play.
+
+        .. note:: In the xrcontrollersuggestions.xml file the recenter action is labeled "reposition_menu".
+
+Recenter (Menus)
+****************
+
+If recentering while navigating some menu, all windows are moved to center on your current location/orientation.
+This is useful if a menu ended up inside of some geometry.
+
+Recenter (Standing play)
+************************
+
+If recentering while in standing play, your view is moved to the location of your character **horizontally**
+
+Recenter (Seated play)
+**********************
+
+If recentering while in seated play, your view is moved to the location of your character **horizontally and vertically**.

docs/source/manuals/openmw-vr/foreword.rst

@@ -0,0 +1,36 @@
+Foreword
+########
+
+How to read the manual
+**********************
+
+The manual can be roughly divided into two parts: a tutorial part that will 
+introduce you to the VR interface and what the available options are, and
+a pitfalls part that will explain (current) known shortcomings of the VR port
+and pitfalls of VR in general.
+
+The rest of this page will explain some terminology.
+
+Terminology
+***********
+A brief explanation of terms and abbreviation
+ - VR: Virtual Reality (duh)
+ - VR Stage: Your physical play area
+ - Mirror texture: The motion picture shown on your pancake monitor when you are playing in VR
+ - OpenXR: An Open Source interface for accessing AR/VR devices.
+
+    This is the VR equivalent of Vulkan, written by the same authors as Vulkan: Khronos. OpenXR, like Vulkan, is purely an interface and not an implementation.
+ - OpenXR Runtime: An implementation of the OpenXR standard.
+ - VR Runtime: The software interfacing with your VR device. An OpenXR Runtime is a subset of a VR runtime.
+ - Native Runtimes: The VR Runtime provided by your device drivers.
+ - SteamVR: Valve's VR Runtime, shipped as a part of Steam. SteamVR, native to the Index, acts also as a non-native runtime to all other headsets
+
+OpenXR vs What you're used to
+*****************************
+Before moving on to the manual contents, I would like to note that OpenMW-VR uses the **OpenXR** API to access VR.
+
+Most VR games you've ever played use vendor-specific APIs, such as OpenVR (SteamVR), Oculus VR, WMR, etc. and not OpenXR.
+This means that while playing OpenMW-VR you may see bugs originating from your VR runtime, that you don't see in other games.
+This will diminish in time as OpenXR runtimes mature.
+
+As an example, SteamVR's OpenXR runtime neglects to map some controls (thumbsticks and the menu button), rendering them inoperable.

docs/source/manuals/openmw-vr/getting_started.rst

@@ -0,0 +1,72 @@
+Getting Started
+###############
+
+Installation
+************
+Navigate to the Installation Guide on the left for help with installing OpenMW-VR.
+
+Before Launching
+****************
+Before launching, you should run the openmw-launcher from your openmw-vr dir and go to the advaced->VR tab.
+Here you should input your real height in meters. There are some other options here that you don't need to care about,
+except maybe the melee combat swing speed if the default doesn't work well for you.
+
+In-game settings
+****************
+In addition to the launcher settings, there are some in-game settings to be aware of. You should look through these
+to make sure everything is to your liking.
+
+:Enable mirror texture:
+    If disabled, nothing is shown on your pancake monitor.
+:Mirror texture eye:
+    Determines which of your eyes is shown on your pancake monitor.
+:Flip mirror texture order:
+    If showing both eyes, flip their order.
+:Haptic Feedback:
+    If enabled, controllers will vibrate in response to successful hits, and to being hit.
+:Hand Directed Movement:
+    If enabled, movement is directed by your left hand instead of your current head orientation.
+:Seated Play:
+    If enabled, tracking is adjusted for seated play.
+:Left Hand Hud Position:
+    Presents two options for where to position the left hand hud. Two options exist since the one i originally made
+    worked very poorly with shields.
+
+Gameplay
+********
+TODO: This part would probably be best demonstrated with a *brief* in-game video.
+The core of the gameplay is the same as pancake OpenMW. The core difference is that instead of pointing and clicking with
+a mouse, you'll be pointing and clicking with motion controllers.
+
+:activators:
+    To interact with activators of any kind (doors, npcs, chests, etc), enable pointer mode using right grip/squeeze
+    and press the trigger when the pointer beam is on an activator.
+
+:text input:
+    Whenever a text input dialogue appears, look at your left hand and write your name using the
+    virtual keyboard attached to your left hand.
+
+:realistic melee combat:
+    Melee combat in openmw-vr is "realistic", meaning you can swing your sword at your foes to hurt them. Currently
+    the only way to disambiguate a dice roll miss from an actual miss, is to see if the enemy's healthbar appeared
+    on your left-hand hud. There is a minimum sing speed below which swings are not activated, and a maximum swing speed
+    above which no benefit is derived. Swing strength scales from minimum to maximum in this interval. Openmw-vr selects
+    between chop, slash, and thrust based on how you moved your weapon.
+
+        .. note:: Although there is no explicit option to disable realistic combat, you can effectively disabled it by
+            entering unreasonably high values for swing speeds.
+
+:unrealistic melee combat:
+    If you prefer not swinging your weapon, point and click combat is possible by holding your weapon towards the enemy
+    and pressing the right trigger. This mode does not receive any animation. Note that you must aim your weapon, not
+    your hand, at the enemy.
+
+:lockpicks and probes:
+    Lockpicks and propes work like unrealistic melee combat. Aim your tool at the door/chest and press use.
+
+:On-touch spells:
+    Simply point your hand at your target and press use.
+
+:Ranged combat:
+    Ranged combat is a simple point and click. Aiming works the same for all ranged, including spells. No aim assistance
+    has been implemented.

docs/source/manuals/openmw-vr/index.rst

@@ -0,0 +1,23 @@
+OpenMW VR User Manual
+#####################
+
+The following document is the complete user manual for *OpenMW VR*, the
+VR port of the OpenMW game engine. It is intended to serve both as an
+introduction and a reference for the application. Even if you are familiar with
+*OpenMW* and/or *The Elder Scrolls III: Morrowind* you should at least read the first
+few chapters to familiarise yourself with the VR interface.
+
+.. warning::
+    OpenMW VR is still software in development. The manual does not cover any of
+    its shortcomings, it is written as if everything was working as intended.
+    Please report any software problems as bugs in the software, not errors in
+    the manual.
+
+.. toctree::
+    :caption: Table of Contents
+    :maxdepth: 2
+
+    foreword
+    getting_started
+    controls
+    common-problems