Add AGENTS.md 文件

2026-05-15 10:34:36 +08:00
parent 32be8f5887
commit 3cbc6f2c55
2 changed files with 130 additions and 0 deletions
@@ -0,0 +1,129 @@
+# 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.