Sprite Import Tutorial

While a comprehensive tutorial for defining sprites is impractical due to the variety of sprites types and rules available, users should be aware of the import feature in SGDK2. In version 1 of the Scrolling Game Development Kit, some pre-defined sprite behaviors were hard-coded into the engine which made defining sprites easy, but severely limited the variety of sprites that could be created without scripting. In version 2, there is no hard-coded behavior for sprites in the engine, but users are free to import these behaviors from external sprite templates. A few are delivered with the initial installation, but more are also available from the SGDK2 project listing. There are a number of advantages to this method of defining sprites:

The set of sprite behaviors delivered with the engine does not define the entire set of sprite behaviors that can easily be created and added to your project.
Any user is free to design and distribute sophisticated sprite behaviors that any other user can use instead of only the author defining the built-in behaviors.
Customizing the existing sprite behaviors is much more practical.
Defining a completely new custom behavior is easier and will yield a sprite that looks and works just as well as any pre-defined sprite behavior.

So to clarify, there are two ways to add a sprite to your project. You can create one from scratch, manually defining the states and rules that define the sprite's appearance and behavior, or you can import and customize a sprite from a pre-existing template. This tutorial will explain the process of importing a sprite.

Add a Cannon to the Sample Project

One of the sprite templates delivered with the program is a cannon. The steps below explain how to import and use the cannon sprite.

Select the sample project from the File->New menu to get a functioning sample project to start with.
Select the "Sprite Definitions" folder in the project tree.
Select "Import From..." from the File menu or the context menu displayed by the right-mouse button.
Click the "..." button to browse for an SGDK2 file to import.
Locate the "Library" folder in the directory where SGDK2 is installed, and open the "Sprites" folder contained in there.
Select "Cannon.sgdk2" and click the Open button.
Click the Next button.
Confirm that both "Cannon" and "CannonBall" are checked and click Next.
If your project already has a sprite whose name conflicts with the imported sprite, or has graphic sheets or framesets that conflict with those for the imported sprite, you will be given the opportunity to rename these components at this phase of the import. This allows you to import the same sprite multiple times and customize each copy differently, for example. Since this tutorial is based on the sample project, you will not see any of these steps this time around.
Click Finish and notice that 2 sprite definitions and the associated graphic sheets and framesets were imported.
Expand the Maps folder, then Level 1, then Layers, then Main and select Editor.
Double-click Editor or select "Edit" from the context menu displayed by the right mouse button.
Switch to the Sprites tab.
Select "Add Sprites".
Select "<All>" from the dropdown list.
Select the sprite that looks like a cannon pointing upwards.
From the "CurrentState" property in the property grid below, select "DownRight".
For the "Solidity" property, select "Standard". Note: the AddSpriteHere rule used by the Cannon sprite assigns the same solidity to the created sprite as the sprite that caused the sprite to be created. So in order for the cannon balls to treat walls as solid, we must set the proper solidity on the cannon.
Select Snap to Tiles from the edit menu.
Move the mouse to tile 9,13 (see the status bar for tile position) and left click to add the cannon to the map.

Make the Cannon Fire

The cannon sprite has a Fire parameter which should be set to 1 in order to fire the cannon. It will automatically reset to 0 when firing is complete. Let's fire the cannon when the player sprite enters a rectangle near the front of the cannon.

Switch to the Plans tab.
Add a new plan and name it FireCannon.
Add two coordinates to the plan to define its rectangle from tile 10,14 to tile 15,19.
Select "Selected Plan Details" from the Edit menu.
Add a new rule named "Is player near cannon".
Select "If" as the rule type.
Select "IsSpriteWithin" as the rule function.
Select "m_ParentLayer.m_Player_1" for the sprite parameter, and "RelativePosition.CenterMiddle" for RelativePosition.
Add a new rule named "Fire cannon".
Select "=" as the rule function.
Specify 1 for the Value parameter.
Select <Select sprite parameter...> from the Output to dropdown list.
In the pop-up window, select Cannon 1 as the sprite, and Fire as the parameter.
Save the project and run it. Notice how the cannon fires when the player gets near. The cannon balls should stop when they hit the wall.

Note that because sprites rely on source code to operate, and some sprites may be rather sophisticated, it's possible that some sprites may be developed that require custom Source Code objects to also be imported in order to function (or even if a sprite has sound effects, for example, it may refer to Source Code objects). So in addition to importing the sprite definition, some sprites may require you to also import an associated Source Code object. Keep your eyes open on the first step of the import wizard to see if any mention of a Source Code object is made in the sprite's description. The source code object might be delivered in the same SGDK2 file, and could be imported by using the Import From command on the Source Code folder. Or it might be delivered as a separate file along with the sprite's SGDK2 file (which will make the need for the extra import obvious). In either case, the source code must be imported separately.

If you would like to deliver your own sprite definitions as importable objects, check out the "Export to template..." command in the Sprite Definition menu of the Sprite Definition editor. This command will not handle the exporting of custom code objects, but it will collect all of the other objects on which the sprite depends into a single SGDK2 file (graphic sheets, framesets) without including the extraneous source code that template files don't require. If you then want to include a custom source code object, you can open the file for editing in the IDE and add/import the custom source code object(s) manually.