Scrolling Game Development Kit

• OnAfterMoveSprites
• OnBeforeMoveSprites
• OnControllerMove
• OnFrameStart
• OnNewSprite
• OnPlayComplete
• OnPlayInit
• OnSpecialFunction
• OnSpritesCollide
• OnTileInteraction
  

• A number can be represented in binary as a series of bits.
• In binary, instead of a ones place, a tens place, a hundreds place, and so forth, there is a ones place, a twos place, a fours place, and so forth.
• Since each binary digit can represent true or false (this is called a boolean value, because it can only have two states), each bit can be used to store one boolean value. This allows many pieces of information to be combined into a single bit map.
• A number can be converted from standard decimal into binary by repeatedly dividing by two and using the remainder as a binary digit.
• A number can be converted from binary into decimal by adding the values of the bits that are set to one.
• The value of a single bit within the bit map can be obtained without performing any conversions by using the and operator with a mask to filter out a single bit value from the bit map. A mask reresents a single place value from a binary bit map.

Examples

Decimal value 11:

Binary value 1011:

• ACTION_UP = 1
  
• ACTION_LEFT = 2
  
• ACTION_RIGHT = 4
  
• ACTION_DOWN = 8
  
• ACTION_BUTTON1 = 16
  
• ACTION_BUTTON2 = 32
  
• ACTION_BUTTON3 = 64
  
• ACTION_BUTTON4 = 128

So, the code in OnControllerMove is using two variations of this technique to determine if the NewActions parameter indicates that the player is now pressing button 1 and the OldActions parameter indicates that it was not being pressed before. (Both NewActions and OldActions parameters are bit maps representing the bits from eActionsBits enumeration.) If it determines that the button has just been pressed, it calles a subroutine to handle the button press.

If you didn't understand the beginning of the bit masking section the first time through, go back and read it now for better understanding. You might understand it.

Custom Subroutines

Sub RecountShots()
Dim nSIdx, nLIdx

In addition to the event handling subroutines, you can define your own subs that can be called from within other subs. This is in line with standard VBScript syntax and is used a number of times in the code generated by the scripting wizard. Variables declared within a sub are local. This means that they can only be accessed within the sub.

The RecountShots sub is used to update the number of shots currently active. A shooting script utilizes this to maintain the internal array of bullets after it sees that some have disappeared.

Object Hierarchies

With ProjectObj.GamePlayer.PlayerSprite.rDef.rLayer
...
End With

GameDev has large and deep hierarchies of objects to support the complex structure of the games it maintains. The with statement is particularily useful here to avoid many long lines of code. This particular with statement locates the layer on which the player sprite resides and makes this object the current context. It is then possible to access the methods and properties of this layer object by simply preceeding the method or property name with a period.

Arrays, Object Variables, and Loops

nSIdx = 0
Do While nSIdx < nShot0Count
For nLIdx = 0 to .SpriteCount - 1
If arBtn0Shots(nSIdx) Is .Sprite(nLIdx) Then
Exit For
End If
Next


Scripts can maintain large private stores of data by putting this data in array variables. In GameDev scripting, arrays of objects can be particularily useful. The Scripting Wizard keeps an array of all the bullet sprites so that it doesn't need to loop through all active sprites when checking to see if a bullet should disappear. It is important to realize when looping through an array that a For loop will not adapt its upper bound if it changes. This is why the outer loop in this code uses a While loop instead of a For loop. This allows nShot0Count to change within the loop, and be certain that nSIdx remains within appropriate boundaries.

The Is keyword is used to compare variables to see if they refer to the same object. The code above searches through the array of active sprites to see which bullets from the internal array still exist as active sprites.

The Set Statement

If nLIdx >= .SpriteCount Then
Set arBtn0Shots(nSIdx) = arBtn0Shots(nShot0Count - 1)
nShot0Count = nShot0Count - 1
Else
nSIdx = nSIdx + 1
End If
Loop

nExpectCount = .SpriteCount

In order to store objects in script variables, the Set statement is used to assign a reference. Objects remain in existence as long as at least one reference exists. This includes references by script code or by GameDev internal code. For instance, clearing the entire contents of the arBtn0Shots array will only free those objects which are not still in use by GameDev. Also, removing all the sprites from a layer and leaving the script's array intact will leave sprite objects in memory. The above code removes from the script's array any bullet sprites that are no longer part of GameDev's internal sprite array for the player sprite's layer.

nExpectCount is used to determine when the number of GameDev internal sprites has changed. This also indicates when the script should check to see if the bullet sprites have changed, that is, if any bullets have been removed. Rather than stepping through each of the sprites for every frame, the script only checks for removed bullets when the number of active sprites has changed.

GameDev vs. VBScript

Sub RemoveShot(Spr)
Dim nIdx
With ProjectObj.GamePlayer.PlayerSprite.rDef.rLayer
For nIdx = 0 to .SpriteCount - 1
If .Sprite(nIdx) Is Spr Then .RemoveSprite(nIdx) : Exit Sub
Next
End With
End Sub

There are two main aspects to understand in scripting in GameDev. The VBScript syntax defines the basic language features and is already documented by Microsoft at their website. The objects, properties, and methods implemented by GameDev are of more interest here. The quick reference provides a short description of everything available in GameDev, but does not provide any detailed documentation on how the pieces work together. The remainder of this docutorial will attempt to focus on that aspect. In the code above, notice the RemoveSprite method call. This removes an active sprite from a layer based on the sprite's index. It is used in the generated script to remove bullets according to the conditions specified in the wizard. Because it is more useful to remove a sprite based on the sprite object itself, this function is created to search through the array of active sprites for the specified sprite and then remove it based on its index.

Sprite States

Function GetStateDeltas(DX, DY)
With ProjectObj.GamePlayer.PlayerSprite
Select Case .rDef.Template.StateType
Case STATE_SINGLE
If Abs(DX) + Abs(DY) > 1 Then
DX = .DX / (Abs(.DX) + Abs(.DY))
DY = .DY / (Abs(.DX) + Abs(.DY))
Else
If Abs(DX) + Abs(DY) < 1 Then DX = 0 : DY = -1
End If
Case STATE_LEFT_RIGHT
DY = 0
If (.CurState Mod 2) = 0 Then DX = -1 Else DX = 1
Case STATE_8_DIRECTION
Select Case (.CurState Mod 8)
Case 0 : DX = 0 : DY = -1
Case 1 : DX = 1 : DY = -1
Case 2 : DX = 1 : DY = 0
Case 3 : DX = 1 : DY = 1
Case 4 : DX = 0 : DY = 1
Case 5 : DX = -1 : DY = 1
Case 6 : DX = -1 : DY = 0
Case 7 : DX = -1 : DY = -1
End Select
Case Else
DX = Cos((.CurState Mod 36) * 3.14159 / 18)
DY = -Sin((.CurState Mod 36) * 3.14159 / 18)
End Select
End With
End Function

The four intrinsic sprite types in GameDev have various ways of tracking their direction and speed. The above function is used to determine the direction of travel of a sprite based on its state. This is used to determine which direction a bullet fired by the sprite should travel (even when the sprite is motionless). Since a single-state sprite has no directional information in its state, it must be based entirely on its existing velocity. As you can see in the first case (STATE_SINGLE) if no current velocity exists, the function defaults to upward for a single state sprite.

The STATE_LEFT_RIGHT case returns a leftward velocity when the sprite is facing left, and a rightward velocity otherwise. A left-right sprite never faces up, down, or diagonally. Notice the connection between the .CurState property and the resulting velocity. A state of 0 for a left-right sprite is the left-facing state and a state of 1 is the right-facing state.

This proceeds naturally to the STATE_8_DIRECTION case. Observe how each of the eight cases represents a different direction for the eight-state sprite. 0 is straight up (vertical velocity = -1), 1 is up and right, 2 is straight right, and so forth.

Finally, 36-state sprite has the most velocity information in its state. Its state effectively represents the direction that it is facing in 10-degree increments. The state number is converted in to degrees by multiplying by 10. However, since VBScript's trigonometric functions deal in radians, we use a slightly different formula to extract its angle. Multiplying by Pi and dividing by 18 (180 degrees / 10 = 18) gives us the result we want. If you understand trigonometry, you will also understand how sin and cos convert this in to a velocity/vector. Sin is negative because the computer's coordinate system is vertically reversed from the Cartesian coordinate system.

This function utilizes VBScript's ability to pass variables by reference instead of by value (this is the default). This allows DX and DY to be changed and affect the variables passed by the caller -- a handy way to return multiple values.

Optimization

Sub Player_OnAfterMoveSprites
Dim nIdx, VLeft, VTop, VRight, VBottom, VDat
With ProjectObj.GamePlayer
VLeft = .MapScrollX
VTop = .MapScrollY
VRight = VLeft + .rMap.ViewWidth
VBottom = VTop + .rMap.ViewHeight
End With

If nExpectCount <> ProjectObj.GamePlayer.PlayerSprite.rDef.rLayer.SpriteCount Then RecountShots

End Sub


While the above code is not being applied in this sample script, it can be used to illustrate an important point. VBScript is an interpreted language, meaning it is processed at runtime and not compiled for the most efficient execution. As such, it's important to optimize code wherever possible so that it executes as efficiently as possible. This code is normally used to remove bullets that have left the view. Since our script had no such bullets defined, it's only calculating the edges of the view, and not using those values to check against bullet positions. Notice that these values are stored in variables rather than calculated for each test that would be performed. Reading a property of an object and performing arithmetic operations in addition to reading values from variables is, of course, slower than simply accessing a value in a variable. This is why the edges of the view are retrieved and calculated ahead of time. Then if there are a lot of bullets, the edges of the view don't have to be re-calculated for each bullet -- just use the stored values.

Notice that this event executes after each frame's MoveSprites stage. A further optimization could be made by removing this function altogether, since it's not needed. Also notice the use of "With". This kind of acts as another optimization because retrieving the GamePlayer property from the ProjectObj object repeatedly would be slower than simply re-using the object as returned by the GamePlayer object the first time. The With statement reuses the same object.

This secton of code also demonstrates another small piece of GameDev's object model. The map's display position and size are, of course, properties of the map object. The best way to access the currently active map object is to go through the GamePlayer property of the ProjectObj object representing the current project. GamePlayer is a single object that describes the current state of gameplay. It stores information such as the current player sprite, the scroll position of the map and the currently active map. Here we are using it to get the currently scroll position of the current map through the MapScrollX and MapScrollY properties. We also use it to get the map (rMap) from which we then retrieve the view width and height for that map. The scroll position is measured in pixels from the top left corner of the map. Note that each layer may have a different scroll position. To find out how for each layer is scrolled you must multiply the map's scroll position by the layer's scroll rate.

Conveniently, yet another of the script's optimizations falls into this function. The nExpectCount variable keeps track of how many sprites the script expects to see on the layer. If it sees the same number of sprites as it expects, it knows that it doesn't have to recount the sprites and possibly remove some from its internal arrays of bullet sprites. As long as the number of sprites remains the same on the layer, it figures it's pretty safe to assume there's no need to spend time recounting the sprites to see which are still active.

Runtime Manipulation

Sub DoFireButton0()
Dim NewSpr, DX, DY
If nShot0Count > = 5 Then Exit Sub
Set NewSpr = ProjectObj.GamePlayer.rMap.SpriteDefs("Bullet").MakeInstance
Set arBtn0Shots(nShot0Count) = NewSpr
nShot0Count = nShot0Count + 1
With ProjectObj.GamePlayer.PlayerSprite
.rDef.rLayer.AddSprite HostObj.AsObject(NewSpr)
nExpectCount = nExpectCount + 1
NewSpr.X = .X + (.Width - NewSpr.Width) / 2
NewSpr.Y = .Y + (.Height - NewSpr.Height) / 2
GetStateDeltas DX, DY
NewSpr.DX = DX * NewSpr.rDef.Template.MoveSpeed
NewSpr.DY = DY * NewSpr.rDef.Template.MoveSpeed
If NewSpr.rDef.Template.StateCount = 36 Then NewSpr.CurState = RectToPolarState(DX, DY)
End With
End Sub

GameDev has a very large and complicated object model. But with care, you can manipulate these objects, creating new ones and adding them to the project, or deleting existing objects. If done correctly, this gives you great control over what happens in the game. You almost have as much power as you would if you were directly editing the original source code. Knowing which operations are safe and which are unstable simply takes some experience and experimentation. The simpler the effect, the more likely it is to function as expected.

Not to describe exactly what operations are going on above that demonstrate this. The DoFireButton0 function handles the response to the player pressing the first button. First it checks to see if the maximum number of bullets of this type are already active. This is a simple variable check. The number of active button-0-sprites is maintained in nShot0Count. Then you will see that if we have to spawn another bullet, we have a long path to go down to do it properly -- these are the steps taken by the next single line:

• Retrieve the player object from the project.
• Get the currently active map from the player object.
• Locate the definition for a sprite called "Bullet".
• Create a new instance of this sprite (note, the definition is not an actual sprite, you have to call MakeInstance to get a sprite object that can go on the layer).
• store that new sprite object in a variable caled NewSpr.

So that's a good example of one specific set of interactions you can easily perform with GameDev and VBScript. There are many other types of interactions where you can manipulate a wide variety of GameDev's internal objects.

Wrapping Up

Function RectToPolarState(X, Y)
Dim Angle, Pi
Pi = 3.14159
If X <> 0 Then
Angle = Atn(-Y / X)
Else
Angle = -(Pi / 2) * Sgn(Y)
End If
If X < 0 Then
Angle = Pi + Angle
ElseIf Y > 0 Then
Angle = Pi * 2 + Angle
End If
RectToPolarState = ((Angle * 18) / Pi) Mod 36
End Function

HostObj.SinkObjectEvents ProjectObj.GamePlayer, "Player"
HostObj.ConnectEventsNow()
ProjectObj.GamePlayer.Play 16

The RectToPolarState doesn't introduce anything new. It just uses trigonometric functions to convert a vector into an angle for use by the previous function which used it to determine the state of a rotational sprite. I won't explain the math because it has little to do with GameDev, but know that if you need to convert a vector into an angle for a GameDev 36-state sprite, that's how to do it in VBScript.

The final three lines of code are the standard lines to connect the events and start playing the game. To connect the script to a game you now need to execute GameDev or GameDevPlayer with the "/p" command line switch. This can be done in many ways. If you have version 1.3 or later, you can specify a script name in the player settings dialog. Then when you right-click on that GDP (after it is saved) and select play, it will automatically pick up that script file. Or, you can use the Create Shortcut button in GameDev to create a shortcut that starts GameDev using a certain GDP file and the VBS file. Or you can manually write the command line yourself, like:

"C:\Program Files\GameDev\GDPlay.exe" "C:\Program Files\GameDev\Projects\MyGame.GDP" /p MyScript.VBS

Chapter III: Lode Runner Clone Script

The project "GoldYoink" is a Lode Runner clone designed with the intention of demonstrating some more advanced scripting tasks. It is available on the GameDev projects page at http://gamedev.sf.net/Projects.html.  In this chapter we will walk through the script implementation of many of the features in this project and describe what's being done and how the script accomplishes the task.  An HTML representation of the entire script is in the frame below.  The script can also be referred to as an independent document here. The content of this chapter will be grouped by task rather than by sequence in the script. All the pieces of script relavent to a task will be mentioned in association with that task (which may require jumping around in the script to see it all). This is presumed to be more helpful than going through the script sequentially and jumping around in describing what's going on. Also, please note that this section does not describe the entire functionality of the GoldYoink script. Rather it picks out some features in the script and uses pieces of the code to demonstrate how they are implemented with GameDev. Use these pieces as sample code and demonstraton of syntax, but don't expect to fully understand the whole script. For instance, I will not be documenting the enemies' search algorithm (at least not in this release) because it has more to do with basic programming and not specific GameDev functionality.

Dynamic Object Construction

Sometimes it is much easier to define or copy GameDev objects within code than to try to manually define such objects within the development environment.  This also allows you to change the rules more easily if you decide you don't want a particular set of objects to behave as they are throughout the game.  Constructing objects dynamically within script can use pretty much the same process that is used within the GameDev source code itself because most of the methods used to construct these objects are exposed to VBScript.  GoldYoink does a significant amount of dynamic object construction, which allows new maps to be added easily without having to re-define sprite templates and such on every map.  Futhermore, it will create sprite definitions based on tiles in the map instead of requiring the designer to go through the trouble of defining paths and sprite definitions and so forth.  You should be aware that dynamically constructed objects can also be saved as part of the project after they are created.  Dynamically creating an object makes it part of the project just as if it had been created in the IDE.  But such a task is better suited to a design-time script rather than a runtime script.  This chapter will not go into design-time scripts.

First, let's look at 520Sub Player_OnSpecialFunction(Func) (Line 520 of the script).  This function traps all events raised by special functions in the game.  This is actually where all initialization occurs.  Since initialization has to take place on each map, special function events are used to initialize maps instead of the one-time OnPlayInit event.  The function that transports the player from one map to the next raises an event and this code traps it and initializes the next map so it's ready to be played.  This is where all the dynamic construction occurs, putting the necessary objects in place on that map before it becomes active.

The first map (where the player simply runs down the ladder to get to the first level) may seem like just a fun little intro, but it actually allows the player to have a defined starting point that always exists.  That way we have some constant special function on the intro map that can be trapped as it tranports the player to the first playable map.  Without this, the first playable map would have to be manually initialized within the IDE or initialized specially within script, and there would be problems setting the player sprite for the game because sprites are generated at runtime. Notice the 3 lines of code that prepare for the initialization of Map1 when the player is coming from the Intro map:
527 Select Case left(ProjectObj.GamePlayer.rMap.Name,3)
528 Case "Int"
529 Set oNextMap = ProjectObj.Maps("Map1")


oNextMap is a local variable used to determine which map we need to initialize and where the player goes next.  The special functions that transport the player from map to map are actually defined to just "raise an event" and not to do the actual transportation.  The switching of the map is done within the script code because we have to ensure that the transportation occurs after the map is initialized, and special function events don't really fire until the special function has completed. The next few lines are for transporting the player from other maps to the following map based on the number in the map name. There's also a special case that allows the player to be transported from the last custom map to the final map of the game, which does not have a number because it must remain at the end of the sequence no matter how many maps there are.

On line 543 you can see that the map is actually initialized in a separate function.  The transportation of the player takes place afterwards.  The code that transports the player is similar to the code that implements a Switch Map function in the GameDev source code.  InitMap starts on line 368 of the script.  This is where all the dynamic creation takes place.

Creating Sprites

Custom Sprite Types

While the player sprite in GoldYoink is based off of several different standard sprite types, the enemy sprites are actually a type of their own. Each enemy is based on only one sprite template, and it doesn't switch from template to template like the player sprite. The enemy sprite is of a type that GameDev does not even define; it's totally defined in script. One of the lines of code that executes when handling the function that switches to a new map calls a function called "InitEnemies".  This call takes place on line 569, and the function is implemented starting on line 574.

The first thing this function does is locate the template on which enemies are based. You may recall that all templates were copied during InitMap so there will be an enemy template on the current map. Pointers to the template and the TileSet are cached.  Then the magic begins; a custom enemy sprite template is configured so enemy sprites can be created and associated with this template:

The StateType property determines what pre-defined type this sprite is. It is generally one of the values from the eStateType enumeration, like STATE_LEFT_RIGHT or STATE_36_DIRECTION.  But here we are making up a new type and so we assign some arbitrary value to this property just to make sure that GameDev's internal processing doesn't make any assumptions about what kind of sprite this is.  The custom sprite has 7 states, each described in the comment block.  What is gained by defining separate states rather than making a single state and managing the switching of frames and states in script?  Well, GameDev does do some work for us even on custom sprites.  It may not have a clue what the different states mean, but is still allows us to add animation frames to each state and advance to the next frame within the state according to the defined animation speed.

So next, we need to define the frames for each state.  First the frames are cleared out of each state, ensuring that we are starting from a blank slate (eliminate any frames from the template that may have been added at design time).  This is done with the ClearState method.  Then we specify for each state which tileset contains the graphics used for that state (each state can use its own tileset).  All of our states are based on graphics in the same tileset.  And finally we add the animation frames to each state by specifying which tile indexes represent animation frames in the various states.  AppendStateFrame's first parameter specifies which state we want to add a frame to, and the second parameter is the index of the frame within the state's tileset.  So state 0 (walking left state), as you can see, is represented by frames 22 and 23 from the tileset drawn in sequence (looping).

When the sprite has been fully defined, it is relatively easy to use it in script. Primarily, what you need to do is set the current state and velocity. For examples, look at certain lines of the ProcessEnemy subroutine that do this:

(There are many more examples in there too.) GameDev will handle all the simple movement, (moving the sprite based on its current velocity) and, sometimes, collision detecton and solidity checking for the sprite. Basically, it can handle the things that are defined in the template that don't care about the sprite's type/states. And since collisions only depend on the current position and current frame and size of the sprite, this can be handled by Gamedev. (Remember that many features are turned off, though, if you set your sprite controller to be "Simple/Scripted".) If you have defined the animations in each state, GameDev should also animate it for you based on the template's animation settings and the animation frames in the defined states.

Programmatic Map Switching

Special functions can be used to do many things, including switch from map to map. Sometimes, however, it's nicer to not have to create a special function on every map to accomplish a particular task, or to accomplish the task slightly differently than the special function implementation accomplishes it. In GoldYoink, rather than using the switch map function to jump from map to map, we implement the map switching in code because it needs to happen after the event has been triggered (normally a switch map function would switch to a new map and then execute the script code).

On lines 544 through 556 is the code that manually switches the current map to a new map. To manually implement special functions it is sometimes helpful to look at the GameDev code itself (that implements the special function), especially since it's written in Visual Basic, which is somewhat similar to VBScript. So lets compare the script code to the original Visual Basic code. The code that implements special functions in GameDev is in the source code file called Player.cls in a function called ActivateFunction. The switch map code is in this section (taken from GameDev version 1.3.2):

• PlayFunctionMedia simply plays the sound effect -- there is no sound effect for this so that has been left out of the script.
• Next we're storing a reference to this map in rOldMap because later we will need to access the map that was current in order to remove the special function from it if it was set to "remove after use". Of course in the script code we don't care about this either, so that also has been skipped.
• Then the reference to the display is set to nothing, indicating that this map is no longer using the display. Line 544 of the script reflects a similar statement.
• TmpCtl is only for GameDev use and ensures that the option is retained to disable player edits in the map editor after the map has switched. This is not needed in the script because the script is not using the IDE.
• The next line sets the map that the player is on (this is the primary map switch line right here) to the new map. In GameDev code, the name of the new map is retrieved from the special function's Value property. In script code, we use the map that was retrieved earlier in the code.
• The script code then does a little extra work to transfer the tile animation (gold sparkling) to the new map.
• The next operation seen in both GameDev and the script is setting the display for the map to the current display.
• LoadTiles then loads the graphics for the new map.
• LoadTileAnims initializes the tile animations.
• InitSprites initializes all the sprite instances.
• InitPlayerSprite initializes the player on the new map.
• GameDev code then searches for a specified player sprite if one was specified, but GoldYoink always uses the default player sprite on the map (defined in InitMap) so we don't need to copy that loop.
• GameDev does some additional steps to restore the PlayerEdits option, set the player to a custom position, fade background music, and switch the background color, none of which we care about.

Accessing Map Tiles

The tiles on each layer of the map are stored in objects that are implemented in BMDXCtls.dll (the graphics engine). It is possible to access and manipulate the tiles in these objects directly from script code. For complete documentation on the objects contained in BMDXCtls.dll, download the source code package for BMDXCtls from the SourceForge project site and refer to BMDXCtls.hlp. The object ob interest is the BMDXTileMap object. Referring to the Scripting Wizard, we can see that BMDXTileMap is used only one place in GameDev, and that is on the Data property of the Layer object. (For any property whose type begins with "IBMDX", refer to the BMDXCtls.hlp file for details.) That means that the data property of the Layer object returns an interface to a BMDXTileMap object and we can use the properties and methods of BMDXTileMap on that object. Take lines 570 and 571 for example:

Here we are accessing the layer data for the player's current layer. MapData (on line 570) accesses the MapData property of the BMDXTileMap object. Referring to BMDXCtls.hlp we can see that the MapData property returns the data for the entire BMDXTileMap object (which represents one layer in GameDev). What that line is doing is storing the state of the current level so if we need to restart the level, we can restore the map tiles to their initial state quickly and easily. Line 571 is setting the tile mapping for tile 45 to 0. That means every tile on the map whose tile index is 45 will be returned as tile 0 instead of 45. This is the same mechanism that is used for tile animation, but in this case it is used to hide the ladders that should only appear when the player is done with the level. Tile 45 is the tile that represents ladders that only appear at the end of the level (when the player has acquired all the gold).

One other, and possibly most important, property of the BMDXTileMap object is the TileValue property. This property is used to directly access or manipulate a single tile within a map. We can see that this was done during map initialization to convert player and enemy tiles into sprites and switch the tiles back to blank tiles. Lines 395 through 399 demonstrate this when they detect that a tile represents a player:

Ladders

Ladders are not built into GameDev, so if you want to design a game in which the player can climb ladders, you either have to cleverly design some sprite/map interactions or use script to switch the player to states where he or she can climb ladders as appropriate. GoldYoink, of course, opts for the scripting solution, but also makes use of some sprite templates and tile categories built into the project.

The first task is to detect when the player is touching a ladder. To do this, a tile category in the project called "Ladder" has been created.  To test if a particular tile is a ladder tile, the IsMember method of the TileGroup object is used.  A TileGroup is accessed by finding the named Category object in the project and then accessing the Group property.  A category is simply a thin wrapper around the group object that allows a name and tileset to be assigned to a group of tile indexes.  This group is used regularly to determine if the tile beneath any corner of the player sprite is a ladder.

Taking a look at the CheckHangAndLadder function on lines 295 through 309 we can see the code in use. Line 303 checks to see of the tile under the top-left, top-right, bottom-left or bottom-right corner of the player sprite corresponds to a ladder tile:

Variables nTLTile, nTRTile, nBLTile and nBRTile represent the tile indexes of the tiles beneath the four corners of the player sprite. They were set in the calling function, ProcessPlayerMovement. This is done to optimize performance so we don't have to read the map and do math every time we want to get these tile indexes. When one of these tiles is found to be a ladder, the special function is activated to switch the player sprite to a ladder climbing sprite.

Now let's follow this ladder climbing case from beginning to end because CheckHangAndLadder is only the lowest level of this feature, and only handles a specific frequently used test, not all cases where the player starts climbing a ladder. It starts when GameDev raises the Player_OnAfterMoveSprites event. This event is used to process the interaction with ladders because it is called for every frame and we want to check for ladders on every frame. In Player_OnAfterMoveSprites, the ProcessPlayerMovement function is called to handle all custom movement of the player (including ladders). ProcessPlayerMovement calculates the tile indexes beneath the 4 corners of the player sprite and stores them in the respective global variables on lines 182 through 191. It also sets some other tile indexes -- the tile that is beneath the center of the sprite goes into the nCTile variable and so forth. The ProcessPlayerMovement function later determines which state the player is in. Lets assume you've started in the walking state. The following condition will be selected as true:

Once it has determined that the player was walking, it determines if the player should switch to the climbing state. This should happen when the player's center is overlapping a ladder and when up is being pressed. This is done by checking the CtlActions property to see if up is being pressed and by checking if the nCTile index matches the index of a ladder tile:

The key action then is to activate the function to switch to the climbing "state" (or switch to a climbing state however you like). After this is done we remember the new player sprite's sprite (since it was recreated as part of the switch process) and center the player over the ladder by adjusting the X property:

Given that you have a function in the project to switch the player sprite into the climbing state, and have properly defined how a climbing sprite can move (none of that requires script) that is fundamentally all you need to do in order to properly switch to the climbing state at the appropriate time. So you can ignore the multitides of extra code for the time being. If you also want to be able to climb down ladders starting from a walking state, look into the block of code directly below it on lines 258 through 262 (nCBelow represents the tile index of the tile below the center of the player's feet).

Keep in mind that this script contains logic for a lot more than just climbing ladders. The script in the code being examined here has a lot of extra logic to account for overhead bars and specifically emulating Lode Runner ladders. As mentioned earlier, if you accept a certain set of simple rules, you can even implement ladder climbing without scripting at all. So remember that this script may be best as examples of syntax, and not necessarily as a whole drop-in code set.

Now that you have entered the climbing state, you will also want to be able to switch back to a non-climbing state when you get off the ladder. This case starts of with the ProcessPlayerMovement function realizing that the player sprite is already in the climbing state:

It then determines if any corner of the player is still touching a ladder tile. If not, we need to switch to a falling state (if no solid ground is below) or a walking state (if there is solid ground below). The script first calls CheckHangAndLadder because we want to switch directly to a hanging state (instead of a falling state) if there is a bar near the player's head. But for the simple case, presume that CheckHangAndLadder returned False indicating that no hanging bars or ladders will prevent the player from falling. The script selects the Fall or Walk function to switch the player into the falling or walking state respectively, as appropriate. Note that nBLBTile represents the tile index of the tile below the bottom left corner of the player sprite and nBRBTile represents the tile below the bottom right corner of the player sprite.

As you see, we again have to re-cache the reference to the player sprite (line 228) after switching sprites because it will have been re-created. The remaining section will re-center the player over the ladder when moving up or down the ladder (by adjusting the X position) and also prevent diagonal climbing.

That's a quick overview of some of the most important aspects of writing a script to help the player climb ladders. There is one more aspect worth noting. In GoldYoink, we want the player to be able to walk past ladders when coming from the side, but also have the ladder support the player when the player walks accross the top. This is handled in two ways in GoldYoink, but really, only one needs to be used. One way is to have a special tile at the top of every ladder which is defined as solid. In GoldYoink there is a tile representing the ladder coming up through a hole in the ground. This tile is defined as solid. Putting this tile at the top of every ladder will allow the player to walk accross those tops, but allow the rest of the ladder to be non-solid so the player can pass through is when in the walking state. This top tile would be defined as non-solid, of course, for the player's climbing state, allowing the player to climb through the top of the ladder. The script then needs to switch the player to a climbing state when it detects that the player is standing on this tile pressing down:

The other method is to have the script specially handle walking accross the tops of ladders. This accounts for some of the complexity you see in the script code. It also contributes to the need for two separate categories to separate solid tiles from "StopFall" tiles, which aren't solid, but will stop the player from falling. The player is forced to remain on top of the ladder when walking, even though GameDev is trying to make the player fall through the non-solid tile:

Conclusion

There is much room for expansion and improvement in this document, but I have only so much energy before I must move on to something else. Hopefully those of you out there who have been hungering for some help and documentation on GameDev's scripting support will find this useful. I'm open to adding new sections to this document to make it more helpful, and to extend it in the future where appropriate. So keep an eye open for updates to this documentation. The latest version should always be available at http://gamedev.sf.net/Help/Docutorial.html.