Team Odysseys

UDK Technical Design Document

Kevin Giang Created 09-26-2013

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

Table of Contents
Introduction How to Read the Document UDK Online Documentation UDK Architecture Version Control Special Setup for our Project Packaging a Game UnrealScript Compiling a Script Setting up Development Environment Setting up nFringe Setting up Config File to Compile your Scripts Compiling Log Console Game Types GameInfo SimpleGame UTDeathMatch Why is Play on PC not using my custom controller/pawn? Objects Data Structures Math Functions Actors Important Functions simulated event PostBeginPlay() event Tick(float DeltaTime) CollidingActors(...) Example DefaultProperties Variables Working with Rotations Rotator Converting Values Between Unreal Units, Radians, Degrees Pawns How to Change Skeletal Mesh Easy Way Hard Way Controllers Why isnt Tick() working? Artificial Intelligence (Bots) Razer Hydras

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

Callback Functions Calibration How to Track Hydra Positions Our solution Hydra Units Oculus Rift Oculus Data Controlling the Rifts Orientation Why Cant I modify the Rifts Pitch? UDK Editor Setting up Editor for Oculus Rift Getting the 32-bit Editor Learning UDK Editor Video Tutorials* 3D Buzz Useful Hotkeys Navigating Perspective Viewport FPS Style Camera Movement Increasing/Decreasing Camera Movement Speed Strafing the Camera Moving the Camera Forwards/Backwards and Turning Kismet Sub-Sequences Useful Hotkeys Touch Triggers Why isnt my KActor hitting the trigger? Named Variables Matinee Grouping Actors in Viewport Manipulating Individual Actors in a Group Simplygon Cascade (Particle Editor) Builder Brushes (BSP) Geometry Mode Crash Warning!

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

Introduction
Welcome to the UDK Technical Design Document. Since Unreal already has the Unreal Development Network for technical documentation, this document will be going over the techniques we are using for our project, including working with the Oculus Rift and Razer Hydras.

How to Read the Document

Like most other dry and technical documents, you do not want to read it from page one. You should be using this document as a reference to answer technical questions. Sections will also have direct links to Unreal Development Network pages on the specific topic for detailed information. Another way to look at this document is to look at it like a FAQs page.

UDK Online Documentation

Unreal already has a massive knowledge library located at: http://udn.epicgames.com/Main/WebHome.html However, they do not cover specifics on how to implement game logic, which this document will cover.

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

UDK Architecture
UDK uses an Object-Oriented architecture. The user is expected to know what this means and how it works. Above the base code is the UnrealScript scripting language that UDK uses, which this document is focused on.

Version Control
For our project we will be using Mercurial SVN and the TortoiseHG GUI. TortoiseHG can be downloaded at: http://tortoisehg.bitbucket.org/download/index.html The game repository address for Team Odyssey is located at: https://hg.digipen.edu/projects/pathfinder

Special Setup for our Project

Since we are version controlling UDK, we will have to do some weird stuff because we dont want to version control the entire engine and all of its scripts. To get the proper updates into the right places, you will have to: 1. Create an empty folder somewhere. This is a temporary folder. 2. Open TortoiseHG and clone our repository into the temporary folder. 3. Cut & Paste the .hg folder from the temporary folder into your root UDK folder. *Note: Warning: Verify you are using the correct version of UDK and placing it in the correct folder containing Binaries, Development, Engine, Resources, and UDKGame. If you do not see these folders, then you are in the wrong directory. 4. Delete the repository you just cloned from TortoiseHG. 5. Go up one folder from your UDK root and drag its folder onto default in TortoiseHG. 6. Open the repository in TortoiseHG. 7. Pull from the repository to get the latest changes. 8. Commit changes you have done, if any, into a temporary branch. 9. Update to any previous revisions. 10. Update to latest revision. 10.1.Steps 9 and 10 are required to refresh the files in your UDK directory to have them updated to the proper files. 11. Done.

Packaging a Game
An online guide is located at:

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

http://www.hourences.com/an-entire-simple-udk-game/ Note: It is highly recommended to make a copy of all Default config files so that you can easily roll back changes in case you mess something up. Summary 1. If you just want to package a level to load by default and not a mod/game, then skip to Step 4 below. 2. Locate DefaultEngine.ini config file within \UDKGame\Config. 2.1. 2.2. 3. 3.1. Find [UnrealEd.EditorEngine] and add +ModEditPackages=<ModName> to the end of the list, where <ModName> is replaced by the name of your mod folder. Delete UDKEngine.ini so that UDK generates a new one with your changes. Find [Engine.GameInfo] so that you set up a default game info and controller. 3.1.1. If you have a custome game info, then 3.1.1.1. Replace DefaultGame=UDKBase.SimpleGame with DefaultGame=<ModName>.<ModGameInfo>. 3.1.2. If you have a custom player controller, then 3.1.2.1. Replace PlayerControllerClassName=UDKBase.SimplePC with PlayerControllerClassName=<ModName>.<ModPlayerController> 3.1.3. To create a custom map prefix if you have a custom game info, 3.1.3.1. Add +DefaultMapPrefixes=(Prefix=<ModAcronym>,bUsesCommonP ackages=FALSE,GameType=<ModName>.<ModGameInfo>). 3.1.4. Delete UDKGame.ini so that the engine will make a new one for you with your modifications. 4. If you have a custom level to load by default, then locate DefaultEngine.ini within \UDKGame\Config and go to section [URL]. 4.1. 4.2. 5. 5.1. 5.2. Change Map=UDKFrontEnd.udk to Map=<Name of your map>. Change LocalMap=UDKFrontEnd.udk to Map=<Name of your map>. When you load up Frontend, you should clear the list of maps to cook and add your own custom map(s). When you are ready to begin the cook process, click on Start. It should run through compiling your scripts, maps, and attempt to launch the game so that you can verify it works. Locate DefaultGame.ini within \UDKGame\Config.

Now you can cook your game using Unreal Frontend, which can be found in \Binaries\

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

5.2.1. If you dont want Frontend to automatically run your game during the Start cook sequence, you can disable it by clicking on the black arrow next to the Launch text to disable it. 5.3. After you have verified everything has cooked properly, you can then package the game by clicking on the Package Game button. 5.3.1. After packaging is done, you will find the installer in your root UDK folder.

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

UnrealScript
http://udn.epicgames.com/Three/UnrealScriptHome.html

Compiling a Script
There are a couple of ways to compile script, but each way has a preliminary setup.

Setting up Development Environment

UnrealScript files are simple text files, so they can be modified using any simple text editor. We are using nFringe to edit script. Setting up nFringe 1. nFringe is a plugin for Visual Studios and can be downloaded at http://pixelminegames.com/nfringe/releases/ 2. After installation, go to this page and follow The Short Way instructions: http://pixelminegames.com/nfringe/features/udk-projects/ Setting up Config File to Compile your Scripts If you created a new folder inside of \Development\Src, then you will need to follow these steps: 1. Locate your ...\UDKGame\Config directory. 2. Find and open UDKEngine.ini 3. Search for [UnrealEd.EditorEngine] 4. Added ModEditPackages=[Your folder name here] to the end of the block. 5. You should now be able to compile your scripts within the folder you created. Compiling Using nFringe, hit F7 for compile or CTRL + ALT + F7 to do a clean build. Using UDK, launch the editor and it will prompt you that scripts have changed and ask if you want to compile them.

Log Console
To enable the log console for debugging, you will need to add -log to the editors target as a parameter, so it should look something like this:

C:\UDK\UDK-2013-03\Binaries\Win32\UDK.exe editor -log

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

Game Types
http://udn.epicgames.com/Three/GametypeTechnicalGuide.html

GameInfo
This is also where you would want to start when making a mod from scratch. There are couple GameInfos you can extend off of to get your mod started: SimpleGame A generic GameInfo that will not handle re/spawning bots but will still spawn a default controller/pawn for the player. UTDeathMatch This GameInfo handles re/spawning players and bots in the game. It also has killspree announcements for players. it wll keep track of player kills and contains win/lose conditions related to time and kill counts. Why is Play on PC not using my custom controller/pawn? You will need to override the following function:
static event class<GameInfo> SetGameType(string MapName, string Options, string Portal) { return Default.Class; }

Putting this in your GameInfo that extends UTDeathMatch should override the SetGameType() function and use your default pawn/controller.

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

Objects
Every single UDK class is extend from the Object class or its children. Object contains many generic functions for math, which will be covered in a later section. Classes that extend off of Object are generally systems that maintain core technical systems such as animations and factories.

Data Structures
Object.uc contains lots of data structures used throughout the engine, the most important ones we will be using are Rotator and Vector.

Math Functions
Object.uc also contains all general math functionality related to vectors, trigonometry, interpolations, etc.

Actors
// Actor: The base class of all actors. // Actor is the base class of all gameplay objects. // A large number of properties, behaviors and interfaces are implemented in Actor, including: // // Display // Animation // Physics and world interaction // Making sounds // Networking properties // Actor creation and destruction // Actor iterator functions // Message broadcasting // // Copyright 1998-2013 Epic Games, Inc. All Rights Reserved.

Important Functions
simulated event PostBeginPlay() This is the initialization function that is triggered after the game has finished loading. event Tick(float DeltaTime) This is called every frame where DeltaTime is the time between the current frame and previous frame in seconds.

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

CollidingActors(...) This function is used to detect Actors within a radius of a location, and gets a reference to the actor. It generally used in iterations. Example { local Actor P; //You can use any other actor class and does not have to be Actor local Vector TempLoc; //This will iterate through every Actor class object within 128 Unreal Units //of the actor this is being called from and prints out their world location. foreach CollidingActor(classActor, P, 128); { `log(P.Location); } //This will iterate through every Actor class object within 128 Unreal Units //of the TempLoc. TempLoc is overriding where the detection should radiate from. foreach CollidingActor(classActor, P, 128, TempLoc); { `log(P.Location); } }

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

DefaultProperties
http://udn.epicgames.com/Three/UnrealScriptDefaultProperties.html Nearly all scripts will contain a DefaultProperties code block at the end of the script. This block is a focused section of the code to initialize values and to help non-programmers make modifications to values such as pawn health or speed.

Variables
http://udn.epicgames.com/Three/UnrealScriptVariables.html Unrealscript has their own way of declaring variables. The important keywords you should know are var and local. var is used for global declarations and local is used for declaring within the scope of a function. Unrealscript variables also follows the C-Style variable declarations in which variables must be declared at the beginning of the function and cannot be declared later.

Working with Rotations

UDK uses Rotators and Quaternions to represent their rotations. Their variables are declared as Rotator and Quat, respectively.

Rotator
Rotator values range between [0, 65536].

Converting Values Between Unreal Units, Radians, Degrees

Rotator values can be converted between Unreal Units (0 to 65536), radians, and degrees by multiplying them by the following constants: RadToDeg DegToRad UnrRotToRad RadToUnrRot DegToUnrRot UnrRotToDeg

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

Pawns
http://udn.epicgames.com/Three/CharactersTechnicalGuide.html

How to Change Skeletal Mesh

There are 2 ways to do this, one is easy, the other is hard but more robust. Easy Way Overload the function:
simulated function SetCharacterClassFromInfo(class<UTFamilyInfo> Info) { Mesh.SetSkeletalMesh(defaultMesh); Mesh.SetMaterial(0,defaultMaterial0); Mesh.SetPhysicsAsset(defaultPhysicsAsset); Mesh.AnimSets=defaultAnimSet; Mesh.SetAnimTreeTemplate(defaultAnimTree); }

Hard Way The hard way takes advantage of UDKs FamilyInfo system, which we most likely will not be diving into. If you are curious, you may refer to this UDK Documentation page: http://udn.epicgames.com/Three/UDKCustomCharacters.html

Controllers
http://udn.epicgames.com/Three/CharactersTechnicalGuide.html

Why isnt Tick() working?

Controllers use PlayerTick() instead of Tick() if they are in possession of a Pawn.

Artificial Intelligence (Bots)

http://udn.epicgames.com/Three/AIAndNavigationHome.html Bots can use the same pawns that players use, but they use a different controller made specifically for controlling a bot.

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

Razer Hydras
http://forums.epicgames.com/threads/937066-Razer-Hydra-Dll-Bind-Player-Input-and-PlayerController-Ready-to-go The Razer Hydras are hooked up into UDK using the scripts provided by Craig A. DeLancy. They handle and process raw input from the Razer Hydras.

Callback Functions

Razer Hydra button callbacks are located in the base Controller class provided by Craig A DeLancy.

Calibration
The Hydras need to be calibrated every time the game restarts by having the user point the Hydras towards the Hydra Base, then calling the function: sixenseAutoEnableHemisphereTracking( int HydraController ) from the RazerInput class, where HydraController = 0 is the left controller and 1 is the right controller. Warning: Failure to calibrate with the users pointing the Hydras at the Hydra Base may create undesirable results.

How to Track Hydra Positions

The Hydra Base is an origin point for the Hydras and it will maintain an XYZ position for the Hydras, which you can access through LeftJoyStick or RightJoyStick of the RazerInput class. This may not be desirable for our game because it defines an arbitrary position that the user must place the Hydra Base at. Our solution We will add a second step to calibration that will define a new point of origin for each hydra to reference. This can be done in a multitude of ways, but for now we are asking the user to place the controllers to the center of their chest and pull the triggers. Assuming the user can stay perfectly still, the center of their chest will be how we keep track of the point of origin for each controller. Hydra Units The Razer Hydra position units are about 10x the size of Unreals units, so their values need to be reduced to 10%.

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

Oculus Rift
Oculus data can be referenced by adding the following lines of code to your function or class: local Oculus OC; OC = class'Oculus'.static.GetGlobals();

Oculus Data
You can access the Oculus current rotation by calling OC.Rotation. Rotation is a UDK Rotator, so it can return values ranging from [-65536, 65536].

Controlling the Rifts Orientation

You can control the Rifts Orientation from the UpdateRotation() function in your player controller. Refer to UpdateRotation() in PlayerController.uc Why Cant I modify the Rifts Pitch? The current version of the Oculus UDK does not support this. Their reasoning is that its a very bad idea to modify their pitch without having the head input ask for it. This is unfortunate as it disables the ability to create flight simulators where pitching up/down should also pitch the players camera.

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

UDK Editor
Setting up Editor for Oculus Rift
The current released version of the Oculus UDK we are using at this time (v0.1) does not support running Oculus code in Play in Editor and only works in Play on PC. It also will not work with the 64-bit version of the editor.

Getting the 32-bit Editor

To get the 32-bit editor up and running to test with the Oculus, follow these steps: 1. Find your root UDK folder, then go to ...\Binaries\Win32 2. Create a shortcut to UDK.exe 3. Right click on the shortcut to UDK.exe and click on Properties 4. Add editor to the end of the target text field so it looks something like this: C:\UDK\UDK-2013-03\Binaries\Win32\UDK.exe editor 4.1.Optionally, and recommended, you can add -log to the end to enable console. 5. Now when you try to open the shortcut to UDK.exe, it will load the editor instead of the game.

Learning UDK Editor

If you want a strong overview of what the editor offers, then you may visit the following links to find video tutorials. You may also search online for hundreds of tutorials on how to use certain parts of the UDK editor.

Video Tutorials*
http://udn.epicgames.com/Three/VideoTutorials.html 3D Buzz 3D Buzz has a series of videos to teach you how to use the Unreal Development Kit editor at: http://www.3dbuzz.com/training/view/unreal-development-kit *Note: These videos are a couple years old and some features may have been deprecated or moved around.

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

Useful Hotkeys
Show/Hide Builder Brush Push B Snap Actor(s) to Nearest Floor Select actor(s) and push the End key. Focus on Actor(s) Select actor(s) and push the Home key.

Navigating Perspective Viewport

FPS Style Camera Movement
To get this movement, hold down right-click in the perspective viewport. You will then be able to move the camera around with WASD and change the camera look direction by moving the mouse. Increasing/Decreasing Camera Movement Speed While in FPS Camera mode, you can scroll the mousewheel to increase/decrease the speed of the camera.

Strafing the Camera

You can strafe the camera by holding down both left-click and right-click.

Moving the Camera Forwards/Backwards and Turning

You can move the camera forwards/backwards and turn it by holding down left-click.

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

Kismet
http://udn.epicgames.com/Three/KismetHome.html http://udn.epicgames.com/Three/KismetExamples.html Kismet is UDKs powerful visual scripting editor within the UDK Editor.

Sub-Sequences
Kismet Sub-Sequences are a useful way to organize your space. Sub-Sequences can be created by right-clicking anywhere in the current Kismet window and clicking on Create new sequence. Sub-sequences are also automatically generated when making a prefab of an object that uses a kismet sequence.

Useful Hotkeys
Quick Comment Block Have object(s) selected and push C This will prompt you to input a comment and will then create a comment box around the objects you selected. Drag Box to select multiple objects Ctrl + Alt + Left-Click Drag This will allow you to drag a box around multiple nodes and variables to select at once. Focus on Selected Objects Push A with objects selected, otherwise this will zoom the camera out to encompass all objects in the sequence. Select Multiple Objects One at a Time Hold Ctrl and click on an object.

Touch Triggers
Why isnt my KActor hitting the trigger? To make a KActor toggle a trigger: 1. You will need to go into the KActors properties and set no encroach check to false. This will enable encroaching for the KActor which will stop it from being ignored by certain collision detections, one of which is detecting collision with the trigger. 2. In the trigger node within Kismet, you will need to make sure the Touch Types > Class Proximity Types lists the KActors class type or one of its parents. 3. Make sure Sequence Event > Player Only is set to false.

Named Variables
http://udn.epicgames.com/Three/KismetUserGuide.html#Named Variables Named variables are very useful in Kismet as they allow the user to reference variables without having to create a link to them.

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

Matinee
http://udn.epicgames.com/Three/MatineeAndCinematicsHome.html http://www.youtube.com/watch?v=HUtbKqWcPkI (Matinee UI Tutorial) Matinee is a powerful tool for keyframing objects in the game. It can be used to create cutscenes and animations, but can also control when particles/lights flicker on/off.

Grouping Actors in Viewport

Grouping actors together in the viewport is a very handy tool that will allow the user to select all objects in a group by selecting one of them. This can significantly increase workflow by making it easier for designer to select multiple objects quickly and move them all together. To group actors, first select the actors you would like to group in the viewports. Next, right-click on one of the actors or on an empty space and select the Group Actors button.

Manipulating Individual Actors in a Group

To move an individual actor in a group, have the group selected and right-click one of the actors or on an empty space. Next, click on Groups > Unlock Groups. You will now be able to modify individually selected actors independent of the group. To put the group back together, select any actor in the group and right-click on the actor or on an epmty space. Next, click on Groups > Lock Groups.

Simplygon
http://udn.epicgames.com/Three/MeshSimplificationTool.html Simplygon is a powerful tool to lower LOD of meshes. This is very handy for us since we are using a low resolution Oculus devkit.

Cascade (Particle Editor)

http://udn.epicgames.com/Three/CascadeUserGuide.html http://udn.epicgames.com/Three/ParticleSystemReference.html UDK sports a very powerful particle editor with a bit of a learning curve. Here is a link to a 3DBuzz tutorial on using Cascade: http://www.youtube.com/watch?v=wTD0KQjxKPg

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.

Builder Brushes (BSP)

http://udn.epicgames.com/Three/UsingBspBrushes.html Builder Brushes in the editor make it very easy to block out levels very quickly in the UDK Editor. They are also used to define areas for other UDK volumes such as water or lava volumes. Many tutorials can be found online that cover this simple tool.

Geometry Mode
http://udn.epicgames.com/Three/UsingBspBrushes.html Geometry mode is a useful editor mode that allows the user to modify faces and vertices of BSPs.

Crash Warning!
Build Brushes do not like to be undone (ctrl+zd). Be careful when undoing builder brush adjustments with Geometry Mode as it may crash the editor and cause you to lose all unsaved progress.

Copyright 2013 DigiPen (USA) Corporation. All rights reserved.