diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index 30a2f5bc0..540ab1755 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -55,7 +55,7 @@ further defined and clarified by project maintainers. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at https://discord.gg/bRCvFy9. All +reported by contacting the project team at https://discord.gg/djs. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index e05d270f1..9bbf9fe1d 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -**The issue tracker is only for bug reports and enhancement suggestions. If you have a question, please ask it in the [Discord server](https://discord.gg/bRCvFy9) instead of opening an issue – you will get redirected there anyway.** +**The issue tracker is only for bug reports and enhancement suggestions. If you have a question, please ask it in the [Discord server](https://discord.gg/djs) instead of opening an issue – you will get redirected there anyway.** If you wish to contribute to the discord.js codebase or documentation, feel free to fork the repository and submit a pull request. We use ESLint to enforce a consistent coding style, so having that set up in your editor of choice @@ -12,7 +12,6 @@ To get ready to work on the codebase, please do the following: 1. Fork & clone the repository, and make sure you're on the **master** branch 2. Run `npm ci` -3. If you're working on voice, also run `npm install @discordjs/opus` or `npm install opusscript` -4. Code your heart out! -5. Run `npm test` to run ESLint and ensure any JSDoc changes are valid -6. [Submit a pull request](https://github.com/discordjs/discord.js/compare) (Make sure you follow the [conventional commit format](https://github.com/discordjs/discord.js-next/blob/master/.github/COMMIT_CONVENTION.md)) +3. Code your heart out! +4. Run `npm test` to run ESLint and ensure any JSDoc changes are valid +5. [Submit a pull request](https://github.com/discordjs/discord.js/compare) (Make sure you follow the [conventional commit format](https://github.com/discordjs/discord.js-next/blob/master/.github/COMMIT_CONVENTION.md)) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 4b0241fbc..9b84e5654 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -6,7 +6,7 @@ title: '' labels: 's: unverified, type: bug' assignees: '' --- - + **Please describe the problem you are having in as much detail as possible:** diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index b20361fee..ac30bcff9 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -6,7 +6,7 @@ title: '' labels: 'type: enhancement' assignees: '' --- - + **Is your feature request related to a problem? Please describe.** A clear and concise description of what the problem is. Eg. I'm always frustrated when [...] diff --git a/README.md b/README.md index 844093332..60b80b9d0 100644 --- a/README.md +++ b/README.md @@ -12,23 +12,8 @@ Dependencies Patreon

-

- npm installnfo -

-## Table of contents - -- [About](#about) -- [Installation](#installation) - - [Audio engines](#audio-engines) - - [Optional packages](#optional-packages) -- [Example Usage](#example-usage) -- [Links](#links) - - [Extensions](#extensions) -- [Contributing](#contributing) -- [Help](#help) - ## About discord.js is a powerful [Node.js](https://nodejs.org) module that allows you to easily interact with the @@ -65,9 +50,9 @@ client.on('ready', () => { console.log(`Logged in as ${client.user.tag}!`); }); -client.on('message', msg => { - if (msg.content === 'ping') { - msg.channel.send('pong'); +client.on('message', message => { + if (message.content === 'ping') { + message.channel.send('pong'); } }); @@ -84,7 +69,7 @@ client.login('token'); - [Discord API Discord server](https://discord.gg/discord-api) - [GitHub](https://github.com/discordjs/discord.js) - [NPM](https://www.npmjs.com/package/discord.js) -- [Related libraries](https://discordapi.com/unofficial/libs.html) +- [Related libraries](https://discord.com/developers/docs/topics/community-resources#libraries) ### Extensions diff --git a/docs/general/faq.md b/docs/general/faq.md deleted file mode 100644 index a46554566..000000000 --- a/docs/general/faq.md +++ /dev/null @@ -1,26 +0,0 @@ -# Frequently Asked Questions - -These questions are some of the most frequently asked. - -## How do I get voice working? - -- Install FFMPEG. -- Install either the `@discordjs/opus` package or the `opusscript` package. - @discordjs/opus is greatly preferred, due to it having significantly better performance. - -## How do I install FFMPEG? - -- **npm:** `npm install ffmpeg-static` -- **Ubuntu 20.04:** `sudo apt install ffmpeg` -- **Ubuntu 18.04:** `sudo apt install ffmpeg` -- **Windows:** `npm install ffmpeg-static` or see [WikiHow](https://www.wikihow.com/Install-FFmpeg-on-Windows). - -## How do I set up @discordjs/opus? - -- **Ubuntu:** Simply run `npm install @discordjs/opus`, and it's done. Congrats! -- **Windows:** Run `npm install --global --production windows-build-tools` in an admin command prompt or PowerShell. - Then, running `npm install @discordjs/opus` in your bot's directory should successfully build it. Woo! - -Other questions can be found at the [official Discord.js guide](https://discordjs.guide/popular-topics/faq.html) -If you have issues not listed here or on the guide, feel free to ask in the [official Discord.js server](https://discord.gg/djs). -Always make sure to read the [documentation](https://discord.js.org/#/docs/main/stable/general/welcome). diff --git a/docs/general/welcome.md b/docs/general/welcome.md deleted file mode 100644 index 6a4f47bad..000000000 --- a/docs/general/welcome.md +++ /dev/null @@ -1,103 +0,0 @@ -
-
-

- -

-
-

- Discord server - NPM version - NPM downloads - Build status - Dependencies - Patreon -

-

- NPM info -

-
- -# Welcome! - -Welcome to the discord.js v13 documentation. - -## About - -discord.js is a powerful [Node.js](https://nodejs.org) module that allows you to easily interact with the -[Discord API](https://discord.com/developers/docs/intro). - -- Object-oriented -- Predictable abstractions -- Performant -- 100% coverage of the Discord API - -## Installation - -**Node.js 14.0.0 or newer is required.** -Ignore any warnings about unmet peer dependencies, as they're all optional. - -Without voice support: `npm install discord.js` -With voice support ([@discordjs/opus](https://www.npmjs.com/package/@discordjs/opus)): `npm install discord.js @discordjs/opus` -With voice support ([opusscript](https://www.npmjs.com/package/opusscript)): `npm install discord.js opusscript` - -### Audio engines - -The preferred audio engine is @discordjs/opus, as it performs significantly better than opusscript. When both are available, discord.js will automatically choose @discordjs/opus. -Using opusscript is only recommended for development environments where @discordjs/opus is tough to get working. -For production bots, using @discordjs/opus should be considered a necessity, especially if they're going to be running on multiple servers. - -### Optional packages - -- [zlib-sync](https://www.npmjs.com/package/zlib-sync) for WebSocket data compression and inflation (`npm install zlib-sync`) -- [erlpack](https://github.com/discord/erlpack) for significantly faster WebSocket data (de)serialisation (`npm install discord/erlpack`) -- One of the following packages can be installed for faster voice packet encryption and decryption: - - [sodium](https://www.npmjs.com/package/sodium) (`npm install sodium`) - - [libsodium.js](https://www.npmjs.com/package/libsodium-wrappers) (`npm install libsodium-wrappers`) -- [bufferutil](https://www.npmjs.com/package/bufferutil) for a much faster WebSocket connection (`npm install bufferutil`) -- [utf-8-validate](https://www.npmjs.com/package/utf-8-validate) in combination with `bufferutil` for much faster WebSocket processing (`npm install utf-8-validate`) - -## Example usage - -```js -const { Client, Intents } = require('discord.js'); -const client = new Client({ intents: [Intents.FLAGS.GUILDS, Intents.FLAGS.GUILD_MESSAGES] }); - -client.on('ready', () => { - console.log(`Logged in as ${client.user.tag}!`); -}); - -client.on('message', msg => { - if (msg.content === 'ping') { - msg.channel.send('pong'); - } -}); - -client.login('token'); -``` - -## Links - -- [Website](https://discord.js.org/) ([source](https://github.com/discordjs/website)) -- [Documentation](https://discord.js.org/#/docs/main/master/general/welcome) -- [Guide](https://discordjs.guide/) ([source](https://github.com/discordjs/guide)) - this is still for stable - See also the WIP [Update Guide](https://discordjs.guide/additional-info/changes-in-v12.html) also including updated and removed items in the library. -- [Discord.js Discord server](https://discord.gg/djs) -- [Discord API Discord server](https://discord.gg/discord-api) -- [GitHub](https://github.com/discordjs/discord.js) -- [NPM](https://www.npmjs.com/package/discord.js) -- [Related libraries](https://discordapi.com/unofficial/libs.html) - -### Extensions - -- [RPC](https://www.npmjs.com/package/discord-rpc) ([source](https://github.com/discordjs/RPC)) - -## Contributing - -Before creating an issue, please ensure that it hasn't already been reported/suggested, and double-check the -[documentation](https://discord.js.org/#/docs). -See [the contribution guide](https://github.com/discordjs/discord.js/blob/master/.github/CONTRIBUTING.md) if you'd like to submit a PR. - -## Help - -If you don't understand something in the documentation, you are experiencing problems, or you just need a gentle -nudge in the right direction, please don't hesitate to join our official [Discord.js Server](https://discord.gg/djs). diff --git a/docs/index.yml b/docs/index.yml index 76734940c..2c993519e 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -1,12 +1,5 @@ - name: General files: - name: Welcome - path: welcome.md - - name: FAQ - path: faq.md -- name: Topics - files: - - name: Voice - path: voice.md - - name: Partials - path: partials.md + id: welcome + path: ../../README.md diff --git a/docs/topics/partials.md b/docs/topics/partials.md deleted file mode 100644 index 4b58f4356..000000000 --- a/docs/topics/partials.md +++ /dev/null @@ -1,65 +0,0 @@ -# Partials - -Partials allow you to receive events that contain uncached instances, providing structures that contain very minimal -data. For example, if you were to receive a `messageDelete` event with an uncached message, normally Discord.js would -discard the event. With partials, you're able to receive the event, with a Message object that contains just an ID. - -## Opting in - -Partials are opt-in, and you can enable them in the Client options by specifying [PartialTypes](/#/docs/main/master/typedef/PartialType): - -```js -// Accept partial messages, DM channels, and reactions when emitting events -new Client({ partials: ['MESSAGE', 'CHANNEL', 'REACTION'] }); -``` - -## Usage & warnings - -The only guaranteed data a partial structure can store is its ID. All other properties/methods should be -considered invalid/defunct while accessing a partial structure. - -After opting-in with the above, you begin to allow partial messages and channels in your caches, so it's important -to check whether they're safe to access whenever you encounter them, whether it be in events or through normal cache -usage. - -All instance of structures that you opted-in for will have a `partial` property. As you'd expect, this value is `true` -when the instance is partial. Partial structures are only guaranteed to contain an ID, any other properties and methods -no longer carry their normal type guarantees. - -This means you have to take time to consider possible parts of your program that might need checks put in place to -prevent accessing partial data: - -```js -client.on('messageDelete', message => { - console.log(`${message.id} was deleted!`); - // Partial messages do not contain any content so skip them - if (!message.partial) { - console.log(`It had content: "${message.content}"`); - } -}); - -// You can also try to upgrade partials to full instances: -client.on('messageReactionAdd', async (reaction, user) => { - // If a message gains a reaction and it is uncached, fetch and cache the message - // You should account for any errors while fetching, it could return API errors if the resource is missing - if (reaction.message.partial) await reaction.message.fetch(); - // Now the message has been cached and is fully available: - console.log(`${reaction.message.author}'s message "${reaction.message.content}" gained a reaction!`); - // Fetches and caches the reaction itself, updating resources that were possibly defunct. - if (reaction.partial) await reaction.fetch(); - // Now the reaction is fully available and the properties will be reflected accurately: - console.log(`${reaction.count} user(s) have given the same reaction to this message!`); -}); -``` - -If a message is deleted and both the message and channel are uncached, you must enable both 'MESSAGE' and -'CHANNEL' in the client options to receive the messageDelete event. - -## Why? - -This allows developers to listen to events that contain uncached data, which is useful if you're running a moderation -bot or any bot that relies on still receiving updates to resources you don't have cached -- message reactions are a -good example. - -Currently, the only type of channel that can be uncached is a DM channel, there is no reason why guild channels should -not be cached. diff --git a/docs/topics/voice.md b/docs/topics/voice.md deleted file mode 100644 index a15497bd1..000000000 --- a/docs/topics/voice.md +++ /dev/null @@ -1,140 +0,0 @@ -# Introduction to Voice - -Voice in discord.js can be used for many things, such as music bots, recording or relaying audio. - -In discord.js, you can use voice by connecting to a `VoiceChannel` to obtain a `VoiceConnection`, where you can start streaming and receiving audio. - -To get started, make sure you have: - -- FFmpeg - `npm install ffmpeg-static` -- an opus encoder, choose one from below: - - `npm install @discordjs/opus` (better performance) - - `npm install opusscript` -- a good network connection - -The preferred opus engine is @discordjs/opus, as it performs significantly better than opusscript. When both are available, discord.js will automatically choose @discordjs/opus. -Using opusscript is only recommended for development environments where @discordjs/opus is tough to get working. -For production bots, using @discordjs/opus should be considered a necessity, especially if they're going to be running on multiple servers. - -## Joining a voice channel - -The example below reacts to a message and joins the sender's voice channel, catching any errors. This is important -as it allows us to obtain a `VoiceConnection` that we can start to stream audio with. - -```js -const { Client, Intents } = require('discord.js'); -const client = new Client({ intents: [Intents.FLAGS.GUILDS, Intents.FLAGS.GUILD_MESSAGES, Intents.FLAGS.GUILD_VOICE_STATES] }); - -client.login('token here'); - -client.on('message', async message => { - // Voice only works in guilds, if the message does not come from a guild, - // we ignore it - if (!message.guild) return; - - if (message.content === '/join') { - // Only try to join the sender's voice channel if they are in one themselves - if (message.member.voice.channel) { - const connection = await message.member.voice.channel.join(); - } else { - message.channel.send('You need to join a voice channel first!'); - } - } -}); -``` - -## Streaming to a Voice Channel - -In the previous example, we looked at how to join a voice channel in order to obtain a `VoiceConnection`. Now that we -have obtained a voice connection, we can start streaming audio to it. - -### Introduction to playing on voice connections - -The most basic example of playing audio over a connection would be playing a local file: - -```js -const dispatcher = connection.play('/home/discord/audio.mp3'); -``` - -The `dispatcher` in this case is a `StreamDispatcher` - here you can control the volume and playback of the stream: - -```js -dispatcher.pause(); -dispatcher.resume(); - -dispatcher.setVolume(0.5); // half the volume - -dispatcher.on('finish', () => { - console.log('Finished playing!'); -}); - -dispatcher.destroy(); // end the stream -``` - -We can also pass in options when we first play the stream: - -```js -const dispatcher = connection.play('/home/discord/audio.mp3', { - volume: 0.5, -}); -``` - -### What can I play? - -Discord.js allows you to play a lot of things: - -```js -// ReadableStreams, in this example YouTube audio -const ytdl = require('ytdl-core'); -connection.play(ytdl('https://www.youtube.com/watch?v=ZlAU_w7-Xp8', { filter: 'audioonly' })); - -// Files on the internet -connection.play('http://www.sample-videos.com/audio/mp3/wave.mp3'); - -// Local files -connection.play('/home/discord/audio.mp3'); -``` - -New to v12 is the ability to play OggOpus and WebmOpus streams with much better performance by skipping out Ffmpeg. Note this comes at the cost of no longer having volume control over the stream: - -```js -connection.play(fs.createReadStream('./media.webm'), { - type: 'webm/opus', -}); - -connection.play(fs.createReadStream('./media.ogg'), { - type: 'ogg/opus', -}); -``` - -Make sure to consult the documentation for a full list of what you can play - there's too much to cover here! - -## Voice Broadcasts - -A voice broadcast is very useful for "radio" bots, that play the same audio across multiple channels. It means audio is only transcoded once, and is much better on performance. - -```js -const broadcast = client.voice.createBroadcast(); - -broadcast.on('subscribe', dispatcher => { - console.log('New broadcast subscriber!'); -}); - -broadcast.on('unsubscribe', dispatcher => { - console.log('Channel unsubscribed from broadcast :('); -}); -``` - -`broadcast` is an instance of `VoiceBroadcast`, which has the same `play` method you are used to with regular VoiceConnections: - -```js -const dispatcher = broadcast.play('./audio.mp3'); - -connection.play(broadcast); -``` - -It's important to note that the `dispatcher` stored above is a `BroadcastDispatcher` - it controls all the dispatcher subscribed to the broadcast, e.g. setting the volume of this dispatcher affects the volume of all subscribers. - -## Voice Receive - -coming soon™ diff --git a/src/client/Client.js b/src/client/Client.js index 7e291ef78..c2d6148fe 100644 --- a/src/client/Client.js +++ b/src/client/Client.js @@ -247,7 +247,7 @@ class Client extends BaseClient { * @param {InviteResolvable} invite Invite code or URL * @returns {Promise} * @example - * client.fetchInvite('https://discord.gg/bRCvFy9') + * client.fetchInvite('https://discord.gg/djs') * .then(invite => console.log(`Obtained invite with code: ${invite.code}`)) * .catch(console.error); */