Skip to content

Advanced Mode Development

Jump to bottom
Mahan Khalili edited this page Aug 21, 2025 · 1 revision

🧠 Advanced Mode Development in Text Forge

This guide is intended for experienced developers who want to build high-quality, maintainable modes for Text Forge.
If you're new to modes, we recommend starting with the basic mode guide first.

🎯 Design Philosophy for Modes

Modes in Text Forge should be:

  • Lightweight and independent – avoid unnecessary dependencies or complexity.
  • Readable and maintainable – use clear structure, naming, and logic so others can understand and extend your mode.
  • Editor-friendly – modes should integrate smoothly with the UI and avoid unexpected behaviors.

📁 Mode Folder Structure

Each mode must reside in its own folder and include at least the following three files:

File Purpose
icon.png Icon displayed in the UI
mode.cfg Configuration file (name, version, supported extensions, etc.)
mode.gd Main script extending TextForgeMode

You may include additional files (e.g. dictionaries, templates, helper scripts).
Text Forge includes all files in the folder during import/export, even if it doesn't use them directly.

🧩 Working with the TFM API

Modes must extend the TextForgeMode class, which inherits from Node. Read this class internal documentation for complete information. Only virtual methods should be overridden—do not override public or private methods.

📌 Key Virtual Methods

Method Purpose
_initialize_mode() Initialize mode and enable features
_auto_format(text) Apply custom formatting to file content
_auto_indent(text) Handle indentation logic
_string_to_buffer(string) Convert editor text to bytes for saving
_buffer_to_string(buffer) Convert file bytes to editor text
_update_code_completion_options(text) Provide code completion suggestions
_generate_preview(text) Return preview string (BBCode supported)
_generate_outline(text) Return nested array representing file structure
_lint_file(text) Return list of problems (errors/warnings) in file

Note

All virtual functions have default behavior. For example, _string_to_buffer(string) and _buffer_to_string(buffer) default to using UTF-8, while other functions simply include appropriate placeholders to prevent errors when running a mode without overriding these functions. These default behaviors are designed precisely for when you don't need to override the function.

🧠 Additional Properties & Utilities

  • syntax_highlighter: You can assign a custom SyntaxHighlighter or use CodeHighlighter for simpler cases.
  • comment_delimiters / string_delimiters: Define comment and string patterns for folding and highlighting.
  • panel: Optional UI panel shown in the editor via show_panel().

🧪 Testing, Debugging & Publishing

To test a mode without full installation:

  • Place the mode folder in modes/ and restart the editor.
  • Use print() in mode.gd for logging at test time, for run-time exceptions use Global.send_notification().
  • Use Godot tools like Remote Inspector for runtime inspection.

To publish a mode:

  • Host the mode folder in a public repository.
  • Include a README.md with description, screenshots, and usage instructions. Use same template as official modes READMEs.
  • Optionally submit your mode to the official mode library for inclusion.

💡 Development Tips

  • Keep your folder structure simple and intuitive.
  • Use TFM API features to enhance user experience.
  • Include any extra resources inside the mode folder so they’re preserved during import/export.

🔝 Back to top 🔝

Text Forge Wiki Community ⚪ 2025-present

Clone this wiki locally