Special Functions

This is part of a series of pages describing the Edit Maps Dialog. This page describes the Special Functions tab.

In order to edit special functions you must have a map selected and the player sprite must have been specified. This is required because some aspects of a special function require the layer in which the player sprite resides.

Along the left side of this tab are listed the special functions defined on the selected map. This is the top level of navigation within this tab. Selecting one of these special functions loads the information for the function into the sub-tabs at the right.

Note: In version 1.1 and earlier, only functions on the player sprite's layer were listed here because the only way to activate a function was for the player (on the same layer) to touch it. The problem with this is that there was no way to edit or delete functions that may have accidentally been added to other layers. Furthermore, there is now the ability to activate any special function(s) when the game begins. So for multiple reasons, all special functions on the selected map are now listed. Functions that reside on a layer other than the player's layer are discernible by the fact that the "Action Parameters" tab hides the controls relavent to the player when such a function is selected.

Action Parameters

The first sub-tab restricts when the special function will take effect and whether it can be activated again. The following options exist on this tab.

• Remove after use: This permanently removes the special function from the map after it has been activated. (Careful with this one in the editor. If you allow the player to activate this kind of function, you may have to re-add it before saving your project. See GameDev Options for details.)
• Initial touch only: Activate this function only when the player first touches it instead of repeatedly activating it as long as the player is touching the function.
• Uses inventory item: Check this to specify that the player must possess one or more of a particular item in order to activate the function. When checked you can select which item is required and how many. There is also the option of removing this many items from the inventory if the function is activated, or allowing the player to keep it/them. This option only affects how the player sprite can activate the function. If you want to alter the players inventory when the function is activated by some other method (for instance a sprite collision) see below in the Alter Inventory function.
• Activate once before gameplay begins: This is useful for things like displaying a title screen or instructions when the game starts up in play mode.
• Raise an event when this function is activated: As of version 1.3 you can raise an event for any special function. The function does not have to be dedicated purely to raising an event by selecting the "Raise an Event" function type. Selecting "Raise an Event" in the Effect tab is now reserved for functions that only raise an event. This will automatically set the bit for "Raise an event" (re-load after selecting that function type and you'll see the box is checked).
• Global: As of version 1.4 there is a new global checkbox to allow functions that can be activated purely based on the state of the input device, no matter where the player is on the map. Of course this can be accomplished by creating a special function that covers the entire layer, but the Global option is nicer in two ways:
  • Global functions are not drawn in the map editor so they don't block your view of other special functions.
  • Global functions are optimized to know that they don't have to check the position of the player first; just assume that they can be activated purely based on the state of the input device.

• All at once: If this is checked, that means all the buttons in this list that are checked must be pressed at one time for the function to be activated. For instance, checking "All at once", "Pressing right" and "Pressing button 1" will require that all those buttons are being pressed in order for the function ot activate. As long as these buttons are being pressed, the function will continue to activate (unless "Initial touch only", "Remove after use", or "Initial press only" is also checked). This is handy for something like shooting or throwing something. Pressing right and button 1 at once could cause a sprite to be created that follows a path leading to the right. If "All at once" is not checked, then pressing and one of the checked buttons can cause the function to trigger. Note: keyboards do not generally allow any number of arbitrary keys to be pressed at once. For example, if you press and hold the left arrow and up arrow keys and then attempt to press the right arrow, the system will probably not properly detect the right arrow, and may beep at you indicating that an un-readable key combination is being pressed. Keep this in mind when defining which keys map to what buttons in the Controller configuration dialog, and when determining which buttons trigger functions. The Control and Shift keys are generally pretty good with any other combination, so use these when possible, if you need an "All at once" combination. The joystick on the other hand should allow all the buttons at once without a problem, but of course you won't be able to press up and down at the same time, nor left and right.
• Pressing Up: Requires that the player be pressing up on the input device to activate this function when touching it.
• Pressing down: Requires that the player be pressing down on the input device to activate this function when touching it.
• Pressing left: Requires that the player be pressing left on the input device to activate this function when touching it.
• Pressing right: Requires that the player be pressing right on the input device to activate this function when touching it.
• Pressing button 1: Requires that the player be pressing button 1 on the input device to activate this function when touching it. (see Controller configuration for information on configuring this button.)
• Pressing button 2-4: These are very similar to button 1, and correspond to the other configured buttons.
• And nothing else: If you want to be strict about what buttons are being pressed to activate a function, you can prevent extra buttons from allowing the function to trigger. For instance, if you want to allow the Q key (as button 2) to shoot to the left and the W key (as button 3) to shoot to the right, but you don't want to allow the player to be shooting in both directions at once by holding both keys, you can check this box so that Q (button 2) will only shoot to the left when no other buttons are being pressed. However, this also means that the function will not be activated even when pressing Q and the left arrow. Attempting to support this kind of rule in a general sense is outside the scope of version 1.4. So you may have to use script or multiple functions if you want to still allow Q and left arrow to trigger the function. Checking this box simply confirms that no extra buttons are being pressed before allowing the function to trigger.
• Initial press only: Similar to "Initial touch only" this will ensure that the function only activates once when the specified button or button combination is pressed. If this is not checked, the function will constantly re-activate for every frame that the the activation parameters continue to apply.

Notice that if the the "All at once" box is not checked, any one of the checked buttons can be pressed to activate the function.

Effect

This tab has a lot of content to support the various types of special functions that are defined in GameDev. The "Function" field at the top of this tab determines what the selected special function should do when it is activated. The information presented below the function field is specific to the selected function.

Display a Message

This type of function pops up a box that displays a message or image and waits for the player to press a button. The game freezes until the message is acknowledged. To display an image enter "#PIC" as the first 4 characters of the message and then enter the path and filename of a bitmap to display. A space following "#PIC" is optional, however there must be no spaces before or inside the text "#PIC" itself. The path should be relative to the path of the GDP file for the project. The image will display centered on the screen and act just like a message until the player presses a button.

This function has been greatly enhanced in version 1.3 and you can now set the font name, size, color and style using #FNA, #FSZ, #FCL and #FFL respectively. Each code must go on a line of its own like the #PIC code. Furthermore you can now display text on top of the picture by adding text starting on the line after the codes. The picture size will be used to determine the size of the rectangle in which the text is printed. I recommend you use the new Message Wizard button to compose your messages now instead of typing these codes in, to make this process easy.

This dialog is displayed when you click the "..." button next to the text box for the message. Here you can separately enter all your parameters for the message and the proper code will be entered for you in the message box for the function. Note that you can leave the text box blank in order to simply display a picture, or leave the image field empty if you don't want a background image for your message. In case you should need to know, the codes are formatted like this (each code goes on a line by itself followed by it's parameter. A space is optional):

• #FNA: Specify the font name. Example: #FNA Arial
• #FSZ: Specify the font size in points. Example: #FSZ 11
• #FCL: Specify the font color as a number. Red is in the low 8 bits of this number, green in the next highest 8 bits, and blue in the next highest 8 bits. Example for Yellow: #FCL 65535
  (This is the main reason I recommend using the message wizard.)
• #FFL: Up to 4 characters representing flags for certain styles
  • Bold: B
  • Italic: I
  • Underline: U
  • Strikethrough: S
  Example: #FFL BI

Switch to a New Sprite

This changes the player sprite to a new sprite. This could come in handy for changing the appearance or functionality of the player, or switching it to an automatically controlled sprite for a period of time while it travels from one point to another. The new sprite will continue to interact with the map as the player sprite always does. There are a few options associated with this function:

• Swap "Controlled by": Normally the player sprite is the only sprite controlled by the input device. If the sprite you are switching to is controlled by something else, you may want to check this option so that the new sprite will be controlled by the keyboard and the previous sprite (if it continues to exist) is controlled by whatever the new sprite was previously controlled by. This should give the effect that the player just took over control of another sprite. Be careful with this option because it changes the sprite template (since that's where the "Controlled by" attribute is determined). All sprites based on the same template as the two sprites will be affected similarly (and possibly permanently; see GameDev Options for details. This action is not one of the features disabled by the "disable player edits" option.)
• New Instance: If this is not checked, GameDev will attempt to locate an existing instance of the indicated sprite definition and switch the player to that sprite. If this is checked, or if no instance exists, the player will transfer to a new instance of the specified sprite definition.
• Same location as old: If this is checked, the new sprite (whether an existing instance or a new instance) will be transported to the location of the player sprite instead of starting in its own current or default locaton. This should have the effect of making it look like the player just changed/upgraded into something else (without moving).
• Delete old sprite: If this is checked, the current player sprite will be deleted as player control is transferred to the new sprite.
• Retain old state: This option (new as of 1.3) will try to retain as much about the state of the old player sprite as possible:
  • Same velocity is retained.
  • State & Frame - If the old player sprite and the new player sprite have the same number of states (left, right, left accelerating, right accelerating for instance) and the current states have the same number of frames, then the state will be copied and the sprite will remain in the same state, and the current frame will also be retained.
  • If the old sprite and new sprite follow the same path, the new sprite will pick up where the old sprite left off on following that path.
  This option is handy if you want to give a sprite new powers (like the ability to walk over new terrains or jump higher) but don't need to change the appearance of the sprite, and want the sprite switch to happen as seamlessly as possible.

Switch to a New Map

There would be little point in having multiple maps within a project if the player were not able to jump between them. This function will transport the player to another map. Usually, the current map is unloaded and the new map is initialized (default instances of sprites are created where appropriate). Then you have the option of starting the player in the default location for this map or overriding the player start position and/or sprite with one of your own choosing. Selecting "(default)" from the "As this sprite" box uses the sprite specified as the Player sprite for the map. The definition you select must be a sprite that has "Initial Instance" checked and would be automatically created when the map is initialized. If you want to override the starting position instead of using the default position for the sprite, you may check the "Set start position" box and specify an X and Y coordinate in pixels. This coordinate is given as an offset from the top left corner of the layer in which the sprite resides.

There are two new features here as of version 1.4. First, notice the "Remember Old Map" checkbox. This will store the location that the player was at before switcing to the new map so you can return to it later. Up to 5 locations can be remembered at a time. When returning to an old location, the last one stored is always used. This is ideal for switching to a menu screen or some other globally accessible location because it's easy then to switch back to the remembered location no matter what map the player was on when they switched to the new map. Next notice the "<Return to old map>" selection in the map list. This is the counterpart which implements the other half of this feature. After storing a location, you return to it by having another function that switches back to the old map. The other feature is the ability to switch to a map without restarting the sprites. The "Restart Sprites" checkbox is checked by default, but if you un-check this box, then whenever you return to this map, it will remember what sprites were there when the player last left that map. If an existing player sprite cannot be found on the map, the sprites will be re-initialized regardless of the state of this option (for instance, if this is the player's first visit to the map).

When the player switches to a new map, the inventory is retained. There may be different interactions defined on the map, but all maps are defined in terms of the same inventory. This is the reason for separating the inventory's interaction with the map (on the Player Interaction tab) from the inventory definition itself (on the Player Settings dialog).

Teleport to a Location

The player can be teleported either to an absolute position or to a position offset from the player's current position or from the trigger point. Coordinates are given in pixels. For an absolute teleport (if the "Offset" boxes are left unchecked) coordinates are given in pixels from the top left corner of the layer in which the player resides, and a preview of the destination location is displayed at the right. The coordinates specify where the top left corner of the sprite should end up. If the "Offset from current" option is checked, the teleport will be an offset from the player's current position. If "Offset from trigger" is checked, the teleport will be relative to the trigger point. The trigger point is set to the location of the last sprite collision, sprite path ending, tile interaction or function activation by the player itself. ("sprite path ending" refers to a sprite that triggers a special function when it reaches the end of its path.)

Alter Map

This is a particularly useful function for changing a piece of the map. It copies the tiles from under another special function and puts them wherever you want. Everything must occur on the same layer as the player. It's not possible to copy tiles accross layers, or to copy areas of tiles from one place to another on a layer other than the layer where the special function was triggered. All the tiles will be copied from under the specified special function to the location specified. The location specified indicates the top left corner of where the tiles are output.

As of version 1.4, the new option "Relative to tile behind trigger point" is avilable. The trigger point is set in pixels, but this function can find the tile that contains the trigger point coordinate and use that as a tile location to set the target location of the copy. This allows, for instance, an easy way to turn a sprite into a tile when it reaches the end of its path and triggers this kind of function.

The "Pick cordinates" box is not part of the special function, but rather a tool you can use to calculate coordinates. If the function being defined happens to contain the destination rectangle (aligned to one corner) you can use the Pick coordinates box to enter the coordinates necessary to copy the rectangle to the appropriate corner. For instance you may have an "UnBlockPassage" function defined at 24,20 to 26,23 and you have an "OpenedPassage" function defined at 100,50 to 101,53 (notice the open passage is one tile narrower horizontally). "UnBlockPassage" represents the area the player can touch to activate a function that copies an image of an opened passageway into the tiles at 25,20 to 26,23. "OpenedPassage" represents this image being copied. Since 26,23 (the bottom right corner) happens to be the same for "UnBlockPassage" and for the rectangle you want to affect, you can select "Match bottom-rights" from the "Pick coordinates list" and it will enter the coordinates "25,20" for you (the top left corner of where the copy must begin to make the bottom right corners match). This tool is convenient if you don't know the coordinates of the destinaton, but you know the destination matches a corner of the function you're currently defining.

Create Sprite

Use this function to create a new instance of a sprite based on the specified sprite definition. You can override the default start position for the sprite if you like by checking the "Set start position" box and entering a pixel coordinate. If the "Absolute" option is selected, the coordinate will be interpreted as pixels relative to the top left corner of the layer. If "Relative to player" is selected, the coordinate will be added to the position of the player. The top left corner of the new sprite will start at the specified offset from the top left corner of the player sprite. If "Relative to trigger" is selected, the sprite will start at the specified offset from the trigger point (new as of version 1.4). The trigger offset feature is good for things like creating explosion effects at the location of a collision between two non-player sprites. The "Maximum count" parameter sets a maximum on how many of the sprite the function should allow. The function will not create another instance of the sprite if the maximum number already exist. (The last parameter is new with version 1.2.)

Raise an Event

This function does not require any parameters. Instead all the work in this case is handled in script. This is a particularly useful option as it allows you to do anything you want if the other function types do not cover the effect you want the special function to have. The Player object's "OnSpecialFunction" event is raised when the function is triggered, and the "SpecialFunction" object that was triggered is passed to the script code as a parameter.

As of version 1.3, any function can raise an event by checking the appropriate box in the "Action Parameters" tab. The purpose of this function type, then, is when there's nothing else you want to do besides raise an event.

Delete Sprites

To prevent the map from becoming over-populated with sprites you may want to make frequent use of this function. It allows you to delete one or all instances of sprites based on the specified sprite definition. Specifying a minimum will prevent all sprites from being deleted by the function; the function will only delete sprites if the minimum number will still exist. Specifying a minumum and checking the "Delete all above min." box will delete sprites until the specified number of sprites exist for that type of sprite. If the minimum is set to zero and the box is checked, all sprites of the specified type will be deleted at once.

Alter Inventory

The Action Parameters tab allows some simplistic manipulating of the inventory, but this only allows subtracting from the inventory and only takes effect when the function is activated by the player touching it. This Alter Inventory function allows you to do more. You may specify any item in the Item name field. You can also enter positive or negative values in the "Change by" field. Positive values will add the specified item to the inventory while negative values will subtract. You can also specify what happens if the inventory item reaches its max (if adding) or 0 (if subtracting) by choosing another function from the "If limit is hit, activate" field. This allows you to activate a special function if the player reaches an upper or lower limit on a particular item. You can also choose to automatically reset the count to the opposite limit when this occurs. One example of using these would be health and life count. A special function can be used to reduce health. When health reaches 0 you can automatically activate another function that reduces life count by 1 and check the box to have the health reset to full. The function that decreases life count could in turn activate another function to teleport you to an end game map if the life count reaches 0. This kind of function would probably be activated often from sprite collision definitions.

Activate Series of Special Functions

OK, so you don't want to write script. Besides, it's cool to show how much GameDev can do without resorting to script. So here's the answer. This may become the most powerful special function yet. It allows you to combine a number of other special functions into one so you can activate them all at once in any order any number of times. Simply select the function or functions that you want to execute in the lefthand list and click the ">" button. These functions will then be added to the list for this function. You can sequence the list however you like by selecting functions in the righthand list and clicking the up and down arrow buttons. The same function can be executed multiple times too, if necessary. And so long as you don't end up with any circular references, you can even have one series call another series. If you need to remove anything from the righthand list, click the "<" button.

Save / Load Game

This function (new as of version 1.4) performs a few different operations with save game files. Saves are represented in GameDev with a slot concept. The names and quantity of the "slots" are determined by the "Game name" values specified for save game functions by the game designer. The specific function is selected by picking one of the options on the left:

• Save game: This will save the current runtime state of the game. A precise copy of the game is saved so it can be loaded precisely to the same state at a later point. Effectively, it is a copy of all the map files in the maps' current states, plus a .SAV file, which is similar to a GDP file, but has a somewhat different set of information specific to the runtime state of the game, like all the sprite instances that are currently active. The map files go in a subdirectory whose name is indicated by the "Game name" field. The .SAV file goes in the same directory as the GDP file (ony directory up from the map files). It contains plain text data just like the GDP file, and is named accordng to the "Game name" field. Be careful when activating this function to make sure it only activates once instead of continuously. The game could go quite slow if it is repeatedly saving the whole game after ever frame.
• Load game: This option can be used to load a game that has been saved into the "slot" specified by the game name. Basically, if you have triggered the save function to save a game into "Save2", then you will also want a function somewhere to be able to load this same game at runtime. The exact state of the game will be loaded, which means you might have to be careful about how the game is saved; the player sprite may find itself on the save function after loading because this is where it was when the game was saved.
• Delete game: If you want your game to kind of support file maintenance operations with respect to saved games, you can use this function to remove old saves. The save game in the specified slot will be deleted (the SAV file and the subdirectory by that name will be deleted) when a function is activated with this option set.
• If save exists...: To help support file maintenance operations, you can use this option to activate another function only if the specified save slot has a game saved in it. For instance, if the "Save2" slot has a saved game, you may want to activate another function that creates a sprite. The sprite could represent the game stored in that slot so the player knows he/she can load the "Save2" game when looking at some saved game listing screen.
• If save does not exist...: Similar to the above option, but is used in the opposite case. For instance, you might want to alter the map if a particular save does not exist in order to block off a particular save slot from being loaded.

Buttons at the Bottom

There are 5 buttons along the bottom of the Special Functions dialog:

• Delete: Deletes the currently selected special function.
• Rename: Renames the currently selected special function (new with version 1.3). This will prompt you for the new name when clicked. It will properly modify references to the function from other functions such as Alter Map, Alter Inventory, and Function Series, as well as modifying references from sprite collision definitions.
• Add: If you want to quickly add a special function that doesn't get activated by contact from the player sprite, you can do it quickly and easily by pressing this Add button (new with version 1.3). The position of the right side of the function ends up in column -1 of the layer, which prevents it from being processed when testing is done to see if the player is touching a function. So it's best to use this method when adding functions that will never be touched.
• The button to the left of the Update button is a calculator button that will run Windows calculator. You might need this in converting between tile coordinates and pixel coordinates (by multiplying the tile coordinate by tile size or dividing pixel coordinate by tile size).
• Update: When the parameters for a special function are complete, you must press the Update button to save them to the currently selected special function.