TouchDevelop includes a “game board” API for writing simple sprite- based games. The API includes a primitive physics engine to simplify common game loops where objects are moving while they experience gravity and friction. Game board elements can be orchestrated using events based on touch and regular timing intervals.
9.1 Introduction
123
9.2 The Board datatype
124
9.3 The Sprite datatype
130
9.4 The Sprite Collection datatype
135
9.5 Touching and board events
136
9.6 Debugging games
140
9.1
Introduction
9.1.1
What is a sprite?
In TouchDevelop, sprites are 2D bitmaps that are drawn directly to the screen. Sprites are commonly used to display information such as health bars, number of lives, or text such as scores. Some games, especially older games, are composed entirely of sprites. TouchDevelop allows creation and use of several types of sprite, such as ellipse, rectangle, text and picture. More details about a sprite’s capabilities can be obtained from
http://msdn.microsoft.com/en-us/library/bb203919.aspx www.itbook.store/books/9781430261360
9.1.2
Coordinates and units
Positions in the game board API are based on pixels. The origin of the grid is the top left corner when holding the device upright, the x-axis is horizontal, the y-axis vertical. Sprite positions refer to the center of the sprite, i.e., the halfway point of its width and height before any rotation is applied. The reasoning behind this choice is so that sprites can rotate around their center. Future versions of TouchDevelop may provide more control for offsetting sprites from their position. Speed and acceleration are measured in pixels/second and pixels/second2.
9.1.3
Game program structure
The code for a typical game has an underlying structure like the following. action main( )
◳board := media → create board(640)
// … create sprites, add color and features to the board ◳board → post to wall
event gameloop( )
// … move objects around … ◳board → update on wall
The gameloop event is triggered approximately every 50 milliseconds, i.e. about 20 times per second.
9.2
The Board datatype
The media resource three two methods for creating a game board; they are listed in Table 9-1. The maximum height supported by TouchDevelop for a board is 640 pixels. A board created by media→create board is 456 pixels wide; a board created by media→create portrait board is 480 pixels wide. A board remains invisible until it is posted to the wall.
Once posted, updates to the board state and the sprites on the board become visible only when calling board→update on wall.
The methods of the Board datatype concerned with the board’s dimensions and general appearance are listed in Table 9-2. The board has a background color and a background picture that can be set separately. The default www.itbook.store/books/9781430261360
background color is transparent, and no background picture is provided by default. An additional possibility is to copy the images captured by the device’s primary camera and use those images as an ever changing background for the board. Only one of these background possibilities can be active at a time.
Table 9-1: Methods to create a board
Methods Description
media→create board(
height : Number) : Board Creates a new board with the specified height in pixels media→create portrait board :
Board Creates a new board that fills the entire screen when displayed and assumes the device is held in portrait mode.
media→create landscape board
: Board Creates a new board that fills the entire screen when displayed and assumes the device is held in landscape mode.
9.2.1
Creating sprites
There are four kinds of sprite that display different kinds of visual content. They can have the shapes of ellipses or rectangles. They can be drawn as solid figures, or they can take the form of a piece of updatable text, or be created from a picture. There is a fifth kind of sprite known as an anchor sprite. It is invisible and has a special purpose, which is explained below under the heading ‘springs and anchors’. Sprites are associated with particular game boards and are created by methods of the Board type. The methods for creating and accessing sprites are listed in Table 9-3.
Sprites have initial positions centered on the board and no speed or angular rotation. These properties can be set for each sprite using the methods of the Sprite datatype.
In addition to the at method, a for each loop can be used to access all the sprites on a board. If board is a variable of type Board, then the loop has the following structure.
for each sprite in board where true do // access the sprite
Table 9-2: Methods of Board datatype: appearance
Board Method Description
clear background camera :
Nothing Removes any association of the board’s background image with the camera clear background picture :
Nothing Removes any background picture provided for the board height : Number Returns the board height in pixels is landscape board : Boolean Returns true if the board is designed for
viewing in landscape mode set background(color : Color) :
Nothing Sets the background color for the board
set background camera(camera
: Camera) : Nothing Sets the background for the board to be image captured by the primary camera set background picture(
picture : Picture) : Nothing Sets a background picture to display on the board width : Number Returns the board width in pixels
Table 9-3: Methods of Board datatype: creating / accessing sprites
Board Method Description
at(i : Number) : Sprite Returns sprite number i on this board instance (0 ≤ i < count)
count : Number Returns the number of sprites on this board
create anchor(width : Number,
height : Number) : Sprite Creates an invisible unmovable anchor sprite create ellipse(width : Number,
height : Number) : Sprite Creates a sprite with an elliptical shape create picture(picture : Picture) :
Sprite Creates a sprite with the same dimensions and image as the picture create rectangle(width : Number,
height : Number) : Sprite Creates a sprite with a rectangular shape create sprite set : Sprite Set Creates an empty collection of sprites create text(width : Number,
height : Number, fontSize : Number, text : String) : Sprite
Creates a sprite which is displayed on the board as a text string
During games it is very useful to have several collections of sprites. For example, one collection contains spacecraft, another asteroids, and so on.
A sprite collection can be created as an instance of the Sprite Set datatype. The method create sprite set creates a new set which can hold sprites associated with the Board instance. Sprites can be added to and removed from these sets by using methods of the Sprite Set datatype.
9.2.2
Obstacles and boundaries
Obstacles are walls that can be added to the board. Walls cannot be moved once created. Moving sprites which encounter an obstacle will bounce back with a speed determined by the product of the obstacle’s elasticity and the sprite’s elasticity. Elasticities of 1 for both the obstacle and the sprite means the sprite will maintain its full speed, albeit in a different direction. If one or both elasticities are 0, there will be full absorption of the impulse; the sprite will stick to the wall. By default, all elasticities are 1.
By default, the board is open, meaning it has no boundary. Sprites moving off the visual part of the board will simply continue moving away. Since it is common to need reflecting walls around the board, the create boundary(distance) method can be used to create a reflective set of walls around the board at the given distance from the board’s edges. The elasticity of these reflective walls is 1, i.e. the sprite’s speed is not reduced. If the distance of the boundary from the board’s edge is larger than the sprite’s size, a sprite can disappear off the screen before bouncing back and re- appearing. If the distance is set as a negative number, the boundaries are located inside the board area.
The methods for creating obstacles and boundaries are listed in Table 9-4.