• Build a cloning machine and make 79 copies of yourself. Send each of those copies to school to study various disciplines, including marketing, server programming, and 3D animation. Then spend a year building the game with your clones. Keep track of who's who by using a sophisticated armband system.
  
• Give up now because you'll never make the game of your dreams.
  

Wide-open worlds with Will
If you'd like to learn how to sculpt your own terrain in Unity, and to add 3D models, sounds, and interactivity to create a simple but functional 3D open-world game, check out, "Unity Game Development Essentials", Will Goldstone, Packt Publishing.

You got a lot of gull
The actual seagulls in the Island Demo are actually more complex than the ones in our simple example. To see what went into creating them, click on the gray arrow next to Birds in the Project panel. Then click on the arrow next to Seagull. Don't worry if you don't understand what you're seeing—the key here is to understand that the Project panel contains many of the elements, or ingredients, that go into making our Game Objects.

Don't mess with the Assets folder!
Unity stores metadata about the folder, and by moving stuff around or deleting things through your operating system, you may break your project. If you need to make changes, make them right inside Unity in the Project panel.

• Click to select the First Person Controller Prefab in the Hierarchy panel.
  
• Navigate to Edit | Frame Selected to focus on the Game Object. Alternatively, you can hover your mouse over the Scene view and press the F key on your keyboard. The First Person Controller Prefab should swing into view.
  
• Click on the Move button, which looks like four connected arrows.
  
  
  

  

  
  A tripod of three arrows appears at the center of the Game Object. The blue Z- axis runs through where the player's belly button would be. The red X-axis runs perpendicular to the X-axis. And the green Y-axis runs straight up and down through the player as if the player was hanging by a piece of string tied to the top of her head. The Y-axis is the up or down axis that we want to adjust.
  
  
  

  

  
  
• You can click-and-drag the green Y-axis arrow to move the player up into the sky, but a better method is to change the Y-axis position in the Inspector panel. Expand the gray arrow next to Transform in the Inspector panel if it's not already open, and change the Y value under Position to 400.
  
  
  

  

  
  
• Now, when you press Play to test the game, your character will start way up in the sky, floating down to the island before making a soft, quiet landing. It's a good thing that the Unity people didn't write a fall damage script, otherwise we might have some crumpled legs to contend with!
  

Changes you make while testing don't stick!
One of the more surprising features of Unity is that you can make changes to Game Objects and variables on the fly while you're testing your game. But it's important to know that the changes you make during testing will not "stick". Once you stop testing your game, the changes that you made during testing will revert to the state they were in before you clicked on the Play button. It's disheartening to make a number of changes to your game, only to realize that the Play button was on the entire time, and your changes will be lost. One way to avoid this problem is to toggle the Maximize on Play button in the Game window so that you'll be more aware of when you're testing and when you're not.

• The Hand tool (Q): Use it to click-and-drag around your scene. Hold down the Alt key on your keyboard to rotate the view. Hold down the Ctrl key (Windows) or the Command key (Apple) to zoom in and out. Your mouse wheel will also zoom the scene. Hold down the Shift key to pan, zoom, and rotate in larger increments to speed things up. This is a way for you to navigate around the game world. It doesn't actually impact the way the player sees the game. To modify the Game view, you need to use the Move or Rotate tools to modify the Camera position.
  
• The Move tool (W): This tool lets you move the Game Objects around your scene. You can either drag the object(s) around by the X, or Y, or Z-axis handles, or by the square in the center for freeform movement. Holding down the Ctrl key will snap movement to set grid increments. We saw this tool when we were positioning the First Person Controller Prefab in the middle of the sky.
  
• Rotate tool (E): Use it to spin your objects around using a neat spherical gizmo. The red, green, and blue lines map to the X, Y, and Z axes.
  
• Scale tool ®: This tool works much the same as the Move and Rotate tools. Use it to make your Game Objects larger or smaller. Dragging an X, Y, or Z handle will non-uniformly scale (squash and stretch) the object, while dragging the gray cube in the center will uniformly scale it.
  

• Select some of the Game Objects in the Hierarchy panel and move them around in the Scene window using the Scene controls. What happens when you put the bridge in the middle of the sky? Can you make one of the birds fly into a tree? What happens when you walk way out into the ocean while testing the game?
  
• Randomly right-click in the three different panels and read through the context menu options to see what you're getting yourself into.
  
• Poke around in the GameObject | Create Other menu. There's a whole list of interesting things that you can add to this scene without even touching the 3D modeling program.
  
• What happens when you delete the lights from the scene? Or the camera? Can you add another camera? More lights? How does that affect the Scene?
  
• Can you move the First Person Controller Prefab to another part of the island to change your starting position? How about starting on top of those two gigantic rocks on the beach?
  
• Can you replace the audio files to make the seagulls sound like car horns?
  
• Download a picture of kittens from the Internet and see if you can wrap it around the boulder model. Kittens rock! You can pull the kittens into your project using the Assets | Import New Asset option in the menu.
  

A tuner's paradise
The Unity 3D interface is designed to be customized. Not only can you define your own custom window layouts, but you can even write custom scripts to make certain buttons and panels appear inside Unity to speed up your workflow. That kind of thing is well beyond the scope of this article, but if you're the kind of person who really likes to get under the hood, you'll be happy to know that you can tweak Unity 3D to your heart's content—maybe add a few racing stripes and install an enormous pair of subwoofers in the back?

• Massive 80 person teams, all the way down to tiny one- or two-person teams are using Unity to create fun games.
  
• By thinking small, we'll have more success in learning Unity and producing fully functional games instead of huge but half-baked abandoned projects.
  
• Different flavors of Unity help us deploy our games to different platforms. By using the free indie version, we can deploy to the Web, and the Mac and PC platforms.
  
• The Unity interface has controls and panels that let us visually compose our game assets, and test games on the fly right inside the program!
  

public enum JointID
  {
	HipCenter = ,
	Spine = 1,
	ShoulderCenter = 2,
	Head = 3,
	ShoulderLeft = 4,
	ElbowLeft = 5,
	WristLeft = 6,
	HandLeft = 7,
	ShoulderRight = 8,
	ElbowRight = 9,
	WristRight = 10,
	HandRight = 11,
	HipLeft = 12,
	KneeLeft = 13,
	AnkleLeft = 14,
	FootLeft = 15,
	HipRight = 16,
	KneeRight = 17,
	AnkleRight = 18,
	FootRight = 19,
	Count = 20,
  } 

• Vector - For Source and Target Joints, you also have to define the Vector to check X or Y against one another.
  
• Operator - Do you expect the Source Vector to be Bigger or Smaller than the Target Vector?
  
• Score - If the rule is true, what is the score for the rule.
  

• Kinect Manager
  
• Configuration Manager
  
• Video Manager
  
• Authentic Manager
  

public KinectManager()
{
	try
	{

	KinectNui = new Runtime();

	KinectNui.Initialize(RuntimeOptions.UseColor | RuntimeOptions.UseSkeletalTracking |
							RuntimeOptions.UseColor);

	KinectNui.VideoStream.Open(ImageStreamType.Video, 2, 
	ImageResolution.Resolution640x480, 
			ImageType.ColorYuv);

	KinectNui.SkeletonEngine.TransformSmooth = true;
	var parameters = new TransformSmoothParameters
							{
							Smoothing = 1.0f,
							Correction = .1f,
							Prediction = .1f,
							JitterRadius = .05f,
							MaxDeviationRadius = .05f
							};
	KinectNui.SkeletonEngine.SmoothParameters = parameters;

	_lastTime = DateTime.Now;
	Camera = KinectNui.NuiCamera;

	IsInitialize = true;
	StatusMessage = Properties.Resources.KinectReady;
	}
	catch (InvalidOperationException ex)
	{
	IsInitialize = false;
	StatusMessage = ex.Message;
	}
} 

public void ChangeCameraAngle(ChangeDirection dir)
{
	if (!IsInitialize) return;

	try
	{
	if (dir == ChangeDirection.Up)
		Camera.ElevationAngle = Camera.ElevationAngle +
		Properties.Settings.Default.ElevationAngleInterval;
	else
		Camera.ElevationAngle = Camera.ElevationAngle -
		Properties.Settings.Default.ElevationAngleInterval;

	StatusMessage = Properties.Resources.KinectReady;
	}
	catch (InvalidOperationException ex)
	{
	StatusMessage = ex.Message;
	}
	catch (ArgumentOutOfRangeException outOfRangeException)
	{
	StatusMessage = outOfRangeException.Message;
	}
}  

public static Uri GetVideo(VideoType type)
{
  if (string.IsNullOrEmpty(Properties.Settings.Default.VideosLibraryFolder) ||
	  !Directory.Exists(Properties.Settings.Default.VideosLibraryFolder))
	  return null;
  else
  {
	  string value = null;
	  switch (type)
	  {
		  case VideoType.In:
			  value = Properties.Settings.Default.VideosLibraryInFile;
			  return string.IsNullOrEmpty(value) || !File.Exists(value) ?
				  CollectRandomMovie() : new Uri(value);
		  case VideoType.Out:
			  value = Properties.Settings.Default.VideosLibraryOutFile;
			  return string.IsNullOrEmpty(value) || !File.Exists(value) ?
				  null : new Uri(value);
		  default:
			  return CollectRandomMovie();
	  }
  }
} 
 private static Uri CollectRandomMovie()
{
	var movies = new ArrayList();

	foreach (var filter in Properties.Settings.Default.VideoFilter)
		movies.AddRange(Directory.GetFiles(Properties.Settings.Default.VideosLibraryFolder,
			filter));

	if (movies.Count == ) return null;

	var rnd = new Random();
	return new Uri(movies[rnd.Next(movies.Count)].ToString());
} 

public static ObservableCollection Load()
{
	var deserializer = new XmlSerializer(typeof(ObservableCollection));
	try
	{
		var xs = new XmlSerializer(typeof(ObservableCollection));
		var memoryStream = 
	new MemoryStream(Encoding.UTF8.GetBytes(Properties.Settings.Default.Rules));
		var xmlTextWriter = new XmlTextWriter(memoryStream, Encoding.UTF8);
		return (ObservableCollection)xs.Deserialize(memoryStream);
	}
	catch (Exception)
	{
		return new ObservableCollection();
	}
} 
public static void Save(ObservableCollection items)
{
	try
	{
		var memoryStream = new MemoryStream();
		var xs = new XmlSerializer(typeof(ObservableCollection));

		var xmlTextWriter = new XmlTextWriter(memoryStream, Encoding.UTF8);
		xs.Serialize(xmlTextWriter, items);

		memoryStream = (MemoryStream)xmlTextWriter.BaseStream;
		var xmlizedString = Encoding.UTF8.GetString(memoryStream.ToArray());

		Properties.Settings.Default.Rules = xmlizedString;
	}
	catch (Exception ex)
	{
		throw new ArgumentException(ex.Message);
	}
} 

public void ChecksForAuthentic(JointsCollection joints)
{
  if (_rules.Count == ) return;

  var fixJoints =
	  joints.Cast().Where(
		  joint => joint.Position.W >= .6f &&
			  joint.TrackingState == JointTrackingState.Tracked).ToList();

  var sb = new StringBuilder();
  for (var index = ; index < _rules.Count; index++)
  {
	var rule = _rules[index];
	var s = (from j in fixJoints.Where(joint => joint.ID == rule.Source) select j).
		DefaultIfEmpty(new Joint() { TrackingState = JointTrackingState.NotTracked }).
		Single();

	var t = (from j in fixJoints.Where(joint => joint.ID == rule.Target) select j).
		DefaultIfEmpty(new Joint() { TrackingState = JointTrackingState.NotTracked }).
		Single();

	if (s.TrackingState == JointTrackingState.NotTracked ||
		t.TrackingState == JointTrackingState.NotTracked) break;

	var sv = s.ToFloat(rule.SourceVector);
	var tv = t.ToFloat(rule.TargetVector);

	if (rule.Operator == Operators.Bigger && sv > tv)
	{
	  Score = Score + rule.Score;
	  sb.AppendLine(string.Format("Bigger -> Source: {0}, Target:{1} , Vector:{2}",
		  rule.Source, rule.Target, rule.SourceVector));
	}
	else if (rule.Operator == Operators.Smaller && sv < tv)
	{
	  Score = Score + rule.Score;
	  sb.AppendLine(string.Format("Smaller -> Source: {0}, Target:{1} , Vector:{2}",
		  rule.Source, rule.Target, rule.SourceVector));
	}
  }

  if (Score >= _goal)
	IsAuthentic(Score, sb.ToString());
} 

This is an affiliate banner - registering with design3 will also benefit GameDev.net!

• Revised profiles, tips, and quotes from industry professionals and educators
  
• New and updated game screenshots, photos, illustrations, and diagrams
  
• Expanded sections on the newest trends in game development including mobile, social, and serious games
  
• Coverage of new console and mobile platforms including the PlayStation Vita, Wii U and Nintendo 3DS
  
• Discussions of new technologies -- including 3D, motion control, augmented reality, game engines, and development tools
  

• How are a game’s challenges and strategies associated with gameplay?
  
• What are interactivity modes and how do they relate to gameplay?
  
• What is the relationship between gameplay and story?
  
• What is the difference between static and dynamic balance?
  
• How can the Prisoner’s Dilemma and the tragedy of the commons be applied to cooperative gameplay?
  

Gameplay and story are the same. The best game systems tell a story through the system itself. We really hit home runs when gameplay goals and story emotional goals intersect.

—Chris Klug (Faculty, Entertainment Technology Center, Carnegie Mellon University)

Victory exclamation in Wii Fit Plus (Courtesy: Nintendo)

Using Tabletop Games in Gameplay Design

Trying to understand the nature of a gameplay experience directly from a video game is akin to trying to understand an internal combustion engine while it’s running at 60mph! A tabletop game allows you to break down all the components of the game and see how all sections (mechanics, rules, characterization, player risk/reward structures, psychological paradigms) interrelate. Good designers understand instinctively that the platform must always fit the task at hand. When constructing a gameplay experience, it is crucial to select a way of depicting it so that you can “see” how the elements work in the best context. Just as some stories are best told in the form of a novel and others are best told in the language of film, certain game elements fit best into different modes. This allows you to shift the gameplay fluidly from platform to platform as the situation demands. Good design is like kendo: When the object is to win, the weapon you use should be the one that will best accomplish that goal.

—Mike Pondsmith (Founder, Owner & Lead Designer, R. Talsorian Games; Senior Lecturer,
Game Software Design & Production, DigiPen Institute of Technology)

Loss indicator in Torment. (Courtesy: FluidPlay)

The Dynamic Language of Games

Only the active contribution of the players can determine the actual outcome of the game, the specificity of the experience. I have noticed that it is very hard for students to get past this aspect of game design; the fact that the player input will intrinsically change the nature of what they’ve created. But once they do understand this, and start thinking about games as a dynamic language, rather than trying to force a particular experience on the players, they realize just how exciting this type of entertainment can be—both for players and designers.

—Tracy Fullerton (Associate Professor, USC School of Cinematic Arts;

Director, Game Innovation Lab)

Emotional Gameplay

Create mechanics that can attain the sweet spot of challenge and reward as well as accommodate multiple play styles. Then wrap those mechanics up in a blanket of story, character development, and/or emotional ties. Story provides a comforting security blanket as the player mentally traverses the rules and mechanics of the game. And, with any security blanket, players form an emotional attachment -- and when the rules and mechanics either fail to amuse/stimulate or reach a plateau (think grind), the player can always latch on to this blanket until they get to the next gameplay challenge.

— Jennifer F. Estaris (Senior Game Designer, Nickelodeon Virtual Worlds)

Story and character development interact on a very deep level. The more connected players feel to a character, the more invested they are in the gameplay. When this relationship is created effectively, developers can really pull at certain strings to create certain emotions in the player. When there isn’t a relationship to the character, the gameplay can feel stale; it can still be fun, but players will be less invested – and less likely to share their experiences with others.

—Nathan Madsen (Composer & Sound Designer, Madsen Studios LLC)

From a ludological perspective, experiencing gameplay includes interacting with game designs to perform cognitive or motor tasks that can trigger various emotions. The interesting part is how these emotions arise, since they can be triggered by player motivations, performance of the game task or by closure through completion of tasks. I would argue that the most significant and most memorable gameplay elements are therefore those that have a strong emotional impact on us. This can be the addition of a new skill or weapon or the pure joy of performing wall jumps with a lively animated character.

—Dr. Lennart E. Nacke (Assistant Professor, Faculty of Business and Information Technology,
University of Ontario Institute of Technology)

(Courtesy: Sony Computer Entertainment America)

Player-to-game interactivity includes how the player interacts with the game’s computer-generated characters (such as in Tekken 6).
(Courtesy: Namco Bandai Games America Inc.)

Team player-to-player interactivity occurs in games such as Star Trek Online. (Courtesy: Cryptic Studios)

Player-to-developer interactivity occurs in official player forums, as shown in The Sims 3. (Courtesy: Electronic Arts)

Players interact with their Wii remotes (input devices) while playing games such as Wii Sports. (Courtesy: Nintendo)

Kevin D. Saunders - Creative Director, Alelo (Courtesy: KS)

Chess is a classic example of a zero-sum game. (Courtesy: Getty Images)

Games that involve cooperation such as Guitar Hero 5 are non zero-sum games. (Courtesy: Activision)

The Prisoner’s Dilemma payoff matrix shows four possible outcomes. (Courtesy: Diagram by Per Olin)

• Reward: You are both rewarded for cooperating with each other. (Neither of you confessed to the theft, and the authorities can’t prove that either of you were involved in the crime.) You are hounded by the authorities for a year until they finally give up (or you are kept in jail as long as possible before your lawyers come to get you!). You both earn 3 points and spend only 1 year in jail.
  
• Punishment: You are both punished for squealing on each other. (The authorities now know that both of you were involved.) You don’t have to stay in jail for five years, but three is bad enough! You both earn only 1 point and must spend 3 years in jail.
  
• Temptation: You decide to squeal, but your partner keeps quiet. (The authorities have what they need on your partner.) This is the best possible outcome for you personally, but your partner suffers. You earn 5 points and are free to go.
  
• Defeat: You decide to keep quiet, but your partner squeals on you. (The authorities have what they need on you.) This is the worst possible outcome for you, but your partner is home free. You don’t earn any points and must spend 5 years in jail.
  

A tragedy of the commons will occur if everyone in a Viking ship stops rowing—since the ship would never reach its destination. Similarly, if everyone
stops to look at an accident cleanup at the side of the freeway, a traffic jam will result. (Courtesy: Illustration by Ben Bourbon, iStock Photo)

Challenges in Need for Speed: Shift are both explicit (win races, beat others) and implicit (tune your car to optimize it for each race).

(Courtesy: Electronic Arts)

Board games such as backgammon provide perfect information to the players, while card games such as poker
provide imperfect information to the players. (Courtesy: Illustration by Ben Bourbon)

Fog of war is a common way of graphically representing incomplete information in a strategy game such as Civilization V. (Courtesy: Firaxis)

Platformers such as Braid typically require intrinsic knowledge and skills to achieve success. (Courtesy: Hothead Games)

In Minecraft, players apply extrinsic knowledge (e.g., wood burns, ore melts) in order to build anything they can imagine—including
shelters that protect them from the monsters that come out at night! (Courtesy: Mojang AB)

Minecraft is not a game but a genre that embraces creativity, cares more about experience than rules, and lets people experience the joy of collaboration. If you apply this to every game you play, think of the worlds and experiences that are possible.

—Mark Terrano (Design Director, Hidden Path Entertainment)

Players navigate through mineshafts in Mystic Mine. (Courtesy: Koonsolo)

In puzzle games such as Chuzzle, players match patterns based on colors and sequences. (Courtesy: PopCap)

In sports management games such as FIFA Manager 11, players must carefully manage resources
(e.g., team members) in order to progress. (Courtesy: Electronic Arts)

In Prince of Persia: Warrior Within, players must react quickly in response to challenges. (Courtesy: Ubisoft)

• Advancement: Reaching a higher level in the game. Each successive level might increase in difficulty—as in many arcade and puzzle games. “Leveling up” could also allow your character to be more powerful, as in many RPGs.
  
• Race: Accomplishing something before another player does; this is a reaction-time challenge associated with some action and multiplayer puzzle games.
  
• Analysis: Applying mental processes to solving riddles and cryptic codes. This is a mental challenge that involves almost every other type of challenge—and it’s used most widely in puzzle and adventure games.
  
• Exploration: Moving into new areas and seeing new things; satisfies the curiosity of the player, and it’s popular in adventure games and RPGs.
  
• Conflict: Disagreements or combat between characters; used in almost all game genres to provide dramatic tension.
  
• Capture: Taking or destroying something belonging to an opponent without being captured or killed in return; remains one of the most overarching game goals across all genres (including action and RTS games).
  
• Chase: Catching or eluding an opponent—often by utilizing either quick reflexes or stealth strategies; popular in action and stealth games.
  
• Organization: Arranging items in a game in a particular order—often by utilizing spatial and pattern-matching strategies; common in most puzzle games (e.g., Bejeweled, Tetris) and in strategy games with a great deal of resource management tasks.
  
• Escape: Rescuing items or players and taking them to safety—often involving analytical reasoning and resource management.
  
• Taboo: Getting the competition to “break the rules”—often involving physical or emotional stamina (e.g., Twister, Don’t Break the Ice).
  
• Construction: Building and maintaining objects—common in process simulations; involve resource management and trade.
  
• Solution: Solving a problem or puzzle before or more accurately than the competition does—involving analytical reasoning and knowledge application. This goal is common in adventure games, which incorporate a lot of detective work.
  
• Outwit: Applying intrinsic or extrinsic knowledge to defeat the competition.
  

Escapism & Challenge

Different genres of games emphasize either escapism or challenge over the other, but every game is ultimately judged by how well it delivers each of them. Escapism is the power to transport the player into a narrative—whether it’s driving a race car, napalming hostile aliens, or being a make-believe mayor of a town named after your cat. Graphics, sound, story, and writing are essential to good escapism. Challenge is self-explanatory, but where many games go wrong is their failure to comprehend what kind of challenge best matches the product. Hardcore players are a vocal minority, and a game that is too challenging stops being good escapism and starts becoming work.

—Matt MacLean (Lead Systems Designer, Obsidian Entertainment)

Emergent Gameplay

Designing for emergence is like building a sandbox. If you give players a set of tools (mechanics) and a big area to play in (the game), they will figure out what they’ll build in the “sandbox”—and how they’ll play the game. [Note: In philosophy and systems theory, “emergence” refers to the way complex systems and patterns arise out of relatively simple interactions. Emergent gameplay is a creative use of a game in ways that were anticipated or planned by the game’s development team.]

—Troy Dunniway (Vice President & General Manager, Globex Studios)

• Consistent challenges: Players should experience gradually more difficult challenges.
  
• Perceivably fair playing experiences: Players shouldn’t be doomed from the start through their “mistakes.”
  
• Lack of stagnation: Players should never get stuck with no way to go on.
  
• Lack of trivial decisions: Players should be required to make only important decisions in the game, even in games that incorporate micromanagement.
  
• Difficulty levels: Players should have a choice of difficulty or the level should adjust to the player’s ability throughout the game.
  

In Warhammer 40,000: Dawn of War II, units have more strength than others in certain situations. (Courtesy: THQ)

Creating Meaningful Choices

The most important task for any game designer is to create meaningful and interesting choices for players. The nature of what makes a choice meaningful is something that varies widely from game to game. Is it a meaningful choice when I decide how to dress my character in a role-playing game? When I choose how many units to create for production and how many for combat in a real-time strategy game? When I determine how to use my roll in backgammon? All of these examples present good, interesting choices for players. Yet they don’t offer us easy solutions for designing such choices in our own games. Studying how other games create choice is one way to learn; another way is to design by setting player-experience goals, rather then feature-driven goals (e.g., “the game will encourage shifting alliances between groups of trading partners,” rather than “players will be able to trade resources”). With this goal in mind, the game can be tested to see when the player experience works as described (e.g., when players are making interesting choices about who to trade with and when to break an alliance with a partner). Learning how to create choices like this means getting inside the head of the player—not focusing on the game as you designed it. When you’re just beginning to design games, one of the hardest things to do is to see beyond the game you envisioned to the actual game the players are playing. What are they thinking as they make choices in your game? How are they feeling? Are the choices you’ve offered as rich and interesting as they can be? Asking these types of questions means opening up your design process to player feedback—and this is a difficult, emotional process for most designers.

—Tracy Fullerton
(Associate Professor, USC School of Cinematic Arts; Director, Game Innovation Lab)

In Age of Empires Mythologies, players begin the game with the same resources. (Courtesy: THQ)

A hierarchical caste system is a type of linear, transitive relationship—whereas a rock-paper-scissors
system is a type of circular, intransitive relationship. (Courtesy: JN)

In Crysis 2, players can shift between three modes: power (more power and ability to move quickly—but less protection and no invisibility),
cloak (less power but ability to become temporarily invisible), and armor (shown—less power but more protection).
(Courtesy: Electronic Arts / Crytek)

In the Advance Wars series (Advance Wars: Dual Strike, shown), players can join two resources (such as tanks) that have been
weakened by combat and form a “new” unit that contained their combined strength. (Courtesy: Nintendo)

In SimCity Deluxe, random events such as alien attacks can affect the game’s balance. (Courtesy: Electronic Arts)

Writing good characters and story that fit in well with the gameplay you want to create is the hardest—and the most audience engaging—part of game development.

— Frank Gilson (Senior Producer, Kabam)

In Red Faction: Guerrilla, players wreak havoc across Mars. (Courtesy: THQ)

In Farm Town, the precursor to FarmVille, players maintain balance of their resources. (Courtesy: Slashkey)

In BioShock, players must take control of a world in anarchy. (Courtesy: Take-Two Interactive)

Developing Rich Characters Through Gameplay

The best game stories grow out of the gameplay itself. What defines a character is what actions he or she takes, so the gameplay is a great way to develop rich characters over time. At the same time, a great story can add context and meaning for gameplay actions the player take. Ideally, story and gameplay play off each other to create a rich and entertaining experience for the player.

— Anne Toole (Writer, The Write Toole)

Titus Levi - Associate Professor, United International College (Courtesy: Kathleen Pittman)

The EverQuest Economy

In MMOs, characters gain skills and objects they can trade with other players using the game’s currency. In 2001, some EverQuest players decided to take the economy outside the game and began selling their assets for real money through auction and trading sites such as eBay. Economist Edward Castronova studied thousands of EverQuest transactions initiated through eBay to determine the real-world economic value generated by the inhabitants of Norrath—the fantasy world of EverQuest. The verdict? In 2002, Norrath’s gross national product (GNP) was $135 million ($2,266 per capita). (If Norrath were a real country, it would have been the 77^th richest in the world—just behind Russia!)

Edward Castronova, PhD - Associate Professor of Telecommunications, Indiana University (Courtesy: EC)

• It would have to run in a browser, so I am stuck with the browser’s Windows and menus and toolbar buttons and URL bar and such.
  
• The Javascript and Flash sandbox would preclude me from accessing the underlying OS filesystem, so I could not open or save text files on the computer.
  

• Create a SWF file using Flash or Flex. If you want to talk to the phone’s features, use the AIR native class library. Note that AIR only contains the second-generation AS3 VM, so it cannot work with old AS1 or AS2 code. Unless you have an old game you are porting to mobile, this should not be much of a problem.
  
• Create an XML file containing a description of the application. This file contains things like the application’s name, version number, path to icons, security descriptor, orientation, etc.
  
• Run the packager. In all cases, the packager is a console application that can be run from a build script or from within the Flash IDE. The packager takes the XML description, SWF, and any other resources (like the icon PNG files) and builds the runtime file.
  
• Copy your executable to your phone and run it.
  

Figure 1: Hexapies

Figure 2: Brain Bones in Flash. My biggest tip for using the Flash IDE is to put “one really bigass monitor” in your budget, as there are a lot of panels you will want to use.

Brain Bones running on the Playbook Simulator.

Brain Bones running on a Motorola Droid

Brain Bones running on an iPod Touch 4

Brain Bones running on a Barnes & Noble Nook Color

Brain Bones running on Windows as an AIR application. Note the volume slider in the lower right. It’s not there on devices with hardware volume buttons.

Brain Bones running on a Mac as an AIR application

And finally, just to be gratuitous, the Brain Bones SWF running in the Chrome web browser as a web app.

• Set the alpha property to zero. This works, but it’s not good practice because, while you can’t see the object, it is still in the rendering pipeline and is included in rendering and bounding-box calculations. And if you are developing for a CPU-constrained platform, you do not want to spend time drawing things you can’t see.
  
• Set the visible property to false at runtime. This is much better practice than setting alpha to zero, but you have to remember to code for it.
  

Intel AppUp Developer Program

AppUp Center

Now Accepting MeeGo Apps for Netbooks and Tablets

Visit our app labs homepage to learn more

Incentives for Developers

Submit Early for MeeGo

Be an early adopter and get rewarded

The Intel AppUp developer challenge and Accelerator Program

The AppUp Developer Challenge

Learn all about it here

Much More to Come

enroll today

• Sprites: Sprite resources are the digital images that you use to represent foreground objects in your games. Game Maker supports loading sprite images from .bmp, .jpg, and .gif file formats and now in Game Maker 8, .png and .gmspr as well. You can load animated images using the .gif and .gmspr formats, or by treating .png files as sequential strips of images by using _stripXX at the end of the file name (where XX = the number of frames in the image).
   
  
• Sounds: Sound resources include both sound effects and music for your games. Game Maker supports .wav, .mid (MIDI), and .mp3 formats, but .mp3 music can take up a lot of space and often contributes to the large size of finished games.
   
  
• Backgrounds: Background resources are digital images that you use to represent the background scene of your game. Backgrounds can only contain single images and Game Maker can load these images from .bmp, .jpg, .gif, and .png formats.
   
  
• Paths: Path resources contain a series of points that define a route for object resources to follow in the game. These can be either closed looping paths or open paths with a start and finish point.
   
  
• Scripts: Script resources contain programming instructions written in Game Maker Language (GML). GML provides a more advanced way of programming in Game Maker.
   
  
• Fonts: Font resources provide a means of displaying text in your game using the fonts installed on your machine. Game Maker grabs images of each character in your chosen font so that the player doesn’t need to have the same font installed on their machine.
   
  
• Timelines: Timeline resources provide a way of triggering many different actions at specific points of time in your game (see Objects for more on actions).
   
  
• Objects: Object resources are the most important of all the resource types in Game Maker as they are used to represent all of the active components of your game. Objects can respond to events in the game by following a series of actions that you add to the event. In this way, you can program the desired behavior for all the different components of your game.
   
  
• Rooms: Room resources provide spaces for staging all the visible aspects of your game (levels, menus, cut scenes, and so forth) and contain all sorts of settings relating to backgrounds, views, and the game window. It also provides an editor for placing instances of objects into your rooms to determine their starting positions.
  

Figure 1–1. The main Game Maker interface with the resource list on the left

Figure 1–2. Object resources are like jelly molds and you can use them to create any number of object instances

• x and y provide the current position of the instance in the room.
  
• xstart and ystart provide the starting position of the instance in the room.
  
• xprevious and yprevious provide the room position of the instance in the previous step.
  
• hspeed is the horizontal speed of the instance (in pixels per step).
  
• vspeed is the vertical speed of the instance (in pixels per step).
  
• direction is the instance’s current direction of motion in degrees (360 degrees of rotation in an anticlockwise direction; 0 degrees is horizontally to the right).
  
• speed is the instance’s current speed in the current direction.
  
• friction is the amount of friction reducing the speed of the instance (in pixels per step).
  
• gravity_direction is the current direction of influence for gravity (defaults to 270 =
  downwards).
  
• gravity is the amount of gravity that pulls the speed of the instance in gravity_direction every step (in pixels per step).
  

• sprite_index is the sprite displayed for the instance.
  
• image_index is the current index into the images of an animated sprite displayed for the instance.
  
• image_speed is the animation speed of an animated sprite (in subimages per step). This is typically set to a value between 1 (normal forward speed) and -1 (normal backwards speed).
  
• mask_index is the sprite used for collision detection (usually set to -1, which makes themask_index the same as the sprite_index).
  
• depth is used to control the order in which instances are drawn on the screen. Highest depth values are drawn first and so appear behind those with lower values.
  
• image_xscale is a scaling value applied to the width of the sprite, where a value of 1.0 is 100% of the original width (normal size).
  
• image_yscale is a scaling value applied to the height of the sprite, where a value of 1.0 is 100% of the original height (normal size).
  
• image_angle is a rotation angle (0-360) applied to the sprite, where a value of 0 is no rotation. You can only change this variable in the registered, Pro version of Game Maker 8.
  
• image_alpha is the opacity of the sprite (how difficult it is to see through it), which can range from a value of 1.0 for fully opaque (unable to see through it at all) to a value of 0.0 for fully-transparent (invisible).
  
• image_blend is a color applied to the sprite when it is drawn. It is set to c_white by default, and using different values will change the color of the sprite when it is drawn. You can only change this variable in the registered, Pro version of Game Maker 8.
  
• visible determines whether the object is visible or invisible (true or false).
  
• solid determines whether the object is treated as solid in collisions (true or false).
  
• persistent determines whether the object will continue to exist in the next room, or whether it remains part of the room in which it was originally created (true or false).
  

• id is a unique identifying number that distinguishes the current instance from any other.
  
• object_index is the index of the object resource that the current instance is an instance of.
  

• sprite_width is the width of the current sprite displayed for the instance.
  
• sprite_height is the height of the current sprite displayed for the instance.
  
• sprite_xoffset is the x position of the origin within the sprite.
  
• sprite_yoffset is the y position of the origin within the sprite.
  
• image_number is the number of images in the current sprite.
  
• bbox_left is the x coordinate of the left edge of the sprite’s bounding box in the room.
  
• bbox_right is the x coordinate of the right edge of the sprite’s bounding box in the room.
  
• bbox_top is the y coordinate of the top edge of the sprite’s bounding box in the room
  
• bbox_bottom is the y coordinate of the bottom edge of the sprite’s bounding box in the room.
  

• other is an object that is used to refer to the other instance involved in a collision event. So other.x is the x position of the other object involved in a collision.
  
• all is an object that refers to all instances, so setting all.visible to 0 would make all instances of all objects invisible.
  
• global is an object used to refer to global variables that you create yourself.
  

• score is the global score value (as used by the actions on the score tab).
  
• lives is the global lives value (as used by the actions on the score tab).
  
• health is the global health value (as used by the actions on the score tab).
  
• mouse_x is the current x position of the mouse cursor in the room.
  
• mouse_y is the current y position of the mouse cursor in the room.
  
• room_caption is the caption shown in the window title bar.
  
• room_width is the width of the current room in pixels.
  
• room_height is the height of the current room in pixels.
  

Figure 1–3. The screen coordinate system used in Game Maker, illustrated for a standard 640x480 room

Figure 1–4. The angle system used in Game Maker

Figure 1–5. A sprite displayed in front of a background with and without punch-through transparency


Figure 1–6. The jagged edges produced by punch-through transparency (left) compared to the smoother edges produced by alpha transparency (right)

Why App Stores Matter

The App Store Gap

The AppUp Model

The Start of AppUp

Broadening Developer Environments

Broadening OS, Device and Storefront Options

Industry and Ecosystem Support

Show Me The Money

• Sprites: Sprite resources are the digital images that you use to represent foreground objects in your games. Game Maker supports loading sprite images from .bmp, .jpg, and .gif file formats and now in Game Maker 8, .png and .gmspr as well. You can load animated images using the .gif and .gmspr formats, or by treating .png files as sequential strips of images by using _stripXX at the end of the file name (where XX = the number of frames in the image).
• Sounds: Sound resources include both sound effects and music for your games. Game Maker supports .wav, .mid (MIDI), and .mp3 formats, but .mp3 music can take up a lot of space and often contributes to the large size of finished games.
• Backgrounds: Background resources are digital images that you use to represent the background scene of your game. Backgrounds can only contain single images and Game Maker can load these images from .bmp, .jpg, .gif, and .png formats.
• Paths: Path resources contain a series of points that define a route for object resources to follow in the game. These can be either closed looping paths or open paths with a start and finish point.
• Scripts: Script resources contain programming instructions written in Game Maker Language (GML). GML provides a more advanced way of programming in Game Maker.
• Fonts: Font resources provide a means of displaying text in your game using the fonts installed on your machine. Game Maker grabs images of each character in your chosen font so that the player doesn’t need to have the same font installed on their machine.
• Timelines: Timeline resources provide a way of triggering many different actions at specific points of time in your game (see Objects for more on actions).
• Objects: Object resources are the most important of all the resource types in Game Maker as they are used to represent all of the active components of your game. Objects can respond to events in the game by following a series of actions that you add to the event. In this way, you can program the desired behavior for all the different components of your game.
• Rooms: Room resources provide spaces for staging all the visible aspects of your game (levels, menus, cut scenes, and so forth) and contain all sorts of settings relating to backgrounds, views, and the game window. It also provides an editor for placing instances of objects into your rooms to determine their starting positions.

• x and y provide the current position of the instance in the room.
• xstart and ystart provide the starting position of the instance in the room.
• xprevious and yprevious provide the room position of the instance in the previous step.
• hspeed is the horizontal speed of the instance (in pixels per step).
• vspeed is the vertical speed of the instance (in pixels per step).
• direction is the instance’s current direction of motion in degrees (360 degrees of rotation in an anticlockwise direction; 0 degrees is horizontally to the right).
• speed is the instance’s current speed in the current direction.
• friction is the amount of friction reducing the speed of the instance (in pixels per step).
• gravity_direction is the current direction of influence for gravity (defaults to 270 = downwards).
• gravity is the amount of gravity that pulls the speed of the instance in gravity_direction every step (in pixels per step).

• sprite_index is the sprite displayed for the instance.
• image_index is the current index into the images of an animated sprite displayed for the instance.
• image_speed is the animation speed of an animated sprite (in subimages per step). This is typically set to a value between 1 (normal forward speed) and -1 (normal backwards speed).
• mask_index is the sprite used for collision detection (usually set to -1, which makes themask_index the same as the sprite_index).
• depth is used to control the order in which instances are drawn on the screen. Highest depth values are drawn first and so appear behind those with lower values.
• image_xscale is a scaling value applied to the width of the sprite, where a value of 1.0 is 100% of the original width (normal size).
• image_yscale is a scaling value applied to the height of the sprite, where a value of 1.0 is 100% of the original height (normal size).
• image_angle is a rotation angle (0-360) applied to the sprite, where a value of 0 is no rotation. You can only change this variable in the registered, Pro version of Game Maker 8.
• image_alpha is the opacity of the sprite (how difficult it is to see through it), which can range from a value of 1.0 for fully opaque (unable to see through it at all) to a value of 0.0 for fully-transparent (invisible).
• image_blend is a color applied to the sprite when it is drawn. It is set to c_white by default, and using different values will change the color of the sprite when it is drawn. You can only change this variable in the registered, Pro version of Game Maker 8.
• visible determines whether the object is visible or invisible (true or false).
• solid determines whether the object is treated as solid in collisions (true or false).
• persistent determines whether the object will continue to exist in the next room, or whether it remains part of the room in which it was originally created (true or false).

• id is a unique identifying number that distinguishes the current instance from any other.
• object_index is the index of the object resource that the current instance is an instance of.

• sprite_width is the width of the current sprite displayed for the instance.
• sprite_height is the height of the current sprite displayed for the instance.
• sprite_xoffset is the x position of the origin within the sprite.
• sprite_yoffset is the y position of the origin within the sprite.
• image_number is the number of images in the current sprite.
• bbox_left is the x coordinate of the left edge of the sprite’s bounding box in the room.
• bbox_right is the x coordinate of the right edge of the sprite’s bounding box in the room.
• bbox_top is the y coordinate of the top edge of the sprite’s bounding box in the room.
• bbox_bottom is the y coordinate of the bottom edge of the sprite’s bounding box in the room.

• other is an object that is used to refer to the other instance involved in a collision event. So other.x is the x position of the other object involved in a collision.
• all is an object that refers to all instances, so setting all.visible to 0 would make all instances of all objects invisible.
• global is an object used to refer to global variables that you create yourself.

• score is the global score value (as used by the actions on the score tab).
• lives is the global lives value (as used by the actions on the score tab).
• health is the global health value (as used by the actions on the score tab).
• mouse_x is the current x position of the mouse cursor in the room.
• mouse_y is the current y position of the mouse cursor in the room.
• room_caption is the caption shown in the window title bar.
• room_width is the width of the current room in pixels.
• room_height is the height of the current room in pixels.

• Start up your version of Flash. I am using CS3, but this will work exactly the same in CS4 and CS5.
• Create a .fla file in the /source/projects/stubgame/flashIDE/ folder called stubgame.
• In the /source/projects/stubgame/flashIDE/ folder, create the following package structure for your game: /com/efg/games/stubgame/
• Set the frame rate of the Flash movie to 30 FPS. Set the width and height both to 400.
• Set the document class to com.efg.games.stubgame.Main
• We have not yet created the Main.as class so you will see a warning. We are going to create this later in this chapter.
• Add the framework reusable class package to the class path for the .fla file
  • In the publish settings, select [Flash] -> [ActionScript 3 Setting].
  • Click the Browse to Path button and find the /source folder we created earlier for the package structure. Select the classes folder, and click the choose button. Now the com.efg.framework package will be available for use when we begin to create our game. We have not created the framework class files yet, but we will be doing this very shortly.

• Create a folder inside the [source lang='plain'][projects][stubgame] folder called [flexSDK] (if you have not already done so).
• Start Flash Develop, and create a new project:
• • Select Flex 3 Project.
  • Give the project the name stubgame.
  • The location should be the /source/projects/stubgame/flexSDK folder.
  • The package should be com.efg.games.stubgame.
  • Do not have Flash Develop create a project folder automatically. Make sure the Create Folder For Project box is unchecked.
  • Click the OK button to create the project.
• Add the class path to the framework to the project:
• • Go to the [project] -> [properties] -> [classpaths] menu item.
  • Click the add class path button.
  • Find the /source folder we created earlier, and select the classes subfolder.
  • Click the ok button and then the apply button.

• STATE_SYSTEM_TITLE: This state is used to display a basic title screen with an OK button for the user to click to move on. Once the instructions are on the screen, the state will change to the next state.
• STATE_SYSTEM_WAIT_FOR_CLOSE: This one waits until the OK button is clicked for any instance of the BasicScreen class.
• STATE_SYSTEM_INSTRUCTIONS: This state is used to display basic instructions with the same OK button as in the SYSTEM_TITLE state. It also changes to the STATE_SYSTEM_WAIT_FOR_CLOSE state until the OK button is clicked.
• STATE_SYSTEM_NEW_GAME: This state will call the game logic class and fire off its game.newGame() function. It does not wait but moves on to the NEW_LEVEL state right away.
• STATE_SYSTEM_NEW_LEVEL: With this state, we can call the game.newLevel() function to set up a new level for the given game.
• STATE_SYSTEM_LEVEL_IN: This state is used to display some basic information, if needed, for the beginning of a level. In this basic game, we simply display the level screen and wait a few seconds before moving on. The wait is accomplished by changing state to the STATE_SYSTEM_WAIT state for the specified number of frame ticks.
• STATE_SYSTEM_GAME_PLAY: This one simply calls the game logic class’s runGame function repeatedly and lets the game take care of its own logic and states.
• STATE_SYSTEM_GAME_OVER: The game over state displays the basic game over screen and waits for the OK button to be clicked before moving back to the instructions screen. It quickly changes state to the STATE_SYSTEM_WAIT_FOR_CLOSE until the OK button is clicked.
• STATE_SYSTEM_WAIT: This state waits for a specified number of frames and then fires off a simple custom event constant called WAIT_COMPLETE.

• Those that wait for a click of the OK button: titleScreen, instructionsScreen, and gameOverScreen
• Those that wait a predefined time to display the screen before moving on: levenInScreen

• The background color BackGroundBitmapData, which is associated BackGroundBimap
• The text to display on the screen, displayText
• The button that will fire off the CustomEventButtonId when clicked, which is an instance of another framework custom class we will create called SimpleBlitButton

• A width
• A height
• A Boolean (true/false) value to indicate whether or not the BitmapData will use transparency
• A color represented as an unsigned integer (uint).

• Debug Mode Menus -- Any reasonably complex game should have a debug mode menu (or console) to allow changing game behavior without restarting. Usually invoked from an uncommon key or button combination (like tilde, or B + START), this allows a way to change gameplay values or modes (such as entering debug drawing mode or no-clip). These modes are often disabled or compiled out entirely in a final build, or left in for modders and tinkerers, but either way they can be vital to the development process.
• Config Files -- Using a simple config file for gameplay values. A text file or .ini file is easy to change, easy to parse, and allows you to change things without a recompile. By watching the file modification time, you don't even need a restart, your game can automatically reload the values when the file is changed.

• End Users -- Then it better be changeable from a settings GUI screen somewhere. I.e. Screen Resolution.
• Modders -- A clear, easy to read text file; .ini files work great for this.
• A level or GUI designer -- Depends on the toolchain, but it should be available wherever they build the gui.
• A game designer -- Debug menus or your level authoring tools.
• Just you, the coder -- Go ahead and use TweakVal.

• Wrapping _TV macros in /* C style */ comments or #if 0 blocks will confuse it. // C++ style comments are OK.
• _TV macros probably won't work in header files.
• You must call ReloadChangedTweakableValues() once per frame (or however often you want updates)
• Right now requires compiler support for the __COUNTER__ macro (I've had reports that it's pretty trivial to modify it to use __LINE__ instead).
• If you're using __COUNTER__ for anything else, you'll need to modify the code to also count those macros.

• It doesn't use polygons or triangles, and no raycasting or polygon detection is performed in real-time.
• It allows curves, hills (up-down), concaves (half-pipe, etc ...), all types of camber ...
• It's not a heightmap, although it shares some characteristics . Some differences:
• • Supports various altitudes. Some paths may cross with others at different heights ...
  • The checkpoints follow the path, so we just store the terrain information that we need, not the entire "rectangle" that covers the circuit - as a heightmap would do.
• It is very transparent to the art and design areas: there's no need for splitting the track, use of specific graphical tools ...
• Efficient:
• • Very little memory needed, much less than with polygons or triangles. The amount of memory needed depends on the control point density configured. This density will not affect the continuous smoothness of the terrain, so it is possible for certain titles to have a very low density of control points.
  • Very good performance. The performace remains constant, no matter the circuit size or the control point density.
  • The collision system takes advantage of the predictable movement of the cars through the track, as they use to move “linealy” and continuosly , and the track data is stored organized. It is not efficient for aleatory movements (for instance, if a car is suddenly placed in the middle of a circuit).
  • The data structure and calculations can be reused for many other gameplay needs:
  • • barriers.
    • tracking waypoints.
    • race car positions
    • Can be used as a partition space system: collision tests only if you're in the same area, cullings graphics, LODS, optimizations ...
• Smoothness:
• • It gives us the ground as a continuous curved surface, regardless of the density of control points we use.
  • Smoothing the polygonal terrain, we separate the physics from the graphics. Depending on the control points density that we set, we will have more softness (if less control points) or more fit to the polygonal track (with more control points).
    
    Setting a density of one control point row each 3-5 meters, the physics will fit quite well to the poligonal track.
    
    Setting a density of one control point row each 50 meters, the physic track will be super-smoothed and very low memory consuming, the drawback being that you must build (or at least modify) a custom graphical track to avoid graphical-physics differences .
• We also get the normal and the tangent of the circuit.

• lengthwise : the car is 0.2 of row2 and and 0.8 of row3.
• widthwise : the car is 0.3 of column3 and 0.7 of column4.

By reading my Introduction to GameMonkey Script articles you have been introduced to the basic features of the GameMonkey Script (GM Script or simply æGMÆ herein) language and how to embed it into your game or application. This article will teach you some of the more advanced aspects of the GM language and the virtual machine API. I will begin by describing the functionality and provide examples in GameMonkey Script code itself as this allows simple and quick demonstration of the features. I will then continue this discussion with examples in C++ code to demonstrate how to access this functionality from within your game engine itself.

In order to follow this article you are assumed to have read, understood and implemented the ideas and examples presented in the introductory articles. It is also expected that you are familiar with concepts such as simple messaging systems and event handlers so that you can follow some of the sample code without issue.

This article covers the following topics:

• Cooperative Threads
• Blocking / Signalling
• Threads and æthisÆ
• Thread States
• The Structure of a Thread
• Creating Script-Extensible Entities
• Best practices for using GameMonkey

Scripting Cooperative Threads

When a thread runs, it executes a function, a sequence of bytecode that is contained within its own stackframe. Whenever you execute a script in GameMonkey the bytecode is compiled into a function and is actually created within a thread to be executed. As a result, any explicit creation of your own threads will need a function to actually execute. This concept will be covered in more detail in a later section of this article.

Creating Threads from Script

There are two ways of creating a thread in GM; the first is via the scripting language itself û there is an in-built function called thread() that takes the thread function and the values to be passed to this function as arguments. The following example demonstrates how to create a new thread from script:

global thread_1 = function( a_count )
{
  print( "[1] Starting..." );
  for (i = 0; i < a_count; i = i + 1)
  {
    print( "[1] iteration: " + i );
  };
  print( "[1] Finishing..." );
};

print( "[0] Ready to execute..." );
thread( thread_1, 100 );
sleep(1);
print( "[0] Thread created..." );

[0] Ready to execute...
[1] Starting...
[1] Iteration 0
...
[1] Iteration 99
[1] Finishing...
[0] Thread Created...

In this example, a new thread is created within the machine which executes a function to count from 0 to 99. It will continue until the function is completed, hogging the machineÆs runtime until it is done. In this example, the sleep() function is called to yield control from the main thread and into the new thread we create. Use of sleep will be discussed later on in this article.

Yielding Thread Execution

In the following example we create two threads, each counting from 0 to a specified number. This example does not use yield() û what do you think will happen when you run it?

global thread_func = function( a_name, a_count )
{
  print( "["+a_name+"] Starting..." );
  for (i = 0; i < a_count; i = i + 1)
  {
    print( "["+a_name+"] iteration: " + i );
  };
  print( "["+a_name+"] Finishing..." );
};

print( "[0] Ready to execute..." );
thread( thread_func, 1, 100 );
thread( thread_func, 2, 100 );
sleep(1);
print( "[0] Thread created..." );

[0] Ready to execute...
[1] Starting...
[1] Iteration 0
...
[1] Iteration 99
[1] Finishing...
[2] Starting...
[2] Iteration 0
...
[2] Iteration 99
[2] Finishing...
[0] Thread Created...

As you see from the output of the script, the two threads ran consecutively and not concurrently as you might have expected. The reason for this is that although two threads were created, the first was executed which blocked the second thread until it had completed. Once complete, the second thread was free to run until completion. If you intended to run a single cycle of each thread in turn you need to tell the GM machine when to yield execution to other threads. In order to tell a thread to yield, you simply call the scripted function yield() with no parameters.

The following example is the same script but with a yield() in the loop of each function.

global thread_func = function( a_name, a_count )
{
  print( "["+a_name+"] Starting..." );
  for (i = 0; i < a_count; i = i + 1)
  {
    print( "["+a_name+"] iteration: " + i );
    yield();
  };
  print( "["+a_name+"] Finishing..." );
};

print( "[0] Ready to execute..." );
thread( thread_func, 1, 100 );
thread( thread_func, 2, 100 );
sleep(1);
print( "[0] Thread created..." );

[0] Ready to execute...
[1] Starting...
[1] Iteration 0
[2] Starting...
[2] Iteration 0
...
[1] Iteration 99
[2] Iteration 99
[1] Finishing...
[2] Finishing...
[0] Thread Created...

After running the above script, you will see that instead of running consecutively as witnessed in the first example the two threads appeared to run concurrently. Internally, the GM machine ran only one thread at a time but the yield() command instructed the virtual machine to switch contexts and execute the next thread.

Sometimes you may want to pause a thread for a specific length of time, for example if you had an NPC that needed to wait for 10 seconds at a waypoint before moving on. This can be achieved using the script command sleep(), which takes a numeric parameter of how many seconds the thread needs to sleep for. A sleeping thread yields until the sleep duration has passed, after which it resumes execution of the next command. Try experimenting with the samples above and replace a yield() with sleep to see the effects it has on execution.

Blocking and Signalling

global WakeUp = false;

global thread_1 = function( a_count )
{
  while (WakeUp == false)
  {
    // Snooze
    print("zzz");
    yield();
  }

  print("I just woke up, boy was I tired!");
  
};

// Launch thread
thread( thread_1 );
// Sleep for 1 secs then set the wakeup variable
sleep(1);

WakeUp = true;

When running the script, you will see a screen full of ôzzzöÆs before the thread æwakes upÆ. The thread is actually still running here, taking up CPU cycles and waiting for the WakeUp call. GM presents a much more efficient way of handling this scenario via its blocking and signalling mechanism.

A thread can block itself until a specific signal (or one of several signals) is received. Blocking effectively takes a thread out of the active thread pool, yielding until a signal wakes it up. A simple example is demonstrated below:

global thread_1 = function()
{
  block("WAKEUP");

  print("I just woke up, boy was I tired!");
  
};

// Launch thread
thread( thread_1 );
// Sleep for 1 secs then set the wakeup variable
sleep(1);

signal("WAKEUP");

The thread will block until it receives a signal string of ôWAKEUPö, which is sent to it after 1 second. This is more efficient as itÆs not taking up interpreted script cycles checking for a scripted variable, weÆre literally waiting upon a message from the GameMonkey machine to continue. It is important to remember that a thread can block or signal on any gmVariable and not specifically strings, which I have used here as the most intuitive way to demonstrate the functionality.

LetÆs take a look a more complicated example involving two threads. Each thread will be created consecutively and will block on a different signal. The first signal will be thrown after the sleep command, which in turn will signal the other thread.

global thread_1 = function()
{
  block("WAKEUP");

  print("I just woke up, boy was I tired! You should wake up too!");
  
  signal("YOUTOO");
};

global thread_2 = function()
{
  block("YOUTOO");

  print("What did you wake me up for?");
  
};

// Launch thread
thread( thread_2 );
thread( thread_1 );
// Sleep for 1 secs then set the wakeup variable
sleep(1);

signal("WAKEUP");

I just woke up, boy as I tired! You should wake up too!
What did you wake me up for?

Often it is desirable for a thread to be able to block until it receives one of a selection signals - for example, you may want your scripted entity to walk to an area and then wait there until it receives a command to move to another point, attack an entity or indeed simply defend itself. The block and signal mechanism offers support for this by allowing you to block on multiple signals. The signal which resumes the thread is returned from the block command allowing you to act in appropriate manner.

global blockfunc = function()
{
  print( "Waiting for instruction, sir!" );
  signal_received = block("attack", "move", "defend");
  if(signal_received == "attack")
  {
    print("Attacking!");
  }
  else if (signal_received == "move")
  {
    print("Moving to position!");
  }
  else if (signal_received == "defend")
  {
    print("Defending til the death!");
  }
};

thread( blockfunc );
sleep(1);
signal("attack");

Waiting for instruction, sir!
Attacking!

In the example above, the thread will block upon 3 signals, attack, move or defend. The signal received will determine what the thread then proceeds to do û in this case the attack signal is received so the entity attacks.

Each of the signalling examples presented until now have relied upon the signal being global, meaning that if two threads were waiting on the same signal, they would both be activated together. In games this would mean that all of your game units waiting for a wakeup call will spring into action at once. You will be relieved to know that it is possible to send a signal to a single thread rather than globally. To achieve this you must know the Thread Id of the thread youÆre signalling, this is returned by the normal thread function when you first create the thread. The following example is adapted to demonstrate the same block function being used with multiple threads.

global blockfunc = function(name)
{
  print( name + ", waiting for instruction, sir!" );
  signal_received = block("attack", "move", "defend");
  if(signal_received == "attack")
  {
    print(name + " is attacking!");
  }
  else if (signal_received == "move")
  {
    print(name + " is moving to position!");
  }
  else if (signal_received == "defend")
  {
    print(name + " is defending til the death!");
  }
};

thread_1 = thread( blockfunc, "woob" );
thread_2 = thread( blockfunc, "foo" );
sleep(1);
signal("attack", thread_1);
signal("defend", thread_2);

woob, waiting for instruction, sir!
foo, waiting for instruction, sir!
woob is attacking!
foo is defending til the death!

As you have seen, the blocking and signalling mechanism in GameMonkey Script allows you to create multiple threads within the virtual machine and have them remain dormant and taking up no execution cycles until a signal is received to call it back into action. This allows you to design complex behaviours within your entities that respond to the signals that are sent back and forth between objects.

Script Threads and æthisÆ

Each thread has a special gmVariable associated with it - the this variable. The concept of this allows you to effectively run a thread against an object and always have that object in scope. If you recall in the introductory article, I demonstrated how you could use this to reference specific objects in function calls. In GameMonkeyÆs threading system, this can be used in exactly the same way, except that it can be accessed in every function. See the example that follows:

global my_entity = {
  x = 50, y = 100, name = "test"
};


global move_ent_left = function()
{
  print( "Starting thread - this.name = " + .name );
  while( this.x > 0 )
  {
    this.x = this.x - 10;
    print( this.name + " - x = " + this.x );
    yield();
  }
  print( "Ending thread - this.name = " + .name );
};

my_entity:thread( move_ent_left );
sleep(1);

Starting thread û this.name = test
test û x = 40
test û x = 30
...
Ending thread û this.name = test

The code demonstrated above creates a simple table called my_entity, which has members x, y and name. The function move_ent_left, which will simply decrement the x position of this by 10 units, is created in the global scope and accepts no parameters, so we canÆt æcheatÆ by passing an object instance to the function.

The thread itself is created as normal using the thread() function, but with one key difference û the my_entity table is passed as this via the syntax my_entity:thread( func );

The next example will show the move_ent_left function being used for multiple objects and on multiple threads.

global robot = {
  x = 50, y = 100, name = "robot"
};

global player = {
  x = 150, y = 200, name = "player"
};

global move_ent_left = function()
{
  print( "Starting thread - this.name = " + .name );
  while( this.x > 0 )
  {
    this.x = this.x - 10;
    print( this.name + " - x = " + this.x );
    yield();
  }
  print( "Ending thread - this.name = " + .name );
};

robot:thread( move_ent_left );
player:thread( move_ent_left );
sleep(1);

Starting thread û this.name = robot
robot û x = 40
Starting thread û this.name = player
player û x = 140
...
Ending thread û this.name = robot
player û x = 90
player û x = 80
...
Ending thread û this.name = player

Clever use of threads and this is an extremely useful way of giving different entities different behaviours, even if they have the same properties; all you would need to do is pass different functions on the thread. In the example that follows, we define 5 ôrobotsö that each posses a different behaviour û this behaviour is executed at runtime.

global create_robot = function(x, y, name)
{
  return { x = x, y = y, name = name, id, class="robot" };
};

global behaviour_stupid = function()
{
  print( .name + " is acting stupidly" );
};

global behaviour_seek = function()
{
  print( .name + " is seeking resources" );
};

global behaviour_rest = function()
{
  print( .name + " is resting" );
};

global robot_def = {
  {"tom", behaviour_seek},
  {"mike", behaviour_rest}, 
  {"jane", behaviour_stupid}, 
  {"bob", behaviour_stupid},
  {"sarah", behaviour_seek}
};

for(id = 0; id < 5; id = id + 1)
{
  robot = create_robot(1 * id, 10 * id, robot_def[id][0]);
  robot:thread(robot_def[id][1]);
}

sleep(1);

tom is seeking resources
mike is resting
jane is acting stupidly
bob is acting stupidly
sarah is seeking resources

If the robot were your normal game entity that is displayed on screen, IÆm sure you could appreciate how being able to script them in this way is extremely powerful.

Thread States

I have demonstrated how you can effectively use different functions to interact with a scripted object through the use of threads and this. As you have seen, GameMonkey Script threads execute a function - the state binding allows you to change the function that is running on a thread. The thread will keep the same Thread Id, but will lose any locally defined variables in the change of execution context. The following code will demonstrate how to initiate a state and change to another:

global awake = function()
{
  print("I'm awake!");
};

global resting = function()
{
  print("I am resting");
  sig = block("wakeup");
  if (sig == "wakeup")
  {
    stateSet( awake );
  }
};

global init_state = function()
{
  // Set a state on the thread
  // we're now using states
  stateSet( resting );
};

thread( init_state );
sleep(1);
signal("wakeup");

I am resting
IÆm awake!

The state of a thread is set by the first call to the in-built global function stateSet() that accepts the new state function and any additionally required parameters. You will notice that this behaves almost exactly how you created the thread in the first place, except this time you are still using the current thread and just changing the function that is being executed. If you want to pass this to the new state, you must explicitly do so when calling stateSet().Once you have set a thread state you can transition to a new state at any time by a subsequent call to stateSet().

Any subsequent changes in state allow you to query the current state function by calling stateGet() or the previous state by calling stateGetLast(). This is useful as GameMonkey allows you to do comparisons on functions, letting you react according to the previous state or simply just resume the previous behaviour by switching the state back to what it was before. If stateGet() returns null, the thread isnÆt engaged in state behaviour; likewise if stateGetLast() returns null the thread hasnÆt had a previous state.

The example that follows will demonstrate an object that is created, blocks until a condition is met, performs an action and then resumes the previous action. In one object, it will start as asleep, stir and then go back to sleep û another will start asleep, get panicked at a loud noise and then cause all sorts of chaos for the player.

global ent_state_panic = function()
{
  print(.name + " is panicking, firing off alrams and attracting attention to you");
};

global ent_state_awake = function()
{
  print(.name + " is waking up");
  this:stateSet( stateGetLast() );	// revert to previous state
};

global ent_state_sleeping = function()
{
  print(.name + " is sleeping");
  sig = block("quiet_noise", "loud_bang", "kill");
  if (sig == "quiet_noise")
  {
    this:stateSet( ent_state_awake );
  }
  else if (sig == "loud_bang")
  {
    this:stateSet( ent_state_panic );
  }
  else
  {
    print( .name + " killed" );
  }
};

/// Initialise the state on the entity
global ent_state_init = function(func)
{
  print( .name, " state initialised");
  this:stateSet(func);
};

global ent_1 = { name = "roboguard 1000" };
global ent_2 = { name = "old ticker" };

// Create two threads, one for each entity and initialise them in the sleeping state
ent_1.threadid = ent_1:thread( ent_state_init, ent_state_sleeping );
ent_2.threadid = ent_2:thread( ent_state_init, ent_state_sleeping );

sleep(1);
print( "You stand on a twig");
signal("quiet_noise");
sleep(1);
print( "You fire a gun at " + ent_1.name + " causing a loud noise");
signal("loud_bang", ent_1.threadid);
// Tell the entity to die
signal("kill", ent_2.threadid);

roboguard 1000  state initialised
roboguard 1000 is sleeping
old ticker  state initialised
old ticker is sleeping
You stand on a twig
old ticker is waking up
old ticker is sleeping
roboguard 1000 is waking up
roboguard 1000 is sleeping
You fire a gun at roboguard 1000 causing a loud noise
roboguard 1000 is panicking, firing off alrams and attracting attention to you
old ticker killed

The state transitions involved above are described in this diagram:

Sometimes itÆs useful to know about a state change before it happens to allow you to run cleanup code or trigger another behaviour. To achieve this you can call the function stateSetExitFunction() and pass a function object. The function you pass will be called just before the state of the thread changes, allowing you to run whatever code you need to. When the function completes the state will transition as expected; you could use this to play a sound effect before the real event happens, for example.

global awake = function()
{
  print("I'm awake!");
};

global waking = function()
{
  print("I am stirring...");
};

global resting = function()
{
  print("I am resting");
  sig = block("wakeup");
  if (sig == "wakeup")
  {
    stateSetExitFunction( waking );
    stateSet( awake );
  }

};

global init_func = function()
{
  // set state on thread
  stateSet( resting );
};

thread( init_func );
sleep(1);
signal("wakeup");

I am resting
I am stirring...
IÆm awake!

All state changes happen on the currently operating thread, but sometimes it would be useful to change the state of another thread in the machine. Imagine you have a thread blocking on a signal for the player to move out of cover; if the cover explodes, you may want to force the players taking cover into a different state, such as the one that decides the next action. The stateSetOnThread() function allows you to do just this and requires a thread id and a state function.

global state_advance = function()
{
  print("Leaving cover and advancing");
};

global state_decide_action = function()
{
  print("I have to decide on a next action");
};

global state_hiding = function()
{
  print("Behind cover, waiting to advance");
  sig = block("advance");
  if (sig == "advance")
  {
    stateSet( awake );
  }
};

global init_state = function()
{
  stateSet( state_hiding );
};

tid = thread( init_state );
sleep(1);
// Signal isn't thrown, tell this thread to change state
print("Cover explodes!");
stateSetOnThread( tid, state_decide_action );

Behind cover, waiting to advance
Cover explodes!
I have to decide on a next action

As you have seen, the threading functionality built into GameMonkey Script provides a useful toolset to control behaviours of your entities and offers flexible solutions to achieve your scripting needs.

Integrating GameMonkey with your Game

npcupdatefunc = function() { ... do stuff... };
npc = createNPC(npcupdatefunction);

npcupdatefunc = function() { ... do stuff... };
npc = createNPC();
npc:thread(npcupdatefunction);

This section will describe how to work with the GameMonkey Script API to take advantage of the threading functionality and offer some simple methods by which you can simplify the interface you provide to your script writers without compromising on the flexibility offered by the scripting language.

Creation of gmThreads

#include 
#include "gmThread.h"

int main(int argc, char* argv[])
{
  // Create gm virtual machine
  gmMachine	gm;
  // A test script which creates the function we're testing
  const char *testscript = "global threadfunc = function() { print(\"Hello, threads!\"); };";
  // Execute the script to create the function in the VM
  if (gm.ExecuteString( testscript, NULL, true ))
  {
    bool first = true;
    std::cout << gm.GetLog().GetEntry(first);
    return 1;
  }

  int new_threadId = 0;
  // Allocate a thread within the machine
  gm.CreateThread( gmVariable::s_null, gm.GetGlobals()->Get(&gm, "threadfunc"), &new_threadId );
  // Execute the machine
  gm.Execute(1);

  return 0;
}

The code is simple; a script is executed to create the scripted function (a global named threadfunc) and a new thread is created using the reference to the script function obtained by reading from the global table. One thing to note is that as weÆve created a scripted function using script, we need to call gmMachine::Execute() to run the thread because the original ExecuteString() call actually created a thread to run in and it is still seen as the active thread in the machine.

To demonstrate the passing of this to a thread upon creation we simply pass an actual variable installed of gmVariable::s_null (the static null value variable). An example of this follows, you will notice that the string I pass as this is available in the script function we call.

#include 
#include "gmThread.h"

int main(int argc, char* argv[])
{
  // Create gm virtual machine
  gmMachine	gm;
  // A test script which creates the function we're testing
  const char *testscript = "global threadfunc = function() { print(\"'this' passed as - \", this); };";
  // Execute the script to create the function in the VM
  if (gm.ExecuteString( testscript, NULL, true ))
  {
    bool first = true;
    std::cout << gm.GetLog().GetEntry(first);
    return 1;
  }

  int new_threadId = 0;
  // Allocate a thread within the machine
  gm.CreateThread( gmVariable(gm.AllocStringObject("Hello, this!")), gm.GetGlobals()->Get(&gm, "threadfunc"), &new_threadId );
  // Execute the machine
  gm.Execute(1);

  return 0;
}

As you expect, itÆs entirely possible to execute a native function as the thread function, you simply bind the function as normal and use the gmFunctionObject pointer wrapped up by a gmVariable. The following code demonstrates the same result as the first, this time binding a function and calling that.

int GM_CDECL gmMyThreadFunc(gmThread *a_thread)
{
  std::cout << "Hello, threads!" << std::endl;
  return GM_OK;
}

int main(int argc, char* argv[])
{
  // Create gm virtual machine
  gmMachine	gm;
  // Bind the function to use by creating a gmFunctionObject
  gmFunctionObject *threadfunc = gm.AllocFunctionObject( gmMyThreadFunc );
  int new_threadId = 0;
  // Allocate a thread within the machine
  gm.CreateThread( gmVariable::s_null, gmVariable(threadfunc), &new_threadId );
  return 0;
}

Any object can be passed to the thread as this if it has been registered within the gmMachine as a gmType and wrapped in a gmVariable. The following example shows how you can access this in the callback via the gmThread::GetThis() method. In this case I expect it to be a string type, but in your code youÆd most likely use your own entity types.

int GM_CDECL gmMyThreadFunc(gmThread *a_thread)
{
  GM_ASSERT( a_thread->GetThis()->m_type == GM_STRING );
  gmStringObject *thisstr = reinterpret_cast(a_thread->GetThis()->m_value.m_ref);
  std::cout << "'this' passed as " << thisstr->GetString() << std::endl;
  return GM_OK;
}

int main(int argc, char* argv[])
{
  // Create gm virtual machine
  gmMachine	gm;
  // Bind the function to use by creating a gmFunctionObject
  gmFunctionObject *threadfunc = gm.AllocFunctionObject( gmMyThreadFunc );
  // Add function to the global table so scripts can access it
  gm.GetGlobals()->Set(&gm, "threadfunc", gmVariable(threadfunc) );
  // Call script to make callback, pass a variable containing "hello" as this
  const char *script = "text = \"hello\"; text:thread( threadfunc );";
  gm.ExecuteString( script );
  return 0;
}

Working with æthisÆ

As you have seen previously, every gmThread has a stack slot allocated for the this variable. This can be accessed in raw gmVariable form by calling gmThread::GetThis(). The main difference between GetThis() and Param() is that GetThis() returns the gmVariable via a const pointer and not by value like the Param() functions. In the previous example (threads_03.cpp), you were accessing a string variable passed as this. It is often required that you validate the type of this variable û the gmThread.h file defines a series of useful macros for checking function parameters, there are also a few for checking the type of this, such as GM_CHECK_THIS_STRING, which will return a thread exception if this is passed as anything other than a string type.

Like the Param() functions, there are several helpers for automatically and safely converting this back to the various native types associated with the GameMonkey type. So, for example ThisString() returns as a const char* and ThisInt() returns an int.

int GM_CDECL gmThisTest(gmThread *a_thread)
{
  GM_CHECK_THIS_STRING;
  std::cout << "'this' passed as " << a_thread->ThisString() << std::endl;
  return GM_OK;
}

There are three methods for returning your user types, ThisUser() returns a void* and the gmType of the object it holds; ThisUserCheckType() will only return a non-NULL pointer to the object if the type you pass in matches the object type and finally ThisUser_NoChecks() passes you just the pointer to the data held in the user object. Of course, these are simply common conversions û you are encouraged to create your own routines should you require anything else, such as converting back and forth to your entity type automatically.

Script-Extensible Objects

The first thing we do is define our game entity. In this example we declare it to have the following attributes:

Variable	Read/Write?	Description
Id	Read	Guid of the entity
X	Read, Write	Write X position of the entity
Y	Read, Write	Write Y position of the entity

If you think back to the simple Vector binding I demonstrated in the original articles, you will remember that we used the raw Vector* pointer as the data tied to GameMonkey and bound the Dot/Ind operators to allow modification of the underlying data. This time along we want to take advantage of the flexibility of GameMonkey and effectively allow additional properties to be added to the object û for example, allowing the script writer to add a ônameö property to the object.

struct Entity
{
  Entity() : Id(0), X(0), Y(0) { }
  Entity(int id) : Id(id), X(0), Y(0) { }
  int Id, X, Y;
};

The first step to achieving this goal is to create a proxy object that holds both the raw Entity data and a gmTableObject that will be used to hold our additional properties; this proxy is represented by a ScriptEntity class. We have a choice to make at this stage; do we want to be invasive to the Entity class and allow it to hold a pointer to the ScriptEntity or do we want the ScriptEntity to wrap the Entity object? I have chosen to add a pointer to the ScriptEntity into the Entity class; this enables any other consumers of the Entity class to be aware of the additional properties and create their own or read any existing ones û this allows for some nice data-driven entities to be created as you will see shortly.

struct ScriptEntity
{
  ScriptEntity(Entity &ent) : EntityObject(ent), ScriptProperties(NULL) { }
  Entity &EntityObject;
  gmTableObject *ScriptProperties;
};

Once the basic objects have been defined the type is bound as normal. I have bound a global function createEntity() to the script environment which will allocate a new Entity from the EntityManager and also allocate a new ScriptObject and gmTableObject for it.

int GM_CDECL gmCreateEntity(gmThread *a_thread)
{
  // Create an entity from the manager
  int entityId = 0;
  Entity &ent = s_EntityManager.CreateEntity(entityId);
  // Allocate a script entity & construct it
  ScriptEntity *sent = reinterpret_cast<scriptEntity*>(s_scriptents.Alloc());
  GM_PLACEMENT_NEW( ScriptEntity(ent), sent );
  // Tie back to entity
  ent.ScriptObject = sent;
  // Create a property table
  sent->ScriptProperties = a_thread->GetMachine()->AllocTableObject();
  // Tell GM how much memory we're using
  int memadjust = sizeof(gmTableObject) + sizeof(Entity) + sizeof(ScriptEntity);
  a_thread->GetMachine()->AdjustKnownMemoryUsed(memadjust);
  // return to client
  a_thread->PushNewUser( sent, s_entitytype );
  return GM_OK;
}

IÆve chosen to use some of the in-built GameMonkey memory allocation routines for the ScriptEntity creation (gmMemFixed); this is a fairly simple fixed memory allocator which uses a freelist for reallocations. You are free to use the normal new and delete operators or to rely on memory allocation routines from your own engine.

Once this function is bound, you can create entities in script û but theyÆre not much use until you bind the operators. In this case I will bind the GetDot and SetDot operators only. They will both work in similar ways; the object is retrieved from the relevant operand and the text of the property is resolved from the gmStringObject it is passed as. If the property is resolved to either X, Y or Id (the properties of the Entity class), we simply access the relevant property on the Entity. Any other property accesses will go straight to the gmTableObject we created on the ScriptEntity, thus allowing us to get and set properties that didnÆt exist on the base class. The SetDot operator code is shown below as an example.

void GM_CDECL gmOpSetDot(gmThread *a_thread, gmVariable *a_operands)
{
  if (a_operands[0].m_type != s_entitytype)
  {
    a_thread->GetMachine()->GetLog().LogEntry( "gmEntity:OpSetDot invalid type passed" );
    a_operands[0] = gmVariable::s_null;
    return;
  }
  // Get scriptentity back
  ScriptEntity *sent = reinterpret_cast<scriptEntity*>(a_operands[0].GetUserSafe(s_entitytype));
  // Get name of 'get' prop
  std::string propname = a_operands[2].GetCStringSafe();
  // Test for our known properties and return their values back immediately
  if (propname == "X")
  {
    sent->EntityObject.X = a_operands[1].GetIntSafe();
  }
  else if (propname == "Y")
  {
    sent->EntityObject.Y = a_operands[1].GetIntSafe();
  }
  else if (propname == "Id")
  {
    a_thread->GetMachine()->GetLog().LogEntry( "gmEntity:OpSetDot cannot set Id" );
    a_operands[0] = gmVariable::s_null;
  }
  else
  {
    // Otherwise, store a value in the table
    sent->ScriptProperties->Set(a_thread->GetMachine(), propname.c_str(), a_operands[1]);
  }
}

When you bear in mind that GameMonkey Script functions can also be stored as variables, you will see that you can start adding scripted functions to the base entity class with ease û be it from the C++ API or from script itself. All functions invoked on the object have this implicitly passed, so code such as the following is possible:

ent = createEntity();
ent.name = "somebody";
ent.sayname = function() 
{ 
  print( "My name is: ", this.name ); 
};
ent.sayname();

// The entity is passed as this
int GM_CDECL gmEntityInfo(gmThread *a_thread)
{
  ScriptEntity *sent = reinterpret_cast<scriptEntity*>(a_thread->ThisUserCheckType(s_entitytype));
  if (sent == NULL)
  {
    a_thread->GetMachine()->GetLog().LogEntry("gmEntityInfo: Expected entity type as this");
    return GM_EXCEPTION;
  }
  std::stringstream infotext;
  infotext << "EntityId: ";
  infotext << sent->EntityObject.Id;
  infotext << " - Postition("; infotext << sent->EntityObject.X; infotext << ","; infotext << sent->EntityObject.Y; infotext << ") - Name: ";
  // Get name from table and pass to object
  gmVariable namevar = sent->ScriptProperties->Get(a_thread->GetMachine(), "name");
  if (namevar.IsNull() || namevar.m_type != GM_STRING)
  {
    infotext << " [No name]";
  }
  else
  {
    infotext << namevar.GetStringObjectSafe()->GetString();
  }
  std::cout << infotext.str() << std::endl;
  return GM_OK;
}

In the full example code ext_01.cpp (not shown), I added an entry to the ScriptProperties table to automatically hold this function for each entity created by the script engine:

// Bind an additional method to the entity's prop table
sent->ScriptProperties->Set(a_thread->GetMachine(), "ShowInfo", gmVariable( a_thread->GetMachine()->AllocFunctionObject(gmEntityInfo) ) );

ent = createEntity();
ent.name = "somebody";
ent.ShowInfo();

EntityId: 1 û Position(100,0) û Name: somebody

Threads, The Stack and Function Calls

A thread on the VMis composed of the following components:

• A unique idenfier
• A stack
• A function to execute
• A pointer to the current instruction (if any)
• A list of blocks and signals pending on the thread
• State information about the thread

The thread function is a gmFunctionObject which can be either a native function callback or a scripted function. A scripted function is a series of bytecode instructions that are interpreted by the GameMonkey VM to create the behaviours you see in script. The execution of the VM bytecode is dependent on the structures in the thread and the VM cannot execute a function without it.

When a function is called in GameMonkey, what actually happens? The first thing pushed to the stack is a variable containing this, it will contain null if there is no value for this. A variable holding the function object is next to be pushed to the stack, followed by any function parameters in order. Finally, a stackframe is pushed to complete the setup and initialise all internal data and structures to ready the thread for execution on the VM. The stackframe is important as it allows the VM to maintain the correct pointers to instructions and data to, for example, allow nested function calls to be made within the system. The function is then executed by the virtual machine, either by calling a native function or by interpreting the bytecode involved with the scripted function. Any return value is pushed back to the stack and the stack frame is popped, allowing the script to continue where it left off before the function call.

We can see this in action by manually creating a thread and calling a native function. The first code we write is a simple function that accepts two integer parameters and writes them to cout.

int GM_CDECL gmFunctionTest(gmThread *a_thread)
{
  GM_CHECK_INT_PARAM( a_param1, 0 );
  GM_CHECK_INT_PARAM( a_param2, 1 );
  std::cout << "Param 1: " << a_param1 << std::endl;
  std::cout << "Param 2: " << a_param2 << std::endl;
  return GM_OK;
}

gmMachine	gm;
int threadid = 0;
gmThread *thread = gm.CreateThread(&threadid);
thread->PushNull(); // Push 'this'
thread->PushFunction( gm.AllocFunctionObject(gmFunctionTest) );	// push function to call
thread->PushInt(50);
thread->PushInt(100);
thread->PushStackFrame(2);

As you can see, we create a thread, push the required information to it and then finally execute it by pushing the stack frame using gmThread::PushStackFrame. If the function were a scripted function, you would need to run it by executing the thread using gmThread::Sys_Execute or by using gmMachine::Execute() to execute the whole machine.

gmMachine gm;
// Create a global scripted function
gm.ExecuteString("global func = function(a, b) { print(\"Param 1:\", a); print(\"Param 2:\", b); };");
gmFunctionObject *func = gm.GetGlobals()->Get(&gm, "func").GetFunctionObjectSafe();
int threadid = 0;
gmThread *thread = gm.CreateThread(&threadid);
thread->PushNull(); // Push 'this'
thread->PushFunction( func ); // push function to call
thread->PushInt(50);
thread->PushInt(100);
thread->PushStackFrame(2);
thread->Sys_Execute();

If weÆd have wanted to return a value from the function itÆs a simple case of pushing it to the stack before we return and retrieving it either by getting the top of the stack from the thread, or if it was a scripted function the call to Sys_Execute accepts an optional pointer to a gmVariable allowing you to capture this if you need to.

This section has shown you how to manually call functions and how they interact with the threads and stack. It is recommended that you use the gmCall helper for most of your script calls as it wraps all of this functionality for you already and reduces the chance of errors occurring.

Callback Return Values

When a function call is made or an operator callback is invoked, you have a chance to indicate success or failure to the VM execution engine. If the call is successful (GM_OK), everything continues as normal û but what happens if there is an error? An error could be that you received the wrong parameter type to a function callback, or maybe even an internal game error that requires your script environment to be notified. In such cases, you would return a value of GM_EXCEPTION to the thread, which has the effect of causing it to terminate.

Usable values are as follows:

Value	Meaning
GM_OK	Success
GM_EXCEPTION	An error occurred
GM_SYS_YIELD	Causes a thread to immediately yield execution to another thread
GM_SYS_BLOCK	A block has been set on the thread, see later for more detail
GM_SYS_SLEEP	Force the thread to sleep after setting the Sys_SetTimeStamp and Sys_SetStartTime values accordingly

There are other values available but they are internal and shouldnÆt be used for risk of corrupting the execution of the VM.

Signalling via the API

ShowQuestDialog( Quests.SaveThePrincess );
response = block( QuestDialog.Accept, QuestDialog.Decline );
if (response == QuestDialog.Accept)
{
  // do something
}
else
{
  // do something else
}

LetÆs look at some sample code:

enum QuestDialog
{
  QD_DECLINE,
  QD_ACCEPT
};

// This function simulates a modal quest dialog
int GM_CDECL gmShowQuestDialog(gmThread *a_thread)
{
  std::cout << "A princess is in danger, do you wish to save her?" << std::endl << "[Accept | Decline]" << std::endl;
  return GM_OK;
}

void HandleUserAcceptQuest(gmMachine &gm, int threadid, QuestDialog response)
{
  // Fire signal to thread to indicate user's choice	
  gm.Signal( gmVariable( (int)response ), threadid, 0 );
}

int main(int argc, char* argv[])
{
  // Create gm virtual machine
  gmMachine	gm;
  // Bind ShowQuestDialog function to script
  gm.GetGlobals()->Set( &gm, "ShowQuestDialog", gmVariable(gm.AllocFunctionObject( gmShowQuestDialog )) );
  // Create a global table to hold Ids for QuestAccept/Decline
  gmTableObject *dialogResponses = gm.AllocTableObject();
  dialogResponses->Set( &gm, "Accept", gmVariable(QD_ACCEPT) ); // Accept = 0
  dialogResponses->Set( &gm, "Decline", gmVariable(QD_DECLINE) ); // Decline = 0
  gm.GetGlobals()->Set( &gm, "QuestDialog", gmVariable( dialogResponses ) );
  // Run an example script that calls dialog and blocks on response
  const char *script = "ShowQuestDialog(); \n"
      "response = block( QuestDialog.Accept, QuestDialog.Decline ); \n"
      "if (response == QuestDialog.Accept) { print(\"[Quest accepted]\"); } else { print(\"[Quest declined]\"); }";
  int threadid = 0;
  // Run script and capture thread it's running on
  gm.ExecuteString( script, &threadid );
  Sleep(5000);	// Wait for 5 seconds to simulate user deciding to accept
  HandleUserAcceptQuest(gm, threadid, QD_ACCEPT);
  // Tick the machine along
  gm.Execute(0);
  return 0;
}

The majority of the code is actually setting up our global script variables and binding the demonstration quest dialog function. The sample script is run on the machine which immediately calls the quest dialog function (in your implementation youÆd open a real GUI window) and then immediately blocks for the response. The signal itself is sent via a call to gmMachine::Signal, which accepts a gmVariable and an optional thread Id û you will see that this is identical to calling signal from script.

A second example is that of a door created in script. The door itself will remain closed until the game instructs it to open, perhaps by a person using a switch or firing some kind of trigger. The script for the door is simple; the door is created and immediately blocks for the signal to open. When this trigger is received, an animation game event is played asynchronously while the door script sleeps for 5 seconds. After it resumes, the close animation is played and the door goes back to blocking û this behaviour will repeat forever or until the thread is terminated by the game, perhaps in response to the door becoming impassible or destroyed.

global DoorFunction = function() 
{	
  while(true)	
  {	
    print(this, "waiting for use..."); 
    block("usedoor");	
    this:startAnimation("dooropen"); 
    sleep(5);	
    this:startAnimation("doorclose"); 
  } 
}; 
createDoor(DoorFunction);

The native callback createDoor() will create a new door instance and run the function you pass it. Note that in this example I just demonstrate the object using a text string, your game will most likely feature an actual door entity being created and returned as a user object.

int GM_CDECL gmCreateDoor(gmThread *a_thread)
{
  GM_CHECK_FUNCTION_PARAM(a_func, 0);
  // Simple example, return "TESTDOOR" as the user object
  gmStringObject *door = a_thread->GetMachine()->AllocStringObject("TESTDOOR");
  // Call passed in function as a new thread (gmCall does this under the hood)
    gmCall gmcall;
    gmcall.BeginFunction(a_thread->GetMachine(), a_func, gmVariable(door), false);
    gmcall.End();
  a_thread->PushString(door);
  return GM_OK;
}

To open the door at any point in the game, you fire the signal. IÆm executing the next frame of the VM manually here, but your game loop will be doing this each frame automatically.

// Open the door... fire global signal for now
gm.Signal(gmVariable( gm.AllocStringObject("usedoor") ), GM_INVALID_THREAD, 0);

The output of this whole example:

TESTDOOR waiting for use...
TESTDOOR starting animation: dooropen
TESTDOOR starting animation: doorclose
TESTDOOR waiting for use...

This example is an excellent way of showing how the thread that controls the door can be created within the game code itself, removing the need for a user to explicitly create them to run the door script. To the user, they are simply creating a door that will play out their behaviour, they donÆt even have to know about the signal being fired by the game.

Blocking via the API

A quick example will show you how to set up a block via script:

enum
{
  SIG_ZERO,
  SIG_ONE
};

int GM_CDECL gmBlockTest(gmThread *a_thread)
{
  gmVariable blocks[] = { gmVariable(SIG_ZERO), gmVariable(SIG_ONE) };
  int ret = a_thread->GetMachine()->Sys_Block( a_thread, 2, blocks );
  if (ret == -1)
  {
    return GM_SYS_BLOCK;
  }
  a_thread->Push(blocks[ret]);
  return GM_OK;
}

In this callback function I have set up two variables containing the values 0 and 1 and have instructed the GameMonkey machine to block the currently running thread on them. Under the hood, the gmMachine::Sys_Block function will attempt to use up any signals already pending on the thread; if a matching signal is found for one of the blocks, it will return immediately with the index of the block variable you supplied. When this happens, I push the variable back to the thread stack as a return value so that it returns the block immediately to the user to allow them to check which block was signalled. If no corresponding signal is found, Sys_Block returns a value of -1 û when this happens you return a value of GM_SYS_BLOCK to indicate to the VM that this thread should be suspended until a signal is received to wake it. When you bind the function above to the machine, it lets you run a script such as:

r = blocktest();
print( ôsignal fired:ö, r);

Games often feature asynchronous actions, such as playing an animation or sound, actor pathfinding/movement and so on. In the real world, many of these actions will be kicked off with an event dropped onto a message queue which is picked by the relevant system. Imagine the case of an NPC being instructed to move across town; the entity management system will pick up the movement message and move the entity a little bit each frame until the NPC arrives at its destination many frames later. At this point the entity manager it will signal back to the game that the movement has completed.

Your scripts will often want to trigger asynchronous behaviours but will need to treat them as if they are synchronous by waiting for the result of the task before deciding how to proceed. If the machine-bound function returned immediately after queuing the message, the script would continue as normal without waiting for completion. In a previous section you achieved this in script by using GameMonkeyÆs blocking and signalling functionality; in this case you could fire your event and then immediately block for the signal back from the game engine to wake up the thread.

doasyncbehaviour();
ret = block( ôokö, ôfailedö );
// continue as normal

For this example I will allow you to imagine a town guard in an RPG game that wanders back and forth between two towers. When he gets to a tower, heÆll inspect the area and move on if nothing is amiss. The guardÆs behaviour is described as the following series of states:

In the game engine this will be achieved by initiating the movement using a goto message to the entity manager. Upon arrival at the destination a goto_success message is sent back to the game system û should anything happen such as the destination being unreachable, the entity being attacked or so on, a goto_failed message is sent back to the game, along with other messages for the next action (if any).

The sequence of events in this asynchronous call are as follows:

1. Script calls NPCWalkTo( dest )
2. Game pushes goto message to message queue
3. Script call blocks thread and returns
4. Game frame advances, entity manager picks up movement message
5. Entity manager moves NPC each frame until destination is reached
6. Message is sent back to script manager to inform destination reached
7. Script manager signals thread of completion, script progresses as normal

global GuardMove = function()
{
  this:stateSet(GuardGotoTowerOne);
};
npc = CreateNPC();
npc:thread(GuardMove);

global GuardGotoTowerOne = function()
{
  print("Going to Tower One...");
  res = NPCGoto(this, Location.TOWER_ONE);
  if (res == Event.SUCCESS)
  {
    print("Arrived at tower One");
    this:stateSet(GuardWait);
  }
  else
  {
    print("Couldn't get there");
  }
};

GM_CHECK_INT_PARAM(a_entity, 0);
GM_CHECK_INT_PARAM(a_location, 1);
  
// Push message to Game Message queue
NPCGotoMessage *msg = new NPCGotoMessage( a_entity, a_thread->GetId(), a_location );
s_Game.GetMessageSystem().PushMessage( msg );

gmVariable blocks[] = { gmVariable(SM_SUCCESS), gmVariable(SM_FAILED) };
int res = a_thread->GetMachine()->Sys_Block( a_thread, 2, blocks );
if (res == -1)
{
  return GM_SYS_BLOCK;
}

if (_Dur >= 2500.0f)	// Simulate time passing
{
  NPCArrivalMessage *msg = new NPCArrivalMessage(ent._Id, ent._ScriptThreadId, ent._Destination);
  s_Game.GetMessageSystem().PushMessage(msg);
  ent._State = Entity::ES_WAITING;	// Go back to waiting state
  _Dur = 0;
}

if (a_msg->MessageType == MT_GOTO_SUCCESS)
{
  NPCArrivalMessage *msg = reinterpret_cast(a_msg);
  // Fire signal on thread
  _Machine.Signal( gmVariable(SM_SUCCESS), msg->ScriptThreadId, 0 );
}

• Logging1.cpp - Basic write function and hooking into std::clog
• Logging2.cpp – Adds support for posting the timestamp into logs
• Logging3.cpp – Adds a thread name to the loggings

I downloaded the Luabind code and started rummaging through it. I quickly realized that the project was way beyond the scope of what I was looking to do (which was just the most basic automatic exporting of functions from C++ to Lua). But in skimming the code, I noticed that Luabind used Boost.FunctionTypes, which was a library that I'd never paid much attention to before, so I decided to check it out. And when I did, it literally blew my mind.

Boost.FunctionTypes gives you functionality to generate typelists containing the types of the parameters to any function you specify (and more!). My Spidey sense was telling me that this was all I needed to automatically generate a type-safe interface between C++ and Lua, so I decided to see were this would take me

Breaking It Down

• Better dispatching of the Lua callback. The Lua C interface allows you to connect a string (the function name) to a static function with a given prototype, and from this callback I had to be able to call the correct instance of the class that would handle the real executing.
• Type checking and value extraction. Given the Lua stack, I needed to be able to traverse it, and for each value on the stack verify that it was of the correct type, and if it was, store it away somewhere until it was time to call my function.
• Execution. At this stage, I would be holding some kind of function object that represented the C++ function I was going to call, and I also had a list of the parameters, so the problem was invoking the functor with the parameters.
• Handling the return value. Functions that don't return anything aren't really that fun, so the final part of the puzzle was getting the return values from my C++ function back to Lua via the stack.

Better Dispatching of the Lua Callback

Lua states that all C callbacks we expose must have the following signature:

typedef int (*lua_CFunction) (lua_State *L);

Lua allows for C closures, which enable you to associate variables, integers in this case, with a specific callback. As I had a unique static callback for each type, I knew that it would be safe to store my this pointer as an integer in the closure, and cast it back when my callback got called. This gave me the following structure:

template< class T >
struct CommandT : public Command {
  CommandT(const string& name, const T& fn) 
    : Command(name)
    , fn_(fn) 
  {}

  int Execute(lua_State* lua_state) const {
    return 1;
  }

  static int callback(lua_State* lua_state){
    const CommandT* this_ptr = reinterpret_cast(lua_tointeger(lua_state, lua_upvalueindex(1)));
    return this_ptr->Execute(lua_state);
  }
  T fn_;
};

  template< class T >
  void Register(string function_name, const T& t) {
    CommandT* ptr = new CommandT(function_name, t);
    // Store the this pointer in the c-closure
    lua_pushinteger(lua_state_, reinterpret_cast(ptr));
    lua_pushcclosure(lua_state_, &CommandT::callback, 1);
    lua_setglobal(lua_state_, function_name.c_str());
    commands_.push_back(boost::shared_ptr(ptr));
  }

Type Checking and Value Extraction

IÆve experimented a bit with functors mapped over typelists before, so I had a pretty good idea of what I wanted to do here. For each application of the functor, weÆre basically walking one step down the Lua stack, and seeing if the type we get from the typelist matches the type that Lua says is on the stack. If it is, we want to get the value from the stack and store it; otherwise we signal an error in some way.

One way to implement this is by having the functorÆs operator() call a method that weÆve overloaded with all the types we want to be able to handle. The overloaded method can then use LuaÆs own lua_isXXX family of functions to ensure that the parameter has the correct type. The functor also holds a stack pointer, keeping track of where we are in the Lua stack, and increments this on each iteration.

class Extractor
{
public:
  Extractor(lua_State* lua_state, AnyParams& params) : lua_state_(lua_state), params_(params), stack_index_(1) {}

  void Extract(const int&) {
    if (!lua_isnumber(lua_state_, stack_index_)) {
      throw exception("Expected parameter of type interger");
    }
    params_.push_back(lua_tointeger(lua_state_, stack_index_));
  }

  void Extract(const std::string&) { 
    if (!lua_isstring(lua_state_, stack_index_)) {
      throw exception("Expected parameter of type string");
    }
    params_.push_back(string(lua_tostring(lua_state_, stack_index_)));
  }

  template< typename T >
  void operator()(T t) {
    Extract(t);
    stack_index_++;
  }
private:
  lua_State* lua_state_;
  vector& params_;
  int stack_index_;
};

typedef vector AnyParams; 

   typedef typename parameter_types::type ParamTypes;

  int Execute(lua_State* lua_state) const {
    AnyParams params;
    boost::mpl::for_each(Extractor(lua_state, params));
    return 1;
  }

Execution

I banged my head against this problem for a little while, until I remembered a trick that IÆd used a while back, that involved partial template specialization and a one line superstar called Int2Type.

template struct Int2Type {};

Hopefully some code will be less confusing than that description!

/**
* The executor is a class with operator() specialized on the class Int2Type, where N is the
* arity of the function we're calling. By specializing on the arity, we know the number of parameters
* the function expects, and can extract these from the vector and cast to the correct type
*/ 
template
struct Executor;

// 0 parameters
template
struct Executor, ParamTypes> {
  template void operator()(Fn& fn, const vector& /*params*/) {
    fn();
  }
};

// 1 parameter
template
struct Executor, ParamTypes> {
  template void operator()(Fn& fn, const vector& params) {
    fn( boost::any_cast >::type>(params[0]) );
  }
};

// 2 parameters
template
struct Executor, ParamTypes> {
  template void operator()(Fn& fn, const vector& params) {
    fn( 
      boost::any_cast >::type>(params[0]),
      boost::any_cast >::type>(params[1]) );
  }
};

// Typedef for the executor (based on the arity of the function)
typedef Executor< Int2Type::value>, ParamTypes> Executor;

int Execute(lua_State* lua_state) const {
  AnyParams params;
  boost::mpl::for_each(Extractor(lua_state, params));
  Executor f;
  f(fn_, params);
  return 0;
}

if (function_has_return_value) {
  return_value = function();
  push_on_lua_stack(return_value);
} else {
  function();
}

typedef typename result_type::type ResultType;
enum { IsVoidResult = boost::is_void::value };

// Typedef for the executor (based on the arity of the function)
typedef Executor< Int2Type::value>, ParamTypes, ResultType > Executor;

// Executer for void return type
int Execute(lua_State* lua_state, Int2Type) const {
  AnyParams params;
  for_each(Extractor(lua_state, params));
  Executor f;
  f(fn_, params);
  return 0;
}

// Executer for non void return type
int Execute(lua_State* lua_state, Int2Type) const {
  AnyParams params;
  for_each(Extractor(lua_state, params));
  Executor f;
  AddReturnValue(lua_state, f(fn_, params));
  return 1;
}

static int callback(lua_State* lua_state){
  const CommandT* this_ptr = reinterpret_cast(lua_tointeger(lua_state, lua_upvalueindex(1)));
  return this_ptr->Execute(lua_state, Int2Type());
}

void AddReturnValue(lua_State* lua_state, const bool value) {
  lua_pushboolean(lua_state, value ? 1 : 0);
}

void AddReturnValue(lua_State* lua_state, const int value) {
  lua_pushinteger(lua_state, value);
}

• tolua++.exe (or equivalent binary for linux folks)
• tolua++.h
• tolua++.lib (or a library file of similar name)

• tolua_export : exports a single line to the pkg file
• tolua_begin : exports all code between this and
• tolua_end : ends tolua_begin