- Modules
- Installation
- Developer's Guide
Modules are the main focus of Macondo+. You can toggle on (or off) modules to your heart's content. For developer's, making a module is incredibily easy. You only need 3 lines of code for adding your script as a module!
As the sole developer of Macondo+, I provide frequently updated modules, and new ones almost every day. To stay up to date with new and updated modules, please join the #macondoplus slack channel.
This is one of the three categories a module can be. This category is for modules that add quality of life improvements to the site.
Makes the page titles useful.
Hides the annoying NPS (feedback) button.
Hides the slop project idea generator.
Adds keyboard shortcuts to Macondo. E for Shop, R for Profile, 1-9 for Projects, Esc to exit the current menu you're in, / to search for projects.
Display how much time is left until your streak is logged in for the day!
Core modules are not features. It's the engines that make most modules work. This section is aimed at developers who want to build new modules for Macondo+.
Information for how to use Core Modules as a developer is available in this section of this readme.
This is one of the three categories a module can be. This category is for modules that add appearance changes to the website.
Adds dark mode to Macondo (WIP)
Adds appearance changes to the Streak Calendar: the more time you spent working on that day, the more darker and red the day gets!
Fixes minor styling issues for Macondo that pisses you off.
This is one of the three categories a module can be. This category is for modules that add additional tools to the website.
Adds achievements.
Adds additional project metadata that the API exposes.
Adds categories for shop items and a filter to narrow your search.
Adds shop goals to the Shop.
Analyzes your streak calendar and shows trends.
Fixes minor styling issues for Macondo that pisses you off.
Adds extra sort options to the shop: A>Z, Z>A, etc.
This is one of the five categories a module can be. This category is for modules that are silly and do not help to improve the website in any way shape or form. Usually, it's to actually hinder the website.
Heavily inspired by hit Undertale mod 'Undertale 25% Bluer'. As it says, it makes Macondo 25% bluer.
Heavily inspired by hit Undertale mod 'Undertale 25% Greener'. As it says, it makes Macondo 25% greener.
Heavily inspired by hit Undertale mod 'Undertale 25% Redder'. As it says, it makes Macondo 25% redder.
Brings forth an extensive range of lucrative premium monetisation possibilities encompassing the whole of the said website.
burn the earth!
please don't drive in these conditions! enable at your own risk.
it's so dark here...
10% chance of deleting a div.
replaces all the text on the page with very inspirational words
free debt!
you cannot do anything except to create new projects
๐ฝ๐๐๐บ๐ป๐ ๐พ๐ ๐๐๐๐ ๐ผ๐๐
pretend to be rich
disable the ability to create new projects
Unstable
Click on "Actions" on the Navigation bar, click on the first result (for Build Extension .zip), scroll down until you find "Artifacts". Download the "macondoplus-(commit hash)-unzip" and extract it. Then, it will create "macondoplus-use-this-in-extensions-page.zip". Now, follow the specific instructions on your respective browsers:
Please do the instructions above this browser-specific tutorial as it is requried.
Go to chrome://extensions/ on the URL bar. Unzip your zip once more to a folder (create one), and press the "Load unpacked" button on the top left of your screen in the Chrome Extensions tab. Choose the folder you just extracted your files to, which should have the images, scripts, manifest.json.
Please do the instructions under "From Source" as it is requried.
Go to about:addons on the URL bar. Press on the cogwheel which should be located in the top center-ish part of your screen (underneath the search bar). Press on it and click on "Install Add-on From File...". Select your zip.
| Browser | Link | Users | Version |
|---|---|---|---|
| Chromium | Chrome Web Store |  |
 |
| Firefox | Firefox Addons |  |
 |
You should have a basic understanding of Javascript and browser extensions before creating a module.
Want to create your very own custom modules for Macondo+? Well, it's simple. Here's a guide on how you can get it up and running!
Some modules (like Streak Trends) use npm packages bundled via esbuild. You'll need Node.js installed.
cd extension
npm install
npm run buildWhile developing, use watch mode to auto-rebuild on save:
npm run watchAfter any rebuild, go to chrome://extensions and click the Refresh button to pick up your changes. (You should be doing this normally anyways, just a general reminder :3)
When the extension loads, it runs content-script.js first. That script creates a global object called window.MacondoPlus that every module can talk to. Think of it as a shared noticeboard that any module can read from.
content-script.js -> sets up window.MacondoPlus
๐ โ
each module file -> checks window.MacondoPlus, then does its purpose
The three properties window.MacondoPlus gives you:
| Property | What it is |
|---|---|
MODULES |
The full list of every registered module (an array of objects) |
isEnabled(id) |
A function. Pass a module's id, get back true or false. This is heavily used to disable the module if it is not enabled. You will likely need to use this. |
setEnabled(id, value) |
A function. Turn a module on or off and save the choice. |
Let's create a custom module you will be making yourself. This will teach you basically everything you need. Good luck!
Open extension/scripts/content-script.js. Inside the MODULES array near the top, add a new entry for your module:
If your module is a WIP or is a silly/troll module, please enter
falsefordefaultEnabled.
{
id: "my-peak-module", // a unique --> kebab-case <-- id
name: "My PEAK Module", // the grammatically accurate name shown in the module manager
description: "This is PEAK", // shown under the name in the manager
category: "QoL", // "QoL", "Tools", or "Appearance"
defaultEnabled: true // is it on by default when someone first installs a version with your module?
}| Category | Use it when your module... |
|---|---|
"QoL" |
Makes the site easier or nicer to use |
"Appearance" |
Changes how something looks |
"Tools" |
Adds a brand-new tool or panel |
"Core" |
Powers other modules (only for internal infrastructure; you probably don't need this) |
Create a new file at extension/scripts/modules/my-peak-module.js.
Every module follows the same (or similar, for older modules) three-line skeleton.
(() => {
if (!window.MacondoPlus?.isEnabled("my-peak-module")) return;
// your code goes after the if statement
})();Alternatively, this is what was used for older modules: (and some newer modules) This is not used since nesting if statements are bad programming practices.
Not recommended for general use. This is documented for archival purposes.
if (window.MacondoPlus?.isEnabled("my-peak-module")) {
// your code goes here
}The ?. after MacondoPlus is JavaScript's way of saying "only try to call isEnabled if window.MacondoPlus actually exists". It keeps things safe.
You should understand basic CSS and how to get a CSS selector for an element first.
(() => {
if (window.MacondoPlus?.isEnabled("my-peak-module")) return;
const style = document.createElement("style");
style.textContent = `
.element {
display: none !important;
}
`;
})();(() => {
if (window.MacondoPlus?.isEnabled("my-peak-module")) return;
document.addEventListener("DOMContentLoaded", () => {
const heading = document.querySelector("h1");
if (heading) {
heading.textContent = "Hello Macondo!";
}
});
})();Open extension/manifest.json. Find the "js" array inside "content_scripts" and add your file to the list:
โ ๏ธ content-script.jsmust always be first in this list. It sets upwindow.MacondoPlusbefore any module file runs.
"js": [
"scripts/content-script.js",
...
"scripts/modules/my-peak-module.js"
]Congratulations, your module is now live!
Some modules need third-party libraries (e.g. Chart.js). Because browser extensions block external CDN scripts, these are bundled at build time using esbuild.
If your bundle needs an npm package:
- Install it:
npm install <package-name>(cd intoextension/first or you get exploded) - Add an
importat the top of your module file:
import Something from "some-random-ass-package";- Update
package.jsonto add a build entry for your module:
"scripts": {
...,
"build": "esbuild scripts/modules/my-peak-module.js --bundle --outfile=scripts/modules/my-peak-module.bundle.js",
...
}
// For multiple bundled modules, chain them with &&.- Register the bundle file (
.bundle.js) inmanifest.json, not the source file. - Run
npm run buildbefore testing.
A set of tutorials on how to use the core modules.
The macondoplus-panel core module gives modules that need panels that look like the base website so you don't have to build it from scratch.
(() => {
if (window.MacondoPlus?.isEnabled("my-peak-module")) return;
document.addEventListener("DOMContentLoaded", () => {
// Create a new panel
const {open, close, content} = window.MacondoPlus.newPanel();
// Put whatever HTML you want inside of the panel
content.innerHTML = `
<h2>My Module</h2>
<p>Ts peak!</p>
`;
// You can set it to open however you like; here, we use a button click
const myButton = document.querySelector(".my-trigger-button");
myButton.addEventListener("click", open);
});
})();newPanel() returns three things:
| What it does | |
|---|---|
open() |
Shows the panel |
close() |
Hides the panel |
content |
The DOM Content; put your HTML inside this |
The macondoplus-styles core module injects a small set of reusable CSS animations and utility classes that all modules share. You can use these CSS classes in any HTML your module creates:
| Class | What it does |
|---|---|
macondoplus-panel-open |
Fades an element in like the Macondo panel. |
macondoplus-panel-close |
Fades an element out like the Macondo panel. |
macondoplus-panel-open-with-scale |
Fades in and zooms in. |
macondoplus-panel-close-with-scale |
Fades out and zooms out. |
There are already used by the panel system internally, so you normally don't need to touch them. But if you're building a custom popup or toast notification, they're here for you to freely use.
If you look at the module list in content-script.js, you'll see two modules with coreModule: true;
{id: "macondoplus-styles", ..., coreModule: true},
{id: "macondoplus-panel", ..., coreModule: true},coreModule: true does two things:
- Make sure the module is always enabled.
isEnabled()returnstrueno matter what the user has modified. - The toggle button in the module manager UI is disabled so the user can't accidentally turn it off and break functionality.
โ ๏ธ You should never setcoreModule: trueon your own module. Only use it if your module provides something that other modules actively depend on to work at all.
When building a new module, run through this list:
- Added an entry to the
MODULESarray incontent-script.js - Created
extension/scripts/modules/your-id.js - Used the basic skeleton to check for if the module is toggled on/off.
- Added the file path to the
"js"array inmanifest.json - If using npm packages: added a build step to
package.jsonand referenced the.bundle.jsin the manifest - Run
npm run buildif your module uses npm packages - Reloaded the extension in your browser to test