FastLogs

Open-source debug engine for game builds where the engine console is out of reach.

Русская версия: docs/ru/README.md.

The goal of FastLogs is to get as many bugs fixed as possible, as fast as possible. At its core it is a tool for the fastest possible loop between QA and a developer: the tester ships a bug in one gesture, the developer opens a link and sees the cause right away, and nobody waits on retellings, follow-up questions or blind reproduction attempts. Every feature is judged by one question: does it shorten the path from a bug happening in a build to that bug being fixed and the fix confirmed? That is also how the roadmap is chosen: whatever removes the most waiting between QA and dev goes first.

Why

In a WebGL build, on a portal, on a phone or on a console you have no access to the engine console. A tester hits a bug, but the log stays on their device and you cannot dictate it over the phone. FastLogs fixes that: from a running build a single gesture (or an agent call) ships the recent log lines, a snapshot of the device (OS, GPU, memory, build) and optional screenshots to a server, and the tester gets a short link. They paste it to you and you open a filterable console, the device info, the context and the screenshot in a browser. One server serves every game and both engines (Unity and GameMaker) on a single JSON contract.

How it works

   Game (client)                  FastLogs server                Recipients
   -------------                  ---------------                ----------
  Unity  C#  ----\                                          /--> short link (viewer)
                  >-- POST /api/logs --> ingest --> SQLite --+--> catalog /browse
  GameMaker GML -/        (JSON)         + blobs (log/PNG)   \--> sinks (Slack/Discord/
                                                                  webhook/Confluence/Sheet)

Engines: Unity (C#, UPM package) and GameMaker (GML; complete but less battle-tested - see the guide's caveat). Platforms: WebGL and web portals, iOS, Android, Standalone (Windows / macOS / Linux). On console retail the tool is stripped out entirely.

This is what a developer opens from the link: a filterable console with the device info, context, scene snapshot, and each recorded run folded under its own session divider.

Features

• Recent log lines + device info + context/breadcrumbs + screenshots + scene snapshot in one report.
• Crash auto-capture with an offline outbox: an unhandled exception is written to disk before FastLogs even attempts the upload, so a report whose process dies mid-send still arrives on the next launch.
• Browsable catalog with full-text search (SQLite FTS5), sessions, crash grouping and triage status/tags. A report can also open a Redmine issue in one click, if you wire the tracker up.
• Agent channel: headless send plus a remote command channel (agent -> game), and config-driven component capture.
• Unity and GameMaker clients speak one JSON contract: a new engine needs one HTTP request plus the log-line format the server parses (see CONTRACT.md section 1a). Skip the format and the report still returns 201 while crash grouping and session dividers go quietly dead.
• Privacy by default: PII scrubbing on log text, context and breadcrumbs; sensitive device fields off unless you opt in.

For QA

• Nothing to install: FastLogs is already baked into the build, and there is no code to write.
• Catch a bug, open the overlay (F8, or three quick taps in the top-right corner). Put your name in once on the Settings tab (Send stays greyed out until it is there), type a short title, tick Shot / Scene if useful, and hit Send.
• The short link lands in your clipboard (Unity also draws a QR of it). Paste it to a developer; it opens for anyone, no token.
• Detailed guide: docs/UNITY.md.

Quick start

Five minutes to your first report.

1. Run the server:

cd server
npm install
node scripts/add-app.js mygame "My Game" 30 # register a game (30-day retention); prints the ingest token once
npm start                                   # node src/server.js on http://localhost:8787 (blocks; leave it running)

Copy the token add-app prints - it is shown once and stored only as a hash. Ingest rejects an untokenized send with 401. Just poking around locally? node scripts/add-app.js mygame "My Game" 30 --no-token opens ingest for that app and you can skip the Token field below. On a real deploy, keep the token.

2. Unity: add the package by Git URL in Packages/manifest.json, create the config asset, then init and send.

{
  "dependencies": {
    "com.playjoy.fastlogs": "https://github.com/AitiX/Fastlogs.git?path=/unity#v0.5.3"
  }
}

Create the config via Tools > PlayJoy > FastLogs > Create Config Asset, set EndpointUrl, AppId and Token (the one add-app printed) in its Server section, then:

using PlayJoy.FastLogs;

FastLogs.Init();                       // loads Resources/FastLogsConfig; idempotent
FastLogs.SetContext("level", "3-2");   // capture already runs: Init starts it
var r = await FastLogs.SendAsync(includeScreenshot: true, title: "Crash on load");
if (r.Success) GUIUtility.systemCopyBuffer = r.Url;

3. Open the returned link in a browser. That is the whole loop.

Supported Unity versions: 6000.1 (Unity 6) and 2022.3 LTS. Server needs Node.js >= 18.

For developers

• Add the client, point it at your server, call FastLogs.Init() and Send(). Logs are captured from Init onward, so a report sent a second later already carries them. Recording (the separate cross-session store on disk) is off by default: set Recording > Enabled = true first, then either tick AutoStartRecording or call StartRecording().
• Enrich reports with SetContext(...), Breadcrumb(...), scene snapshots, file/save uploads and multi-screenshot capture.
• Gate for release: the whole client is stripped from retail via #if UNITY_EDITOR || DEVELOPMENT_BUILD; opt back in on non-console targets with LOGSHARE_FORCE_ENABLED. Consoles stay stripped regardless.
• Guides: Unity docs/UNITY.md, GameMaker docs/GAMEMAKER.md.

Automation and agents

Agents get a two-way inspect + drive channel into a running build, no debugger attached.

• Headless send with no overlay, toast, screenshot or loop guard. On WebGL it posts through fetch, so a report leaves even a backgrounded tab with a stalled player loop. From JS after Init: await window.FastLogs.send({ title, comment, sceneContext }) resolves with {ok, id, url, status, error} (the same object also lands on window.FastLogs.lastResult).
• Command channel (agent -> game): an agent enqueues a named command with POST /api/commands/<appId>, the game polls, runs its whitelisted handler and acks the result, and the agent reads it back. On WebGL the poll lives in JS and works even in a hidden tab. A result past the server's 64 KB inline cap is uploaded as a file instead of failing: the ack then carries {"__fastlogsResultRef": "<url>", "bytes": N}, so wide dumps survive their own size. See CONTRACT.md section 8 and docs/UNITY.md.
• Pointed inspection (fastlogs.inspect): ask one component for its live state instead of hauling the whole scene tree. Args {type, go?, props?, max?} return serialized fields plus Renderer / MaterialPropertyBlock values. Read-only by construction, and it works whether or not component capture is enabled.
• Component capture: rule-driven snapshots of live component state (materials, MaterialPropertyBlock, sorting) straight from the build.
• Command-to-report correlation: while a command runs, any report it produces is tagged with that command id, so GET /api/await/<appId>?code=<commandId> returns exactly what the command caused. Enqueue, then await, no timestamp matching.
• Liveness beacon: GET /api/commands/<appId>/health answers "is a build actually polling right now", so a command that never gets acked reads as "nothing is running" rather than "the handler hung".
• MCP server (server/mcp/): the whole loop as native agent tools (run a command and wait for its result, check channel health, await a report by correlation code, search and read logs) instead of shelling out to CLI helpers. It dereferences an offloaded result for you.

Documentation

• CONTRACT.md - the single JSON API contract (source of truth: body schema, endpoints, error codes, limits).
• docs/UNITY.md - full Unity integrator guide.
• docs/GAMEMAKER.md - full GameMaker integrator guide.
• docs/ADMIN-GUIDE.md - deploy and server administration.
• server/README.md - server: env vars, deploy (Docker / systemd), sinks, catalog features, tests.
• server/mcp/README.md - MCP server: drive and inspect a build from an AI agent as native tools.
• unity/README.md - Unity package reference: every config field and its default.
• unity/ARCHITECTURE.md - Unity client architecture.
• test/e2e/README.md - end-to-end harness: a real server and a real built player over the live command channel.
• CONTRIBUTING.md - layout, dev setup, tests and PR flow.
• CHANGELOG.md - release notes and tags.

Russian translations live in docs/ru/ (README, UNITY, GAMEMAKER, ADMIN-GUIDE). Those four are translations: the English original wins if they disagree. CONTRACT.md is the exception - it is written in Russian and is itself the source of truth for the API.

Bugs and feature requests

Found a bug, hit something confusing, or want a feature? Open a GitHub Issue - there are templates for a bug report and a feature request. Security vulnerabilities are the one exception: see SECURITY.md for private disclosure instead.

Contributing

PRs welcome; good first issues are labelled. See CONTRIBUTING.md for the layout, dev setup and PR flow, and SECURITY.md for reporting vulnerabilities.

License

MIT. See LICENSE.