game.lua

--- Game related variables and functions.
...

--- The current level the game is played on. Read-only.
level = nil

--- A list the player's settings and client information.
settings = {
	isMobile = false, -- Is the client running on iOS or Android? Read-only.
	isGuest = false, -- Is the player a guest? Read-only.
	isMuted = false, -- Is the player's sound muted? Read-only.
	drawBackgrounds = false, -- Does the player have art backgrounds / art lua enabled? Read-only.
	soundVolume = 100, -- The player's sound volume, expressed as a value ranging from 0 - 100. Read-only.
	musicVolume = 100 -- The player's music volume, expressed as a value ranging from 0 - 100. Read-only.
}

--- The amount of players in the game. Read-only.
--- @see getPlayer
playersCount = 1

--- [Alias of `playersCount`] The amount of players in the game. Read-only.
--- @see getPlayer
playerCount = 1

--- How many ticks have passed since the game started. Read-only.
--- Returns a game timer which calls `listener` every `interval` milliseconds up to `maxCount` times.

--- How many milliseconds (in simulated game time) have passed since the game started. Read-only.
elapsedMS = 0

--- How many milliseconds (in real time / wall clock time) have passed since Lua started running. Read-only.
elapsedRealMS = 0

--- A server-synced random seed. In level editor / offline, this seed is created by the client.
seed = 0

--- A lua table that can be read from and written to freely, but the field itself cannot be overwritten.
_METADATA = {}

--- The event handler for game init. A drawing lock may be obtained from this event.
---
--- The drawing lock will prevent drawing completion until all existing drawing locks are disposed of.
--- @usage local lock = nil
---- game.init.addListener(function(event)
----     lock = event.acquireLock()
----     
----     game.requestUserData(function(data, error)
----         data = data
----         error = error
----         -- Do something here
----         lock.dispose()
----     end)
---- end)
--- @see eventlistener
--- @see lock
init = nil

--- The event handler for game start.
--- @see eventlistener
start = nil

--- The event handler for game tick.
--- @see eventlistener
tick = nil

--- The event handler for enter frame. Fires on every rendered frame.
--- @see eventlistener
enterFrame = nil

--- The handler for gameEvents sent via player.postGameEvent.
---
--- Provides a gameEvent, from which you can get data and source (the player-sender).
---
--- tolua method must be used for every variable you get from the gameEvent.
--- @usage game.gameEvent.addListener(function(event)
----     local data = event.data
----     local sender = event.source
----     -- Do something here
---- end)
gameEvent = nil

--- The event handler for player removing, whether by finishing or forfeiting the match.
--- Provides the object of the removed player.
--- @usage game.playerRemoved.addListener(function(removedPlayer)
----     -- Do something here
---- end)
playerRemoved = nil

--- 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
function newRNG(seed)
end

--- Gets a player object by their index.
--- 
--- Remote player objects' variables are read-only. Exceptions are metadata and visual effects, which can be both set and get.
--- Note: remote metadata and visual effects are still local only.
--- @tparam int index Index of the player.
--- @return Returns the local/remote player object.
--- @usage game.getPlayer(1)
--- @see playersCount
--- @see remoteplayer
function getPlayer(index)
end

--- Gets a list of all players existing in the game.
--- 
--- Remote player objects' variables are read-only. Exceptions are metadata and visual effects, which can be both set and get.
--- Note: remote metadata and visual effects are still local only.
--- @return An AS3 array of all players in the game.
--- @usage local players = totable(game.getAllPlayers())
---- for i, v in pairs(players) do
----     v.setmetadata("index", i)
---- end
--- @see @{utils.tovararg|tovararg}
--- @see remoteplayer
function getAllPlayers()
end

--- Returns a game timer which calls `listener` every `interval` milliseconds (in simulated game time) up to `maxCount` times.
--- 
--- Timers created with this method will not run before the game has finished initializing or after the player is dead.
--- 
--- The timer cannot be triggered on the same tick it is created, nor can it be triggered mid-tick by changing its properties.
--- @tparam number interval How many milliseconds must pass to complete an interval.
--- @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.
--- @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, game.elapsedMS, toobject{})
---- end)
function newTimer(interval, maxCount, listener)
end

--- Returns a game timer which calls `listener` every `interval` milliseconds (in real time / wall clock time) up to `maxCount` times.
--- 
--- Unlike other timers and tick handlers, timers created with this method will run even if the game has not finished initializing yet or if the player is dead.
--- 
--- The timer cannot be triggered on the same tick it is created, nor can it be triggered mid-tick by changing its properties.
--- @tparam number interval How many milliseconds must pass to complete an interval.
--- @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.
--- @see timer
--- @usage playerDiedTimer = game.newRealTimer(100, -1, function()
----     if (not player) or (player.health > 0) then
----         return
----     end
----     
----     player.chat("You died around " .. (playerDiedTimer.elapsedMS / 1000) .. " seconds after the timer started!")
----     playerDiedTimer.destroy()
---- end)
function newRealTimer(interval, maxCount, listener)
end

--- Destroys all game timers created by `newTimer` or `newRealTimer`.
--- @see timer
function destroyAllTimers()
end

--- Requests the player's saved userdata for the level from the server.
--- Provides the userdata or an error message.
---
--- 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.
---
--- @tparam function callback The function that will be called once the request has completed or failed.
--- @usage game.requestUserData(function(data, error)
----     if error ~= nil then
----         player.chat("Error loading user data: " .. tostring(error), 0xFF0000)
----     else
----         player.speed = data.speed
----         player.accel = data.accel
----         player.jump = data.jump
----     end
---- end)
--- @see saveUserData
function requestUserData(callback)
end

--- Requests to save the player's userdata for the level onto the server.
---
--- 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.
---
--- toobject method must be used for the userdata if it is a table.
--- 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 = player.speed,
----     accel = player.accel,
----     jump = player.jump
---- }
----     
---- game.saveUserData(toobject(userdata), function(error)
----     if error ~= nil then
----         player.chat("Error saving user data: " .. tostring(error), 0xFF0000)
----     end
---- end)
--- @see requestUserData
function saveUserData(userdata, callback)
end