Nomchy/discord.js
1
0
Fork 0
mirror of https://github.com/discordjs/discord.js.git synced 2026-03-09 16:13:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

Removed old docs

Browse Source
This commit is contained in:
hydrabolt
2015-11-19 18:05:02 +00:00
parent e08c10507d
commit 9785f37c24
14 changed files with 0 additions and 1855 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
docs/create_simple_bot.rst
View File

@@ -1,132 +0,0 @@
Creating a Simple Bot
=====================
This page will walk you through writing a simple bot and will introduce you to some of the most important functions and objects you will encounter in the API.
Setting up a Project
--------------------
Before you start creating your bot, you need to create a directory, for example *discordbot*.
After you've done that, open up the directory and have a look at how to `install the module`_. After you've installed the module, you can progress to the next step
Creating the Bot
----------------
Now we can begin writing the bot. This bot will just server the user their avatar but at a higher resolution - assuming they have one.
Firstly, create a file named ``bot.js`` in the directory you made earlier. Open it up, and type the following lines of code:
.. code-block:: js
var Discord = require("discord.js");
var bot = new Discord.Client();
This code firstly imports the discord.js module, which contains classes to help you create clients for Discord. The second line creates a new Discord Client, which we can manipulate later. Now, we want the client to be alerted when there is a new message and do something, so we can type this:
.. code-block:: js
bot.on("message", function(message){
} )
This will simply get our client to listen out for new messages, but not yet do anything. Let's have a look at this:
.. code-block:: js
bot.on("message", function(message){
if( message.content === "avatar me!" ){
}
} )
This code will now get our client to execute anything inside the if statement as long as the message sent was "avatar me!" We can now get it to see if the user has an avatar:
.. code-block:: js
bot.on("message", function(message){
if( message.content === "avatar me!" ){
var usersAvatar = message.sender.avatarURL;
if(usersAvatar){
// user has an avatar
}else{
// user doesn't have an avatar
}
}
} )
This code will now see if the user has an avatar and then do something based on that, let's finalise it:
.. code-block:: js
bot.on("message", function(message){
if( message.content === "avatar me!" ){
var usersAvatar = message.sender.avatarURL;
if(usersAvatar){
// user has an avatar
bot.reply(message, "your avatar can be found at " + usersAvatar);
}else{
// user doesn't have an avatar
bot.reply(message, "you don't have an avatar!");
}
}
} )
Let's have a look at the function we used here; *bot.reply*. This function takes 2 necessary parameters, a message object to reply to and a message to send. The first parameter we already have, and it is the message we have received. The second parameter is what we want to send.
Now that we've finished the listener event, we need to log the client in:
.. code-block:: js
bot.login("your discord email", "your discord password");
And that's it! Run the code with ``node bot.js`` and wait a few seconds, and then try sending *avatar me!* to any of the channels that the user you provided has details to.
Final Product
-------------
.. code-block:: js
var Discord = require("discord.js");
var bot = new Discord.Client();
bot.on("message", function(message){
if( message.content === "avatar me!" ){
var usersAvatar = message.sender.avatarURL;
if(usersAvatar){
// user has an avatar
bot.reply(message, "your avatar can be found at " + usersAvatar);
}else{
// user doesn't have an avatar
bot.reply(message, "you don't have an avatar!");
}
}
} );
bot.login("your discord email", "your discord password");
.. note:: This page is still a WIP, check back later for more documentation on it.
.. _install the module : http://discordjs.readthedocs.org/en/latest/get_started.html#installation

82
docs/docs_channel.rst
View File

@@ -1,82 +0,0 @@
.. include:: ./vars.rst
Channels
========
The Channel Class is used to represent data about a Channel.
Attributes
----------
client
~~~~~~
The Discord Client_ that cached the channel
server
~~~~~~
The Server_ that the channel belongs to
name
~~~~
The channel's name, as a `String`.
id
~~
The channel's id, as a `String`.
type
~~~~
The type of the channel as a `String`, either ``text`` or ``voice``.
topic
~~~~~
A `String` that is the topic of the channel, if the channel doesn't have a topic this will be `null`.
messages
~~~~~~~~
An `Array` of Message_ objects received from the channel. There are up to a 1000 messages here, and the older messages will be deleted if necessary.
members
~~~~~~~
**Aliases** : `users`
The members in the channel's server, an `Array` of User_ objects.
-----
Functions
---------
.. note:: When concatenated with a String, the object will become the channel's embed code, e.g. ``"this is " + channel`` would be ``this is <#channelid>``
getMessage(key, value)
~~~~~~~~~~~~~~~~~~~~~~
Gets a Message_ from the channel that matches the specified criteria. E.g:
.. code-block:: js
channel.getMessage("id", 1243987349) // returns a Message where message.id === 1243987349
- **key** - a `String` that is the key
- **value** - a `String` that is the value
permissionsOf(user)
~~~~~~~~~~~~~~~~~~~
Gets the EvaluatedPermissions_ of a User in the channel.
- **user** - A User_ or Member_ you want to get the permissions of.
equals(object)
~~~~~~~~~~~~~~
Returns a `Boolean` depending on whether the Channel's ID (``channel.id``) equals the object's ID (``object.id``). You should **always**, always use this if you want to compare channels. **NEVER** do ``channel1 == channel2``.

775
docs/docs_client.rst
View File

@@ -1,775 +0,0 @@
.. include:: ./vars.rst
Client
======
This page contains documentation on the `Discord.Client` class. This should be used when you want to start creating things with the API.
It might be beneficial to use CTRL+F to search for what you're looking for, or use the navigation provided by readthedocs on the left.
.. note:: As of 3.10.1, Discord.Client extends EventEmitter_. In previous versions, the only available methods were `on` and `off`.
Missed Messages
---------------
As of version 4.1.0, Clients now have the ability to find all the messages they missed and then emit them as `message` events. To opt-in for catching up on messages, just instantiate your client like so:
.. code-block:: js
var client = new Discord.Client({
catchup : "all"
/* this setup will force the client to get ALL
the messages the client has missed */
});
var client = new Discord.Client({
catchup : "fast"
/* this setup will get the last 2500
missed messages, which can be faster
and easier on resources */
});
Messages that have been caught up with will be emitted as a `message` event with the extra parameter `caughtup` which will be true. This allows you to differentiate real-time messages and caught-up ones.
Attributes
----------
options
~~~~~~~
An `Object` containing a configuration for the Client. Currently can only be configured like so:
.. code-block:: js
{
compress : false // whether packets >50kb should be received compressed and later decompressed
catchup : false // read above ^^
}
token
~~~~~
A `String` that is the token received after logging in. It is used to authorise the Client when joining WebSockets or making HTTP requests. Example token:
.. code-block:: js
ODAzTOc4MTA2BjQ2MjY4ODg.COmrCA.fEtD_Tc0JU6iZJU_11coEWBOQHE
state
~~~~~
An `Integer` representing what state of connection the Client is in.
- **0** is idle, meaning the Client has been created but no login attempts have been made.
- **1** is logging in, meaning the Client is in the process of logging in.
- **2** is logged in, meaning the Client is logged in but not necessarily ready.
- **3** is ready, meaning the Client is ready to begin listening.
- **4** is disconnected, meaning the Client was disconnected due to any reason.
See also ready_.
.. code-block:: js
if( bot.state === 3 ) // ready to go
user
~~~~
A `User`_ object representing the account of the signed in client. This will only be available when the client is in the ready state (3).
.. code-block:: js
bot.user.username; // username of the account logged in
email
~~~~~
A `String` that is the email used to sign the client in.
password
~~~~~~~~
A `String` that is the password used to sign the client in.
readyTime
~~~~~~~~~
A `Number` representing the unix timestamp from when the client was ready. `Null` if not yet ready.
.. code-block:: js
bot.readyTime; // 1443378242464
uptime
~~~~~~
A `Number` representing how many milliseconds have passed since the client was ready. `Null` if not yet ready.
.. code-block:: js
if( bot.uptime > 5000 ) // true if the client has been up for more than 5 seconds
ready
~~~~~
A `Boolean` that is true if the client is ready. A shortcut to checking if ``bot.state === 3``.
servers
~~~~~~~
An `Array` of Server_ objects that the client has access to.
channels
~~~~~~~~
An `Array` of Channel_ objects that the client has access to.
users
~~~~~
An `Array` of User_ objects that the client has access to.
PMChannels
~~~~~~~~~~
An `Array` of PMChannel_ objects the client has access to.
messages
~~~~~~~~
An `Array` of Message_ objects the client has received over its uptime.
Functions
---------
.. note :: Any functions used here that take callbacks as an optional parameter can also be used as Promises_. Promises take the exact same parameters for each use case, except errors are moved to catch statements instead of then. For example, you can do:
.. code-block:: js
bot.login(email, password).then(success).catch(err);
function success(token){
}
function err(error){
}
// OR use callbacks:
bot.login(email, password, function(error, token){
});
-----
login(email, password, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Logs the client in to set it up. Use this after registering your event listeners to ensure they are called.
- **email** - A `String` which is the email you want to sign in with.
- **password** - A `String` which is the password you want to sign in with.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
- **token** - if successful, it is the received authorisation token.
logout(`callback`)
~~~~~~~~~~~~~~~~~~
Logs the client out if it is logged in. If successful, ``bot.state == 4``.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
createServer(name, region, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Creates a server with the specified name or region. See valid regions below:
- **name** - A `String` that will be the name of your server.
- **region** - A `String` that is a valid Discord region. Currently **us-west**, **us-east**, **singapore**, **london**, **sydney** or **amsterdam**. Providing an invalid region will result in an error. To find the latest available regions, check the `official API here`_.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
- **server** - A Server_ that represents the created Server.
joinServer(invite, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Accepts a given invite to join a server. The server is automatically cached ASAP.
- **invite** - An `Invite Resolvable`_ which is the invite that should be accepted.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
- **server** - A Server_ that represents the joined Server.
leaveServer(server, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Leaves the given server.
- **server** - A `Server Resolvable`_ that represents the server you want to leave.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
createInvite(channel, options, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Creates an invite for the given channel and returns an Invite_.
- **channel** - A `Channel Resolvable`_ that is the channel you want to create an invite for.
- **options** - An `object` containing configurable options for the invite. See below for possible configurations.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
- **invite** - An Invite_ object that contains the details about the created invite.
.. code-block:: js
// default configuration of the options variable:
options = {
max_age : 0, //A number signifying the expiry time for the invite. 0 means infinite.
max_uses : 0, //A number signifying the amount of uses of the invite. 0 means infinite.
temporary : false, //boolean - whether users who use it are kicked unless promoted within 24h.
xkcd : false //boolean - whether the invite's URL should be human-readable
}
createChannel(server, channelName, channelType, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Creates a channel in the given server.
- **server** - A `Server Resolvable`_ that will be the server the channel is created in.
- **channelName** - A `String` that is the name of the channel.
- **channelType** - A `String` that is the type of the channel, either **voice** or **text**.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
- **channel** - An Channel_ object that represents the created channel.
deleteChannel(channel, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Deletes the specified channel.
- **channel** - A `Channel Resolvable`_ that will be the channel to delete.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
getChannelLogs(channel, `amount`, `options`, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gets previous messages from the specified channel.
- **channel** - A `Channel Resolvable`_ to take logs from.
- **amount** - A `Number` that defaults to **500**. This is the amount of messages to try and get.
- **options** - An `Object` containing the following values:
- **before** - A Message_ (or String ID) which will make the function return messages before this message.
- **after** - A Message_ (or String ID) which will make the function return messages after this message.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
- **logs** - An `Array` of Message_ objects that represent the previous messages.
.. warning:: If the logs contain messages from a user who is no longer in the server, the user object *MAY* be malformed.
sendMessage(channel, message, `options`, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sends a message to the specified channel.
- **channel** - A `Channel Resolvable`_ to send the message to.
- **message** - A `String` or an Array of strings. If an Array, the array will be joined with a new line as a delimiter and this will be the message to be sent.
- **options** - An `Object` that can contain the following parameters:
- **tts** - Whether the message should be text-to-speech (defaults to false)
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
- **message** - A Message_ representing the sent message.
sendFile(channel, file, `fileName`, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sends a file to the specified channel. Note that **fileName is necessary in certain cases** for when a file other than an image is sent. For example, if you send a file containing JS code, fileName should be something like ``myCode.js``.
- **channel** - A `Channel Resolvable`_ to send the file to.
- **file** - The file to send, either a `Buffer` or `String` - if a String, it should be a relative (`./`) or absolute path to a file.
- **fileName** - A `String` containing the file's name and extension, used by Discord (I didn't make this please don't shoot me :s) Examples include `picture.png`, `text.txt`, `wowanamazingscript.js`
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
- **message** - A Message_ representing the sent file.
updateMessage(message, content, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Updates/edits a message with new content.
- **message** - A Message_ that should be updated.
- **content** - A `String` or an Array of strings. If an Array, the array will be joined with a new line as a delimiter and this will be the message to be sent.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
- **message** - A Message_ representing the updated message.
reply(message, yourMessage, `options`, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Alias for sendMessage, but prepends a mention to whoever sent the specified mention. Useful shortcut for directing a message at a user.
.. code-block:: js
// example usage:
the user 'bob' sent a message
bot.reply(message, "hello");
// will send the message '@bob, hello' to the channel the message that bob sent was in.
- **message** - A Message_ that should be replied to.
- **yourMessage** - A `String` or an Array of strings. If an Array, the array will be joined with a new line as a delimiter and this will be the message to be sent.
- **options** - An `Object` that can contain the following parameters:
- **tts** - Whether the message should be text-to-speech (defaults to false)
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
- **message** - A Message_ representing the sent message.
setUsername(newName, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the username of the logged in client.
- **newName** - The new name of the client, a `String`.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
startTyping(channel, *stopTime*)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Makes the client appear to be typing in the specified channel.
- **channel** - A `Channel Resolvable`_ that should be the channel to start typing in
- **stopTime** - A `Number` in ms which should make the client stop typing after. Allow 5 seconds.
stopTyping(channel)
~~~~~~~~~~~~~~~~~~~
Makes the client stop typing in a specified channel.
- **channel** - A `Channel Resolvable`_ that should be the channel to stop typing in.
setStatusOnline()
~~~~~~~~~~~~~~~~~
**Aliases**: ``setStatusActive()`` and ``setStatusHere()``
Sets the client's status to online; green.
setStatusIdle()
~~~~~~~~~~~~~~~~~
**Aliases**: ``setStatusAway()``
Sets the client's status to idle; orange.
setTopic(channel, topic, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the topic of the specified channel
- **channel** - A `Channel Resolvable`_ that is the channel you want to change the topic of
- **topic** - A `String` that is the topic you want
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
createRole(server, data, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Creates a role (or set of permissions) in a given server.
- **server** - A `Server Resolvable`_ where the role should be created.
- **data** - An `Object` containing values available in any `ServerPermissions`_ object.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
- **role** - If no errors occurred, this will be a `ServerPermissions`_ object representing the created role.
.. code-block:: js
// example usage:
bot.createRole(server, {
name : "My Role",
color : Discord.Colors.RED,
sendMessages : false
});
// or you can use a hex string for colours
bot.createRole(server, {
name : "My Role",
color : "#ff0000",
sendMessages : false
});
.. note:: Check the Colors_ helper to find out more about valid Role Colors.
createRoleIfNotExists(server, data, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identical to createRole_ but it only executes if a role with the same name, permissions and color exists in the given server.
- **server** - A `Server Resolvable`_ where the role should be created.
- **data** - An `Object` containing values available in any `ServerPermissions`_ object.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
- **role** - If no errors occurred, this will be a `ServerPermissions`_ object representing the created role.
.. code-block:: js
// example usage:
bot.createRoleIfNotExists(server, {
name : "My Role",
color : Discord.Colors.RED,
sendMessages : false
}) // would execute, role doesn't exist in the server yet
.then(function(){
bot.createRoleIfNotExists(server, {
name : "My Role",
color : Discord.Colors.RED,
sendMessages : false
}); // would not execute, role already exists
});
.. warning :: Due to the asynchronous nature of the code, if you ran the same code twice without putting one in a callback, both would execute as at the point of execution, neither are existant.
deleteRole(role, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Deletes a Role
- **role** - The `ServerPermissions` that you want to delete.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
updateRole(role, data, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Updates a role existing in a server to have new permissions, order, color, name or to have `hoist` (whether it should be its own category in the users list)
- **role** - A `ServerPermissions`_ which represents the role to edit.
- **data** - An `Object` containing values available in any `ServerPermissions`_ object.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
- **role** - If no errors occurred, this will be a `ServerPermissions`_ object representing the edited role.
.. code-block:: js
bot.updateRole(alreadyExistantRole, {
name : "this is a new role name"
});
addMemberToRole(member, role, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Adds a Member to a Server Role.
- **member** - The `Member`_ you would like to add to the role.
- **role** - The `ServerPermissions`_ (or role) you would like to add the member to.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
removeMemberFromRole(member, role, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Removes a Member from a Server Role.
- **member** - The `Member`_ you would like to remove from the role.
- **role** - The `ServerPermissions`_ (or role) you would like to remove the member from.
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
overwritePermissions(channel, role, overwrites, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Overrides/overwrites a role in a specific channel.
- **channel** - A `Channel Resolvable`_ where the permissions should be overridden.
- **role** - A `ServerPermissions`_ role that you want to override
- **overwrites** - An `Object` containing any values in a `ChannelPermissions`_
- **callback** - A `function` that can take the following parameters:
- **error** - An error if one occurred, otherwise it is null.
getUser(key, value)
~~~~~~~~~~~~~~~~~~~
Gets a User_ that matches the specified criteria. E.g:
.. code-block:: js
bot.getUser("id", 1243987349) // returns a user where user.id === 1243987349
- **key** - a `String` that is the key
- **value** - a `String` that is the value
getServer(key, value)
~~~~~~~~~~~~~~~~~~~~~
Gets a Server_ that matches the specified criteria. E.g:
.. code-block:: js
bot.getServer("id", 1243987349) // returns a server where server.id === 1243987349
- **key** - a `String` that is the key
- **value** - a `String` that is the value
getChannel(key, value)
~~~~~~~~~~~~~~~~~~~~~~
Gets a Channel_ that matches the specified criteria. E.g:
.. code-block:: js
bot.getChannel("id", 1243987349) // returns a Channel where channel.id === 1243987349
- **key** - a `String` that is the key
- **value** - a `String` that is the value
getPMChannel(key, value)
~~~~~~~~~~~~~~~~~~~~~~~~
Gets a PMChannel_ that matches the specified criteria. E.g:
.. code-block:: js
bot.getPMChannel("id", 1243987349) // returns a PMChannel where pmchannel.id === 1243987349
- **key** - a `String` that is the key
- **value** - a `String` that is the value
setPlayingGame(id)
~~~~~~~~~~~~~~~~~~
**Aliases** : `playGame`, `playingGame`
Sets the client as playing the specified game name/id.
- **id** - Either a `Number` or a `String`. If it's a Number, it's assumed that you are using a `Discord Game ID`_ and know what you want. If you supply a `String`, it will assume you are entering a game name and try resolving it to a Discord Game ID if it's available. Example:
.. code-block:: js
client.setPlayingGame(18);
// sets the client as playing Minecraft, game ID 18
client.setPlayingGame("Minecraft");
// sets the client as playing Minecraft by resolving the ID to 18
client.setPlayingGame("my magical made up game")
// will stop the client from playing anything as it is unresolved, not a valid game.
-----
Event Management
----------------
Events are a useful way of listening to events and are available in every API.
Registering Events
~~~~~~~~~~~~~~~~~~
.. code-block:: js
bot.on("eventName", function(arg1, arg2...){
// code here is called when eventName is emitted.
})
Unregistering Events
~~~~~~~~~~~~~~~~~~~~
.. code-block:: js
bot.off("eventName")
// eventName is no longer listened for
Event Types
-----------
ready
~~~~~
Called when the bot is ready and you can begin working with it.
disconnected
~~~~~~~~~~~~
Called when the bot is disconnected for whatever reason.
error
~~~~~
Called whenever there is an error.
**Parameters**
- **error** - the encountered error
.. note:: There may be more parameters supplied depending on the errors. Use the ``arguments`` variable to check for this for advanced debugging.
debug
~~~~~
Called when the client debugs some information that might be useful for a developer but not for an end user.
**Parameters**
- **message** - the debug message as a `String`
message
~~~~~~~
Called when a message has been received by the client.
**Parameters**
- **message** - the received Message_.
messageDelete
~~~~~~~~~~~~~
Called when a message has been deleted.
**Parameters**
- **channel** - The Channel_ that the deleted message was in.
- **message** - *May* be available. If the message wasn't previously cached, this will not be supplied and all you would know is that a message was deleted in the channel. If it is available, it will be in the format of a Message_.
messageUpdate
~~~~~~~~~~~~~
Called when a message has been updated.
**Parameters**
- **newMessage** - The updated Message_.
- **oldMessage** - The old Message_ before it was updated.
serverDelete
~~~~~~~~~~~~
Called when a server is deleted.
**Parameters**
- **server** - The deleted Server_.
channelDelete
~~~~~~~~~~~~~
Called when a channel is deleted.
**Parameters**
- **channel** - The deleted Channel_.
serverCreate
~~~~~~~~~~~~
Called when a server is created/joined.
**Parameters**
- **server** - The created Server_.
channelCreate
~~~~~~~~~~~~
Called when a channel is created.
**Parameters**
- **channel** - The created Channel_.
serverNewMember
~~~~~~~~~~~~~~~
Called when a new member is added to a server.
**Parameters**
- **user** - The User_ that was added.
- **server** - The Server_ that the user was added to.
serverRemoveMember
~~~~~~~~~~~~~~~~~~
Called when a member of a server leaves or is kicked out.
**Parameters**
- **user** - The User_ that was removed.
- **server** - The Server_ that the user was removed from.
userUpdate
~~~~~~~~~~
Called when information about a user changes, such as their username.
**Parameters**
- **newUser** - A User_ object representing the changes to the old user (this will be in the cache)
- **oldUser** - A User_ object representing the user before the update.
presence
~~~~~~~~
Called when a user goes online/offline/away or starts/stops playing a game.
**Parameters**
- **dataObject** - Instead of separate arguments, presence update takes an object containing the following information:
- **user** - A User_ representing the User that had a presence update
- **status** - The status change as a `String`.
- **server** - The Server_ that the presence change occurred in.
- **gameId** - A `Number` representing the game they are playing if any. Currently, discord.js has no internal support for converting this into a game name.
unknown
~~~~~~~
Called when an unknown packet was received or there is no handler for it.
**Parameters**
- **data** - A `JSON Object` which is the message received over WebSocket.
raw
~~~
Called when a WebSocket message is received and it gives you the message.
**Parameters**
- **data** - A `JSON Object` which is the message received over WebSocket.
.. _official API here : https://discordapp.com/api/voice/regions
.. _Discord Game ID : https://raw.githubusercontent.com/hydrabolt/discord.js/master/ref/gameMap.json
.. _EventEmitter : https://nodejs.org/api/events.html#events_class_events_eventemitter
.. _createRole : #createRole

108
docs/docs_embed.rst
View File

@@ -1,108 +0,0 @@
.. include:: ./vars.rst
Embeds
======
Embeds are parts of Messages that are sort-of like a preview. They are created serverside by Discord, so in real-time they would come through as part of a `messageUpdate` event. When grabbing messages from logs, they will already be embedded as part of the array ``message.embeds``.
All the Embed classes extend ``Discord.Embed``.
Link Embed
----------
A Link Embed is an embed showing a preview of any linked site in a message.
Attributes
~~~~~~~~~~
.. code-block:: js
{
url, // the URL of the link
type : "link",
title, // title of the embed/URL
thumbnail : {
width, // the width of the thumbnail in pixels
height, // the height of the thumbnail in pixels
url, // the direct URL to the thumbnail
proxy_url, // a proxy URL to the thumbnail
},
provider : {
url, // ???
name, // ???
},
description, // description of the embed
author : {
url, // URL to the author (if any)
name // name of the author (if any)
}
}
Image Embed
-----------
An Image Embed shows an image of a referenced link
Attributes
~~~~~~~~~~
.. code-block:: js
{
url, // the URL of the image
type : "image",
title, // title of the embed/image
thumbnail : {
width, // the width of the thumbnail in pixels
height, // the height of the thumbnail in pixels
url, // the direct URL to the thumbnail
proxy_url, // a proxy URL to the thumbnail
},
provider : {
url, // ???
name, // ???
},
description, // description of the embed
author : {
url, // URL to the author (if any)
name // name of the author (if any)
}
}
Video Embed
-----------
A Video Embed embeds videos (e.g. youtube)
Attributes
~~~~~~~~~~
.. code-block:: js
{
url, // the URL of the video
type : "video",
title, // title of the embed/video
thumbnail : {
width, // the width of the thumbnail in pixels
height, // the height of the thumbnail in pixels
url, // the direct URL to the thumbnail
proxy_url, // a proxy URL to the thumbnail
},
provider : {
url, // ???
name, // ???
},
description, // description of the embed
author : {
url, // URL to the author (if any)
name // name of the author (if any)
},
video : {
width, // the width of the embedded video player
height, // the height of the embedded video player
url // the URL of the embedded play
}
}

64
docs/docs_invite.rst
View File

@@ -1,64 +0,0 @@
.. include:: ./vars.rst
Invites
=======
The Invite Class is used to represent data about an Invite.
Attributes
----------
max_age
~~~~~~~
A `Number` in minutes for how long the Invite should be valid for. E.g. a value of ``3600`` is equal to 30 minutes.
code
~~~~
`String` an alphanumeric code for the Invite.
revoked
~~~~~~~
`Boolean` that dictates whether the Invite has been cancelled or not
created_at
~~~~~~~~~~
A unix timestamp as a `Number` which is the time that the invite was created.
temporary
~~~~~~~~~
`Boolean` that dictates whether the invite is temporary.
uses
~~~~
`Number` the number of uses of the Invite, a value of ``0`` is none.
max_uses
~~~~~~~~
`Number` that is the maximum amount of uses of the invite, ``0`` is unlimited.
inviter
~~~~~~~
The User_ that created the invite.
xkcd
~~~~
`Boolean` that is true if the invite should be human-readable.
channel
~~~~~~~
The Channel_ that the invite is inviting to.
URL
~~~
A `String` that generates a clickable link to the invite.

52
docs/docs_member.rst
View File

@@ -1,52 +0,0 @@
.. include:: ./vars.rst
Members
=======
The Member Class is used to represent a User_ but specific to a server. **Any attributes/functions available in the User class are omitted.**
How do I get a Member from a User?
----------------------------------
Sometimes you might want a Member object, but instead you are given a User_ object. Since Members belong to servers, you can just do:
.. code-block:: js
server.getMember("id", user.id);
This code will either return `false` if no member is found, or a Member if one is found. This method will work if you are given either a User OR Member object.
Attributes
----------
server
~~~~~~
The Server_ that the Member belongs to.
roles
~~~~~
An `Array` of ServerPermissions_ and ChannelPermissions_ that the Member is affected by.
rawRoles
~~~~~~~~
An `Array` of role IDs.
Functions
---------
hasRole(role)
~~~~~~~~~~~~~
Returns a `Boolean` depending on whether or not a user has a certain role.
- **role** - The ServerPermissions_ you want to see if a user has.
permissionsIn(channel)
~~~~~~~~~~~~~~~~~~~~~~
Returns an EvaluatedPermissions_ giving the final permissions of the Member in a channel.
- **channel** - The Channel_ that you want to evaluate the permissions in.

84
docs/docs_message.rst
View File

@@ -1,84 +0,0 @@
.. include:: ./vars.rst
Messages
========
The Message Class is used to represent data about a Message.
Attributes
----------
tts
~~~
A `Boolean` that is ``true`` if the sent message was text-to-speech, otherwise ``false``.
timestamp
~~~~~~~~~
A `unix timestamp` as a `Number` representing when the message was sent.
mentions
~~~~~~~~
An `Array` of Member_ and User_ objects that represent the users mentioned in the message. The only way that the User_ objects would exist in the Array is if the message is from a log, where the mentioned users may have left the server afterwards.
everyoneMentioned
~~~~~~~~~~~~~~~~~
A `Boolean` that is ``true`` if **@everyone** was used, otherwise ``false``.
id
~~
A `String` UUID of the message, will never change.
.. note:: Currently, message IDs are totally unique. However, in the future they may only be unique within a channel. Make sure to check periodically whether this has changed.
embeds
~~~~~~
An `Array` of Embed_ objects.
editedTimestamp
~~~~~~~~~~~~~~~
A `unix timestamp` as a `Number` that is when the message was last edited.
content
~~~~~~~
The actual content of the message as a `String`.
channel
~~~~~~~
The Channel_ that the message was sent in.
author
~~~~~~
**Aliases** : `sender`
The Member or User_ that sent the message. May be a User_ if from a log, it depends on whether the sender left the server after sending the message. If received in realtime, always a Member.
attachments
~~~~~~~~~~~
A raw, unhandled `JSON object` that will contain attachments of the message - if any.
isPrivate
~~~~~~~~~
A `Boolean` that is ``true`` if the message was sent in a PM / DM chat, or if it was sent in a group chat it will be ``false``.
Functions
---------
isMentioned(user)
~~~~~~~~~~~~~~~~~
A `Boolean` that will return ``true`` if the specified user was mentioned in the message. If everyone is mentioned, this will be false - this function checks specifically for if they were mentioned.
- **user** - The User_ that you want to see is mentioned or not.

100
docs/docs_module.rst
View File

@@ -1,100 +0,0 @@
.. include:: ./vars.rst
Module
======
The Module (``require("discord.js")``) contains some helper functions/objects as well the classes use in Discord. The Classes available are omitted as they are visible under the rest of the `Documentation` section.
Discord.Colors
--------------
Currently Colors are only usable in Roles_. You can't use any colour in messages, unless it's syntax highlighting from codeblocks.
.. note:: There is currently an unresolved bug in Discord, long story short any hex colors provided that start with a 0 (e.g. #00FF00) will be changed to #10FF00 to ensure they render properly.
Example Usage
~~~~~~~~~~~~~
.. code-block:: js
// valid color usage (examples 2-4 only from version 3.10.2):
mybot.createRole(server, {
color : Discord.Colors.AQUA
});
mybot.createRole(server, {
color : "#ff0000"
});
mybot.createRole(server, {
color : "ff0000"
});
mybot.createRole(server, {
color : 0xff0000
});
Preset Colors:
~~~~~~~~~~~~~~
.. code-block:: js
// these values are just hex converted to base 10
// e.g.
// 15844367 -> #f1c40f
// dec hex
{
DEFAULT: 0,
AQUA: 1752220,
GREEN: 3066993,
BLUE: 3447003,
PURPLE: 10181046,
GOLD: 15844367,
ORANGE: 15105570,
RED: 15158332,
GREY: 9807270,
DARKER_GREY: 8359053,
NAVY: 3426654,
DARK_AQUA: 1146986,
DARK_GREEN: 2067276,
DARK_BLUE: 2123412,
DARK_PURPLE: 7419530,
DARK_GOLD: 12745742,
DARK_ORANGE: 11027200,
DARK_RED: 10038562,
DARK_GREY: 9936031,
LIGHT_GREY: 12370112,
DARK_NAVY: 2899536
}
toHex(num)
~~~~~~~~~~
Converts a base 10 color (such as the one found in ``serverPermissions.color``) to a valid hex string (e.g. ``#ff0000``)
- **num** - `Number` that you want to convert to hex
.. code-block:: js
// converts Discord.Color.DARK_NAVY to hex:
Discord.Color.toHex( Discord.Color.DARK_NAVY ); // returns '#2C3E50'
toDec(data)
~~~~~~~~~~~
Converts a hex string to a valid, base 10 Discord color.
- **data** - `String` that you want to convert, valid formats include: ``ff0000` and ``#ff0000`. If a valid base 10 color (e.g. ``0xff0000`` is passed, this is returned, making the function well at handling ambiguous data.
.. code-block:: js
// if you want to create/update a role, you don't have to use
// Color.toDec, this is done for you.
Discord.Color.toDec( "#ff0000" ); // 16711680
Discord.Color.toDec( "ff0000" ); // 16711680
Discord.Color.toDec( 0xff0000 ); // 16711680

156
docs/docs_permissions.rst
View File

@@ -1,156 +0,0 @@
.. include:: ./vars.rst
Permissions
===========
The Permissions Class represents data of permissions/roles.
ServerPermissions
-----------------
ServerPermissions are also known as roles. They give the general gist of permissions of all users in a Server.
name
~~~~
`String` that is the name of the role.
color
~~~~~
`Number` that represents a colour in base 10. To resolve it to a hex colour, just do: ``permission.color.toString(16)``
hoist
~~~~~
`Boolean`, whether the role should be a separate category in the users list.
managed
~~~~~~~
`Boolean`, whether the permission is managed by Discord. Currently only used by Twitch integration.
position
~~~~~~~~
`Number`, the position of the role that states its importance.
id
~~
`Number`, the ID of the role.
server
~~~~~~
Server_ that the role belongs to.
Actual Permissions:
~~~~~~~~~~~~~~~~~~~
`Actual Permissions` is not an attribute, however the following permissions are attributes of ServerPermissions. They are self-explanatory.
.. code-block:: js
{
createInstantInvite,
manageRoles, // if this is true all the others are true
manageChannels,
readMessages,
sendMessages,
sendTTSMessages,
manageMessages, // deleting, editing etc
embedLinks,
attachFiles,
readMessageHistory,
mentionEveryone,
voiceConnect,
voiceSpeak,
voiceMuteMembers,
voiceDeafenMembers,
voiceMoveMembers,
voiceUseVoiceActivation
}
serialize()
~~~~~~~~~~~
**Aliases** : *serialise()*
To get a valid `Object` of the actual permissions of the object, just do `serverPermissions.serialise()` to get an object with the above mentioned permissions
ChannelPermissions
------------------
ChannelPermissions are based from a ServerPermissions object (although not actually extending them, none of the Permissions objects extend each other). It represents an override/overwrite of a server permission.
Actual Permissions:
~~~~~~~~~~~~~~~~~~~
.. code-block:: js
{
createInstantInvite,
manageRoles,
manageChannels,
readMessages,
sendMessages,
sendTTSMessages,
manageMessages,
embedLinks,
attachFiles,
readMessageHistory,
mentionEveryone,
voiceConnect,
voiceSpeak,
voiceMuteMembers,
voiceDeafenMembers,
voiceMoveMember,
voiceUseVoiceActivation
}
serialize()
~~~~~~~~~~~
**Aliases** : *serialise()*
To get a valid `Object` of the actual permissions of the object, just do `channelPermissions.serialise()` to get an object with the above mentioned permissions
EvaluatedPermissions
--------------------
EvaluatedPermissions represents the permissions of a user in a channel, taking into account all roles and overwrites active on them; an evaluation of their permissions.
Actual Permissions:
~~~~~~~~~~~~~~~~~~~
EvaluatedPermissions has the same permissions as ChannelPermissions.
.. code-block:: js
{
createInstantInvite,
manageRoles,
manageChannels,
readMessages,
sendMessages,
sendTTSMessages,
manageMessages,
embedLinks,
attachFiles,
readMessageHistory,
mentionEveryone,
voiceConnect,
voiceSpeak,
voiceMuteMembers,
voiceDeafenMembers,
voiceMoveMember,
voiceUseVoiceActivation
}
serialize()
~~~~~~~~~~~
**Aliases** : *serialise()*
To get a valid `Object` of the actual permissions of the object, just do `channelPermissions.serialise()` to get an object with the above mentioned permissions

41
docs/docs_pmchannel.rst
View File

@@ -1,41 +0,0 @@
.. include:: ./vars.rst
PMChannel
=========
The PMChannel Class is used to represent data about a Private Message Channel.
.. note:: Beware! The PMChannel class does `not` extend the Channel_ class.
Attributes
----------
user
~~~~
The recipient User_ of the PM Channel.
id
~~
`String` UUID of the PM Channel.
messages
~~~~~~~~
An `Array` of Message_ objects. Contains all the cached messages sent in this channel up to a limit of 1000. If the limit is reached, the oldest message is removed first to make space for it.
Functions
---------
getMessage(key, value)
~~~~~~~~~~~~~~~~~~~~~~
Gets a Message_ from the PM Channel that matches the specified criteria. E.g:
.. code-block:: js
pmchannel.getMessage("id", 1243987349) // returns a Message where message.id === 1243987349
- **key** - a `String` that is the key
- **value** - a `String` that is the value

39
docs/docs_resolvable.rst
View File

@@ -1,39 +0,0 @@
.. include:: ./vars.rst
Resolvables
===========
To be robust, discord.js needs to handle a wide amount of ambiguous data that is supplied to it. This means you can use functions much more easily. Anything that is resolvable means it can be normalised without you having to do it explicitly.
Resolvables are not objects or classes, they are just ways of expressing what type of data is expected.
Channel Resolvable
------------------
A Channel Resolvable is data that can be resolved to a channel ID. Here is what is currently supported:
- A Channel_ object
- A Server_ object (the #general channel of the server will be used)
- A `String` representing the channel ID
- A Message_ (the channel the message was sent in will be used)
- A User_ (will get the PM channel with the specified user)
.. note:: A User cannot always be specified in certain cases. For example, if using `bot.setTopic`, a User or PM Channel can't be specified as these do not support channel topics.
Server Resolvable
-----------------
A Server Resolvable is anything that can be resolved to a server ID. Here is what you can use:
- A Server_ object
- A Channel_ object
- A Message_ object
- A `String` representing the ID of the server
Invite Resolvable
-----------------
An Invite Resolvable is anything that resolves to an invite code. Here is what you can use:
- An Invite_ object
- A `String` which is either the code or an invite URL containing it (e.g. ``https://discord.gg/0SCTAU1wZTZtIopF``)

107
docs/docs_server.rst
View File

@@ -1,107 +0,0 @@
.. include:: ./vars.rst
Servers
=======
The Server Class is used to represent data about a server.
Attributes
----------
client
~~~~~~
The Discord Client_ that the Server was cached by.
region
~~~~~~
The region that the server is in, a `String`.
name
~~~~
The server's name, as a `String`.
id
~~
The server's id, as a `String`.
members
~~~~~~~
**Aliases** : `users`
The members in a server, an `Array` of User_ objects.
channels
~~~~~~~~
The channels in a server, an `Array` of Channel_ objects.
icon
~~~~
The icon ID of the server if it has one as a `String`, otherwise it is `null`.
iconURL
~~~~~~~
A `String` that is the URL of the server icon if it has one, otherwise it is `null`.
afkTimeout
~~~~~~~~~~
A `Number` that is the AFK Timeout of the Server.
afkChannel
~~~~~~~~~~
A Channel_ that represents the AFK Channel of the server if it has one, otherwise it is `null`.
defaultChannel
~~~~~~~~~~~~~~
The **#general** Channel_ of the server.
owner
~~~~~
A User_ object representing the user that owns the server.
-----
Functions
---------
.. note:: When concatenated with a String, the object will become the server's name, e.g. ``"this is " + server`` would be ``this is Discord API`` if the server was called `Discord API`.
getChannel(key, value)
~~~~~~~~~~~~~~~~~~~~~~
Gets a Channel_ that matches the specified criteria. E.g:
.. code-block:: js
server.getChannel("id", 1243987349) // returns a Channel where channel.id === 1243987349
- **key** - a `String` that is the key
- **value** - a `String` that is the value
getMember(key, value)
~~~~~~~~~~~~~~~~~~~~~
Gets a Member_ that matches the specified criteria. E.g:
.. code-block:: js
server.getMember("id", 1243987349) // returns a Member where member.id === 1243987349
- **key** - a `String` that is the key
- **value** - a `String` that is the value
equals(object)
~~~~~~~~~~~~~~
Returns a `Boolean` depending on whether the Server's ID (``server.id``) equals the object's ID (``object.id``). You should **always**, always use this if you want to compare servers. **NEVER** do ``server1 == server2``.

67
docs/docs_user.rst
View File

@@ -1,67 +0,0 @@
.. include:: ./vars.rst
Users
=====
The User Class is used to represent data about users.
Attributes
----------
username
~~~~~~~~
A `String` that is the username of the user.
discriminator
~~~~~~~~~~~~~
Used to differentiate users with the same username, provided by Discord. If you want to differentiate users, we'd recommend using the `id` attribute.
id
~~
A `String` UUID of the user, will never change.
avatar
~~~~~~
A `String` that is the user's avatar's ID, or if they don't have one this is `null`.
avatarURL
~~~~~~~~~
A `String` that points to the user's avatar's URL, or if they don't have an avatar this is `null`.
status
~~~~~~
The status of the user as a `String`; offline/online/idle.
-----
Functions
---------
mention()
~~~~~~~~~
Returns a `String`. This function will generate the mention string for the user, which when sent will preview as a mention. E.g:
.. code-block:: js
user.mention(); // something like <@3245982345035>
This is mainly used internally by the API to correct mentions when sending messages, however you can use it.
.. note:: You can also just concatenate a User object with strings to get the mention code, as the `toString()` method points to this. This is useful when sending messages.
equals(object)
~~~~~~~~~~~~~~
Returns a `Boolean` depending on whether the User's ID (``user.id``) equals the object's ID (``object.id``). You should **always**, always use this if you want to compare users. **NEVER** do ``user1 == user2``.
equalsStrict(object)
~~~~~~~~~~~~~~~~~~~~
Sees if the supplied object has the same username, ID, avatar and discriminator of the user. Mainly used internally. Returns a `Boolean` depending on the result.

48
docs/get_started.rst
View File

@@ -1,48 +0,0 @@
===========
Get Started
===========
Installation
------------
Linux
~~~~~~
Install Python 2 and then run ``npm install discord.js --save`` in your project's directory and you should be good to go!
OS X
~~~~
Python 2 and **potentially** X Code, try building without first.
Windows
~~~~~~~~~~~~
**TL;DR You need Visual Studio and Python 2**
Unfortunately, the Windows installation process is a little more lengthy. You need to have `Visual Studio Express`_ (or any of the other distributions of it). This is necessary for build tools for the WebSocket dependency.
.. note:: If you are using another version of Visual Studio, such as 2012, replace the flag with ``--msvs_version=2012``
After you have installed Visual Studio, you then need to install any Python setups that are version 2.
After you have obtained these tools, you need to run ``npm install discord.js --save --msvs_version=2015`` in your working directory. Hopefully this should all go well!
Cloning the Repo
----------------
If you want to try some examples or make your own changes to discord.js, you can `clone the repo`_. After that run ``npm install`` to install dependencies.
Running Examples
~~~~~~~~~~~~~~~~
If you've cloned the repo, you also have the option to run some examples. You can also do this by just copying the examples_ and then running them. I'd be more than happy to get some pull requests if you want to make any patches ;)
Before you run them though, you need to configure the ``examples/auth.json`` file. This should contain valid Discord credentials and passwords.
After you've configured your credentials, just run ``node examples/pingpong.js`` to run the ping pong example.
.. _Visual Studio Express: https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx
.. _clone the repo: https://github.com/hydrabolt/discord.js.git
.. _examples: https://github.com/hydrabolt/discord.js/tree/master/examples