|
| 1 | +# VeltoKit / gametriki — context for AI assistants |
| 2 | + |
| 3 | +Read this file **before** changing code or answering questions about this repository. Human docs: https://koderhack.github.io/veltokit/docs/intro — source in `website/docs/`. |
| 4 | + |
| 5 | +## What this project is |
| 6 | + |
| 7 | +- **VeltoKit** (`VeltoKit/`) — Swift package: BLE motion bytes → **`GameInput`** every frame. Public API: **`MotionSDK`**. |
| 8 | +- **gametriki** (`app/`) — sample iOS app (Xcode: `app/gametriki.xcodeproj`) that uses VeltoKit. Not a second SDK. |
| 9 | +- **Triki** — informal name for the BLE cap UI layer in the app (`app/UI/TrikiUI/`, `TrikiInputAdapter`). Games still consume **`GameInput`**, not raw BLE. |
| 10 | + |
| 11 | +Unofficial / educational. Do not invent hardware brands or packet layouts not in `VeltoKit/BLE/` and `website/docs/sdk/ble-integration.md`. |
| 12 | + |
| 13 | +## Terminology (do not confuse) |
| 14 | + |
| 15 | +| Term | Meaning | |
| 16 | +|------|---------| |
| 17 | +| `MotionSDK` | Main SDK facade: `connect()`, `pollInput()`, `enqueueBLE`, `input` | |
| 18 | +| `MotionEngine` | Internal frame processor (modes, gestures) | |
| 19 | +| `GameInput` | **Only** struct games should use in `update(input:deltaTime:)` | |
| 20 | +| `MotionMode` | `.paddle` \| `.pointer` \| `.gesture` | |
| 21 | +| `TrikiInputAdapter` | App-only wrapper with calibration UI; forwards to `MotionSDK` | |
| 22 | +| `trikiUIScreen` | SwiftUI modifier for focus/hold navigation in menus | |
| 23 | +| `MotionInputProvider` | Typealias / protocol used by Triki UI for live `GameInput` | |
| 24 | + |
| 25 | +## Repository map (read these paths) |
| 26 | + |
| 27 | +```text |
| 28 | +VeltoKit/ |
| 29 | + MotionSDK.swift # Public API — start here for SDK questions |
| 30 | + MotionEngine.swift # Per-frame processing, modes, calibration |
| 31 | + GameInput.swift # Output contract — start here for game logic |
| 32 | + MotionConfig.swift # Presets per MotionMode |
| 33 | + BLE/BLEManager.swift # Scan, connect, notify |
| 34 | + BLEGyroParser.swift # Packet parsing |
| 35 | +app/ |
| 36 | + gametriki.xcodeproj |
| 37 | + Platform/TrikiInputAdapter.swift # Optional adapter (sample app) |
| 38 | + Engine/GameManager.swift # Applies MotionMode per game |
| 39 | + Engine/GameEngine.swift |
| 40 | + Games/PongGame.swift # .paddle |
| 41 | + Games/DartGame.swift # .pointer + throw |
| 42 | + Games/BowlingGame.swift # .gesture |
| 43 | + Games/QuizGame.swift # .paddle |
| 44 | + UI/TrikiUI/ # Navigation chrome (not in VeltoKit target) |
| 45 | +website/docs/ # Docusaurus source (English) |
| 46 | +website/static/skills/ # Downloadable Cursor/Claude prompts |
| 47 | +``` |
| 48 | + |
| 49 | +## Data flow (ground truth) |
| 50 | + |
| 51 | +```text |
| 52 | +BLE notify bytes |
| 53 | + → MotionSDK.enqueueBLE (or BLEManager inside connect()) |
| 54 | + → BLEGyroParser / ButtonDetector |
| 55 | + → MotionEngine.updateFrame(deltaTime:) |
| 56 | + → MotionSDK copies into GameInput |
| 57 | + → Game.update(input:deltaTime:) OR Triki UI reads live GameInput |
| 58 | +``` |
| 59 | + |
| 60 | +Preferred integration after `connect()`: |
| 61 | + |
| 62 | +```swift |
| 63 | +let input = motion.pollInput(deltaTime: dt) |
| 64 | +``` |
| 65 | + |
| 66 | +Manual BLE ownership: |
| 67 | + |
| 68 | +```swift |
| 69 | +motion.enqueueBLE(bytes) |
| 70 | +motion.updateFrame(deltaTime: dt) |
| 71 | +let input = motion.input |
| 72 | +``` |
| 73 | + |
| 74 | +## GameInput — fields games actually use |
| 75 | + |
| 76 | +| Field | Type | When it matters | |
| 77 | +|-------|------|-----------------| |
| 78 | +| `posX`, `posY` | `Double` | Aim / paddle position (~0…1, center ≈ 0.5) | |
| 79 | +| `primaryAction` | `Bool` | Button click this frame | |
| 80 | +| `shotTriggered` | `Bool` | Gesture throw edge (Dart, Bowling) | |
| 81 | +| `throwPower` | `Double` | 0…1 when `shotTriggered` | |
| 82 | +| `gesturePrimed` | `Bool` | Pull-back before throw (UI) | |
| 83 | +| `pointerDirection` | enum | Pointer mode sectors | |
| 84 | +| `didShoot` | computed | `primaryAction \|\| shotTriggered` | |
| 85 | +| `tiltX`, `tiltY`, `deltaX`, `deltaY` | `Double` | Debug / HUD | |
| 86 | +| `sensors` | `TrikiSensors` | Filled mainly by app `MotionParser`, not core SDK | |
| 87 | + |
| 88 | +Full reference: `website/docs/sdk/game-input.md` and `VeltoKit/GameInput.swift`. |
| 89 | + |
| 90 | +## MotionMode → sample games |
| 91 | + |
| 92 | +| Mode | Games | Main inputs | |
| 93 | +|------|-------|-------------| |
| 94 | +| `.paddle` | Pong, Quiz | `posX`, `primaryAction` / `didShoot` | |
| 95 | +| `.pointer` | Dart | `posX`, `posY`, `shotTriggered`, `sensors` | |
| 96 | +| `.gesture` | Bowling | `posX`, `shotTriggered`, `throwPower` | |
| 97 | + |
| 98 | +Mode setup in app: `app/Engine/GameManager.swift`. Per-game docs: `website/docs/examples/*.md`. |
| 99 | + |
| 100 | +## Which docs to open (in repo) |
| 101 | + |
| 102 | +| Task | Read first | |
| 103 | +|------|------------| |
| 104 | +| Integrate SDK in a new app | `website/docs/quick-start.md`, `sdk/motion-sdk.md`, `sdk/game-input.md` | |
| 105 | +| BLE packets / debugging | `sdk/ble-integration.md`, `VeltoKit/BLE/` | |
| 106 | +| Change gesture / throw | `sdk/gestures.md`, `VeltoKit/GestureDetector.swift` | |
| 107 | +| Triki menus / focus | `sdk/triki-ui.md`, `app/UI/TrikiUI/` | |
| 108 | +| Calibrate cap + simple menu (Quiz-style) | `sdk/triki-ui.md` (§ calibration), `app/UI/Quiz/QuizFlowView.swift`, `TrikiCalibrationView.swift` | |
| 109 | +| Copy a game pattern | `website/docs/examples/pong.md` (etc.) + matching `app/Games/*.swift` | |
| 110 | +| AI workflow / skills | `website/docs/ai-context.mdx`, `website/docs/for-cursor-claude.mdx` | |
| 111 | + |
| 112 | +Website paths map 1:1: `website/docs/sdk/overview.md` → `/docs/sdk/overview` on the site. |
| 113 | + |
| 114 | +## Rules when editing |
| 115 | + |
| 116 | +1. **Scope**: SDK changes → `VeltoKit/` only unless app integration is requested. Do not move BLE into games. |
| 117 | +2. **Stable API**: Do not rename public symbols unless asked. Prefer minimal diffs. |
| 118 | +3. **Single output type**: Games must not depend on raw `Data` BLE in game files. |
| 119 | +4. **Docs**: Behavior change → update `website/docs/` and Swift `///` on touched APIs. |
| 120 | +5. **Swift comments**: Existing Polish `///` in VeltoKit is OK; new public API docs can be English or Polish — stay consistent within the file you touch. |
| 121 | +6. **No fake APIs**: If unsure, read `MotionSDK.swift` and call sites in `app/Games/`. |
| 122 | + |
| 123 | +## Common AI mistakes in this repo |
| 124 | + |
| 125 | +- Treating **gametriki** as a separate framework from **VeltoKit**. |
| 126 | +- Using marketing names for hardware instead of “generic BLE cap” / packet docs. |
| 127 | +- Editing `posX` mapping in games without checking `MotionMode` and `MotionConfig.preset`. |
| 128 | +- Confusing **Triki UI** (SwiftUI navigation) with **GameInput** (per-frame state). |
| 129 | +- Linking to `/skills/...` as Docusaurus routes — they are static files under `website/static/skills/`. |
| 130 | +- Assuming Algolia search — docs use **local search** (navbar, `⌘K` / `Ctrl+K`). |
| 131 | + |
| 132 | +## Validation |
| 133 | + |
| 134 | +- SDK-only logic: build **VeltoKit** scheme in Xcode or SwiftPM. |
| 135 | +- App + BLE: scheme **gametriki** on a physical iPhone. |
| 136 | +- Docs site: `cd website && npm run build`. |
0 commit comments