Skip to content

Commit 76acf75

Browse files
prplwtfprplwtf
committed
feat: basically finished documentation??
1 parent c8b25ed commit 76acf75

File tree

6 files changed

+170
-9
lines changed

6 files changed

+170
-9
lines changed

‎apps/frontend/content/docs/concepts/flags.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -42,19 +42,19 @@ Use Blueprint's (deprecated) legacy placeholders. This flag will automatically b
4242

4343
### Development
4444

45-
Developer feature-flags only apply to developer commands.
45+
Developer feature-flags only apply to [developer commands](/docs/cli/commands#developer).
4646

4747
#### `developerIgnoreInstallScript`
4848

49-
Skip running the extension's [install script](/docs/concepts/scripts) when the extension is installed through developer commands.
49+
Skip running the extension's [install script](/docs/concepts/scripts) when the extension is installed through [developer commands](/docs/cli/commands#developer).
5050

5151
#### `developerIgnoreRebuild`
5252

53-
Skip rebuilding frontend assets when the extension is installed through developer commands. Asset rebuilds are only triggered when Blueprint determines that your extension may require one.
53+
Skip rebuilding frontend assets when the extension is installed through [developer commands](/docs/cli/commands#developer). Asset rebuilds are only triggered when Blueprint determines that your extension may require one.
5454

5555
#### `developerKeepApplicationCache`
5656

57-
Skip flushing the application's cache when the extension is installed through developer commands.
57+
Skip flushing the application's cache when the extension is installed through [developer commands](/docs/cli/commands#developer).
5858

5959
#### `developerEscalateInstallScript`
6060

@@ -82,4 +82,4 @@ Blueprint will look for a file called `export.sh`, relative to the extension's d
8282

8383
#### ~~`developerForceMigrate`~~ (deprecated)
8484

85-
Forcefully migrate the database non-interactively when installing your extension through developer commands. **As of beta-2024-12, Blueprint no longer requires interaction for database migrations.**
85+
Forcefully migrate the database non-interactively when installing your extension through [developer commands](/docs/cli/commands#developer). **As of beta-2024-12, Blueprint no longer requires interaction for database migrations.**

‎apps/frontend/content/docs/concepts/placeholders.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,7 @@ With this info, your extension could warn users if they aren't using the Bluepri
149149

150150
#### Mode
151151

152-
Returns either `local` or `develop` depending on if the extension has been installed through a packaged `myextension.blueprint` file or developer commands.
152+
Returns either `local` or `develop` depending on if the extension has been installed through a packaged `myextension.blueprint` file or [developer commands](/docs/cli/commands#developer).
153153

154154
| Placeholder | Output |
155155
| ----------- | ------ |

‎apps/frontend/content/docs/concepts/scripts.md‎

Lines changed: 118 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,123 @@
11
---
22
title: Extension scripts
3-
description: Go out-of-scope, without destroying compatibility with other extensions
3+
description: Make out-of-scope modifications to the Pterodactyl panel
44
category: concepts
55
---
66

7-
...
7+
## Introduction
8+
9+
Sometimes your extension may require to hook into or create a file Blueprint doesn't give you access to through extension APIs. In that case, you have to patch files yourself when your extension is installed, removed and updated. You can do so through scripts.
10+
11+
## Writing extension scripts
12+
13+
Extension scripts live in the root path of the `data.directory` [conf.yml bind](/docs/configs/confyml#datadirectory).
14+
15+
The extension install script is called `install.sh`, update script `update.sh`, remove script `remove.sh` and export script `export.sh`.
16+
17+
## Environment variables
18+
19+
Blueprint exposes environment variables to extension scripts. Depending on the script type, the variables in this list can be used.
20+
21+
| Variable | Description |
22+
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
23+
| `$ENGINE` | Codename of the engine handling the extension and matches the `{engine}` [placeholder](/docs/concepts/placeholders#engine) |
24+
| `$EXTENSION_IDENTIFIER` | Extension identifier (`info.identifier` in [conf.yml](/docs/configs/confyml#infoidentifier-required)) |
25+
| `$EXTENSION_VERSION` | Extension version (`info.version` in [conf.yml](/docs/configs/confyml#infoversion-required)) |
26+
| `$EXTENSION_TARGET` | Extension target version (`info.target` in [conf.yml](/docs/configs/confyml#infotarget-required)) |
27+
| `$PTERODACTYL_DIRECTORY` | Pterodactyl webserver directory |
28+
| `$BLUEPRINT_VERSION` | Blueprint version installed to the panel |
29+
30+
### Limited availability
31+
32+
Select environment variables are limited to select script types.
33+
34+
| Variable | Description | Availability |
35+
| ---------------------- | ------------------------------------------------------------------------------------------ | ---------------------------- |
36+
| `$BLUEPRINT_DEVELOPER` | `true` if extension is being installed through developer commands, otherwise `false` | `install.sh` and `update.sh` |
37+
| `$BLUEPRINT_TMP` | Path to where the extracted extension files are currently located and handled by Blueprint | `update.sh` and `export.sh` |
38+
39+
## Important considerations
40+
41+
What differenciates Blueprint extensions from standalone modifications the most is the focus on compatibility. You as a developer are expected to build scripts with compatibility as a focus, extensively test your scripts and take conflicts seriously. These restrictions apply to scripts themselves and any (if applicable) other files being ran by the extension.
42+
43+
### Script timing
44+
45+
Especially during extension installation, it's important to know _when_ extension scripts get ran. Below is a quick rundown of script timing and potential conditions.
46+
47+
| Script type | Runs when? |
48+
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
49+
| `install.sh` | During the final part of extension installation, before rebuilding dashboard frontend assets (if applicable) |
50+
| `update.sh` | During the initial part of extension installation, where Blueprint determines if the extension is already installed, and if so, runs the extension's update script (if available) |
51+
| `remove.sh` | During the initial part of extension removal, where Blueprint is yet to undo any changes made by the extension |
52+
| `export.sh` | During the final part of extension exporting, right before packaging the extension to a `{identifier}.blueprint` file |
53+
54+
It is important to note that Blueprint does not run the `update.sh` script from an extension's updated `{identifier}.blueprint` file. Instead, Blueprint runs the `update.sh` file of the pre-updated extension.
55+
56+
### Editing files
57+
58+
**Scripts shouldn't overwrite/replace existing files**, instead, they should replace/append strings existent in out-of-scope files.
59+
60+
#### What you should do
61+
62+
You should use tools such as `sed` to search and replace strings to edit files. This tactic should be used for both adding modifications and removing them.
63+
64+
Here is an example of how `sed` can be used for editing files. For more information, check out "[sed, a stream editor](https://www.gnu.org/software/sed/manual/sed.html)".
65+
66+
```bash [install.sh]
67+
# Replaces foo with bar in the foo.txt file
68+
sed -i "s/foo/bar/g" $PTERODACTYL_DIRECTORY/foo.txt
69+
```
70+
71+
Then upon extension removal, we undo the changes.
72+
73+
```bash [remove.sh]
74+
# Replaces foo back to bar in the foo.txt file
75+
sed -i "s/bar/foo/g" $PTERODACTYL_DIRECTORY/foo.txt
76+
```
77+
78+
#### What you shouldn't do
79+
80+
Replacing files, overwriting files, moving files around, replacing complete file content and adding file content based on writing to a specific "file position" are all examples of scripts shouldn't do.
81+
82+
::card
83+
If you are missing specific extension APIs that are preventing you from properly writing an extension, please propose them to us by making a [GitHub issue in BlueprintFramework/framework](https://github.com/BlueprintFramework/framework/issues/new/choose).
84+
::
85+
86+
### Safety and privacy concerns
87+
88+
Extensions shouldn't make calls to internet services through scripts and be installable, removable and updatable without an internet connection.
89+
90+
If your extension specifically requires calls to internet services through scripts to function, users should be prompted to "approve" the request beforehand and be shown the hostname.
91+
92+
#### Obfuscation
93+
94+
No. Extension scripts should not obfuscated by any means, for any purpose.
95+
96+
#### Remote scripts
97+
98+
Neither. Extensions scripts should by no means run anything sourced from a remote endpoint, even when given explicit user approval.
99+
100+
### What happens in Pterodactyl, stays in Pterodactyl
101+
102+
Do not create, modify or alter anything outside of the Pterodactyl directory, with the only exception being `/tmp`.
103+
104+
For referencing Pterodactyl's location, you can use the `$PTERODACTYL_DIRECTORY` environment variable or the `{root}` [placeholder](/docs/concepts/placeholders#root).
105+
106+
### Placeholder limitations
107+
108+
Placeholder availability depends on the script. Below is a table showing a rundown of placeholder support per script.
109+
110+
| Script type | Placeholder support |
111+
| ------------ | ----------------------------------------------------------------------------- |
112+
| `install.sh` | Full support |
113+
| `update.sh` | Partial support. Relevant to previous extension install; data may be outdated |
114+
| `remove.sh` | Full support |
115+
| `export.sh` | No support |
116+
117+
Placeholders are not available in `export.sh`. They are available in `update.sh`. However, keep in mind that placeholders in that file were applied during the previous extension installation.
118+
119+
### Export scripts
120+
121+
Export scripts are for developers to simplify extension packaging. As long as you prevent yourself from destroying your own operating system, you are generally fine.
122+
123+
That said, if you are about to export an extension that has a custom `export.sh` script, read through it before running it.

‎apps/frontend/content/docs/configs/componentsyml.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,50 @@ System administrators can set which "eggs" have which routes [as explained in th
5757

5858
While components themselves are very unlikely to conflict with each other, **routes totally can**. Make sure to not use generic routes names and paths to prevent breakage.
5959

60+
## Building components
61+
62+
Components are created using React and exist in the same environment as Pterodactyl. Before building your first component, make sure you are familiar with the following do-s and don't-s:
63+
64+
| <span class="text-green-400">Do</span> | <span class="text-red-400">Don't</span> |
65+
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
66+
| Do make requests to client API routes | **DON'T EVER STORE TOKENS OR API CREDENTIALS USERS SHOULDN'T HAVE DIRECT ACCESS TO** |
67+
| Do use Pterodactyl- and [your extension's API](/docs/concepts/routing)s | Don't query external site APIs directly from the React application/frontend |
68+
| Do build with Pterodactyl's existing components or your own | Don't rely on other extension's components |
69+
| Do extend the Pterodactyl user interface | Don't modify the dashboard in a way that would (hypothetically) prevent other extensions from working |
70+
71+
With that out of the way, let's create a component in your extension's `dashboard.components` directory.
72+
73+
### Creating a basic component
74+
75+
Create a file called `MyFirstComponent.tsx` in your `dashboard.components` directory and add the following content to it.
76+
77+
```tsx [MyFirstComponent.tsx]
78+
// Import React from the react library
79+
import React from 'react'
80+
81+
// Create a function and set it as the default
82+
// function for this file
83+
export default = () => {
84+
// Return the component's contents
85+
return (
86+
<>
87+
{/* Add a paragraph element */}
88+
<p>this is my first component!</p>
89+
</>
90+
)
91+
}
92+
```
93+
94+
Then, bind it to a placement area in your Components.yml configuration. In this example, we're adding it to `Dashboard.Serverlist.BeforeContent`.
95+
96+
```yaml [Components.yml]
97+
Dashboard:
98+
Serverlist:
99+
BeforeContent: 'MyFirstComponent'
100+
```
101+
102+
After installing your extension, you should see the component appear above the Pterodactyl serverlist.
103+
60104
## Configuration
61105

62106
### Example configuration

‎apps/frontend/content/guides/dev/quickstart.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ order: -1
88
---
99

1010
::card
11-
Developer mode has to be turned on in your admin panel before you can run developer commands. Navigate to `/admin/extensions`, select "Blueprint" and set `developer` to `true`. You only have to do this once.
11+
Developer mode has to be turned on in your admin panel before you can run [developer commands](/docs/cli/commands#developer). Navigate to `/admin/extensions`, select "Blueprint" and set `developer` to `true`. You only have to do this once.
1212
::
1313

1414
## Initialize your extension

‎apps/frontend/nuxt.config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ export default defineNuxtConfig({
6060
'json',
6161
'js',
6262
'ts',
63+
'tsx',
6364
'html',
6465
'css',
6566
'vue',

0 commit comments

Comments
 (0)