Developer Documentation has moved to https://docs.vencord.dev
Vendicated
5 months ago
parent
df32e8d305
commit
d61a930b99
@ -1,82 +1,55 @@
|
|||||||
# Contribution Guide
|
# Contributing to Vencord
|
||||||
|
|
||||||
First of all, thank you for contributing! :3
|
Vencord is a community project and welcomes any kind of contribution from anyone!
|
||||||
|
|
||||||
To ensure your contribution is robust, please follow the below guide!
|
We have development documentation for new contributors, which can be found at <https://docs.vencord.dev>.
|
||||||
|
|
||||||
For a friendly introduction to plugins, see [Megu's Plugin Guide!](docs/2_PLUGINS.md)
|
All contributions should be made in accordance with our [Code of Conduct](./CODE_OF_CONDUCT.md).
|
||||||
|
|
||||||
## Style Guide
|
## How to contribute
|
||||||
|
|
||||||
- This project has a very minimal .editorconfig. Make sure your editor supports this!
|
Contributions can be sent via pull requests. If you're new to Git, check [this guide](https://opensource.com/article/19/7/create-pull-request-github).
|
||||||
If you are using VSCode, it should automatically recommend you the extension; If not,
|
|
||||||
please install the Editorconfig extension
|
|
||||||
- Try to follow the formatting in the rest of the project and stay consistent
|
|
||||||
- Follow the file naming convention. File names should usually be camelCase, unless they export a Class
|
|
||||||
or React Component, in which case they should be PascalCase
|
|
||||||
|
|
||||||
## Contributing a Plugin
|
Pull requests can be made either to the `main` or the `dev` branch. However, unless you're an advanced user, I recommend sticking to `main`. This is because the dev branch might contain unstable changes and be force pushed frequently, which could cause conflicts in your pull request.
|
||||||
|
|
||||||
Because plugins modify code directly, incompatibilities are a problem.
|
## Write a plugin
|
||||||
|
|
||||||
Thus, 3rd party plugins are not supported, instead all plugins are part of Vencord itself.
|
Writing a plugin is the primary way to contribute.
|
||||||
This way we can ensure compatibility and high quality patches.
|
|
||||||
|
|
||||||
Follow the below guide to make your first plugin!
|
Before starting your plugin:
|
||||||
|
- Check existing pull requests to see if someone is already working on a similar plugin
|
||||||
|
- Check our [plugin requests tracker](https://github.com/Vencord/plugin-requests/issues) to see if there is an existing request, or if the same idea has been rejected
|
||||||
|
- If there isn't an existing request, [open one](https://github.com/Vencord/plugin-requests/issues/new?assignees=&labels=&projects=&template=request.yml) yourself
|
||||||
|
and include that you'd like to work on this yourself. Then wait for feedback to see if the idea even has any chance of being accepted. Or maybe others have some ideas to improve it!
|
||||||
|
- Familarise yourself with our plugin rules below to ensure your plugin is not banned
|
||||||
|
|
||||||
### Finding the right module to patch
|
### Plugin Rules
|
||||||
|
|
||||||
If the thing you want to patch is an action performed when interacting with a part of the UI, use React DevTools.
|
- No simple slash command plugins like `/cat`. Instead, make a [user installable Discord bot](https://discord.com/developers/docs/change-log#userinstallable-apps-preview)
|
||||||
They come preinstalled and can be found as the "Components" tab in DevTools.
|
- No simple text replace plugins like Let me Google that for you. The TextReplace plugin can do this
|
||||||
Use the Selector (top left) to select the UI Element. Now you can see all callbacks, props or jump to the source
|
- No raw DOM manipulation. Use proper patches and React
|
||||||
directly.
|
- No FakeDeafen or FakeMute
|
||||||
|
- No StereoMic
|
||||||
|
- No plugins that simply hide or redesign ui elements. This can be done with CSS
|
||||||
|
- No selfbots or API spam (animated status, message pruner, auto reply, nitro snipers, etc)
|
||||||
|
- No untrusted third party APIs. Popular services like Google or GitHub are fine, but absolutely no self hosted ones
|
||||||
|
- No plugins that require the user to enter their own API key
|
||||||
|
- Do not introduce new dependencies unless absolutely necessary and warranted
|
||||||
|
|
||||||
If it is anything else, or you're too lazy to use React DevTools, hit `CTRL + Shift + F` while in DevTools and
|
## Improve Vencord itself
|
||||||
enter a search term, for example "getUser" to search all source files.
|
|
||||||
Look at the results until you find something promising. Set a breakpoint and trigger the execution of that part of Code to inspect arguments, locals, etc...
|
|
||||||
|
|
||||||
### Writing a robust patch
|
If you have any ideas on how to improve Vencord itself, or want to propose a new plugin API, feel free to open a feature request so we can discuss.
|
||||||
|
|
||||||
##### "find"
|
Or if you notice any bugs or typos, feel free to fix them!
|
||||||
|
|
||||||
First you need to find a good `find` value. This should be a string that is unique to your module.
|
## Contribute to our Documentation
|
||||||
If you want to patch the `getUser` function, usually a good first try is `getUser:` or `function getUser()`,
|
|
||||||
depending on how the module is structured. Again, make sure this string is unique to your module and is not
|
|
||||||
found in any other module. To verify this, search for it in all bundles (CTRL + Shift + F)
|
|
||||||
|
|
||||||
##### "match"
|
The source code of our documentation is available at <https://github.com/Vencord/Docs>
|
||||||
|
|
||||||
This is the regex that will operate on the module found with "find". Just like in find, you should make sure
|
If you see anything outdated, incorrect or lacking, please fix it!
|
||||||
this only matches exactly the part you want to patch and no other parts in the file.
|
If you think a new page should be added, feel free to suggest it via an issue and we can discuss.
|
||||||
|
|
||||||
The easiest way to write and test your regex is the following:
|
## Help out users in our Discord community
|
||||||
|
|
||||||
- Get the ID of the module you want to patch. To do this, go to it in the sources tab and scroll up until you
|
We have an open support channel in our [Discord community](https://vencord.dev/discord).
|
||||||
see something like `447887: (e,t,n)=>{` (Obviously the number will differ).
|
Helping out users there is always appreciated! The more, the merrier.
|
||||||
- Now paste the following into the console: `Vencord.Webpack.wreq.m[447887].toString()` (Changing the number to your ID)
|
|
||||||
- Now either test regexes on this string in the console or use a tool like https://regex101.com
|
|
||||||
|
|
||||||
Also pay attention to the following:
|
|
||||||
|
|
||||||
- Never hardcode variable or parameter names or any other minified names. They will change in the future. The only Exception to this rule
|
|
||||||
are the react props parameter which seems to always be `e`, but even then only rely on this if it is necessary.
|
|
||||||
Instead, use one of the following approaches where applicable:
|
|
||||||
- Match 1 or 2 of any character: `.{1,2}`, for example to match the variable name in `var a=b`, `var (.{1,2})=`
|
|
||||||
- Match any but a guaranteed terminating character: `[^;]+`, for example to match the entire assigned value in `var a=b||c||func();`,
|
|
||||||
`var .{1,2}=([^;]+);`
|
|
||||||
- If you don't care about that part, just match a bunch of chars: `.{0,50}`, for example to extract the variable "b" in `createElement("div",{a:"foo",c:"bar"},b)`, `createElement\("div".{0,30},(.{1,2})\),`. Note the `.{0,30}`, this is essentially the same as `.+`, but safer as you can't end up accidently eating thousands of characters
|
|
||||||
- Additionally, as you might have noticed, all of the above approaches use regex groups (`(...)`) to capture the variable name. You can then use those groups in your replacement to access those variables dynamically
|
|
||||||
|
|
||||||
#### "replace"
|
|
||||||
|
|
||||||
This is the replacement for the match. This is the second argument to [String.replace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace), so refer to those docs for info.
|
|
||||||
|
|
||||||
Never hardcode minified variable or parameter names here. Instead, use capture groups in your regex to capture the variable names
|
|
||||||
and use those in your replacement
|
|
||||||
|
|
||||||
Make sure your replacement does not introduce any whitespace. While this might seem weird, random whitespace may mess up other patches.
|
|
||||||
This includes spaces, tabs and especially newlines
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
And that's it! Now open a Pull Request with your Plugin
|
|
||||||
|
|||||||
@ -1,97 +0,0 @@
|
|||||||
> [!WARNING]
|
|
||||||
> These instructions are only for advanced users. If you're not a Developer, you should use our [graphical installer](https://github.com/Vendicated/VencordInstaller#usage) instead.
|
|
||||||
> No support will be provided for installing in this fashion. If you cannot figure it out, you should just stick to a regular install.
|
|
||||||
|
|
||||||
# Installation Guide
|
|
||||||
|
|
||||||
Welcome to Megu's Installation Guide! In this file, you will learn about how to download, install, and uninstall Vencord!
|
|
||||||
|
|
||||||
## Sections
|
|
||||||
|
|
||||||
- [Installation Guide](#installation-guide)
|
|
||||||
- [Sections](#sections)
|
|
||||||
- [Dependencies](#dependencies)
|
|
||||||
- [Installing Vencord](#installing-vencord)
|
|
||||||
- [Updating Vencord](#updating-vencord)
|
|
||||||
- [Uninstalling Vencord](#uninstalling-vencord)
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
- Install Git from https://git-scm.com/download
|
|
||||||
- Install Node.JS LTS from here: https://nodejs.dev/en/
|
|
||||||
|
|
||||||
## Installing Vencord
|
|
||||||
|
|
||||||
Install `pnpm`:
|
|
||||||
|
|
||||||
> :exclamation: This next command may need to be run as admin/root depending on your system, and you may need to close and reopen your terminal for pnpm to be in your PATH.
|
|
||||||
|
|
||||||
```shell
|
|
||||||
npm i -g pnpm
|
|
||||||
```
|
|
||||||
|
|
||||||
> :exclamation: **IMPORTANT** Make sure you aren't using an admin/root terminal from here onwards. It **will** mess up your Discord/Vencord instance and you **will** most likely have to reinstall.
|
|
||||||
|
|
||||||
Clone Vencord:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
git clone https://github.com/Vendicated/Vencord
|
|
||||||
cd Vencord
|
|
||||||
```
|
|
||||||
|
|
||||||
Install dependencies:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
pnpm install --frozen-lockfile
|
|
||||||
```
|
|
||||||
|
|
||||||
Build Vencord:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
pnpm build
|
|
||||||
```
|
|
||||||
|
|
||||||
Inject vencord into your client:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
pnpm inject
|
|
||||||
```
|
|
||||||
|
|
||||||
Then fully close Discord from your taskbar or task manager, and restart it. Vencord should be injected - you can check this by looking for the Vencord section in Discord settings.
|
|
||||||
|
|
||||||
## Updating Vencord
|
|
||||||
|
|
||||||
If you're using Discord already, go into the `Updater` tab in settings.
|
|
||||||
|
|
||||||
Sometimes it may be necessary to manually update if the GUI updater fails.
|
|
||||||
|
|
||||||
To pull latest changes:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
git pull
|
|
||||||
```
|
|
||||||
|
|
||||||
If this fails, you likely need to reset your local changes to vencord to resolve merge errors:
|
|
||||||
|
|
||||||
> :exclamation: This command will remove any local changes you've made to vencord. Make sure you back up if you made any code changes you don't want to lose!
|
|
||||||
|
|
||||||
```shell
|
|
||||||
git reset --hard
|
|
||||||
git pull
|
|
||||||
```
|
|
||||||
|
|
||||||
and then to build the changes:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
pnpm build
|
|
||||||
```
|
|
||||||
|
|
||||||
Then just refresh your client
|
|
||||||
|
|
||||||
## Uninstalling Vencord
|
|
||||||
|
|
||||||
Simply run:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
pnpm uninject
|
|
||||||
```
|
|
||||||
@ -1,111 +0,0 @@
|
|||||||
# Plugins Guide
|
|
||||||
|
|
||||||
Welcome to Megu's Plugin Guide! In this file, you will learn about how to write your own plugin!
|
|
||||||
|
|
||||||
You don't need to run `pnpm build` every time you make a change. Instead, use `pnpm watch` - this will auto-compile Vencord whenever you make a change. If using code patches (recommended), you will need to CTRL+R to load the changes.
|
|
||||||
|
|
||||||
## Plugin Entrypoint
|
|
||||||
|
|
||||||
> If it doesn't already exist, create a folder called `userplugins` in the `src` directory of this repo.
|
|
||||||
|
|
||||||
1. Create a folder in `src/userplugins/` with the name of your plugin. For example, `src/userplugins/epicPlugin/` - All of your plugin files will go here.
|
|
||||||
|
|
||||||
2. Create a file in that folder called `index.ts`
|
|
||||||
|
|
||||||
3. In `index.ts`, copy-paste the following template code:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
import definePlugin from "@utils/types";
|
|
||||||
|
|
||||||
export default definePlugin({
|
|
||||||
name: "Epic Plugin",
|
|
||||||
description: "This plugin is absolutely epic",
|
|
||||||
authors: [
|
|
||||||
{
|
|
||||||
id: 12345n,
|
|
||||||
name: "Your Name",
|
|
||||||
},
|
|
||||||
],
|
|
||||||
patches: [],
|
|
||||||
// Delete these two below if you are only using code patches
|
|
||||||
start() {},
|
|
||||||
stop() {},
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
Change the name, description, and authors to your own information.
|
|
||||||
|
|
||||||
Replace `12345n` with your user ID ending in `n` (e.g., `545581357812678656n`). If you don't want to share your Discord account, use `0n` instead!
|
|
||||||
|
|
||||||
## How Plugins Work In Vencord
|
|
||||||
|
|
||||||
Vencord uses a different way of making mods than you're used to.
|
|
||||||
Instead of monkeypatching webpack, we directly modify the code before Discord loads it.
|
|
||||||
|
|
||||||
This is _significantly_ more efficient than monkeypatching webpack, and is surprisingly easy, but it may be confusing at first.
|
|
||||||
|
|
||||||
## Making your patch
|
|
||||||
|
|
||||||
For an in-depth guide into patching code, see [CONTRIBUTING.md](../CONTRIBUTING.md)
|
|
||||||
|
|
||||||
in the `index.ts` file we made earlier, you'll see a `patches` array.
|
|
||||||
|
|
||||||
> You'll see examples of how patches are used in all the existing plugins, and it'll be easier to understand by looking at those examples, so do that first, and then return here!
|
|
||||||
|
|
||||||
> For a good example of a plugin using code patches AND runtime patching, check `src/plugins/unindent.ts`, which uses code patches to run custom runtime code.
|
|
||||||
|
|
||||||
One of the patches in the `isStaff` plugin, looks like this:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
{
|
|
||||||
match: /(\w+)\.isStaff=function\(\){return\s*!1};/,
|
|
||||||
replace: "$1.isStaff=function(){return true};",
|
|
||||||
},
|
|
||||||
```
|
|
||||||
|
|
||||||
The above regex matches the string in discord that will look something like:
|
|
||||||
|
|
||||||
```js
|
|
||||||
abc.isStaff = function () {
|
|
||||||
return !1;
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
Remember that Discord code is minified, so there won't be any newlines, and there will only be spaces where necessary. So the source code looks something like:
|
|
||||||
|
|
||||||
```
|
|
||||||
abc.isStaff=function(){return!1;}
|
|
||||||
```
|
|
||||||
|
|
||||||
You can find these snippets by opening the devtools (`ctrl+shift+i`) and pressing `ctrl+shift+f`, searching for what you're looking to modify in there, and beautifying the file to make it more readable.
|
|
||||||
|
|
||||||
In the `match` regex in the example shown above, you'll notice at the start there is a `(\w+)`.
|
|
||||||
Anything in the brackets will be accessible in the `replace` string using `$<number>`. e.g., the first pair of brackets will be `$1`, the second will be `$2`, etc.
|
|
||||||
|
|
||||||
The replacement string we used is:
|
|
||||||
|
|
||||||
```
|
|
||||||
"$1.isStaff=function(){return true;};"
|
|
||||||
```
|
|
||||||
|
|
||||||
Which, using the above example, would replace the code with:
|
|
||||||
|
|
||||||
> **Note**
|
|
||||||
> In this example, `$1` becomes `abc`
|
|
||||||
|
|
||||||
```js
|
|
||||||
abc.isStaff = function () {
|
|
||||||
return true;
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
The match value _can_ be a string, rather than regex, however usually regex will be better suited, as it can work with unknown values, whereas strings must be exact matches.
|
|
||||||
|
|
||||||
Once you've made your plugin, make sure you run `pnpm test` and make sure your code is nice and clean!
|
|
||||||
|
|
||||||
If you want to publish your plugin into the Vencord repo, move your plugin from `src/userplugins` into the `src/plugins` folder and open a PR!
|
|
||||||
|
|
||||||
> **Warning**
|
|
||||||
> Make sure you've read [CONTRIBUTING.md](../CONTRIBUTING.md) before opening a PR
|
|
||||||
|
|
||||||
If you need more help, ask in the support channel in our [Discord Server](https://discord.gg/D9uwnFnqmd).
|
|
||||||
Loading…
Reference in new issue