Dev Guide
Dev Guide
Dev Guide
==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.
==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.
===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).
===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 Kinect===
Enables Kinect systems in UnityEngine.Kinect.
===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.
==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:
===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:
# 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.
==Profiling==
===Unity Profiler===
Unity editor can attach to a development player running on any Xbox on the network.
==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.
==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:
===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).