diff --git a/rinkplanner/rinkplanner_definition_agent_guidelines.md b/rinkplanner/rinkplanner_definition_agent_guidelines.md index 08c59c1..6a1250d 100644 --- a/rinkplanner/rinkplanner_definition_agent_guidelines.md +++ b/rinkplanner/rinkplanner_definition_agent_guidelines.md @@ -1,96 +1,107 @@ -# Project Context: Rinkplanner +# Project Definition & AI Agent Guidelines: Rinkplanner -## 1. Project Overview -**Rinkplanner** is a 3D desktop application designed for visual planning, choreography, and timing of figure skating routines (specifically tailored to ISU Adult regulations and rules). It allows choreographers and skaters to map out elements on a 3D ice rink, sync them to music audio tracks, and visualize realistic movement paths and technical elements. +Specialized Choreography & Step Planning Software for ISU Adult Competitive Figure Skating --- -## 2. Technical Stack & Architecture +## 1. Executive Summary & Core Vision -- **Game Engine:** Godot 4.x (GDScript) -- **3D Creation & Asset Pipeline:** Blender 4.x -- **Rigging Solution:** Auto-Rig Pro (Blender) -- **Animation Workflow:** Video Rotoscoping / Motion Capture based on action-cam footage (e.g., DJI Osmo Action) recorded from rinkside/tribune setups. -- **Audio:** Multi-track / timed audio synchronization in Godot for element triggers. -- **Rules Engine:** ISU Adult Figure Skating Scale of Values (SOV) and element verification rules. +**Rinkplanner** is a purpose-built desktop and mobile application engineered for figure skating coaches, choreographers, and competitive adult skaters. The platform optimizes pattern construction, step sequence choreography, and time-space distribution across standard arena surface dimensions ($60\text{m} \times 30\text{m}$). + +The system is developed under a phased lifecycle: + +* **Phase 1 (MVP Focus):** A **2D "Digital Whiteboard"** engineered for touch-enabled Linux, Mobile, and Web runtimes. It offers rink-side tools to plot paths, enforce edge-encoding standards, handle complex pattern overlaps, and preview element execution rates. +* **Phase 2 (Future Extension):** A **3D Visualization and Presentation Layer** built with Godot 4 and Blender, using Non-Linear Animation (NLA) tracks to compose complete routines without requiring manual keyframe authoring by the coach. --- -## 3. Core Features & Data Structures +## 2. MVP Definition & Architecture (Phase 1) -### A. Ice Rink & Spatial System -- **Dimensions:** Standard ISU Rink ($60\text{m} \times 30\text{m}$). -- **Coordinate System:** - - Origin $(0,0,0)$ at the exact center of the ice rink surface. - - $X$-axis: Long axis ($-30\text{m}$ to $+30\text{m}$). - - $Z$-axis: Short axis ($-15\text{m}$ to $+15\text{m}$). - - $Y$-axis: Vertical height (Up = positive). +### A. Visual Encoding Specifications +To maintain clarity and align with figure skating pedagogy, the canvas enforces a strict visual grammar: -### B. Choreography Pathing System -- Path definition using 3D Bézier curves (`Path3D` / `PathFollow3D` in Godot). -- **Control points:** Position $(X, Y, Z)$, Speed/In/Out tangents, Edge Type (Inside/Outside, Forward/Backward). -- **Time Markers:** Syncing node positions on the curve with exact timestamps in seconds on the audio track. +| Category | Value / Property | Visual Encoding | Rendering Implementation | +| :--- | :--- | :--- | :--- | +| **Direction** | Forward (*Vorwärts*) | Solid Line | Standard vector stroke | +| **Direction** | Backward (*Rückwärts*) | Dashed Line | Dash pattern `[12, 6]` | +| **Edge Alignment** | Outside Edge (*Außenkante*) | Subdued Red | Primary stroke color (`#DC2626`) | +| **Edge Alignment** | Inside Edge (*Innenkante*) | Subdued Blue | Primary stroke color (`#2563EB`) | +| **Geometry** | Templates vs. Freehand | Arcs, lobes, freeform | Parametric Bézier curves & vector paths | -### C. ISU Adult Rules & Elements Data Structure -- Elements must follow ISU category codes (e.g., `1A` for Single Axel, `2S` for Double Salchow, `FCSp` for Flying Camel Spin, `ChSq1` for Choreo Step Sequence). -- Each element node contains: - - `element_id`: String (e.g., `"1A"`) - - `start_time`: Float (seconds) - - `duration`: Float (seconds) - - `execution_path_id`: NodePath - - `isu_category`: Enum (`JUMP`, `SPIN`, `STEP_SEQUENCE`, `TURNS`, `CONNECTIVE_SKATING`) - - `adult_level_validity`: Boolean check based on current ISU Adult Handbook rules. +### B. Canvas & Input Capabilities +* **Template-Based Geometry:** Standardized lobes, continuous three-turn arcs, bracket entry lines, and circle-eight segments ensure accurate technical tracking. +* **Freehand Notation:** Fast-input markup overlay for directional arrows, element markers, rotational notation, and target placements. +* **Resolution Isolation:** Vector-backed rendering pipeline preserving visual clarity across varying tablet and display resolutions. + +### C. Path Overlap Management ("Spaghetti-Problem") +Complex choreographies frequently cross the same ice zones, leading to visual clutter. Rinkplanner resolves this through structured sectioning: +* **Chronological Sectioning:** Routines are broken down into sequential time-slice blocks (e.g., *Section 1: Opening Entry*, *Section 2: Step Sequence*). +* **Ghosting Engine:** The active section retains 100% opacity with full editability. Prior and subsequent sections automatically dim to **20% opacity** as non-interactive reference layers. + +### D. Playback & Simulation Engine +* **Real-Time Interpolation:** A 2D pacing marker (dot) traverses the authored curves according to calibrated entry speeds and segment durations. +* **Playback Controls:** Granular Play, Pause, Scrubbing Timeline, Reset, and Playback Speed scales ($0.25\times$ to $2.0\times$). +* **Temporal Metadata:** Direct real-time audio playback is deferred in Phase 1. Routine duration, section timestamps, and tempo targets are tracked via metadata fields. + +### E. Export Pipeline +* Scalable Vector Graphics (SVG) / PDF Export for full-sheet printable session charts. +* High-resolution raster (PNG) export configured for mobile tablet handoff and off-ice review. --- -## 4. MCP Agent Guidelines & Tool Integration +## 3. Technology Stack & Toolchain -### A. General Coding Standards -1. **GDScript Standards:** - - Always use strong typing in GDScript (`var speed: float = 2.5`, `func calculate_element_time(start: float) -> void:`). - - Use signal-driven architecture for UI updates (`signal element_added(element_data)`). - - Keep logic separated: UI Layer -> Choreography Manager -> Physics/Path Interpolator. +### A. Core Infrastructure -2. **File & Folder Structure:** - ```text - res:// - ├── assets/ - │ ├── models/ # .blend / .gltf files (Rink, Skater, Rig) - │ ├── animations/ # .res / .gltf imported animation clips - │ └── audio/ # Music tracks - ├── core/ - │ ├── pathing/ # Curve interpolation & speed calculation - │ ├── isu/ # ISU Rules, SOV, and element data models - │ └── sync/ # Audio-to-time synchro engine - └── scenes/ - ├── rink/ # 3D Rink Environment - ├── skater/ # Skater model, ARP Rig, AnimationTree - └── ui/ # Timeline, element inspector, control panels - ``` +| Component | Technology | Target / Responsibility | +| :--- | :--- | :--- | +| **Runtime Engine** | Godot 4.x (GDScript) | 2D Canvas architecture, Node-based UI, vector renderer | +| **Target Platforms** | Linux, Web (Wasm), Mobile | Primary touch-first tablet and rink-side hardware | +| **3D Modeling & Rigging** | Blender 4.x & Auto-Rig Pro | Character kinematics, rink geometry (Phase 2) | +| **Motion Digitization** | Action-cam (DJI Osmo Action) | Rotoscoped real-ice captures modularized to NLA blocks (Phase 2) | +| **Knowledge & Rules Sync** | Markdown / JSON | Documentation, ISU rule tables, local-first data sync | + +### B. Model Context Protocol (MCP) Integrations +* **Godot MCP Server:** Enables autonomous LLM developer agents to query the runtime hierarchy, inspect UI node trees, execute headless GDScript unit tests, and implement resource refactorings. +* **Blender MCP Server (Phase 2):** Connects external AI toolchains to execute Python hooks in Blender, inspect armature bone maps, orchestrate NLA track exports, and automate `.glb`/`.gltf` compilation. --- -### B. Godot MCP Guidelines -When issuing commands via the **Godot MCP Server**: -- **Scene Manipulation:** Ensure node references use unique names (`%NodeName`) or absolute type-checked paths. -- **AnimationTree:** The skater uses an `AnimationTree` with a `StateNode` or `BlendTree` to transition smoothly between stroking, crossovers, turns, and jumps. -- **Real-time Path Update:** When updating Bézier handles dynamically, call `curve.clear_points()` and rebuild or use `set_point_position()` / `set_point_in()` / `set_point_out()` cleanly without breaking time-stamps. +## 4. Coding & Architecture Guidelines for AI Agents ---- +All automated contributions must conform to the following architectural rules: -### C. Blender MCP Guidelines (For Future Integration) -When connected to a **Blender MCP Server**: -- **Rigging Standard:** Target rig must match the **Auto-Rig Pro (ARP)** bone structure (specifically the Humanoid preset). -- **Export Presets:** - - Format: `GLTF / GLB` - - Mesh: Apply Modifiers, Include Armature. - - Animation: Export NLA Tracks / Actions cleanly named with prefix (e.g., `anim_jump_1A`, `anim_gliding_RFO`). - - Axis Orientations: $+Y$ Forward, $+Z$ Up (Godot compatible). -- **Rotoscope Setup:** Camera parameters must match action camera settings (e.g., 1080p/4K at 60fps, fixed focal length, wide-angle distortion correction turned on prior to tracking). +### 1. Strict Module Decoupling +Maintain complete structural isolation between the 2D Whiteboard model (curve computation, edge-state schemas, ghosting logic) and any Phase 2 3D rendering assemblies. The Phase 1 engine must run cleanly in lightweight 2D contexts without 3D node overhead. + +### 2. GDScript Typing Standards +All GDScript code must be strictly typed. Explicitly type all dynamic properties, parameters, and return types. Avoid dynamic untyped allocations. + +```gdscript +# Standard resource pattern for routine sections +class_name RoutineSection +extends Resource + +@export var section_id: String = "" +@export var sequence_order: int = 0 +@export var duration_seconds: float = 0.0 +@export var path_curve: Curve2D +@export var is_backward: bool = false +@export var is_outside_edge: bool = true +``` + +### 3. ISU Rule Data Structures +Structure all element definitions, levels of difficulty (Base, 1, 2, 3, 4), and feature criteria into explicit JSON schema definitions or native Godot Resource files (`.tres`). Avoid hardcoding element properties inside visualization controllers. + +### 4. Architectural Separation (MVC) +* **Model Layer:** Native Resource derivatives containing pure path, timing, and rule data. +* **View Layer:** `Node2D` / `Control` elements rendering canvas vectors and ghosted overlays. +* **Controller Layer:** Decoupled input handlers managing touch gestures, curve handles, and playback state machines. --- ## 5. Development Principles for AI Assistance -1. **Prioritize Performance:** Keep track interpolation optimized. Do not execute heavy curve recalculations inside `_process()` unless the curve is actively being edited by the user. -2. **Modular ISU Rules:** Keep the ISU rules set isolated in JSON or dedicated Resource files (`.tres`) so they can be updated annually without breaking application code. -3. **Respect User Voice & Design:** Maintain a clean, desktop-focused tool approach with dark-mode aesthetic, highly responsive timeline controls, and crisp 3D visualization. \ No newline at end of file + +1. **Prioritize Performance:** Keep vector rendering and curve interpolation lightweight. Recalculate Bézier handles only on edit events, not inside `_process()`. +2. **Modular ISU Rules:** Keep the ISU rules set isolated so annual rule updates (SOV changes) do not break pathing or canvas features. +3. **Touch-First UI:** Design all UI interactions with touch targets (min $48\text{px} \times 48\text{px}$) suitable for tablet screens used in rink-side cold environments. \ No newline at end of file