TACWiki - User contributions [en]

Dev Setup

2009-09-07T20:51:55Z

Zinsser:

Follow these steps to run the development build of the game.

==System Requirements==

===Windows XP or Vista===

* Hardware:
** A graphics card that supports DirectX 9.0c and Shader Model 1.1 or newer.

* Software:
** [http://www.microsoft.com/downloads/details.aspx?FamilyID=2da43d38-db71-4c1b-bc6a-9b6652cd92a3&DisplayLang=en DirectX End-User Runtime 9.0c] or newer.
** [http://www.microsoft.com/express/download/ Microsoft Visual C# 2008 Express Edition] (the full version of Visual Studio 2008 should also work).
** [http://www.microsoft.com/downloads/details.aspx?FamilyID=0856eacb-4362-4b0d-8edd-aab15c5e04f5&DisplayLang=en Microsoft .NET Redistributable Version 2.0] (This may have already been installed by MSC#2008Express. If a newer version is already installed, that will likely be sufficient). Windows Vista users should find that this is already installed as part of the OS.)
** [http://www.microsoft.com/downloads/details.aspx?FamilyID=80782277-d584-42d2-8024-893fcd9d3e82&displaylang=en Microsoft XNA Game Studio 3.1].
** [http://tortoisesvn.net/downloads TortoiseSVN] (other Subversion clients will not work because the build system also uses SubWCRev, a tool included with TortoiseSVN)

===Other Systems===

XNA does not officially support non-Windows systems. See [http://www.mono-project.com/Main_Page Mono] and [http://groups.google.com/group/monoxna MonoXna] for assistance.

==Download the Code==

* Obtain a Subversion username and password from a Subversion Admin ([[User:Belmonte|Matthew Belmonte]]). The username will be used to track your changes to the code repository and the password will be known by all Subversion Admins.
* From within the Windows Explorer, check out the repository:
** Create a new directory, called "Autism Collaborative" for example.
** Right-click (or on a Macintosh running Windows, place two fingers on the trackpad and click) on the folder and select TortsoiseSVN->Checkout... from the context menu
** In the URL of repository field, enter http://www.AutismCollaborative.org/autism_collaborative/
** Click OK

==Run the Game==

New users of Visual Studio or similar IDE (Integrated Development Environment) should check out Microsoft's [http://msdn.microsoft.com/vstudio/express/beginner/ Online Learning Center].

==Troubleshooting==

If the code won't build/run at this point, check out the [[Troubleshooting]] page.

==Start Developing==

Read [[How to Make a Mini-Game]] to get started developing your own addition.

Check out the [[Code Overview]] for an explanation of how the code base works. It may also be helpful to visit the [[Code How To's]] for explanations of common coding tasks. And don't forget about the weekly [[Meetings]]!

2008-02-22T19:04:26Z

Zinsser:

This mode refers to the bulk of the game (or more accurately "toy") which is spent placing buildings.

==Premise==

In the future, humans have depleted nearly all natural resources from all accessible planet. As they slowly become a nomadic species, they rely more and more on colonies that float through space looking for new planets and life forms.

Play as a colony leader, whose job is to build and manage a city contained within a large spacecraft.

==Objective==

This is technically a toy, so there is no clear objective. Some players may attempt to make a large city which requires efficient placement of buildings. Others may strive to build specific structures and will need to first build their target's dependencies.

==Gameplay==

[[Image:ColonyMode_Mockup.png]]

'''As of Feb 2008, this gameplay spec is very old. Stay tuned for an up-to-date version!'''

The main city area is divided into a grid oriented at 45 degrees (to increase visibility). Buildings and units can occupy any number of whole squares. Each grid space may only host 1 structure, but may host as many units as necessary. The game is turn based, but there are multiple turns per second thus giving the game a real-time feel. Units can only move 1 space per turn and must wait a specific number of turns before moving again.

Upon starting a new game, the player is presented with an empty city. Resources are dispersed randomly (and count as structures). If the player has enough resources, (s)he can select a building and then place it on the map to instantly construct it. If the building comes with units, they are launched. A unit has 1 destination and travels along the least-cost path to its objective. Roads lower the cost of travel. Once it arrives, a unit remains at its objective for some randomized number of turns and then returns to its home structure. Citizens travel to work or recreational areas, harvesters travel to resources, transporters travel to industrial complexes, etc.

Certain structures generate resource income upon the return of their unit(s). This accounts for the majority of the player's resources. The one exception is money, which can only be generated by playing the minigames. All structures cost some amount of money, so minigames are inevitable. With minimal effort, a minigame will also reward a special building which is stored in a "Rewards" menu until placement in the city. Some minigames reward more than a structure and money, but these less rare rewards can also be earned through the existence of specific city structures.

Each building has construction costs and operational costs measured in units of various resources and utilities. See [[Structures]] and [[Consumables]]. If a structure's operational costs cannot be met, it shuts down and ceases launching its units. Buildings with harvester or transporter units will increase the player's resource stock each time the unit returns. For example, the Lumber Mill launches a harvester that travels to the nearest forest square and after some time returns to the mill thus increasing the player's supply of wood.

Most structures require certain utilities (see [[Structures]] for the list of utility plants). A meat-packing plant requires Electricity, for example. In order to operate, this plant must be within 3 grids of a Power Line or other powered structure.

The last dependency on structures are its employees. Each structure requires some number of staff and if the city does not have enough citizens then the each new structure does not operate. As the population grows, structures become operational on a first-built first-served basis.

Some structures output products (see [[Consumables]] for a complete list). Each product requires some number of consumables. Once these consumables are delivered, the structure makes one product and sends it to the appropriate location as a delivery or transport unit. The location is determined by the type of product. Food, for example, goes to shops whereas wheels may go to a car factory.

==User Interface==

The screen is divided into two major sections. The main area displays the city (with approximately 20x20 tiles visible). A menu bar sits on the right of the screen, approximately 2 inches wide. The menu bar contains buttons that are labeled graphically. When the user hovers over them, the name will appear over the cursor. The buttons are as follows: Build Structure, Build Line, Build Path, Place Reward, Budget, Sell, and Options. If a button is clicked, then a submenu pops out to the left of the main menu bar. This submenu contains a scrollable list of all placeable buildings within the selected category. Clicking on one of these brings up the building information in the bottom area of the main menu. With a specific building selected, the cursor is replaced by a transparent image of the building if the user mouses over the main city area. Clicking on a suitable location places that building in the colony.

When no building is selected in the submenu, the user can click on any placed structure to display its information in the bottom of the main menu. This information contains a picture of the building, and displays (with words and symbols) the build costs, operational costs, output, and units.

==Scoring==

Since there is no explicit victory, a player's score is essentially the various metrics such as colony asset value, resources, population (both human and android), approval rating, crime, etc. The player may also consider the colony's products to be their score, as some of the coolest products are very hard to obtain.

==Under the Hood==

This section outlines the algorithms/systems used in the colony mode. Part of the fun of this game is learning the interactions between all the game's systems and figuring out how to use them to get the kind of colony the user desires.

===Time===

There are two types of time: ''Game'' and ''Visual''. Both of them are directly proportional to real time * game speed. Visual time is used to make the colony look like it is going through day and night, and should move at the speed that looks the best. Game time determines how fast the colony's denizens act. The standard unit is 1 day.

===Pathfinding===

This is probably one of the colony's biggest technical hurdles. If thousands of units are allowed to wander around all willy-nilly the game may come to a screeching halt. Obviously, there will need to be a sophisticated searching algorithm that the units use (like IDA*) but that will be transparent to the user.

Fortunately, the game can place some constraints on unit movement to both lessen the burden of pathing AND make the placement of transportation buidlings/paths in the game more interesting!

====Paths====

The obvious first constraint: units are only allowed to move on paths placed by user. There may be some exceptions for gathering and/or service units, but they would use the paths to get as close to their destination as possible before moving onto open ground. The standard path is a simple road with sidewalks. Vehicles and pedestrians can use them simultaneously.

====Express Paths====

Just as most ''real'' people wouldn't be willing to take side-streets for very long distances, the colony's units will only use the standard roads for a certain distance before deeming the destination "too far" and deciding to go somewhere else (like another colony that's laid-out better!). Units will use standard roads to get to Express Paths (Freeways or Tubes (like the opening scene from Futurama)) and then when they leave the express paths (at user-placed exits) they will travel up to their willingness-to-travel-on-standard-paths distance.

This helps from a programming standpoint because the game can calculate paths from each express path exit to all of the buildings within some manhattan distance and store that as a graph for units to use when calculating travel routes.

====Hubs====

Public transportation can also help. Units may travel to a station (bus stop, train stop, teleporter?) and then travel from another station to their final destination. Note that using a hub means they will leave their vehicles behind and their willingness-to-travel-on-standard-paths distance may be much less once they leave the hub and must walk the rest of the way.

The coding benefit from hubs is very similar to Express Paths, but may require a unit to remember where it left its vehicle and then get back in it when returning to that hub.

Colony Mode

2008-02-22T18:15:27Z

Zinsser: /* Gameplay */

Code How To's

2008-02-15T17:28:30Z

Zinsser: /* Publish the Installer */

This page provides tutorials for some of the most common actions a programmer may wish to implement. It may helpful to read the [[Code Overview]] first.

==Submit a Bug or Other Issue==

* Login to BugHost.com
** Developers sign in with the email address "collaborators@autismcollaborative.org"
** Ask a developer for the password
* Click the Submit button on the top navigation bar
* Fill out the fields that apply to this issue

'''Type of Bug:'''
* Functional Problem
** Any actual "Bug"
* Suggestion
** A possible change to the game that may improve it
* New Feature
** Something that '''absolutely must''' be implemented
** Use sparingly; make sure it's not actually a Suggestion

'''Severity:'''
* How much this issue affects the game/application

'''Priority:'''
* How soon the issue should be resolved (relative to other issues)
* The majority of issues should be Low priority
* Use High sparingly

==Coding Conventions==

* Place the name of the file, authors, and copyright info at the top of each file
** Any person who makes significant changes to a file should add their name to the list of authors in a file
*** This helps anyone reading the code because they know who to ask if they have a question about something
* All private and protected class member variables are lowerCamelCase
* Private/protected class member variables are preceded with "m" (ie mLocalVariable)
* All functions, properties (sometimes called "smart fields"), and public class variables are UpperCamelCase
* Public variables should only be used with small classes that are only used by one or two other classes
* This code is intended to be viewed by many people who do not have strong programming backgrounds, therefore documentation is '''very''' important
** Document the purpose of each class's member variables, either next to their declaration or as a summary for their property accessor
** Create a summary documentation block for every function unless it is extremely obvious
*** This can be done by placing the cursor above a function definition and typing "///"
*** This block shows up in Intellisense when writing that function in code
** Add a summary to any properties that are possibly confusing or not straightforward
** Document every step of each algorithm (except for very obvious function calls like ResetSettings();)
*** Someone should be able to read only the comments in a function and still understand what it does
** See MeteorMadness.cs for an example of the appropriate level of documentation
* See the Load a Texture section for naming conventions of texture assets

==Create a New Minigame==

* Declare the class
** Create a new folder under ColonySimulator
** Create a new file in that folder named NewMinigame.cs where NewGame is the name of the new minigame
** Place all new minigame-specific classes in that folder
** Have the class derive from MiniGame
class NewGame : MiniGame {...}
* Implement the Constructor
** Initialize game variables
** Declare a ScoreCard (see Scoring tutorial)
** Log the GameBegin code (see the Logging tutorial)
* Implement Update()
public override void Update(ContentManager content){...}
** Do not assume a constant call rate
*** This function will almost always be called 60 times per second, but that rate may vary depending on CPU load
*** At the beginning of each cycle, get the time since the last cycle like this:
**** float dt = ColonyBaseApplication.GameManager.ElapsedSeconds;
**** '''DO NOT use XNA.Framework.GameTime.ElapsedGameTime''' because tAC_Engine implements update timing differently than a standard XNA application!
*** Build the time into all movement and timers, for example:
myEntity.LifeSpan -= dt;
myEntity.Position += myEntity.Velocity * dt;
* Implement Draw()
public override void Draw(SpriteBatch spriteBatch){...}
** Loop through all the game's entities and call their Draw() functions
** Consider using a generalized render-queue such as GenericWorldSpace '''(not-yet-implemented as of Oct 2007)'''
* Create a new game mode
** Add a new entry to ColonyBaseApplication.Modes = { ModeSelector, ColonySim, ...}
** Add the appropriate case to ColonyBaseApplication.SwitchMode(...)
** Add a new MiniGameInfo entry to ModeSelector.ModeSelector()
* End the game
** Flush the particle system (see the particles tutorial) if any emitters were created
** Log the GameEndSuccess/GameEndFailure code
** Flush the log (forces it to write any cached codes to disk)
** Show the score
** Switch the mode to ColonySim
ColonyBaseApplication.SwitchMode(ColonyBaseApplication.Modes.ColonySim);

==Use Images==

The tAC_Engine augments XNA's already great image support by automatically shrinking images based on a global Level Of Detail property. This means you can use it to load a graphic and the engine will automatically shrink its resolution if the Texture Detail settings are changed (via an in-game menu or a script) to Medium or Low (High retains the full resolution). This is more important for the main game since it will need to display a complex 3D scene, and minigames that just use a handful of sprites can essentially ignore this feature.

This is accomplished by discarding the first 0-2 mipmaps of an image. As a result, images without mipmaps (most "common" types like JPEG, PNG, GIF, TIFF) will always be loaded at their max resolution. For that reason, use DDS (or another XNA-supported mipmappable format) for 3D model textures. A DDS plugin for Photoshop is available at [http://developer.nvidia.com/object/nv_texture_tools.html NVidia's website].

To allow tAC_Engine to determine the appropriate resolution, each texture asset should be tagged with a "_Hi", "_Med", or "_Lo" as in "myImage_Hi.dds". If an image does not contain a detail tag at the end of its filename (before the extension) then the engine assumes it is at High resolution and will scale it down if the LOD property is Medium or lower. Most source images will have the "_Hi" tag, but some (like small objects or icons) may use the "_Med" or even "_Lo" setting to prevent the engine from downsampling them to the point where they are unrecognizable.

===Load a Texture===

'''DO NOT use XNA's ContentManager''' to load an asset in code unless you want the asset to ignore tAC_Engine.TextureManager.LOD property. The ContentManager should only be used in engine code when appropriate; games should always use the TextureManager.

But before you can load a texture in code you must add it to the content pipeline:

* Import the content into the project
** Browse to the appropriate folder in Visual Studio's Solution Explorer
*** For example, Content\MiniGames\MyImage.png
** Right click on that folder and select Add->Existing Item
** Select the image to import

Once that's done, you can load it memory with the TextureManager:

Texture2D myTexture = TextureManager.Load(@"Content\General\myTexture");

Do not include the "_Hi" (or "_Med" or "_Lo") naming convention or the file extension call to TextureManager.Load().

===Display a Static Image===

Before manually drawing something to screen consider using some type of game object, be it an Entity, HUD element, or even a Ticker (see the tutorials below). Game objects all know how to draw themselves, so it is unlikely that a minigame will need to draw something directly to the screen. Should the need arise, however, here's how it's done:

* Load it in code:
GraphicsDeviceManager gdm = ...; // This is declared in GenericGameManager.cs
ConentManager cm = ...; // Usually a parameter, as in Update(ContentManager content)
SpriteBatch sb = new SpriteBatch(gdm.GraphicsDevice); // Basically a wrapper for a DirectX render target
Texture2D texture = TextureManager.Load(@"Content\General\myTexture");
Rectangle destination = ...; // Display destination
Color tint = Color.White; // Tint the image with this color
float rotation = 0f; // Rotation (in radians)
Vector2 center = new Vector2(texture.Width / 2f, texture.Height / 2f); // Origin of rotation
float zDepth = 1f; // Order to draw sprites within this spritebatch

sb.Begin(SpriteBlendMode.AlphaBlend, SpriteSortMode.BackToFront, SaveStateMode.SaveState);

sb.Draw(
texture,
destination ,
null, // What part of the source image to sample from--null tells it to use the whole image
tint ,
rotation,
center,
SpriteEffects.None, // How to mirror the image
zDepth
);

sb.End();

===Display an Animation===

Animations are built into Entities. There are currently no plans to support animation in any other context. Here's an example:

Animation anim = new Animation(new Vector2(100, 100)); // Create an animation that is 100x100 pixels when displayed
anim.AddClip("Idle", content.Load<Texture2D>(@"Content/IdleSpriteSheet"), 5, 1f/60f); // a 500x100 spritesheet
anim.AddClip("Walk", content.Load<Texture2D>(@"Content/WalkSpriteSheet"), 12, 1f / 60f); // a 400x300 spritesheet
Entity ent = new Entity(anim, new Vector3(10f, 50f, 0f), new Vector3(100f, 100f, 0f)); // a 100x100 2D entity located at (10,50)

ent.Play("Idle"); // Start the idle animation
// ...
ent.Play("Walk"); // Switch to the walking animation
// ...
ent.Draw(sb); // Draw to the SpriteBatch sb

==Create a New Type of Game Object==

All specific game objects (players, enemies, collectibles, projectiles, etc.) should derive from Entity. This gives them easy ways to draw themselves, move, collide with other entities, and be passed to many tAC_Engine functions.

==Get User Input==

'''DO NOT''' use the standard XNA keyboard accessors (Xna.Framework.Input.KeyboardState or Xna.Framework.Input.Keyboard) or mouse accessors (Xna.Framework.Input.MouseState) because tAC_Engine does a lot of caching and logging behind the scenes. Use tAC_Engine.InputState instead.

===Keyboard===

if (InputState.IsKeyDown(Keys.A))
{
// The A key was pressed
}

===Mouse===

if (InputState.IsMouseLeftUp && InputState.WasMouseLeftDown)
{
// The mouse was just clicked (clicks are typically registered on the release, not the initial press)
}

Vector2 location = InputState.MouseLocation;

==Manage a Heads Up Display==

Use the HUD class for any HUD element (like health bars, menu buttons, etc.). Typically, you'll want to create a class that inherits from Widget2D. See MeteorWidgets.cs for examples.

==Display Text or Icons with the Ticker==

string text = "w00t."; // Text to display (can be "")
Texture2D image = null; // Can also be set to an image
Vector2 imageSize = new Vector2(25f, 25f); // Size of the (optional) icon
Vector2 offset = new Vector2(700f, 50f); // This will display the ticker 700 pixels to the right of the screen's
// center and 50 pixels below the screen's center
Vector2 velocity = new Vector2 (-10f, 0f); // Move left 10 pixels per second
Ticker.Font font = Ticker.Font.Standard; // Regular text
Color color = Color.DeepPink; // The manliest of colors
float opacity = .5f; // 50% transparent
float seconds = 5f; // Disappear after 5 seconds
bool fade = true; // Fade in and fade out

Ticker.Display(text, image, imageSize, offset, velocity, font, color, opacity, seconds, fade);

==Display Text Manually==

Most text displayed should be done using the Ticker, but if you really want to display text manually use the Nuclex font library (XNA now supports text, so the Nuclex library may eventually be removed). First you must import the desired font:

* Create an xml file for the new font called FontName.tffimport that looks like this:
<?xml version="1.0"?>
<TrueTypeImport>
<Path>Content\Fonts\MercuryII.ttf</Path>
<Size>32</Size>
</TrueTypeImport>
* Put the font (FontName.ttf) and FontName.tffimport in the Content\Fonts directory
* Set the following properties for FontName.ttf
** Build Action: None
** Copy to Output Directory: Copy if newer
** File Name: MercuryII.ttf
* Set the following properties for FontName.tffimport
** Build Action: Content
** Content Importer: TrueTypeFont - XNA Framework
** Content Processor: Bitmap Font - XNA Framework
** Copy to Output Directory: Do not copy
** XNA Framework Content: True

Now for the code:

ContentManager cm = ...;
SpriteBatch sb = ...;
BitmapFont bmf = cm.Load<BitmapFont>(@"Content\Fonts\Arial");
sb.Begin(SpriteBlendMode.AlphaBlend);
bmf.DrawString(new Vector2(10.0F, 10.0F), "Manual Text!", Color.Azure);
sb.End();

==Use Sound==

===Import a new Sound===

* Run Autism Collaborative\Utilities\XACT\Xact.exe
** This is the XACT tool from Microsoft DirectX SDK August 2006
** If--after following the steps in this tutorial--playing a file in code throws an exception about using the wrong version of XACT, try using Xact.exe from a different SDK build
* Open Autism Collaborative\Game\Game\Content\Sounds\AudioProject.xap
* Expand Wave Banks and double click Wave Bank in the panel on the left
* Expand Sound Banks and double click Sound Bank in the panel on the left
* Go to Wave Banks->Insert Wave File(s)...
* Select the file to import (Autism Collaborative\Game\Game\Content\Sounds\MySound.wav) and click OK
* Drag the newly-added file to the Cue Name section in the Sound Bank:Sound Bank window
* Go to File->Build
* Save and close XACT
* Open game.sln with Visual Studio
* Browse to the Content\Sounds folder in the Solution Explorer
* Right click the Sounds folder and select Add->Existing Item...
* Select MySound.wav and click OK

===Play a Sound===

Sound.Play("MySound"); // No file extension

==Use the Particle Engine==

Particles are handled by Sparx, a subset of the Pina library being developed alongside the Autism Game. Features are added to it on an as-needed basis so if a new feature '''is''' needed contact August or email support.

Particle Effects are imported via the content pipeline, so they can be called in a similar manner:

using Pina3D.Particles;

...

Emitter mRootEmitter;
mRootEmitter = Sparx.LoadParticleEffect(@"Content\Particle Effects\MyParticleEffect.spx");
Sparx.AddEmitter(mRootEmitter);

Don't forget to kill emitters when they are no longer needed.

mRootEmitter.Alive = false; // Kills the Emitter
Sparx.Flush(); // Kills all Emitters

Emitters can be moved around:

mRootEmitter.Position2D = new Vector2(100f, 100f); // Emitter will move, but existing Particles will not be affected

They can also move and keep their Particles in the same relative location.

// COMING SOON (this old code does not yet work with the new 3D particle system
//mRootEmitter.Transform = Matrix.CreateTranslation(100f, 100f, 0); // Particles will move with the Emitter

Any aspect of a Particle Effect can be changed at runtime. For example, to make an effect green add a Modifier:

mRootEmitter.RegularEmissionType.Modifiers.Add(new Modifier("whateverMyNameIs", 0f, 0f, Color.Green, Color.Green, 1f, 1f, 1f, 1f, 0f, 0f));

Or apply forces at runtime:

mRootEmitter.SubscribeEmissionsToForce(new Current("theWind", 0f, 0f, new Vector3(10f, 0f, 0f), 1f));

===Create a New Particle Effect===

This can be done entirely at runtime, however it is usually much easier (and more fun) to use they WYSIWYG editor SparxCreator3D. Please report any bugs to August or submit them to the bug database.

* Run Autism Collaborative\Utilities\SparxCreator3D.exe
* Make an effect
** Emitters can emit Emissions
** Emissions can be Particles or Emitters
** Modifiers can be applied to Emissions
** Forces can be applied to Emitters

Once an effect file is generated (MyEffect.spx) import it into the game to use it.

* In the Solution Explorer, browse to Content\Particle Effects
* Right click the folder and select Add->Existing Item...
* Select MyEffect.spx and click OK
* Change MyEffect.spx's Copy to Output Directory property to Copy Always

==Keep Score and Give Resources to the Simulator Mode==

Use the ScoreCard class to keep track of the score from a minigame. It provides easy ways to add and subtract resources, as well as an easy way to display them and pass them along to the Colony Simulator.

MiniGame has a ColonyScoreCard built into it, accessible by the Score property. Here are some examples of how to use it:

class MyGame : MiniGame
{
public override void Update(ContentManager content)
{
Score.Gather(ColonyResources.Money, 500); // Get 500 Monies

MyGameObject mgo = new MyGameObject();
mgo.GiveMyGameCarbon(); // Get 1 Carbon

Score.IncurDamageCost(100); // On CashOut, Money = Max (Money - DamageCosts, 0)

int HowMuchMoneyIHave = Score.QueryResource(ColonyResources.Money);
}

public void DisplayTheScore()
{
bool playerWonTheMinigame = true; // Can be set to false if the player lost
Score.Display(playerWonTheMinigame ); // Displays a copy of the current score and a message for succses/failure
Score.CashOut(); // Transfers resources from MyGame to the Colony Simulator
}

// ...
}

class MyGameObject : Entity
{
public void GiveMyGameCarbon()
{
ColonyBaseApplication.MiniGame.Score.Gather(ColonyResources.Carbon, 1);
}
}

==Write to the Experimental Log==

As the game runs, certain actions are recorded and written to a file (Autism Collaborative\Game\Game\bin\x86\Debug\ExperimentalLog.txt or the corresponding Release folder). In the lab, these codes are also sent through the parallel port to sync the EEG data. Every action that pertains to an experiment must be logged in order to be analyzed (that's kind of the whole point of this game!).

First define the necessary game codes.

* Open Logger.cs
* Add up to 253 codes to public enum ExperimentalCode
** All codes must start with a unique "code identifier", an underscore, and then a descriptor in UpperCamelCase
*** For minigames, the code identifier is 2 letters
** 3 codes are reserved for special parallel port functions with the software that runs the EEG machines used in lab tests

Now those codes are available for logging. Like so:

Logger.LogCode(Logger.ExperimentalCode.XX_Descriptor);

It is also possible to tell the logger to log a code every time a specific key is pressed:

InputState.Encode(Keys.A, InputState.KeyState.Down, Logger.ExperimentalCode.DEBUG_DudeJustPushedA);

Each minigame should remove the encodings when it is done, but it is also a good idea to decode the keys at the start of each minigame just in case.

InputState.Encode(Keys.A, InputState.KeyState.Down);
InputState.DecodeAll();

Every minigame should also start with its GameBegin and end with its GameEnd[Success/Failure] codes.

It may be helpful to log events for debugging purposes. These codes have the identifier "DEBUG" and will not be logged unless the game is running in Debug mode. All new DEBUG tags must be explicitly assigned a value less than 0.

==Use the Game Script==

The tAC_Engine houses a [[http://www.lua.org/ Lua]] Virtual Machine. This can be used to tweak global parameters at runtime, load them from config files, drive cutscenes, or even save and load levels.

Function callbacks are defined in C# and then invoked from a Lua file or the in-game Debug console. In other words, C# tells Lua "you may use these functions: X,Y,..." and then Lua says "do X, do Y, etc."

Here are a couple of ways to leverage this system:

===Make a Cutscene===

* Create a new lua file in the Scripts directory
** That file can call any registered function callbacks
* In the Properties window, set Copy to Output Directory to Copy if Newer
* Call that cutscene with:
GenericBaseApplication.GameManager.PlayCutscene(@"Scripts\MyCutscene.lua");

===To Register a Function Callback===

* Create the function in C# (if the function does not already exist)
** It must be declared public and non-static
** If the need arises to register a static function, declare an instanced function in GenericLuaHelper or ColonyLuaHelper that simply calls the static function.
* Register the function with the Lua Virtual Machine
** Add the special LuaCallback annotation to the function
* Call the RegisterLuaCallbacks function in the class's constructor that contains the function.
* Example:
public MyClass()
{ // Constructor
LuaHelper.RegisterLuaCallbacks(this);
}

[LuaCallback("SetMyVariable")]
public int SetMyVariable(int value)
{
mMyVariable = value;
}

===Tweak Game Parameters===

Exposing a variable to the Lua Virtual Machine allows it to be accessed by a any script (including config files) or changed at runtime in the drop down console (accessible in Debug mode by hitting "~").

* Expose a variable with a global setter/getter with a LuaCallback annotation
** Make sure to call the RegisterLuaCallbacks function in that class's constructor if the getter/setter is not in the Game Manager
* Set the default value for the variable in the config file (optional)
** There are 3 config files for the 3 configurations of the game builds
*** Debug.conf, for development
*** StandardRelease.conf, for public releases of the game
*** LabRelease.conf, for use in the lab

===Create Local Settings===

Programmers may want to change certain properties on their machines without affecting the source-controlled code. They could change the resolution, sound settings, or even have the game bypass the regular startup sequence and launch right into the middle of a MiniGame all with no effect on other developers.

* Create a new file: Autism Collaborative\Game\Game\Scripts\LocalSettings.lua
** The Visual Studio project already has this file included, but VS won't be able to edit it until the file is created manually
* Add Lua commands and save the file
** Visual Studio can now be used to edit the file
* The file is run at the end of the Debug.conf script (if it exists)
** That means that this script is only run in Debug mode
* do '''NOT''' add LocalSettings.lua to source control!

==Run the Game in the Lab==

To enable the features necessary to run the game in the lab, the file conlab.tac must exist next to the game's executable.

From visual studio:
* Change the configuration to "ReleaseLab"
* Build the solution
From a public release of the game:
* Find "constd.tac," the standard encrypted config file
* Copy "conlab.tac" to the same directory
** Autism Collaborative\Game\Game\bin\x86\Laboratory\conlab.tac is generated when the game is compiled
** If the game finds conlab, it assumes it is in the lab and uses that config file
** If conlab is not present, it assumes it is not in the lab and uses constd.tac as the config file

==Publish the Installer==

===Create the Installer===

We use InnoSetup to create the installer. Checkout their website (http://www.jrsoftware.org/isinfo.php) if you need to change the script, but simply publishing the game does not require any adjustment to the installer script.

* Install InnoSetup if necessary
** Run Autism Collaborative\Utilities\Installer Installer\isetup-5.2.2.exe
* Compile the installer script
** Open Autism Collaborative\Game\Game\Installer.iss with InnoSetup
** Goto Build->Compile
** Goto Run->Run
*** This creates the file Autism Collaborative\Game\Game\Output\tAC_Installer.exe

===Upload the Installer to the Web===

* Get a username/password for autismcollaborative.org from Matthew.
* Use a secure FTP client to login, such as WinSCP
** Either download it or run Autism Collaborative\Utilities\WinSCP.exe
* Login to autismcollaborative.org (port 22)
* Upload tAC_Installer.exe to your home directory (for example /home/zinsser)
** Do not overwrite the existing installer (/home/belmonte/autismcollaborative.org/downloads/AstropolisSetup.exe) since that would delete the installer from the website until the new installer finishes uploading (usually over an hour!)
* Once the upload is complete, enter the command "mv /home/zinsser/tAC_Installer.exe /home/belmonte/autismcollaborative.org/downloads/AstropolisSetup.exe" (you may have to open a terminal first, depending on your SFTP client)
** In the above command, substitute your username for "zinsser", but keep "belmonte" as the destination user directory
** If there is a permissions problem, contact Matthew to make sure your user has permission to the autismcollaborative.org directory!

==Use the ErrorLog==

When the game encounters an Unhandled Exception (like when an end user runs into a bug in our code), useful information is dumped to ErrorLog.txt. The user is encouraged to email that file to us so we can locate the problem they ran into. Although the ErrorLog will tell us what function the program died in, it cannot tell us specifically which line was the culprit (although ErrorLogs created when the game is running in Visual Studio will tell us exactly which line!).

We do, however, have the ability to log any custom information from a MiniGame. This may prove invaluable in debugging based on end-user error reports. All you (the programmer) must do is override the string MiniGame.DebugInfo() function. When ErrorLog.txt is created, it calls that function on the current MiniGame and appends the returned text to the bottom of the file.

Code How To's

2008-02-13T21:08:31Z

Zinsser:

This page provides tutorials for some of the most common actions a programmer may wish to implement. It may helpful to read the [[Code Overview]] first.

==Submit a Bug or Other Issue==

* Login to BugHost.com
** Developers sign in with the email address "collaborators@autismcollaborative.org"
** Ask a developer for the password
* Click the Submit button on the top navigation bar
* Fill out the fields that apply to this issue

'''Type of Bug:'''
* Functional Problem
** Any actual "Bug"
* Suggestion
** A possible change to the game that may improve it
* New Feature
** Something that '''absolutely must''' be implemented
** Use sparingly; make sure it's not actually a Suggestion

'''Severity:'''
* How much this issue affects the game/application

'''Priority:'''
* How soon the issue should be resolved (relative to other issues)
* The majority of issues should be Low priority
* Use High sparingly

==Coding Conventions==

* Place the name of the file, authors, and copyright info at the top of each file
** Any person who makes significant changes to a file should add their name to the list of authors in a file
*** This helps anyone reading the code because they know who to ask if they have a question about something
* All private and protected class member variables are lowerCamelCase
* Private/protected class member variables are preceded with "m" (ie mLocalVariable)
* All functions, properties (sometimes called "smart fields"), and public class variables are UpperCamelCase
* Public variables should only be used with small classes that are only used by one or two other classes
* This code is intended to be viewed by many people who do not have strong programming backgrounds, therefore documentation is '''very''' important
** Document the purpose of each class's member variables, either next to their declaration or as a summary for their property accessor
** Create a summary documentation block for every function unless it is extremely obvious
*** This can be done by placing the cursor above a function definition and typing "///"
*** This block shows up in Intellisense when writing that function in code
** Add a summary to any properties that are possibly confusing or not straightforward
** Document every step of each algorithm (except for very obvious function calls like ResetSettings();)
*** Someone should be able to read only the comments in a function and still understand what it does
** See MeteorMadness.cs for an example of the appropriate level of documentation
* See the Load a Texture section for naming conventions of texture assets

==Create a New Minigame==

* Declare the class
** Create a new folder under ColonySimulator
** Create a new file in that folder named NewMinigame.cs where NewGame is the name of the new minigame
** Place all new minigame-specific classes in that folder
** Have the class derive from MiniGame
class NewGame : MiniGame {...}
* Implement the Constructor
** Initialize game variables
** Declare a ScoreCard (see Scoring tutorial)
** Log the GameBegin code (see the Logging tutorial)
* Implement Update()
public override void Update(ContentManager content){...}
** Do not assume a constant call rate
*** This function will almost always be called 60 times per second, but that rate may vary depending on CPU load
*** At the beginning of each cycle, get the time since the last cycle like this:
**** float dt = ColonyBaseApplication.GameManager.ElapsedSeconds;
**** '''DO NOT use XNA.Framework.GameTime.ElapsedGameTime''' because tAC_Engine implements update timing differently than a standard XNA application!
*** Build the time into all movement and timers, for example:
myEntity.LifeSpan -= dt;
myEntity.Position += myEntity.Velocity * dt;
* Implement Draw()
public override void Draw(SpriteBatch spriteBatch){...}
** Loop through all the game's entities and call their Draw() functions
** Consider using a generalized render-queue such as GenericWorldSpace '''(not-yet-implemented as of Oct 2007)'''
* Create a new game mode
** Add a new entry to ColonyBaseApplication.Modes = { ModeSelector, ColonySim, ...}
** Add the appropriate case to ColonyBaseApplication.SwitchMode(...)
** Add a new MiniGameInfo entry to ModeSelector.ModeSelector()
* End the game
** Flush the particle system (see the particles tutorial) if any emitters were created
** Log the GameEndSuccess/GameEndFailure code
** Flush the log (forces it to write any cached codes to disk)
** Show the score
** Switch the mode to ColonySim
ColonyBaseApplication.SwitchMode(ColonyBaseApplication.Modes.ColonySim);

==Use Images==

The tAC_Engine augments XNA's already great image support by automatically shrinking images based on a global Level Of Detail property. This means you can use it to load a graphic and the engine will automatically shrink its resolution if the Texture Detail settings are changed (via an in-game menu or a script) to Medium or Low (High retains the full resolution). This is more important for the main game since it will need to display a complex 3D scene, and minigames that just use a handful of sprites can essentially ignore this feature.

This is accomplished by discarding the first 0-2 mipmaps of an image. As a result, images without mipmaps (most "common" types like JPEG, PNG, GIF, TIFF) will always be loaded at their max resolution. For that reason, use DDS (or another XNA-supported mipmappable format) for 3D model textures. A DDS plugin for Photoshop is available at [http://developer.nvidia.com/object/nv_texture_tools.html NVidia's website].

To allow tAC_Engine to determine the appropriate resolution, each texture asset should be tagged with a "_Hi", "_Med", or "_Lo" as in "myImage_Hi.dds". If an image does not contain a detail tag at the end of its filename (before the extension) then the engine assumes it is at High resolution and will scale it down if the LOD property is Medium or lower. Most source images will have the "_Hi" tag, but some (like small objects or icons) may use the "_Med" or even "_Lo" setting to prevent the engine from downsampling them to the point where they are unrecognizable.

===Load a Texture===

'''DO NOT use XNA's ContentManager''' to load an asset in code unless you want the asset to ignore tAC_Engine.TextureManager.LOD property. The ContentManager should only be used in engine code when appropriate; games should always use the TextureManager.

But before you can load a texture in code you must add it to the content pipeline:

* Import the content into the project
** Browse to the appropriate folder in Visual Studio's Solution Explorer
*** For example, Content\MiniGames\MyImage.png
** Right click on that folder and select Add->Existing Item
** Select the image to import

Once that's done, you can load it memory with the TextureManager:

Texture2D myTexture = TextureManager.Load(@"Content\General\myTexture");

Do not include the "_Hi" (or "_Med" or "_Lo") naming convention or the file extension call to TextureManager.Load().

===Display a Static Image===

Before manually drawing something to screen consider using some type of game object, be it an Entity, HUD element, or even a Ticker (see the tutorials below). Game objects all know how to draw themselves, so it is unlikely that a minigame will need to draw something directly to the screen. Should the need arise, however, here's how it's done:

* Load it in code:
GraphicsDeviceManager gdm = ...; // This is declared in GenericGameManager.cs
ConentManager cm = ...; // Usually a parameter, as in Update(ContentManager content)
SpriteBatch sb = new SpriteBatch(gdm.GraphicsDevice); // Basically a wrapper for a DirectX render target
Texture2D texture = TextureManager.Load(@"Content\General\myTexture");
Rectangle destination = ...; // Display destination
Color tint = Color.White; // Tint the image with this color
float rotation = 0f; // Rotation (in radians)
Vector2 center = new Vector2(texture.Width / 2f, texture.Height / 2f); // Origin of rotation
float zDepth = 1f; // Order to draw sprites within this spritebatch

sb.Begin(SpriteBlendMode.AlphaBlend, SpriteSortMode.BackToFront, SaveStateMode.SaveState);

sb.Draw(
texture,
destination ,
null, // What part of the source image to sample from--null tells it to use the whole image
tint ,
rotation,
center,
SpriteEffects.None, // How to mirror the image
zDepth
);

sb.End();

===Display an Animation===

Animations are built into Entities. There are currently no plans to support animation in any other context. Here's an example:

Animation anim = new Animation(new Vector2(100, 100)); // Create an animation that is 100x100 pixels when displayed
anim.AddClip("Idle", content.Load<Texture2D>(@"Content/IdleSpriteSheet"), 5, 1f/60f); // a 500x100 spritesheet
anim.AddClip("Walk", content.Load<Texture2D>(@"Content/WalkSpriteSheet"), 12, 1f / 60f); // a 400x300 spritesheet
Entity ent = new Entity(anim, new Vector3(10f, 50f, 0f), new Vector3(100f, 100f, 0f)); // a 100x100 2D entity located at (10,50)

ent.Play("Idle"); // Start the idle animation
// ...
ent.Play("Walk"); // Switch to the walking animation
// ...
ent.Draw(sb); // Draw to the SpriteBatch sb

==Create a New Type of Game Object==

All specific game objects (players, enemies, collectibles, projectiles, etc.) should derive from Entity. This gives them easy ways to draw themselves, move, collide with other entities, and be passed to many tAC_Engine functions.

==Get User Input==

'''DO NOT''' use the standard XNA keyboard accessors (Xna.Framework.Input.KeyboardState or Xna.Framework.Input.Keyboard) or mouse accessors (Xna.Framework.Input.MouseState) because tAC_Engine does a lot of caching and logging behind the scenes. Use tAC_Engine.InputState instead.

===Keyboard===

if (InputState.IsKeyDown(Keys.A))
{
// The A key was pressed
}

===Mouse===

if (InputState.IsMouseLeftUp && InputState.WasMouseLeftDown)
{
// The mouse was just clicked (clicks are typically registered on the release, not the initial press)
}

Vector2 location = InputState.MouseLocation;

==Manage a Heads Up Display==

Use the HUD class for any HUD element (like health bars, menu buttons, etc.). Typically, you'll want to create a class that inherits from Widget2D. See MeteorWidgets.cs for examples.

==Display Text or Icons with the Ticker==

string text = "w00t."; // Text to display (can be "")
Texture2D image = null; // Can also be set to an image
Vector2 imageSize = new Vector2(25f, 25f); // Size of the (optional) icon
Vector2 offset = new Vector2(700f, 50f); // This will display the ticker 700 pixels to the right of the screen's
// center and 50 pixels below the screen's center
Vector2 velocity = new Vector2 (-10f, 0f); // Move left 10 pixels per second
Ticker.Font font = Ticker.Font.Standard; // Regular text
Color color = Color.DeepPink; // The manliest of colors
float opacity = .5f; // 50% transparent
float seconds = 5f; // Disappear after 5 seconds
bool fade = true; // Fade in and fade out

Ticker.Display(text, image, imageSize, offset, velocity, font, color, opacity, seconds, fade);

==Display Text Manually==

Most text displayed should be done using the Ticker, but if you really want to display text manually use the Nuclex font library (XNA now supports text, so the Nuclex library may eventually be removed). First you must import the desired font:

* Create an xml file for the new font called FontName.tffimport that looks like this:
<?xml version="1.0"?>
<TrueTypeImport>
<Path>Content\Fonts\MercuryII.ttf</Path>
<Size>32</Size>
</TrueTypeImport>
* Put the font (FontName.ttf) and FontName.tffimport in the Content\Fonts directory
* Set the following properties for FontName.ttf
** Build Action: None
** Copy to Output Directory: Copy if newer
** File Name: MercuryII.ttf
* Set the following properties for FontName.tffimport
** Build Action: Content
** Content Importer: TrueTypeFont - XNA Framework
** Content Processor: Bitmap Font - XNA Framework
** Copy to Output Directory: Do not copy
** XNA Framework Content: True

Now for the code:

ContentManager cm = ...;
SpriteBatch sb = ...;
BitmapFont bmf = cm.Load<BitmapFont>(@"Content\Fonts\Arial");
sb.Begin(SpriteBlendMode.AlphaBlend);
bmf.DrawString(new Vector2(10.0F, 10.0F), "Manual Text!", Color.Azure);
sb.End();

==Use Sound==

===Import a new Sound===

* Run Autism Collaborative\Utilities\XACT\Xact.exe
** This is the XACT tool from Microsoft DirectX SDK August 2006
** If--after following the steps in this tutorial--playing a file in code throws an exception about using the wrong version of XACT, try using Xact.exe from a different SDK build
* Open Autism Collaborative\Game\Game\Content\Sounds\AudioProject.xap
* Expand Wave Banks and double click Wave Bank in the panel on the left
* Expand Sound Banks and double click Sound Bank in the panel on the left
* Go to Wave Banks->Insert Wave File(s)...
* Select the file to import (Autism Collaborative\Game\Game\Content\Sounds\MySound.wav) and click OK
* Drag the newly-added file to the Cue Name section in the Sound Bank:Sound Bank window
* Go to File->Build
* Save and close XACT
* Open game.sln with Visual Studio
* Browse to the Content\Sounds folder in the Solution Explorer
* Right click the Sounds folder and select Add->Existing Item...
* Select MySound.wav and click OK

===Play a Sound===

Sound.Play("MySound"); // No file extension

==Use the Particle Engine==

Particles are handled by Sparx, a subset of the Pina library being developed alongside the Autism Game. Features are added to it on an as-needed basis so if a new feature '''is''' needed contact August or email support.

Particle Effects are imported via the content pipeline, so they can be called in a similar manner:

using Pina3D.Particles;

...

Emitter mRootEmitter;
mRootEmitter = Sparx.LoadParticleEffect(@"Content\Particle Effects\MyParticleEffect.spx");
Sparx.AddEmitter(mRootEmitter);

Don't forget to kill emitters when they are no longer needed.

mRootEmitter.Alive = false; // Kills the Emitter
Sparx.Flush(); // Kills all Emitters

Emitters can be moved around:

mRootEmitter.Position2D = new Vector2(100f, 100f); // Emitter will move, but existing Particles will not be affected

They can also move and keep their Particles in the same relative location.

// COMING SOON (this old code does not yet work with the new 3D particle system
//mRootEmitter.Transform = Matrix.CreateTranslation(100f, 100f, 0); // Particles will move with the Emitter

Any aspect of a Particle Effect can be changed at runtime. For example, to make an effect green add a Modifier:

mRootEmitter.RegularEmissionType.Modifiers.Add(new Modifier("whateverMyNameIs", 0f, 0f, Color.Green, Color.Green, 1f, 1f, 1f, 1f, 0f, 0f));

Or apply forces at runtime:

mRootEmitter.SubscribeEmissionsToForce(new Current("theWind", 0f, 0f, new Vector3(10f, 0f, 0f), 1f));

===Create a New Particle Effect===

This can be done entirely at runtime, however it is usually much easier (and more fun) to use they WYSIWYG editor SparxCreator3D. Please report any bugs to August or submit them to the bug database.

* Run Autism Collaborative\Utilities\SparxCreator3D.exe
* Make an effect
** Emitters can emit Emissions
** Emissions can be Particles or Emitters
** Modifiers can be applied to Emissions
** Forces can be applied to Emitters

Once an effect file is generated (MyEffect.spx) import it into the game to use it.

* In the Solution Explorer, browse to Content\Particle Effects
* Right click the folder and select Add->Existing Item...
* Select MyEffect.spx and click OK
* Change MyEffect.spx's Copy to Output Directory property to Copy Always

==Keep Score and Give Resources to the Simulator Mode==

Use the ScoreCard class to keep track of the score from a minigame. It provides easy ways to add and subtract resources, as well as an easy way to display them and pass them along to the Colony Simulator.

MiniGame has a ColonyScoreCard built into it, accessible by the Score property. Here are some examples of how to use it:

class MyGame : MiniGame
{
public override void Update(ContentManager content)
{
Score.Gather(ColonyResources.Money, 500); // Get 500 Monies

MyGameObject mgo = new MyGameObject();
mgo.GiveMyGameCarbon(); // Get 1 Carbon

Score.IncurDamageCost(100); // On CashOut, Money = Max (Money - DamageCosts, 0)

int HowMuchMoneyIHave = Score.QueryResource(ColonyResources.Money);
}

public void DisplayTheScore()
{
bool playerWonTheMinigame = true; // Can be set to false if the player lost
Score.Display(playerWonTheMinigame ); // Displays a copy of the current score and a message for succses/failure
Score.CashOut(); // Transfers resources from MyGame to the Colony Simulator
}

// ...
}

class MyGameObject : Entity
{
public void GiveMyGameCarbon()
{
ColonyBaseApplication.MiniGame.Score.Gather(ColonyResources.Carbon, 1);
}
}

==Write to the Experimental Log==

As the game runs, certain actions are recorded and written to a file (Autism Collaborative\Game\Game\bin\x86\Debug\ExperimentalLog.txt or the corresponding Release folder). In the lab, these codes are also sent through the parallel port to sync the EEG data. Every action that pertains to an experiment must be logged in order to be analyzed (that's kind of the whole point of this game!).

First define the necessary game codes.

* Open Logger.cs
* Add up to 253 codes to public enum ExperimentalCode
** All codes must start with a unique "code identifier", an underscore, and then a descriptor in UpperCamelCase
*** For minigames, the code identifier is 2 letters
** 3 codes are reserved for special parallel port functions with the software that runs the EEG machines used in lab tests

Now those codes are available for logging. Like so:

Logger.LogCode(Logger.ExperimentalCode.XX_Descriptor);

It is also possible to tell the logger to log a code every time a specific key is pressed:

InputState.Encode(Keys.A, InputState.KeyState.Down, Logger.ExperimentalCode.DEBUG_DudeJustPushedA);

Each minigame should remove the encodings when it is done, but it is also a good idea to decode the keys at the start of each minigame just in case.

InputState.Encode(Keys.A, InputState.KeyState.Down);
InputState.DecodeAll();

Every minigame should also start with its GameBegin and end with its GameEnd[Success/Failure] codes.

It may be helpful to log events for debugging purposes. These codes have the identifier "DEBUG" and will not be logged unless the game is running in Debug mode. All new DEBUG tags must be explicitly assigned a value less than 0.

==Use the Game Script==

The tAC_Engine houses a [[http://www.lua.org/ Lua]] Virtual Machine. This can be used to tweak global parameters at runtime, load them from config files, drive cutscenes, or even save and load levels.

Function callbacks are defined in C# and then invoked from a Lua file or the in-game Debug console. In other words, C# tells Lua "you may use these functions: X,Y,..." and then Lua says "do X, do Y, etc."

Here are a couple of ways to leverage this system:

===Make a Cutscene===

* Create a new lua file in the Scripts directory
** That file can call any registered function callbacks
* In the Properties window, set Copy to Output Directory to Copy if Newer
* Call that cutscene with:
GenericBaseApplication.GameManager.PlayCutscene(@"Scripts\MyCutscene.lua");

===To Register a Function Callback===

* Create the function in C# (if the function does not already exist)
** It must be declared public and non-static
** If the need arises to register a static function, declare an instanced function in GenericLuaHelper or ColonyLuaHelper that simply calls the static function.
* Register the function with the Lua Virtual Machine
** Add the special LuaCallback annotation to the function
* Call the RegisterLuaCallbacks function in the class's constructor that contains the function.
* Example:
public MyClass()
{ // Constructor
LuaHelper.RegisterLuaCallbacks(this);
}

[LuaCallback("SetMyVariable")]
public int SetMyVariable(int value)
{
mMyVariable = value;
}

===Tweak Game Parameters===

Exposing a variable to the Lua Virtual Machine allows it to be accessed by a any script (including config files) or changed at runtime in the drop down console (accessible in Debug mode by hitting "~").

* Expose a variable with a global setter/getter with a LuaCallback annotation
** Make sure to call the RegisterLuaCallbacks function in that class's constructor if the getter/setter is not in the Game Manager
* Set the default value for the variable in the config file (optional)
** There are 3 config files for the 3 configurations of the game builds
*** Debug.conf, for development
*** StandardRelease.conf, for public releases of the game
*** LabRelease.conf, for use in the lab

===Create Local Settings===

Programmers may want to change certain properties on their machines without affecting the source-controlled code. They could change the resolution, sound settings, or even have the game bypass the regular startup sequence and launch right into the middle of a MiniGame all with no effect on other developers.

* Create a new file: Autism Collaborative\Game\Game\Scripts\LocalSettings.lua
** The Visual Studio project already has this file included, but VS won't be able to edit it until the file is created manually
* Add Lua commands and save the file
** Visual Studio can now be used to edit the file
* The file is run at the end of the Debug.conf script (if it exists)
** That means that this script is only run in Debug mode
* do '''NOT''' add LocalSettings.lua to source control!

==Run the Game in the Lab==

To enable the features necessary to run the game in the lab, the file conlab.tac must exist next to the game's executable.

From visual studio:
* Change the configuration to "ReleaseLab"
* Build the solution
From a public release of the game:
* Find "constd.tac," the standard encrypted config file
* Copy "conlab.tac" to the same directory
** Autism Collaborative\Game\Game\bin\x86\Laboratory\conlab.tac is generated when the game is compiled
** If the game finds conlab, it assumes it is in the lab and uses that config file
** If conlab is not present, it assumes it is not in the lab and uses constd.tac as the config file

==Publish the Installer==

===Create the Installer===

We use InnoSetup to create the installer. Checkout their website (http://www.jrsoftware.org/isinfo.php) if you need to change the script, but simply publishing the game does not require any adjustment to the installer script.

* Install InnoSetup if necessary
** Run Autism Collaborative\Utilities\Installer Installer\isetup-5.2.2.exe
* Compile the installer script
** Open Autism Collaborative\Game\Game\Installer.iss with InnoSetup
** Goto Build->Compile
** Goto Run->Run
*** This creates the file Autism Collaborative\Game\Game\Output\tAC_Installer.exe

===Upload the Installer to the Web===

* Get a username/password for autismcollaborative.org from Matthew.
* Use a secure FTP client to login, such as WinSCP
** Either download it or run Autism Collaborative\Utilities\WinSCP.exe
* Login to autismcollaborative.org (port 22)
* Upload tAC_Installer.exe to your home directory (for example \home\zinsser)
** Do not overwrite the existing installer (\home\belmonte\autismcollaborative.org\downloads\AstropolisSetup.exe) since that would delete the installer from the website until the new installer finishes uploading (usually over an hour!)
* Once the upload is complete, enter the command "mv \home\zinsser\tAC_Installer.exe \home\belmonte\autismcollaborative.org\downloads\AstropolisSetup.exe" (you may have to open a terminal first, depending on your SFTP client)
** In the above command, substitute your username for "zinsser", but keep "belmonte" as the destination user directory
** If there is a permissions problem, contact Matthew to make sure your user has permission to the autismcollaborative.org directory!

==Use the ErrorLog==

When the game encounters an Unhandled Exception (like when an end user runs into a bug in our code), useful information is dumped to ErrorLog.txt. The user is encouraged to email that file to us so we can locate the problem they ran into. Although the ErrorLog will tell us what function the program died in, it cannot tell us specifically which line was the culprit (although ErrorLogs created when the game is running in Visual Studio will tell us exactly which line!).

We do, however, have the ability to log any custom information from a MiniGame. This may prove invaluable in debugging based on end-user error reports. All you (the programmer) must do is override the string MiniGame.DebugInfo() function. When ErrorLog.txt is created, it calls that function on the current MiniGame and appends the returned text to the bottom of the file.

TODO List

2008-02-13T14:25:45Z

2008-02-11T15:25:25Z

Zinsser:

<big>'''Welcome to the Autism Game wiki'''</big>

This page is used by the developers working on Astropolis, a video game that collects scientific research. Here at the Autism Collaborative, we want to share both our findings and our processes with the public because we believe that is the most beneficial for everyone. As such, this wiki is a tool used by the Astropolis developers, but we encourage anyone interested in the project to explore and gain insight into our process for making the game.

==The Motivation==
'''Integrative studies of perception, attention, and social cognition in autism'''

Although much progress has been made identifying structural and functional profiles in autism, this work has resulted in a multiplicity of hypotheses targeted at particular brain or cognitive subsystems or levels of analysis; our most vexing problem often is not identifying the observational details, but assembling these details into a coherent theory. The division between social and non-social studies of autism is a case in point. Competing theories have construed autism variously as an exclusively social deficit in "theory of mind," an abnormality of attention and executive function with social and non-social consequences, an atypical weakness in "central coherence," or an enhancement of perceptual function. Although each of these views seems to capture a piece of the truth, a synthesis of all of them will not be possible as long as they continue to be approached as competing rather than synergistic views, as long as their psychological descriptions remain incompletely connected to neurobiological explanations and to clinical impairments, and as long as individual experiments continue to collect data germane to only one theory in isolation.

==The Strategy==
'''Embed a suite of psychological experiments within a video game that's fun to play'''

Perhaps the single most important obstacle to integrative studies of autism is the practical limit on the amount of time that a single experimental subject can reasonably be expected to perform before becoming fatigued. Unfortunately, often the more controlled a stimulus is from the scientist's point of view, the more repetitive and tedious the experiment can seem from the subject's point of view. Behavioural research on autism in recent years has highlighted the importance of motivation, behavioural set, and task instruction in establishing cognitive strategy and determining performance (e.g. Plaisted et al. 1999; Dalton et al. 2005). In light of these considerations, we propose to embed experimental stimuli in the context of a video game that captures and maintains subjects' interest, transparently collecting behavioural data and synchronising with physiological recording as the subject plays the game. The practical advantages of such an engaging and ecologically valid format over the usual repetitive blocks of trials are legion. Indeed, varying levels and demands of attentional shifting and multimodal integration are natural in the context of video game play, and psychophysical measures such as dot motion coherence and embedded figures are easily implemented as, for example, the movement of a star field on a view screen and the detection of an adversary in a cluttered environment. In addition, the strategic and adversarial nature of a video game carries natural opportunities to explore higher-level cognitive measures such as comprehension of game-related narratives and social attribution to a computer-generated adversary. The video game format is increasingly being used to acquire simultaneous behavioural and EEG observations in ecologically valid contexts, for example in visuomotor tracking (Smith et al. 1999), air traffic control (Brookings et al. 1996), and military command and control simulations (St John et al. 2002, 2004; Berka et al. 2004). Recent results in human-computer interaction (von Ahn 2006) also point to the power of the game context to establish and to maintain motivation in tasks that otherwise might not seem engaging, and to teach persons with developmental disorders (Golan & Baron-Cohen 2006). Also along these lines, the video game format affords subjects more of a chance to become comfortable with the task before entering the laboratory, minimising the potential confound of state anxiety associated with performance of an unfamiliar task in a testing situation.

==Major Sections==

[[Plot]]

[[Functional specifications]]

[[Meetings]]

[[Dev Setup]]

[[Code How To's]]

[[TODO List]]

Code How To's

2008-02-08T02:29:34Z

Zinsser: /* Create the Installer */

This page provides tutorials for some of the most common actions a programmer may wish to implement. It may helpful to read the [[Code Overview]] first.

==Submit a Bug or Other Issue==

* Login to BugHost.com
** Developers sign in with the email address "collaborators@autismcollaborative.org"
** Ask a developer for the password
* Click the Submit button on the top navigation bar
* Fill out the fields that apply to this issue

'''Type of Bug:'''
* Functional Problem
** Any actual "Bug"
* Suggestion
** A possible change to the game that may improve it
* New Feature
** Something that '''absolutely must''' be implemented
** Use sparingly; make sure it's not actually a Suggestion

'''Severity:'''
* How much this issue affects the game/application

'''Priority:'''
* How soon the issue should be resolved (relative to other issues)
* The majority of issues should be Low priority
* Use High sparingly

==Coding Conventions==

* Place the name of the file, authors, and copyright info at the top of each file
** Any person who makes significant changes to a file should add their name to the list of authors in a file
*** This helps anyone reading the code because they know who to ask if they have a question about something
* All private and protected class member variables are lowerCamelCase
* Private/protected class member variables are preceded with "m" (ie mLocalVariable)
* All functions, properties (sometimes called "smart fields"), and public class variables are UpperCamelCase
* Public variables should only be used with small classes that are only used by one or two other classes
* This code is intended to be viewed by many people who do not have strong programming backgrounds, therefore documentation is '''very''' important
** Document the purpose of each class's member variables, either next to their declaration or as a summary for their property accessor
** Create a summary documentation block for every function unless it is extremely obvious
*** This can be done by placing the cursor above a function definition and typing "///"
*** This block shows up in Intellisense when writing that function in code
** Add a summary to any properties that are possibly confusing or not straightforward
** Document every step of each algorithm (except for very obvious function calls like ResetSettings();)
*** Someone should be able to read only the comments in a function and still understand what it does
** See MeteorMadness.cs for an example of the appropriate level of documentation
* See the Load a Texture section for naming conventions of texture assets

==Create a New Minigame==

* Declare the class
** Create a new folder under ColonySimulator
** Create a new file in that folder named NewMinigame.cs where NewGame is the name of the new minigame
** Place all new minigame-specific classes in that folder
** Have the class derive from MiniGame
class NewGame : MiniGame {...}
* Implement the Constructor
** Initialize game variables
** Declare a ScoreCard (see Scoring tutorial)
** Log the GameBegin code (see the Logging tutorial)
* Implement Update()
public override void Update(ContentManager content){...}
** Do not assume a constant call rate
*** This function will almost always be called 60 times per second, but that rate may vary depending on CPU load
*** At the beginning of each cycle, get the time since the last cycle like this:
**** float dt = ColonyBaseApplication.GameManager.ElapsedSeconds;
**** '''DO NOT use XNA.Framework.GameTime.ElapsedGameTime''' because tAC_Engine implements update timing differently than a standard XNA application!
*** Build the time into all movement and timers, for example:
myEntity.LifeSpan -= dt;
myEntity.Position += myEntity.Velocity * dt;
* Implement Draw()
public override void Draw(SpriteBatch spriteBatch){...}
** Loop through all the game's entities and call their Draw() functions
** Consider using a generalized render-queue such as GenericWorldSpace '''(not-yet-implemented as of Oct 2007)'''
* Create a new game mode
** Add a new entry to ColonyBaseApplication.Modes = { ModeSelector, ColonySim, ...}
** Add the appropriate case to ColonyBaseApplication.SwitchMode(...)
** Add a new MiniGameInfo entry to ModeSelector.ModeSelector()
* End the game
** Flush the particle system (see the particles tutorial) if any emitters were created
** Log the GameEndSuccess/GameEndFailure code
** Flush the log (forces it to write any cached codes to disk)
** Show the score
** Switch the mode to ColonySim
ColonyBaseApplication.SwitchMode(ColonyBaseApplication.Modes.ColonySim);

==Use Images==

The tAC_Engine augments XNA's already great image support by automatically shrinking images based on a global Level Of Detail property. This means you can use it to load a graphic and the engine will automatically shrink its resolution if the Texture Detail settings are changed (via an in-game menu or a script) to Medium or Low (High retains the full resolution). This is more important for the main game since it will need to display a complex 3D scene, and minigames that just use a handful of sprites can essentially ignore this feature.

This is accomplished by discarding the first 0-2 mipmaps of an image. As a result, images without mipmaps (most "common" types like JPEG, PNG, GIF, TIFF) will always be loaded at their max resolution. For that reason, use DDS (or another XNA-supported mipmappable format) for 3D model textures. A DDS plugin for Photoshop is available at [http://developer.nvidia.com/object/nv_texture_tools.html NVidia's website].

To allow tAC_Engine to determine the appropriate resolution, each texture asset should be tagged with a "_Hi", "_Med", or "_Lo" as in "myImage_Hi.dds". If an image does not contain a detail tag at the end of its filename (before the extension) then the engine assumes it is at High resolution and will scale it down if the LOD property is Medium or lower. Most source images will have the "_Hi" tag, but some (like small objects or icons) may use the "_Med" or even "_Lo" setting to prevent the engine from downsampling them to the point where they are unrecognizable.

===Load a Texture===

'''DO NOT use XNA's ContentManager''' to load an asset in code unless you want the asset to ignore tAC_Engine.TextureManager.LOD property. The ContentManager should only be used in engine code when appropriate; games should always use the TextureManager.

But before you can load a texture in code you must add it to the content pipeline:

* Import the content into the project
** Browse to the appropriate folder in Visual Studio's Solution Explorer
*** For example, Content\MiniGames\MyImage.png
** Right click on that folder and select Add->Existing Item
** Select the image to import

Once that's done, you can load it memory with the TextureManager:

Texture2D myTexture = TextureManager.Load(@"Content\General\myTexture");

Do not include the "_Hi" (or "_Med" or "_Lo") naming convention or the file extension call to TextureManager.Load().

===Display a Static Image===

Before manually drawing something to screen consider using some type of game object, be it an Entity, HUD element, or even a Ticker (see the tutorials below). Game objects all know how to draw themselves, so it is unlikely that a minigame will need to draw something directly to the screen. Should the need arise, however, here's how it's done:

* Load it in code:
GraphicsDeviceManager gdm = ...; // This is declared in GenericGameManager.cs
ConentManager cm = ...; // Usually a parameter, as in Update(ContentManager content)
SpriteBatch sb = new SpriteBatch(gdm.GraphicsDevice); // Basically a wrapper for a DirectX render target
Texture2D texture = TextureManager.Load(@"Content\General\myTexture");
Rectangle destination = ...; // Display destination
Color tint = Color.White; // Tint the image with this color
float rotation = 0f; // Rotation (in radians)
Vector2 center = new Vector2(texture.Width / 2f, texture.Height / 2f); // Origin of rotation
float zDepth = 1f; // Order to draw sprites within this spritebatch

sb.Begin(SpriteBlendMode.AlphaBlend, SpriteSortMode.BackToFront, SaveStateMode.SaveState);

sb.Draw(
texture,
destination ,
null, // What part of the source image to sample from--null tells it to use the whole image
tint ,
rotation,
center,
SpriteEffects.None, // How to mirror the image
zDepth
);

sb.End();

===Display an Animation===

Animations are built into Entities. There are currently no plans to support animation in any other context. Here's an example:

Animation anim = new Animation(new Vector2(100, 100)); // Create an animation that is 100x100 pixels when displayed
anim.AddClip("Idle", content.Load<Texture2D>(@"Content/IdleSpriteSheet"), 5, 1f/60f); // a 500x100 spritesheet
anim.AddClip("Walk", content.Load<Texture2D>(@"Content/WalkSpriteSheet"), 12, 1f / 60f); // a 400x300 spritesheet
Entity ent = new Entity(anim, new Vector3(10f, 50f, 0f), new Vector3(100f, 100f, 0f)); // a 100x100 2D entity located at (10,50)

ent.Play("Idle"); // Start the idle animation
// ...
ent.Play("Walk"); // Switch to the walking animation
// ...
ent.Draw(sb); // Draw to the SpriteBatch sb

==Create a New Type of Game Object==

All specific game objects (players, enemies, collectibles, projectiles, etc.) should derive from Entity. This gives them easy ways to draw themselves, move, collide with other entities, and be passed to many tAC_Engine functions.

==Get User Input==

'''DO NOT''' use the standard XNA keyboard accessors (Xna.Framework.Input.KeyboardState or Xna.Framework.Input.Keyboard) or mouse accessors (Xna.Framework.Input.MouseState) because tAC_Engine does a lot of caching and logging behind the scenes. Use tAC_Engine.InputState instead.

===Keyboard===

if (InputState.IsKeyDown(Keys.A))
{
// The A key was pressed
}

===Mouse===

if (InputState.IsMouseLeftUp && InputState.WasMouseLeftDown)
{
// The mouse was just clicked (clicks are typically registered on the release, not the initial press)
}

Vector2 location = InputState.MouseLocation;

==Manage a Heads Up Display==

Use the HUD class for any HUD element (like health bars, menu buttons, etc.). Typically, you'll want to create a class that inherits from Widget2D. See MeteorWidgets.cs for examples.

==Display Text or Icons with the Ticker==

string text = "w00t."; // Text to display (can be "")
Texture2D image = null; // Can also be set to an image
Vector2 imageSize = new Vector2(25f, 25f); // Size of the (optional) icon
Vector2 offset = new Vector2(700f, 50f); // This will display the ticker 700 pixels to the right of the screen's
// center and 50 pixels below the screen's center
Vector2 velocity = new Vector2 (-10f, 0f); // Move left 10 pixels per second
Ticker.Font font = Ticker.Font.Standard; // Regular text
Color color = Color.DeepPink; // The manliest of colors
float opacity = .5f; // 50% transparent
float seconds = 5f; // Disappear after 5 seconds
bool fade = true; // Fade in and fade out

Ticker.Display(text, image, imageSize, offset, velocity, font, color, opacity, seconds, fade);

==Display Text Manually==

Most text displayed should be done using the Ticker, but if you really want to display text manually use the Nuclex font library (XNA now supports text, so the Nuclex library may eventually be removed). First you must import the desired font:

* Create an xml file for the new font called FontName.tffimport that looks like this:
<?xml version="1.0"?>
<TrueTypeImport>
<Path>Content\Fonts\MercuryII.ttf</Path>
<Size>32</Size>
</TrueTypeImport>
* Put the font (FontName.ttf) and FontName.tffimport in the Content\Fonts directory
* Set the following properties for FontName.ttf
** Build Action: None
** Copy to Output Directory: Copy if newer
** File Name: MercuryII.ttf
* Set the following properties for FontName.tffimport
** Build Action: Content
** Content Importer: TrueTypeFont - XNA Framework
** Content Processor: Bitmap Font - XNA Framework
** Copy to Output Directory: Do not copy
** XNA Framework Content: True

Now for the code:

ContentManager cm = ...;
SpriteBatch sb = ...;
BitmapFont bmf = cm.Load<BitmapFont>(@"Content\Fonts\Arial");
sb.Begin(SpriteBlendMode.AlphaBlend);
bmf.DrawString(new Vector2(10.0F, 10.0F), "Manual Text!", Color.Azure);
sb.End();

==Use Sound==

===Import a new Sound===

* Run Autism Collaborative\Utilities\XACT\Xact.exe
** This is the XACT tool from Microsoft DirectX SDK August 2006
** If--after following the steps in this tutorial--playing a file in code throws an exception about using the wrong version of XACT, try using Xact.exe from a different SDK build
* Open Autism Collaborative\Game\Game\Content\Sounds\AudioProject.xap
* Expand Wave Banks and double click Wave Bank in the panel on the left
* Expand Sound Banks and double click Sound Bank in the panel on the left
* Go to Wave Banks->Insert Wave File(s)...
* Select the file to import (Autism Collaborative\Game\Game\Content\Sounds\MySound.wav) and click OK
* Drag the newly-added file to the Cue Name section in the Sound Bank:Sound Bank window
* Go to File->Build
* Save and close XACT
* Open game.sln with Visual Studio
* Browse to the Content\Sounds folder in the Solution Explorer
* Right click the Sounds folder and select Add->Existing Item...
* Select MySound.wav and click OK

===Play a Sound===

Sound.Play("MySound"); // No file extension

==Use the Particle Engine==

Particles are handled by Sparx, a subset of the Pina library being developed alongside the Autism Game. Features are added to it on an as-needed basis so if a new feature '''is''' needed contact August or email support.

Particle Effects are imported via the content pipeline, so they can be called in a similar manner:

using Pina3D.Particles;

...

Emitter mRootEmitter;
mRootEmitter = Sparx.LoadParticleEffect(@"Content\Particle Effects\MyParticleEffect.spx");
Sparx.AddEmitter(mRootEmitter);

Don't forget to kill emitters when they are no longer needed.

mRootEmitter.Alive = false; // Kills the Emitter
Sparx.Flush(); // Kills all Emitters

Emitters can be moved around:

mRootEmitter.Position2D = new Vector2(100f, 100f); // Emitter will move, but existing Particles will not be affected

They can also move and keep their Particles in the same relative location.

// COMING SOON (this old code does not yet work with the new 3D particle system
//mRootEmitter.Transform = Matrix.CreateTranslation(100f, 100f, 0); // Particles will move with the Emitter

Any aspect of a Particle Effect can be changed at runtime. For example, to make an effect green add a Modifier:

mRootEmitter.RegularEmissionType.Modifiers.Add(new Modifier("whateverMyNameIs", 0f, 0f, Color.Green, Color.Green, 1f, 1f, 1f, 1f, 0f, 0f));

Or apply forces at runtime:

mRootEmitter.SubscribeEmissionsToForce(new Current("theWind", 0f, 0f, new Vector3(10f, 0f, 0f), 1f));

===Create a New Particle Effect===

This can be done entirely at runtime, however it is usually much easier (and more fun) to use they WYSIWYG editor SparxCreator3D. Please report any bugs to August or submit them to the bug database.

* Run Autism Collaborative\Utilities\SparxCreator3D.exe
* Make an effect
** Emitters can emit Emissions
** Emissions can be Particles or Emitters
** Modifiers can be applied to Emissions
** Forces can be applied to Emitters

Once an effect file is generated (MyEffect.spx) import it into the game to use it.

* In the Solution Explorer, browse to Content\Particle Effects
* Right click the folder and select Add->Existing Item...
* Select MyEffect.spx and click OK
* Change MyEffect.spx's Copy to Output Directory property to Copy Always

==Keep Score and Give Resources to the Simulator Mode==

Use the ScoreCard class to keep track of the score from a minigame. It provides easy ways to add and subtract resources, as well as an easy way to display them and pass them along to the Colony Simulator.

MiniGame has a ColonyScoreCard built into it, accessible by the Score property. Here are some examples of how to use it:

class MyGame : MiniGame
{
public override void Update(ContentManager content)
{
Score.Gather(ColonyResources.Money, 500); // Get 500 Monies

MyGameObject mgo = new MyGameObject();
mgo.GiveMyGameCarbon(); // Get 1 Carbon

Score.IncurDamageCost(100); // On CashOut, Money = Max (Money - DamageCosts, 0)

int HowMuchMoneyIHave = Score.QueryResource(ColonyResources.Money);
}

public void DisplayTheScore()
{
bool playerWonTheMinigame = true; // Can be set to false if the player lost
Score.Display(playerWonTheMinigame ); // Displays a copy of the current score and a message for succses/failure
Score.CashOut(); // Transfers resources from MyGame to the Colony Simulator
}

// ...
}

class MyGameObject : Entity
{
public void GiveMyGameCarbon()
{
ColonyBaseApplication.MiniGame.Score.Gather(ColonyResources.Carbon, 1);
}
}

==Write to the Experimental Log==

As the game runs, certain actions are recorded and written to a file (Autism Collaborative\Game\Game\bin\x86\Debug\ExperimentalLog.txt or the corresponding Release folder). In the lab, these codes are also sent through the parallel port to sync the EEG data. Every action that pertains to an experiment must be logged in order to be analyzed (that's kind of the whole point of this game!).

First define the necessary game codes.

* Open Logger.cs
* Add up to 253 codes to public enum ExperimentalCode
** All codes must start with a unique "code identifier", an underscore, and then a descriptor in UpperCamelCase
*** For minigames, the code identifier is 2 letters
** 3 codes are reserved for special parallel port functions with the software that runs the EEG machines used in lab tests

Now those codes are available for logging. Like so:

Logger.LogCode(Logger.ExperimentalCode.XX_Descriptor);

It is also possible to tell the logger to log a code every time a specific key is pressed:

InputState.Encode(Keys.A, InputState.KeyState.Down, Logger.ExperimentalCode.DEBUG_DudeJustPushedA);

Each minigame should remove the encodings when it is done, but it is also a good idea to decode the keys at the start of each minigame just in case.

InputState.Encode(Keys.A, InputState.KeyState.Down);
InputState.DecodeAll();

Every minigame should also start with its GameBegin and end with its GameEnd[Success/Failure] codes.

It may be helpful to log events for debugging purposes. These codes have the identifier "DEBUG" and will not be logged unless the game is running in Debug mode. All new DEBUG tags must be explicitly assigned a value less than 0.

==Use the Game Script==

The tAC_Engine houses a [[http://www.lua.org/ Lua]] Virtual Machine. This can be used to tweak global parameters at runtime, load them from config files, drive cutscenes, or even save and load levels.

Function callbacks are defined in C# and then invoked from a Lua file or the in-game Debug console. In other words, C# tells Lua "you may use these functions: X,Y,..." and then Lua says "do X, do Y, etc."

Here are a couple of ways to leverage this system:

===Make a Cutscene===

* Create a new lua file in the Scripts directory
** That file can call any registered function callbacks
* In the Properties window, set Copy to Output Directory to Copy if Newer
* Call that cutscene with:
GenericBaseApplication.GameManager.PlayCutscene(@"Scripts\MyCutscene.lua");

===To Register a Function Callback===

* Create the function in C# (if the function does not already exist)
** It must be declared public and non-static
** If the need arises to register a static function, declare an instanced function in GenericLuaHelper or ColonyLuaHelper that simply calls the static function.
* Register the function with the Lua Virtual Machine
** Add the special LuaCallback annotation to the function
* Call the RegisterLuaCallbacks function in the class's constructor that contains the function.
* Example:
public MyClass()
{ // Constructor
LuaHelper.RegisterLuaCallbacks(this);
}

[LuaCallback("SetMyVariable")]
public int SetMyVariable(int value)
{
mMyVariable = value;
}

===Tweak Game Parameters===

Exposing a variable to the Lua Virtual Machine allows it to be accessed by a any script (including config files) or changed at runtime in the drop down console (accessible in Debug mode by hitting "~").

* Expose a variable with a global setter/getter with a LuaCallback annotation
** Make sure to call the RegisterLuaCallbacks function in that class's constructor if the getter/setter is not in the Game Manager
* Set the default value for the variable in the config file (optional)
** There are 3 config files for the 3 configurations of the game builds
*** Debug.conf, for development
*** StandardRelease.conf, for public releases of the game
*** LabRelease.conf, for use in the lab

===Create Local Settings===

Programmers may want to change certain properties on their machines without affecting the source-controlled code. They could change the resolution, sound settings, or even have the game bypass the regular startup sequence and launch right into the middle of a MiniGame all with no effect on other developers.

* Create a new file: Autism Collaborative\Game\Game\Scripts\LocalSettings.lua
** The Visual Studio project already has this file included, but VS won't be able to edit it until the file is created manually
* Add Lua commands and save the file
** Visual Studio can now be used to edit the file
* The file is run at the end of the Debug.conf script (if it exists)
** That means that this script is only run in Debug mode
* do '''NOT''' add LocalSettings.lua to source control!

==Run the Game in the Lab==

To enable the features necessary to run the game in the lab, the file conlab.tac must exist next to the game's executable.

From visual studio:
* Change the configuration to "ReleaseLab"
* Build the solution
From a public release of the game:
* Find "constd.tac," the standard encrypted config file
* Copy "conlab.tac" to the same directory
** Autism Collaborative\Game\Game\bin\x86\Laboratory\conlab.tac is generated when the game is compiled
** If the game finds conlab, it assumes it is in the lab and uses that config file
** If conlab is not present, it assumes it is not in the lab and uses constd.tac as the config file

==Publish the Installer==

===Create the Installer===

We use InnoSetup to create the installer. Checkout their website (http://www.jrsoftware.org/isinfo.php) if you need to change the script, but simply publishing the game does not require any adjustment to the installer script.

* Install InnoSetup if necessary
** Run Autism Collaborative\Utilities\Installer Installer\isetup-5.2.2.exe
* Compile the installer script
** Open Autism Collaborative\Game\Game\Installer.iss with InnoSetup
** Goto Build->Compile
** Goto Run->Run
*** This creates the file Autism Collaborative\Game\Game\Output\tAC_Installer.exe

===Upload the Installer to the Web===

* Get a username/password for autismcollaborative.org from Matthew.
* Use a secure FTP client to login, such as WinSCP
** Either download it or run Autism Collaborative\Utilities\WinSCP.exe
* Login to autismcollaborative.org (port 22)
* Upload tAC_Installer.exe to your home directory (for example \home\zinsser)
** Do not overwrite the existing installer (\home\belmonte\autismcollaborative.org\downloads\AstropolisSetup.exe) since that would delete the installer from the website until the new installer finishes uploading (usually over an hour!)
* Once the upload is complete, enter the command "mv \home\zinsser\tAC_Installer.exe \home\belmonte\autismcollaborative.org\downloads\AstropolisSetup.exe" (you may have to open a terminal first, depending on your SFTP client)
** In the above command, substitute your username for "zinsser", but keep "belmonte" as the destination user directory
** If there is a permissions problem, contact Matthew to make sure your user has permission to the autismcollaborative.org directory!

Code How To's

2008-02-06T02:13:48Z

Zinsser:

This page provides tutorials for some of the most common actions a programmer may wish to implement. It may helpful to read the [[Code Overview]] first.

==Submit a Bug or Other Issue==

* Login to BugHost.com
** Developers sign in with the email address "collaborators@autismcollaborative.org"
** Ask a developer for the password
* Click the Submit button on the top navigation bar
* Fill out the fields that apply to this issue

'''Type of Bug:'''
* Functional Problem
** Any actual "Bug"
* Suggestion
** A possible change to the game that may improve it
* New Feature
** Something that '''absolutely must''' be implemented
** Use sparingly; make sure it's not actually a Suggestion

'''Severity:'''
* How much this issue affects the game/application

'''Priority:'''
* How soon the issue should be resolved (relative to other issues)
* The majority of issues should be Low priority
* Use High sparingly

==Coding Conventions==

* Place the name of the file, authors, and copyright info at the top of each file
** Any person who makes significant changes to a file should add their name to the list of authors in a file
*** This helps anyone reading the code because they know who to ask if they have a question about something
* All private and protected class member variables are lowerCamelCase
* Private/protected class member variables are preceded with "m" (ie mLocalVariable)
* All functions, properties (sometimes called "smart fields"), and public class variables are UpperCamelCase
* Public variables should only be used with small classes that are only used by one or two other classes
* This code is intended to be viewed by many people who do not have strong programming backgrounds, therefore documentation is '''very''' important
** Document the purpose of each class's member variables, either next to their declaration or as a summary for their property accessor
** Create a summary documentation block for every function unless it is extremely obvious
*** This can be done by placing the cursor above a function definition and typing "///"
*** This block shows up in Intellisense when writing that function in code
** Add a summary to any properties that are possibly confusing or not straightforward
** Document every step of each algorithm (except for very obvious function calls like ResetSettings();)
*** Someone should be able to read only the comments in a function and still understand what it does
** See MeteorMadness.cs for an example of the appropriate level of documentation
* See the Load a Texture section for naming conventions of texture assets

==Create a New Minigame==

* Declare the class
** Create a new folder under ColonySimulator
** Create a new file in that folder named NewMinigame.cs where NewGame is the name of the new minigame
** Place all new minigame-specific classes in that folder
** Have the class derive from MiniGame
class NewGame : MiniGame {...}
* Implement the Constructor
** Initialize game variables
** Declare a ScoreCard (see Scoring tutorial)
** Log the GameBegin code (see the Logging tutorial)
* Implement Update()
public override void Update(ContentManager content){...}
** Do not assume a constant call rate
*** This function will almost always be called 60 times per second, but that rate may vary depending on CPU load
*** At the beginning of each cycle, get the time since the last cycle like this:
**** float dt = ColonyBaseApplication.GameManager.ElapsedSeconds;
**** '''DO NOT use XNA.Framework.GameTime.ElapsedGameTime''' because tAC_Engine implements update timing differently than a standard XNA application!
*** Build the time into all movement and timers, for example:
myEntity.LifeSpan -= dt;
myEntity.Position += myEntity.Velocity * dt;
* Implement Draw()
public override void Draw(SpriteBatch spriteBatch){...}
** Loop through all the game's entities and call their Draw() functions
** Consider using a generalized render-queue such as GenericWorldSpace '''(not-yet-implemented as of Oct 2007)'''
* Create a new game mode
** Add a new entry to ColonyBaseApplication.Modes = { ModeSelector, ColonySim, ...}
** Add the appropriate case to ColonyBaseApplication.SwitchMode(...)
** Add a new MiniGameInfo entry to ModeSelector.ModeSelector()
* End the game
** Flush the particle system (see the particles tutorial) if any emitters were created
** Log the GameEndSuccess/GameEndFailure code
** Flush the log (forces it to write any cached codes to disk)
** Show the score
** Switch the mode to ColonySim
ColonyBaseApplication.SwitchMode(ColonyBaseApplication.Modes.ColonySim);

==Use Images==

The tAC_Engine augments XNA's already great image support by automatically shrinking images based on a global Level Of Detail property. This means you can use it to load a graphic and the engine will automatically shrink its resolution if the Texture Detail settings are changed (via an in-game menu or a script) to Medium or Low (High retains the full resolution). This is more important for the main game since it will need to display a complex 3D scene, and minigames that just use a handful of sprites can essentially ignore this feature.

This is accomplished by discarding the first 0-2 mipmaps of an image. As a result, images without mipmaps (most "common" types like JPEG, PNG, GIF, TIFF) will always be loaded at their max resolution. For that reason, use DDS (or another XNA-supported mipmappable format) for 3D model textures. A DDS plugin for Photoshop is available at [http://developer.nvidia.com/object/nv_texture_tools.html NVidia's website].

To allow tAC_Engine to determine the appropriate resolution, each texture asset should be tagged with a "_Hi", "_Med", or "_Lo" as in "myImage_Hi.dds". If an image does not contain a detail tag at the end of its filename (before the extension) then the engine assumes it is at High resolution and will scale it down if the LOD property is Medium or lower. Most source images will have the "_Hi" tag, but some (like small objects or icons) may use the "_Med" or even "_Lo" setting to prevent the engine from downsampling them to the point where they are unrecognizable.

===Load a Texture===

'''DO NOT use XNA's ContentManager''' to load an asset in code unless you want the asset to ignore tAC_Engine.TextureManager.LOD property. The ContentManager should only be used in engine code when appropriate; games should always use the TextureManager.

But before you can load a texture in code you must add it to the content pipeline:

* Import the content into the project
** Browse to the appropriate folder in Visual Studio's Solution Explorer
*** For example, Content\MiniGames\MyImage.png
** Right click on that folder and select Add->Existing Item
** Select the image to import

Once that's done, you can load it memory with the TextureManager:

Texture2D myTexture = TextureManager.Load(@"Content\General\myTexture");

Do not include the "_Hi" (or "_Med" or "_Lo") naming convention or the file extension call to TextureManager.Load().

===Display a Static Image===

Before manually drawing something to screen consider using some type of game object, be it an Entity, HUD element, or even a Ticker (see the tutorials below). Game objects all know how to draw themselves, so it is unlikely that a minigame will need to draw something directly to the screen. Should the need arise, however, here's how it's done:

* Load it in code:
GraphicsDeviceManager gdm = ...; // This is declared in GenericGameManager.cs
ConentManager cm = ...; // Usually a parameter, as in Update(ContentManager content)
SpriteBatch sb = new SpriteBatch(gdm.GraphicsDevice); // Basically a wrapper for a DirectX render target
Texture2D texture = TextureManager.Load(@"Content\General\myTexture");
Rectangle destination = ...; // Display destination
Color tint = Color.White; // Tint the image with this color
float rotation = 0f; // Rotation (in radians)
Vector2 center = new Vector2(texture.Width / 2f, texture.Height / 2f); // Origin of rotation
float zDepth = 1f; // Order to draw sprites within this spritebatch

sb.Begin(SpriteBlendMode.AlphaBlend, SpriteSortMode.BackToFront, SaveStateMode.SaveState);

sb.Draw(
texture,
destination ,
null, // What part of the source image to sample from--null tells it to use the whole image
tint ,
rotation,
center,
SpriteEffects.None, // How to mirror the image
zDepth
);

sb.End();

===Display an Animation===

Animations are built into Entities. There are currently no plans to support animation in any other context. Here's an example:

Animation anim = new Animation(new Vector2(100, 100)); // Create an animation that is 100x100 pixels when displayed
anim.AddClip("Idle", content.Load<Texture2D>(@"Content/IdleSpriteSheet"), 5, 1f/60f); // a 500x100 spritesheet
anim.AddClip("Walk", content.Load<Texture2D>(@"Content/WalkSpriteSheet"), 12, 1f / 60f); // a 400x300 spritesheet
Entity ent = new Entity(anim, new Vector3(10f, 50f, 0f), new Vector3(100f, 100f, 0f)); // a 100x100 2D entity located at (10,50)

ent.Play("Idle"); // Start the idle animation
// ...
ent.Play("Walk"); // Switch to the walking animation
// ...
ent.Draw(sb); // Draw to the SpriteBatch sb

==Create a New Type of Game Object==

All specific game objects (players, enemies, collectibles, projectiles, etc.) should derive from Entity. This gives them easy ways to draw themselves, move, collide with other entities, and be passed to many tAC_Engine functions.

==Get User Input==

'''DO NOT''' use the standard XNA keyboard accessors (Xna.Framework.Input.KeyboardState or Xna.Framework.Input.Keyboard) or mouse accessors (Xna.Framework.Input.MouseState) because tAC_Engine does a lot of caching and logging behind the scenes. Use tAC_Engine.InputState instead.

===Keyboard===

if (InputState.IsKeyDown(Keys.A))
{
// The A key was pressed
}

===Mouse===

if (InputState.IsMouseLeftUp && InputState.WasMouseLeftDown)
{
// The mouse was just clicked (clicks are typically registered on the release, not the initial press)
}

Vector2 location = InputState.MouseLocation;

==Manage a Heads Up Display==

Use the HUD class for any HUD element (like health bars, menu buttons, etc.). Typically, you'll want to create a class that inherits from Widget2D. See MeteorWidgets.cs for examples.

==Display Text or Icons with the Ticker==

string text = "w00t."; // Text to display (can be "")
Texture2D image = null; // Can also be set to an image
Vector2 imageSize = new Vector2(25f, 25f); // Size of the (optional) icon
Vector2 offset = new Vector2(700f, 50f); // This will display the ticker 700 pixels to the right of the screen's
// center and 50 pixels below the screen's center
Vector2 velocity = new Vector2 (-10f, 0f); // Move left 10 pixels per second
Ticker.Font font = Ticker.Font.Standard; // Regular text
Color color = Color.DeepPink; // The manliest of colors
float opacity = .5f; // 50% transparent
float seconds = 5f; // Disappear after 5 seconds
bool fade = true; // Fade in and fade out

Ticker.Display(text, image, imageSize, offset, velocity, font, color, opacity, seconds, fade);

==Display Text Manually==

Most text displayed should be done using the Ticker, but if you really want to display text manually use the Nuclex font library (XNA now supports text, so the Nuclex library may eventually be removed). First you must import the desired font:

* Create an xml file for the new font called FontName.tffimport that looks like this:
<?xml version="1.0"?>
<TrueTypeImport>
<Path>Content\Fonts\MercuryII.ttf</Path>
<Size>32</Size>
</TrueTypeImport>
* Put the font (FontName.ttf) and FontName.tffimport in the Content\Fonts directory
* Set the following properties for FontName.ttf
** Build Action: None
** Copy to Output Directory: Copy if newer
** File Name: MercuryII.ttf
* Set the following properties for FontName.tffimport
** Build Action: Content
** Content Importer: TrueTypeFont - XNA Framework
** Content Processor: Bitmap Font - XNA Framework
** Copy to Output Directory: Do not copy
** XNA Framework Content: True

Now for the code:

ContentManager cm = ...;
SpriteBatch sb = ...;
BitmapFont bmf = cm.Load<BitmapFont>(@"Content\Fonts\Arial");
sb.Begin(SpriteBlendMode.AlphaBlend);
bmf.DrawString(new Vector2(10.0F, 10.0F), "Manual Text!", Color.Azure);
sb.End();

==Use Sound==

===Import a new Sound===

* Run Autism Collaborative\Utilities\XACT\Xact.exe
** This is the XACT tool from Microsoft DirectX SDK August 2006
** If--after following the steps in this tutorial--playing a file in code throws an exception about using the wrong version of XACT, try using Xact.exe from a different SDK build
* Open Autism Collaborative\Game\Game\Content\Sounds\AudioProject.xap
* Expand Wave Banks and double click Wave Bank in the panel on the left
* Expand Sound Banks and double click Sound Bank in the panel on the left
* Go to Wave Banks->Insert Wave File(s)...
* Select the file to import (Autism Collaborative\Game\Game\Content\Sounds\MySound.wav) and click OK
* Drag the newly-added file to the Cue Name section in the Sound Bank:Sound Bank window
* Go to File->Build
* Save and close XACT
* Open game.sln with Visual Studio
* Browse to the Content\Sounds folder in the Solution Explorer
* Right click the Sounds folder and select Add->Existing Item...
* Select MySound.wav and click OK

===Play a Sound===

Sound.Play("MySound"); // No file extension

==Use the Particle Engine==

Particles are handled by Sparx, a subset of the Pina library being developed alongside the Autism Game. Features are added to it on an as-needed basis so if a new feature '''is''' needed contact August or email support.

Particle Effects are imported via the content pipeline, so they can be called in a similar manner:

using Pina3D.Particles;

...

Emitter mRootEmitter;
mRootEmitter = Sparx.LoadParticleEffect(@"Content\Particle Effects\MyParticleEffect.spx");
Sparx.AddEmitter(mRootEmitter);

Don't forget to kill emitters when they are no longer needed.

mRootEmitter.Alive = false; // Kills the Emitter
Sparx.Flush(); // Kills all Emitters

Emitters can be moved around:

mRootEmitter.Position2D = new Vector2(100f, 100f); // Emitter will move, but existing Particles will not be affected

They can also move and keep their Particles in the same relative location.

// COMING SOON (this old code does not yet work with the new 3D particle system
//mRootEmitter.Transform = Matrix.CreateTranslation(100f, 100f, 0); // Particles will move with the Emitter

Any aspect of a Particle Effect can be changed at runtime. For example, to make an effect green add a Modifier:

mRootEmitter.RegularEmissionType.Modifiers.Add(new Modifier("whateverMyNameIs", 0f, 0f, Color.Green, Color.Green, 1f, 1f, 1f, 1f, 0f, 0f));

Or apply forces at runtime:

mRootEmitter.SubscribeEmissionsToForce(new Current("theWind", 0f, 0f, new Vector3(10f, 0f, 0f), 1f));

===Create a New Particle Effect===

This can be done entirely at runtime, however it is usually much easier (and more fun) to use they WYSIWYG editor SparxCreator3D. Please report any bugs to August or submit them to the bug database.

* Run Autism Collaborative\Utilities\SparxCreator3D.exe
* Make an effect
** Emitters can emit Emissions
** Emissions can be Particles or Emitters
** Modifiers can be applied to Emissions
** Forces can be applied to Emitters

Once an effect file is generated (MyEffect.spx) import it into the game to use it.

* In the Solution Explorer, browse to Content\Particle Effects
* Right click the folder and select Add->Existing Item...
* Select MyEffect.spx and click OK
* Change MyEffect.spx's Copy to Output Directory property to Copy Always

==Keep Score and Give Resources to the Simulator Mode==

Use the ScoreCard class to keep track of the score from a minigame. It provides easy ways to add and subtract resources, as well as an easy way to display them and pass them along to the Colony Simulator.

MiniGame has a ColonyScoreCard built into it, accessible by the Score property. Here are some examples of how to use it:

class MyGame : MiniGame
{
public override void Update(ContentManager content)
{
Score.Gather(ColonyResources.Money, 500); // Get 500 Monies

MyGameObject mgo = new MyGameObject();
mgo.GiveMyGameCarbon(); // Get 1 Carbon

Score.IncurDamageCost(100); // On CashOut, Money = Max (Money - DamageCosts, 0)

int HowMuchMoneyIHave = Score.QueryResource(ColonyResources.Money);
}

public void DisplayTheScore()
{
bool playerWonTheMinigame = true; // Can be set to false if the player lost
Score.Display(playerWonTheMinigame ); // Displays a copy of the current score and a message for succses/failure
Score.CashOut(); // Transfers resources from MyGame to the Colony Simulator
}

// ...
}

class MyGameObject : Entity
{
public void GiveMyGameCarbon()
{
ColonyBaseApplication.MiniGame.Score.Gather(ColonyResources.Carbon, 1);
}
}

==Write to the Experimental Log==

As the game runs, certain actions are recorded and written to a file (Autism Collaborative\Game\Game\bin\x86\Debug\ExperimentalLog.txt or the corresponding Release folder). In the lab, these codes are also sent through the parallel port to sync the EEG data. Every action that pertains to an experiment must be logged in order to be analyzed (that's kind of the whole point of this game!).

First define the necessary game codes.

* Open Logger.cs
* Add up to 253 codes to public enum ExperimentalCode
** All codes must start with a unique "code identifier", an underscore, and then a descriptor in UpperCamelCase
*** For minigames, the code identifier is 2 letters
** 3 codes are reserved for special parallel port functions with the software that runs the EEG machines used in lab tests

Now those codes are available for logging. Like so:

Logger.LogCode(Logger.ExperimentalCode.XX_Descriptor);

It is also possible to tell the logger to log a code every time a specific key is pressed:

InputState.Encode(Keys.A, InputState.KeyState.Down, Logger.ExperimentalCode.DEBUG_DudeJustPushedA);

Each minigame should remove the encodings when it is done, but it is also a good idea to decode the keys at the start of each minigame just in case.

InputState.Encode(Keys.A, InputState.KeyState.Down);
InputState.DecodeAll();

Every minigame should also start with its GameBegin and end with its GameEnd[Success/Failure] codes.

It may be helpful to log events for debugging purposes. These codes have the identifier "DEBUG" and will not be logged unless the game is running in Debug mode. All new DEBUG tags must be explicitly assigned a value less than 0.

==Use the Game Script==

The tAC_Engine houses a [[http://www.lua.org/ Lua]] Virtual Machine. This can be used to tweak global parameters at runtime, load them from config files, drive cutscenes, or even save and load levels.

Function callbacks are defined in C# and then invoked from a Lua file or the in-game Debug console. In other words, C# tells Lua "you may use these functions: X,Y,..." and then Lua says "do X, do Y, etc."

Here are a couple of ways to leverage this system:

===Make a Cutscene===

* Create a new lua file in the Scripts directory
** That file can call any registered function callbacks
* In the Properties window, set Copy to Output Directory to Copy if Newer
* Call that cutscene with:
GenericBaseApplication.GameManager.PlayCutscene(@"Scripts\MyCutscene.lua");

===To Register a Function Callback===

* Create the function in C# (if the function does not already exist)
** It must be declared public and non-static
** If the need arises to register a static function, declare an instanced function in GenericLuaHelper or ColonyLuaHelper that simply calls the static function.
* Register the function with the Lua Virtual Machine
** Add the special LuaCallback annotation to the function
* Call the RegisterLuaCallbacks function in the class's constructor that contains the function.
* Example:
public MyClass()
{ // Constructor
LuaHelper.RegisterLuaCallbacks(this);
}

[LuaCallback("SetMyVariable")]
public int SetMyVariable(int value)
{
mMyVariable = value;
}

===Tweak Game Parameters===

Exposing a variable to the Lua Virtual Machine allows it to be accessed by a any script (including config files) or changed at runtime in the drop down console (accessible in Debug mode by hitting "~").

* Expose a variable with a global setter/getter with a LuaCallback annotation
** Make sure to call the RegisterLuaCallbacks function in that class's constructor if the getter/setter is not in the Game Manager
* Set the default value for the variable in the config file (optional)
** There are 3 config files for the 3 configurations of the game builds
*** Debug.conf, for development
*** StandardRelease.conf, for public releases of the game
*** LabRelease.conf, for use in the lab

===Create Local Settings===

Programmers may want to change certain properties on their machines without affecting the source-controlled code. They could change the resolution, sound settings, or even have the game bypass the regular startup sequence and launch right into the middle of a MiniGame all with no effect on other developers.

* Create a new file: Autism Collaborative\Game\Game\Scripts\LocalSettings.lua
** The Visual Studio project already has this file included, but VS won't be able to edit it until the file is created manually
* Add Lua commands and save the file
** Visual Studio can now be used to edit the file
* The file is run at the end of the Debug.conf script (if it exists)
** That means that this script is only run in Debug mode
* do '''NOT''' add LocalSettings.lua to source control!

==Run the Game in the Lab==

To enable the features necessary to run the game in the lab, the file conlab.tac must exist next to the game's executable.

From visual studio:
* Change the configuration to "ReleaseLab"
* Build the solution
From a public release of the game:
* Find "constd.tac," the standard encrypted config file
* Copy "conlab.tac" to the same directory
** Autism Collaborative\Game\Game\bin\x86\Laboratory\conlab.tac is generated when the game is compiled
** If the game finds conlab, it assumes it is in the lab and uses that config file
** If conlab is not present, it assumes it is not in the lab and uses constd.tac as the config file

==Publish the Installer==

===Create the Installer===

We use InnoSetup to create the installer. Checkout their website (http://www.jrsoftware.org/isinfo.php) if you need to change the script, but simply publishing the game does not require any adjustment to the installer script.

* Install InnoSetup if necessary
** Run Autism Collaborative\Utilities\Installer Installer\isetup-5.2.2.exe
* Compile the installer script
** Open Autism Collaborative\Game\Game\Installer.iss with InnoSetup
** Goto Run->Run
*** This creates the file Autism Collaborative\Game\Game\Output\tAC_Installer.exe

===Upload the Installer to the Web===

* Get a username/password for autismcollaborative.org from Matthew.
* Use a secure FTP client to login, such as WinSCP
** Either download it or run Autism Collaborative\Utilities\WinSCP.exe
* Login to autismcollaborative.org (port 22)
* Upload tAC_Installer.exe to your home directory (for example \home\zinsser)
** Do not overwrite the existing installer (\home\belmonte\autismcollaborative.org\downloads\AstropolisSetup.exe) since that would delete the installer from the website until the new installer finishes uploading (usually over an hour!)
* Once the upload is complete, enter the command "mv \home\zinsser\tAC_Installer.exe \home\belmonte\autismcollaborative.org\downloads\AstropolisSetup.exe" (you may have to open a terminal first, depending on your SFTP client)
** In the above command, substitute your username for "zinsser", but keep "belmonte" as the destination user directory
** If there is a permissions problem, contact Matthew to make sure your user has permission to the autismcollaborative.org directory!

Code How To's

2008-01-18T15:40:32Z

Zinsser: /* Manage a Heads Up Display */

Code How To's

2008-01-18T15:38:27Z

Zinsser: /* Get User Input */

This page provides tutorials for some of the most common actions a programmer may wish to implement. It may helpful to read the [[Code Overview]] first.

==Submit a Bug or Other Issue==

* Login to BugHost.com
** Developers sign in with the email address "collaborators@autismcollaborative.org"
** Ask a developer for the password
* Click the Submit button on the top navigation bar
* Fill out the fields that apply to this issue

'''Type of Bug:'''
* Functional Problem
** Any actual "Bug"
* Suggestion
** A possible change to the game that may improve it
* New Feature
** Something that '''absolutely must''' be implemented
** Use sparingly; make sure it's not actually a Suggestion

'''Severity:'''
* How much this issue affects the game/application

'''Priority:'''
* How soon the issue should be resolved (relative to other issues)
* The majority of issues should be Low priority
* Use High sparingly

==Coding Conventions==

* Place the name of the file, authors, and copyright info at the top of each file
** Any person who makes significant changes to a file should add their name to the list of authors in a file
*** This helps anyone reading the code because they know who to ask if they have a question about something
* All private and protected class member variables are lowerCamelCase
* Private/protected class member variables are preceded with "m" (ie mLocalVariable)
* All functions, properties (sometimes called "smart fields"), and public class variables are UpperCamelCase
* Public variables should only be used with small classes that are only used by one or two other classes
* This code is intended to be viewed by many people who do not have strong programming backgrounds, therefore documentation is '''very''' important
** Document the purpose of each class's member variables, either next to their declaration or as a summary for their property accessor
** Create a summary documentation block for every function unless it is extremely obvious
*** This can be done by placing the cursor above a function definition and typing "///"
*** This block shows up in Intellisense when writing that function in code
** Add a summary to any properties that are possibly confusing or not straightforward
** Document every step of each algorithm (except for very obvious function calls like ResetSettings();)
*** Someone should be able to read only the comments in a function and still understand what it does
** See MeteorMadness.cs for an example of the appropriate level of documentation
* See the Load a Texture section for naming conventions of texture assets

==Create a New Minigame==

* Declare the class
** Create a new folder under ColonySimulator
** Create a new file in that folder named NewMinigame.cs where NewGame is the name of the new minigame
** Place all new minigame-specific classes in that folder
** Have the class derive from MiniGame
class NewGame : MiniGame {...}
* Implement the Constructor
** Initialize game variables
** Declare a ScoreCard (see Scoring tutorial)
** Log the GameBegin code (see the Logging tutorial)
* Implement Update()
public override void Update(ContentManager content){...}
** Do not assume a constant call rate
*** This function will almost always be called 60 times per second, but that rate may vary depending on CPU load
*** At the beginning of each cycle, get the time since the last cycle like this:
**** float dt = ColonyBaseApplication.GameManager.ElapsedSeconds;
**** '''DO NOT use XNA.Framework.GameTime.ElapsedGameTime''' because tAC_Engine implements update timing differently than a standard XNA application!
*** Build the time into all movement and timers, for example:
myEntity.LifeSpan -= dt;
myEntity.Position += myEntity.Velocity * dt;
* Implement Draw()
public override void Draw(SpriteBatch spriteBatch){...}
** Loop through all the game's entities and call their Draw() functions
** Consider using a generalized render-queue such as GenericWorldSpace '''(not-yet-implemented as of Oct 2007)'''
* Create a new game mode
** Add a new entry to ColonyBaseApplication.Modes = { ModeSelector, ColonySim, ...}
** Add the appropriate case to ColonyBaseApplication.SwitchMode(...)
** Add a new MiniGameInfo entry to ModeSelector.ModeSelector()
* End the game
** Flush the particle system (see the particles tutorial) if any emitters were created
** Log the GameEndSuccess/GameEndFailure code
** Flush the log (forces it to write any cached codes to disk)
** Show the score
** Switch the mode to ColonySim
ColonyBaseApplication.SwitchMode(ColonyBaseApplication.Modes.ColonySim);

==Use Images==

The tAC_Engine augments XNA's already great image support by automatically shrinking images based on a global Level Of Detail property. This means you can use it to load a graphic and the engine will automatically shrink its resolution if the Texture Detail settings are changed (via an in-game menu or a script) to Medium or Low (High retains the full resolution). This is more important for the main game since it will need to display a complex 3D scene, and minigames that just use a handful of sprites can essentially ignore this feature.

This is accomplished by discarding the first 0-2 mipmaps of an image. As a result, images without mipmaps (most "common" types like JPEG, PNG, GIF, TIFF) will always be loaded at their max resolution. For that reason, use DDS (or another XNA-supported mipmappable format) for 3D model textures. A DDS plugin for Photoshop is available at [http://developer.nvidia.com/object/nv_texture_tools.html NVidia's website].

To allow tAC_Engine to determine the appropriate resolution, each texture asset should be tagged with a "_Hi", "_Med", or "_Lo" as in "myImage_Hi.dds". If an image does not contain a detail tag at the end of its filename (before the extension) then the engine assumes it is at High resolution and will scale it down if the LOD property is Medium or lower. Most source images will have the "_Hi" tag, but some (like small objects or icons) may use the "_Med" or even "_Lo" setting to prevent the engine from downsampling them to the point where they are unrecognizable.

===Load a Texture===

'''DO NOT use XNA's ContentManager''' to load an asset in code unless you want the asset to ignore tAC_Engine.TextureManager.LOD property. The ContentManager should only be used in engine code when appropriate; games should always use the TextureManager.

But before you can load a texture in code you must add it to the content pipeline:

* Import the content into the project
** Browse to the appropriate folder in Visual Studio's Solution Explorer
*** For example, Content\MiniGames\MyImage.png
** Right click on that folder and select Add->Existing Item
** Select the image to import

Once that's done, you can load it memory with the TextureManager:

Texture2D myTexture = TextureManager.Load(@"Content\General\myTexture");

Do not include the "_Hi" (or "_Med" or "_Lo") naming convention or the file extension call to TextureManager.Load().

===Display a Static Image===

Before manually drawing something to screen consider using some type of game object, be it an Entity, HUD element, or even a Ticker (see the tutorials below). Game objects all know how to draw themselves, so it is unlikely that a minigame will need to draw something directly to the screen. Should the need arise, however, here's how it's done:

* Load it in code:
GraphicsDeviceManager gdm = ...; // This is declared in GenericGameManager.cs
ConentManager cm = ...; // Usually a parameter, as in Update(ContentManager content)
SpriteBatch sb = new SpriteBatch(gdm.GraphicsDevice); // Basically a wrapper for a DirectX render target
Texture2D texture = TextureManager.Load(@"Content\General\myTexture");
Rectangle destination = ...; // Display destination
Color tint = Color.White; // Tint the image with this color
float rotation = 0f; // Rotation (in radians)
Vector2 center = new Vector2(texture.Width / 2f, texture.Height / 2f); // Origin of rotation
float zDepth = 1f; // Order to draw sprites within this spritebatch

sb.Begin(SpriteBlendMode.AlphaBlend, SpriteSortMode.BackToFront, SaveStateMode.SaveState);

sb.Draw(
texture,
destination ,
null, // What part of the source image to sample from--null tells it to use the whole image
tint ,
rotation,
center,
SpriteEffects.None, // How to mirror the image
zDepth
);

sb.End();

===Display an Animation===

Animations are built into Entities. There are currently no plans to support animation in any other context. Here's an example:

Animation anim = new Animation(new Vector2(100, 100)); // Create an animation that is 100x100 pixels when displayed
anim.AddClip("Idle", content.Load<Texture2D>(@"Content/IdleSpriteSheet"), 5, 1f/60f); // a 500x100 spritesheet
anim.AddClip("Walk", content.Load<Texture2D>(@"Content/WalkSpriteSheet"), 12, 1f / 60f); // a 400x300 spritesheet
Entity ent = new Entity(anim, new Vector3(10f, 50f, 0f), new Vector3(100f, 100f, 0f)); // a 100x100 2D entity located at (10,50)

ent.Play("Idle"); // Start the idle animation
// ...
ent.Play("Walk"); // Switch to the walking animation
// ...
ent.Draw(sb); // Draw to the SpriteBatch sb

==Create a New Type of Game Object==

All specific game objects (players, enemies, collectibles, projectiles, etc.) should derive from Entity. This gives them easy ways to draw themselves, move, collide with other entities, and be passed to many tAC_Engine functions.

==Get User Input==

'''DO NOT''' use the standard XNA keyboard accessors (Xna.Framework.Input.KeyboardState or Xna.Framework.Input.Keyboard) or mouse accessors (Xna.Framework.Input.MouseState) because tAC_Engine does a lot of caching and logging behind the scenes. Use tAC_Engine.InputState instead.

===Keyboard===

if (InputState.IsKeyDown(Keys.A))
{
// The A key was pressed
}

===Mouse===

if (InputState.IsMouseLeftUp && InputState.WasMouseLeftDown)
{
// The mouse was just clicked (clicks are typically registered on the release, not the initial press)
}

Vector2 location = InputState.MouseLocation;

==Manage a Heads Up Display==

Not yet implemented.

==Display Text or Icons with the Ticker==

string text = "w00t."; // Text to display (can be "")
Texture2D image = null; // Can also be set to an image
Vector2 imageSize = new Vector2(25f, 25f); // Size of the (optional) icon
Vector2 offset = new Vector2(700f, 50f); // This will display the ticker 700 pixels to the right of the screen's
// center and 50 pixels below the screen's center
Vector2 velocity = new Vector2 (-10f, 0f); // Move left 10 pixels per second
Ticker.Font font = Ticker.Font.Standard; // Regular text
Color color = Color.DeepPink; // The manliest of colors
float opacity = .5f; // 50% transparent
float seconds = 5f; // Disappear after 5 seconds
bool fade = true; // Fade in and fade out

Ticker.Display(text, image, imageSize, offset, velocity, font, color, opacity, seconds, fade);

==Display Text Manually==

Most text displayed should be done using the Ticker, but if you really want to display text manually use the Nuclex font library (XNA now supports text, so the Nuclex library may eventually be removed). First you must import the desired font:

* Create an xml file for the new font called FontName.tffimport that looks like this:
<?xml version="1.0"?>
<TrueTypeImport>
<Path>Content\Fonts\MercuryII.ttf</Path>
<Size>32</Size>
</TrueTypeImport>
* Put the font (FontName.ttf) and FontName.tffimport in the Content\Fonts directory
* Set the following properties for FontName.ttf
** Build Action: None
** Copy to Output Directory: Copy if newer
** File Name: MercuryII.ttf
* Set the following properties for FontName.tffimport
** Build Action: Content
** Content Importer: TrueTypeFont - XNA Framework
** Content Processor: Bitmap Font - XNA Framework
** Copy to Output Directory: Do not copy
** XNA Framework Content: True

Now for the code:

ContentManager cm = ...;
SpriteBatch sb = ...;
BitmapFont bmf = cm.Load<BitmapFont>(@"Content\Fonts\Arial");
sb.Begin(SpriteBlendMode.AlphaBlend);
bmf.DrawString(new Vector2(10.0F, 10.0F), "Manual Text!", Color.Azure);
sb.End();

==Use Sound==

===Import a new Sound===

* Run Autism Collaborative\Utilities\XACT\Xact.exe
** This is the XACT tool from Microsoft DirectX SDK August 2006
** If--after following the steps in this tutorial--playing a file in code throws an exception about using the wrong version of XACT, try using Xact.exe from a different SDK build
* Open Autism Collaborative\Game\Game\Content\Sounds\AudioProject.xap
* Expand Wave Banks and double click Wave Bank in the panel on the left
* Expand Sound Banks and double click Sound Bank in the panel on the left
* Go to Wave Banks->Insert Wave File(s)...
* Select the file to import (Autism Collaborative\Game\Game\Content\Sounds\MySound.wav) and click OK
* Drag the newly-added file to the Cue Name section in the Sound Bank:Sound Bank window
* Go to File->Build
* Save and close XACT
* Open game.sln with Visual Studio
* Browse to the Content\Sounds folder in the Solution Explorer
* Right click the Sounds folder and select Add->Existing Item...
* Select MySound.wav and click OK

===Play a Sound===

Sound.Play("MySound"); // No file extension

==Use the Particle Engine==

Particles are handled by Sparx, a subset of the Pina library being developed alongside the Autism Game. Features are added to it on an as-needed basis so if a new feature '''is''' needed contact August or email support.

Particle Effects are imported via the content pipeline, so they can be called in a similar manner:

using Pina3D.Particles;

...

Emitter mRootEmitter;
mRootEmitter = Sparx.LoadParticleEffect(@"Content\Particle Effects\MyParticleEffect.spx");
Sparx.AddEmitter(mRootEmitter);

Don't forget to kill emitters when they are no longer needed.

mRootEmitter.Alive = false; // Kills the Emitter
Sparx.Flush(); // Kills all Emitters

Emitters can be moved around:

mRootEmitter.Position2D = new Vector2(100f, 100f); // Emitter will move, but existing Particles will not be affected

They can also move and keep their Particles in the same relative location.

// COMING SOON (this old code does not yet work with the new 3D particle system
//mRootEmitter.Transform = Matrix.CreateTranslation(100f, 100f, 0); // Particles will move with the Emitter

Any aspect of a Particle Effect can be changed at runtime. For example, to make an effect green add a Modifier:

mRootEmitter.RegularEmissionType.Modifiers.Add(new Modifier("whateverMyNameIs", 0f, 0f, Color.Green, Color.Green, 1f, 1f, 1f, 1f, 0f, 0f));

Or apply forces at runtime:

mRootEmitter.SubscribeEmissionsToForce(new Current("theWind", 0f, 0f, new Vector3(10f, 0f, 0f), 1f));

===Create a New Particle Effect===

This can be done entirely at runtime, however it is usually much easier (and more fun) to use they WYSIWYG editor SparxCreator3D. Please report any bugs to August or submit them to the bug database.

* Run Autism Collaborative\Utilities\SparxCreator3D.exe
* Make an effect
** Emitters can emit Emissions
** Emissions can be Particles or Emitters
** Modifiers can be applied to Emissions
** Forces can be applied to Emitters

Once an effect file is generated (MyEffect.spx) import it into the game to use it.

* In the Solution Explorer, browse to Content\Particle Effects
* Right click the folder and select Add->Existing Item...
* Select MyEffect.spx and click OK
* Change MyEffect.spx's Copy to Output Directory property to Copy Always

==Keep Score and Give Resources to the Simulator Mode==

Use the ScoreCard class to keep track of the score from a minigame. It provides easy ways to add and subtract resources, as well as an easy way to display them and pass them along to the Colony Simulator.

MiniGame has a ColonyScoreCard built into it, accessible by the Score property. Here are some examples of how to use it:

class MyGame : MiniGame
{
public override void Update(ContentManager content)
{
Score.Gather(ColonyResources.Money, 500); // Get 500 Monies

MyGameObject mgo = new MyGameObject();
mgo.GiveMyGameCarbon(); // Get 1 Carbon

Score.IncurDamageCost(100); // On CashOut, Money = Max (Money - DamageCosts, 0)

int HowMuchMoneyIHave = Score.QueryResource(ColonyResources.Money);
}

public void DisplayTheScore()
{
bool playerWonTheMinigame = true; // Can be set to false if the player lost
Score.Display(playerWonTheMinigame ); // Displays a copy of the current score and a message for succses/failure
Score.CashOut(); // Transfers resources from MyGame to the Colony Simulator
}

// ...
}

class MyGameObject : Entity
{
public void GiveMyGameCarbon()
{
ColonyBaseApplication.MiniGame.Score.Gather(ColonyResources.Carbon, 1);
}
}

==Write to the Experimental Log==

As the game runs, certain actions are recorded and written to a file (Autism Collaborative\Game\Game\bin\x86\Debug\ExperimentalLog.txt or the corresponding Release folder). In the lab, these codes are also sent through the parallel port to sync the EEG data. Every action that pertains to an experiment must be logged in order to be analyzed (that's kind of the whole point of this game!).

First define the necessary game codes.

* Open Logger.cs
* Add up to 253 codes to public enum ExperimentalCode
** All codes must start with a unique "code identifier", an underscore, and then a descriptor in UpperCamelCase
*** For minigames, the code identifier is 2 letters
** 3 codes are reserved for special parallel port functions with the software that runs the EEG machines used in lab tests

Now those codes are available for logging. Like so:

Logger.LogCode(Logger.ExperimentalCode.XX_Descriptor);

It is also possible to tell the logger to log a code every time a specific key is pressed:

InputState.Encode(Keys.A, InputState.KeyState.Down, Logger.ExperimentalCode.DEBUG_DudeJustPushedA);

Each minigame should remove the encodings when it is done, but it is also a good idea to decode the keys at the start of each minigame just in case.

InputState.Encode(Keys.A, InputState.KeyState.Down);
InputState.DecodeAll();

Every minigame should also start with its GameBegin and end with its GameEnd[Success/Failure] codes.

It may be helpful to log events for debugging purposes. These codes have the identifier "DEBUG" and will not be logged unless the game is running in Debug mode. All new DEBUG tags must be explicitly assigned a value less than 0.

==Use the Game Script==

The tAC_Engine houses a [[http://www.lua.org/ Lua]] Virtual Machine. This can be used to tweak global parameters at runtime, load them from config files, drive cutscenes, or even save and load levels.

Function callbacks are defined in C# and then invoked from a Lua file or the in-game Debug console. In other words, C# tells Lua "you may use these functions: X,Y,..." and then Lua says "do X, do Y, etc."

Here are a couple of ways to leverage this system:

===Make a Cutscene===

* Create a new lua file in the Scripts directory
** That file can call any registered function callbacks
* In the Properties window, set Copy to Output Directory to Copy if Newer
* Call that cutscene with:
GenericBaseApplication.GameManager.PlayCutscene(@"Scripts\MyCutscene.lua");

===To Register a Function Callback===

* Create the function in C# (if the function does not already exist)
** It must be declared public and non-static
** If the need arises to register a static function, declare an instanced function in GenericLuaHelper or ColonyLuaHelper that simply calls the static function.
* Register the function with the Lua Virtual Machine
** Add the special LuaCallback annotation to the function
* Call the RegisterLuaCallbacks function in the class's constructor that contains the function.
* Example:
public MyClass()
{ // Constructor
LuaHelper.RegisterLuaCallbacks(this);
}

[LuaCallback("SetMyVariable")]
public int SetMyVariable(int value)
{
mMyVariable = value;
}

===Tweak Game Parameters===

Exposing a variable to the Lua Virtual Machine allows it to be accessed by a any script (including config files) or changed at runtime in the drop down console (accessible in Debug mode by hitting "~").

* Expose a variable with a global setter/getter with a LuaCallback annotation
** Make sure to call the RegisterLuaCallbacks function in that class's constructor if the getter/setter is not in the Game Manager
* Set the default value for the variable in the config file (optional)
** There are 3 config files for the 3 configurations of the game builds
*** Debug.conf, for development
*** StandardRelease.conf, for public releases of the game
*** LabRelease.conf, for use in the lab

===Create Local Settings===

Programmers may want to change certain properties on their machines without affecting the source-controlled code. They could change the resolution, sound settings, or even have the game bypass the regular startup sequence and launch right into the middle of a MiniGame all with no effect on other developers.

* Create a new file: Autism Collaborative\Game\Game\Scripts\LocalSettings.lua
** The Visual Studio project already has this file included, but VS won't be able to edit it until the file is created manually
* Add Lua commands and save the file
** Visual Studio can now be used to edit the file
* The file is run at the end of the Debug.conf script (if it exists)
** That means that this script is only run in Debug mode
* do '''NOT''' add LocalSettings.lua to source control!

==Run the Game in the Lab==

To enable the features necessary to run the game in the lab, the file conlab.tac must exist next to the game's executable.

From visual studio:
* Change the configuration to "ReleaseLab"
* Build the solution
From a public release of the game:
* Find "constd.tac," the standard encrypted config file
* Copy "conlab.tac" to the same directory
** Autism Collaborative\Game\Game\bin\x86\Laboratory\conlab.tac is generated when the game is compiled
** If the game finds conlab, it assumes it is in the lab and uses that config file
** If conlab is not present, it assumes it is not in the lab and uses constd.tac as the config file

Dev Setup

2008-01-14T14:54:24Z

Zinsser: /* Start Developing */

Follow these steps to run the development build of the game.

==System Requirements==

This game requires the following for both development and released versions:

* Intel-based PC with at least 1.0 GHz
* Windows XP or Windows Vista (it has been reported that Macintosh systems running Boot Camp can run the released build, but development must be done on a Windows machine)
* Graphics card with Pixel Shader 1.0+ (any computer that can run Windows Vista meets this requirement)

==Download and Install the Software==

* [http://msdn2.microsoft.com/en-us/express/aa975050.aspx Visual C# Express Edition] - As of Oct 2007, development is in Version 1 but Version 2 may also work
* [http://www.microsoft.com/downloads/details.aspx?FamilyId=12ADCD12-7A7B-4413-A0AF-FF87242A78DE&displaylang=en XNA Game Studio Express]
* [http://tortoisesvn.net/downloads Tortoise SVN] - or other Subversion Client

==Download the Code==

* Obtain a Subversion username and password from a Subversion Admin (Matthew or August). The username will be used to track your changes to the code repository and the password will be known by all Subversion Admins, so don't use your "real" password!
* Checkout the Repository
** Create a new directory called "Autism Collaborative" (or something else if you're a rebel)
** Right click on the folder and select TortsoiseSVN->Checkout... from the popup menu
** In the URL of repository field, enter http://www.autismcollaborative.org/autism_collaborative
** Click OK
* Register the code dependencies
** Browse to Autism Collaborative\Dependencies
** Run RegisterDependencies.bat

==Run the Game==

New users of Visual Studio or similar IDE (Integrated Development Environment) should check out Microsoft's [http://msdn.microsoft.com/vstudio/express/beginner/ Online Learning Center].

==Start Developing==

Check out the [[Code Overview]] for an explanation of how the code base works. It may also be helpful to visit the [[Code How To's]] for explanations of common coding tasks. And don't forget about the weekly [[Meetings]]!

Main Page

2008-01-14T14:53:23Z

Zinsser: /* Major Sections */

<big>'''Welcome to the Autism Game wiki'''</big>

==The Motivation==
'''Integrative studies of perception, attention, and social cognition in autism'''

Although much progress has been made identifying structural and functional profiles in autism, this work has resulted in a multiplicity of hypotheses targeted at particular brain or cognitive subsystems or levels of analysis; our most vexing problem often is not identifying the observational details, but assembling these details into a coherent theory. The division between social and non-social studies of autism is a case in point. Competing theories have construed autism variously as an exclusively social deficit in "theory of mind," an abnormality of attention and executive function with social and non-social consequences, an atypical weakness in "central coherence," or an enhancement of perceptual function. Although each of these views seems to capture a piece of the truth, a synthesis of all of them will not be possible as long as they continue to be approached as competing rather than synergistic views, as long as their psychological descriptions remain incompletely connected to neurobiological explanations and to clinical impairments, and as long as individual experiments continue to collect data germane to only one theory in isolation.

==The Strategy==
'''Embed a suite of psychological experiments within a video game that's fun to play'''

Perhaps the single most important obstacle to integrative studies of autism is the practical limit on the amount of time that a single experimental subject can reasonably be expected to perform before becoming fatigued. Unfortunately, often the more controlled a stimulus is from the scientist's point of view, the more repetitive and tedious the experiment can seem from the subject's point of view. Behavioural research on autism in recent years has highlighted the importance of motivation, behavioural set, and task instruction in establishing cognitive strategy and determining performance (e.g. Plaisted et al. 1999; Dalton et al. 2005). In light of these considerations, we propose to embed experimental stimuli in the context of a video game that captures and maintains subjects' interest, transparently collecting behavioural data and synchronising with physiological recording as the subject plays the game. The practical advantages of such an engaging and ecologically valid format over the usual repetitive blocks of trials are legion. Indeed, varying levels and demands of attentional shifting and multimodal integration are natural in the context of video game play, and psychophysical measures such as dot motion coherence and embedded figures are easily implemented as, for example, the movement of a star field on a view screen and the detection of an adversary in a cluttered environment. In addition, the strategic and adversarial nature of a video game carries natural opportunities to explore higher-level cognitive measures such as comprehension of game-related narratives and social attribution to a computer-generated adversary. The video game format is increasingly being used to acquire simultaneous behavioural and EEG observations in ecologically valid contexts, for example in visuomotor tracking (Smith et al. 1999), air traffic control (Brookings et al. 1996), and military command and control simulations (St John et al. 2002, 2004; Berka et al. 2004). Recent results in human-computer interaction (von Ahn 2006) also point to the power of the game context to establish and to maintain motivation in tasks that otherwise might not seem engaging, and to teach persons with developmental disorders (Golan & Baron-Cohen 2006). Also along these lines, the video game format affords subjects more of a chance to become comfortable with the task before entering the laboratory, minimising the potential confound of state anxiety associated with performance of an unfamiliar task in a testing situation.

==Major Sections==

[[Plot]]

[[Functional specifications]]

[[Meetings]]

[[Dev Setup]]

[[Code How To's]]

Meetings

2008-01-14T14:52:39Z

Zinsser: New page: '''Skype''' '''Tuesdays''' '''Noon''' The developers and Matthew have weekly teleconferences via Skype. Just sign in and August or Matthew will start a conference call. By 10am that da...

'''Skype'''

'''Tuesdays'''

'''Noon'''

The developers and Matthew have weekly teleconferences via Skype. Just sign in and August or Matthew will start a conference call. By 10am that day, each developer should email his/her Accomplishments since the last meeting and Objectives for the next meeting (A's and O's) to the programmer listserv.

Meteor Madness

2008-01-12T18:17:32Z

Zinsser:

Display Name: '''Maritime Defender'''

[[image:MaritimeDefender05.jpg|thumb|right]] [[image:MaritimeDefender04.jpg|thumb|right]] [[image:MaritimeDefender07.jpg|thumb|right]]

==Abstract==

This mini-game resembles the arcade games Tempest and Asteroids, and combines tests of motion coherence threshold, motor inhibition, and executive flexibility. The player commands a spaceship that moves clockwise (left arrow key) or counterclockwise (right arrow key) around the perimeter of a circular field. Slow-moving meteors materialise at the centre of the field and drift outward; the player must fire torpedoes (space bar) to destroy these meteors. (This ongoing task serves simply to maintain vigilance.) Periodically, a wormhole materialises within the field. The player can open this wormhole by moving around the circle to align with it, then connecting with the wormhole (up arrow). Connecting temporarily drains the ship's propulsion systems; the ship is locked in place in front of the wormhole as an unidentified ship begins to emerge. This ship can be either a friend or a foe, with equal probability. Friend and foe ships are identical in area and luminance, but differ subtly in form: one has two warp nacelles protruding, the other three. Foes should be fired upon and destroyed before they get a chance to attack the player. Conversely, withholding fire on a friend is rewarded by a weapons power-up which increases the player's firing rate. (This change in firing rate alters the game tactically but does not affect measurement of reaction times.) Friends and foes cannot be discriminated until they have emerged from the wormhole. Thus during the opening of the wormhole the player must prepare, but not execute, a motor response. Foes do not fire, and friends do not deliver weapons power-ups, until 800 ms after emerging. A hit in this task is therefore defined as firing on a foe within this 800 ms interval, a miss as failing to fire on a foe within this interval, a correct rejection as withholding fire on a friend, and a false alarm as firing on a friend. This task behaviourally measures inhibitory function, and can be used in conjunction with EEG measures to assess motor planning.

Friendly and enemy forces in this game are pirates or mercenaries who have requested the player's help (to fend off the pirates). The class of ship used by each side therefore can change from one session of the game to the next. A '''shift''' session is one in which the assignment of ship classes differs from that of the session immediately preceding. A '''hold''' session is one in which the assignment of ship classes does not differ from that of a session immediately preceding. Differences in reaction time and accuracy for the fire-or-withhold task between shift and hold sessions measure executive flexibility.

After the player has completed a session of five wormhole connections, the ship warps to another meteor field. Whilst in warp, the player views a field of 200 stars (white dots on a black background), a percentage of which move coherently in one direction, either left or right. Other stars move in random directions. Each star appears in the field for four video frames, or until its motion carries it outside the boundary of the field. Coherent motion of the star field signals that the ship is veering right (for leftwards apparent motion) or left (for rightwards apparent motion) of its intended course. The player's task is to compensate for this drift by steering left (left arrow) when leftwards apparent motion is perceived, and right (right arrow) when rightwards apparent motion is perceived. Failure to compensate for an actual drift or compensation when no drift is present causes the ship to collide with this mysterious subspace matter, draining its shield and possibly resulting in its destruction. Each drift interval lasts 2 seconds plus a random and uniformly distributed interval between 0 and 250 ms, or until a course correction is commanded. The player's motion coherence threshold is estimated via parameter estimation by sequential testing (PEST). Since the threshold adjusts to the player, it is expected that about half of the trials will result in a failure. To avoid frustrating the player, approximately every 4 trials is a dummy trial with an artificially high coherence threshold.

==Premise==

A "nearby" freighter is under attack by marauders! Warp to its location and destroy all hostile forces before it's too late. Friendly escort ships will assist you with weapon upgrades.

==Objective==

Salvage as many survivors and goods as possible whilst keeping your own ship alive.

==Characters==

[[image:Cheetah_300.png]]

'''Cheetah C-24 Fighters:''' The colony's squadron of high-speed attack ships. They are equipped with magnetic photonic torpedoes. The Cheetah's shields are capable of absorbing substantial energy surges before becoming vulnerable to enemy fire or physical collision.

'''Wormhole:''' Requires 2 entities to open; one on each side. These appear during the shooter phase and with the help of the player allow a resource or a hostile to warp through to the player's location.

[[image:Drone_300.png]] [[image:Wasp_300.png]]

'''UFO1,2:''' Marauding space pirates or mercenaries (depending on the session). They are both equipped with weapons and capable of destroying C-24 Fighters.

'''Meteorites:''' Come in a couple of different shapes and sizes. Slamming into one causes a hit on a ship's shields or destruction if the ship's shields have failed.

'''Subspace Matter:''' Random particles that fly through space in a logical manner when piloting at regular speeds, however in warp drive they seem to defy the laws of physics.

==Gameplay==

There are 3 phases to this minigame. The game begins at level 1 in the shooter phase. After this, the ship uses a wormhole to enter a warp-jump phase that lasts for about 15 seconds. This cycle is repeated 4 times (unless the player dies). The final phase is a boss phase.

The player's shield persists through all phases. After taking a hit, the shield is reduced by 1/2. Thus, 2 hits are enough to deplete the shield, leaving the player only 1 more hit before dying in an exploserous ball of flame. Shields slowly recharge over time (about 10 seconds for a full charge, but this number will likely change upon play-testing), but once a shield is fully depleted it does not recharge leaving the ship permanently vulnerable to one more hit.

'''Warp-Jump Phase'''

This phase tests the subject's Motion Coherence. During warp-jumps, the mysterious dots move in a mostly random manner. A small percentage of these particles begin to drift in the same direction indicating that the ship is veering off course. The player must correct the ship's course by pressing the arrow key corresponding to that directional drift. Once the drift starts, the player has only a couple seconds to react. If no correction is made in time, the ship slams into debris and takes a hit. This phase ends after a set amount of time which is not disclosed to the player or the ship is destroyed.

The percentage of drifting stars is determined by PEST.

'''Dog Fight Phase'''

This phase tests the subject's focused spatial attention.

The playing field consists of an invisible cylinder whose caps are parallel to the camera's viewing plane. The player's ship is located at the near cap. All entities can only exist on the cylinder's circumference but may rotate around it or move up and down it lengthwise.

The player may fire, sending projectiles down the cylinder lengthwise. At first, the rate of fire is fairly slow, but as the player collects powerups from friendly ships that rate increases.

It may be necessary to add a wingman if many autistic players have trouble with this phase. The wingman would automatically move and fire upon enemies/meteors.

Wormholes appear at the far cylinder cap. The player can align his/her ship with a wormhole and activate it. A short time later, a ship (friendly or foe) replaces the wormhole. The player should immediately fire and attempt to destroy any hostiles. Should the player fire enough times upon a mercenary, it is destroyed. If a mercenary survives the trial, it awards the player with a weapon upgrade. Similarly, if a hostile is destroyed it leaves a small cash collectible behind.

Additionally, meteorites appear at the far cylinder cap and scroll down its circumference towards the camera. If they hit a ship, then the meteor is destroyed and the ship's shield takes a hit. Meteors will not appear in a column that is occupied by a wormhole. Meteors can be destroyed by shooting them.

'''Boss Phase'''

The final phase is a boss battle. This boss will not be incredibly difficult, but serves mostly to give the player a sense of accomplishment and reward them by letting them blast the away at a something with their upgraded lasers.

==User Interface==

For the warp phase, the only input will be left and right arrow keys to indicate a course correction. The HUD consists of a inner-cockpit view. The cockpit will remain static during test trials, but between trials will blink or sound to provide positive/negative feedback for successful/failed trials.

While in the shooter phase, pressing the left arrow key rotates the player's ship clockwise, while right rotates it counterclockwise. This would normally seem counterintuitive, but in this case the player's ship is displayed upright when it is near the bottom of the screen. Therefore, pressing left always shifts the C-24 to its port side. Spacebar fires weapons. Pressing the up arrow key will attempt to open a partial wormhole. This attempt is successful if the player is aligned with the wormhole (ie, they are near the same position on the opposite cylinder caps). A different color beam will indicate a successful or failed wormhole activation.

To minimize distraction, the shooter phase has no HUD. Shield power feedback is given through the color and opacity of the shield particle effect when a player gets hit.

The UI for the boss phase is identical to the shooter phase.

==Scoring==

Defeating the boss rewards a lump sum of cash. A colony structure is awarded if the player collects enough powerups. Any cash collected from destroyed enemies is also kept. Money is subtracted for the cost of each derelict ship destroyed by the player. If this dips the reward into negative money, then the money rewarded is set to 0.

File:MaritimeDefender07.jpg

2008-01-12T18:03:40Z

Zinsser:

File:MaritimeDefender04.jpg

2008-01-12T18:03:13Z

Zinsser:

2007-12-04T01:30:33Z

Zinsser: /* Use the Game Script */

This page provides tutorials for some of the most common actions a programmer may wish to implement. It may helpful to read the [[Code Overview]] first.

==Submit a Bug or Other Issue==

* Login to BugHost.com
** Email August for a new user if necessary
* Click the Submit button on the top navigation bar
* Fill out the fields that apply to this issue

'''Type of Bug:'''
* Functional Problem
** Any actual "Bug"
* Suggestion
** A possible change to the game that may improve it
* New Feature
** Something that '''absolutely must''' be implemented
** Use sparingly; make sure it's not actually a Suggestion

'''Severity:'''
* How much this issue affects the game/application

'''Priority:'''
* How soon the issue should be resolved (relative to other issues)
* The majority of issues should be Low priority
* Use High sparingly

==Coding Conventions==

* Place the name of the file, authors, and copyright info at the top of each file
** Any person who makes significant changes to a file should add their name to the list of authors in a file
*** This helps anyone reading the code because they know who to ask if they have a question about something
* All private and protected class member variables are lowerCamelCase
* Private/protected class member variables are preceded with "m" (ie mLocalVariable)
* All functions, properties (sometimes called "smart fields"), and public class variables are UpperCamelCase
* Public variables should only be used with small classes that are only used by one or two other classes
* This code is intended to be viewed by many people who do not have strong programming backgrounds, therefore documentation is '''very''' important
** Document the purpose of each class's member variables, either next to their declaration or as a summary for their property accessor
** Create a summary documentation block for every function unless it is extremely obvious
*** This can be done by placing the cursor above a function definition and typing "///"
*** This block shows up in Intellisense when writing that function in code
** Add a summary to any properties that are possibly confusing or not straightforward
** Document every step of each algorithm (except for very obvious function calls like ResetSettings();)
*** Someone should be able to read only the comments in a function and still understand what it does
** See MeteorMadness.cs for an example of the appropriate level of documentation

==Create a New Minigame==

* Declare the class
** Create a new folder under ColonySimulator
** Create a new file in that folder named NewMinigame.cs where NewGame is the name of the new minigame
** Place all new minigame-specific classes in that folder
** Have the class derive from MiniGame
class NewGame : MiniGame {...}
* Implement the Constructor
** Initialize game variables
** Declare a ScoreCard (see Scoring tutorial)
** Log the GameBegin code (see the Logging tutorial)
* Implement Update()
public override void Update(ContentManager content){...}
** Do not assume a constant call rate
*** This function will almost always be called 60 times per second, but that rate may vary depending on CPU load
*** At the beginning of each cycle, get the time since the last cycle like this:
**** float dt = ColonyBaseApplication.GameManager.ElapsedSeconds;
**** '''DO NOT''' use XNA.Framework.GameTime.ElapsedGameTime as tAC_Engine implements update timing differently than a standard XNA application!
*** Build the time into all movement and timers, for example:
myEntity.LifeSpan -= dt;
myEntity.Position += myEntity.Velocity * dt;
* Implement Draw()
public override void Draw(SpriteBatch spriteBatch){...}
** Loop through all the game's entities and call their Draw() functions
** Consider using a generalized render-queue such as GenericWorldSpace '''(not-yet-implemented as of Oct 2007)'''
* Create a new game mode
** Add a new entry to ColonyBaseApplication.Modes = { ModeSelector, ColonySim, ...}
** Add the appropriate case to ColonyBaseApplication.SwitchMode(...)
** Add a new MiniGameInfo entry to ModeSelector.ModeSelector()
* End the game
** Flush the particle system (see the particles tutorial) if any emitters were created
** Log the GameEndSuccess/GameEndFailure code
** Flush the log (forces it to write any cached codes to disk)
** Show the score
** Switch the mode to ColonySim
ColonyBaseApplication.SwitchMode(ColonyBaseApplication.Modes.ColonySim);

==Display a Static Image==

Before manually drawing something to screen consider using some type of game object, be it an Entity, HUD element, or even a Ticker (see the tutorials below). Game objects all know how to draw themselves, so it is unlikely that a programmer will need to draw something directly to the screen. Should the need arise, however, here's how it's done:

* Import the content into the project
** Browse to the appropriate folder in Visual Studio's Solution Explorer
*** For example, Content\MiniGames\MyImage.png
** Right click on that folder and select Add->Existing Item
** Select the image to import
* Load it in code:
GraphicsDeviceManager gdm = ...; // This is declared in GenericGameManager.cs
ConentManager cm = ...; // Usually a parameter, as in Update(ContentManager content)
SpriteBatch sb = new SpriteBatch(gdm.GraphicsDevice); // Basically a wrapper for a DirectX render target
Texture2D texture = cm.Load<Texture2D>(@"Content\MiniGames\MyImage"); // Source image with no file extension
Rectangle destination = ...; // Display destination
Color tint = Color.White; // Tint the image with this color
float rotation = 0f; // Rotation (in radians)
Vector2 center = new Vector2(texture.Width / 2f, texture.Height / 2f); // Origin of rotation
float zDepth = 1f; // Order to draw sprites within this spritebatch

sb.Begin(SpriteBlendMode.AlphaBlend, SpriteSortMode.BackToFront, SaveStateMode.SaveState);

sb.Draw(
texture,
destination ,
null, // What part of the source image to sample from--null tells it to use the whole image
tint ,
rotation,
center,
SpriteEffects.None, // How to mirror the image
zDepth
);

sb.End();

==Display an Animation==

Animations are built into Entities. There are no plans to support animation in any other context. Here's an example:

Animation anim = new Animation(new Vector2(100, 100)); // Create an animation that is 100x100 pixels when displayed
anim.AddClip("Idle", content.Load<Texture2D>(@"Content/IdleSpriteSheet"), 5, 1f/60f); // a 500x100 spritesheet
anim.AddClip("Walk", content.Load<Texture2D>(@"Content/WalkSpriteSheet"), 12, 1f / 60f); // a 400x300 spritesheet
Entity ent = new Entity(anim, new Vector3(10f, 50f, 0f), new Vector3(100f, 100f, 0f)); // a 100x100 2D entity located at (10,50)

ent.Play("Idle"); // Start the idle animation
// ...
ent.Play("Walk"); // Switch to the walking animation
// ...
ent.Draw(sb); // Draw to the SpriteBatch sb

==Create a New Type of Game Object==

All specific game objects (players, enemies, collectibles, projectiles, etc.) should derive from Entity. This gives them easy ways to draw themselves, move, collide with other entities, and be passed to many tAC_Engine functions.

==Get User Input==

'''DO NOT''' use the standard XNA keyboard accessors (Xna.Framework.Input.KeyboardState or Xna.Framework.Input.Keyboard) because tAC_Engine does a lot of caching and logging behind the scenes. Instead get keyboard input like this:

if (InputState.IsKeyDown(Keys.Left))
{
// The left key was pressed
}

If an exception is thrown stating "Unregistered Key Comparison" then add that key to the list in the InputState constructor.

==Manage a Heads Up Display==

Not yet implemented.

==Display Text or Icons with the Ticker==

string text = "w00t."; // Text to display (can be "")
Texture2D image = null; // Can also be set to an image
Vector2 imageSize = new Vector2(25f, 25f); // Size of the (optional) icon
Vector2 offset = new Vector2(700f, 50f); // This will display the ticker 700 pixels to the right of the screen's
// center and 50 pixels below the screen's center
Vector2 velocity = new Vector2 (-10f, 0f); // Move left 10 pixels per second
Ticker.Font font = Ticker.Font.Standard; // Regular text
Color color = Color.DeepPink; // The manliest of colors
float opacity = .5f; // 50% transparent
float seconds = 5f; // Disappear after 5 seconds
bool fade = true; // Fade in and fade out

Ticker.Display(text, image, imageSize, offset, velocity, font, color, opacity, seconds, fade);

==Display Text Manually==

Most text displayed should be done using the Ticker, but if you really want to display text manually use the Nuclex font library (XNA now supports text, so the Nuclex library may eventually be removed). First you must import the desired font:

* Create an xml file for the new font called FontName.tffimport that looks like this:
<?xml version="1.0"?>
<TrueTypeImport>
<Path>Content\Fonts\MercuryII.ttf</Path>
<Size>32</Size>
</TrueTypeImport>
* Put the font (FontName.ttf) and FontName.tffimport in the Content\Fonts directory
* Set the following properties for FontName.ttf
** Build Action: None
** Copy to Output Directory: Copy if newer
** File Name: MercuryII.ttf
* Set the following properties for FontName.tffimport
** Build Action: Content
** Content Importer: TrueTypeFont - XNA Framework
** Content Processor: Bitmap Font - XNA Framework
** Copy to Output Directory: Do not copy
** XNA Framework Content: True

Now for the code:

ContentManager cm = ...;
SpriteBatch sb = ...;
BitmapFont bmf = cm.Load<BitmapFont>(@"Content\Fonts\Arial");
sb.Begin(SpriteBlendMode.AlphaBlend);
bmf.DrawString(new Vector2(10.0F, 10.0F), "Manual Text!", Color.Azure);
sb.End();

==Import and Play a Sound==

* Run Autism Collaborative\Utilities\XACT\Xact.exe
** This is the XACT tool from Microsoft DirectX SDK August 2006
** If--after following the steps in this tutorial--playing a file in code throws an exception about using the wrong version of XACT, try using Xact.exe from a different SDK build
* Open Autism Collaborative\Game\Game\Content\Sounds\AudioProject.xap
* Expand Wave Banks and double click Wave Bank in the panel on the left
* Expand Sound Banks and double click Sound Bank in the panel on the left
* Go to Wave Banks->Insert Wave File(s)...
* Select the file to import (MySound.wav) and click OK
* Drag the newly-added file to the Cue Name section in the Sound Bank:Sound Bank window
* Go to File->Build
* Save and close XACT
* Open game.sln with Visual Studio
* Browse to the Content\Sounds folder in the Solution Explorer
* Right click the Sounds folder and select Add->Existing Item...
* Select MySound.wav and click OK
* To play this new sound, use the following code:
Sound.Play("MySound"); // No file extension

==Use the Particle Engine==

Particles are handled by Sparx, a subset of the Pina library being developed alongside the Autism Game. Features are added to it on an as-needed basis so if a new feature '''is''' needed contact August or email support.

Particle Effects are imported via the content pipeline, so they can be called in a similar manner:

using Pina3D.Particles;

...

Emitter mRootEmitter;
mRootEmitter = Sparx.LoadParticleEffect(@"Content\Particle Effects\MyParticleEffect.spx");
Sparx.AddEmitter(mRootEmitter);

Don't forget to kill emitters when they are no longer needed.

mRootEmitter.Alive = false; // Kills the Emitter
Sparx.Flush(); // Kills all Emitters

Emitters can be moved around:

mRootEmitter.Position2D = new Vector2(100f, 100f); // Emitter will move, but existing Particles will not be affected

They can also move and keep their Particles in the same relative location.

// COMING SOON (this old code does not yet work with the new 3D particle system
//mRootEmitter.Transform = Matrix.CreateTranslation(100f, 100f, 0); // Particles will move with the Emitter

Any aspect of a Particle Effect can be changed at runtime. For example, to make an effect green add a Modifier:

mRootEmitter.RegularEmissionType.Modifiers.Add(new Modifier("whateverMyNameIs", 0f, 0f, Color.Green, Color.Green, 1f, 1f, 1f, 1f, 0f, 0f));

Or apply forces at runtime:

mRootEmitter.SubscribeEmissionsToForce(new Current("theWind", 0f, 0f, new Vector3(10f, 0f, 0f), 1f));

===Create a New Particle Effect===

This can be done entirely at runtime, however it is usually much easier (and more fun) to use they WYSIWYG editor SparxCreator3D. Please report any bugs to August or submit them to the bug database.

* Run Autism Collaborative\Utilities\SparxCreator3D.exe
* Make an effect
** Emitters can emit Emissions
** Emissions can be Particles or Emitters
** Modifiers can be applied to Emissions
** Forces can be applied to Emitters

Once an effect file is generated (MyEffect.spx) import it into the game to use it.

* In the Solution Explorer, browse to Content\Particle Effects
* Right click the folder and select Add->Existing Item...
* Select MyEffect.spx and click OK
* Change MyEffect.spx's Copy to Output Directory property to Copy Always

==Keep Score and Give Resources to the Simulator Mode==

Use the ScoreCard class to keep track of the score from a minigame. It provides easy ways to add and subtract resources, as well as an easy way to display them and pass them along to the Colony Simulator.

MiniGame has a ColonyScoreCard built into it, accessible by the Score property. Here are some examples of how to use it:

class MyGame : MiniGame
{
public override void Update(ContentManager content)
{
Score.Gather(ColonyResources.Money, 500); // Get 500 Monies

MyGameObject mgo = new MyGameObject();
mgo.GiveMyGameCarbon(); // Get 1 Carbon

Score.IncurDamageCost(100); // On CashOut, Money = Max (Money - DamageCosts, 0)

int HowMuchMoneyIHave = Score.QueryResource(ColonyResources.Money);
}

public void DisplayTheScore()
{
bool playerWonTheMinigame = true; // Can be set to false if the player lost
Score.Display(playerWonTheMinigame ); // Displays a copy of the current score and a message for succses/failure
Score.CashOut(); // Transfers resources from MyGame to the Colony Simulator
}

// ...
}

class MyGameObject : Entity
{
public void GiveMyGameCarbon()
{
ColonyBaseApplication.MiniGame.Score.Gather(ColonyResources.Carbon, 1);
}
}

==Write to the Experimental Log==

As the game runs, certain actions are recorded and written to a file (Autism Collaborative\Game\Game\bin\x86\Debug\ExperimentalLog.txt or the corresponding Release folder). In the lab, these codes are also sent through the parallel port to sync the EEG data. Every action that pertains to an experiment must be logged in order to be analyzed (that's kind of the whole point of this game!).

First define the necessary game codes.

* Open Logger.cs
* Add up to 253 codes to public enum ExperimentalCode
** All codes must start with a unique "code identifier", an underscore, and then a descriptor in UpperCamelCase
*** For minigames, the code identifier is 2 letters
** 3 codes are reserved for special parallel port functions with the software that runs the EEG machines used in lab tests

Now those codes are available for logging. Like so:

Logger.LogCode(Logger.ExperimentalCode.XX_Descriptor);

It is also possible to tell the logger to log a code every time a specific key is pressed:

InputState.Encode(Keys.A, InputState.KeyState.Down, Logger.ExperimentalCode.DEBUG_DudeJustPushedA);

Each minigame should remove the encodings when it is done, but it is also a good idea to decode the keys at the start of each minigame just in case.

InputState.Encode(Keys.A, InputState.KeyState.Down);
InputState.DecodeAll();

Every minigame should also start with its GameBegin and end with its GameEnd[Success/Failure] codes.

It may be helpful to log events for debugging purposes. These codes have the identifier "DEBUG" and will not be logged unless the game is running in Debug mode. All new DEBUG tags must be explicitly assigned a value less than 0.

==Use the Game Script==

The tAC_Engine houses a [[http://www.lua.org/ Lua]] Virtual Machine. This can be used to tweak global parameters at runtime, load them from config files, drive cutscenes, or even save and load levels.

Function callbacks are defined in C# and then invoked from a Lua file or the in-game Debug console. In other words, C# tells Lua "you may use these functions: X,Y,..." and then Lua says "do X, do Y, etc."

Here are a couple of ways to leverage this system:

===Make a Cutscene===

* Create a new lua file in the Scripts directory
** That file can call any registered function callbacks
* In the Properties window, set Copy to Output Directory to Copy if Newer
* Call that cutscene with:
GenericBaseApplication.GameManager.PlayCutscene(@"Scripts\MyCutscene.lua");

===To Register a Function Callback===

* Create the function in C# (if the function does not already exist)
** It must be declared public and non-static
** If the need arises to register a static function, declare an instanced function in GenericLuaHelper or ColonyLuaHelper that simply calls the static function.
* Register the function with the Lua Virtual Machine
** Add the special LuaCallback annotation to the function
* Call the RegisterLuaCallbacks function in the class's constructor that contains the function.
* Example:
public MyClass()
{ // Constructor
LuaHelper.RegisterLuaCallbacks(this);
}

[LuaCallback("SetMyVariable")]
public int SetMyVariable(int value)
{
mMyVariable = value;
}

===Tweak Game Parameters===

Exposing a variable to the Lua Virtual Machine allows it to be accessed by a any script (including config files) or changed at runtime in the drop down console (accessible in Debug mode by hitting "~").

* Expose a variable with a global setter/getter with a LuaCallback annotation
** Make sure to call the RegisterLuaCallbacks function in that class's constructor if the getter/setter is not in the Game Manager
* Set the default value for the variable in the config file (optional)
** There are 3 config files for the 3 configurations of the game builds
*** Debug.conf, for development
*** StandardRelease.conf, for public releases of the game
*** LabRelease.conf, for use in the lab

===Create Local Settings===

Programmers may want to change certain properties on their machines without affecting the source-controlled code. They could change the resolution, sound settings, or even have the game bypass the regular startup sequence and launch right into the middle of a MiniGame all with no effect on other developers.

* Create a new file: Autism Collaborative\Game\Game\Scripts\LocalSettings.lua
** The Visual Studio project already has this file included, but VS won't be able to edit it until the file is created manually
* Add Lua commands and save the file
** Visual Studio can now be used to edit the file
* The file is run at the end of the Debug.conf script (if it exists)
** That means that this script is only run in Debug mode
* do '''NOT''' add LocalSettings.lua to source control!

==Run the Game in the Lab==

To enable the features necessary to run the game in the lab, the file conlab.tac must exist next to the game's executable.

From visual studio:
* Change the configuration to "ReleaseLab"
* Build the solution
From a public release of the game:
* Find "constd.tac," the standard encrypted config file
* Copy "conlab.tac" to the same directory
** Autism Collaborative\Game\Game\bin\x86\Laboratory\conlab.tac is generated when the game is compiled
** If the game finds conlab, it assumes it is in the lab and uses that config file
** If conlab is not present, it assumes it is not in the lab and uses constd.tac as the config file