Dev Guide

Download as txt, pdf, or txt
Download as txt, pdf, or txt
You are on page 1of 8

== 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:===
# Install Visual Studio 2010
# Install Microsoft XDK (Full)
#XEDK environment variable must be set up - XDK setup does this automatically.
#Exact version number will be provided with every Unity build.
#Set up a default devkit or testkit in your Xbox 360 Neighborhood.
#Install Unity.
#Install Xbox for Unity.
#Install Unity 3D Patcher.
#Install Standard Asset Pack.
#Install Microsoft Visual Studio 2010 Tools for 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.
==== PROJECT/Assets/Plugins - for native plugins. .def and .xex files are copied to
OUTPUT\Media\Plugins. ====

===Runtime paths:===
# Xbox mounts the game folder to game:.
# Unity executable is located at game:\Project.XEX.
# Unity data files are located at _game:\Media_.
# Unity compiled script assemblies are located at _game:\Media\Managed_.
# 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.'''
# Editor-player connection enabled.
# Unity profiler enabled.
# Full debug information emitted to standard output.
# Linked with debug libs.
# PDBs for managed code emitted to BUILD_TARGET\Media\Managed.

'''Development player has most of the debug functionality required for normal
development.'''
# Editor-player connection enabled.
# Unity profiler enabled.
# Critical debug information emitted to standard output.
# Linked with instrumented libs to enable PIX captures.
# PDBs for managed code emitted to BUILD_TARGET\Media\Managed.

'''Master player is TCR compliant.'''


# All standard output disabled.
# 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:

# Copy to HDD - the usual way of testing Xbox 360 applications. The whole project
output folder is copied to a devkit.
# 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.
#No timing - the emulator does not emulate DVD behavior or introduce any latency
into file read times.
#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:

# Download the Xbox LIVE Publishing Toolkit from the Xbox Developer site.
# 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.
# Generate the .SPA and .SPA.H files for your configuration.
# 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:===
# An Xbox 360 DLL is written as usual.
# A relocation address must be provided manually:
*See library Project Properties - Xbox 360 Image conversion - Base Address.
*Available address range: 0x06000000 to 0x08000000.
# Compiled libraries are be placed in PROJECT\Assets\Plugins folder. See See
Project Structure for more details.
# A library definition file must be provided (PLUGINNAME.def).
# 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.

# Video files must be placed in the PROJECT\Assets\StreamingAssets folder. See


Project Structure for more details.
# Specify an absolute path when loading video files on the Xbox: _game:\Media\Raw_.
# Playing a video will automatically disable the gamer’s background music (see TCR
024).
# Playback is based on XMedia2 library. See the Xbox 360 SDK Documentation for
details.

==Controller==
[[File:Unity Xbox 360 Controller Mapping.png|frame|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.

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

# Convert it to hex to get Exception : 0xF9000000 0xC0000005 0x880102B8


FirstChance.
# The second value is the exception type (i.e. 0xC0000005 is
EXCEPTION_ACCESS_VIOLATION).
# The third value is the instruction address (i.e. 0x880102B8).
# 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
# If the instruction address is in the mapped range of a DLL, it’s the culprit.
# 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:

# Open the dump in Visual Studio.


# Start debugging.
# Load symbols for your managed code from BUILD_TARGET\Media\Managed.
# Examine the callstack, etc.
# Known issue: Visual Studio currently displays only the top function when in
compiled script code.
# 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:

# Throw a NullReferenceException.
# 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.

# 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.
# In Unity re-import the .shaders files (Shader opcode generation occurs during
import time not at build time).
# Build and run your Unity project.
# Launch PIX and perform a “Record GPU” [ctrl+G]
# Launch the PIX analysis app [F5]
# Select the DrawIndexPrimitive of interest and select Shaders tab. Periodic
clearing of the UPDB folder might be required.

===Script Debugging with MonoDevelop===


# Detach Xbox Watson! Script debugging does not work if a debugger is attached.
# Enable script debugging in the build settings window.
# Build and run your project.
# Attach MonoDevelop to an instance of “XenonPlayer”.
# Use as normal.
# 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.

# Run your build.


# Activate Windows->Profiler.
# Select XenonPlayer(YOUR_XBOX_NAME) as the active profiler.
# 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).

You might also like