@twocatmoon/game-doctor
v1.1.1
Published
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 configurab
Downloads
72
Maintainers
Readme
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 FPSdoctor.doTick()
(Optional) Call the
generateReport
methodawait 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
]
}
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.
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
License
Distributed under the MIT License. See LICENSE
for more information.
Contact
Twitter - @twocatmoon
Project Link - https://github.com/twocatmoon/game-doctor