Skip to content

Latest commit

 

History

History
144 lines (121 loc) · 5.55 KB

CONTRIBUTING.md

File metadata and controls

144 lines (121 loc) · 5.55 KB

Contribute to the API

Donations

Donate

Funny or not, donations are fundamental to keep the development of the project going.

If you have disponibility to donate any value, do not hesitate in helping us via PayPal!

Thanks for all the donations until now! ($24) ♥

Documentation

You must document every function / event in your pull request, but it's not necessary to edit the markdown files.

To document Methods use the format provided here.
Currently the Events documentation has to be done manually using the functions format.

Coding Convention

The code style matters in your pull requests.
Please follow the clear conventions used in the files or you risk your pull request getting rejected.

- Use tab to indent the code:

	local x = 0 -- Correct
    local x = 0 -- Wrong

- Ifs not only returning nil must be written in different lines:

-- Correct
if true then return end
if true then
	x() -- Correct
end
-- Wrong
if true then
	return
end
if true then x() end

- Comments are only needed when a detailed explaination sums up to the understanding of the line;
- Function must not use sugar syntax. (also applies for OOP):

-- Correct
x = function(a, b)
o.x = function(self, ...)
-- Wrong
function x(a, b)
function o:x(...)

- Global functions must be avoided;
- There must not be indexes and values spaced as in enumerators:

-- Correct
local hi = 0
local name = 1
-- Wrong
local hi   = 0
local name = 1

- Functions must not be called without parentheses;
- Tables must start and end with a space:

local id = { 1, 2, 3 } -- Correct
local id = {1, 2, 3} -- Wrong

- Use one space between operators:

local x = 1 + 1 -- Correct
local x = 1+1 -- Wrong

- Avoid unnecessary parentheses in conditions or flow controls;
- Use an underscore, _, in variables and indexes that are (or should be) only used internally in the API.

Packet parsers

The packet parsers in the file Client.lua handle the C and CC individually in hashed tables, making the system elegant and efficient.

Use their specific tables to add new events as necessary. Pull requests with the insertXListener are not going to be accepted.

If you are editing an event which already exists, please make sure you include clear reasons in your pull request commentary.

Tribulle events

Tribulle is everything related to the community platform.

  • Search for -- Tribulle functions or for the table tribulleListener;
  • Each function receives the parameters:
    • self<client> The instance receiving the data;
    • packet<byteArray> The data received;
    • connection<connection> The connection that received the data;
    • tribulleId<int> The tribulle id (just for reference)

Regular events

  • Search for -- Normal functions or for the table packetListener;
  • Each function receives the parameters:
    • self<client> The instance receiving the data;
    • packet<byteArray> The data received;
    • connection<connection> The connection that received the data.
    • identifiers<table> The identifiers (C, CC) received. (just for reference)

Old-Packet events

Old packets were used in the old version of the system. They are the data extracted from the first UTF of the received packet.

  • Search for -- Old packet functions or for the table oldPacketListener;
  • Each function receives the parameters:
    • self<client> The instance receiving the data;
    • packet<byteArray> The data extracted;
    • connection<connection> The connection that received the data.
    • oldIdentifiers<table> The identifiers (oldC, oldCC) received. (just for reference)

Functions

Functions and methods are used by the instanced object to perform actions in the game.

If you are editing a function which already exists, please make sure you include clear reasons in your pull request commentary.

It is not necessary that you handle parameter type errors, except if the parameter needs an enumeration.
If the parameter requires an enumeration, use the function (enum._validate)[docs/Internal/enum.md#enumvalidate--enumeration-default-value-errormsg-]

Enumerations

Enumerations should only be created if necessary. They indicate immutable values of an action or behavior.

They must be created in the file Enum.lua and must follow:

- Must use the function (constructor) enum to create enumerators;
→ Must set the second value as true if there are identical values in the table.
- Must space all its values in the same position:

{
	apple     = 1,
	pineapple = 2,
	sandwich  = 3
}

- Enumerators must be aligned, and if the values are numbers they must be appended to zeroes based on the highest value:

{
	apple     = 001,
	pineapple = 002,
	sandwich  = 003,
	soda      = 100
}

Files

New files must start with requires, constructors and auxiliar functions, and the main functions at the end.

Your file must not overwrite functions or tables that are in other files.