Fix project structure

flutter-scene-spike/.claude/skills/flutter_scene-kit/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: flutter_scene-kit
+version: 3
+description: Build interactive 3D gameplay, character controllers, camera rigs, dynamic day/night cycles, water surfaces, audio, pooling, and debug overlays in flutter_scene. Use when creating game mechanics, camera controls, NPC behaviors, atmospheric environments, or diagnostic HUDs.
+---
+
+# Gameplay, camera, and atmosphere kit in flutter_scene
+
+Flutter Scene provides high-level gameplay components and ergonomic building blocks in `package:flutter_scene/kit.dart` so games and interactive experiences do not need to re-implement standard mechanics from scratch.
+
+When choosing components, consider existing engine alternatives:
+- For physics-driven character navigation with collider capsules, wall sliding, and autostep, use `KinematicCharacterController` from `package:flutter_scene/physics.dart`.
+- For interactive mouse/touch orbit cameras with inertia, use `OrbitCameraController` or `FollowCameraController`.
+- For framing a standalone `PerspectiveCamera`, use `PerspectiveCamera.framing`. Use `BoundsFraming` when computing a transform for a `NodeCamera` mounted in the scene graph.
+
+## Imports
+
+```dart
+import 'package:flutter_scene/scene.dart';
+import 'package:flutter_scene/kit.dart';
+import 'package:vector_math/vector_math.dart' as vm;
+```
+
+## Camera rigs and smoothing
+
+### SpringArmComponent
+
+`SpringArmComponent` attaches to a target character node and mounts a camera node at the arm's socket. It casts rays against the scene hierarchy to prevent geometry clipping, smoothly pulling the camera inward when colliding with walls.
+
+Note on offsets: `targetOffset` is applied in world space from the character node's origin, and `socketOffset` acts in the camera socket's local plane along X (right) and Y (up).
+
+```dart
+final characterNode = Node();
+final cameraNode = Node();
+final cameraArm = SpringArmComponent(
+  targetLength: 5.0,
+  targetOffset: vm.Vector3(0, 1.6, 0), // Eye height
+  socketOffset: vm.Vector3(0.5, 0, 0), // Over-the-shoulder
+  enablePositionLag: true,
+  positionLagSpeed: 8.0,
+  cameraNode: cameraNode,
+);
+
+characterNode.addComponent(cameraArm);
+scene.root.add(characterNode);
+scene.root.add(cameraNode);
+```
+
+### CameraShake
+
+`CameraShake` implements a trauma-decay model driven by deterministic simplex noise for organic multi-axis camera shake (explosions, footsteps, hits).
+
+```dart
+final shake = CameraShake(decayRate: 1.2, frequency: 25.0);
+
+// Add trauma on hit
+shake.addTrauma(0.6);
+
+// Inside game loop
+final offset = shake.update(deltaSeconds);
+cameraNode.localTransform = baseTransform * offset.toMatrix4();
+```
+
+## Character movement and steering
+
+### ThirdPersonControllerComponent
+
+`ThirdPersonControllerComponent` handles kinematic movement, sprint multipliers, turn smoothing, ground snapping with raycasts, slope sliding, coyote time, and buffered jumps. Input expects `+Y` as forward in 3D.
+
+```dart
+final playerNode = Node();
+final controller = ThirdPersonControllerComponent(
+  walkSpeed: 4.5,
+  runMultiplier: 1.8,
+  jumpVelocity: 7.0,
+  groundPlaneHeight: 0.0, // Optional fallback floor
+);
+playerNode.addComponent(controller);
+
+// When using VirtualJoystick (where up is -Y in screen space), invert Y:
+// controller.setMoveInput(vm.Vector2(joystickDir.x, -joystickDir.y), isRunning: isSprinting);
+if (jumpPressed) controller.jump();
+```
+
+### Autonomous Steering Behaviors
+
+`Steering` provides math helpers for NPC navigation, flocking, and crowd dynamics.
+
+```dart
+// Seek target
+final seekForce = Steering.seek(npcPos, npcVel, targetPos, maxSpeed: 4.0);
+
+// Arrive smoothly
+final arriveForce = Steering.arrive(npcPos, npcVel, targetPos, slowingRadius: 3.0);
+
+// Flocking separation
+final sepForce = Steering.separation(npcPos, npcVel, neighborPositions, desiredDistance: 1.5);
+```
+
+## Dynamic environments and atmosphere
+
+### DayNightCycleComponent
+
+`DayNightCycleComponent` moves the sun along a realistic solar arc given latitude and time of day, evaluating sun colors, intensities, and ambient lighting transitions.
+
+```dart
+final sunLight = DirectionalLight();
+final sunNode = Node()..addComponent(DirectionalLightComponent(sunLight));
+scene.root.add(sunNode);
+
+final skyCycle = DayNightCycleComponent(
+  timeOfDay: 14.5, // 2:30 PM
+  timeSpeed: 0.1,  // Progress 0.1 hours per second
+  latitude: 34.0,
+  sunLightNode: sunNode,
+);
+scene.root.addComponent(skyCycle);
+```
+
+### WaterSurfaceComponent
+
+`WaterSurfaceComponent` evaluates multi-harmonic Gerstner trochoidal waves for water surfaces and floating buoyancy queries.
+
+```dart
+final water = WaterSurfaceComponent();
+final surface = water.evaluateAt(vm.Vector2(playerPos.x, playerPos.z));
+final waterHeight = surface.displacement.y;
+final waterNormal = surface.normal;
+```
+
+## Immediate-mode debug visualization
+
+`DebugDraw` provides static immediate-mode line, ray, box, sphere, and axis drawing utilities for physics debugging and AI visualizers.
+
+```dart
+DebugDraw.line(startPos, endPos, color: vm.Vector4(1, 0, 0, 1));
+DebugDraw.box(aabb, color: vm.Vector4(0, 1, 0, 1));
+DebugDraw.sphere(center, 1.0, color: vm.Vector4(0, 0, 1, 1));
+DebugDraw.axes(node.globalTransform, size: 2.0);
+
+// Render debug lines
+final debugMesh = DebugDraw.flushMesh();
+if (debugMesh != null) {
+  debugNode.mesh = Mesh(debugMesh, UnlitMaterial());
+}
+```