commented some stuff

actor.lua

@@ -7,35 +7,40 @@ Actor = inherits(AnimatedSprite, {
 
 local actor_mt = class(Actor)
 
-function Actor:new(x, y, skins, args)
-    args = args or {}
+function Actor:new(x, y, skins, opts)
+    opts = opts or {}
 
     local o = AnimatedSprite:init(x, y, skins)
-    o.type = args.type or "static"
+    o.type = opts.type or "static"
 
     local s = setmetatable(o, actor_mt)
 
-    if args.default then
+    if opts.default then
         s:adddefaultbox()
     end
 
     return s
 end
 
-function Actor:add(x, y, skins, args)
-    table.insert(p, Actor:new(x, y, skins, args))
+function Actor:add(x, y, skins, opts)
+    table.insert(p, Actor:new(x, y, skins, opts))
 end
 
+--add a collision box to the actor with a specified width or height
+--xoff/yoff define the box's position relative to the actor
 function Actor:addbox(width, height, xoff, yoff)
     xoff = xoff or 0
     yoff = yoff or 0
     table.insert(self.body, Rectangle:new(self.x + xoff, self.y + yoff, width, height, xoff, yoff))
 end
 
+--add a collision box that is the size of the sprite
 function Actor:adddefaultbox()
     self:addbox(self.width, self.height)
 end
 
+--check if this actor collides with another actor
+--offset applies to the position of this actor
 function Actor:collides(offset)
     offset = offset or { x = 0, y = 0 }
     for _, box in pairs(self.body) do
@@ -52,6 +57,8 @@ function Actor:collides(offset)
     return false
 end
 
+--check if this actor collides with the defined rectangle
+--offset applies to the position of this actor
 function Actor:collideswithrect(rect, offset)
     offset = offset or { x = 0, y = 0 }
     for _, box in pairs(self.body) do
@@ -62,46 +69,61 @@ function Actor:collideswithrect(rect, offset)
     return false
 end
 
+--update the position of this actor horizontally, checking for collisions every pixel
 function Actor:movex(vel)
+    --update subpixel by velocity, and round to a whole pixel
     self.xr = self.xr + vel
     local move = self.xr > 0 and math.floor(self.xr) or self.xr <= 0 and math.ceil(self.xr)
+
+    --step forward one pixel at a time
     if math.abs(move) > 0 then
         local sign = self.xr > 0 and 1 or self.xr < 0 and -1
         self.xr = self.xr - move
 
         while move ~= 0 do
+            --if the next step would cause a collision, halt velocity
             if self:collides({ x = sign, y = 0 }) then
                 self.dx = 0
                 self.xr = 0
                 break
             end
+
+            --otherwise, step forward and update this actor's collision
             self.x = self.x + sign
             move = move - sign
             self:updatebody()
         end
     end
 end
 
+--update the position of this actor vertically, checking for collisions every pixel
 function Actor:movey(vel)
+    --update subpixel by velocity, and round to a whole pixel
     self.yr = self.yr + vel
     local move = self.yr > 0 and math.floor(self.yr) or self.yr <= 0 and math.ceil(self.yr)
+
+    --step forward one pixel at a time
     if math.abs(move) > 0 then
         local sign = self.yr > 0 and 1 or self.yr < 0 and -1
         self.yr = self.yr - move
 
         while move ~= 0 do
+            --if the next step would cause a collision, halt velocity
             if self:collides({ x = 0, y = sign }) then
                 self.dy = 0
                 self.yr = 0
                 break
             end
+
+            --otherwise, step forward and update this actor's collision
             self.y = self.y + sign
             move = move - sign
             self:updatebody()
         end
     end
 end
 
+--update this actor's collision to this actor's (new) position
 function Actor:updatebody()
     for _,box in pairs(self.body) do
         box.x = self.x + box.xoff
@@ -110,16 +132,19 @@ function Actor:updatebody()
 end
 
 function Actor:applyphysics(dt)
+    --calculate friction based on framerate, and apply
     local friction = 1 / (1 + (dt * physics.friction))
     self.dx = self.dx * friction
-    --self.dy = self.dy * friction
 
+    --move self based on velocity
     self:movex(self.dx * dt * 100)
     self:movey(self.dy * dt * 100)
 
+    --if self's velocity is very small, snap to 0
     if math.abs(self.dx) < 0.001 then self.dx = 0 end
     if math.abs(self.dy) < 0.001 then self.dy = 0 end
 
+    --apply gravity
     self.dy = self.dy + dt * physics.gravity
 end
 

map.lua

@@ -38,9 +38,9 @@ end
 --check to see if a tile is surrounded by other tiles on this layer
 function surrounded(layer, x, y, custommap)
     custommap = custommap or map
-    return gettile(layer, x - 1, y, custommap) ~= nil 
+    return gettile(layer, x - 1, y, custommap) ~= nil
         and gettile(layer, x + 1, y, custommap) ~= nil
-        and gettile(layer, x, y - 1, custommap) ~= nil 
+        and gettile(layer, x, y - 1, custommap) ~= nil
         and gettile(layer, x, y + 1, custommap) ~= nil
 end
 
@@ -113,7 +113,7 @@ end
 
 --look up in the spawntable for each object in the map
 function spawn(map)
-    for k,v in pairs(map.objects) do
+    for _,v in pairs(map.objects) do
         if spawntable[v.name] then
             spawntable[v.name](v)
         end

player.lua

@@ -1,23 +1,23 @@
 Player = inherits(Actor)
 local player_mt = class(Player)
 
-function Player:new(x, y, skins, args)
-    args = args or {}
+function Player:new(x, y, skins, opts)
+    opts = opts or {}
 
     local o = Actor:init(x, y, skins)
     o.type = "dynamic"
 
     local s = setmetatable(o, player_mt)
 
-    if args.default then
+    if opts.default then
         s:adddefaultbox()
     end
 
     return s
 end
 
-function Player:add(x, y, skins, args)
-    table.insert(p, Player:new(x, y, skins, args))
+function Player:add(x, y, skins, opts)
+    table.insert(p, Player:new(x, y, skins, opts))
 end
 
 function Player:update(dt)