From 1acd03f96f9b1133e1f76d76004f5fcddd0c4788 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Mon, 28 Jul 2014 17:09:39 +0200 Subject: Added cClientHandle:GetUUIDsFromPlayerNames() to Lua API. --- MCServer/Plugins/APIDump/APIDesc.lua | 1 + 1 file changed, 1 insertion(+) (limited to 'MCServer/Plugins/APIDump/APIDesc.lua') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index e65da1d16..f29c47338 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -529,6 +529,7 @@ end GetPlayer = { Params = "", Return = "{{cPlayer|cPlayer}}", Notes = "Returns the player object connected to this client. Note that this may be nil, for example if the player object is not yet spawned." }, GetUniqueID = { Params = "", Return = "number", Notes = "Returns the UniqueID of the client used to identify the client in the server" }, GetUUID = { Params = "", Return = "string", Notes = "Returns the authentication-based UUID of the client. This UUID should be used to identify the player when persisting any player-related data." }, + GetUUIDsFromPlayerNames = { Params = "PlayerNames", Return = "table", Notes = "(STATIC) Returns a table that contains the map, 'PlayerName' -> 'UUID', for all valid playernames in the input array-table. PlayerNames not recognized will not be set in the returned map. Queries the Mojang servers for the results. WARNING: Do NOT use this function while the server is running. Only use it when the server is starting up (inside the Initialize() method), otherwise you will lag the server severely. NOTE: Mojang API has a limit of 100 names per query and 600 queries per 10 minutes (may change)" }, GetUsername = { Params = "", Return = "string", Notes = "Returns the username that the client has provided" }, GetViewDistance = { Params = "", Return = "number", Notes = "Returns the viewdistance (number of chunks loaded for the player in each direction)" }, HasPluginChannel = { Params = "ChannelName", Return = "bool", Notes = "Returns true if the client has registered to receive messages on the specified plugin channel." }, -- cgit v1.2.3 From 6476bd0e2ee7e128e3eaa56159f169f0a53736ff Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Wed, 30 Jul 2014 13:44:03 +0200 Subject: Exported cMojangAPI to Lua. --- MCServer/Plugins/APIDump/APIDesc.lua | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) (limited to 'MCServer/Plugins/APIDump/APIDesc.lua') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index f29c47338..e5114784e 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -529,7 +529,6 @@ end GetPlayer = { Params = "", Return = "{{cPlayer|cPlayer}}", Notes = "Returns the player object connected to this client. Note that this may be nil, for example if the player object is not yet spawned." }, GetUniqueID = { Params = "", Return = "number", Notes = "Returns the UniqueID of the client used to identify the client in the server" }, GetUUID = { Params = "", Return = "string", Notes = "Returns the authentication-based UUID of the client. This UUID should be used to identify the player when persisting any player-related data." }, - GetUUIDsFromPlayerNames = { Params = "PlayerNames", Return = "table", Notes = "(STATIC) Returns a table that contains the map, 'PlayerName' -> 'UUID', for all valid playernames in the input array-table. PlayerNames not recognized will not be set in the returned map. Queries the Mojang servers for the results. WARNING: Do NOT use this function while the server is running. Only use it when the server is starting up (inside the Initialize() method), otherwise you will lag the server severely. NOTE: Mojang API has a limit of 100 names per query and 600 queries per 10 minutes (may change)" }, GetUsername = { Params = "", Return = "string", Notes = "Returns the username that the client has provided" }, GetViewDistance = { Params = "", Return = "number", Notes = "Returns the viewdistance (number of chunks loaded for the player in each direction)" }, HasPluginChannel = { Params = "ChannelName", Return = "bool", Notes = "Returns true if the client has registered to receive messages on the specified plugin channel." }, @@ -1607,6 +1606,31 @@ a_Player:OpenWindow(Window); }, -- cMapManager + cMojangAPI = + { + Desc = [[ + Provides interface to various API functions that Mojang provides through their servers. Note that + some of these calls will wait for a response from the network, and so shouldn't be used while the + server is fully running (or at least when there are players connected) to avoid percepted lag.

+

+ Some functions are static and do not require an instance to be called. For others, you need to get + the singleton instance of this class using {{cRoot}}'s GetMojangAPI() function.

+

+ Mojang uses two formats for UUIDs, short and dashed. MCServer works with short UUIDs internally, but + will convert to dashed UUIDs where needed - in the protocol login for example. The MakeUUIDShort() + and MakeUUIDDashed() functions are provided for plugins to use for conversion between the two + formats. + ]], + Functions = + { + AddPlayerNameToUUIDMapping = { Params = "PlayerName, UUID", Return = "", Notes = "Adds the specified PlayerName-to-UUID mapping into the cache, with current timestamp." }, + GetUUIDsFromPlayerNames = { Params = "PlayerNames", Return = "table", Notes = "Returns a table that contains the map, 'PlayerName' -> 'UUID', for all valid playernames in the input array-table. PlayerNames not recognized will not be set in the returned map. Queries the Mojang servers for the results. WARNING: Do NOT use this function while the server is running. Only use it when the server is starting up (inside the Initialize() method), otherwise you will lag the server severely." }, + MakeUUIDDashed = { Params = "UUID", Return = "DashedUUID", Notes = "(STATIC) Converts the UUID to a dashed format (\"01234567-8901-2345-6789-012345678901\"). Accepts both dashed and short UUIDs. Logs a warning and returns an empty string if UUID format not recognized." }, + MakeUUIDShort = { Params = "UUID", Return = "ShortUUID", Notes = "(STATIC) Converts the UUID to a short format (without dashes, \"01234567890123456789012345678901\"). Accepts both dashed and short UUIDs. Logs a warning and returns an empty string if UUID format not recognized." }, + }, + + }, + cMonster = { Desc = [[ @@ -2002,6 +2026,7 @@ cPluginManager.AddHook(cPluginManager.HOOK_CHAT, OnChatMessage); GetFurnaceFuelBurnTime = { Params = "{{cItem|Fuel}}", Return = "number", Notes = "(STATIC) Returns the number of ticks for how long the item would fuel a furnace. Returns zero if not a fuel." }, GetFurnaceRecipe = { Params = "{{cItem|InItem}}", Return = "{{cItem|OutItem}}, NumTicks, {{cItem|InItem}}", Notes = "(STATIC) Returns the furnace recipe for smelting the specified input. If a recipe is found, returns the smelted result, the number of ticks required for the smelting operation, and the input consumed (note that MCServer supports smelting M items into N items and different smelting rates). If no recipe is found, returns no value." }, GetGroupManager = { Params = "", Return = "{{cGroupManager|cGroupManager}}", Notes = "Returns the cGroupManager object." }, + GetMojangAPI = { Params = "", Return = "{{cMojangAPI}}", Notes = "Returns the {{cMojangAPI}} object." }, GetPhysicalRAMUsage = { Params = "", Return = "number", Notes = "Returns the amount of physical RAM that the entire MCServer process is using, in KiB. Negative if the OS doesn't support this query." }, GetPluginManager = { Params = "", Return = "{{cPluginManager|cPluginManager}}", Notes = "Returns the cPluginManager object." }, GetPrimaryServerVersion = { Params = "", Return = "number", Notes = "Returns the servers primary server version." }, -- cgit v1.2.3 From 1793644feff66b076980c669ede94d7b03eceafe Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Wed, 30 Jul 2014 14:02:36 +0200 Subject: APIDump: Fixed UUID-related documentation. --- MCServer/Plugins/APIDump/APIDesc.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'MCServer/Plugins/APIDump/APIDesc.lua') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index e5114784e..692ca80ac 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -523,12 +523,12 @@ end Functions = { - GenerateOfflineUUID = { Params = "Username", Return = "string", Notes = "(STATIC) Generates an UUID based on the player name provided. This is used for the offline (non-auth) mode, when there's no UUID source. Each username generates a unique and constant UUID, so that when the player reconnects with the same name, their UUID is the same. Returns a 36-char UUID (with dashes)." }, + GenerateOfflineUUID = { Params = "Username", Return = "string", Notes = "(STATIC) Generates an UUID based on the player name provided. This is used for the offline (non-auth) mode, when there's no UUID source. Each username generates a unique and constant UUID, so that when the player reconnects with the same name, their UUID is the same. Returns a 32-char UUID (no dashes)." }, GetLocale = { Params = "", Return = "Locale", Notes = "Returns the locale string that the client sends as part of the protocol handshake. Can be used to provide localized strings." }, GetPing = { Params = "", Return = "number", Notes = "Returns the ping time, in ms" }, GetPlayer = { Params = "", Return = "{{cPlayer|cPlayer}}", Notes = "Returns the player object connected to this client. Note that this may be nil, for example if the player object is not yet spawned." }, GetUniqueID = { Params = "", Return = "number", Notes = "Returns the UniqueID of the client used to identify the client in the server" }, - GetUUID = { Params = "", Return = "string", Notes = "Returns the authentication-based UUID of the client. This UUID should be used to identify the player when persisting any player-related data." }, + GetUUID = { Params = "", Return = "string", Notes = "Returns the authentication-based UUID of the client. This UUID should be used to identify the player when persisting any player-related data. Returns a 32-char UUID (no dashes)" }, GetUsername = { Params = "", Return = "string", Notes = "Returns the username that the client has provided" }, GetViewDistance = { Params = "", Return = "number", Notes = "Returns the viewdistance (number of chunks loaded for the player in each direction)" }, HasPluginChannel = { Params = "ChannelName", Return = "bool", Notes = "Returns true if the client has registered to receive messages on the specified plugin channel." }, -- cgit v1.2.3 From a71c2da3f8ee329977902a36274d720908a77c48 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Wed, 30 Jul 2014 17:07:57 +0200 Subject: APIDump: Added notes about cache to cMojangAPI. --- MCServer/Plugins/APIDump/APIDesc.lua | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'MCServer/Plugins/APIDump/APIDesc.lua') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 692ca80ac..2a8ae90f9 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -1619,7 +1619,13 @@ a_Player:OpenWindow(Window); Mojang uses two formats for UUIDs, short and dashed. MCServer works with short UUIDs internally, but will convert to dashed UUIDs where needed - in the protocol login for example. The MakeUUIDShort() and MakeUUIDDashed() functions are provided for plugins to use for conversion between the two - formats. + formats.

+

+ This class will cache values returned by the API service. The cache will hold the values for 7 days + by default, after that, they will no longer be available. This is in order to not let the server get + banned from using the API service, since they are rate-limited to 600 queries per 10 minutes. The + cache contents also gets updated whenever a player successfully joins, since that makes the server + contact the API service, too, and retrieve the relevant data.

]], Functions = { -- cgit v1.2.3 From 8b519bf6e20a987c9544ef11f0df6467831cc069 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Thu, 31 Jul 2014 10:02:50 +0200 Subject: MojangAPI: Added a UseCachedOnly param to GetUUIDsFromPlayerNames(). --- MCServer/Plugins/APIDump/APIDesc.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'MCServer/Plugins/APIDump/APIDesc.lua') diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 2a8ae90f9..9d0e90999 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -1630,7 +1630,7 @@ a_Player:OpenWindow(Window); Functions = { AddPlayerNameToUUIDMapping = { Params = "PlayerName, UUID", Return = "", Notes = "Adds the specified PlayerName-to-UUID mapping into the cache, with current timestamp." }, - GetUUIDsFromPlayerNames = { Params = "PlayerNames", Return = "table", Notes = "Returns a table that contains the map, 'PlayerName' -> 'UUID', for all valid playernames in the input array-table. PlayerNames not recognized will not be set in the returned map. Queries the Mojang servers for the results. WARNING: Do NOT use this function while the server is running. Only use it when the server is starting up (inside the Initialize() method), otherwise you will lag the server severely." }, + GetUUIDsFromPlayerNames = { Params = "PlayerNames, [UseOnlyCached]", Return = "table", Notes = "Returns a table that contains the map, 'PlayerName' -> 'UUID', for all valid playernames in the input array-table. PlayerNames not recognized will not be set in the returned map. If UseOnlyCached is false (the default), queries the Mojang servers for the results that are not in the cache.
WARNING: Do NOT use this function with UseOnlyCached set to false while the server is running. Only use it when the server is starting up (inside the Initialize() method), otherwise you will lag the server severely." }, MakeUUIDDashed = { Params = "UUID", Return = "DashedUUID", Notes = "(STATIC) Converts the UUID to a dashed format (\"01234567-8901-2345-6789-012345678901\"). Accepts both dashed and short UUIDs. Logs a warning and returns an empty string if UUID format not recognized." }, MakeUUIDShort = { Params = "UUID", Return = "ShortUUID", Notes = "(STATIC) Converts the UUID to a short format (without dashes, \"01234567890123456789012345678901\"). Accepts both dashed and short UUIDs. Logs a warning and returns an empty string if UUID format not recognized." }, }, -- cgit v1.2.3