ZeldaGame- game assets

Once again, we will be writing up a Zelda-like animation, because the file’s on-hand and already formatted and somewhat optimized for our use. And so, if you don’t have it from following previous tutorials, here it is again:

Sample Animation Sheet

Setup

Start out by creating a new project in Torque Game Builder. I am using version 1.7.5 on my Mac, but there should be no differences between platforms or versions for this project. I’m calling mine “ZeldaGame” and including the executable, but that’s personal preference more than necessity. Once you’ve got the project created, make sure you create a new image map from the Link animation sheet above by either dragging the file into the assets pane on the right (under Static Sprites – only works on Windows), or by using the Create ImageMap button.

After creating the image map, double-click on it so that we can edit its properties as follows:

Link Image Map

Image Mode: Cell
Filter Mode: Smooth
Cell Height: 64
Cell Width: 64

This will break our sprite sheet into its individual frames, ready to be used in animations. It’s best to keep as many frames of an animation set within the same file as possible, because it will help the Torque engine to limit the number of times it is changing the texture context during the game’s execution.

Animation Naming Scheme

It is important to come up with a naming scheme for your assets and your animations. In this sample, it was fine to leave Link’s image name as linkImageMap, because it’s the only image we’re going to have. Your animation names, however, should have a structured and defined naming scheme, because it will make things much easier when you are writing the behavior (or class, if that is your preference) that will control which animation we are displaying. For this project, we will use “linkRunDirectionAnimation” for our names; link being the name of the entity, Run being the name of the object’s state (running, as opposed to swimming or dying), Direction being the direction he is running (North, South, East, or West), and Animation to denote that this is an animation resource.

We will now create four animations: North, South, East, and West. Click the Create New Animation button, and select the linkImageMap image as the base for our animation. Double-click each frame, in sequence, to add it to the animation. Change Frames Per Second for the animation to 15 (so that it looks good), and name the animation based on the direction he is going (such as linkRunSouthAnimation). Create the remaining animations, and we can begin programming our behavior.

Behave, Link!

Now we are going to write a behavior script to define the Link object’s interaction. In this project, our behavior is going to control everything about our player- it will store the object’s state, ensure that the proper animation is playing, and we will be able to edit the player’s movement speed within the editor interface. Open your project’s folder and create a new file in ZeldaGame/game/behaviors/ folder called playerBehavior.cs. You can use Notepad, Text Edit, Torsion, TextMate, or whatever your TorqueScript editor preference to write these scripts, so long as it is saved without special formatting data that may occur from applications such as word processing applications.

// Make sure the PlayerBehavior object doesn't already exist
if(!isObject(PlayerBehavior))
{
	// Create & Define the template
	%template = new BehaviorTemplate(PlayerBehavior);

	%template.friendlyName = "Player Controls";	// This is the name that will appear in the Behaviors property
	%template.behaviorType = "Player";	// This will be the category under which the behavior appears
	%template.description = "Player input for the Zelda sample";	// This will provide the user with a description of the property

	// Behavior fields will expose values to the editor interface
	// Note that, unlike the Torque Game Builder documentation's used of simply
	// "Up" and "Down", we must define "keyboard" as the source for the binding.
	%template.addBehaviorField(runNorthKey, "Run- North", keybind, "keyboard up");
	%template.addBehaviorField(runSouthKey, "Run- South", keybind, "keyboard down");
	%template.addBehaviorField(runWestKey, "Run- West", keybind, "keyboard left");
	%template.addBehaviorField(runEastKey, "Run- East", keybind, "keyboard right");

	// Bind the Movement Speed for Link
	%template.addBehaviorField(runSpeed, "Movement Speed", float, 15.0);

	// Movement Flags
	%template.direction = "South";
	%template.FLAG_RUN_SOUTH = 0;
	%template.FLAG_RUN_NORTH = 0;
	%template.FLAG_RUN_EAST = 0;
	%template.FLAG_RUN_WEST = 0;
}

In this first portion, we are actually defining the behavior template. As this is covered in the TGB documentation, I’m not going to go into too much detail- I recommend reading up if you’re unfamiliar with behaviors in TGB. Down at the bottom, though, we set some flags that we will use for checking our movement. The first, “direction,” will allow us to determine which directional animation we wish to display (North, South, East, or West). The following four are used to determine whether the associated key is being held, as we want to use prioritized animations with movement, but don’t want to lose the player’s ability to run in multiple directions.

// Called when the behavior is added to an object by the editor
function PlayerBehavior::onBehaviorAdd(%this)
{
	// Enable the Update callback
	%this.owner.enableUpdateCallback();

	// Make sure that the moveMap object exists before attempting
	// to bind keys to it
	if(!isObject(moveMap))
		return;

	// Bind our movement keys
	moveMap.bindObj(getWord(%this.runNorthKey, 0), getWord(%this.runNorthKey, 1), "runNorth", %this);
	moveMap.bindObj(getWord(%this.runSouthKey, 0), getWord(%this.runSouthKey, 1), "runSouth", %this);
	moveMap.bindObj(getWord(%this.runEastKey, 0), getWord(%this.runEastKey, 1), "runEast", %this);
	moveMap.bindObj(getWord(%this.runWestKey, 0), getWord(%this.runWestKey, 1), "runWest", %this);
}

Again, all of this is covered in the Torque Game Builder documentation. Note, however, the highlighted line. Here, we are enabling the onUpdate() callback function, which will be called every frame to allow us to update the object where needed. We will use this to check the animation against the current object state, and to update movement information.

// Utility Function - Get what our current animation name is supposed to be
function PlayerBehavior::whichAnimation(%this)
{
	return "linkRun" @ %this.direction @ "Animation";
}

// Movement Keys
function PlayerBehavior::runNorth(%this, %val)
{
	%this.FLAG_RUN_NORTH = %val;
}

// [...]

Because of their simplicity, I’m not going to include all of the movement response functions in this online sample- they each just edit their associated flag based on whether the key was pressed or released. The utility function, whichAnimation, will allow us to quickly get the animation that we are currently using. Normally, we would use an animation state variable in place of “Run,” but I’ve eschewed it in favor of simplicity.

// Player Update
function PlayerBehavior::onUpdate(%this)
{
	%standing = false;

	// Directional Animation Priority
	if(%this.FLAG_RUN_SOUTH)
		%this.direction = "South";
	else if(%this.FLAG_RUN_NORTH)
		%this.direction = "North";
	else if(%this.FLAG_RUN_EAST)
		%this.direction = "East";
	else if(%this.FLAG_RUN_WEST)
		%this.direction = "West";
	else
		%standing = true;

	// Movement
	%this.owner.setLinearVelocityY((%this.FLAG_RUN_SOUTH - %this.FLAG_RUN_NORTH) * %this.runSpeed);
	%this.owner.setLinearVelocityX((%this.FLAG_RUN_EAST - %this.FLAG_RUN_WEST) * %this.runSpeed);

	// Check the animation, and set it if it must be updated
	if(%this.owner.getAnimationName() !$= %this.whichAnimation())
		%this.owner.setAnimation(%this.whichAnimation());

	// If we're standing still, use the 'idle' frame (0)
	if(%standing)
		%this.owner.setAnimationFrame(0);
}

Here is the meat of our project. First, we create a temporary variable that we can set to mark the player as simply standing there (rather than walking in place, a la Final Fantasy). We check each of our movement flags sequentially, allowing us to prioritize which direction our player will be considered to be facing (South > North > East > West), and if none of them are pressed, we set the player to be standing (the direction variable will persist across frames, so the player will be facing the last direction he was moving). Next, we set the linear velocity -the amount the player moves each frame- in both vertical (Y) and horizontal (X) axes by calculating the value of the directional flags multiplied by the run speed (if the south and north keys are pressed together, the player will not move in that direction, for example (1-1=0=false)).

Finally, we check the animation’s name and compare it to our whichAnimation() function, and if it is not already set to the appropriate animation, we change it to such with setAnimation(). Note that these are called on the behavior’s owner, not the behavior itself – and you will want to make sure that the owner of the behavior (the object to which the behavior was assigned) is a t2dAnimatedSceneObject or a derivative of such (Animated Sprites dragged from the editor window are t2dAnimatedSceneObjects), so that the animation functions actually work. If the player is standing (%standing == true), we set the animation frame to 0, which is perfect for our idle image. You might also choose to include an idle animation, set as another animation state, if you wish to have an animated idle object.

Tying it all Together

Now, you will want to either close out the editor and re-open it, or you will want to go to Project->Reload Project in order for the editor to automatically load in our behaviors. Drag your South animation over from the editor window, under Animated Sprites, and place Link wherever you’d like. Next, select the object we just placed and go into the Edit pane. Under the Behaviors category, select “Player Controls” from the drop-down menu and click the + button the left to add the behavior to the player object.

Player Controls behavior

Now simply press Play, and use the arrow keys to move Link around. Congratulations, you’ve now got Link running around in the middle of absolutely nothing!