130 lines
6.1 KiB
Markdown
130 lines
6.1 KiB
Markdown
# Project Instructions
|
|
|
|
This file provides context for AI assistants working on this project.
|
|
|
|
## Project Overview
|
|
|
|
**HapticSystem** is a Unity-based haptic feedback framework built on the Lofelt Nice Vibrations SDK. It provides a data-driven, cross-platform haptic playback system for iOS and Android.
|
|
|
|
## Project Type: Unity (C#)
|
|
|
|
- **Engine**: Unity (see `ProjectSettings/` for version)
|
|
- **Language**: C# (.NET Framework / Mono)
|
|
- **Solution**: `HapticSystem.sln`
|
|
|
|
## Architecture
|
|
|
|
### Layered Design
|
|
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ HapticInvoker (MonoBehaviour) │ ← Scene-level entry point
|
|
├─────────────────────────────────────────┤
|
|
│ HapticSystem (MonoBehaviour, │ ← Core singleton; dispatches by type
|
|
│ DontDestroyOnLoad) │
|
|
├──────────────────┬──────────────────────┤
|
|
│ Generated Layer │ Handwritten Core │
|
|
│ HapticObject.cs │ HapticSettings │
|
|
│ (auto-gen from │ (ScriptableObj) │
|
|
│ data table) │ IBinarySerializable │
|
|
├──────────────────┴──────────────────────┤
|
|
│ ResourceLoader │ ← Sync/async resource cache
|
|
├─────────────────────────────────────────┤
|
|
│ Lofelt Nice Vibrations SDK │ ← Native haptic engine
|
|
│ (Plugins/Android, iOS, macOS, Win) │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
### Key Namespaces
|
|
|
|
| Namespace | Purpose |
|
|
|-----------|---------|
|
|
| `OCES.Haptic` | Core haptic system, data models, binary serialization |
|
|
| `OCES` | Shared utilities (ResourceLoader) |
|
|
|
|
### Data Flow
|
|
|
|
1. **Data source**: `DataTables/HapticManagement.xlsx` — Excel table defining haptic objects
|
|
2. **Auto-generation**: Row data is serialized to binary (`.bytes`) and the `HapticObject.cs` model is generated
|
|
3. **Build artifact**: Binary files placed under `Assets/Resources/HapticData/`; `.haptic` files under `Assets/Resources/Haptics/`
|
|
4. **Runtime**: `HapticSystem.Awake()` loads `HapticObjectConfig` from Resources via `IBinarySerializable`, then dispatches `Play()` calls based on `HapticType`
|
|
|
|
### Haptic Types
|
|
|
|
| Type | Enum Value | Behavior |
|
|
|------|-----------|----------|
|
|
| `Preset` | 0 | Plays a built-in Lofelt preset (enum-mapped string) |
|
|
| `Emphasis` | 1 | Transient haptic with amplitude + frequency |
|
|
| `Constant` | 2 | Continuous haptic with amplitude + frequency + duration |
|
|
| `Advance` | 3 | Plays a `.haptic` file with fallback preset |
|
|
|
|
## Source Tree (relevant paths)
|
|
|
|
```
|
|
Assets/
|
|
├── Resources/
|
|
│ ├── HapticData/ # Binary config files (auto-generated from Excel)
|
|
│ └── Haptics/ # .haptic resource files (e.g., NVDice, NVHeartbeats)
|
|
├── Scenes/
|
|
│ └── HomeScene.unity # Demo scene with HapticInvoker
|
|
├── Scripts/OCES/Haptic/
|
|
│ ├── Generated/
|
|
│ │ └── HapticObject.cs # Auto-generated — DO NOT EDIT
|
|
│ ├── Handwritten/
|
|
│ │ ├── HapticSystem.cs # Core singleton: load config, dispatch Play
|
|
│ │ ├── HandwrittenDefinitions.cs # IBinarySerializable, HapticType enum, FileManager
|
|
│ │ ├── HapticSettings.cs # ScriptableObject: config + resource paths
|
|
│ │ └── Editor/
|
|
│ │ └── HapticSettingsProvider.cs # Project Settings integration
|
|
│ └── HapticInvoker.cs # Debug component: UI input → haptic playback
|
|
├── Scripts/OCES/
|
|
│ └── ResourceLoader.cs # Cached sync/async Resources loader
|
|
├── Settings/
|
|
│ └── HapticSettings.asset # HapticSettings instance (config paths)
|
|
└── Plugins/
|
|
├── Android/libs/LofeltHaptics.aar
|
|
├── iOS/LofeltHaptics.framework/
|
|
├── macOS/libnice_vibrations_editor_plugin.dylib
|
|
└── Windows/x64/nice_vibrations_editor_plugin.dll
|
|
```
|
|
|
|
## Build & Test Commands
|
|
|
|
```bash
|
|
# Build Android APK (output: Build/HapticSystemDemo.apk)
|
|
# Use Unity Build Settings or command-line:
|
|
# /Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/MacOS/Unity \
|
|
# -quit -batchmode -projectPath . -buildTarget Android \
|
|
# -executeMethod <BuildScript.Method>
|
|
|
|
# Build iOS Xcode project (output: Build/iOS/)
|
|
# Configured via Unity Build Settings → iOS → Build
|
|
```
|
|
|
|
<!-- Add specific Unity CLI build commands if a build script exists -->
|
|
|
|
## External Dependencies
|
|
|
|
- **Lofelt Nice Vibrations**: Cross-platform haptic SDK (native plugins for Android/iOS/macOS/Windows)
|
|
- Assembly Definition: `Assets/Scripts/Lofelt/NiceVibrations/Lofelt.NiceVibrations.asmdef`
|
|
|
|
## Guidelines
|
|
|
|
- **Do not edit `Assets/Scripts/OCES/Haptic/Generated/`** — these files are auto-generated from the data table
|
|
- Data-driven: add/modify haptic definitions in `DataTables/HapticManagement.xlsx`, then regenerate
|
|
- Follow existing naming conventions: PascalCase for public, camelCase for private fields, `m_` prefix for member fields
|
|
- `HapticSystem` is a singleton (DontDestroyOnLoad) — access via `HapticSystem.Instance`
|
|
- All haptic types implement `IBinarySerializable` for runtime data loading
|
|
- Keep changes focused and atomic
|
|
|
|
## Important Notes
|
|
|
|
- Haptic data files live under `Resources/` so they are included in builds and loadable via `Resources.Load`
|
|
- `.haptic` files are Lofelt's proprietary haptic clip format
|
|
- The `HapticInvoker` component in HomeScene is for debugging only — production should use `HapticSystem.Instance.Play(id)` directly
|
|
- Editor integration at: **Project Settings → Haptic Settings** (via `SettingsProvider`)
|
|
- `HapticSettings` asset location: `Assets/Settings/HapticSettings.asset`
|
|
|
|
### Version Control
|
|
This project uses Git. See `.gitignore` for excluded files.
|