Reality Breach - Plugin Docs

--[[ Reality Breach - API Documentation ]]--
-- Last updated: 27 oct 2015
-- RB version: Alpha 0.1
-- Mind that not every new RB version brings a new version of this document
-- (Mostly because not every RB version changes anything to the API)
-- (If I fix a bug in the API, I still don't update this, because no reason to)

--[[ API Members
    API.Version
        A string indicating the current version.

    API:IsRegistered(string name)
        Returns whether or not a pack under that name is registered.
        Useful for making sure your plugins don't run several times.
        It's adviced to check for this, certainly if your plugin
        gets added to the default list, else it'll lead to bugs.
    API:RegisterPack(string name, string creator, string desc)
        Create a new commandpack with the given data.
        Check the section "CommandPack" for using the result.
    API:GetPlayerData(variant player)
        'player' can be: A username, an userId or a Player object.
        You can only load data of in-game players.
        Check the section "PlayerData" for using the result.
--]]

--[[ CommandPack
    Note: You better keep a good secure reference to this!
    A CommandPack gets created by API:RegisterPack() and is unique.
    Nobody else can create a pack with the same name, unless this one gets destroyed.
    You can only add commands to RB by adding them to a commandpack.

    Pack:RegisterCommand(string name, string permission, function handler,
            string desc, string syntax = "", array aliases = {})
        Adds a new command to RB using this commandpack.
        'name', 'permission' and 'desc' are obvious.
        'handler' gets called when someone uses the command.
        It gets called with: Player player, table arguments
        The 'arguments' holds the player's message, split by whitespace
        An example: ".teleport others me" --> handler(PLAYER,{"others","me"})
        'syntax' is a string containing the arguments for the command.
        Examples: "kick <player> (reason)", "hint ...",
                    "showplayers <group>", "move (player) <player,up,down>"
                    (Actually I'm not sure the last example works... oh well)
        'aliases' is an array (a numeric table) containing aliases for the command.
        A simple example for kill: {"makedead","murder","rip"}
    Pack:UnregisterCommand(string name)
        Remove a command you've registered before
    Pack:RegisterPermission(string name, string desc = "<none>")
        Register a new permission, including adding a description to it, if supplied.
        A commandpack "PackA" can only add permissions that start with:
        - commands.packa. (e.g. commands.packa.banana)
        - pack.packa. (e.g. pack.packa.roomaccess.vip)
        (Mind that permissions are case insensitive)
        Creating the permission "a.b.c" will automaticly create
        the permissions "a.b." and "a" if they're missing.
    Pack:UnregisterPermission(string name)
        Removes a permission (same restrictions as for RegisterPermission)
        Deleting a permission will also delete all its childs.
        (E.g. deleting "a.b" also deletes "a.b.c", "a.b.c.d", "a.b.idk", ...
    Pack:Destroy()
        Destroys this pack, removing all permissions and commands created by it.
        This will remove the permissions "commands.PACK" and "packs.PACK" along
        with all commands that got registered by this pack.
--]]

--[[ PlayerData

--]]

--[[ IN-DEPTH INFORMATION ]]--
--[[ Command names
    In case 2 commandpacks have the same command, for example "kill", the
    command "kill" won't work. You'll have to use "pack.kill".
    For packs A and B that would be "A.kill" and "B.kill".
    The command "murder" would work, though, unless another pack also has that.
    It's best if you use original names, while aliases are abbrevations.

    There's a order in which commandnames are "linked" to actual commands.
    Assume we have those 2 packs with the following commands:
    Pack A: "kill" with aliases {"makedead","murder","rip"}
    Pack B: "murder" with aliases {"stopheart"}
            "kill" with aliases {"zerohealth","rip"}
    When the following commands are used, the following happens:
        kill: RB will inform the user it's ambigious, since 2 packs have it as main command
        rip: RB will inform the user it's ambigious, since 2 packs have it as an alias
        murder: "murder" from pack B will be used, even though "kill" has it as alias
        A.kill: "kill" from pack A will be used, since the user used "pack.command"
        makedead: "kill" from pack A will be used, as it's the only command with this alias
    Basicly, when you use a commandname, those are the possible results:
    - There's only one command called that way, which will get used
    - Several commands are called that way, which results in an error (ambigious)
    - There's only one command with it as an alias, that command will get used
    - Several commands have it as an alias, which results in an error (ambigious)
    Of course, a user can bypass this order by using "pack.command", which
    will get the command named "command" directly from the pack "pack"
--]]

--[[ LOADING PLUGINS
    There are 2 ways of loading a plugin.
    Those work basicly the same, though:
    - Have a ModuleScript in the Plugins-folder
    - Manually call "local RB = ..." and use that
    Basicly, all ModuleScripts in the Plugins-folder are
    automaticly required right after RB has loaded.
    If they return a function, it'll be called with RB as argument.
    You can just put your MS somewhere else and require the ID.
    You can even use a regular script if you want.

    If you are using a Dev Build of RB, make sure the RBLoader is
    in ServerScriptService, unless you want weird dualboot and bugs.
--]]

--[[ EXAMPLE PLUGIN ]]--


-- Ignore this code. Just stops the plugin from running online
-- (This is just a test plugin for in studio, for showing an
-- example to developers who want to create a plugin for RB)
local RS = game:GetService("RunService")
local s,e = pcall(RS.IsStudio,RS)
if s  and not e then return false end
RS = UserSettings().GameSettings
if not RS:InStudioMode() then return false end

-- Declare the RB API
local RB = require(293985200)
if RB:IsRegistered("Test") then
    -- We already ran, I guess?
    return false
end

-- Create a commandpack
local Pack = RB:RegisterPack("Test","einsteinK","A pack for testing")

-- Register a permission for our command
Pack:RegisterPermission("commands.test.banana","Use the banana command")

-- Register our command
Pack:RegisterCommand("Banana","commands.test.banana",function(plr,args)
    local num = tonumber(args[1])
    if num and num ~= 1 then
        print(plr,"wants",num,"bananas!")
    else
        print(plr,"wants a banana!")
    end
end,"Announce you want a banana")

-- Register our other command
Pack:RegisterCommand("NoBanana","commands.test.banana",function(plr,args)
    -- Doing ".nobanana" would actually remove this and our previous command
    Pack:UnregisterCommand("NoBanana")
    Pack:UnregisterCommand("Banana")
    -- And our permission we created for it too
    Pack:UnregisterPermission("commands.test")
    print("No more bananas!")
    -- Actually let's just destroy the whole pack
    Pack:Destroy()
end)

return true