GameDev Tutorial Step 9 - Adding Script Code

GameDev Tutorial - Creating a Simple Game

Step 9 - Adding Script Code

With all the features in GameDev, sometimes what you really want to do just isn't supported automatically in the set of basic functionality. Trying to predict everything that one might want to implement in a scrolling game, and trying to implement a system that supports these inherently would be far too big a task for this programmer. In hopes of remedying this problem to some extent, VBScript support is included in GameDev to open up all the internal workings of the game engine to custimized code. This won't solve everything, but does go a long way past GameDev's intrinsic functionality and interface.

This step of the tutorial will take you through a simple customization via script code. By no means is this a complete reference to scripting with GameDev or even a thorough representation of the scripting capability within GameDev. A complete scripting reference for VBScript can be found at http://msdn.microsoft.com/scripting/. Scripting runtime components can also be downloaded there, should you be lacking those. Of course that reference has no information about how scripting relates to GameDev. Also a GameDev-specific scripting reference is now available in the online help under GameDev Scripting Reference. It's not exactly complete documention, but at least includes quick coverage of everything exposed by GameDev, and some more scripting tutorial-type information. The object model exposed through COM is similar if not identical to that exposed to the scripting environment. The document should be handy for indicating what's avaialble to both. (Furthermore, since this is an open source project, you can see *exactly* how everything works if you're a savvy VB developer -- download the GameDev source available at http://gamedev.sf.net/.)

Anyway, getting back on track, thinking of something that would require script to implement in GameDev. Say you want to drop a "bomb" (or object of some sort) out the bottom of your ship whenever you press button number 2 (which is defined as the Space key by default). You may have noticed (in versions prior to 1.4) that there are 4 configurable buttons in the controller configuration dialog, but only 1 is supported intrinsically by GameDev (in the action parameters for a special function) -- again speaking only of versions prior to 1.4. Let's make button number 2 "drop" a new sprite out of the ship. With each new version of GameDev, this task grows less applicable to the current release, and with version 1.4 it can be done entirely without script, but work with me; I don't want to rewrite this step of the tutorial :).

The easiest way to do this with a minimum of scripting is to define a special function that creates the sprite near the ship and have the script activate this function when button 2 is pressed. But before this special function can exist, we need a graphic and a sprite. Use the tileset editor to create a tile that looks like the object you want to drop out of the ship. Then use the sprite/path editor to create a single-state sprite consisting of the one tile on "TutorialPath1" (the path selected will be irrelavent). The sprite should use "TutorialSolid" as the Solidity Definition and "Controlled by" should be set to "Inert". The movement speed should be all the way up, gravity slightly in the down direction and Inertia all the way up. Name the template "Bomb" and the sprite "Bomb1". Do not check the "Initial instance" checkbox.

Now go to the map editing dialog and select "TutorialMap". Go to the "Special Functions" tab and select the "Closed" function (we just need an unused function since it won't be activated by the player touching it). All action parameters should be blank. In the Effect, function should be "Create sprite". Select the Bomb1 sprite and check the box to set the start position (this is why the path for the sprite is irrelavent, we override the start position). Enter 0 for the X and 16 for the Y. Select "Relative to player". This causes the bomb sprite to start directly under the ship, 16 pixels below the top (halfway). Click Update and save all files in the project.

Now the function is done and we need to write script to activate it at the appropriate time. I've also added script to remove the bomb when it hits solid ground. The following code can be entered in any text editor and saved as "GameDev.vbs" in the GameDev directory:

Sub Player_OnControllerMove(OldActions, NewActions)
   If ((OldActions And eActionBits.ACTION_BUTTON2) = 0) And _
      ((NewActions And eActionBits.ACTION_BUTTON2) <> 0) Then
      ' Button 2 has just been pressed, activate the "Closed" function which we said creates the sprite
      ProjectObj.GamePlayer.ActivateFunction ProjectObj.Maps("TutorialMap").Specials("Closed")
   End If
End Sub

' After each time the sprites move, we want to check and see if the bomb(s)
' have hit anything solid, and remove those that have.
Sub Player_OnAfterMoveSprites()
   Dim I
   Dim Lyr, Spr, Def

   ' Get the one layer object
   Set Lyr = ProjectObj.Maps("TutorialMap").MapLayer("Main")

   I=0
   ' Cycle through each sprite (Don't use For because that doesn't work when bounds change)
   Do While I<Lyr.SpriteCount
      Set Spr = Lyr.Sprite(I)
      Set Def = Spr.rDef
      ' If the sprite is a bomb...
      If Def.Name = "Bomb1" Then
         ' Is the pixel below the bottom left corner or the bottom right corner solid?
         If Def.SolidTest(Spr.X,Spr.Y+32) Or Def.SolidTest(Spr.X+31, Spr.Y+32) Then
            ' The bomb hit bottom, remove it
            Lyr.RemoveSprite I
         Else
            ' Only increase the index when we haven't removed a sprite
            I=I+1
         End If
      Else
         I=I+1
      End If
   Loop
End Sub

' This links the OnControllerMove and OnAfterMoveSprites events to the code
' above based on the name "Player"
HostObj.SinkObjectEvents ProjectObj.GamePlayer, "Player"
' This says "We're done defining all the functions and linking objects
' so connect all the events now"
HostObj.ConnectEventsNow()

' This starts playing the game
ProjectObj.GamePlayer.Play 16

Now when you run "GameDev Tutorial.gdp /p" it will automatically run this script after loading the project Tutorial.gdp. When the script is complete GameDev exits. Notice that the last line of the script plays the game, so "GameDev Tutorial.gdp /p" will play the game, using the script, and then exit. GameDev looks for the filename "GameDev.vbs" by default, when no other script name is specified in the Player Settings dialog. One nice thing about not requiring the name of the VBS file is that, once GameDev has registered the GDP file type (which it does when you first run it -- if you said "no" and need a second chance at that, delete HKEY_CURRENT_USER\Software\VB and VBA Program Settings\GameDev from the registry) you can right-click on a GDP file and select "play" and it will automatically pick up GameDev.vbs in the GameDev.exe directory if it exists. If you would like to name the script something other than GameDev.vbs, you can execute this script with a game project using "GameDev Tutorial.gdp /p MyScript.vbs".

Note: As of GameDev version 1.2 you can simply use the Make Shortcut command to create a shortcut to play the project using a specified script file.

This concludes the GameDev tutorial.

Return to the main tutorial page.