-------------------------------------------------------------------------------- GOBLIN README -------------------------------------------------------------------------------- Created: 3/25/05 Updated: 3/05/07 Overview -------- Goblin, an architecture for building augmented reality, virtual reality, and 3D applications and games. Implemented using C# and Managed DirectX. See "Docs\Goblin Proposal.v1.2.doc" and "Docs\Goblin Requirements.doc" for details. There is currently one game, Botica, built using Goblin. You can download Botica from the Goblin website, http://www.cs.columbia.edu/~eaddy/goblin. Requirements ------------ o Windows XP o Microsoft DirectX 9.0c (required to run Goblin) o Microsoft .NET Framework 1.1.4322 or higher (required to run Goblin) o Microsoft Visual Studio .NET 2003/2005 (required to build Goblin) Anti-Requirements ----------------- Edit-and-Continue currently does not work for Goblin if it is compiled with Visual Studio.NET 2005. See Notes. Installation ------------ 1. Extract Goblin package (using WinZip or tar xzf Goblin.tar.gz) 2. Add \Common to your PATH (in System Properties->Advanced-> Environment Variables) 3. Run INSTALL.BAT Package Contents (THIS IS OUT OF DATE!) ---------------- \Goblin README.TXT - This file PACKLIST.TXT - List of files in package INSTALL.BAT - Registers Patcher.dll TEST.BAT - Launches Goblin and Notepad to allow the user to test EnC Goblin.vcproj - Goblin "Launcher" project \Engine - Goblin source code TEST.BAT - Launches Goblin with EnC enabled BUILD.BAT - Builds Goblin Patcher.log - Patcher log file (created when Goblin is run with EnC enabled) Watcher.log - Watcher log file (created when Goblin is run with EnC enabled) \BIN\DEBUG Goblin.exe - Goblin application Goblin.log - Goblin log file \Patcher - EnC Patcher source code (Unmanaged C++ COM object) README.TXT - Patcher readme ENABLE.BAT - (see below) DISABLE.BAT - (see below) ENABLE_BREAK.BAT - (see below) DISABLE_BREAK.BAT - (see below) BUILD.BAT - Builds Hello.* files and creates the bugreport files needed for EnC. Hello.cs - Simple console app (C#) Hello.vb - Simple console app (VB.NET) Hello.js - Simple console app (JScript.NET) Hello.jsl - Simple console app (J#) Hello.cpp - Simple console app (Managed C++) IlxLogSettings.xml - Log settings configuration file \DEBUG Patcher.dll - Patcher DLL \Watcher - EnC Watcher source code (C#) Watcher.exe - Watcher application Watcher.exe.config - All the CodeDomProviders we've ever heard of. This determines which languages EnC supports. We've only verified support for C#, VB.NET, and JScript.NET. \Common - Helper classes \ILXLog - Logging COM object \ILXCrashFinder - Obtains stack trace from C++ exception NOTE: Helper classes and projects under the "Common" directory are copyright ILX Systems/Thomson Financial. Redistribution of source code or binaries is not permitted. -------------------------------------------------------------------------------- Mapping Concerns in Goblin -------------------------- To help understand how concerns are separated and distributed in Goblin, we have annotated each program statement in the source code to indicate the features and requirements the statement implements. The following paper gives more details: Marc Eaddy, Alfred Aho, and Gail C. Murphy, "Identifying, Assigning, and Quantifying Crosscutting Concerns," in the ICSE Workshop on Assessment of Contemporary Modularization Techniques (ACoM 2007), Minneapolis, MN, May 22, 2007. We used statement annotation comments to annotate at the statement level. This is described by the following paper: Marc Eaddy and Alfred Aho, "Statement Annotations for Fine-Grained Advising," in Proceedings of the Third ECOOP Workshop on Reflection, AOP and Meta-Data for Software Evolution (RAM-SE 2006), Nantes, France, July 4, 2006. The Wicca# Compiler (wsc) can parse these statement annotations and generate the metrics described in the ACOM paper. Wsc is part of the Wicca package which you can download from http://www.cs.columbia.edu/~eaddy/wicca. Use the following command-line to generate the metrics (this will also build Goblin.Engine.dll): C:\PROJECTS\> wicca\bin\wsc.exe -nologo -concern:all -imgdir:"C:\temp\ConcernStats" -unsafe -r:"C:\WINDOWS\Microsoft.NET\DirectX for Managed Code\1.0.2902.0\Microsoft.DirectX.Direct3D.dll" -r:"C:\WINDOWS\Microsoft.NET\DirectX for Managed Code\1.0.2910.0\Microsoft.DirectX.Direct3DX.dll" -r:"C:\WINDOWS\Microsoft.NET\DirectX for Managed Code\1.0.2902.0\Microsoft.DirectX.dll" -r:C:\PROJECTS\Common\Columbia.Utilities.dll -r:C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\mscorlib.dll -r:C:\PROJECTS\Wicca\Morpher\bin\Phx.Aop.dll -r:C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.dll -r:C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.Drawing.dll -r:C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.Windows.Forms.dll -r:C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.Xml.dll Goblin\Engine\Engine.cs Goblin\Engine\D3DX\AssemblyInfo.cs Goblin\Engine\D3DX\dxmut.cs Goblin\Engine\D3DX\dxmutdata.cs Goblin\Engine\D3DX\dxmutenum.cs Goblin\Engine\D3DX\dxmutexception.cs Goblin\Engine\D3DX\dxmutgui.cs Goblin\Engine\D3DX\dxmutmesh.cs Goblin\Engine\D3DX\dxmutmisc.cs Goblin\Engine\D3DX\dxmutSettingsDlg.cs Goblin\Engine\Devices\InputDevice.cs Goblin\Engine\Devices\InputDeviceDriver.cs Goblin\Engine\Devices\InputDeviceMapper.cs Goblin\Engine\Devices\InputDevice_6DOF.cs Goblin\Engine\Devices\InterSense\InterSense.cs Goblin\Engine\Devices\InterSense\InterSenseSocket.cs Goblin\Engine\Devices\InterSense\InterSenseStation.cs Goblin\Engine\Devices\InterSense\ISDllBridge.cs Goblin\Engine\Physics\Collision.cs Goblin\Engine\Scene\Bounds.cs Goblin\Engine\Scene\MyMeshContainer.cs Goblin\Engine\Scene\SceneGraph.cs Goblin\Engine\Scene\Nodes\CameraNode.cs Goblin\Engine\Scene\Nodes\Node.cs Goblin\Engine\Scene\Transformers\AccelerationTransformer.cs Goblin\Engine\Scene\Transformers\CollisionSticker.cs Goblin\Engine\Scene\Transformers\CombinerTransformer.cs Goblin\Engine\Scene\Transformers\DXCameraTransformer.cs Goblin\Engine\Scene\Transformers\ICollisionListener.cs Goblin\Engine\Scene\Transformers\IgnoreCollision.cs Goblin\Engine\Scene\Transformers\InverterTransformer.cs Goblin\Engine\Scene\Transformers\TrackerTransformer.cs Goblin\Engine\Scene\Transformers\Transformer.cs Goblin\Engine\Scene\Transformers\VelocityTransformer.cs Goblin\Engine\Scene\Transformers\Xfrm.cs Goblin\Engine\Utilities\MyUtility.cs The above assumes you've unzipped Goblin in C:\PROJECTS\Goblin and Wicca in C:\PROJECTS\Wicca, and you've already built Wicca. The references aren't strictly necessary to obtain the concern statistics. Make sure you fix the paths for your machines. "wcs -help" will explain the command-line options. Testing Goblin and EnC ---------------------- 1. Run \TEST.BAT. This will launch Goblin and also opens Engine\Engine.cs in Notepad. The Goblin application window should appear, showing a 3D model of our Lab at Columbia and a spinning Tiger. 2. In Notepad, search (CTRL+F) for the "OnFrameRender" method. 3. In the call to device.clear(), modify the background color from 0x00000000 to 0x000000FF. 4. Save your changes (CTRL+S). After about a second, you should see the background color in Goblin change from black to blue. 5. In the "OnFrameMove" method, change the line from: aniFramiacs.rotationY(elapsedTime); to aniFramiacs.rotationY(elapsedTime*10); After about a second, you should see the tiger spinning 10 times faster than before. Enabling/Disabling EnC ---------------------- EnC is enabled by setting some environment variables. You should do this from a Command Prompt instead of setting them in System Properties or else EnC will be enabled for all managed/.NET processes on your machine. Enabling: 1. Run Patcher\ENABLE.BAT Disabling: 1. Run Patcher\DISABLE.BAT Calling ENABLE_BREAK.BAT causes Patcher to invoke the Just-In-Time Debugger via DebugBreak(). You can then put breakpoints in Patcher and debug. Enabling debugging: 1. Run Patcher\ENABLE_BREAK.BAT Disabling debugging 1. Run Patcher\DISABLE_BREAK.BAT Building the Projects --------------------- 1. Open Goblin.sln in Visual Studio .NET 2003. You may see some error prompts which you should be able to safely ignore. 2. In Visual Studio .NET 2003, add the following directory to Tools-> Options...->Projects->VC++ Directories->Executable files: \Common 3. Right click on Solution and select "Rebuild All" Troubleshooting --------------- Check Patcher.log and Watcher.log for errors. If you make a change to a source file that causes a compile error you'll see the error in Watcher.log. If you made a change that is not supported by Edit-and-Continue you'll see errors in Patcher.log. Optimizations ------------- 1. Collision Detection For LigerHunter, when many robots are displayed (~16) collision detection (CD) functions dominate the running time: IsRayColliding() - 11.9% IsCollision() - 9.1% A robot performs many CD checks: for determining its spawn point, collision detection, collision response, obtaining random waypoints, and for determining if the prey is in its line-of-sight (IsRayColliding). Solution: Reduce need for CD calls. For some reason, robots keep getting spawned inside other objects still causing them to be frozen in place. However, many CD calls are still getting made since it triggers the collision response. Fixing this will reduce the calls without any penalties. Solution: Reduce rate of non-mandatory CD calls. This might make the robot more sluggish and "dumber" since it won't adjust to things like collisions and tracking the prey as quickly. 2. DirectX GC Handles Using the DirectX Frame class causes many gcroot<> function calls to appear high in the running time list. Solution: Create our own Frame class. Notes ----- 1. If you modify the Goblin project make sure you synchronize the changes with BUILD.BAT. For example, if you add a source file you must update BUILD.BAT. 2. You should always build Goblin using BUILD.BAT before trying to use Edit- and-Continue to ensure that the Goblin.exe.bugreport file is up-to-date. 3. If you want to use a .NET profiler like Numega DevPartner Community Edition, you must rename or remove the following environment variables: COR_PROFILER COR_PROFILER_DLL Cor_Enable_Profiling These variables are needed to enable Edit-and-Continue but in setting these it prevents other "legitimate" profilers from working. 4. Edit-and-Continue will only work for Goblin if P5Glove.dll is built using the Managed C++ compiler from VS 2003, and if Goblin, Botica, and Engine are built from the command-line using the build.bat file, which uses the C# compiler v1.1. This is the only way to ensure that all refs target .NET v1.1. In addition, Watcher and its referenced assemblies (CSharpParser) must target .NET v1.1. If you install VS 2005, you won't be able to get EnC to work because the VC++ 2003 DLL will have been removed by the VS 2005 install and P5Glove.dll appears to depend on it. I keep getting: System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation. ---> System.IO.FileNotFoundException: File or assembly name P5Glove, or one of its dependencies, was not found. File name: "P5Glove" at Goblin.Apps.Botica..ctor() -------------------------------------------------------------------------------- Release Notes ------------- 1.1 --- x Annotated every statement in Engine to indicate what requirement it implements x Annotated every statement in Engine to indicate what feature it implements 1.0 ---- x Basic scene graph support x IS900/IS600 tracker support (direct and via network) x Device config file x 6DOF device abstraction x Application plug-ins x Transformers for controlling node motion x Basic pathfinding AI x Collision detection (ray/polygon, sphere/sphere, mesh/mesh) x Basic AR experience (Lab model, tracked head-worn display) x Basic AR game: "LigerHunter" x Edit-and-Continue support x Aspect-Oriented Programming support x Prototyped Aspect-Oriented Programming x Improve HMD registration x Cool application icon x AR rendering (real objects rendered black) x Simple AI node controller (ChaseAI) x Real objects occlude virtual objects x Hand gesture for firing crossbow x Support projectile weapon: "Crossbow" x Smarter AI x Application plugins x Support P5 Glove x Basic LigerHunter levels x Screenshot -------------------------------------------------------------------------------- TODO ---- o Goblin should be able to locate files by looking in the launch directory o Support monster: "Robotica" [Erik] [Game] x Find model x Add model to scene graph o Animations x Movement x Attacking x Death sequence o Audio o Movement o Menacing o Death o Impact marks x Projectile collision detection with Robot [Erik] o Audio and video feedback o Shadows o Robot fires laser at player's head x Multiple robots [John] x Configuration file [John] [Platform] o Assign tracker to node/cameras x Head-eye and other tracker transformations x ISenseServer network address o Miscellaneous [Platform] o Video overlay [Benko] o Stereo [Marc] o Lighting [Erik] Later... o Support multiple users [Benko] [Platform] x Aspect-Oriented Programming [Marc] [Platform] o Logging o Profiling o Distribution by sending C# code [Platform] o Dynamic script compilation [Platform] o Create object hierarchy [Platform] o Support for more devices [Platform] o Implement another prototype using Goblin [Platform] o Support melee weapon: "Light saber" [Game] o Find model o Add model to scene graph o Make Tracker #4 its controller o Support melee weapons: "Bullwhip", "Chainwhip", "Deadly Chinese Yo-Yo" [Game] o Support projectile weapons: "Throwing knives", "Paintball", "Snowballs", "Web", "Shurikan" [Game] o Support defense: "Dune shield" [Game] o Improve UI [Platform] o Voice recognition [Benko] o Gesture recognition [Benko] o 3D marking menus o Console overlay o Scene graph [Platform] o Remove CombinedTransformaions. Implement hierarchical transformations using Transformer. o Create graph traversal visitor method ala Studierstube (double dispatch) o Animation o Key frame o Skeletal o BSP tree o Bounding boxes o Visual culling o Collision detection o Networking [Platform] o Message-based o "Agent" messages o Plugins [Marc] [Platform] o Device plugins o Interface-based plugins o Autonomous plugins o Dynamically compiled -------------------------------------------------------------------------------- TODO for video -------------- o occlude player (so robots disappear when they are behind player) o update model (so it matches current lab setup) o have robots not collide (they spend too much time stuck together and not moving) o camera calibration (need better registration for camera, fov, tracker offset, etc.) o gun calibration o have robots chase player not camera (can switch between the two) o some bolts don't always hit the robot o some bolts don't stick into the wall properly (they appear to stick 'inside' the wall) o need ceiling for the lab so bolts don't go off into space o make it easy to setup the scene o Need sound -------------------------------------------------------------------------------- Credits ------- Hrvoje Benko (benko@cs.columbia.edu) Marc Eaddy (eaddy@cs.columbia.edu) Erik Peterson (edp2002@columbia.edu) John Waugh (jrw2005@columbia.edu) Sean White (swhite@cs.columbia.edu) IlxLog and IlxCrashFinder are copyrights of ILX Systems (Thomson Financial). Goblin icon courtesy of Juan Manzano (www.topicons.com) --------------------------------------------------------------------------------