XBOX 360 Getting Starting

Xbox 360: Getting Started

Developing for Xbox 360

To develop for the Xbox 360 you must be a Microsoft Certified Xbox 360 Developer and own the appropriate hardware. See the Xbox 360 Setup page for a seat setup checklist.

Access Xbox 360 unique functionality

Unity Xbox provides a number of new scripting APIs to access Xbox Live services, storage devices, Avatars and much more. See the UnityEngine.X360 namespace in the scripting API.

How Unity Xbox differs from Desktop Unity

Strongly Typed JavaScript

• Dynamic typing in JavaScript is always turned off in Unity on Xbox. This is the same as adding #pragma strict to your scripts, but it is done by default instead, in order to improve performance. When you launch an existing Unity Project, with dynamic typing, you will see compiler errors. You can easily fix them by either using static typing for the variables that are causing errors or taking advantage of type interface.

Ahead-Of-Time (AOT) compilation

• Scripts are AOT compiled and loaded in as normal Xbox 360 dynamic libraries. JITing is not supported.
• Exotic class libraries (reflection, LINQ etc) not fully supported.

Limited memory

• Expect about 440MB free system memory with an empty project loaded.

Fixed resolution

• 720p (1280x720) is the only resolution you’ll have to deal with.

No hardware MSAA

• Unity for Xbox does not do hardware MSAA. Use “AntialiasingAsPostEffect” technique “FXAA3” from the “Image Effects” standard package for best results.

XMA audio compression

• Unity will compress audio to XMA when targeting Xbox 360.
• Unity will use OGG in the editor (XMA can not be played on the PC). Expect audio quality to differ and check the output Xbox produces.
• Only two channels are supported when load type is “Compressed in memory”.

SETUP

Step-by-step guide for installing Unity for Xbox 360:

1. Install Visual Studio 2010
2. Install Microsoft XDK (Full)
3. XEDK environment variable must be set up - XDK setup does this automatically.
4. Exact version number will be provided with every Unity build.
5. Set up a default devkit or testkit in your Xbox 360 Neighborhood.
6. Install Unity.

Build information:

• XDK version: November 2012, #21250.7.

Project Structure

Special directories:

PROJECT/Assets/StreamingAssets - for assets that Unity should not process. Files are copied to OUTPUT\Media\Raw.

• Videos.
• Asset bundles.
• Custom assets.

Runtime paths:

1. Xbox mounts the game folder to game:.
2. Unity executable is located at game:\Project.XEX.
3. Unity data files are located at _game:\Media_.
4. Unity compiled script assemblies are located at _game:\Media\Managed_.
5. Raw assets are located at _game:\Media\Raw_.

Project Settings

Unity for Xbox 360 comes with additional project settings.

Build Type

Debug player has full debug output and asserts enabled.

1. Editor-player connection enabled.
2. Unity profiler enabled.
3. Full debug information emitted to standard output.
4. Linked with debug libs.
5. PDBs for managed code emitted to BUILD_TARGET\Media\Managed.

Development player has most of the debug functionality required for normal development.

1. Editor-player connection enabled.
2. Unity profiler enabled.
3. Critical debug information emitted to standard output.
4. Linked with instrumented libs to enable PIX captures.
5. PDBs for managed code emitted to BUILD_TARGET\Media\Managed.

Master player is TCR compliant.

1. All standard output disabled.
2. Linked with retail libs.

Explicit Null Checks

Development Build feature that enables you to catch null references. Enabling it will cause the compiler to emit explicit null checks around every managed deref operation and throw a NullPointerException. This does influence performance slightly. Disabling it will cause the console to crash under the same conditions. See Debugging for more details.

Compress Libs

Enables compression of the main executable and script assemblies. Decreases project boot time (esp. from DVD), but increases build time.

Run Method

“Build and Run” command behavior can be customized:

1. Copy to HDD - the usual way of testing Xbox 360 applications. The whole project output folder is copied to a devkit.
2. DVD Emulation - a disc layout file AutoLayout.XGD is created in the project output folder and the Game Disc Emulator is started. Devkit must be connected via the DVD EMU USB port (see DVD Emulation_ in the Xbox 360 SDK Documentation for details). Note that you will have to close the Game Disc Emulator window prior to the next build.
3. No timing - the emulator does not emulate DVD behavior or introduce any latency into file read times.
4. Accurate - the emulator emulates DVD behavior by introducing accurate latency based on the LBAs of the files accessed. Note that the automatically generated layout might be suboptimal for your game.

Title Id

Title id of your game. Format: ABCD1234. Contact your developer account manager at Microsoft for details. A title id is required by certain Xbox features (i.e. storage or Xbox Live services).

ImageXEX config override

Specifies a configuration file for the XEX image conversion tool. Unity player is converted to a XEX during the process. See XEX Image Converter in the Xbox 360 SDK Documentation for details.

SPA config

Specifies a SPA configuration file to be embedded in the executable. This configuration is required by certain Xbox features (i.e. Xbox Live services). Step-by-step guide:

1. Download the Xbox LIVE Publishing Toolkit from the Xbox Developer site.
2. Prepare a configuration using the Xbox LIVE Game Configuration tool and upload it to PartnerNet. See LIVE Environments in the the Xbox 360 SDK Documentation for details.
3. Generate the .SPA and .SPA.H files for your configuration.
4. Enter the path to the .SPA file.

Generate _SPAConfig.cs

Convenience feature enabled only when the SPA config is specified. Enabling this will have Unity look for a .SPA.H file in the same folder as the specified .SPA file and convert it to a Unity script containing a single enum SPAConfig. Hardcoding values is not an option as they may change after rebuilding the SPA files.

Enable Avatar rendering

Initializes the Avatar system. See Avatars for more details.

Deploy Kinect resources

Copies Kinect resources (Database.xmplr and NuiIdentity.bin.be) to the project output folder.

Deploy Speech resources

Copies Speech resources (selected languages) to the project output folder.

Enable Kinect

Enables Kinect systems in UnityEngine.Kinect.

Enable Kinect AutoTracking

Enables automatic skeleton tracking. If disabled, UnityEngine.Kinect.Skeleton.SetTrackedSkeletons must be called to specify tracked skeletons. Only visible if Enable Kinect is checked.

Enable Kinect Fitness

Enables Kinect Fitness API.

Enable GPU skinning

Enables Unity to use a GPU skinning path with memexport.

Stripping Level

Enables code stripping. Strips managed bytecode and unused native code. Greatly reduces DLL size and boot time. “micro mscorlib” is not available for Xbox 360. Selecting it will act as “Strip ByteCode”.

Building Plugins for Xbox 360

Plugin requirements:

- Linked against the same libraries as Unity.

   *Development Build uses instrumented XDK libraries.
   *Non-development Build uses release XDK libraries.

- Access to certain system services might not be possible if Unity already uses them:

   *Avatar system can be disabled in Player Settings if a custom implementation is desired.

Plugin development:

1. An Xbox 360 DLL is written as usual.
2. A relocation address must be provided manually:

• See library Project Properties - Xbox 360 Image conversion - Base Address.
• Available address range: 0x06000000 to 0x08000000.

1. Compiled libraries are be placed in PROJECT\Assets\Plugins folder. See See Project Structure for more details.
2. A library definition file must be provided (PLUGINNAME.def).
3. See Mono Interop docs for marshaling details.

Examples

See “Xbox 360 - Native Plugin Example” package.

Video Playback

Full-screen video playback on the Xbox can be done using functions in the UnityEngine.X360VideoPlayer class.

1. Video files must be placed in the PROJECT\Assets\StreamingAssets folder. See Project Structure for more details.
2. Specify an absolute path when loading video files on the Xbox: _game:\Media\Raw_.
3. Playing a video will automatically disable the gamer’s background music (see TCR 024).
4. Playback is based on XMedia2 library. See the Xbox 360 SDK Documentation for details.

Controller

Reference

Notes:

- To query button states:

• Call Input.GetKey*() with a KeyCode. See table for reference.
• Call Input.GetButton*() with a name set in the InputManager.

   * Joystick 0 button names are formed as “joystick button #”.
   * Joystick 1–3 button names are formed as “joystick # button #”.

- To query analog axis values:

   *Call Input.GetAxis*() with a name set in the InputManager.

- Axis 3 is “Axis 9 minus Axis 10” for backwards compatibility. - Axis 8 is not used.

No.	Button Name	KeyCode	Axis#	Comments
1	Guide Button	N/A	N/A	Use the X360Core Class "X360Core.IsSystemUIVisible()"
2	A(Green)	JoyStickButton0	N/A
3	B(Red)	JoyStickButton1	N/A
4	X(Blue)	JoyStickButton2	N/A
5	Y(Yellow)	JoyStickButton3	N/A
6	Left Stick	JoyStickButton8	Axis 1 (X) - Horizontal, Axis 2 (Y) - Vertical	Range [–1; 1]
7	Right Stick	JoyStickButton9	Axis 4 - Horizontal, Axis 5 - Vertical	Range [–1; 1]
8	Dpad	Example	Axis 6 - Horizontal, Axis 7 - Vertical	Set {–1; 0; 1}
9	Back	JoyStickButton6	N/A
10	Start	JoyStickButton7	N/A
11	Left Trigger	N/A	Axis 9	Range [0; 1]
12	Right Trigger	N/A	Axis 10	Range [0; 1]
13	Left Bumper	JoyStickButton4	N/A
14	Right Bumper	JoyStickButton5	N/A

Debugging

Xbox Watson

Keeping Xbox Watson attached to the kit you’re testing on is always a good idea for the visibility of debug output. If your project crashes, you will get output similar to this: Exception : 4177526784 3221225477 2281767608 FirstChance. Here’s how to interpret it:

1. Convert it to hex to get Exception : 0xF9000000 0xC0000005 0x880102B8 FirstChance.
2. The second value is the exception type (i.e. 0xC0000005 is EXCEPTION_ACCESS_VIOLATION).
3. The third value is the instruction address (i.e. 0x880102B8).
4. Look for previous output mentioning loaded DLLs, i.e.: Loaded DLL Assembly-CSharp.dll.xex (\Device\Harddisk0\Partition1\DEVKIT\Unity\Media\Managed\Assembly-CSharp.dll.xex); Mapped 0x88000000 thru 0x88030000
5. If the instruction address is in the mapped range of a DLL, it’s the culprit.
6. This method is not very informative.

Crash Dumps

Crash dumps are saved on your devkit (DEVKIT\dumps) if Watson is not attached, otherwise dumps can be saved directly to your pc. Once a crash dump is on your development machine it can be examined like this:

1. Open the dump in Visual Studio.
2. Start debugging.
3. Load symbols for your managed code from BUILD_TARGET\Media\Managed.
4. Examine the callstack, etc.
5. Known issue: Visual Studio currently displays only the top function when in compiled script code.
6. Note: Make sure to save ‘MiniDump with heap’ otherwise symbols will not load.

Explicit Null Checks

In case you’re only interested in hunting down your null ref bugs, this is your best bet. Enabling the feature will:

1. Throw a NullReferenceException.
2. Output the managed callstack, i.e.: [F9000000:] EXCEPTION handling: NullReferenceException NullReferenceException: A null value was found where an object instance was required. at MyScript.BadFunction () [0x00023] in C:\MyExample\Assets\MyScript.cs:19 at MyScript.Start () [0x00000] in C:\MyExample\Assets\MyScript.cs:23 Note that NullReferenceException will NOT work in non-development(Release) builds.

Debugging shaders via PIX (Automatic UPDB generation)

To enable PIX debugging of shaders.

1. In the Windows system registry (regedit), create a DumpShaderPdbDir string registry entry in the HKEY_CURRENT_USER\Software\Microsoft\XenonSDK\ subkey. Within the registry entry, specify a directory on your PC where UPDB files will be automatically generated.
2. In Unity re-import the .shaders files (Shader opcode generation occurs during import time not at build time).
3. Build and run your Unity project.
4. Launch PIX and perform a “Record GPU” [ctrl+G]
5. Launch the PIX analysis app [F5]
6. Select the DrawIndexPrimitive of interest and select Shaders tab. Periodic clearing of the UPDB folder might be required.

Script Debugging with MonoDevelop

1. Detach Xbox Watson! Script debugging does not work if a debugger is attached.
2. Enable script debugging in the build settings window.
3. Build and run your project.
4. Attach MonoDevelop to an instance of “XenonPlayer”.
5. Use as normal.
6. Known issues:

   * Floating point registers may be trampled in the current version. Take care when debugging around plugin invocation code that uses floating point values.

Profiling

Unity Profiler

Unity editor can attach to a development player running on any Xbox on the network.

1. Run your build.
2. Activate Windows->Profiler.
3. Select XenonPlayer(YOUR_XBOX_NAME) as the active profiler.
4. Use the profiler as usual.

PIX Timing Capture

Timing capture can be used like for any normal Xbox application.

PIX GPU Trace

GPU trace can be used like for any normal Xbox application.

PIX CPU Trace

CPU trace can be used like for any normal Xbox application. Navigate to “Functions->Module” tab and load any missing symbol files from BUILD_TARGET\Media\Managed.

• Assembly* files are generated from your Unity scripts.
• Other libraries with AOTCompileStep in their paths are also Unity related. Symbol names do not match those in your scripts exactly, but they can be easily interpreted. Examples:
• plt_UnityEngine_Screen_get_width is the getter of UnityEngine.Screen.width.
• MyScript_Update is the Update function of MyScript.
• plt_UnityEngine_Rect__ctor_single_single_single_single is the constructor of UnityEngine.Rect with 4 arguments.

Title Updates

How to build a title update

To create a title update follow the “Title Updates on Xbox 360” page in the Xbox 360 SDK Documentation.

- Store the output of your original game build after release. - Use the same Unity version for the update (or an updated one that has been approved). - If updating scripts:

• Include the updated .def and .mono files.
• If using the same Unity version for the update, only the Assembly-* files need to be updated.
• If code stripping was enabled in the original game build, all assemblies will most likely need to be updated (with the exception of tiny bigfixes).
• If title update contains a lot of new code and forces the in-memory size of any assembly to decrease/increase below/above the next multiple of 64KB, the relocation address of multiple assemblies will change and all assemblies will need to be updated.

- If updating assets:

• Build them with UncompressedAssetBundle flag.
• Add custom code to call AssetBundle.CreateFromFile.
• Load asset bundles from the UPDATE: mount that will become available when the title update is applied.

Kinect

Kinect Editor Window

In Unity you can test your Kinect based projects from within the Unity editor. Firstly you need to create Kinect recording(s) from Microsoft’s Xstudio tool. This is located: WindowsOS Start->All Programs->Microsoft Xbox 360 SDK->Natural Input->Xbox Studio or via C:\Program Files (x86)\Microsoft Xbox 360 SDK\bin\win32\Xstudio.exe

• Place the Microsoft XStudio recordings (.xed files) into your Unity project
• In Unity open the kinect window - located at the menu bar Window->Xbox 360->Kinect
• Start your project in the editor (main play button)
• In the kinect window Select the recording from the dropdown and press play

Avatars

Avatars

Unity provides a simple way to load Avatar resources - see Scripting API reference for UnityEngine.X360Avatars Displaying an avatar step by step:

- Make sure a user is signed in: UnityEngine.X360Core.RequestSignIn() when requesting user avatars. - Issue an avatar load: UnityEngine.X360Avatars.RequestLocalUserAvatar() or any other Request* function. - Handle the OnAvatarLoaded(UnityEngine.X360AvatarModel model, IntPtr avatarAssets) callback.

• X360AvatarModel contains a Mesh with multiple subsets (X360AvatarModel.batchCount). It is a rough wrapper around XAVATAR_ASSETS (see XAvatar Structures in Xbox 360 SDK Documentation). Hold on to it for as long as the Avatar is required.
• avatarAssets is a pointer to XAVATAR_ASSETS valid during the callback. It may be passed to a plugin.

- X360AvatarModel.Mesh can be used in Unity as a normal Mesh. - Avatar vertex buffers contain extra UV channels (half2) in certain cases:

• Head: TEXCOORD2 through TEXCOORD5 for:

   *Eyebrow texture.
   *Eye texture.
   *Mouth texture.
   *Eye shadow texture.

• Non-shiny body parts: TEXCOORD2 for the decal texture.
• Data from these extra channels can not be accessed from scripts.

Shaderlab extensions

In order to support Avatar rendering, shaderlab was extended to allow for more UV sets on Xbox 360. In case of surface shaders, those UV sets are only accessible when #pragma only_renderers xbox360 is set.

Example project:

See “Xbox 360 - Avatar Rendering Example” package.

Known Issues

Known Issues

• Mono threads will currently only run on thread 4.
• Image effects from the Standard Assets package are not modified to benefit from RenderTexture.DiscardContents.

Known Crashes

• Certain crashes are developer’s responsibility to fix and are not handled by Unity:
• It is mandatory to have at least one Rich Presence string in the Xbox Live game configuration. Failing to do so will cause a crash in SendToLive@PresenceCollection (see callstack).