cirnogodot/docs/bullet-script-graph-editor-plan.md

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.