game-doctor: A TypeScript repository from Two-Cat Moon

Game Doctor

Game Doctor generates diagnostic reports for HTML5 video games in easy-to-share formats. Reports contain information about graphics, device, network, fps, screenshots, client fingerprint, and much more. Easy to implement, easy to use, and fully configurable with key-bindings and global window hooks.

Use our Diagnostic Formatting Tool to decode and generate human-friendly PDFs from diagnostic reports.

Diagnostic Formatting Tool »

Report Bug · Request Feature

Table of Contents

Getting Started
Decoding Reports
Contributing
License
Contact
Acknowledgments

Getting Started

This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.

Installation

Install Game Doctor via NPM
```
npm i @twocatmoon/game-doctor
```

Import the GameDoctor class into your project and initialize an instance

import { GameDoctor } from '@twocatmoon/game-doctor'

const doctor = new GameDoctor({
   gameName: 'My Game',
   gameVersion: '1.0.0',
   outputToConsole: true,
   outputFormat: 'base64',
   copyToClipboard: true,
   canvasEl: myGame.canvasEl,
   async canvasRenderFn () { myGame.render() },
})

Call the doTick method somewhere in your main game loop so we can detect FPS
```
doctor.doTick()
```
(Optional) Call the generateReport method
```
await doctor.generateReport()
```

(Optional) Hook up the FPS indicator

doctor.showFps()
doctor.showFps(boolean)
doctor.hideFps()

You should now see a diagnostic report in your console, and have the base64-encoded JSON copied to your clipboard. Have your users send the outputted report data to your support team, which can be used to generate human-readable reports via Game Doctor or the online Diagnostic Formatting Tool.

Note: For full configuration options and further usage instructions see below.

Configuration

type GameDoctorOptions = {
    // The name of your game
    gameName: string
    // The current version of your game client
    gameVersion: string
    // Copies output to clipboard while true
    copyToClipboard?: boolean
    // Add additional info to the fingerprinting hash algorithm
    additionalFingerprintInfo?: any
    // The canvas element your game is rendering to
    canvasEl?: HTMLCanvasElement
    // The method you call to render your game to the canvas (required for taking screenshots from WebGL contexts)
    canvasRenderFn?: () => Promise<void>
    // URL to use to determine ping duration
    pingUrl?: string
    // Add __toggleFps and __generateReport methods to the window object
    attachToWindow?: boolean
    // Any additional information you'd like included in the report
    getAdditionalInfo?: () => Promise<any>
    // Output the report to the console in a human-readable format
    outputToConsole?: boolean
    // Output format in json, base64 encoded json, or shareable png (Diagnostic Formatting Tool requires base64 or image/png formats)
    outputFormat?: 'json' | 'base64' | 'image/png'
    // Image to overlay ontop of image/png exports (like your game or company logo)
    overlayImage?: HTMLCanvasElement | HTMLImageElement
    // Configure keyboard shortcuts to generate reports and toggle the FPS counter
    keyboardShortcuts?: {
        generateReport: {
            key: string
            ctrlKey?: boolean
            altKey?: boolean
            shiftKey?: boolean
            metaKey?: boolean
        },
        toggleFps: {
            key: string
            ctrlKey?: boolean
            altKey?: boolean
            shiftKey?: boolean
            metaKey?: boolean
        },
    }
    // Which reports to generate (by default all are enabled except for location)
    reports?: {
        performance?: boolean
        network?: boolean
        window?: boolean
        device?: boolean
        graphicsDevice?: boolean
        screenshot?: boolean
        location?: boolean
        fingerprint?: boolean
        fps?: boolean
        lastError?: boolean
    }
}

Example Output

{
  "reportId": "f2301f0e5d35f",
  "date": "2023-02-07T19:43:21.133Z",
  "timezone": 420,
  "gameName": "Test Game",
  "gameVersion": "1.0.0",
  "additionalInfo": {
    "foo": "bar"
  },
  "performance": {
    "timeOrigin": 1675798998737.4,
    "timing": {
      "connectStart": 1675798998749,
      "navigationStart": 1675798998737,
      "secureConnectionStart": 0,
      "fetchStart": 1675798998741,
      "domContentLoadedEventStart": 1675798998860,
      "responseStart": 1675798998761,
      "domInteractive": 1675798998800,
      "domainLookupEnd": 1675798998749,
      "responseEnd": 1675798998762,
      "redirectStart": 0,
      "requestStart": 1675798998749,
      "unloadEventEnd": 1675798998771,
      "unloadEventStart": 1675798998771,
      "domLoading": 1675798998772,
      "domComplete": 1675798998885,
      "domainLookupStart": 1675798998749,
      "loadEventStart": 1675798998885,
      "domContentLoadedEventEnd": 1675798998860,
      "loadEventEnd": 1675798998885,
      "redirectEnd": 0,
      "connectEnd": 1675798998749
    },
    "navigation": {
      "type": 1,
      "redirectCount": 0
    },
    "memory": {
      "totalJSHeapSize": 10424393,
      "usedJSHeapSize": 8561557,
      "jsHeapSizeLimit": 2172649472
    },
    "eventCounts": {
      "size": 36
    }
  },
  "network": {
    "effectiveType": "4g",
    "rtt": 100,
    "downlink": 10,
    "ipAddress": "XX.XX.XX.XX",
    "ping": 158.89999999850988
  },
  "window": {
    "innerWidth": 1197,
    "innerHeight": 1181,
    "pixelRatio": 1,
    "href": "http://localhost:5173/",
    "title": "Test Game",
    "isEmbedded": false,
    "referrer": "http://localhost:5173/"
  },
  "device": {
    "language": "en-US",
    "languages": [
      "en-US",
      "en"
    ],
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/109.0.0.0 Safari/537.36",
    "deviceMemory": 8,
    "doNotTrack": null,
    "hardwareConcurrency": 8,
    "maxTouchPoints": 0
  },
  "graphicsDevice": {
    "renderer": "WebKit WebGL",
    "rendererUnmasked": "ANGLE (Apple, Apple M1, OpenGL 4.1)",
    "vendor": "WebKit",
    "vendorUnmasked": "Google Inc. (Apple)"
  },
  "screenshot": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...",
  "fingerprint": "1845e3df8030e9bd8ada1ff6757b550c59b75b09f0459cae3686fe103afd809d",
  "fps": "55.3",
  "lastError": [
    "Uncaught Error: foo bar baz",
    "http://localhost:5173/src/main.ts?t=1675798998734",
    61
  ]
}

(back to top)

Decoding Reports

Via Game Doctor

Reports can be decoded programatically using a set of static methods on the Game Doctor class.

  const decoded = GameDoctor.decodeBase64(string)
  const decoded = await GameDoctor.decodeImageUrl(string)
  const decoded = await GameDoctor.decodeImage(HTMLImageElement | HTMLCanvasElement)

Via the online Diagnostic Formatting Tool

Reports in the base64 or image/png formats can be decoded and formatted into human-readable, printable HTML pages using the Diagnostic Formatting Tool.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Twitter - @twocatmoon

Project Link - https://github.com/twocatmoon/game-doctor

(back to top)

Acknowledgments

Best-README-Template

(back to top)