# AeThex Kinect Module

Native AeThex Engine module for Kinect skeleton tracking and gesture detection.

## Features

- **KinectBridge**: Main node that receives OSC data from Python bridge
- **KinectSkeleton**: 20-joint skeleton data with tracking states
- **KinectGestureDetector**: Detects arms raised, push, swipe gestures

## Setup

### 1. Build AeThex Engine with this module

```bash
cd engine
scons platform=windows target=editor
```

The module is automatically included via the modules system.

### 2. Run the Python Kinect Bridge

```bash
cd c:\Dev\aethex-kinect-bridge\python_bridge
py kinect_bridge.py --simulate   # Without hardware
py kinect_bridge.py              # With Kinect v1
```

### 3. Create a scene with KinectBridge

```gdscript
extends Node3D

var kinect: KinectBridge

func _ready():
    kinect = KinectBridge.new()
    add_child(kinect)
    
    kinect.skeleton_detected.connect(_on_skeleton_detected)
    kinect.gesture_received.connect(_on_gesture)
    kinect.identity_forged.connect(_on_identity_forged)
    
    kinect.set_mode(KinectBridge.MODE_FOUNDRY)
    kinect.start(9000)

func _on_skeleton_detected(detected: bool):
    print("Skeleton: ", "DETECTED" if detected else "LOST")

func _on_gesture(type: String, params: Dictionary):
    print("Gesture: %s %s" % [type, params])

func _on_identity_forged(signature: Dictionary):
    print("🔥 FORGED: ", signature)
```

## API Reference

### KinectBridge

| Method | Description |
|--------|-------------|
| `start(port: int)` | Start listening for OSC on port (default 9000) |
| `stop()` | Stop the bridge |
| `set_mode(mode)` | MODE_FOUNDRY or MODE_GAMEFORGE |
| `get_skeleton()` | Returns KinectSkeleton |
| `get_joint_position(id)` | Get Vector3 position of joint |

### Signals

| Signal | Parameters | Description |
|--------|-----------|-------------|
| `skeleton_detected` | `detected: bool` | Skeleton tracking state changed |
| `joint_updated` | `id, pos, state` | Joint position updated |
| `gesture_received` | `type, params` | Gesture detected |
| `identity_forged` | `signature` | Foundry identity forged |
| `forge_progress` | `progress: float` | Arms raised progress (0-1) |

### KinectSkeleton.JointID

```
JOINT_HIP_CENTER = 0
JOINT_SPINE = 1
JOINT_SHOULDER_CENTER = 2
JOINT_HEAD = 3
JOINT_SHOULDER_LEFT = 4
JOINT_ELBOW_LEFT = 5
JOINT_WRIST_LEFT = 6
JOINT_HAND_LEFT = 7
JOINT_SHOULDER_RIGHT = 8
JOINT_ELBOW_RIGHT = 9
JOINT_WRIST_RIGHT = 10
JOINT_HAND_RIGHT = 11
JOINT_HIP_LEFT = 12
JOINT_KNEE_LEFT = 13
JOINT_ANKLE_LEFT = 14
JOINT_FOOT_LEFT = 15
JOINT_HIP_RIGHT = 16
JOINT_KNEE_RIGHT = 17
JOINT_ANKLE_RIGHT = 18
JOINT_FOOT_RIGHT = 19
```

## Foundry Onboarding

The Foundry mode generates unique identity signatures based on:
- Movement patterns during onboarding
- Hand positions at forge moment
- Variance and rhythm of movement

Identity data includes:
- `seed`: Deterministic seed for generative visuals
- `color_hue`: Base color (0-1)
- `particle_density`: Density modifier
- `movement_signature`: Motion characteristic

## GameForge Spatial IDE

In GameForge mode, gestures map to code navigation:

| Gesture | Action |
|---------|--------|
| Push (forward) | Drill into code/function |
| Swipe left/right | Close tab / navigate |
| Swipe up/down | Scroll through code |
| Both arms raised | Run code |