Skip to content
bbautiPublic

About

Client-side performance diagnostics for Vintage Story with offline reports.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Ember Diagnostics

Record client performance in Vintage Story. Investigate stutters in a self-contained offline report.

Documentation · Contributing · Issues · Releases · MIT license

AI development disclosure: This mod was written entirely with AI assistance using OpenAI GPT-6 Astra through OpenCode—including its implementation, viewer, tests and documentation. bbauti directs and maintains the project. This is not a claim of independent human code review. Read AI_USAGE.md for the development process, validation limits and contributor expectations.

Ember was motivated primarily by spark and Lithos Probe: make performance problems easier to record, inspect and discuss. It brings that workflow to Vintage Story's client, combining frame/runtime history, sampled managed stacks and mod context. See motivation and credits.

Ember Investigate workspace showing a 30-minute recording, an incident queue, timeline, flame graph and method inspector

Actual 1.1.2 viewer displaying a historical 30-minute test recording with deliberately injected stalls. This is not an overhead benchmark. Screenshot provenance and mobile view.

At a glance

Current scope
Game target Vintage Story 1.22.7
Installation Client only; no remote-server installation or administrator privilege required by Ember
Recording runtime .NET 10, matching game architecture, with a discoverable dotnet host
Platform validation Windows; Linux/macOS recording workflows have not been validated
Reports Local HTML, JSON, Markdown, CSV and optional speedscope profile
Network / AI services No automatic upload, telemetry backend or AI-service dependency
Maintenance Community project maintained by bbauti

Start one recording, play normally, then stop or leave the world. Ember prepares a session bundle you can open from disk. The profiler helps find evidence and the next experiment; it does not prove which mod caused a slowdown.

Multiplayer use requires no Ember network packets or server command permission. Follow the rules of the server you join. In singleplayer, the integrated server shares the client process: process CPU, memory, GC and stack samples can include its work.

Install

  1. Obtain emberdiagnostics-1.1.2.zip from GitHub Releases, when published, or build it from source. GitHub's automatically generated Source code ZIP is not an installable mod.
  2. Put the ZIP in the Mods directory of your Vintage Story data folder (normally %APPDATA%\VintagestoryData\Mods on Windows), then restart the client. Keep only one Ember version installed.
  3. Join a world and run .ember health.
  4. Session recording requires a matching-architecture .NET 10 runtime and a discoverable dotnet host. The bundled tracer/Ember.Trace.dll is a framework-dependent worker; it launches separately and attaches to this client's PID through local .NET diagnostics IPC. See runtime troubleshooting if startup fails.

The game installation directory used to build is different from the data directory used for mods and exports.

Record a session

.ember start

Play normally, then run .ember stop or leave the world/server. Ember automatically prepares one session ZIP in the background, and opens the export folder by default. Its standalone worker can finish after the client exits. Extract the ZIP and open report.html. For optional AI-assisted interpretation, GPT-REPORT.md is the single-file first attachment. No hosting, AI account or automatic upload is involved.

.ember profile with no argument starts the same session. For an optional timer, use .ember profile 1800 for 30 minutes (accepted range: 5–28,800 seconds). No history configuration edit is needed. Untimed sessions have a default four-hour maximum and a 2 GiB disk budget; limits can finish a recording earlier.

Command Purpose
.ember help Show available commands.
.ember health Show a current client health snapshot.
.ember start Start a session; save automatically on stop or world exit.
.ember profile [seconds] Start the same session; optionally stop after 5–28,800 seconds.
.ember stop Finish the active session and automatically export.
.ember cancel Cancel the active recording.
.ember status Show recording/finalization status.
.ember export Export a recent monitoring snapshot; an active session keeps recording.
.ember mark <text> Add a timestamped observation to the report timeline.
.ember recover Retry unfinished recordings from saved journals/checkpoints.
.ember folder Open the export folder.

What is collected

  • During recording, per-second runtime/frame batches are journaled to disk across the session, rather than truncated to the recent 15-minute buffer. Final reports bound individual frames and stack observations and retain incident evidence; omissions and gaps are disclosed.
  • Outside recording, lightweight monitoring keeps a rolling 15-minute runtime timeline and up to 120,000 recent frame records by default. High frame rates can exhaust the record cap sooner.
  • Frame intervals and instrumented render/stage wall times, plus optional asynchronous GPU Before/Done elapsed timestamps. GPU timestamps include pipeline gaps, exclude earlier ticks and presentation, and are not GPU busy time/utilization; results arrive later.
  • Process CPU in both one-core and machine-normalized units, working set/private/managed memory, allocation rate, GC and thread-pool context.
  • CPU/GPU identity, OS/runtime, selected graphics settings, client-visible entity/chunk counts, meshing queues, received-byte counters, reported ping, and recent warnings/errors and timeline markers.
  • Mod identities, versions, dependencies, systems, associated assemblies, optional file hashes, and Harmony patch inventory. Inventory and sampled module matches are evidence for investigation, not proof a mod caused a stall.
  • Session managed-stack segments (60 seconds and up to 50,000 retained observations per segment by default), with coverage, rundown/parse status and quality metadata. Attachment and segment transitions can leave gaps; continuous stack coverage is not guaranteed. Sample percentages are thread observations, not exact CPU percentages.

Optional mod configuration collection is off by default (IncludeModConfigs=false). If enabled, configurations pass through redaction. Logs and markers can still contain identifying information: review the files before sharing them. See data and metric semantics for interpretation and sharing details.

Exports

Bundles are written under <DataPath>/Ember/exports/:

File Contents
GPT-REPORT.md Single-file first attachment for GPT: selected evidence, session/incident context, limitations and analysis instructions.
report.html Self-contained offline viewer with embedded report data.
report.json Structured report, metric definitions, timeline, inventory and limitations.
llm-context.json Compact context: environment/settings, mods, selected worst windows and top stacks, with links to full evidence.
SUMMARY.md Human-readable summary and evidence-based findings.
ASK-AN-LLM.md Analysis instructions to accompany the report when asking an LLM for help.
metrics.csv Runtime and frame distributions over time.
frames.csv Individual retained frame intervals and render-submission wall times.
incidents.csv Detected incident windows, severity evidence and stack coverage.
manifest.json Export file sizes and SHA-256 hashes.
profile.speedscope.json Per-thread sampled profile, present when a profile was captured.

The HTML template is embedded in Ember.Core.dll; users do not need a separate viewer download or web server. Attach GPT-REPORT.md with what you did and when. Keep report.json available for deeper investigation—it contains the retained evidence and can be large. The other summaries remain useful supplementary files. Open the speedscope file in speedscope for a dedicated stack viewer.

Interrupted recordings are saved under <DataPath>/Ember/sessions/; startup recovery and .ember recover retry unfinished reports. Recovery can salvage complete journal batches and usable segments, but cannot guarantee the final moments of a crash.

Investigate in the offline viewer

The Investigate workspace combines an incident queue with a stack laboratory. It opens the incident with the largest recorded frame peak and its surrounding context. Choose another incident in the queue or on the session timeline; filter by thread, managed classification, method/module/mod, and Context / Before / During / After / Comparable normal.

The recording header identifies the capture date, duration, observed frames and stack coverage. The compact range/source strip stays beside the filters; Sampling details explains time boundaries, sample density and graph/export semantics.

  • Select a flame-graph branch to zoom and inspect its method. The method inspector shows the full signature, ownership hints, self/inclusive observations and self share. The paginated hotspot table and expandable call tree use the same filtered sample set.
  • Expand supporting evidence, counter-evidence and next experiments beside the stacks. The main thread is labelled when its OS thread ID was captured.
  • Drag the timeline, select a window with the arrow keys and Enter, or enter a custom interval. Time coordinates share the profile origin; end boundaries are exclusive.
  • Export selection saves ember-selection.json with matching observations, frame definitions, filters, time origin and incident evidence. Search includes entire stacks containing a matching frame; flame zoom changes only the displayed branch. GPT brief remains the primary full-report handoff.
  • Overview, runtime/GPU charts, baseline comparison, session coverage, inventory and full-capture allocation/exception/contention tools remain available in the report navigation.

An older exported HTML keeps its embedded viewer. To inspect an older capture in the new interface, open its report.json in the updated viewer; there is no need to record again.

Build

Prerequisites: .NET 10 SDK, a local Vintage Story 1.22.7 installation, and network access for initial NuGet restore. The Bash script also needs Python 3.

./scripts/build.ps1 -GamePath 'C:\path\to\Vintagestory'
bash scripts/build.sh --game-path "$HOME/vintagestory"

Both scripts accept -GamePath; path resolution is explicit argument, then VINTAGE_STORY, then APPDATA/Vintagestory when APPDATA exists. They build Release/net10.0, publish the framework-dependent worker, stop on failures, and take the package version from src/Ember.Mod/modinfo.json. Output: artifacts/emberdiagnostics-<version>.zip.

Package root: modinfo.json, Ember.dll, Ember.Core.dll, .ignore, documentation and licenses, plus tracer/ with the worker's complete publish output. The .ignore rule keeps worker DLLs out of Vintage Story's mod-assembly scan. Game assemblies are excluded. See build and verification for the release validation procedure and recorded status.

Review the code

Path Responsibility
src/Ember.Mod/ Client hooks, commands, snapshots, GPU timing and recording lifecycle
src/Ember.Core/ Bounded collection, data models, journals, analysis, redaction and exports
src/Ember.Trace/ External EventPipe supervisor, segment capture, parsing and recovery
viewer/report.html Dependency-free offline HTML/CSS/JavaScript viewer embedded in the core assembly
tests/ Executable regression and integration harnesses
scripts/ Local packaging and graphical game-test runners

Start with the architecture and reading map, then development setup and testing guide. The game-independent checks and synthetic viewer tests can be run without a game installation:

dotnet run --project tests/Ember.Tests/Ember.Tests.csproj -c Release
dotnet run --project tests/Ember.Session.Tests/Ember.Session.Tests.csproj -c Release
node viewer/verify.cjs

The viewer checks need Node.js 22+ and Chrome/Chromium (CHROME_PATH can select the browser). Public CI exercises game-independent code and the viewer; packaging and gameplay validation require a local game installation. These suites are console programs, not dotnet test projects.

Validation and known limits

  • A historical 1.1.0 Windows/loopback multiplayer run recorded 30 minutes, 107,384 frames and 98.97% usable stack interval coverage. Version 1.1.2 reuses that capture for viewer validation; it did not receive a new gameplay soak.
  • The viewer regression suite includes hostile text, old/new/empty reports, keyboard interactions and a 400,000-sample / 200,000-frame stress fixture.
  • A representative, controlled overhead benchmark remains outstanding. Sampling and collection consume resources; Ember does not promise zero overhead.
  • Sample shares are thread observations, not exact CPU time. GPU elapsed timestamps are not utilization. Module ownership and temporal overlap are not proof of cause.
  • Remote-server internals are unavailable. Linux/macOS game workflows and public-server network/authentication conditions remain unvalidated.

See the full verification record. Raw private captures and generated binaries are intentionally excluded from Git.

Motivation and credits

spark, by lucko and contributors, and Lithos Probe, by imtsubaki, were the principal motivations for Ember.

  • spark demonstrated the value of an accessible capture workflow, runtime context and a rich profiler viewer. Documentation · Source.
  • Lithos Probe brought a packaged profiling/report workflow to Vintage Story servers and motivated a complementary client-focused tool. Mod page · Source.

Ember is an independent implementation, not a port or fork of either project; no spark or Lithos Probe code is copied or distributed. Their authors are not responsible for Ember. See research and comparisons and third-party notices for additional sources and distributed dependency licenses.

Contribute and get help

Bug reports, code review, documentation corrections and reproducible measurements are welcome. Read CONTRIBUTING.md, then use Issues or a pull request. Report sensitive vulnerabilities through the process in SECURITY.md. Community participation follows our code of conduct.

All original project code and documentation were written with AI assistance using OpenAI GPT-6 Astra. Please read the full disclosure before evaluating or contributing to the project.

License

MIT, copyright © 2026 Ember contributors. Third-party components retain their own licenses and notices. Vintage Story is copyright Anego Studios; Ember is an independent community project and does not distribute the game. A licensed game installation is required to build and run the mod.

About

Client-side performance diagnostics for Vintage Story with offline reports.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages