From 801588b2d4c855ceee8ebe7919d07f4a01ee77f2 Mon Sep 17 00:00:00 2001 From: Schuyler Cebulskie Date: Wed, 26 Oct 2016 20:39:11 -0400 Subject: [PATCH 1/5] Add v10 details to docs --- README.md | 2 +- docs/custom/documents/faq.md | 9 +-- docs/custom/documents/updating.md | 94 ++++++++++++++++++++++++++++++- docs/custom/documents/welcome.md | 14 ++--- 4 files changed, 102 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index fb6b0ebd8..bbd4aabd4 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ [![NPM](https://nodei.co/npm/discord.js.png?downloads=true&stars=true)](https://nodei.co/npm/discord.js/) -discord.js is a powerful node.js module that allows you to interact with the [Discord API](https://discordapp.com/developers/docs/intro). +discord.js is a powerful node.js module that allows you to interact with the [Discord API](https://discordapp.com/developers/docs/intro) very easily. ## Installation **Node.js 6.0.0 or newer is required.** diff --git a/docs/custom/documents/faq.md b/docs/custom/documents/faq.md index 21a838061..82a94f656 100644 --- a/docs/custom/documents/faq.md +++ b/docs/custom/documents/faq.md @@ -6,13 +6,10 @@ Always make sure to read the documentation. ## No matter what, I get `SyntaxError: Block-scoped declarations (let, const, function, class) not yet supported outside strict mode`‽ Update to Node.js 6.0.0 or newer. -## I get an absurd amount of errors when installing discord.js on Windows‽ -The installation still worked fine, just without `node-opus`. -If you don't need voice support, using `npm install discord.js --no-optional` will prevent these errors. - ## How do I get voice working? - Install FFMPEG. -- Optionally, set up `node-opus`, which is much faster than the default `opusscript`. +- Install either the `node-opus` package or the `opusscript` package. + node-opus is greatly preferred, but is tougher to get working on Windows. ## How do I install FFMPEG? - **Ubuntu 16.04:** `sudo apt install ffpmeg` @@ -20,5 +17,5 @@ If you don't need voice support, using `npm install discord.js --no-optional` wi - **Windows:** See the [FFMPEG section of AoDude's guide](https://github.com/bdistin/OhGodMusicBot/blob/master/README.md#download-ffmpeg). ## How do I set up node-opus? -- **Ubuntu:** It's already done when you run `npm install discord.js` without `--no-optional`. Congrats! +- **Ubuntu:** Simply run `npm install node-opus`, and it's done. Congrats! - **Windows:** See [AoDude's guide](https://github.com/bdistin/OhGodMusicBot/blob/master/README.md). Good luck. diff --git a/docs/custom/documents/updating.md b/docs/custom/documents/updating.md index 451ba9380..9efe1c8f8 100644 --- a/docs/custom/documents/updating.md +++ b/docs/custom/documents/updating.md @@ -1,10 +1,98 @@ -# About Version 9 +# Version 10 +Version 10's non-BC changes focus on cleaning up some inconsistencies that exist in previous versions. +Upgrading from v9 should be quick and painless. + +## Client options +All client options have been converted to camelCase rather than snake_case, and `max_message_cache` was renamed to `messageCacheMaxSize`. + +v9 code example: +```js +const client = new Discord.Client({ + disable_everyone: true, + max_message_cache: 500, + message_cache_lifetime: 120, + message_sweep_interval: 60 +}); +``` + +v10 code example: +```js +const client = new Discord.Client({ + disableEveryone: true, + messageCacheMaxSize: 500, + messageCacheLifetime: 120, + messageSweepInterval: 60 +}); +``` + +## Presences +Presences have been completely restructured. +Previous versions of discord.js assumed that users had the same presence amongst all guilds - with the introduction of sharding, however, this is no longer the case. + +v9 discord.js code may look something like this: +```js +User.status; // the status of the user +User.game; // the game that the user is playing +ClientUser.setStatus(status, game, url); // set the new status for the user +``` + +v10 moves presences to GuildMember instances. For the sake of simplicity, though, User classes also expose presences. +When accessing a presence on a User object, it simply finds the first GuildMember for the user, and uses its presence. +Additionally, the introduction of the Presence class keeps all of the presence data organised. + +**It is strongly recommended that you use a GuildMember's presence where available, rather than a User. +A user may have an entirely different presence between two different guilds.** + +v10 code: +```js +MemberOrUser.presence.status; // the status of the member or user +MemberOrUser.presence.game; // the game that the member or user is playing +ClientUser.setStatus(status); // online, idle, dnd, offline +ClientUser.setGame(game, streamingURL); // a game +ClientUser.setPresence(fullPresence); // status and game combined +``` + +## Voice +Voice has been rewritten internally, but in a backwards-compatible manner. +There is only one breaking change here; the `disconnected` event was renamed to `disconnect`. +Several more events have been made available to a VoiceConnection, so see the documentation. + +## Events +Many events have been renamed or had their arguments change. + +### Client events +| Version 9 | Version 10 | +|------------------------------------------------------|-----------------------------------------------| +| guildMemberAdd(guild, member) | guildMemberAdd(member) | +| guildMemberAvailable(guild, member) | guildMemberAvailable(member) | +| guildMemberRemove(guild, member) | guildMemberRemove(member) | +| guildMembersChunk(guild, members) | guildMembersChunk(members) | +| guildMemberUpdate(guild, oldMember, newMember) | guildMemberUpdate(oldMember, newMember) | +| guildRoleCreate(guild, role) | roleCreate(role) | +| guildRoleDelete(guild, role) | roleDelete(role) | +| guildRoleUpdate(guild, oldRole, newRole) | roleUpdate(oldRole, newRole) | + +The guild parameter that has been dropped from the guild-related events can still be derived using `member.guild` or `role.guild`. + +### VoiceConnection events +| Version 9 | Version 10 | +|--------------|------------| +| disconnected | disconnect | + +## Dates and timestamps +All dates/timestamps on the structures have been refactored to have a consistent naming scheme and availability. +All of them are named similarly to this: +**Date:** `Message.createdAt` +**Timestamp:** `Message.createdTimestamp` +See the docs for each structure to see which date/timestamps are available on them. + + +# Version 9 The version 9 (v9) rewrite takes a much more object-oriented approach than previous versions, which allows your code to be much more readable and manageable. It's been rebuilt from the ground up and should be much more stable, fixing caching issues that affected older versions. It also has support for newer Discord Features, such as emojis. -## Upgrading your code Version 9, while containing a sizable number of breaking changes, does not require much change in your code's logic - most of the concepts are still the same, but loads of functions have been moved around. The vast majority of methods you're used to using have been moved out of the Client class, @@ -23,7 +111,7 @@ A couple more important details: * `Client.loginWithToken("token")` ==> `client.login("token")` * `Client.servers.length` ==> `client.guilds.size` (all instances of `server` are now `guild`) -## Callbacks +## No more callbacks! Version 9 eschews callbacks in favour of Promises. This means all code relying on callbacks must be changed. For example, the following code: diff --git a/docs/custom/documents/welcome.md b/docs/custom/documents/welcome.md index d2b50758c..39fd45a62 100644 --- a/docs/custom/documents/welcome.md +++ b/docs/custom/documents/welcome.md @@ -1,22 +1,22 @@

- discord.js
+ discord.js

[![Discord](https://discordapp.com/api/guilds/222078108977594368/embed.png)](https://discord.gg/bRCvFy9) -[![npm](https://img.shields.io/npm/v/discord.js.svg?maxAge=2592000)](https://www.npmjs.com/package/discord.js) -[![npm](https://img.shields.io/npm/dt/discord.js.svg?maxAge=2592000)](https://www.npmjs.com/package/discord.js) +[![npm](https://img.shields.io/npm/v/discord.js.svg?maxAge=3600)](https://www.npmjs.com/package/discord.js) +[![npm](https://img.shields.io/npm/dt/discord.js.svg?maxAge=3600)](https://www.npmjs.com/package/discord.js) [![Build Status](https://travis-ci.org/hydrabolt/discord.js.svg)](https://travis-ci.org/hydrabolt/discord.js) -[![David](https://img.shields.io/david/hydrabolt/discord.js.svg?maxAge=2592000)](https://david-dm.org/hydrabolt/discord.js) +[![David](https://img.shields.io/david/hydrabolt/discord.js.svg?maxAge=3600)](https://david-dm.org/hydrabolt/discord.js) [![NPM](https://nodei.co/npm/discord.js.png?downloads=true&stars=true)](https://nodei.co/npm/discord.js/) -discord.js is a powerful node.js module that allows you to interact with the [Discord API](https://discordapp.com/developers/docs/intro). +discord.js is a powerful node.js module that allows you to interact with the [Discord API](https://discordapp.com/developers/docs/intro) very easily. # Welcome! -Welcome to the discord.js v9 documentation. The v9 rewrite has taken a lot of time, but it should be much more -stable and performant than previous versions. +Welcome to the discord.js v10 documentation. +v10 is just a more consistent and stable iteration over v9, and contains loads of new/improved features, optimisations, and bug fixes. ## Installation **Node.js 6.0.0 or newer is required.** From 6dfb904e6b5dc45ebbacd179126af9837d7d8460 Mon Sep 17 00:00:00 2001 From: Schuyler Cebulskie Date: Wed, 26 Oct 2016 20:45:48 -0400 Subject: [PATCH 2/5] Center the shields and NPM banner --- README.md | 29 ++++++++++++++++------------- docs/custom/documents/welcome.md | 29 ++++++++++++++++------------- 2 files changed, 32 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index bbd4aabd4..82d72a592 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,19 @@ -

- - discord.js
- -

- -[![Discord](https://discordapp.com/api/guilds/222078108977594368/embed.png)](https://discord.gg/bRCvFy9) -[![npm](https://img.shields.io/npm/v/discord.js.svg?maxAge=3600)](https://www.npmjs.com/package/discord.js) -[![npm](https://img.shields.io/npm/dt/discord.js.svg?maxAge=3600)](https://www.npmjs.com/package/discord.js) -[![Build Status](https://travis-ci.org/hydrabolt/discord.js.svg)](https://travis-ci.org/hydrabolt/discord.js) -[![David](https://img.shields.io/david/hydrabolt/discord.js.svg?maxAge=3600)](https://david-dm.org/hydrabolt/discord.js) - -[![NPM](https://nodei.co/npm/discord.js.png?downloads=true&stars=true)](https://nodei.co/npm/discord.js/) +
+

+ + discord.js + +

+

+ [![Discord](https://discordapp.com/api/guilds/222078108977594368/embed.png)](https://discord.gg/bRCvFy9) + [![npm](https://img.shields.io/npm/v/discord.js.svg?maxAge=3600)](https://www.npmjs.com/package/discord.js) + [![npm](https://img.shields.io/npm/dt/discord.js.svg?maxAge=3600)](https://www.npmjs.com/package/discord.js) + [![Build Status](https://travis-ci.org/hydrabolt/discord.js.svg)](https://travis-ci.org/hydrabolt/discord.js) + [![David](https://img.shields.io/david/hydrabolt/discord.js.svg?maxAge=3600)](https://david-dm.org/hydrabolt/discord.js) +

+

[![NPM](https://nodei.co/npm/discord.js.png?downloads=true&stars=true)](https://nodei.co/npm/discord.js/)

+
+
discord.js is a powerful node.js module that allows you to interact with the [Discord API](https://discordapp.com/developers/docs/intro) very easily. diff --git a/docs/custom/documents/welcome.md b/docs/custom/documents/welcome.md index 39fd45a62..cf0426b32 100644 --- a/docs/custom/documents/welcome.md +++ b/docs/custom/documents/welcome.md @@ -1,16 +1,19 @@ -

- - discord.js
- -

- -[![Discord](https://discordapp.com/api/guilds/222078108977594368/embed.png)](https://discord.gg/bRCvFy9) -[![npm](https://img.shields.io/npm/v/discord.js.svg?maxAge=3600)](https://www.npmjs.com/package/discord.js) -[![npm](https://img.shields.io/npm/dt/discord.js.svg?maxAge=3600)](https://www.npmjs.com/package/discord.js) -[![Build Status](https://travis-ci.org/hydrabolt/discord.js.svg)](https://travis-ci.org/hydrabolt/discord.js) -[![David](https://img.shields.io/david/hydrabolt/discord.js.svg?maxAge=3600)](https://david-dm.org/hydrabolt/discord.js) - -[![NPM](https://nodei.co/npm/discord.js.png?downloads=true&stars=true)](https://nodei.co/npm/discord.js/) +
+

+ + discord.js + +

+

+ [![Discord](https://discordapp.com/api/guilds/222078108977594368/embed.png)](https://discord.gg/bRCvFy9) + [![npm](https://img.shields.io/npm/v/discord.js.svg?maxAge=3600)](https://www.npmjs.com/package/discord.js) + [![npm](https://img.shields.io/npm/dt/discord.js.svg?maxAge=3600)](https://www.npmjs.com/package/discord.js) + [![Build Status](https://travis-ci.org/hydrabolt/discord.js.svg)](https://travis-ci.org/hydrabolt/discord.js) + [![David](https://img.shields.io/david/hydrabolt/discord.js.svg?maxAge=3600)](https://david-dm.org/hydrabolt/discord.js) +

+

[![NPM](https://nodei.co/npm/discord.js.png?downloads=true&stars=true)](https://nodei.co/npm/discord.js/)

+
+
discord.js is a powerful node.js module that allows you to interact with the [Discord API](https://discordapp.com/developers/docs/intro) very easily. From c4ee802c3b047e344755c7536acd3cd94a6928b9 Mon Sep 17 00:00:00 2001 From: Schuyler Cebulskie Date: Wed, 26 Oct 2016 20:51:34 -0400 Subject: [PATCH 3/5] Fix formatting for GitHub --- README.md | 26 ++++++++++++++++++++------ docs/custom/documents/welcome.md | 26 ++++++++++++++++++++------ 2 files changed, 40 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 82d72a592..23b30ede2 100644 --- a/README.md +++ b/README.md @@ -5,13 +5,27 @@

- [![Discord](https://discordapp.com/api/guilds/222078108977594368/embed.png)](https://discord.gg/bRCvFy9) - [![npm](https://img.shields.io/npm/v/discord.js.svg?maxAge=3600)](https://www.npmjs.com/package/discord.js) - [![npm](https://img.shields.io/npm/dt/discord.js.svg?maxAge=3600)](https://www.npmjs.com/package/discord.js) - [![Build Status](https://travis-ci.org/hydrabolt/discord.js.svg)](https://travis-ci.org/hydrabolt/discord.js) - [![David](https://img.shields.io/david/hydrabolt/discord.js.svg?maxAge=3600)](https://david-dm.org/hydrabolt/discord.js) + + Discord server + + + NPM version + + + NPM downloads + + + Build status + + + Dependencies + +

+

+ + NPM info +

-

[![NPM](https://nodei.co/npm/discord.js.png?downloads=true&stars=true)](https://nodei.co/npm/discord.js/)


diff --git a/docs/custom/documents/welcome.md b/docs/custom/documents/welcome.md index cf0426b32..c12a9f9fc 100644 --- a/docs/custom/documents/welcome.md +++ b/docs/custom/documents/welcome.md @@ -5,13 +5,27 @@

- [![Discord](https://discordapp.com/api/guilds/222078108977594368/embed.png)](https://discord.gg/bRCvFy9) - [![npm](https://img.shields.io/npm/v/discord.js.svg?maxAge=3600)](https://www.npmjs.com/package/discord.js) - [![npm](https://img.shields.io/npm/dt/discord.js.svg?maxAge=3600)](https://www.npmjs.com/package/discord.js) - [![Build Status](https://travis-ci.org/hydrabolt/discord.js.svg)](https://travis-ci.org/hydrabolt/discord.js) - [![David](https://img.shields.io/david/hydrabolt/discord.js.svg?maxAge=3600)](https://david-dm.org/hydrabolt/discord.js) + + Discord server + + + NPM version + + + NPM downloads + + + Build status + + + Dependencies + +

+

+ + NPM info +

-

[![NPM](https://nodei.co/npm/discord.js.png?downloads=true&stars=true)](https://nodei.co/npm/discord.js/)


From e8eac4990e1dddf65189b9106b5c31e5e1cfaeff Mon Sep 17 00:00:00 2001 From: Schuyler Cebulskie Date: Wed, 26 Oct 2016 21:03:44 -0400 Subject: [PATCH 4/5] Add more general info about discord.js --- README.md | 11 +++++++---- docs/custom/documents/welcome.md | 17 ++++++++++------- 2 files changed, 17 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 23b30ede2..dc9b62c09 100644 --- a/README.md +++ b/README.md @@ -29,16 +29,19 @@
+## About discord.js is a powerful node.js module that allows you to interact with the [Discord API](https://discordapp.com/developers/docs/intro) very easily. +It takes a much more object-oriented approach than most other JS Discord libraries, making your bot's code much tidier and easier to comprehend. +Usability and performance are key focuses of discord.js. It also has nearly 100% coverage of the Discord API. ## Installation -**Node.js 6.0.0 or newer is required.** +**Node.js 6.0.0 or newer is required.** + Without voice support: `npm install discord.js --save` With voice support ([node-opus](https://www.npmjs.com/package/node-opus)): `npm install discord.js node-opus --save` -With voice support ([opusscript](https://www.npmjs.com/package/opusscript)): `npm install discord.js opusscript --save` -If both audio packages are installed, discord.js will automatically choose node-opus. +With voice support ([opusscript](https://www.npmjs.com/package/opusscript)): `npm install discord.js opusscript --save` -The preferred audio engine is node-opus, as it performs significantly better than opusscript. +The preferred audio engine is node-opus, as it performs significantly better than opusscript. When both are available, discord.js will automatically choose node-opus. Using opusscript is only recommended for development on Windows, since getting node-opus to build there can be a bit of a challenge. For production bots, using node-opus should be considered a necessity, especially if they're going to be running on multiple servers. diff --git a/docs/custom/documents/welcome.md b/docs/custom/documents/welcome.md index c12a9f9fc..a946cfdbb 100644 --- a/docs/custom/documents/welcome.md +++ b/docs/custom/documents/welcome.md @@ -29,20 +29,23 @@
-discord.js is a powerful node.js module that allows you to interact with the [Discord API](https://discordapp.com/developers/docs/intro) very easily. - # Welcome! Welcome to the discord.js v10 documentation. -v10 is just a more consistent and stable iteration over v9, and contains loads of new/improved features, optimisations, and bug fixes. +v10 is just a more consistent and stable iteration over v9, and contains loads of new and improved features, optimisations, and bug fixes. + +## About +discord.js is a powerful node.js module that allows you to interact with the [Discord API](https://discordapp.com/developers/docs/intro) very easily. +It takes a much more object-oriented approach than most other JS Discord libraries, making your bot's code much tidier and easier to comprehend. +Usability and performance are key focuses of discord.js. It also has nearly 100% coverage of the Discord API. ## Installation -**Node.js 6.0.0 or newer is required.** +**Node.js 6.0.0 or newer is required.** + Without voice support: `npm install discord.js --save` With voice support ([node-opus](https://www.npmjs.com/package/node-opus)): `npm install discord.js node-opus --save` -With voice support ([opusscript](https://www.npmjs.com/package/opusscript)): `npm install discord.js opusscript --save` -If both audio packages are installed, discord.js will automatically prefer node-opus. +With voice support ([opusscript](https://www.npmjs.com/package/opusscript)): `npm install discord.js opusscript --save` -The preferred audio engine is node-opus, as it performs significantly better than opusscript. +The preferred audio engine is node-opus, as it performs significantly better than opusscript. When both are available, discord.js will automatically choose node-opus. Using opusscript is only recommended for development on Windows, since getting node-opus to build there can be a bit of a challenge. For production bots, using node-opus should be considered a necessity, especially if they're going to be running on multiple servers. From 99cea11e6d595e07c1ffcd52323f9fa3315e491d Mon Sep 17 00:00:00 2001 From: Schuyler Cebulskie Date: Wed, 26 Oct 2016 21:04:41 -0400 Subject: [PATCH 5/5] Change a word --- README.md | 2 +- docs/custom/documents/welcome.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dc9b62c09..98a1cfe41 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ ## About discord.js is a powerful node.js module that allows you to interact with the [Discord API](https://discordapp.com/developers/docs/intro) very easily. -It takes a much more object-oriented approach than most other JS Discord libraries, making your bot's code much tidier and easier to comprehend. +It takes a much more object-oriented approach than most other JS Discord libraries, making your bot's code significantly tidier and easier to comprehend. Usability and performance are key focuses of discord.js. It also has nearly 100% coverage of the Discord API. ## Installation diff --git a/docs/custom/documents/welcome.md b/docs/custom/documents/welcome.md index a946cfdbb..4fdc38117 100644 --- a/docs/custom/documents/welcome.md +++ b/docs/custom/documents/welcome.md @@ -35,7 +35,7 @@ v10 is just a more consistent and stable iteration over v9, and contains loads o ## About discord.js is a powerful node.js module that allows you to interact with the [Discord API](https://discordapp.com/developers/docs/intro) very easily. -It takes a much more object-oriented approach than most other JS Discord libraries, making your bot's code much tidier and easier to comprehend. +It takes a much more object-oriented approach than most other JS Discord libraries, making your bot's code significantly tidier and easier to comprehend. Usability and performance are key focuses of discord.js. It also has nearly 100% coverage of the Discord API. ## Installation