From 6e565e19b4e9feb5f128c22d917b85aec65770cb Mon Sep 17 00:00:00 2001 From: Reece Dunham Date: Mon, 8 Jan 2024 15:07:33 -0500 Subject: [PATCH] Begin plugin development guides --- LICENSE | 2 +- docusaurus.config.mjs | 20 ++++++++ .../current.json | 10 ++++ i18n/en/docusaurus-theme-classic/footer.json | 4 ++ plugin-dev/prep.md | 50 +++++++++++++++++++ plugin-dev/what-is-a-plugin.md | 23 +++++++++ sidebarsPluginDev.mjs | 16 ++++++ 7 files changed, 124 insertions(+), 1 deletion(-) create mode 100644 i18n/en/docusaurus-plugin-content-docs-plugin-dev/current.json create mode 100644 plugin-dev/prep.md create mode 100644 plugin-dev/what-is-a-plugin.md create mode 100644 sidebarsPluginDev.mjs diff --git a/LICENSE b/LICENSE index 9c52d33..ac249fd 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2022-2023 The Peacock Project +Copyright (c) 2022-2024 The Peacock Project Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/docusaurus.config.mjs b/docusaurus.config.mjs index ae0e21d..97232ea 100644 --- a/docusaurus.config.mjs +++ b/docusaurus.config.mjs @@ -88,6 +88,10 @@ export default { label: "Help/Bugs/Feature Requests (in our Discord)", href: "https://discord.gg/F8qQTfnajw", }, + { + label: "Plugin Development", + to: "/plugins", + } ], }, { @@ -161,6 +165,22 @@ export default { showLastUpdateTime: true, }, ], + [ + "@docusaurus/plugin-content-docs", + { + id: "plugin-dev", + sidebarPath: require.resolve("./sidebarsPluginDev.mjs"), + routeBasePath: "/plugins/", + path: "plugin-dev", + editUrl: ({ locale, docPath }) => { + if (locale !== `en`) { + return `https://crowdin.com/project/peacock/${locale}` + } + return `https://github.com/thepeacockproject/peacockprojectorg/edit/main/plugin-dev/${docPath}` + }, + showLastUpdateTime: true, + }, + ], "@docusaurus/plugin-content-pages", require.resolve("./src/search/plugin.mjs"), [ diff --git a/i18n/en/docusaurus-plugin-content-docs-plugin-dev/current.json b/i18n/en/docusaurus-plugin-content-docs-plugin-dev/current.json new file mode 100644 index 0000000..2cb71d5 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs-plugin-dev/current.json @@ -0,0 +1,10 @@ +{ + "version.label": { + "message": "Next", + "description": "The label for version current" + }, + "sidebar.sidebar.category.Plugin Development": { + "message": "Plugin Development", + "description": "The label for category Plugin Development in sidebar sidebar" + } +} diff --git a/i18n/en/docusaurus-theme-classic/footer.json b/i18n/en/docusaurus-theme-classic/footer.json index 0817ec9..d2b0e46 100644 --- a/i18n/en/docusaurus-theme-classic/footer.json +++ b/i18n/en/docusaurus-theme-classic/footer.json @@ -54,5 +54,9 @@ "logo.alt": { "message": "Peacock Feather Logo", "description": "The alt text of footer logo" + }, + "link.item.label.Plugin Development": { + "message": "Plugin Development", + "description": "The label of footer link with label=Plugin Development linking to /plugins" } } diff --git a/plugin-dev/prep.md b/plugin-dev/prep.md new file mode 100644 index 0000000..bac0ec0 --- /dev/null +++ b/plugin-dev/prep.md @@ -0,0 +1,50 @@ +--- +title: Start Building +--- + +Ready to develop a plugin? Great! Here's how to get started. + +## Pre-Requisites + +First, you will need to install [Node.js](https://nodejs.org) - use the [same major version as Peacock](https://github.com/thepeacockproject/Peacock/blob/v7/.nvmrc). + +After installing Node, you will need to active Node.js' package manager-manager, `corepack`. +Visit a terminal or command prompt, and use the command `corepack enable` to do so. + +:::note PowerShell error + +If you are using PowerShell on Windows, you may run into an issue where it says you can't run unsigned scripts. +To fix this, run `Set-ExecutionPolicy Unrestricted` and try again. + +::: + +Lastly, you will need to install [Git](https://git-scm.com). The installer on Windows has a lot of options, and the defaults are fine. + +## Workspace Setup + +Once you have all the pre-requisites satisfied, you will need to clone the Peacock repository. +You can develop your plugin alongside the Peacock source code for ease of access. + +To clone the repository, run the following command in a terminal or command prompt: + +```bash +git clone https://github.com/thepeacockproject/Peacock.git +``` + +You will then want to open the project in a code editor of your choice, such as [Visual Studio Code](https://code.visualstudio.com) or [WebStorm](https://jetbrains.com/webstorm). + +Once you have opened the project, run the following command to install the dependencies: + +```bash +yarn install +``` + +You now have the workspace fully set up. You can create a new file for your plugin in the `plugins` folder, and start developing. + +To run the Peacock server from the repository in development mode, run the following command: + +```bash +yarn run-dev +``` + +While in development mode, plugins written in TypeScript will be loaded and automatically transformed into JavaScript. diff --git a/plugin-dev/what-is-a-plugin.md b/plugin-dev/what-is-a-plugin.md new file mode 100644 index 0000000..0506ebd --- /dev/null +++ b/plugin-dev/what-is-a-plugin.md @@ -0,0 +1,23 @@ +--- +title: What is a Plugin? +--- + +Peacock plugins allow you to extend Peacock's functionality and add new features. + +If you're interested in creating a plugin, you're in the right place. + +If you're a user and you want to install a plugin, check out the [Custom Content page](/wiki/custom-content), which has instructions. + +## Plugin Specification + +Peacock plugins are written in JavaScript. They can also be written in TypeScript, but must be compiled to JavaScript before Peacock can load it. Peacock comes with full type definitions. + +Plugins can use the latest ECMAScript features [available](https://node.green) in the version of Node.js [that Peacock uses](https://github.com/thepeacockproject/Peacock/blob/v7/.nvmrc). + +Plugins can be written in [CommonJS or ES Modules](https://blog.logrocket.com/commonjs-vs-es-modules-node-js/), but must be compiled to CommonJS before Peacock can load it. + +Plugins can be installed and managed by [Simple Mod Framework](https://www.nexusmods.com/hitman3/mods/200) mods, or manually by the user. + +Peacock loads plugins that match the file name schema from the Peacock folder itself or (the new and better) `plugins` folder. + +The file name schema is `*Plugin.js` or `*.plugin.js`, where `*` is the name of the plugin. diff --git a/sidebarsPluginDev.mjs b/sidebarsPluginDev.mjs new file mode 100644 index 0000000..64abce1 --- /dev/null +++ b/sidebarsPluginDev.mjs @@ -0,0 +1,16 @@ +export default { + sidebar: [ + { + type: "category", + label: "Plugin Development", + link: { + type: "generated-index", + slug: "/", + }, + items: [ + "what-is-a-plugin", + "prep", + ], + }, + ], +}