Compare commits
4 Commits
f29c0ce9e5
...
15f2479e94
| Author | SHA1 | Date |
|---|---|---|
フズキ
|
15f2479e94 | |
|
フズキ
|
2f5538a480 | |
|
フズキ
|
18cd7e1595 | |
|
フズキ
|
70bd71b4e2 |
|
|
@ -205,12 +205,16 @@ GEM
|
|||
rb-fsevent (~> 0.10, >= 0.10.3)
|
||||
rb-inotify (~> 0.9, >= 0.9.10)
|
||||
mercenary (0.3.6)
|
||||
mini_portile2 (2.5.1)
|
||||
minima (2.5.1)
|
||||
jekyll (>= 3.5, < 5.0)
|
||||
jekyll-feed (~> 0.9)
|
||||
jekyll-seo-tag (~> 2.1)
|
||||
minitest (5.14.4)
|
||||
multipart-post (2.1.1)
|
||||
nokogiri (1.11.1)
|
||||
mini_portile2 (~> 2.5.0)
|
||||
racc (~> 1.4)
|
||||
nokogiri (1.11.1-x86_64-linux)
|
||||
racc (~> 1.4)
|
||||
octokit (4.20.0)
|
||||
|
|
@ -254,6 +258,7 @@ GEM
|
|||
zeitwerk (2.4.2)
|
||||
|
||||
PLATFORMS
|
||||
ruby
|
||||
x86_64-linux
|
||||
|
||||
DEPENDENCIES
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ sort: <number>
|
|||
Before pushing your edits to the documentation, you may want to see what they
|
||||
look like. To do so, you need to:
|
||||
|
||||
- have a local [Ruby](https://www.ruby-lang.org) environment
|
||||
- have a local [Ruby](https://www.ruby-lang.org) 2.7 environment
|
||||
- install the `bundler` and `jekyll` gems
|
||||
`gem install bundler jekyll`
|
||||
- install this project's specific requirements:
|
||||
|
|
|
|||
|
|
@ -0,0 +1,129 @@
|
|||
---
|
||||
title: Introduction
|
||||
sort: 1
|
||||
---
|
||||
|
||||
# Starting out making GooseMod modules
|
||||
|
||||
## Module structure
|
||||
### Manifest file
|
||||
|
||||
The manifest file contains the metadata for your module. Its name is `goosemodModule.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"main": "",
|
||||
|
||||
"name": "",
|
||||
"description": "",
|
||||
"tags": ["", ""],
|
||||
|
||||
"authors": ["", ""],
|
||||
|
||||
"version": ""
|
||||
}
|
||||
```
|
||||
|
||||
- `main`: Main file of your module.
|
||||
- `name`: Name of your module.
|
||||
- `description`: Description of your module.
|
||||
- `tags`: List of tags for your module.
|
||||
- `authors`: List of authors (Discord IDs).
|
||||
- `version`: Version of your module (semver).
|
||||
|
||||
### Main
|
||||
|
||||
Your main file will probably have your main definitions, but the only mandatory definition is the exported object:
|
||||
|
||||
```js
|
||||
export default {
|
||||
gooseHandlers: {
|
||||
onImport: () => {
|
||||
// Will be ran when your module is installed or on every GM load.
|
||||
},
|
||||
onRemove: () => {
|
||||
// Will be ran when your module is uninstalled or disabled.
|
||||
// Clean up everything here.
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### Other files
|
||||
|
||||
You can separate your code in multiple files using ES module syntax.
|
||||
|
||||
## Testing your module
|
||||
|
||||
Once you have reached a point when you want to test your module, you'll want to run the development server. You can get it by cloning the [GooseMod/MS2Builder](https://github.com/GooseMod/MS2Builder) github repository.
|
||||
|
||||
You can then run the developement server with the following command, in the repository's directory:
|
||||
`node src/dev.js <modules_dir> <port>`, replacing `<modules_dir>` with the directore in which you have your modules and `<port>` with the port to serve on.
|
||||
|
||||
An exemple `<modules_dir>` structure would be:
|
||||
|
||||
- `modules/`
|
||||
- `module-1/`
|
||||
- `goosemodModule.json`
|
||||
- `index.js`
|
||||
- `module-2/`
|
||||
- `goosemodModule.json`
|
||||
- `main.js`
|
||||
- ...
|
||||
- ...
|
||||
|
||||
## Local modules
|
||||
|
||||
```note
|
||||
Local modules are currently a non-supported feature, but you could use [this method](#custom-repository) to have your own repository, or use the [development](#testing-your-module) server, although you need to launch it every time.
|
||||
```
|
||||
|
||||
## Publishing your modules
|
||||
### Official repository
|
||||
|
||||
Publishing to the official repository can be asked for on the [GooseNest Discord server](https://goosemod.com/discord).
|
||||
|
||||
### Custom repository
|
||||
|
||||
You can make your own repository by taking [GooseMod/MS2Builder](https://github.com/GooseMod/MS2Builder) as a base.
|
||||
|
||||
The first step is to clean up the repository definitions. Remove the files you don't need from the followin and remove all entries from those you kept:
|
||||
|
||||
- `src/modules/goosemod.js`: GooseMod modules (you will probably want to keep this one, just saying).
|
||||
- `src/modules/ms2porter.js`: Ported GM MS1 modules (you won't need this one).
|
||||
- `src/modules/ports/plugins/pcPlugins.js`: Powercord plugins auto-ports.
|
||||
- `src/modules/ports/themes/bdThemes.js`: BetterDiscord themes auto-ports.
|
||||
- `src/modules/ports/themes/pcThemes.js`: Powercord themes auto-ports.
|
||||
|
||||
To finish cleaning up, edit `src/modules/index.js`. This file contains the metadata for each generated repository. Remove the entries related to the files you previously removed, as well as the related imports at the top of the file.
|
||||
|
||||
Now that you've cleared everything unneeded out, you can start setting your repository up:
|
||||
|
||||
- Edit the module lists in the files you kept. The format for a single module is:
|
||||
```js
|
||||
[
|
||||
'Github/repository', // Example: 'GooseMod/GMExampleModule'
|
||||
'ref (commit hash, branch or tag)', // Example: 'main' (recommended to use a commit hash for safety,
|
||||
// if left clear uses the default branch)
|
||||
'path to module', // [OPTIONAL] Example: '/path/to/module'
|
||||
'preprocessor (undefined for GM modules)', // [OPTIONAL] Example: 'pcPlugin' (used for autoports)
|
||||
{} // [OPTIONAL] Metadata override (see goosemodModule.json)
|
||||
]
|
||||
```
|
||||
- Edit the repository metadata in `src/modules/index.js`:
|
||||
- `meta`:
|
||||
- `name`: Name of the repository shown in the repository list in GooseMod.
|
||||
- `description`: Description in the repository shown in the repository list in GooseMod.
|
||||
- `filename`: Name of the generated repository definition file.
|
||||
- `modules`: Object containing module definitions, use imports to keep the file clean.
|
||||
|
||||
Add a file named `gh_pat.js` in the `src/` directory, with the following content:
|
||||
```js
|
||||
export default "ghp_randomstuff"; // replace with an actual Github Personal Access Token
|
||||
```
|
||||
|
||||
You can now buid your repository/repositories by running `node src/index.js` from the base directory of the MS2Builder clone.
|
||||
|
||||
If all went well, there should have been no errors in the building process. If there were errors you can ask for support on the [GooseNest Discord server](https://goosemod.com/discord), on the `#module-dev` channel.
|
||||
|
||||
You now have the necessary files for hosting the repository in `dist/`. You can just serve the directory directly, or you could make a repository like `GooseMod/MS2Builder`'s to host your repositories and built files, or even go a step further and setup CI/CD. That's all on you though.
|
||||
|
|
@ -7,22 +7,15 @@ sort: 2
|
|||
|
||||
## Accessing the GooseMod settings interface
|
||||
|
||||
The GooseMod settings interface can be accessed in your modules by importing
|
||||
`@goosemod/settings`. You can extend Discord's settings with more categories,
|
||||
pages, and other elements by importing the right procedures.
|
||||
The GooseMod settings interface can be accessed in your modules by importing `@goosemod/settings`. You can extend Discord's settings with more categories, pages, and other elements by importing the right procedures.
|
||||
|
||||
## Adding a new settings page
|
||||
|
||||
When GooseMod loads all modules, it first creates a new category called
|
||||
`GooseMod Modules`, so that all modules thereafter add their settings under
|
||||
this category by default.
|
||||
When GooseMod loads all modules, it first creates a new category called `GooseMod Modules`, so that all modules thereafter add their settings under this category by default.
|
||||
|
||||
Adding your own settings page is pretty straightforward: once your module has
|
||||
been completely loaded it will call its defined `onLoadingFinished` prodedure,
|
||||
all that's needed to add a page is call `createItem` from the settings import.
|
||||
Adding your own settings page is pretty straightforward: once your module has been completely loaded it will call its defined `onLoadingFinished` prodedure, all that's needed to add a page is call `createItem` from the settings import.
|
||||
|
||||
Do remember to remove the settings pages you add when your module gets disabled
|
||||
though.
|
||||
Do remember to remove the settings pages you add when your module gets disabled though.
|
||||
|
||||
First import `createItem`:
|
||||
|
||||
|
|
@ -41,11 +34,9 @@ createItem('Page name', [
|
|||
|
||||
## Removing a settings page
|
||||
|
||||
When your module is disabled, it should undo all modifications made, to
|
||||
restore the state of Discord prior to when it was enabled.
|
||||
When your module is disabled, it should undo all modifications made, to restore the state of Discord prior to when it was enabled.
|
||||
|
||||
[Adding a settings page](#adding-a-new-settings-page) was easy enough, but
|
||||
removing one is even easier.
|
||||
[Adding a settings page](#adding-a-new-settings-page) was easy enough, but removing one is even easier.
|
||||
|
||||
First add `removeItem` to your imports from `@goosemod/settings`:
|
||||
|
||||
|
|
@ -61,12 +52,9 @@ removeItem('Page name');
|
|||
|
||||
## Types of settings fields
|
||||
|
||||
Settings fields are objects, each having a `type` property defining its type,
|
||||
a `text` property defining the field's text.
|
||||
Settings fields are objects, each having a `type` property defining its type, a `text` property defining the field's text.
|
||||
|
||||
Most fields also have a `subtext` property to add additional information if
|
||||
needed, for example: precising the default values of your settings. The way
|
||||
you would define a fields subtext is like so:
|
||||
Most fields also have a `subtext` property to add additional information if needed, for example: precising the default values of your settings. The way you would define a fields subtext is like so:
|
||||
|
||||
```js
|
||||
{
|
||||
|
|
@ -78,8 +66,7 @@ you would define a fields subtext is like so:
|
|||
|
||||
### Divider field
|
||||
|
||||
A simple divider to separate your fields. Most other fields already add a
|
||||
divider, so needing one is a more specific use case. They are defined like so:
|
||||
A simple divider to separate your fields. Most other fields already add a divider, so needing one is a more specific use case. They are defined like so:
|
||||
|
||||
```js
|
||||
{
|
||||
|
|
@ -88,19 +75,16 @@ divider, so needing one is a more specific use case. They are defined like so:
|
|||
```
|
||||
|
||||
```note
|
||||
Divider fields **do not** use the `subtext` property. However they have a
|
||||
`text` property.
|
||||
Divider fields **do not** use the `subtext` property. However they have a `text` property.
|
||||
```
|
||||
|
||||
```warning
|
||||
The divider field's `text` property has not yet been experimented with
|
||||
and documented.
|
||||
The divider field's `text` property has not yet been experimented with and documented.
|
||||
```
|
||||
|
||||
### Header field
|
||||
|
||||
Header fields let you make categories in your settings page, they are defined
|
||||
like so:
|
||||
Header fields let you make categories in your settings page, they are defined like so:
|
||||
|
||||
```js
|
||||
{
|
||||
|
|
@ -126,8 +110,7 @@ Text fields let you write text without user controls, they are defined like so:
|
|||
|
||||
### Button field
|
||||
|
||||
Button fields let you add simple buttons to launch actions, they are defined
|
||||
like so:
|
||||
Button fields let you add simple buttons to launch actions, they are defined like so:
|
||||
|
||||
```js
|
||||
{
|
||||
|
|
@ -144,15 +127,11 @@ Buttons do not use the `subtext` property.
|
|||
```
|
||||
|
||||
```note
|
||||
Button fields are pretty bare and only simple buttons. If you use them, you may
|
||||
want to add a [text field](#text-field) before to explain their function and a
|
||||
[divider field](#divider-field) afterwards to properly separate them from the
|
||||
following fields.
|
||||
Button fields are pretty bare and only simple buttons. If you use them, you may want to add a [text field](#text-field) before to explain their function and a [divider field](#divider-field) afterwards to properly separate them from the following fields.
|
||||
```
|
||||
|
||||
```tip
|
||||
Given that button fields are so bare, I'd recommend using
|
||||
[text-button fields](#text-button-field) in most cases.
|
||||
Given that button fields are so bare, [text-button fields](#text-button-field) may be more appropriate for your use case.
|
||||
```
|
||||
|
||||
#### Text-Button field
|
||||
|
|
@ -172,14 +151,12 @@ They are defined like so:
|
|||
```
|
||||
|
||||
```note
|
||||
Unlike [button fields](#button-field), text-button fields include a
|
||||
[divider field](#divider-field), so you don't need to add one after.
|
||||
Unlike [button fields](#button-field), text-button fields include a [divider field](#divider-field), so you don't need to add one after.
|
||||
```
|
||||
|
||||
#### Text-Button-Danger field
|
||||
|
||||
Exactly like the [text-button field](#text-button-field), but the button has
|
||||
the danger styling (red). They are defined like so:
|
||||
Exactly like the [text-button field](#text-button-field), but the button has the danger styling (red). They are defined like so:
|
||||
|
||||
```js
|
||||
{
|
||||
|
|
@ -193,14 +170,12 @@ the danger styling (red). They are defined like so:
|
|||
```
|
||||
|
||||
```note
|
||||
Due to the design language surrounding them, you should only use these if the
|
||||
action could have impactful consequences.
|
||||
Due to the design language surrounding them, you should only use these if the action could have impactful consequences.
|
||||
```
|
||||
|
||||
### Toggle field
|
||||
|
||||
Toggle fields let you make on/off switches for your basic settings, they are
|
||||
defined like so:
|
||||
Toggle fields let you make on/off switches for your basic settings, they are defined like so:
|
||||
|
||||
```js
|
||||
{
|
||||
|
|
@ -218,9 +193,7 @@ defined like so:
|
|||
|
||||
#### Toggle-Text-Button field
|
||||
|
||||
A [toggle field](#toggle-field) with a small [button](#button-field), or a
|
||||
[text-button field](#text-button-field) with a [toggle switch](#toggle-field).
|
||||
They are defined like so:
|
||||
A [toggle field](#toggle-field) with a small [button](#button-field), or a [text-button field](#text-button-field) with a [toggle switch](#toggle-field). They are defined like so:
|
||||
|
||||
```js
|
||||
{
|
||||
|
|
@ -242,8 +215,7 @@ They are defined like so:
|
|||
|
||||
#### Toggle-Text-Button-Danger
|
||||
|
||||
Exactly like the [toggle-text-button field](#toggle-text-button-field), but
|
||||
the button has the danger styling (red). They are defined like so:
|
||||
Exactly like the [toggle-text-button field](#toggle-text-button-field), but the button has the danger styling (red). They are defined like so:
|
||||
|
||||
```js
|
||||
{
|
||||
|
|
@ -264,14 +236,12 @@ the button has the danger styling (red). They are defined like so:
|
|||
```
|
||||
|
||||
```note
|
||||
Due to the design language surrounding them, you should only use these if the
|
||||
action could have impactful consequences.
|
||||
Due to the design language surrounding them, you should only use these if the action could have impactful consequences.
|
||||
```
|
||||
|
||||
### Colour field
|
||||
|
||||
Colour fields let you make colour pickers for your settings, they are defined
|
||||
like so:
|
||||
Colour fields let you make colour pickers for your settings, they are defined like so:
|
||||
|
||||
```js
|
||||
{
|
||||
|
|
@ -291,43 +261,105 @@ like so:
|
|||
The colour picker doesn't support alpha channel (opacity) yet.
|
||||
```
|
||||
|
||||
### Card field
|
||||
### Text input field
|
||||
|
||||
```warning
|
||||
Not yet experimented with or documented.
|
||||
```
|
||||
Text input fields let you get text input for more complex needs. They are defined like so:
|
||||
|
||||
### Search field
|
||||
|
||||
```warning
|
||||
Not yet experimented with or documented.
|
||||
```
|
||||
|
||||
### Sidebar field
|
||||
|
||||
```warning
|
||||
Not yet experimented with or documented.
|
||||
```js
|
||||
{
|
||||
type: "text-input",
|
||||
text: "Description",
|
||||
initialValue: () => "Initial value",
|
||||
oninput: (value, element) => {
|
||||
// Do something.
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Custom field
|
||||
|
||||
Custom fields only support a single property: `element`. They are defined like
|
||||
so:
|
||||
Custom fields only support a single property: `element`. They are defined like so:
|
||||
|
||||
```js
|
||||
{
|
||||
type: "custom",
|
||||
element: (() => {
|
||||
element: () => {
|
||||
// Return a DOM element
|
||||
let e = document.createElement("span");
|
||||
e.innerText = "Custom Element";
|
||||
return e;
|
||||
})()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```note
|
||||
Custom fields can be used to make any kind of field that is not built into
|
||||
GooseMod. For example, [here is a procedure building a text input field](https://github.com/NovaGM/Modules/blob/master/settings-experiment/custom-settings.js#L1).
|
||||
`element` can be a DOM element or a function that will be called and expected to return the element.
|
||||
```
|
||||
|
||||
```note
|
||||
Custom fields can be used to make any kind of field that is not built into GooseMod.
|
||||
|
||||
For example, [here is a procedure building a text input field](https://github.com/NovaGM/Modules/blob/master/comfy-theme/custom-settings.js#L1) made when there was no [text input field](#text-input) yet.
|
||||
```
|
||||
|
||||
### Internal fields
|
||||
|
||||
These fields are used internally by GooseMod for specific uses. You may reuse them, but you'll want to do your own research and testing.
|
||||
|
||||
#### Card field
|
||||
|
||||
Can be seen in the module and theme stores, each entry has a card.
|
||||
|
||||
Defined [here](https://github.com/GooseMod/GooseMod/blob/master/src/ui/settings.js#L697-L1126).
|
||||
|
||||
```warning
|
||||
Not yet experimented with or documented.
|
||||
```
|
||||
|
||||
#### Search field
|
||||
|
||||
Can be seen in the module and theme stores.
|
||||
|
||||
Defined [here](https://github.com/GooseMod/GooseMod/blob/master/src/ui/settings.js#L1128-L1203).
|
||||
|
||||
```warning
|
||||
Not yet experimented with or documented.
|
||||
```
|
||||
|
||||
#### Sidebar field
|
||||
|
||||
Defined [here](https://github.com/GooseMod/GooseMod/blob/master/src/ui/settings.js#L1205-L1309).
|
||||
|
||||
```warning
|
||||
Not yet experimented with or documented.
|
||||
```
|
||||
|
||||
#### Dropdown fields
|
||||
##### Dropdown field
|
||||
|
||||
Dropdown field to offer multipple defined choices. Can be seen in the GooseMod settings page, to force select a language.
|
||||
|
||||
Defined [here](https://github.com/GooseMod/GooseMod/blob/master/src/ui/settings.js#L1450-L1520).
|
||||
|
||||
```warning
|
||||
Not yet experimented with or documented.
|
||||
```
|
||||
##### Inline dropdown field
|
||||
|
||||
Dropdown field to offer multipple defined choices, designed to be used side by side. Can be seen in the module and theme stores.
|
||||
|
||||
Defined [here](https://github.com/GooseMod/GooseMod/blob/master/src/ui/settings.js#L1392-L1448).
|
||||
|
||||
```warning
|
||||
Not yet experimented with or documented.
|
||||
```
|
||||
|
||||
#### GM footer
|
||||
|
||||
Footer for the GooseMod settings page.
|
||||
|
||||
Defined [here](https://github.com/GooseMod/GooseMod/blob/master/src/ui/settings.js#L1321-L1390).
|
||||
|
||||
```note
|
||||
Not intended for use in modules.
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue