HapticSystem/AGENTS.md

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

# 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

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.