Tile API Instructions

Hectate

  • *
  • Posts: 4643
Using the Tile API in Stencyl 3.x+
version 1.0

General Information
What is it?
The Tile API is an extension that permits users to access advanced functions to manipulate tiles in behaviors and events by using custom blocks.

How do you get it?
The extension is included in the Stencyl download, however it is disabled by default for new games. To enable it, load the your game in Stencyl, open the Settings menu, locate the Extensions tab, and click "Enable" on the Tile API extension. You will have to save, close, and re-open your game for the change to take effect. Once you have done so, the new blocks will appear in the Custom section of the block palette for you to use.


Additional Notes
Tile coordinates are measured in Rows and Columns. It is important to note that a Row coordinate is a measure of the tile's position on the Y axis, while Columns are measured on the X axis. Initially this may appear to be incorrect, but it is necessary to remember that "10 rows" means 10 tiles vertically (rows are stacked), but "10 columns" means 10 tiles horizontally.

Row and column coordinates start at 0 (zero), at the top-left corner of the scene, and increase in number going down (for rows) and to the right (for columns).

Tileset ID numbers can be found by looking at the bottom bar in the Tileset Editor. If a single tile is selected you will also see the Tile ID of the selected tile.

Layer ID numbers can be found in the Scene Designer's Layer box.

For performance reasons, layers are not able to contain tiles unless they did so at the time of compile (from the Scene Designer). Thus, attempting to place a new tile on a non-tile layer will fail.

Individual Block Information

Get (Column/Row) Coordinate Of (number) In Scene
Type: Number

This blocks produces the tilemap coordinate of a position in the scene. To get the coordinate in Rows, use a positive Y value. To get the coordinate in Columns, use a positive X value. Negative values are accepted, however they represent tile coordinates that are out-of-bounds of the scene (to the left of or above the top left corner of the scene).

Set Tile At Row: (number) Col: (number) LayerID: (number) Using TileID: (number) From TilesetID: (number)
Type: Action

This block creates a new tile in the scene at the designated coordinate and layer. The tile to be used is determined by the other two ID's given; the Tileset ID and Tile ID of the desired tile from that tileset. Note that placing a tile into the scene in this manner will create a new collision shape each time if the tile placed has a collision shape assigned to it. Significant numbers of these tiles can incur a performance penalty due to the many collision shapes

Tile Exists At Row: (number) Col: (number) LayerID: (number)
Type: Boolean (True/False)

This block indicates if there is a tile of any kind at the given coordinate and layer.

ID For Tile At Row: (number) Col: (number) LayerID: (number)
Type: Number

This block produces the Tile ID for a tile at the given coordinate and layer. If there is no tile at the position, this block returns the value -1 instead.

Tile Collision Shape Found At Row: (number) Col: (number) LayerID: (number)
Type: Boolean (True/False)

This block indicates if the tile at the given coordinate and layer has a collision shape or not. If a negative value (e.g. -1) is used for the Layer ID, it will check all tile layers automatically. Note that to do so, the block must loop through all tile layers in a scene to check; doing so could incur a performance penalty.

Collision ID For Tile At Row: (number) Col: (number) LayerID: (number)
Type: Number

This block provides the numeric value of the collision ID for a tile at the given coordinate and layer. If there is no collision shape found, it will return a value of -1 instead. This includes if there is no tile, or if a tile exists but lacks a collision shape.

ID For Tile's Tileset At Row: (number) Col: (number) LayerID: (number)
Type: Number

This block provides the numeric value of the Tileset ID of the tile at the given coordinate and layer. If there is no tile found, it will return a value of -1 instead.

Remove Tile At Row: (number) Col: (number) LayerID: (number)
Type: Action

This block will delete the tile at the given coordinate and layer. Note that deleting a tile will only remove it's collision shape from the scene if it was added through the Tile API. If the tile was placed in Scene Designer, the tile's visual image will be removed but the collision shape will remain behind (invisible unless Debug Drawing is enabled).

Example Usage
The following image demonstrates how these blocks might be combined to produce a behavior that places, or removes, a tile in the scene when the player clicks the mouse.


« Last Edit: March 02, 2014, 03:28:09 pm by Hectate »
:
:
Patience is a Virtue,
But Haste is my Life.
Proud member of the League of Idiotic Stencylers; doing things in Stencyl that probably shouldn't be done.

Hectate

  • *
  • Posts: 4643
[Reserved]

Note that two of the blocks were recently added to the Tile API by myself. If they are not yet present in your version of Stencyl, you should be able to find them in an upcoming update. Jon has to include the updated files in the download.
:
:
Patience is a Virtue,
But Haste is my Life.
Proud member of the League of Idiotic Stencylers; doing things in Stencyl that probably shouldn't be done.

UnrealCanine

  • Posts: 244
Is there a way to see if an actor exists at a certain tile?

Hectate

  • *
  • Posts: 4643
This extension does not do anything with actors.
:
:
Patience is a Virtue,
But Haste is my Life.
Proud member of the League of Idiotic Stencylers; doing things in Stencyl that probably shouldn't be done.

Jon

  • *
  • Posts: 17524
We should mention this pitfall related to the Tile API.
http://community.stencyl.com/index.php/topic,29360.0.html

Hectate

  • *
  • Posts: 4643
Yeah, I just saw that earlier and made a mental note to add that information. Will do.

Edit: Updated the OP and Stencylpedia.

« Last Edit: March 02, 2014, 03:33:45 pm by Hectate »
:
:
Patience is a Virtue,
But Haste is my Life.
Proud member of the League of Idiotic Stencylers; doing things in Stencyl that probably shouldn't be done.

Cheesington

  • Posts: 1
Everywhere I've looked all the pages says that Tile API comes with Stencyl 3, and all you need to do is activate it. But I don't, the only extension I have is Resources Monitor, and I need Tile API to make a chase-able flying saucer in my game. I JUST CAN'T FIND IT ANYWHERE!  :'(

Hectate

  • *
  • Posts: 4643
I think it's enabled by default now. Look for these blocks in the palette.
:
:
Patience is a Virtue,
But Haste is my Life.
Proud member of the League of Idiotic Stencylers; doing things in Stencyl that probably shouldn't be done.

ETHproductions

  • *
  • Posts: 430
Very nice guide to the API! This extension is tricky to get the hang of, but once I did, I was able to do everything I had wanted to.

I've attached an updated version of the extension, both so that people who don't have it can download it, and so that people who do have it can get a more user-friendly version. Each block has its own roll-over help text, and the View Help option is linked to this page.
Fontstruct - Stencyl - Website (in progress)

Proud Member of the League of Idiotic Stencylers; doing things in Stencyl that probably shouldn't be done.

Jon

  • *
  • Posts: 17524
Hey Hectate - I've ported over the article to Github as part of the ongoing Stencylpedia overhaul. If you'd like to update it, that's the place to do it from now on.

https://github.com/Stencyl/stencylpedia/blob/master/chapter-6/tile-api.md

One addition that would be nice is to provide a Stencyl project for the example at the bottom, so users can play with it.

Hectate

  • *
  • Posts: 4643
I might be free this weekend to look into this.
:
:
Patience is a Virtue,
But Haste is my Life.
Proud member of the League of Idiotic Stencylers; doing things in Stencyl that probably shouldn't be done.