discordjs/discord.js
2
0
Fork 0
mirror of https://github.com/discordjs/discord.js.git synced 2024-07-16 01:27:37 +12:00
Code Issues Packages Projects Releases Wiki Activity

docs: removed topics and FAQ from the repository (#5820)

Browse source 
Co-authored-by: SpaceEEC <spaceeec@yahoo.com>
Co-authored-by: Vlad Frangu <kingdgrizzle@gmail.com>
Co-authored-by: ckohen <chaikohen@gmail.com>
This commit is contained in:
Antonio Román 2021-06-12 00:41:49 +02:00 committed by GitHub
parent 24e5868818
commit 9e5106d90e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
11 changed files with 14 additions and 371 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/CODE_OF_CONDUCT.md vendored
View file

@ -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.

9
.github/CONTRIBUTING.md vendored
View file

@ -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))

2
.github/ISSUE_TEMPLATE/bug_report.md vendored
View file

@ -6,7 +6,7 @@ title: ''
labels: 's: unverified, type: bug'
assignees: ''
---
<!-- Use Discord for questions: https://discord.gg/bRCvFy9 -->
<!-- Use Discord for questions: https://discord.gg/djs -->
<!-- If you are reporting a voice issue, please post your issue at https://github.com/discordjs/voice/issues -->
**Please describe the problem you are having in as much detail as possible:**

2
.github/ISSUE_TEMPLATE/feature_request.md vendored
View file

@ -6,7 +6,7 @@ title: ''
labels: 'type: enhancement'
assignees: ''
---
<!-- Use Discord for questions: https://discord.gg/bRCvFy9 -->
<!-- Use Discord for questions: https://discord.gg/djs -->
**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 [...]

23
README.md
View file

@ -12,23 +12,8 @@
<a href="https://david-dm.org/discordjs/discord.js"><img src="https://img.shields.io/david/discordjs/discord.js.svg?maxAge=3600" alt="Dependencies" /></a>
<a href="https://www.patreon.com/discordjs"><img src="https://img.shields.io/badge/donate-patreon-F96854.svg" alt="Patreon" /></a>
</p>
<p>
<a href="https://nodei.co/npm/discord.js/"><img src="https://nodei.co/npm/discord.js.png?downloads=true&stars=true" alt="npm installnfo" /></a>
</p>
</div>
## 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

26
docs/general/faq.md
View file

@ -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).

103
docs/general/welcome.md
View file

@ -1,103 +0,0 @@
<div align="center">
<br />
<p>
<a href="https://discord.js.org"><img src="/static/logo.svg" width="546" alt="discord.js" id="djs-logo" /></a>
</p>
<br />
<p>
<a href="https://discord.gg/djs"><img src="https://img.shields.io/discord/222078108977594368?color=7289da&logo=discord&logoColor=white" alt="Discord server" /></a>
<a href="https://www.npmjs.com/package/discord.js"><img src="https://img.shields.io/npm/v/discord.js.svg?maxAge=3600" alt="NPM version" /></a>
<a href="https://www.npmjs.com/package/discord.js"><img src="https://img.shields.io/npm/dt/discord.js.svg?maxAge=3600" alt="NPM downloads" /></a>
<a href="https://travis-ci.org/discordjs/discord.js"><img src="https://travis-ci.org/discordjs/discord.js.svg" alt="Build status" /></a>
<a href="https://david-dm.org/discordjs/discord.js"><img src="https://img.shields.io/david/discordjs/discord.js.svg?maxAge=3600" alt="Dependencies" /></a>
<a href="https://www.patreon.com/discordjs"><img src="https://img.shields.io/badge/donate-patreon-F96854.svg" alt="Patreon" /></a>
</p>
<p>
<a href="https://nodei.co/npm/discord.js/"><img src="https://nodei.co/npm/discord.js.png?downloads=true&stars=true" alt="NPM info" /></a>
</p>
</div>
# 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).

11
docs/index.yml
View file

@ -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

65
docs/topics/partials.md
View file

@ -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
<warn>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.</warn>
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!`);
});
```
<info>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.</info>
## 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.

140
docs/topics/voice.md
View file

@ -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&trade;

2
src/client/Client.js
View file

@ -247,7 +247,7 @@ class Client extends BaseClient {
* @param {InviteResolvable} invite Invite code or URL
* @returns {Promise<Invite>}
* @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);
*/