Ren'Py Text Analyzer

Ren'Py Text Analyzer is a VS Code extension providing detailed statistics about your Ren'Py scripts—both for individual files and entire projects—helping you track writing progress, analyze character voice, and understand script structure.

While dialogue parsing and character resolution are robust, complex script structures might occasionally lead to variations compared to other tools.

Note: This extension counts words and dialogues differently than the Ren'Py Lint tool in some cases. See "Important Notes (Comparison to Ren'Py Lint)" below.

Key Features

1. Comprehensive Script Analysis (Single File & Project-Wide)

• Project-Wide Analysis:
  • Execute the "Ren'Py Analyzer: Analyze Entire Ren'Py Project" command to scan all relevant .rpy files in your workspace.
  • Excludes common non-script folders by default, with further customization available via settings (projectAnalysis.excludeFolders, projectAnalysis.excludeGlobPatterns).
  • Generates a detailed Markdown report summarizing aggregated statistics for the entire project, which opens automatically in preview mode.
• In-Depth Statistics:
  • Word Count: Displays total words within identified dialogue, narration, and thoughts. Features extensive configurable filtering (stopwords, character names, text tags, interpolation, custom words). Also shows counts for selected dialogue text in the active editor.
  • Dialogue Count: Shows the total number of dialogue lines identified based on Ren'Py syntax and current configuration.
  • Keyword Analysis: Identifies and displays the most frequent words used in dialogue, with options to include/exclude stopwords and limit the number of keywords shown.
  • Ren'Py Element Counts (Beta): Counts occurrences of common Ren'Py statements like scene, show, menu, label, python, etc.
  • Time Estimates: Provides estimated reading and speaking times based on the filtered word count and configurable WPM settings.
• Editor Integration for Labels:
  • Displays an estimated word count for the dialogue within each Ren'Py label block directly above the label definition in the editor. This feature can be toggled via the codeLens.enableLabelWordCounts setting.

2. Detailed Character Insights

• Advanced Character Resolution: Intelligently identifies character variables defined using define x = Character(...).
  • Handles variable references for display names (e.g., Character([name_var])) and resolves chained definitions.
  • For single-file analysis (tree view), resolution is scoped to character definitions within the currently active file.
  • For project-wide analysis, a global character map is constructed from definitions across all analyzed project files for more comprehensive resolution.
• Per-Character Statistics: Breaks down dialogue line count, filtered word count, and percentage contributions for each resolved character.
• Sentiment Analysis (Optional): Calculates and displays the average sentiment score for each character's dialogue lines (can be enabled in settings).
• Speaker Tag Exclusion: Allows users to specify a list of speaker tags (e.g., script keywords like "if", "return") to be completely excluded from character analysis and counts via the analysis.excludeCharacters setting.

3. Intelligent Dialogue & Script Parsing

• Versatile Format Recognition: Understands various Ren'Py dialogue formats, including standard character "dialogue", simple quotes ("dialogue" for narration/thoughts), multi-line strings ("""...""" or '''...'''), centered narration (or other configured narration keywords), and text from menu choices.
• Python Context Awareness:
  • Effectively distinguishes between Ren'Py dialogue and Python code by recognizing and appropriately handling content within python: blocks, init <priority>: blocks, and multi-line Python data structures (dictionaries, lists) declared via define, default, or direct assignment.
  • Identifies and counts renpy.say() and say() function calls as dialogue, even when used within these Python contexts.
• narrator Variable Handling: Correctly classifies lines attributed to the special narrator variable based on the dialogueParsing.simpleQuotesAre setting, aligning with Ren'Py conventions.
• extend Statement Processing: Interprets extend statements as continuations of the preceding dialogue block, merging their text for word counting.
• Configurable Block Exclusion: By default, content within screen, style, and transform (ATL) blocks is excluded from dialogue and word count analysis. This behavior can be modified in the extension settings.

4. Integrated View & User Experience

• Status Bar Display: Shows the filtered word count (total for the current file, and for the current text selection) directly in the VS Code status bar. Tooltips provide details on applied filters.
• Tree View Visualization (Single File): Presents all statistics for the currently active Ren'Py file in an organized tree view: Overview, Characters, Top Keywords, and Ren'Py Elements.
• Customizable View: Sections for Keywords and Ren'Py Elements in the tree view are collapsed by default. Sentiment analysis and the display of Narration/Thoughts can be toggled via settings.
• Automatic & Debounced Updates: Statistics for the active file (tree view and status bar) refresh automatically as you type or change selection, with a slight debounce delay to optimize performance.

Important Notes (Comparison to Ren'Py Lint)

This extension's counting methodology may differ from the Ren'Py Launcher's Lint statistics:

• Word Splitting: Words connected by an em dash (—) will be counted as two words by the extension, while Lint usually count them as one.
• extend Statements: This extension merges extend text with the previous dialogue line for word counting; Lint count extend blocks separately.
• Menu Choices: This extension includes text from menu (text in dialogue box while waiting for player choice) and the menu choices (as "Thoughts") in its dialogue and word counts; Lint typically excludes them.
• Filtering: This extension applies configurable filters (stopwords, character names, tags, etc.) to its primary word count, resulting in a potentially lower count than Lint's raw count.
• Block Content: By default, this extension excludes content from screen, style, and transform blocks, which Lint might include if they contain say statements.

Known Limitations

• Complex renpy.say()/say()/e() Arguments: The extension primarily supports direct variable names, the None keyword, or simple string literals as speaker/dialogue arguments in renpy.say()/say() or e() calls. It does not parse dialogue from complex expressions (like f-strings, concatenations) or other function calls used directly as arguments within these functions.
• Dynamic/Python-Generated Dialogue: While renpy.say() within Python is handled, dialogue heavily generated through very complex Python logic that doesn't use recognizable say statements or standard dialogue syntax might not be fully captured.
• Character Resolution Scope (Single File View): In the tree view (single-file analysis), character display name resolution depends on the Character definition being present in the currently analyzed file. The project-wide analysis feature addresses this by building a global understanding.

Usage

1. Single File Analysis (Tree View & Status Bar):
   • Open a Ren'Py script file (.rpy) in VS Code.
   • The Ren'Py Analyzer tree view (accessible via its icon in the Activity Bar) will automatically display statistics for this file.
   • The status bar will show the word count for the file. Select text to see selection-specific counts.
   • If enabled, word counts for label blocks will appear above their definitions in the editor.
2. Project-Wide Analysis (Markdown Report):
   • Ensure your Ren'Py project folder is open as the workspace in VS Code.
   • Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
   • Type and select "Ren'Py Analyzer: Analyze Entire Ren'Py Project".
   • After processing, a Markdown report summarizing the project's statistics will be generated and opened in preview mode.
3. Configuration:
   • Access extension settings via the standard VS Code settings UI (File > Preferences > Settings, then search for "Ren'Py Analyzer" or navigate to Extensions > Ren'Py Analyzer).
   • Customize various aspects including word count filters, dialogue parsing rules, keyword generation, view options, project analysis exclusions, and CodeLens behavior.

Configuration Highlights

(Refer to the VS Code Settings UI under "Extensions > Ren'Py Analyzer" for the complete list of settings and their detailed descriptions.)

• Word Count & Filtering: Control filtering for stopwords, character names, text tags, interpolation, and custom words.
• Keyword List Generation: Configure whether stopwords appear in the keyword list and set the maximum number of keywords to display.
• Dialogue Parsing Rules:
  • Define custom narration keywords (e.g., "centered") or change how simple quotes and the narrator variable are classified (as "Thoughts" or "Narration").
  • Enable or disable the exclusion of content within screen, transform (ATL), and style blocks.
• Analysis View Options (Tree View & Report):
  • Toggle the display of "Narration" and "Thoughts" in overall counts.
  • Enable or disable character Sentiment scores.
  • Specify a list of speaker tags/names to completely exclude from the analysis.
• CodeLens for Labels: Enable or disable the display of word counts above label definitions in the editor.
• Time Estimation Parameters: Set custom Words Per Minute (WPM) values for reading and speaking time calculations.
• Project Analysis Settings: Define lists of folder names or glob patterns to exclude specific parts of your project from the project-wide analysis.

Feedback & Feature Requests

This extension was initially developed for personal use, and while efforts have been made to support common Ren'Py scripting practices, there are undoubtedly many ways developers structure their visual novels.

Your feedback would be truly helpful in improving the Ren'Py Text Analyzer.

Where your input would be especially helpful:

• Unusual Script Structures: If you use Ren'Py syntax for dialogue, character definitions, or script organization in a way that this analyzer doesn't fully capture or misinterprets, please share examples.
• Dialogue Parsing Edge Cases: Encountered a line of dialogue that isn't counted or is misattributed? Let me know.
• Feature Ideas: Are there specific statistics, analyses, or views you'd love to see that would help your Ren'Py development workflow?
• Accuracy Discrepancies: If you notice significant differences in counts compared to your expectations or other tools (beyond the known differences with Lint mentioned above), providing specific examples can help identify areas for improvement.

Contact

• Discord: collynnyy
• E-Mail: coltosocial@gmail.com

Donations

This project is developed and maintained in spare time. If you find it useful and would like to show your support, any donations are greatly appreciated!