Instruction file imported from DMINATOR/supreme-system (.github/instructions/godot-scripting.instructions.md). Copyright stays with the author.

Godot Scripting Conventions

Node Scripts

• All Godot node scripts must be partial class
• Do not use namespaces — the Godot autoload/scene system expects top-level types
• Don't put game logic directly in node scripts — delegate to SupremeEngine
• Never use generic base classes for Godot node scripts — Godot 4's C# script registry cannot handle open generic types (e.g. class Foo<T> : Node) and will throw a duplicate-key ArgumentException when reloading the assembly; if you need a typed base, use a non-generic abstract base class and cast at the call site in the concrete subclass

Logging

• Use GD.Print for logging — never Console.WriteLine

_Ready Structure

• _Ready calls LoadNodes() and then PrepareNodes() — omit PrepareNodes() only if the scene has no signal wiring or state initialization
• LoadNodes(): every GetNode<T>(...) assignment goes here and nowhere else
• PrepareNodes(): signal wiring, initial state setup, and any calls that rely on loaded nodes go here
• Both are private void methods placed in the private methods section of the class

Setup Methods

• Scenes that require external data before display must expose a Setup(...) method
• Never call Setup before AddChild — _Ready must have already fired so that LoadNodes has run and nodes are available; Setup then populates them directly
• [Export] properties are the opposite — they must be set before AddChild so they are readable when _Ready fires; this is a different pattern from Setup() and the two must not be confused: [Export] values → before AddChild; Setup() calls → after AddChild
• For Util helpers that instantiate scenes, the helper must call parent.AddChild(scene) first, then scene.Setup(...) — this guarantees _Ready has fired by the time Setup runs
• Do not use null checks on node fields inside Setup to detect whether _Ready has fired; that is a design flaw — fix the call order instead

Node References

• Every GetNode<T>(...) call must be stored in a private field in LoadNodes — never chain .Pressed, .Text, etc. directly off a GetNode call
• This applies to both autoloads and scene-tree nodes; storing in a field makes null-reference issues easy to spot and debug
• Autoloads are retrieved using path constants from AutoloadPath — never hard-code "/root/..." strings inline
  • Current autoloads: AutoloadPath.SceneManager, AutoloadPath.SaveManager, AutoloadPath.WorldManager
  • When a new autoload is added, add its constant to Managers/AutoloadPath.cs first

Scene Files (.tscn) and Resources (.tres)

• Every .cs script attached to a scene or resource has a matching .cs.uid file generated by Godot
• Never invent a UID — Godot UIDs are base62-encoded random values; any manually written value will be rejected at runtime with an "invalid UID" warning
• This applies equally to .tscn scene files, .tres resource files, and .cs.uid script UID files — do not write uid= values in any of them manually
• When creating a .tscn or .tres manually for a script that already has a .cs.uid file: read the .cs.uid file and copy the exact value into the [ext_resource] line
• When creating a .tscn or .tres manually for a new script (no .cs.uid exists yet): omit the uid= attribute from [ext_resource] entirely — Godot will use the path as a fallback and generate the .cs.uid and assign the UID on next project load
• Never create .cs.uid files manually — always let Godot generate them
• Never use a .cs.uid value as the uid= for a PackedScene ext_resource — .cs.uid files hold script UIDs, not scene UIDs; scene UIDs live in the uid= attribute on the [gd_scene] header line of the .tscn file itself; if the .tscn was created manually and has no header UID, omit uid= from the [ext_resource] reference entirely
• UID quick-reference when creating a .tscn manually:

  Situation	What to write
  [gd_scene] header of the new file	Omit uid= — Godot assigns on load
  Script [ext_resource] — .cs.uid exists	Copy exact value from .cs.uid file
  Script [ext_resource] — no .cs.uid yet	Omit uid= entirely
  PackedScene [ext_resource] (sub-scene)	Omit uid= — never copy a .cs.uid value here

• When embedding a sub-scene inside a .tscn, use instance=ExtResource("...") on the node line — never combine type= and instance= on the same node; type= overrides instance= and the script won't be attached:

  [node name="CardScene" parent="VBoxContainer" instance=ExtResource("2_card")]
  

• Scene/Node names in the editor: PascalCase
• To change the entry-point scene, update run/main_scene in project.godot

Prefab Scenes

• Prefab scenes are reusable scene fragments that are instantiated programmatically and embedded inside other scenes — they are not navigated to via SceneManager
• They live in Scenes/Prefabs/ and their filenames end with PrefabScene (e.g. CardPrefabScene.tscn, CardOfferPrefabScene.tscn)
• Their C# class names also end with PrefabScene (e.g. CardPrefabScene, CardOfferPrefabScene)
• Their path constants in SceneManager end with PrefabScene — no GoTo method is added for them
• They are always instantiated via a PrefabFactory-style helper in Util/, never directly from a scene script
• Never call Setup before AddChild on a prefab scene — _Ready (and therefore LoadNodes) must fire first; the helper is responsible for the correct order
• When removing a dynamically instantiated prefab scene, unsubscribe from all C# events before calling QueueFree() to prevent dangling references

Navigation Buttons

• Always use SceneButtonPrefabScene for any button that navigates to another scene — embed it as an instance=ExtResource(...) in the .tscn and set its [Export] TargetScene property inline; never wire a plain Button to SceneManager.GoTo in C# code
• The correct .tscn pattern:

  [ext_resource type="PackedScene" path="res://Scenes/Prefabs/Control/SceneButtonPrefabScene.tscn" id="N_id"]
  ...
  [node name="BackButton" parent="Hud" instance=ExtResource("N_id")]
  text = "Back"
  TargetScene = 9
  

  TargetScene is a GameScene enum export; Godot serializes enum exports as integers in .tscn files (e.g. 9 for RegionMapScene) — see SceneManager.GameScene for the full list of values
• Before adding any navigation button, check Scenes/Prefabs/Control/ for the right prefab — do not invent a new approach

Scene Structure — Static vs Dynamic

• All static controls a scene needs must be declared in its .tscn file with sensible default values set inline — never construct them in C#
• Never call new Label(), new Button(), new HBoxContainer(), or any other bare Godot control constructor in a scene script — these nodes have no .tscn backing, cannot be themed, inspected, or resized in the editor
• Every element that must be added dynamically at runtime must be a prefab scene, instantiated through PrefabFactory — if no matching factory method exists, add one
• This rule applies to structural layout containers too — a VBoxContainer wrapping companion tabs is not exempt; it must also be a prefab, not new VBoxContainer()
• The one-sentence test: if a control cannot be pointed to in a .tscn file or its prefab's .tscn, it should not exist

Asset Binding — Prefer Exported Fields Over Hardcoded Paths

• Never hardcode res:// resource paths inside C# scripts — use [Export] fields and bind the resources in the .tscn file instead
• This keeps resource references deterministic and editor-visible: the scene file is the single source of truth for which assets are used
• When a sub-component needs to select from a fixed set of assets based on data (e.g. a header image per rarity), extract it into its own prefab scene with one [Export] field per variant, bind all variants in that scene's .tscn, and expose a Setup(...) method that picks the correct one:

  // CardPrefabHeaderScene.cs
  [Export] public Texture2D CommonHeader { get; set; }
  [Export] public Texture2D RareHeader   { get; set; }
  
  public void Setup(CardRarity rarity)
  {
      Texture = rarity switch { CardRarity.Common => CommonHeader, _ => RareHeader };
  }

• The parent scene embeds the sub-scene via instance=ExtResource(...) and calls Setup(...) from its own Setup method — no path strings appear anywhere in C#

Util

• godot/supreme-godot/Util/ contains shared Godot-layer helpers — check here before writing one-off boilerplate in a scene script
• Current helpers:
  • DialogHelper.ShowConfirm(Node parent, string message, Action onConfirmed) — shows a ConfirmationDialog, wires confirm/cancel, and calls QueueFree automatically
  • DialogHelper.ShowError(Node parent, string message) — logs via GD.PushError and shows an AcceptDialog
  • PrefabFactory.CreateCardSlotScenes(Node parent, ICardCollection collection, bool enableDragAndDrop, Action<Card> onCardPressed) — creates all card slot scenes for every slot in collection, enables drag-and-drop if requested, and wires CardPressed to onCardPressed on each; use this instead of a manual loop
  • PrefabFactory.CreateBagScene(Node parent, ICardCollection bag) — instantiates CardCollectionPrefabScene.tscn, adds it to parent, calls Setup(bag, "Bag"), and returns the ready node
  • PrefabFactory.CreateCompanionDeckScene(Node parent, ICardCollection deck) — instantiates CardCollectionPrefabScene.tscn, adds it to parent, calls Setup(deck, "Deck"), and returns the ready node; the caller resolves the deck from WorldManager
  • PrefabFactory.CreateCatalogueScene(Node parent) — instantiates CardCollectionPrefabScene.tscn, loads CardTemplateLibrary, builds a CardCollection from all templates, calls Setup with D&D disabled, and returns the ready node; exposes CardSelected event via CardCollectionPrefabScene
  • PrefabFactory.CreateCardTemplateRowScene(Node parent, string displayText) — instantiates CardTemplateRowPrefabScene.tscn, adds it to parent, calls Setup(displayText), and returns the ready node; exposes CreatePressed event for the caller to subscribe to
  • PrefabFactory.CreateCardTemplateRowScene(Node parent, string displayText, Action onCreate) — same as above but also wires CreatePressed in one call; prefer this overload when the callback is known at creation time
  • PrefabFactory.CreateSaveSlotRowScene(Node parent, SlotSummary summary) — instantiates SaveSlotRowPrefabScene.tscn, adds it to parent, calls Setup(summary), and returns the ready node; exposes NewPressed, LoadPressed, and DeletePressed events
  • PrefabFactory.CreateSaveSlotRowScene(Node parent, SlotSummary summary, Action onNew, Action onLoad, Action onDelete) — same as above but also wires all three events in one call; prefer this overload when the callbacks are known at creation time
  • PrefabFactory.CreateCompanionMemberTabScene(Node parent, string companionId) — instantiates CompanionMemberTabPrefabScene.tscn, sets CompanionId before AddChild, adds it to parent, and returns the ready node; the scene self-loads its deck and equipment from WorldManager in _Ready
  • PrefabFactory.CreateCompanionEquipmentScene(Node parent, string companionId) — instantiates CompanionEquipmentSlotsPrefabScene.tscn scoped to a companion
  • PrefabFactory.CreateRegionCellScene(Node parent, Region region, Action<Region> onSelected) — instantiates RegionCellPrefabScene.tscn, adds it to parent, calls Setup(region), wires RegionSelected to onSelected, and returns the ready node
  • PrefabFactory.CreateLocationRowScene(Node parent, RegionLocation location) — instantiates LocationRowPrefabScene.tscn, adds it to parent, calls Setup(location), and returns the ready node
  • RegionDetailPrefabScene — static embed (not factory-instantiated); embedded via instance=ExtResource(...) in WorldMapScene.tscn; call Setup(region) to populate it; exposes public event Action ClosePressed
• All prefab instantiation helpers live in PrefabFactory — do not create separate helper classes per prefab type
• Self-loading prefab scenes use [Export] properties to identify their data source; set these properties on the instantiated node before calling AddChild so they are available when _Ready fires — this is intentionally opposite to Setup(), which must always be called after AddChild
• Static prefab instances (non-companion) are embedded directly in the parent .tscn using instance=ExtResource(...) with their [Export] values set inline — no runtime instantiation needed for fixed slots
• InventoryPrefabScene is the prefab that owns the member TabContainer; it embeds static Player tab sub-scenes in its .tscn and adds dynamic companion tabs in PrepareNodes — embed it in parent scenes via instance=ExtResource(...) rather than instantiating it in code
• When adding new reusable Godot UI/node utilities, place them in Util/ as static classes
• When a helper needs a scene path, reference the public const on SceneManager — do not declare a duplicate path string in the helper

Signals vs C# Events

• Use [Signal] delegates only when the event needs to cross the GDScript boundary or be visible in the Godot editor
• [Signal] delegates only support Godot Variant-compatible types (built-in Godot types, GodotObject subclasses) — never use pure C# types like Card, Bag, etc. as signal parameters
• When communicating between C#-only nodes with pure C# payloads, use a standard C# event instead:

  public event Action<Card> Accepted;
  public event Action Declined;

• Never use a plain Action<T> field — always declare public event Action<T> so callers use +=/-= and cannot overwrite existing subscribers with =
• Wire C# events in PrepareNodes the same way as Godot signals

Error Handling

• Never silently swallow missing state — use GD.PushError to make programming mistakes visible in the Godot debugger

• For optional/recoverable failures (e.g. missing save data): call GD.PushError with a descriptive message, then return early

• For missing required pre-conditions set before _Ready (e.g. Setup() not called): use GD.PushError and return — never silently continue with null state

• Do not use C# exceptions for Godot-layer errors; GD.PushError is the idiomatic equivalent

• All scene transitions go through SceneManager — do not call GetTree().ChangeSceneToFile(...) directly from node scripts

• Navigation-only buttons (whose sole purpose is to navigate to a scene) must use SceneButtonPrefabScene — embed instance=ExtResource(...) in the .tscn with text and TargetScene set inline; do NOT add a private Button field, GetNode, or _sceneManager.GoTo* wiring in C#

  • SceneButtonPrefabScene lives at res://Scenes/Prefabs/Control/SceneButtonPrefabScene.tscn
  • TargetScene is a GameScene enum export — set it to the integer value of the enum in the .tscn (e.g. TargetScene = 0 for GameScene.MainMenu); the GameScene enum is defined inside SceneManager and lists all navigable scenes in order
  • Each GameScene value is decorated with [ScenePath("res://...")] — SceneManager.GoTo(GameScene) resolves the path via reflection; no switch statement is needed
  • When a new navigable scene is added, add its value to GameScene with a [ScenePath(...)] attribute and a GoTo<SceneName>() convenience method to SceneManager
  • Only use a plain Button + _sceneManager.GoTo* when navigation is conditional (e.g. guarded by a load result or confirmation dialog)

• When a scene is created, renamed, or removed, always update all of the following without being asked:

  • SceneManager.cs: path constant and GoTo<SceneName>() method (add, rename, or remove)
  • DebugScene.tscn: SceneButtonPrefabScene instance node in VBoxContainer/TabContainer/Scenes, with text and TargetScene bound inline (add, rename, or remove)
  • DebugScene.cs: no C# changes needed for navigation buttons — handled entirely by the .tscn