Troubleshooting Guide

🛠 Troubleshooting Guide for Text Forge

This guide helps you diagnose and resolve common issues when developing or using modes in Text Forge.
It covers both mode-specific bugs and editor behaviors that may seem unexpected.

---

🧩 Mode Development Issues

❌ Syntax highlighting not working

Possible causes:

• syntax_highlighter not assigned in _initialize_mode()
• Regex pattern errors or missing delimiters

Fixes:

• Use print() to inspect highlighter assignment
• Test with minimal patterns first
• Check engine docs

---

❌ Panel UI not showing

Possible causes:

• panel not assigned or not added to the scene tree

Fixes:

• Ensure panel is a valid TextForgePanel node
• Try with panel = Factory.simple_panel() and panel.load_scene_as_child(scene_path)

---

❌ File not saving correctly

Possible causes:

• _string_to_buffer() or _buffer_to_string() not implemented
• Returned value is not a valid byte array or string

Fixes:

• Use print() to inspect buffer contents
• Ensure encoding is consistent (e.g. UTF-8)

---

❌ Code completion not triggering

Possible causes:

• _update_code_completion_options() logic have no effect

Fixes:

• Use Global.get_editor().add_code_completion_option() and try with static options

---

🧠 Editor Behaviors & Quirks

🔄 Folding not working as expected

Possible causes:

• Missing or incorrect comment_delimiters / string_delimiters in modes
• No structural markers (e.g. headers, braces)

Fixes:

• Define folding patterns in mode.gd

---

🧼 Auto-formatting overrides user input

Cause:
_auto_format(text) modifies content aggressively

Fix:

• Make formatting context-aware
• Apply formatting just for white spaces

---

🧊 Frozen or empty editor buffer

Possible causes:

• _buffer_to_string() returns empty string

Fixes:

• Validate buffer conversion logic

---

⚔️ Shortcut conflicts

Cause:
Multiple modes or editor actions using same key binding

Fix:

• Use Customization Guide wiki page to remap shortcuts
• Avoid assigning global shortcuts inside modes
• Find shortcuts with command palette

---

🧪 Debugging Tips

• Use print() generously during development
• Use Godot’s Remote Inspector to inspect live nodes
• Test modes with real files and edge cases
• Keep mode logic modular for easier isolation

---

📦 Reporting Bugs

If you encounter a bug that isn’t covered here:

• Check the CONTRIBUTING.md for reporting guidelines
• Include reproduction steps, screenshots, and mode files if possible