feat: v1.0 — Config UI app, live tuning, throttle/brake curves, haptics, CI

.github/workflows/quality.yml

@@ -0,0 +1,112 @@
+name: Quality
+
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  syntax:
+    name: Lua Syntax
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Lua 5.2
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y lua5.2
+      - name: Check syntax
+        run: |
+          find . -name "*.lua" -not -path "./.github/*" | while read f; do
+            echo "Checking $f"
+            luac5.2 -p "$f" || exit 1
+          done
+          echo "All Lua files pass syntax check"
+
+  lint:
+    name: Luacheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install luacheck
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y luarocks
+          sudo luarocks install luacheck
+      - name: Run luacheck
+        run: luacheck .
+
+  validate:
+    name: Structure
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Required files present
+        run: |
+          for f in MyGamepadFX/manifest.ini MyGamepadFX/config.lua MyGamepadFX/lib.lua MyGamepadFX/assist.lua MyGamepadFX/debug.lua MyGamepadFX_Config/manifest.ini MyGamepadFX_Config/app.lua; do
+            test -f "$f" || { echo "FAIL: missing $f"; exit 1; }
+          done
+          echo "All required files present"
+      - name: Manifest keys
+        run: |
+          grep -q "^NAME" MyGamepadFX/manifest.ini || { echo "FAIL: MyGamepadFX/manifest.ini missing NAME"; exit 1; }
+          grep -q "^VERSION" MyGamepadFX/manifest.ini || { echo "FAIL: MyGamepadFX/manifest.ini missing VERSION"; exit 1; }
+          grep -q "^NAME" MyGamepadFX_Config/manifest.ini || { echo "FAIL: MyGamepadFX_Config/manifest.ini missing NAME"; exit 1; }
+          grep -q "^FUNCTION_MAIN" MyGamepadFX_Config/manifest.ini || { echo "FAIL: MyGamepadFX_Config/manifest.ini missing FUNCTION_MAIN"; exit 1; }
+          echo "Manifests OK"
+      - name: Config keys
+        run: |
+          for key in DEADZONE GAMMA STEER_SMOOTH SPEED_SCALE_START SPEED_SCALE_END SPEED_SCALE_MIN COUNTERSTEER_GAIN COUNTERSTEER_DAMP SLIP_LIMIT_START SLIP_LIMIT_RANGE SLIP_LIMIT_MIN GAS_DEADZONE GAS_GAMMA BRAKE_DEADZONE BRAKE_GAMMA HAPTICS_ENABLED HAPTICS_SLIP_START HAPTICS_SLIP_MAX HAPTICS_STRENGTH DEBUG_MODE; do
+            grep -q "$key" MyGamepadFX/config.lua || { echo "FAIL: config.lua missing $key"; exit 1; }
+          done
+          echo "All 20 config keys present"
+
+  comment:
+    name: PR Comment
+    needs: [syntax, lint, validate]
+    if: always() && github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const results = {
+              'Lua Syntax': '${{ needs.syntax.result }}',
+              'Luacheck':   '${{ needs.lint.result }}',
+              'Structure':  '${{ needs.validate.result }}',
+            }
+            const icon = r => ({ success: '✅', failure: '❌', skipped: '⏭️' }[r] || '⏳')
+            const allGood = Object.values(results).every(r => r === 'success')
+            const rows = Object.entries(results).map(([k, v]) => `| ${k} | ${icon(v)} ${v} |`).join('\n')
+            const body = [
+              `## Quality Check ${allGood ? '✅ Passed' : '❌ Issues found'}`,
+              '',
+              '| Check | Result |',
+              '|---|---|',
+              rows,
+            ].join('\n')
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            })
+            const existing = comments.find(c => c.body.startsWith('## Quality Check'))
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              })
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              })
+            }

.luacheckrc

@@ -0,0 +1,17 @@
+-- CSP (Custom Shaders Patch) LuaJIT 5.2 environment
+std = "lua52"
+max_line_length = false
+
+globals = {
+    "ac",         -- CSP API namespace
+    "ui",         -- CSP UI rendering (app scripts only)
+    "script",     -- CSP entry point table (script.update, script.reset)
+    "windowMain", -- CSP app window entry point (called by runtime, not defined by us)
+    "vec2", "vec3", "vec4", "rgbm",  -- CSP math/color types
+}
+
+ignore = {
+    "212",  -- unused argument: dt is required by CSP entry point signatures
+    "141",  -- setting undefined field: script.update/reset are CSP-defined entry points
+    "143",  -- accessing undefined field: math.clamp is a CSP extension to math
+}

CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Hard Rule — Skill Execution Policy
+
+Skills are lazy-loaded. Nothing runs, reads, or costs tokens unless its trigger condition is explicitly matched by the current task.
+
+- Never pre-load a skill speculatively
+- Never keep a skill active between tasks
+- Read a SKILL.md once per invocation, then release it
+- If no trigger matches, no skill loads
+- Routing is stateless and costs nothing — only the matched skill's read costs tokens
+
+This applies to every skill, every subagent, every session. No exceptions.
+
+## Hard Rule — Response Behavior
+
+No AI patterns. Ever.
+
+No formulaic transitions. No symmetrical structure. No generic phrasing. No predictable rhythm. Vary sentence length naturally.
+
+If multiple choice → output only the correct letter.
+If short answer → output only the direct answer.
+No explanation unless explicitly asked.
+No conclusions. No summaries. No filler.
+
+---
+
+## What This Is
+
+A [Custom Shaders Patch](https://acstuff.ru/patch/) Gamepad FX Lua script for Assetto Corsa. Runs in **LuaJIT** (5.2 compatibility mode) via CSP — no standard Lua toolchain, no package manager, no build step.
+
+## Deployment & Testing
+
+There is no build system. "Deploying" means copying the folder:
+
+```
+MyGamepadFX/ → assettocorsa/extension/lua/joypad-assist/MyGamepadFX/
+```
+
+Testing requires launching Assetto Corsa with the script active. Activate in **Content Manager → Settings → Custom Shaders Patch → Gamepad FX → MyGamepadFX**.
+
+AC Controls must have Speed Sensitivity, Steering Gamma, Steering Filter, and Steering Deadzone all at 0%, Steering Speed at 100% — the script owns all of these.
+
+## Architecture
+
+Four files, strict separation of concerns:
+
+| File | Role |
+|---|---|
+| `manifest.ini` | CSP plugin declaration (name, version) |
+| `config.lua` | All tunable constants, nothing else — returns a `CFG` table |
+| `lib.lua` | Pure math helpers (`applyDeadzone`, `applyGamma`, `lerp`, `expSmooth`, `speedScale`) — no `ac.*` calls, no constants |
+| `assist.lua` | Pipeline assembly and the two CSP entry points |
+| `debug.lua` | Optional live telemetry overlay via `ac.debug()` — disabled by default |
+
+**Pipeline in `assist.lua` (execution order):**
+
+```
+raw input → applyDeadzone → applyGamma → speedScale
+         → slip limit clamp (driver input only)
+         → + selfSteer (not subject to slip clamp)
+         → expSmooth (combined signal)
+         → clamp → ac.setSteer / ac.setGas / ac.setBrake
+```
+
+## CSP Entry Points
+
+```lua
+function script.update(dt)   -- called every physics frame; dt = seconds
+function script.reset()      -- called on session reset; must clear all persistent state
+```
+
+`ac.getCar(0)` returns nil on the first frame — always nil-guard before reading car properties. `dt <= 0` guard also required.
+
+## Debug Overlay
+
+Uncomment in `assist.lua` to enable:
+
+```lua
+local dbg = require('debug')
+```
+
+And uncomment the `dbg.draw({...})` call block. Shows all pipeline intermediate values via `ac.debug()`. Never ship with this enabled.
+
+## Key CSP API
+
+```lua
+ac.getGamepad(0)           -- gamepad.axes[1] = left stick X (steering)
+ac.getCar(0)               -- car.speedKmh, car.wheelsSlip[0..3], car.steer
+ac.setSteer(v)             -- [-1, 1]
+ac.setGas(v)               -- [0, 1]
+ac.setBrake(v)             -- [0, 1]
+math.clamp(v, min, max)    -- CSP extension, not vanilla LuaJIT
+```
+
+## Tuning
+
+Edit `config.lua` only — `assist.lua` contains no raw constants. Tuning order: deadzone → gamma → speed scale → countersteer gain → damp → slip limit → smoothing last.
+
+`COUNTERSTEER_DAMP` must stay ≥ `COUNTERSTEER_GAIN × 0.6` or the car develops tank-slappers.
+
+Frame-rate independence: smoothing uses `expSmooth` with `(1 - smooth)^(dt * 60)` — never use a bare lerp constant directly against `dt`.

INSTALLATION.md

@@ -0,0 +1,104 @@
+# Installation Guide — AC Gamepad FX
+
+---
+
+## Prerequisites
+
+- **Assetto Corsa** (any version)
+- **Custom Shaders Patch (CSP)** v0.2.0 or later — [download at acstuff.ru/patch](https://acstuff.ru/patch/)
+- **Content Manager** (recommended) — [download at assettocorsa.club/content-manager.html](https://assettocorsa.club/content-manager.html)
+
+---
+
+## Step 1: Install the Script
+
+Copy the `MyGamepadFX/` folder into your Assetto Corsa installation:
+
+```
+assettocorsa/extension/lua/joypad-assist/MyGamepadFX/
+```
+
+The folder must contain these four files:
+
+```
+MyGamepadFX/
+├── manifest.ini
+├── config.lua
+├── lib.lua
+├── assist.lua
+└── debug.lua
+```
+
+If the `joypad-assist/` folder doesn't exist, create it.
+
+---
+
+## Step 2: Configure AC Controls (REQUIRED)
+
+**This step must be completed before driving. Skipping it causes broken steering feel that the script cannot detect or correct.**
+
+Navigate to: **Content Manager → Settings (gear icon, top right) → Assetto Corsa → Controls tab**
+
+Set each value exactly as listed:
+
+| Setting | Required Value | Notes |
+|---|---|---|
+| Input Method | Gamepad | Must be Gamepad, not Keyboard/Wheel |
+| Speed Sensitivity | 0% | Script handles this |
+| Steering Speed | 100% | Set to maximum |
+| Steering Gamma | 100% | Critical — script applies its own gamma |
+| Steering Filter | 0% | Script applies its own smoothing |
+| Steering Deadzone | 0% | Script applies its own deadzone |
+
+[Screenshot: CM Controls tab — Input Method dropdown set to "Gamepad"]
+
+[Screenshot: CM Controls tab — Speed Sensitivity slider at 0%]
+
+[Screenshot: CM Controls tab — Steering Gamma slider at 100%]
+
+[Screenshot: CM Controls tab — Steering Filter and Deadzone both at 0%]
+
+**Why these values?** The script takes over all steering correction. If AC applies gamma or deadzone and the script applies them again, they stack — the result is unusable double-processing that cannot be fixed from inside the script.
+
+---
+
+## Step 3: Activate in CSP
+
+In Content Manager: **Settings → Custom Shaders Patch → Gamepad FX**
+
+1. Check that **"Active"** is enabled
+2. Select **"MyGamepadFX"** from the plugin dropdown
+
+[Screenshot: CM CSP settings showing Gamepad FX section with MyGamepadFX selected]
+
+---
+
+## Step 4: First Drive
+
+1. Launch a session (Monaco pitlane is ideal — open space, low traffic)
+2. Open the CM log: **View → Show Log** (or press `Ctrl+L`)
+3. Confirm you see this line at startup:
+   ```
+   [MyGamepadFX] Axis map — axes[0]=... axes[1]=... axes[3]=... axes[4]=...
+   ```
+4. Check the axis values: with the controller at rest, all four should be near `0.0` or `0.00`
+5. Move the left stick — `axes[1]` should change
+6. Press the right trigger — `axes[3]` should change
+7. Drive around and confirm steering, throttle, and brake respond correctly
+
+If you see `[MyGamepadFX] ERROR:` in the log, see [Troubleshooting.md](Troubleshooting.md).
+
+---
+
+## Troubleshooting
+
+| Symptom | First check |
+|---|---|
+| Steering twitchy or spikey | Steering Gamma not at 100% — redo Step 2 |
+| Unresponsive center / large dead zone | Steering Deadzone not at 0% — redo Step 2 |
+| Steering feels delayed/laggy | Steering Filter not at 0% — redo Step 2 |
+| No `[MyGamepadFX]` lines in log | CSP not active or wrong plugin — redo Step 3 |
+| Car drifts without input | Raise `DEADZONE` in config.lua |
+| Car oscillates (tank-slapper) | Raise `COUNTERSTEER_DAMP` in config.lua |
+
+Full troubleshooting guide: [Troubleshooting.md](Troubleshooting.md)