During title development, programmers, designers, and testers often encounter unexpected behaviors in their titles. Capturing appropriate information about such behaviors is a vital first step in understanding and mitigating them, and in some cases, can even provide self-diagnostic substitutes for support avenues like the XGD Entertainment Developer Forums or escalation to the developer account manager team. This white paper outlines some of the key pieces of prominent configuration and implementation data that support successful investigation and resolution of title implementation issues in a number of frequently encountered areas.
Certain key pieces of information must be gathered to diagnose all issues, regardless of the nature of the problem. These are:
Without this information, it might not be possible to reproduce the issue or to identify whether it has already been addressed in a later XDK or recovery release than you are using. Do note that recoveries are decoupled from XDK releases on Xbox One, and titles are encouraged to always run against the latest publicly released “production” recovery.
The following tables contain lists of both general and feature area-specific diagnostic information that can accelerate response to problems and issues seen during development. In many cases, title developers can use this information to resolve their issues independently.
|
Data to collect |
Where to find it / comments |
Self-diagnosis tips |
| Xbox One recovery version | On the Xbox One XDK Software Downloads page on the Xbox Game Developer (XGD) site, or if the recovery is successfully installed, on the development kit itself: Settings app > System > Developer settings > Shell version
Or from the XDK-installed PC: xbconnect [Tools IP address], look for the HOST: value. See also Connect (xbconnect.exe). | |
| Console type (entitlement) | Settings app > System > Developer settings > Certificate Type | |
| Where in the setup process the point of failure occurs | When you report a problem, specify which step presented the failure and any workarounds you attempted. The steps are provided in the Getting Started page on XGD. | |
| Error codes or debugger output | | See the white paper How to Install an Xbox One Recovery Update
.
|
|
Data to collect |
Where to find it / comments |
Self-diagnosis tips |
| XDK version | Connect (xbconnect.exe) (read Client Build value) Or go to Control Panel > Uninstall or change a program
and read the Version value for Microsoft Xbox One XDK. xdk.h also includes a #define _XDK_VER indicating the current XDK version a title is building against. It can be useful to include this information inside a title’s debug HUD/UI. | Ensure that the PC’s XDK version matches that of the compiled app running on Xbox One, as well as the provisioning, through the PC xbprovision tool, of the console itself. |
| Xbox One recovery version | Settings app > System > Developer settings > Shell version Or from the XDK-installed PC: xbconnect [Tools IP address], look for the HOST: value. See also: Connect (xbconnect.exe). | |
| Are any non-standard libraries or services, such as evaluation DLLs, test packages, and so forth, being used? | | |
| Output from Connect (xbconnect.exe) while title is running | From the XDK-installed PC: xbconnect [Tools IP address] /D | Client build: XDK version in use on the development PC. HOST: Recovery version. SYSTEM: System OS version present on the console—deployed from the XDK or ADK through xbprovision. TITLE: Game OS in use by the current title—matches SYSTEM where title is loosely deployed. |
| Stack trace | Copied from Visual Studio debugger. A number of additional title library symbols—for example, “Xbox One Debugging Symbols”—are available from the Xbox One XDK Software Downloads page on XGD. | See the XDK documentation topic Debugging Xbox One Projects. |
| Reproducibility | Does the issue occur on one console or across multiple consoles? With one or multiple user accounts? Are there any other unique configurations that always cause the issue or that, alternatively, cause the issue not to occur? | |
| Repro steps | Capture the source code—ideally a pared-down Visual Studio Solution with appropriate sources—the pre-configuration steps on the PC or Xbox One, in-title behavior, and so forth. | |
| Analogous XDK sample repro? | If there is an XDK sample that demonstrates similar functionality, does the unmodified sample work properly in the XDKS.1 sandbox? If so, does changing the sample's SCID, TitleID, and other information to match the title result in the same behavior in the title's development sandbox? | |
| File System activity | Download and install ProcMon from the Microsoft Windows SysInternals site and generate a log while the tool you are using is running. Generate the log using extended information. You can filter the log to the specific tool if you desire, though this might remove useful information. | The log file will show file access errors, and it enables you to identify the file name, path, and any other executables that might be accessing the file. |
| Xbox One DLL version information | If the title's build system uses copies of ERA DLLs rather than using them directly from the XDK, ensure that they don't become stale by matching them to the current XDK the title is built against. You can check versions by running DumpBin from the Xbox One XDK command prompt with the /HEADERS parameter specified. | Ensure that the timestamp from the DumpBin header information matches the public release date of the XDK you expect to build against, with a maximum variance of two days. |
|
Data to collect |
Where to find it / comments |
Self-diagnosis tips |
| Can the issue be reproduced on a Windows build of the title? | | |
| Is the error reproducible with the stock driver instead of running the monolithic driver? | | |
| Does the title receive warnings or errors when running with D3D11_CREATE_DEVICE_DEBUG? | | See the MSDN article Software Layers—specifically, the section on the D3D11 Debug Layer. |
| Does the behavior change when running with D3D__CpuSingleStepper? |
- Create an empty file named D3D__CpuSingleStepper in the layout root.
- Deploy to console (push or pull).
- Run the title with the debug version of the monolithic driver (D3D11_CREATE_DEVICE_DEBUG).
- Note whether the issue still occurs or there are any changes in behavior.
- Delete the D3D__CpuSingleStepper file from the layout and from the console using
xbdel or xbdeploy /s.
| |
| Command list issue debugging | Does the issue occur when all command lists are generated on a single thread?Does the issue occur without command lists, if all rendering is performed on the immediate context? | |
| If possible, take a PIX GPU capture. Does the issue still occur during playback of the capture? | | See the XDK documentation topic PIX GPU Captures. |
|
Data to collect |
Where to find it / comments |
Self-diagnosis tips |
|---|
| What audio engine is being used? | XAudio2, low-level WASAPI, middleware? See XAudio2 Overview. | |
| On which CPU(s) is audio processing running? | The XAudio2Create function has an XAUDIO2_PROCESSOR parameter (will also set WASAPI). WASAPI is controlled through the SetWasapiThreadAffinityMask function. | |
| What other processing runs on threads that are shared with audio? | xbperf capture: were any cores where the audio processing was occurring at or near 100% consumption? | See the XDK documentation topic entitled CPU Performance (xbperf.exe). |
| What are the console's audio output format and audio output port? | Output format: Settings app > Display & sound > HDMI audio
and Optical audio dropdown settings. Can also query using the IMMXboxDeviceEnumerator::GetHdAudioChannelCounts Method. Output port: verify whether the receiver is using optical port (S/PDIF) or HDMI. | |
| What is the audio engine's target output format? | Typically 7.1 48 KHz. For XAudio2, you can specify otherwise using the IXAudio2::CreateMasteringVoice Method. | |
| Are the audio artifacts or issues specific to certain pieces of content? | If so, do these pieces of content play successfully in audio samples? If these assets are compressed, do the artifacts remain when the content is played as uncompressed PCM? | |
| Describing and capturing samples of artifacts | Do any of the following describe the audible artifacts?
- Clipping: the audio is playing louder than the console can represent = “distortion”; shaved-off peaks of waveforms.
- Dropouts: the entire audio output falls silent. If this occurs: for how many samples?
- Partial dropouts: one or more voices fall silent, but the overall mix remains). If this occurs: for how many samples?
- Digital noise: the audio becomes unintelligible and uncorrelated with actual source content.
- Partial digital noise: one or more voices play as “static,” while the overall mix remains in the background.
- Discontinuities: some samples have been eliminated; the audio jumps to another location in a playback stream.
| |
|
Data to collect |
Where to find it / comments |
Self-diagnosis tips |
|---|
| Sandbox ID | Settings app > System > Developer settings > Sandbox ID, or with the remote command xbconfig SandboxId. Set using remote command xbconfig SandboxId=DesiredId (console reboot required to apply). | Ensure that the console's sandbox matches that of the configured title. See the white paper entitled Sandbox Survival Kit. |
| Service Configuration ID (SCID) | | See the XDK documentation topic entitled Obtaining Critical IDs and Setting Up Sandboxes. |
| TitleID | | See the XDK documentation topic entitled Obtaining Critical IDs and Setting Up Sandboxes. |
| NAT Type report | Settings app > Network > “NAT Type:”Additionally, note whether the kit is connected to an internal corporate network, directly to the Internet, and so forth. | |
| Connection status from Network Troubleshooter | Settings app > Network > Test network connection
| |
| Connection status from Multiplayer Troubleshooter | Settings app > Network > Test multiplayer connection
| Ensure that the console is successfully getting a Teredo address. |
| Fiddler trace | | See the XDK documentation topic entitled How to use Fiddler with Xbox One. |
For additional troubleshooting tips, see the “Xbox Live and Networking” table, above.