diff --git a/BlockTypes.lua b/BlockTypes.lua new file mode 100644 index 0000000..e4eacb3 --- /dev/null +++ b/BlockTypes.lua @@ -0,0 +1,60 @@ +--- BlockTypes library for easier use of block types. +... + +--- Impervious block type. ("impervious") +IMPERVIOUS = "impervious" + +--- Weak block type. ("weak") +WEAK = "weak" + +--- Active block type. ("active") +ACTIVE = "active" + +--- Start block type. ("start") +START = "start" + +--- Inactive block type. ("inactive") +INACTIVE = "inactive" + +--- Change block type. ("change") +CHANGE = "change" + +--- Move block type. ("move") +MOVE = "move" + +--- Water block type. ("water") +WATER = "water" + +--- Reactor block type. ("reactor") +REACTOR = "reactor" + +--- Generator block type. ("generator") +GENERATOR = "generator" + +--- Inactive lua block type. ("lua inactive") +INACTIVE_LUA = "lua inactive" + +--- Water lua block type. ("lua water") +WATER_LUA = "lua water" + + +--- Checks if a block type string is of an active block type. +--- @param type The block type string +--- @treturn boolean Returns whether the block type string is of an active block type. +--- @usage isActive = BlockTypes.isActive(block.type) +function isActive(type) +end + +--- Checks if a block type string is of an inactive block type. +--- @param type The block type string +--- @treturn boolean Returns whether the block type string is of an inactive block type. +--- @usage isInactive = BlockTypes.isInactive(block.type) +function isInactive(type) +end + +--- Checks if a block type string is of a water block type. +--- @param type The block type string +--- @treturn boolean Returns whether the block type string is of a water block type. +--- @usage isWater = BlockTypes.isWater(block.type) +function isWater(type) +end diff --git a/RNG.lua b/RNG.lua index e5ce42d..2901f7b 100644 --- a/RNG.lua +++ b/RNG.lua @@ -16,12 +16,12 @@ end --- Functions the same as math.randomseed(seed), but affecting the RNG object's state. --- Sets the pseudo-random generator's seed: equal seeds produce equal sequences of numbers. ---- @tparam int seed (optional) An optional number input to set the seed with. If none is given, a client-generated seed is used. +--- @tparam number seed (optional) An optional number input to set the seed with. If none is given, a client-generated seed is used. --- @usage RNG.randomseed(151260123) function randomseed(seed) end ---- Returns the RNG object's seed. ---- @treturn int The RNG object's seed. +--- Returns the last number the RNG object was seeded with +--- @treturn number The RNG object's seed. function getseed() end diff --git a/block.lua b/block.lua index 098a31b..0d5ab51 100644 --- a/block.lua +++ b/block.lua @@ -16,6 +16,13 @@ xpos = 0 --- The absolute y-position of the block. ypos = 0 +--- An array containing all of a block's block tags. The tags themselves are strings. +blockTags = 0 + +--- A string describing a block's type. +--- @see BlockTypes +type = "active" + --- The event handler for block break. This event may be cancelled to prevent the block from breaking. --- --- Provides the broken block, the side from which it was broken, and the reason; @@ -25,13 +32,13 @@ ypos = 0 --- @usage game.level.getBlockAt(5, 7).onBreak.addListener(function(event) ---- event.cancelled = true --Prevents the block from breaking ---- ----- local block = tolua(event.block) ----- local side = tolua(event.side) ----- local reason = tolua(event.reason) +---- local block = event.block +---- local side = event.side +---- local reason = event.reason ---- ----- if tolua(instanceof(reason, Projectile)) then --Checks if an item was used to break the block ----- local shooter = tolua(reason.shooter) ----- if tolua(instanceof(shooter, LocalPlayer)) then --Checks if the shooter is the local player +---- if instanceof(reason, Projectile) then --Checks if an item was used to break the block +---- local shooter = reason.shooter +---- if instanceof(shooter, LocalPlayer) then --Checks if the shooter is the local player ---- shooter.hurt() ---- end ---- end @@ -150,7 +157,7 @@ end --- Returns the block's texture as a lua stamp. --- The texture is the block's raw texture, not accounting for effects such as vanishing, freezing, dye, etc. ---- @usage local stamp = tolua(block.getStamp()) +--- @usage local stamp = block.getStamp() --- @treturn stamp The block's texture, or nil if the player has backgrounds disabled in their settings. function getStamp() end @@ -159,7 +166,7 @@ end --- @tparam int x How many blocks to the right the wanted block is? --- @tparam int y How many blocks downwards the wanted block is? --- @tparam boolean keepPlayerReference Is the player reference kept? By default false. ---- @treturn block The found block as an object. Returns nil if a block isn't found. +--- @treturn block The found block as an object. Returns safe null if a block isn't found. --- @usage block.getblock(0,-1).shatter() function getblock(x, y, keepPlayerReference) end @@ -180,3 +187,12 @@ end --- @usage block.getmetadata("block name", "unnamed") function getmetadata(key, defaultValue) end + +--- Returns the first matching block tag, or nil if none is found +--- @tparam string tag The tag to search for +--- @tparam boolean isExact If true, only search for tags that match exactly. Otherwise, matches with any tag that contains the given string. True by default +--- @return Returns the first matching block tag, or nil if none is found. +--- @usage if block.searchTag("awesome", true) then player.chat("Awesome!") end +--- @usage local startTag = block.searchTag("start", false) +function searchTag(tag, isExact) +end diff --git a/game.lua b/game.lua index 5359023..9584f15 100644 --- a/game.lua +++ b/game.lua @@ -45,8 +45,8 @@ _METADATA = {} ---- lock = event.acquireLock() ---- ---- game.requestUserData(function(data, error) ----- data = tolua(data) ----- error = tolua(error) +---- data = data +---- error = error ---- -- Do something here ---- lock.dispose() ---- end) @@ -73,8 +73,8 @@ enterFrame = nil --- --- tolua method must be used for every variable you get from the gameEvent. --- @usage game.gameEvent.addListener(function(event) ----- local data = tolua(event.data) ----- local sender = tolua(event.source) +---- local data = event.data +---- local sender = event.source ---- -- Do something here ---- end) gameEvent = nil @@ -86,8 +86,8 @@ gameEvent = nil ---- end) playerRemoved = nil ---- Returns a new lua-side RNG object (tolua not needed), seeded by the given seed, or a generated client seed is none is given. ---- int seed (optional) An optional number input to set the seed with. If none is given, a client-generated seed is used. +--- Returns a new lua-side RNG object, seeded by the given seed, or a generated client seed is none is given. +--- @tparam int seed (optional) An optional number input to set the seed with. If none is given, a client-generated seed is used. --- @treturn RNG The new RNG object. --- @usage local rng = game.newRNG(51832591) --- @see RNG @@ -132,7 +132,7 @@ end --- @see timer --- @usage alienSpawnTimer = game.newTimer(1000 * 10, -1, function() ---- -- Spawns a new alien every 10 seconds (in simulated game time) ----- game.level.newAlien(1, tolua(game.elapsedMS), toobject{}) +---- game.level.newAlien(1, game.elapsedMS, toobject{}) ---- end) function newTimer(interval, maxCount, listener) end @@ -148,11 +148,11 @@ end --- @treturn timer The created timer object. --- @see timer --- @usage playerDiedTimer = game.newRealTimer(100, -1, function() ----- if (not player) or (tolua(player.health) > 0) then +---- if (not player) or (player.health > 0) then ---- return ---- end ---- ----- player.chat("You died around " .. (tolua(playerDiedTimer.elapsedMS) / 1000) .. " seconds after the timer started!") +---- player.chat("You died around " .. (playerDiedTimer.elapsedMS / 1000) .. " seconds after the timer started!") ---- playerDiedTimer.destroy() ---- end) function newRealTimer(interval, maxCount, listener) @@ -169,15 +169,14 @@ end --- This is an asynchronous method; it will not pause the script while the request is processing. --- Instead, it will later run the given callback function once the request has completed or failed. --- ---- tolua method must be used for every variable you get from the userdata, as well as for the error message. --- @tparam function callback The function that will be called once the request has completed or failed. --- @usage game.requestUserData(function(data, error) ----- if tolua(error) ~= nil then ----- player.chat("Error loading user data: " .. tostring(tolua(error)), 0xFF0000) +---- if error ~= nil then +---- player.chat("Error loading user data: " .. tostring(error), 0xFF0000) ---- else ----- player.speed = tolua(data.speed) ----- player.accel = tolua(data.accel) ----- player.jump = tolua(data.jump) +---- player.speed = data.speed +---- player.accel = data.accel +---- player.jump = data.jump ---- end ---- end) --- @see saveUserData @@ -190,18 +189,18 @@ end --- Instead, it will later run the given callback function once the request has completed or failed. --- --- toobject method must be used for the userdata if it is a table. ---- tolua method must be used for the error message. +--- Buffer data cannot be sent over the network currently, it must be converted to a string with the BufferUtils methods. --- @param userdata The userdata for the level that will be saved to the server. --- @tparam function callback The function that will be called once the request has completed or failed. --- @usage local userdata = { ----- speed = tolua(player.speed), ----- accel = tolua(player.accel), ----- jump = tolua(player.jump) +---- speed = player.speed, +---- accel = player.accel, +---- jump = player.jump ---- } ---- ---- game.saveUserData(toobject(userdata), function(error) ----- if tolua(error) ~= nil then ----- player.chat("Error saving user data: " .. tostring(tolua(error)), 0xFF0000) +---- if error ~= nil then +---- player.chat("Error saving user data: " .. tostring(error), 0xFF0000) ---- end ---- end) --- @see requestUserData diff --git a/level.lua b/level.lua index b6afe7b..1750d5f 100644 --- a/level.lua +++ b/level.lua @@ -16,7 +16,7 @@ maxY = 0 --- Finds a block in the specific coordinates. --- @tparam int x The absolute x position. --- @tparam int y The absolute y position. ---- @treturn block Returns the found block, or nil if not found. +--- @treturn block Returns the found block, or safe null if not found. function getBlockAt(x, y) end @@ -25,7 +25,7 @@ end --- @see @{utils.totable|totable} --- @usage local blocks = totable(game.level.getAllBlocks()) ---- for i, v in pairs(blocks) do ----- v.setmetatable("index", i) +---- v.setmetadata("index", i) ---- end function getAllBlocks() end @@ -58,7 +58,7 @@ end --- @tparam int layerNum The layerNum of the art layer (equivalent to the ">" icon in Level Editor). By default 1. Greater layerNum layers are drawn above lesser layerNum layers, regardless of layer depth. layerNums of 2 or greater draw above blocks. 3 or greater draws above players, hats, projectiles, and other visual effects. --- @treturn artlayer The new art layer, or nil if the player has backgrounds disabled in their settings. --- @see artlayer ---- @usage local layer = tolua(game.level.newArtLayer(1, 3)) +--- @usage local layer = game.level.newArtLayer(1, 3) ---- if layer then ---- layer.drawStamp(someStamp) ---- end @@ -80,7 +80,7 @@ end --- @tparam boolean smoothing Whether the stamp will be smoothed when scaled and rotated or not. By default false. --- @treturn stamp The new stamp, or nil if the player has backgrounds disabled in their settings. --- @see stamp ---- @usage local stamp = tolua(game.level.newStamp(500, 500)) +--- @usage local stamp = game.level.newStamp(500, 500) ---- if stamp then ---- stamp.setRect(0, 0, 500, 500, 0xFF000000) ---- someLayer.drawStamp(stamp) @@ -99,7 +99,7 @@ end --- A sprite may also be set as the "parent" of other display objects, meaning that they will also be rendered whenever the sprite is rendered to an art layer, and with the same transformations as the sprite. --- @treturn sprite The new sprite, or nil if the player has backgrounds disabled in their settings. --- @see sprite ---- @usage local sprite = tolua(game.level.newSprite()) +--- @usage local sprite = game.level.newSprite() ---- if sprite then ---- sprite.beginFill(0xFF000000) -- Draw everything with a solid, fully opaque black. ---- sprite.drawCircle(0, 0, 250) @@ -122,7 +122,7 @@ end --- @param vars An AS3 object containing other variables to provide to the text field, see the text field page for reference. --- @treturn textfield The new text field, or nil if the player has backgrounds disabled in their settings. --- @see textfield ---- @usage local textField = tolua(game.level.newTextField("Awesome Text", 24, 0x80FFCC)) +--- @usage local textField = game.level.newTextField("Awesome Text", 24, 0x80FFCC) ---- someLayer.drawTextField(text) function newTextField(text, size, color, vars) end diff --git a/player.lua b/player.lua index 2ce9e0f..9486ec7 100644 --- a/player.lua +++ b/player.lua @@ -198,7 +198,7 @@ end --- @treturn timer The created timer object. --- @usage healthRegenTimer = player.newTimer(1000 * 6, -1, function() ---- -- Heals 1 health every 6 seconds (in simulated game time) ----- player.health = tolua(player.health) + 1 +---- player.health = player.health + 1 ---- end) function newTimer(interval, maxCount, listener) end @@ -212,11 +212,11 @@ end --- @tparam int maxCount How many intervals will be completed. Set to -1 for infinite intervals. --- @tparam function listener The listener to be called every time an iteration is completed. --- @treturn timer The created timer object. ---- @usage startElapsedTicks = tolua(game.elapsedTicks) +--- @usage startElapsedTicks = game.elapsedTicks ---- tpsCountTimer = player.newRealTimer(1000 * 6, -1, function() ---- -- Reports average ticks per second over a 6 second interval ----- player.chat(tostring((tolua(game.elapsedTicks) - startElapsedTicks) / 6)) ----- startElapsedTicks = tolua(game.elapsedTicks) +---- player.chat(tostring((game.elapsedTicks - startElapsedTicks) / 6)) +---- startElapsedTicks = game.elapsedTicks ---- end) function newRealTimer(interval, maxCount, listener) end @@ -609,7 +609,7 @@ end --- @usage local item = totable(player.getitem()) ---- local item_name = item.typename ---- local item_ammo = item.ammo ---- @return Returns the item as an AS3 Object, with each key being the property name and each value being the property's value. +--- @return Returns the item as an AS3 Object, with each key being the property name and each value being the property's value. If the player is not holding an item, returns safe null. --- ---### Fields ### --- @@ -751,7 +751,7 @@ end --- Is the specified key currently pressed? --- @tparam int keycode The specified key that is being checked. --- @return Returns true if pressed, otherwise false. ---- @usage local Zpressed = tolua(player.keypressed(keys.Z)) +--- @usage local Zpressed = player.keypressed(keys.Z) --- @see @{utils.keys|keys} function keypressed(keycode) end diff --git a/projectile.lua b/projectile.lua index 644e3bf..d1f7eed 100644 --- a/projectile.lua +++ b/projectile.lua @@ -3,5 +3,5 @@ --- The shooter. --- May be either a @{utils.Player|Player} (which may also be a @{utils.LocalPlayer|LocalPlayer}) or nil. ---- @see @{utils.Player|Player} -shooter = nil \ No newline at end of file +--- @see {utils.Player|Player} +shooter = nil diff --git a/sprite.lua b/sprite.lua index 6536c33..4a3417d 100644 --- a/sprite.lua +++ b/sprite.lua @@ -234,11 +234,11 @@ end --- @usage local colors = toarray{0xFF0000FF, 0xFFFFFFFF} -- The gradient will be blue on the left and white on the right ---- local ratios = toarray{0.3 * 255, 1 * 255} -- The gradient will be fully blue up to 30% of the way through the fill, then transition from blue to white across the remaining 70% ---- someSprite.lineStyle(0,24) ----- someSprite.gradientLineStyle(colors, ratios, toobject{width = 100, height = 200, spreadMethod = GradientSpreadMethod.PAD}) -- The width and height of the gradient box will now match that of our next draw call. +---- someSprite.lineGradientStyle(colors, ratios, toobject{width = 100, height = 200, spreadMethod = GradientSpreadMethod.PAD}) -- The width and height of the gradient box will now match that of our next draw call. ---- someSprite.drawRect(0, 0, 100, 200) ---- someSprite.endFill() ---- someLayer.drawSprite(someSprite) -function gradientLineStyle(colors, ratios, vars) +function lineGradientStyle(colors, ratios, vars) end @@ -269,7 +269,7 @@ end --- @see endFill --- @usage ---- someSprite.lineStyle(0,24) ----- someSprite.beginBitmapFill(someStamp,true,true,toobject{ +---- someSprite.lineBitmapStyle(someStamp,true,true,toobject{ ---- x = 5, y = 5, ---- scaleX = 3, scaleY = 3, ---- rotation = 45 @@ -277,7 +277,7 @@ end ---- someSprite.drawRect(0,0,255,255) ---- someSprite.endFill() ---- someLayer.drawSprite(someSprite) -function bitmapLineStyle(stamp, repeats, smooth, vars) +function lineBitmapStyle(stamp, repeats, smooth, vars) end --- Sets the current drawing position used by `lineTo`, `curveTo`, and `cubicCurveTo` to the given coordinates. diff --git a/stamp.lua b/stamp.lua index 10156d4..26212fb 100644 --- a/stamp.lua +++ b/stamp.lua @@ -134,7 +134,7 @@ function setRect(x, y, width, height, color) end --- Sets the ARGB values (alpha and color) of the pixels within the given rectangle, based on a string input. ---- @tparam string hexARGB A string containing ARGB data for each pixel in the hexadecimal format (e.g "FF808080FF000000" for the first pixel to be gray and the second pixel to be black) +--- @param data Either a string containing ARGB data for each pixel in the hexadecimal format (e.g "FF808080FF000000" for the first pixel to be gray and the second pixel to be black), or a buffer containing ARGB data for each pixel. --- @tparam int x The x-coordinate of the top left corner of the rectangle. 0 by default. --- @tparam int y The y-coordinate of the top left corner of the rectangle. 0 by default. --- @tparam int width The width of the rectangle. Stamp width by default. @@ -148,9 +148,30 @@ end ---- end ---- end ---- someStamp.setPixels(table.concat(strBuff),0,0,64,64) -- Set each pixel to a be a fully opaque random color -function setPixels(hexARGB, x, y, width, height) +function setPixels(data, x, y, width, height) end +--- Retrieves the ARGB value (alpha and color) of the pixel at the given coordinate. +--- Note that flash stores the pixels as premultiplied color values, which may cause loss of precision. All stamp methods take and return unmultiplied values. +--- @tparam int x The x-coordinate of the pixel. 0 by default. +--- @tparam int y The y-coordinate of the pixel. 0 by default. +--- @treturn int The ARGB value of the pixel. +--- @usage local pixelColor = someStamp.getPixel(10, 10) -- Retrieves the color of the pixel at (10, 10) +function getPixel(x, y, color) +end + +--- Retrieves the ARGB values (alpha and color) of the pixels within the given rectangle, returning it in a buffer. +--- Note that flash stores the pixels as premultiplied color values, which may cause loss of precision. All stamp methods take and return unmultiplied values. +--- @tparam int x The x-coordinate of the top left corner of the rectangle. 0 by default. +--- @tparam int y The y-coordinate of the top left corner of the rectangle. 0 by default. +--- @tparam int width The width of the rectangle. Stamp width by default. +--- @tparam int height The height of the rectangle. Stamp height by default. +--- @treturn buffer A buffer containing the ARGB data of the pixels in the rectangle. +--- @usage local pixelData = someStamp.getPixels(12,12,24,24) -- Retrieves the pixel data from the rectangle +function getPixels(x, y, width, height) +end + + --- Fills the stamp with randomly generated noise --- @tparam int randomSeed The seed to use for random numbers. --- @tparam int low The lowest value to generate for each channel. diff --git a/utils.lua b/utils.lua index ed874cc..66c2d43 100644 --- a/utils.lua +++ b/utils.lua @@ -19,14 +19,16 @@ Player = nil --- @see instanceof LocalPlayer = nil ---- Converts game value to Lua. This allows the modification of given value. +--- Converts safe null values to nil. Leaves all other values unchanged. --- @param value The value to convert. ---- @return Lua type of the value. ---- @usage player.speed = tolua(player.speed) + 10 +--- @return A value +--- @usage if tolua(game.level.getBlockAt(3,3)) then +---- player.chat("There is a block at 3,3") +---- end function tolua(value) end ---- Converts game object / game array to Lua. This allows iteration over its fields. +--- Converts game object / game array to a lua table. This allows use of the Lua table library. --- --- The Lua table is a copy of the original game data. Therefore, modifications made to the Lua table will not affect the original object / array. --- @param value The value to convert. @@ -323,3 +325,43 @@ GraphicsPathCommand = { --- @see GraphicsPathCommand function GraphicsPathCommand.new() end + + +BufferUtils = { +} + +--- Returns a compressed version of the given buffer. +--- @tparam buffer buf The buffer to compress +--- @treturn buffer A buffer containing the compressed data. +function BufferUtils.compress(buf) +end + +--- Returns a decompressed version of the given buffer. +--- @tparam buffer buf The compressed buffer +--- @treturn buffer A buffer containing the decompressed data. +function BufferUtils.decompress(buf) +end + +--- Converts a given buffer to base64. +--- @tparam buffer buf The buffer to convert +--- @treturn string A base64 string containing the buffer data. +function BufferUtils.toBase64(buf) +end + +--- Converts a base64 string to a buffer. +--- @tparam string str A base64 string +--- @treturn buffer A buffer containing the data. +function BufferUtils.fromBase64(str) +end + +--- Converts a given buffer to hexadecimal. +--- @tparam buffer buf The buffer to convert +--- @treturn string A hex string containing the buffer data. +function BufferUtils.toHex(buf) +end + +--- Converts a hex string to a buffer. +--- @tparam string str A hex string +--- @treturn buffer A buffer containing the data. +function BufferUtils.fromHex(str) +end