# Bullet Script Graph Editor Plan

## Goals
- Create an editor plugin in GDScript using `GraphEdit` and `GraphNode` for visual authoring of bullet scripts.
- Support opening from `BossScript`, `BossPhase`, `BulletScript3D`, or `BulletScript`.
- Visualize parent/child pattern relationships as linked graph nodes.
- Keep legacy `BossPhase.Patterns` intact to avoid breaking existing compositions.
- Introduce `BossPhase -> BulletScript3D` for flexible composition.
- Persist graph layout metadata so graph positions remain stable across sessions.

## Existing System Summary
- `BossScript` contains phases: `Scripts/Resources/ScriptableBullets/BossScript.cs`.
- `BossPhase` currently executes legacy `Patterns` (`Array<AttackPattern>`): `Scripts/Resources/BossPhase.cs`.
- `BulletScript3D` and `BulletScript` are standalone pattern containers:
  - `Scripts/Resources/BulletScripts/BulletScript3D.cs`
  - `Scripts/Resources/BulletScript.cs`
- Pattern composition already exists with:
  - Sequential group: `Scripts/Resources/PatternGroup.cs`
  - Parallel group: `Scripts/Resources/ScriptableBullets/ParallelPatternGroup.cs`

## Non-Breaking Runtime Changes
1. Add `[Export] public BulletScript3D BulletScript3D;` to `BossPhase`.
2. Keep `Patterns` unchanged and mark as legacy with a TODO comment.
3. In `BossPhase.Start` and `BossPhase.UpdatePhase`, prioritize `BulletScript3D` execution when assigned.
4. Fall back to legacy `Patterns` path when `BulletScript3D` is not assigned.
5. Add null/empty guards for robust editor/runtime behavior.

## Plugin Architecture
- New addon: `addons/bullet_script_graph_editor/`
- Main files:
  - `plugin.cfg`
  - `plugin.gd` (`EditorPlugin` entry)
  - `inspector_plugin.gd` (open-in-graph button in inspector)
  - `ui/graph_editor_dock.tscn`
  - `ui/graph_editor_dock.gd`
  - `model/graph_adapter.gd`

### Entry Points
- Bottom dock panel for direct resource picking/opening.
- Inspector button for fast open from selected resource.

### Graph Mapping Rules
- `BossScript` -> phase chain nodes.
- `BossPhase` ->
  - legacy pattern chain lane from `Patterns`
  - optional linked `BulletScript3D` lane.
- `BulletScript3D` / `BulletScript` -> ordered pattern chain.
- `PatternGroup` and `ParallelPatternGroup` -> composite nodes with child links.

### Persistence
- Store node graph position metadata on resources using editor metadata keys.
- Use stable node IDs to restore positions across reopen.

## Validation Checklist
1. Enable plugin and confirm dock is visible.
2. Open `Resources/BossPhases/Rumia_Boss_Script_3D.tres` and verify phase/pattern graph.
3. Open `Resources/BulletScripts/Danmaku_Room_1.tres` and verify pattern chain graph.
4. Save, reopen, and verify node positions persist.
5. Run build:
   - `dotnet build k:/godot/cirno/Cirno.csproj -c Debug -v normal -p:GodotTargetPlatform=windows`

## Out-of-Scope for Initial Cut
- Removing legacy `Patterns`.
- Full simulation/debug playback inside the graph UI.
- Automatic bulk migration of all existing resources.