# 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.