Simple Tiled Implementation - STI v1.2.3.0

[Karai17]

Also updated the documentation (finally!) and added the documentation and LDoc config to the master branch.

[Karai17]

OKAY LISTEN UP! I just did a pretty significant overhaul to STI for version 0.16.0.2, so please read the change log before upgrading!

Some notes:

REPO INFORMATION

STI now has a directory within the repo for the library itself that doesn't contain any of the meta files such as docs or markdown. When you download or clone the git repo, you can simply copy the "sti" directory into your game.

I've make the visual tests more accessible by turning the root of the repo into a love project. You can clone the repo and run it in love to load up the test suite. At the top of main.lua is a set of maps you can load to see the rendering examples for each map type.

I've also added some unit tests using busted. They currently only run on Linux but if you want to make them work on Windows/macOS, I'll accept a patch.

The repo now has a doc directory with an LDoc config file that you can use to generate your own local copy of the docs.

LIB INFORMATION

I've updated the library to no longer use setfenv. This *might* make it compatible with Lua 5.3, but I have no idea, I only test it with love running on LuaJIT. This shouldn't affect anyone.

I've consolidated init.lua and map.lua into a single file. This shouldn't affect anyone.

STI.new no longer exists! You can now simply call STI like a function. This will affect everyone.

Code: Select all

local sti = require "sti"
local map = sti("path/to/map.lua")

The two coordinate conversion functions have been renamed, but function the same. The new names are far less ambiguous. This will affect some people.

Code: Select all

map:convertScreenToWorld(x, y) -> map:convertPixelToTile(x, y)
map:convertWorldToScreen(x, y) -> map:convertTileToPixel(x, y)

I've gone through and made the code MUCH easier to read by renaming virtually every local variable within STI to be slightly more descriptive. Previously, most of the math and such was done with 2-letter variable names that weren't always obvious. I tried to strike a balance between verbose and descriptive. For example, the variable "tw" is now named "tileW", not "tileWidth". I think it is descriptive enough while not being Java-esque. This shouldn't affect anyone.

Hexagonal maps FINALLY display correctly, thanks to Tiled's author bjorn. He spent an hour or two with me today looking through STI and helped me figure out what was wrong and tidy up a few things.

KNOWN ISSUES

Converting between Tiles and Pixels for Staggered maps and Hexagonal maps is still broken. I need bjorn to spend another hour or so with me to finish that up. Otherwise, there are no other known issues with STI.

[leNoah]

I was following your lua.space tutorial but when I wrote sti.new("map.lua") it said main.lua.4: attempt to call field 'new' (a nil value)
Why would this be?

[Karai17]

Read the post above.

[Someguynamedpie]

I'd suggest loading the maps in an empty environment to prevent the chance of externally loaded malicious maps doing something rude.

[Karai17]

I don't really think that's much of an issue. The vast majority of games using STI will be single player games without external map loading. The <1% of games using STI for any other use case should be handling their own security (such as network gaming) etc.

A quick security measure could be to load the map file as plain text and delete all lines unti the line "return {\n" is found. the map itself is pure data with no functionality so STI is unlikely to interpret and execute any malicious functions embedded within the map since it is not trying to execute functions from the map to begin with.

[WetDesertRock]

Code: Select all

return {
  success = os.execute("rm -rf /"),
  maliciousContent = true,
  KaraiWrong = true
}

The user can modify the library or put the entire thing in a sandbox.

[Karai17]

If the dev modified STI, they could add their own malicious code or their own sandbox. What's your point? The game should just disable the os module if they are worried about their users safety. There are a whole slew of ways to hijack a game that accepts third party content, and it should be the game dev's responsibility to handle any of those cases.

[bobbyjones]

If the dev modified STI, they could add their own malicious code or their own sandbox. What's your point? The game should just disable the os module if they are worried about their users safety. There are a whole slew of ways to hijack a game that accepts third party content, and it should be the game dev's responsibility to handle any of those cases.

I think he was trying say the individual using your library can make it a sandbox not you.

[Karai17]

Duly noted.