From 1ad888281deaaaa21eb028adbb48e8ef0a29f8da Mon Sep 17 00:00:00 2001 From: dkwdaft <31158132+dkwdaft@users.noreply.github.com> Date: Thu, 9 Apr 2026 10:14:45 +0100 Subject: [PATCH 1/5] Add Node.js CI workflow for testing and building This workflow installs node dependencies, builds the source code, and runs tests across multiple Node.js versions. --- .github/workflows/node.js.yml | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 .github/workflows/node.js.yml diff --git a/.github/workflows/node.js.yml b/.github/workflows/node.js.yml new file mode 100644 index 000000000..2284b9357 --- /dev/null +++ b/.github/workflows/node.js.yml @@ -0,0 +1,31 @@ +# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node +# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs + +name: Node.js CI + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + +jobs: + build: + + runs-on: ubuntu-latest + + strategy: + matrix: + node-version: [18.x, 20.x, 22.x] + # See supported Node.js release schedule at https://nodejs.org/en/about/releases/ + + steps: + - uses: actions/checkout@v4 + - name: Use Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: 'npm' + - run: npm ci + - run: npm run build --if-present + - run: npm test From 9c18a4c332e66355e4780b140a768ef2c1a4ad20 Mon Sep 17 00:00:00 2001 From: dkwdaft <31158132+dkwdaft@users.noreply.github.com> Date: Sat, 18 Apr 2026 18:53:33 +0100 Subject: [PATCH 2/5] Delete .github/workflows/node.js.yml --- .github/workflows/node.js.yml | 31 ------------------------------- 1 file changed, 31 deletions(-) delete mode 100644 .github/workflows/node.js.yml diff --git a/.github/workflows/node.js.yml b/.github/workflows/node.js.yml deleted file mode 100644 index 2284b9357..000000000 --- a/.github/workflows/node.js.yml +++ /dev/null @@ -1,31 +0,0 @@ -# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node -# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs - -name: Node.js CI - -on: - push: - branches: [ "main" ] - pull_request: - branches: [ "main" ] - -jobs: - build: - - runs-on: ubuntu-latest - - strategy: - matrix: - node-version: [18.x, 20.x, 22.x] - # See supported Node.js release schedule at https://nodejs.org/en/about/releases/ - - steps: - - uses: actions/checkout@v4 - - name: Use Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v4 - with: - node-version: ${{ matrix.node-version }} - cache: 'npm' - - run: npm ci - - run: npm run build --if-present - - run: npm test From 14da807a5933685f7a2fa849aa334a0d45c39263 Mon Sep 17 00:00:00 2001 From: dkwdaft <31158132+dkwdaft@users.noreply.github.com> Date: Sun, 25 Oct 2026 12:16:19 +0000 Subject: [PATCH 3/5] update gitignore --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index ceec18389..e16ff3322 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,5 @@ logs/ reports/ .claude/settings.json .claude/settings.local.json +docs/.DS_Store +.DS_Store From 357ea62f172144dcdae8dd99b007673472b171ab Mon Sep 17 00:00:00 2001 From: dkwdaft <31158132+dkwdaft@users.noreply.github.com> Date: Sun, 25 Oct 2026 12:16:35 +0000 Subject: [PATCH 4/5] add PS access controller docs --- docs/playstation-access-controller-setup.md | 109 ++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 docs/playstation-access-controller-setup.md diff --git a/docs/playstation-access-controller-setup.md b/docs/playstation-access-controller-setup.md new file mode 100644 index 000000000..296edc1f1 --- /dev/null +++ b/docs/playstation-access-controller-setup.md @@ -0,0 +1,109 @@ +# Complete Setup Guide: PlayStation Access Controller for Flock XR + +This guide walks you through setting up and configuring the PlayStation Access controller for use with **Flock XR**, covering initial profile creation on the PS5 console, button-to-direction mapping, building an external second joystick for camera control, Bluetooth pairing across **mobile phones (iOS / Android)** and **computers (Windows / macOS)**, and testing. + +--- + +## Step 1: Create & Configure a Profile on the PS5 + +Before connecting to your mobile device or computer, you must create a custom profile directly on a PlayStation 5 console to assign physical directions to the specific **Button Numbers** used by Flock XR and configure joystick inputs. + +1. Connect your Access controller to a PS5 console using the included USB-C cable. +2. Navigate to **Settings** > **Accessibility** > **Access Controller** on the PS5 menu. +3. Select **Create Profile** (or edit an existing custom profile). +4. **Set Orientation**: Select the physical orientation of the controller on your desk/surface so the console correctly registers **North**, **East**, **South**, and **West**. + +--- + +## Step 2: Map Directions to Flock XR Button Numbers & Symbols + +In the PS5 button assignment menu, assign each cardinal direction to its corresponding **Flock XR Button Number** and PlayStation face symbol: + +| Direction | Flock XR Button Number | PlayStation Symbol Tag | PS5 Input Assignment | +| --- | --- | --- | --- | +| **East** | **Button 1** | **Circle ($\bigcirc$)** | Assign to **Button 1** (or $\bigcirc$) | +| **North** | **Button 2** | **Triangle ($\triangle$)** | Assign to **Button 2** (or $\triangle$) | +| **West** | **Button 3** | **Square ($\square$)** | Assign to **Button 3** (or $\square$) | +| **South** | **Button 4** | **Cross ($\times$)** | Assign to **Button 4** (or $\times$) | + +*Tip: You can swap the physical button cap tags ($\bigcirc, \triangle, \square, \times$) on the Access controller so the visual tags match your physical layout.* + +--- + +## Step 3: Configure Joysticks & Build an External Second Joystick (Movement & Camera Control) + +Flock XR requires two joysticks for standard 3D navigation (one for player movement and one for camera orientation): + +1. **Integrated Left Joystick (Movement)**: +* Configure the built-in joystick on the Access controller as the **Left Stick** in the PS5 controller settings. +* Adjust the stick orientation, sensitivity, and dead zones to match your setup position. + + +2. **External Right Joystick (Camera Movement)**: +* Because the PlayStation Access controller comes with only one built-in joystick, you will need a second analog stick plugged into one of the 3.5mm expansion ports to handle camera movement. +* You can 3D print and assemble your own custom module using open designs like the **[PS5 Access Controller Second Stick on Thingiverse](https://www.thingiverse.com/thing:6533366)** by Harakan. +* This design uses a standard dual-axis joystick module (such as an Arduino KY-023), a 3.5mm 4-pole audio connector wired to the appropriate pins (Sleeve for Vdd, Ring 2 for Gnd, Ring 1 for X-Axis, Tip for Y-Axis), and a 3D-printed enclosure. +* Plug your completed external joystick into a 3.5mm expansion port on the Access controller, and map it as the **Right Stick** in your PS5 profile settings. + + + +--- + +## Step 4: Save to Onboard Memory + +1. Save the configuration to one of the **3 onboard profile slots** on the Access controller. +2. Unplug the USB cable from the console. +3. Press the physical **Profile Button** on the side/base of the Access controller until the indicator LED shows the slot where you saved this profile. + +--- + +## Step 5: Pair Controller via Bluetooth (Mobile Phones & Computers) + +To connect the Access controller wirelessly to the device running Flock XR: + +1. **Put the Controller into Pairing Mode**: +* Ensure the controller is turned **OFF** (unplugged and status lights off). +* Press and hold the **PS Button** and the **Profile Button** simultaneously until the **status indicator LEDs** start flashing rapidly. + + +2. **Connect to Your Device**: +* **Mobile Phones (iOS / iPhone)**: +1. Open **Settings** > **Bluetooth** and turn Bluetooth **ON**. +2. Under **Other Devices**, select **Access Controller** (or *Wireless Controller*). +3. *(Optional)* Go to **Settings** > **General** > **Game Controller** to review profile or button settings. + + +* **Mobile Phones (Android)**: +1. Open **Settings** > **Connected devices** (or **Connections**) > **Bluetooth**. +2. Tap **Pair new device**. +3. Select **Access Controller** (or *Wireless Controller*) from the list. + + +* **Windows PC**: +1. Go to **Settings** > **Bluetooth & devices** > **Add device** > **Bluetooth**. +2. Select **Access Controller** (or *Wireless Controller*). + + +* **Mac (macOS)**: +1. Go to **System Settings** > **Bluetooth**. +2. Locate **Access Controller** under *Nearby Devices* and click **Connect**. + + + + + +*Once paired, the status indicator LEDs will stop flashing and stay solid.* + +--- + +## Step 6: Test in Flock XR + +1. Open **Flock XR** on your mobile phone or computer. +2. Test inputs to verify that pressing each cardinal direction registers the correct software button and PlayStation symbol: +* **East** $\rightarrow$ **Button 1 ($\bigcirc$)** +* **North** $\rightarrow$ **Button 2 ($\triangle$)** +* **West** $\rightarrow$ **Button 3 ($\square$)** +* **South** $\rightarrow$ **Button 4 ($\times$)** + + +3. Verify that the **Left Joystick** controls character movement and the **External Right Joystick** controls camera rotation smoothly. \ No newline at end of file From 17f27417437dc7645c57fe13ddf87f15779702c1 Mon Sep 17 00:00:00 2001 From: dkwdaft <31158132+dkwdaft@users.noreply.github.com> Date: Sun, 25 Oct 2026 12:25:03 +0000 Subject: [PATCH 5/5] add AI disclaimer to documentation --- docs/playstation-access-controller-setup.md | 41 ++++++++++++--------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/playstation-access-controller-setup.md b/docs/playstation-access-controller-setup.md index 296edc1f1..9e291c191 100644 --- a/docs/playstation-access-controller-setup.md +++ b/docs/playstation-access-controller-setup.md @@ -1,32 +1,37 @@ # Complete Setup Guide: PlayStation Access Controller for Flock XR -This guide walks you through setting up and configuring the PlayStation Access controller for use with **Flock XR**, covering initial profile creation on the PS5 console, button-to-direction mapping, building an external second joystick for camera control, Bluetooth pairing across **mobile phones (iOS / Android)** and **computers (Windows / macOS)**, and testing. +> **Disclosure:** This guide was drafted with AI (Google Gemini) assistance and reviewed and verified by a human. + +--- + +> **Note on Accessibility Controllers (PlayStation Access, Xbox Adaptive Controller, & Other Systems):** +> Flock XR relies on a standard 4-way cardinal spatial button layout (1 at East, 2 at North, 3 at West, 4 at South). Even if an adaptive controller—such as the **Xbox Adaptive Controller (XAC)** for Xbox One/Series/PC, **Logitech Adaptive Gaming Kit**, or custom switch interfaces—does not feature PlayStation geometric symbols ($\bigcirc, \triangle, \square, \times$), the exact same setup principles apply across all accessibility hardware. On an Xbox Adaptive Controller or Xbox-compatible setup, simply map whichever physical switches, jack inputs, or buttons occupy those spatial positions to Buttons 1 through 4 (or $B, Y, X, A$) in the Xbox Accessories app or your controller's profile settings. --- ## Step 1: Create & Configure a Profile on the PS5 -Before connecting to your mobile device or computer, you must create a custom profile directly on a PlayStation 5 console to assign physical directions to the specific **Button Numbers** used by Flock XR and configure joystick inputs. +Before connecting to your mobile device or computer, you must create a custom profile directly on a PlayStation 5 console to assign physical positions to the specific **Button Numbers** used by Flock XR and configure joystick inputs. 1. Connect your Access controller to a PS5 console using the included USB-C cable. 2. Navigate to **Settings** > **Accessibility** > **Access Controller** on the PS5 menu. 3. Select **Create Profile** (or edit an existing custom profile). -4. **Set Orientation**: Select the physical orientation of the controller on your desk/surface so the console correctly registers **North**, **East**, **South**, and **West**. +4. **Set Orientation**: Select the physical orientation of the controller on your desk or mounting surface so the console correctly registers the **North**, **East**, **South**, and **West** cardinal layout around the button ring. --- -## Step 2: Map Directions to Flock XR Button Numbers & Symbols +## Step 2: Map Cardinal Positions to Flock XR Button Numbers & Symbols -In the PS5 button assignment menu, assign each cardinal direction to its corresponding **Flock XR Button Number** and PlayStation face symbol: +In the PS5 button assignment menu, assign each cardinal position around the controller ring to its corresponding **Flock XR Button Number** and PlayStation face symbol: -| Direction | Flock XR Button Number | PlayStation Symbol Tag | PS5 Input Assignment | -| --- | --- | --- | --- | -| **East** | **Button 1** | **Circle ($\bigcirc$)** | Assign to **Button 1** (or $\bigcirc$) | -| **North** | **Button 2** | **Triangle ($\triangle$)** | Assign to **Button 2** (or $\triangle$) | -| **West** | **Button 3** | **Square ($\square$)** | Assign to **Button 3** (or $\square$) | -| **South** | **Button 4** | **Cross ($\times$)** | Assign to **Button 4** (or $\times$) | +| Spatial Position | Flock XR Button Number | PlayStation Symbol Tag | PS5 Input Assignment | Xbox Equivalent | +| --- | --- | --- | --- | --- | +| **East** | **Button 1** | **Circle ($\bigcirc$)** | Assign to **Button 1** (or $\bigcirc$) | **B Button** | +| **North** | **Button 2** | **Triangle ($\triangle$)** | Assign to **Button 2** (or $\triangle$) | **Y Button** | +| **West** | **Button 3** | **Square ($\square$)** | Assign to **Button 3** (or $\square$) | **X Button** | +| **South** | **Button 4** | **Cross ($\times$)** | Assign to **Button 4** (or $\times$) | **A Button** | -*Tip: You can swap the physical button cap tags ($\bigcirc, \triangle, \square, \times$) on the Access controller so the visual tags match your physical layout.* +*Tip: You can swap the physical button cap tags ($\bigcirc, \triangle, \square, \times$) on the Access controller so the visual tags match your physical spatial layout.* --- @@ -40,7 +45,7 @@ Flock XR requires two joysticks for standard 3D navigation (one for player movem 2. **External Right Joystick (Camera Movement)**: -* Because the PlayStation Access controller comes with only one built-in joystick, you will need a second analog stick plugged into one of the 3.5mm expansion ports to handle camera movement. +* Because the PlayStation Access controller comes with only one built-in joystick, you will need a second analogue stick plugged into one of the 3.5mm expansion ports to handle camera movement. * You can 3D print and assemble your own custom module using open designs like the **[PS5 Access Controller Second Stick on Thingiverse](https://www.thingiverse.com/thing:6533366)** by Harakan. * This design uses a standard dual-axis joystick module (such as an Arduino KY-023), a 3.5mm 4-pole audio connector wired to the appropriate pins (Sleeve for Vdd, Ring 2 for Gnd, Ring 1 for X-Axis, Tip for Y-Axis), and a 3D-printed enclosure. * Plug your completed external joystick into a 3.5mm expansion port on the Access controller, and map it as the **Right Stick** in your PS5 profile settings. @@ -99,11 +104,11 @@ To connect the Access controller wirelessly to the device running Flock XR: ## Step 6: Test in Flock XR 1. Open **Flock XR** on your mobile phone or computer. -2. Test inputs to verify that pressing each cardinal direction registers the correct software button and PlayStation symbol: -* **East** $\rightarrow$ **Button 1 ($\bigcirc$)** -* **North** $\rightarrow$ **Button 2 ($\triangle$)** -* **West** $\rightarrow$ **Button 3 ($\square$)** -* **South** $\rightarrow$ **Button 4 ($\times$)** +2. Test inputs to verify that pressing each cardinal position registers the correct software button and symbol: +* **East** $\rightarrow$ **Button 1 ($\bigcirc$ / B)** +* **North** $\rightarrow$ **Button 2 ($\triangle$ / Y)** +* **West** $\rightarrow$ **Button 3 ($\square$ / X)** +* **South** $\rightarrow$ **Button 4 ($\times$ / A)** 3. Verify that the **Left Joystick** controls character movement and the **External Right Joystick** controls camera rotation smoothly. \ No newline at end of file