This is a compilation of questions from the main Dusk forum post and elsewhere, as well as other helpful questions to help you use Dusk.

How do I add physics to tiles or objects?

You can add physics to tiles or objects in one of two ways.

Through tile or object properties. To do this, edit the properties of a tile in a tileset or an object in a layer, and add the property physics:enabled as true. Then, you can add other physics options by prefixing them with physics:. Everything prefixed with physics: is automatically added to the physics table when an object or tile is created. For example, to add the bounce or friction properties, use physics:bounce and physics:friction.

Through layer properties. If you set up physics through layer properties (viz. add a physics:enabled property and options to the layer instead of to the layer's children), physics will be passed to the layer's children automatically, because layers aren't physics-enabled. Thus, any physics options you add to a layer will be added to the layer's children instead. Everything detailed in the paragraph above applies here.

An important thing to note is that two physics properties behave differently. The isSensor property can be added to the physics table (that is, physics:isSensor), but it can also be added directly to the object as a property. The bodyType property can only be added to the object as a property, and does not go inside the physics table. If you specify physics:bodyType in your options, nothing will appear to happen. You will have to set it as a simple property, without the physics: prefix. You can make the property apply to all children of a layer by prefixing the option with tiles: or objects: for tile layers and object layers, respectively.

My map loads one rectangle of tiles and won't load any more. What's happening?

One of the things that makes Dusk a good engine is its tile culling capabilities. Tile culling is the removal and addition of tiles as needed as the map moves around the screen. By using tile culling, tile engines like Dusk are able to load maps of a far bigger size (25,000,000 - twenty-five million - is the most I've ever tried), because the only tiles that really exist are the ones currently visible in the screen.

Your problem is likely that you're forgetting to call map.updateView() as you move your map around. Simply place this function call in an enterFrame listener in your code, and add a call to it when you move the map, and this problem will be solved.

I'm trying to use the camera system, but when I focus it on an object, the map moves, but the focus object continues to move outside the screen. How do I fix this?

This is a simple fix. Make sure everything you want to move with the camera is inserted into one of the map's layers.

How do I add a bodyType to my physics objects? physics:bodyType doesn't work!

As detailed in How do I add physics to tiles or objects?, the bodyType property is different in Corona from the rest of the physics properties. It requires that you add it as a plain property instead of in the physics table. Thus, for an object or tile, bodyType will work; for a layer's children, objects:bodyType or tiles:bodyType will work.

How can I erase or draw a tile permanently?

Use the layer.lockTileErased(x, y) or layer.lockTileDrawn(x, y) function. These two functions basically turn off culling for a single tile. You can then unlock the tile with layer.unlockTile(x, y).

How do I get rid of the flickering lines between tiles?

First, add the following two lines to the top of your main.lua:

display.setDefault("minTextureFilter", "nearest")
display.setDefault("magTextureFilter", "nearest")

Then, make sure your tileset has a spacing of at least 1 pixel. Spacing is the distance between tiles in a tileset. Dusk ought to fix everything else automatically.

For a slightly more effective approach to getting rid of this, you can extrude your tilesets by 1 or 2 pixels.

Why do there seem to be two copies of each layer/object when I iterate through the map.layer/layer.object table?

Dusk stores each layer two times: once under map.layer[index] and once under map.layer[name]. This is so that you can access each layer either through the layer's index or the layer's name. For iterating through each layer, you should use one of the designated layer iterators.

The same thing applies to layer.object. Each object gets two references as well.

How do I remove a map? When I use map:removeSelf(), all sorts of nasty errors appear.

The correct way to remove a map is via the map.destroy() function.

How do I make the camera follow my game's main character?

Use the map.setCameraFocus(player) function. It will tell Dusk to stay focused on an object. Don't forget to call map.updateView() every frame, or the camera will appear to do nothing.

How do I make the camera less "rigid"?

Use the map.setTrackingLevel(t) function. It takes a number from 0 to 1, and makes the camera more or less "fluid" and slow to track. Numbers approaching 0 are more fluid. A tracking value of 0.3 or 0.4 is usually good for most games.

Alternatively, you can use the map.setDamping(d) function; it takes any number over zero and sets the tracking level inversely. For this, higher numbers make the camera slower, which can be more natural-feeling to some people.

My physics objects are "catching" at the boundaries between physical tiles. How do I fix this?

This is a common drawback of using a real physics engine for a tile-based game. There are several ways to get around this:

  • Make your object physics body a shape with clipped off corners at the bottom
  • Make your object physics body circular
  • Make your object a multi-element physics body with a circle at the bottom
  • Give your object a tiny bit of bounce
  • Give tiles a clipped-off-corner shape and your object a normal rectangular one with a tiny bit of bounce