From 5e0a6241a7e8b9c9cca053745c9f3a6561305c53 Mon Sep 17 00:00:00 2001 From: Patryk Kalinowski Date: Wed, 3 May 2023 12:56:50 +0200 Subject: [PATCH] release 0.1.0 --- .gitattributes | 7 ++ .gitignore | 18 ++- LICENSE | 2 +- README.MD | 25 ++-- addons/xr-kit/LICENSE | 21 ++++ addons/xr-kit/README.MD | 118 ++++++++++++++++++ addons/xr-kit/cinematic-view/README.MD | 6 +- .../{Playground.tscn => playground.tscn} | 0 .../xr-kit/hand-gesture-recognition/README.MD | 10 +- addons/xr-kit/physics-movement/README.MD | 8 +- addons/xr-kit/smooth-input-filter/README.MD | 4 +- icon.png | Bin 0 -> 4197 bytes .../cinematic_view.gif | Bin .../hand_gesture_recognition.gif | Bin .../openxr_hands.png | Bin .../physics_movement.gif | Bin .../smooth_input_filter.gif | Bin 17 files changed, 190 insertions(+), 29 deletions(-) create mode 100644 .gitattributes create mode 100644 addons/xr-kit/LICENSE create mode 100644 addons/xr-kit/README.MD rename addons/xr-kit/examples/{Playground.tscn => playground.tscn} (100%) create mode 100644 icon.png rename addons/xr-kit/cinematic-view/showcase.gif => screenshots/cinematic_view.gif (100%) rename addons/xr-kit/hand-gesture-recognition/showcase.gif => screenshots/hand_gesture_recognition.gif (100%) rename {addons/xr-kit/physics-movement => screenshots}/openxr_hands.png (100%) rename addons/xr-kit/physics-movement/showcase.gif => screenshots/physics_movement.gif (100%) rename addons/xr-kit/smooth-input-filter/showcase.gif => screenshots/smooth_input_filter.gif (100%) diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..e6ac634 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,7 @@ +# Normalize line endings for all files that Git considers text files. +* text=auto eol=lf + +# Only include the addons folder when downloading from the Asset Library. +/** export-ignore +/addons !export-ignore +/addons/** !export-ignore \ No newline at end of file diff --git a/.gitignore b/.gitignore index 913c792..0c3c32d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,16 @@ -.godot -*.import \ No newline at end of file +# Godot 4+ specific ignores +.godot/ + +# Godot-specific ignores +.import/ +*.import +export.cfg +export_presets.cfg + +# Imported translations (automatically generated from CSV files) +*.translation + +# Mono-specific ignores +.mono/ +data_*/ +mono_crash.*.json \ No newline at end of file diff --git a/LICENSE b/LICENSE index 698e4f5..88d663f 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2022 Patryk Kalinowski (patrykkalinowski.com) +Copyright (c) 2023 Patryk Kalinowski (patrykkalinowski.com) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.MD b/README.MD index 1546660..b1ac990 100644 --- a/README.MD +++ b/README.MD @@ -6,7 +6,7 @@ Godot XR Kit is a set of addons providing various features for XR development in Physics-based XR movement. Player hands collide with environment and can grab or push physics object in realistic manner. Player body can collide with physics objects and be moved around in space. -![Godot XR Kit - Physics Movement](/addons/xr-kit/physics-movement/showcase.gif) +![Godot XR Kit - Physics Movement](/screenshots/physics_movement.gif) ### Features @@ -29,7 +29,7 @@ Physics-based XR movement. Player hands collide with environment and can grab or Real-time recognition of hand poses based on predefined templates. -![Godot XR Kit - Hand Gesture Recognition](/addons/xr-kit/hand-gesture-recognition/showcase.gif) +![Godot XR Kit - Hand Gesture Recognition](/screenshots/hand_gesture_recognition.gif) ### Currently tracked hand poses: @@ -46,7 +46,7 @@ Real-time recognition of hand poses based on predefined templates. Applies smoothing to XR hand movement using [1€ filter](https://gery.casiez.net/1euro/). Supports hand and controller tracking. See [1€ filter demo](https://gery.casiez.net/1euro/InteractiveDemo/). Can be used to reduce microstutter or simulate fake weight by increasing hand movement lag. -![Godot XR Kit - Smooth Input Filter](/addons/xr-kit/smooth-input-filter/showcase.gif) +![Godot XR Kit - Smooth Input Filter](/screenshots/smooth_input_filter.gif) ### Features: @@ -59,7 +59,7 @@ Applies smoothing to XR hand movement using [1€ filter](https://gery.casiez.ne Smooth VR preview for recording in native monitor resolution. -![Godot XR Kit - Cinematic View](/addons/xr-kit/cinematic-view/showcase.gif) +![Godot XR Kit - Cinematic View](/screenshots/cinematic_view.gif) *Raw preview (left) vs Cinematic View* @@ -74,14 +74,15 @@ Smooth VR preview for recording in native monitor resolution. ## Getting started -Repository contains Godot v4.0.1 project with XR and main scene preconfigured. +Repository contains Godot 4.0.2 project with XR and main scene preconfigured. Releases are reduced to addon files only. -1. Download project using [this link](https://github.com/patrykkalinowski/godot-xr-kit/archive/refs/heads/master.zip). -2. Click `Run Project` or press F5 -3. `Playground` scene from examples folder will be loaded +Latest release is available in Godot's Asset Library under the name [XR Kit](https://godotengine.org/asset-library/asset/1870) or on [releases page](https://github.com/patrykkalinowski/godot-xr-kit/releases/latest). -`xr-kit/examples/playground.tscn` implements Physics Movement and Hand Gesture Recognition. -`xr-kit/examples/smooth_input_filter.tscn` implements Smooth Input Filter. +To get most recent version of the whole project, [download from master branch](https://github.com/patrykkalinowski/godot-xr-kit/archive/refs/heads/master.zip). + +`/addons/xr-kit/examples/playground.tscn` implements Physics Movement, Hand Gesture Recognition and Cinematic View. + +`/addons/xr-kit/examples/smooth_input_filter.tscn` implements Smooth Input Filter. ## Compatibility @@ -110,8 +111,8 @@ Source code contains multiple `TODO` comments with known issues and missing feat ### Showcase -Build something with the plugin and share an example scene or recorded video +Build something with the plugin and share an example scene or recorded video [here](https://github.com/patrykkalinowski/godot-xr-kit/discussions/categories/show-and-tell). ### Ideas -If you have some ideas how to improve the plugin, don't hesitate to [create an issue](https://github.com/patrykkalinowski/godot-xr-kit/issues/new) or message me directly at [patryk@patrykkalinowski.com](mailto:patryk@patrykkalinowski.com). +If you have some ideas how to improve the plugin, don't hesitate to [create new discussion](https://github.com/patrykkalinowski/godot-xr-kit/discussions/categories/ideas) or message me directly at [patryk@patrykkalinowski.com](mailto:patryk@patrykkalinowski.com). diff --git a/addons/xr-kit/LICENSE b/addons/xr-kit/LICENSE new file mode 100644 index 0000000..88d663f --- /dev/null +++ b/addons/xr-kit/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023 Patryk Kalinowski (patrykkalinowski.com) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/addons/xr-kit/README.MD b/addons/xr-kit/README.MD new file mode 100644 index 0000000..b1ac990 --- /dev/null +++ b/addons/xr-kit/README.MD @@ -0,0 +1,118 @@ +# Godot XR Kit + +Godot XR Kit is a set of addons providing various features for XR development in Godot 4. + +## Physics Movement + +Physics-based XR movement. Player hands collide with environment and can grab or push physics object in realistic manner. Player body can collide with physics objects and be moved around in space. + +![Godot XR Kit - Physics Movement](/screenshots/physics_movement.gif) + +### Features + +- Physics hand follows controller and can be blocked by world objects +- Players can grab and move objects + - Heavy objects are harder to move + - Grabbing heavy objects with two hands makes them easier to move + - Fingers curl around grabbed objects geometry +- Players can move themselves by pushing away from objects + - Heavier objects allow for stronger push +- Players can move in space with thrusters (button activated) +- Players can hit objects with their head and push themselves away +- Ghost hand appears when controller hand gets far from physics one +- Body snap rotation +- Body XYZ rotation around static object using hands (trigger activated) + +[Read more](/addons/xr-kit/physics-movement/) + +## Hand Gesture Recognition + +Real-time recognition of hand poses based on predefined templates. + +![Godot XR Kit - Hand Gesture Recognition](/screenshots/hand_gesture_recognition.gif) + +### Currently tracked hand poses: + +- open +- rest +- half_grip +- full_grip +- point +- thumb_up + +[Read more](/addons/xr-kit/hand-gesture-recognition/) + +## Smooth Input Filter + +Applies smoothing to XR hand movement using [1€ filter](https://gery.casiez.net/1euro/). Supports hand and controller tracking. See [1€ filter demo](https://gery.casiez.net/1euro/InteractiveDemo/). Can be used to reduce microstutter or simulate fake weight by increasing hand movement lag. + +![Godot XR Kit - Smooth Input Filter](/screenshots/smooth_input_filter.gif) + +### Features: + +- Supports smoothing movement for hand tracking Skeleton3D and Node3D (ex. XRController3D) +- Reduces jitter while keeping lag to minimum + +[Read more](/addons/xr-kit/smooth-input-filter/) + +## Cinematic View + +Smooth VR preview for recording in native monitor resolution. + +![Godot XR Kit - Cinematic View](/screenshots/cinematic_view.gif) + +*Raw preview (left) vs Cinematic View* + +## Features: + +- Full screen VR preview in monitor native resolution +- Smooth preview can be rendered to another screen +- Smoothing parameters can be tuned +- Full range of Godot's camera settings is available + +[Read more](/addons/xr-kit/cinematic-view/) + +## Getting started + +Repository contains Godot 4.0.2 project with XR and main scene preconfigured. Releases are reduced to addon files only. + +Latest release is available in Godot's Asset Library under the name [XR Kit](https://godotengine.org/asset-library/asset/1870) or on [releases page](https://github.com/patrykkalinowski/godot-xr-kit/releases/latest). + +To get most recent version of the whole project, [download from master branch](https://github.com/patrykkalinowski/godot-xr-kit/archive/refs/heads/master.zip). + +`/addons/xr-kit/examples/playground.tscn` implements Physics Movement, Hand Gesture Recognition and Cinematic View. + +`/addons/xr-kit/examples/smooth_input_filter.tscn` implements Smooth Input Filter. + +## Compatibility + +Plugin should work with every OpenXR runtime supporting Vulkan and using OpenXR hand tracking extension. It works best with SteamVR, as it simulates hand skeleton even when using controllers. In other runtimes, when using controllers, hands will not receive skeleton data and they will not work. + +For plugin to be fully compatible with all OpenXR runtimes, it needs hand models with animations - which is planned, but not yet implemented. + +| Headset | Runtime | Compatible | +|---|---|:---:| +| HP Reverb G2 | SteamVR | Yes | +| Pico 4 | Standalone | No hand tracking | +| Meta Quest 2 | Standalone | Hand tracking only (no controllers) +| Other | ? | ? | + +## Contributing + +If you'd like to improve the plugin, there are few options: + +### Test compatibility with other headsets and runtimes + +I don't have access to other headset than mine (HP Reverb G2). Compatibility checks with other headsets are more than welcome. + +### Code improvements + +Source code contains multiple `TODO` comments with known issues and missing features. You can also take a look at existing [Issues](https://github.com/patrykkalinowski/godot-xr-kit/issues). + +### Showcase + +Build something with the plugin and share an example scene or recorded video [here](https://github.com/patrykkalinowski/godot-xr-kit/discussions/categories/show-and-tell). + +### Ideas + +If you have some ideas how to improve the plugin, don't hesitate to [create new discussion](https://github.com/patrykkalinowski/godot-xr-kit/discussions/categories/ideas) or message me directly at [patryk@patrykkalinowski.com](mailto:patryk@patrykkalinowski.com). diff --git a/addons/xr-kit/cinematic-view/README.MD b/addons/xr-kit/cinematic-view/README.MD index 4ad59ab..88a83db 100644 --- a/addons/xr-kit/cinematic-view/README.MD +++ b/addons/xr-kit/cinematic-view/README.MD @@ -2,7 +2,7 @@ Smooth VR preview for recording in native monitor resolution. -![Godot XR Kit - Cinematic View](showcase.gif) +![Godot XR Kit - Cinematic View](/screenshots/cinematic_view.gif) *Raw preview (left) vs Cinematic View* @@ -21,8 +21,8 @@ Cinematic View creates new separate window with player camera view smoothed out. 1. Go to Project Settings, toggle **Advanced settings** and disable **Embed Subwindows** option in **Display -> Window** tab 2. Add `cinematic_view.tscn` anywhere to your scene. -3. Assign your `XRCamera3D` to `CinematicView` node in property editor. +3. Assign your `XRCamera3D` node to `CinematicView` node in property editor. 4. Start a project. Cinematic View will appear as full screen window on your main screen. 5. Record videos using capture software such as OBS Studio or Nvidia Shadowplay. -Cinematic View is implemented in `examples/playground.tscn`. \ No newline at end of file +Cinematic View is implemented in `/addons/xr-kit/examples/playground.tscn`. \ No newline at end of file diff --git a/addons/xr-kit/examples/Playground.tscn b/addons/xr-kit/examples/playground.tscn similarity index 100% rename from addons/xr-kit/examples/Playground.tscn rename to addons/xr-kit/examples/playground.tscn diff --git a/addons/xr-kit/hand-gesture-recognition/README.MD b/addons/xr-kit/hand-gesture-recognition/README.MD index 309878d..f49ea8e 100644 --- a/addons/xr-kit/hand-gesture-recognition/README.MD +++ b/addons/xr-kit/hand-gesture-recognition/README.MD @@ -2,7 +2,7 @@ Real-time recognition of hand poses based on predefined templates. -![Godot XR Kit - Hand Gesture Recognition](showcase.gif) +![Godot XR Kit - Hand Gesture Recognition](/screenshots/hand_gesture_recognition.gif) ## Currently tracked poses: @@ -20,15 +20,15 @@ Distance of every bone in skeleton to bone 0 (wrist) is compared with distances ## Getting started 1. Add `HandPoseRecognition.tscn` anywhere to your scene where hand skeleton is available. -2. Assign your `Skeleton3D` to `HandPoseRecognition` node in property editor. +2. Assign your `Skeleton3D` node to `HandPoseRecognition` node in property editor. 3. When new pose is recognized, `HandPoseRecognition` node will fire `new_pose` signal. 4. Current pose can also be queried from `HandPoseRecognition.pose` variable. -Predefined poses in template file (`hand_pose_templates.json`) were created with skeleton conforming to [OpenXR convention of hand joints](https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#_conventions_of_hand_joints) +Predefined poses in template file (`hand_pose_templates.json`) were created using SteamVR and Valve hands, with skeleton conforming to [OpenXR convention of hand joints](https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#_conventions_of_hand_joints) ## Adding new pose templates 1. Add `HandPoseSave.tscn` anywhere to your scene where hand skeleton is available. -2. Assign your `Skeleton3D` to `HandPoseSave` node. -3. During play, press **spacebar** to save skeleton pose as a template. By default, template will be named `custom_pose` and every press of spacebar will override it with current pose. You can change pose name in `HandPoseSave` property editor (right sidebar). +2. Assign your `Skeleton3D` node to `HandPoseSave` node. +3. During play, press **spacebar** to save skeleton pose as a template. By default, template will be named `custom_pose` and every press of spacebar will override it with current pose. You can change pose name in `HandPoseSave` property editor. 4. You will need to reload the game for new templates to be loaded for recognition. diff --git a/addons/xr-kit/physics-movement/README.MD b/addons/xr-kit/physics-movement/README.MD index 4496007..fcb2cf4 100644 --- a/addons/xr-kit/physics-movement/README.MD +++ b/addons/xr-kit/physics-movement/README.MD @@ -2,9 +2,9 @@ Scripts and scenes for physics-based XR movement. Player hands collide with environment and can grab or push physics object in realistic manner. Player body can collide with physics objects and be moved around in space. -*It is still a work in progress, not ready to be dropped in your game as-is.* +*Physics Movement is in alpha stage.* -![Godot XR Kit - Physics Movement](showcase.gif) +![Godot XR Kit - Physics Movement](/screenshots/physics_movement.gif) ## Features @@ -31,12 +31,12 @@ To make sure physics hand works in predictable ways, only wrist bone is responsi Provided hand models use OpenXR convention of 26 joints for hand tracking: 4 joints for the thumb finger, 5 joints for the other four fingers, and the wrist and palm of the hands. -![OpenXR Hands](openxr_hands.png) +![OpenXR Hands](/screenshots/openxr_hands.png) *Source: https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#_conventions_of_hand_joints* ## Getting started -`player.tscn` contains everything needed for physics movement, including XR interface initialization. +`/addons/xr-kit/physics_movement/scenes/player.tscn` contains everything needed for physics movement, including XR interface initialization. ## Godot 3.5 diff --git a/addons/xr-kit/smooth-input-filter/README.MD b/addons/xr-kit/smooth-input-filter/README.MD index 394a292..d51ec9d 100644 --- a/addons/xr-kit/smooth-input-filter/README.MD +++ b/addons/xr-kit/smooth-input-filter/README.MD @@ -2,7 +2,7 @@ Applies smoothing to XR hand movement using [1€ filter](https://gery.casiez.net/1euro/). Supports hand and controller tracking. See [1€ filter demo](https://gery.casiez.net/1euro/InteractiveDemo/). Can be used to reduce microstutter or simulate fake weight by increasing hand movement lag. -![Godot XR Kit - Smooth Input Filter](showcase.gif) +![Godot XR Kit - Smooth Input Filter](/screenshots/smooth_input_filter.gif) ## Features: @@ -17,7 +17,7 @@ Every axis of source node global_transform's origin (`Vector3`) is passed throug 1. Add `smooth_open_xr_hand.tscn` anywhere to your scene. 2. You need to duplicate nodes you want to smooth, these duplicates will follow source nodes with filter applied. -2. If you are using hand tracking, assign `Skeleton3D` controlled by `OpenXRHand` as **Source Skeleton**. Assign `Skeleton3D` you want to have smoothed as **Destination Skeleton**. +2. If you are using hand tracking, assign `Skeleton3D` node controlled by `OpenXRHand` as **Source Skeleton**. Assign `Skeleton3D` node you want to have smoothed as **Destination Skeleton**. 3. If you are using controllers or want to smooth out movement of any other 3D node, assign nodes to **Source Node** and **Destination Node**. 4. Tune filter with **Allowed Jitter** and **Lag Reduction** parameters. diff --git a/icon.png b/icon.png new file mode 100644 index 0000000000000000000000000000000000000000..a9d943dff5677b66927cbd429d25d05aac321f4c GIT binary patch literal 4197 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