description.html

<h1>Anomaly DevTools - Profiler & Logger v1.3.5</h1>

<p><strong>A standalone developer toolkit for S.T.A.L.K.E.R. Anomaly that provides zero-code performance profiling and structured logging for any mod.</strong></p>

<p><strong>🎯 Perfect for Modders:</strong> Profile and debug ANY mod without modifying its source code. Works with all Anomaly mods out of the box.</p>

<h2>Key Features</h2>
<ul>
    <li><strong>Zero-Code Profiling:</strong> Profile any Lua module without modifying its source code. Just select modules in the UI and start profiling.</li>
    <li><strong>Live Statistics:</strong> View real-time function timing data including call counts, average/min/max/total execution times in milliseconds.</li>
    <li><strong>Module Browser:</strong> Built-in UI to discover and select modules to profile from the global Lua namespace (<code>_G</code>).</li>
    <li><strong>Profiling Presets:</strong> Save and load your profiling configurations for different debugging scenarios. Includes auto-start on game load.</li>
    <li><strong>Structured Logging:</strong> Advanced logging system with severity levels (DEBUG, INFO, WARN, ERROR), custom categories, color coding, and filtering.</li>
    <li><strong>CSV Export:</strong> Export profiling data to CSV for detailed analysis in Excel, Google Sheets, or other tools.</li>
    <li><strong>Flamegraph Export:</strong> Export call stack data in collapsed stacks format (`.folded`) for visualization in external tools like FlameGraph.pl, Inferno, and speedscope.</li>
    <li><strong>Call Graph Export:</strong> Export call graphs in DOT format for visualization in Graphviz and other tools. Analyze function call relationships and module dependencies.</li>
    <li><strong>JSONL Live Streaming (Experimental):</strong> Real-time streaming export of function call data in JSONL format for post-processing and external tool integration. Includes buffered I/O and UI controls.</li>
    <li><strong>Self-Time Tracking:</strong> New self-time metrics (total, average, median, min, max) show time spent in a function excluding child calls. Provides clearer picture of actual function performance vs cumulative time.</li>
    <li><strong>Parent Function Tracking:</strong> Track caller relationships and identify most common callers for each function. Understand which code paths are invoking your slow functions.</li>
    <li><strong>Timed Profiling Auto-Export:</strong> CSV and flamegraph are now automatically exported when timed profiling completes. No more missing data when the timer expires.</li>
    <li><strong>ImGui Interface:</strong> Self-contained, user-friendly UI panel for controlling the profiler and viewing logs in-game.</li>
    <li><strong>Profile on Load:</strong> Automatically start profiling when the game loads or transitions between locations (optional).</li>
    <li><strong>Modular Architecture:</strong> Complete code refactoring splitting monolithic codebase into focused modules for better maintainability and extensibility.</li>
</ul>

<h2>What's New in v1.3.5</h2>
<ul>
    <li><strong>📡 JSONL Live Streaming (Experimental):</strong> New real-time streaming export of function call data in JSONL format for post-processing and external tool integration</li>
    <li><strong>🎛️ JSONL Stream Controls (Experimental):</strong> UI controls for starting/stopping JSONL streams and exporting stream summaries</li>
    <li><strong>🏗️ Shared State Refactoring:</strong> Profiler scripts now use a shared state module for improved consistency across modules</li>
    <li><strong>🧹 Export Logic Cleanup:</strong> Streamlined export code paths for CSV, flamegraph, and JSONL</li>
</ul>

<h2>What's New in v1.3.0</h2>
<ul>
    <li><strong>🎯 Self-Time Tracking:</strong> New self-time metrics (total, average, median, min, max) show time spent in a function excluding child calls</li>
    <li><strong>🎯 Parent Function Tracking:</strong> Track caller relationships and identify most common callers for each function</li>
    <li><strong>🎯 Call Graph Export:</strong> Export call graphs in DOT format for visualization in Graphviz and other tools</li>
    <li><strong>🎯 Timed Profiling Auto-Export:</strong> CSV and flamegraph are now automatically exported when timed profiling completes</li>
    <li><strong>🔧 Bug Fixes:</strong> Fixed timed profiling issues, preset load/delete operations, dropdown display issues, and various UI improvements</li>
    <li><strong>🏗️ Modular Architecture:</strong> Complete code refactoring from monolithic to modular design with separated concerns</li>
</ul>

<h2>Previous Versions</h2>
<ul>
    <li><strong>v1.2.2:</strong> Critical fixes for function wrapping, custom module colors, high precision display, elapsed time tracking</li>
    <li><strong>v1.2.1:</strong> Median execution time, toggleable columns, color mapping fix</li>
    <li><strong>v1.2.0:</strong> LuaBind class method profiling, verbose logging flag</li>
    <li><strong>v1.1.2:</strong> Major performance improvements (2x FPS), timed profiling, minimal mode</li>
</ul>

<h2>Installation</h2>

<h3>Mod Organizer 2 (Recommended)</h3>
<ol>
    <li>Download the mod zip file</li>
    <li>In MO2, click "Install Mod" button</li>
    <li>Select the zip file</li>
    <li>MO2 will extract it automatically</li>
    <li>Enable the mod in your load order</li>
</ol>

<h3>Manual Installation</h3>
<ol>
    <li>Extract the zip file</li>
    <li>Copy the contents of the <code>gamedata</code> folder to your Anomaly installation's <code>gamedata</code> folder</li>
</ol>

<h2>Usage</h2>
<ol>
    <li>Start the game</li>
    <li>Open the ImGui menu (default: <strong>F1</strong> or <strong>Ins</strong>)</li>
    <li>Navigate to the <strong>DevTools</strong> menu</li>
    <li>Select <strong>Profiler</strong> or <strong>Logs</strong> to open the respective windows</li>
</ol>

<h3>Quick Start Guide</h3>
<pre>1. Open DevTools → Profiler tab
2. Expand "Module Browser"
3. Check the modules you want to profile
4. Click "Start Profiling"
5. Watch the stats table populate with timing data</pre>

<h3>Using Presets</h3>
<ol>
    <li>Select the modules you want to profile</li>
    <li>In the "Presets" section, type a name</li>
    <li>Click "Save"</li>
    <li>Later, click a preset name to restore that selection</li>
    <li>Enable "Profile on Load" to automatically start profiling when the game loads</li>
</ol>

<p><strong>⚠️ Warning:</strong> Selecting too many modules at once can cause stack overflows. Use moderation when selecting modules to profile. Start with a few modules and gradually add more if needed.</p>

<h2>Files Included</h2>
<ul>
    <li><code>devtools_profiler.script</code> - Core profiling engine</li>
    <li><code>devtools_profiler_export.script</code> - Export functionality (CSV, flamegraph, DOT, JSONL)</li>
    <li><code>devtools_ui_profiler.script</code> - Profiler ImGui user interface</li>
    <li><code>devtools_ui_logging.script</code> - Logging ImGui user interface</li>
    <li><code>devtools_logging.script</code> - Structured logging system</li>
    <li><code>devtools_config.script</code> - Configuration and presets storage</li>
    <li><code>mod_script_devtools_early.ltx</code> - DLTX config for early script loading</li>
    <li><code>devtools_README.md</code> - Detailed documentation (included in package)</li>
</ul>

<h2>Technical Details</h2>
<ul>
    <li><strong>Timer Precision:</strong> Uses X-Ray's native <code>profile_timer</code> for microsecond-precision timing</li>
    <li><strong>Stack Overflow Protection:</strong> Multiple safeguards including module blacklists, function blacklists, and call depth limits</li>
    <li><strong>Performance Impact:</strong> Adds ~1-5% overhead when profiling. Disable during normal gameplay.</li>
    <li><strong>Configuration Storage:</strong> Presets are stored in <code>appdata/devtools/presets/devtools_presets.txt</code></li>
    <li><strong>Export Locations:</strong> CSV exports to <code>appdata/devtools/devtools_profiler_export.csv</code>, flamegraph to <code>appdata/devtools/devtools_flamegraph.folded</code>, call graph to <code>appdata/devtools/devtools_callgraph.dot</code>, JSONL streams to <code>appdata/devtools/devtools_stream.jsonl</code></li>
</ul>

<h2>Tips</h2>
<ul>
    <li>Profile performance issues by registering your mod and enabling profiling to see which functions are slow</li>
    <li>Use categories for different subsystems (AI, UI, Combat, etc.) to filter logs effectively</li>
    <li>Save presets for different debugging scenarios (e.g., "AI_Debug", "Combat_Debug")</li>
    <li>Use CSV export to compare performance across different game sessions</li>
    <li>Export flamegraph data to visualize call stacks and identify performance bottlenecks</li>
    <li>Export call graphs in DOT format to analyze function call relationships and module dependencies</li>
    <li>Use self-time metrics to identify functions that are actually slow vs those that just call slow functions</li>
    <li>Check parent function tracking to understand which code paths are invoking your slow functions</li>
    <li>The Module Browser scans all of <code>_G</code> - you can profile ANY mod, even ones you didn't write</li>
</ul>

<h2>Advanced: Full Initialization Profiling</h2>
<p>DevTools uses DLTX for early script loading, allowing it to capture the complete game initialization including 
<code>start_game_callback</code> and <code>axr_main.on_game_start</code>. Just enable "Profile on Load" with your 
desired modules (including <code>_g</code> and <code>axr_main</code>) and restart the game. No manual patches needed!</p>

<p><strong>Author:</strong> CDEV<br>
For detailed API documentation and examples, see <code>gamedata/scripts/devtools_README.md</code></p>