From 7b27054e0e8dbcd83a42dc330ee9673ebfdfa155 Mon Sep 17 00:00:00 2001 From: SwingTheVine Date: Sun, 10 Aug 2025 00:47:48 -0400 Subject: [PATCH] Branch sync --- docs/CONTRIBUTING.md | 189 ++++++++++++++++++++++++++++++++++++++++++- docs/README.md | 101 ++++++++++++----------- 2 files changed, 244 insertions(+), 46 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 1665315..1b24bc0 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -33,6 +33,15 @@  How to Contribute + +  Production Enviroment + + +   Npm Run + + +   Charts +  Development Environment @@ -42,6 +51,8 @@ Software License: MPL-2.0

Thank you for wanting to contribute to the userscript "Blue Marble"! It means a lot to me that someone likes my project enough to want to help it grow. If you haven't already done so, consider joining our Discord. You can ask questions about the userscript there and receive feedback. +
+ Note: If you are using AI, and you want to tell the AI how the codebase files are related to each-other, go to the Class diagram of relationships for Blue Marble diagram in the chart section of this file. Copy the chart, and give it to the AI.

Summary

@@ -127,6 +138,182 @@

+

Production Enviroment

+

+ Here lies information that may be of interest to those who wish to modify Blue Marble. + +

Npm Run

+

+ Running npm run build will compile Blue Marble. The compiled files can be found in the dist/ directory. Running npm run patch will increment the patch version, and compile Blue Marble. +

+ +

Charts

+

+ Use the arrow and zoom buttons to navigate the charts. Use the ↔️ button to go fullscreen. Use the 🔄 button to reset. All buttons can be found on the chart. Use the "two squares" icon to copy the chart. If you need assistance reading the chart, copy the chart into an AI using the "two squares" button on the chart. +

+

+ + + +Class diagram of relationships for Blue Marble: +(last updated 0.74.0) +```mermaid +--- + config: + class: + hideEmptyMembersBox: true +--- +classDiagram + class main { + name : string + version : string + +inject() + +observeBlack() + +buildOverlayMain() + } + class utils { + +escapeHTML() + +serverTPtoDisplayTP() + +negativeSafeModulo() + +consoleLog() + +consoleError() + +consoleWarn() + +numberToEncoded() + +uint8ToBase64() + +base64ToUint8() + } + class apiManager { + coordsTilePixel : number[4] + +spontaneousResponseListener() + } + class templateManager { + userID : number + templatesShouldBeDrawn : boolean + +createJSON() + +createTemplate() + -storeTemplates() + +disableTemplate() + +drawTemplateOnTile() + +importJSON() + +parseBlueMarble() + +setTemplatesShouldBeDrawn() + } + class Template { + +createTemplateTiles() + } + class Overlay { + +setApiManager() + -createElement() + +add...() + +buildElement() + +buildOverlay() + +updateInnerHTML() + +handleDrag() + +handleDisplayStatus() + +handleDisplayError() + } + + main o-- apiManager : creates + main o-- utils : creates + main o-- Overlay : creates main, tabTemplate + main o-- templateManager : creates + apiManager ..> templateManager : calls drawTemplateOnTiles(), sets userID + apiManager ..> utils : calls escapeHTML(), numberToEncoded(), serverTPtoDisplayTP() + Overlay ..> apiManager : uses coordsTilePixel + Overlay ..> templateManager : calls setTemplatesShouldBeDrawn() + templateManager *-- Template : manages + templateManager ..> utils : calls base64ToUint8(), numberToEncoded() + Template ..> utils : calls uint8ToBase64() +``` + +Class diagram of relationships for Blue Marble's compiler/builder: +(last updated 0.74.0) +```mermaid +--- + config: + class: + hideEmptyMembersBox: true +--- +classDiagram + + namespace npm_run_patch { + class `patch.js` { + } + + class `docs/README.md` { + } + } + + namespace npm_run_build { + class `build.js` { + mapCSS : JSON Object + } + + class `cssMangler.js` { + importMap : JSON Object + returnMap : JSON Object + +mangleSelectors() + +escapeRegex() + +numberToEncoded() + } + + class `update-version.js` { + } + + class `utils.js` { + +consoleStyle() + } + + class esbuild { + +build() + } + + class terser { + +minify() + } + + class `dist/BlueMarble.user.js` { + } + + class `dist/BlueMarble.user.css` { + } + + class `dist/BlueMarble.user.css.map.json` { + } + + class `src/BlueMarble.meta.js` { + } + + class `src/main.js` { + } + + class `package.json` { + } + } + + note for `patch.js` "calls npm_run_build" + `build.js` ..> terser : requires + `build.js` ..> `utils.js` : calls consoleStyle() + `build.js` ..> `update-version.js` : executes + `build.js` ..> `src/BlueMarble.meta.js` : reads + `build.js` ..> esbuild : calls build() + `build.js` ..> `dist/BlueMarble.user.css` : writes + esbuild ..> `src/main.js` : reads + `build.js` ..> `dist/BlueMarble.user.js` : writes + terser ..> `dist/BlueMarble.user.js` : reads & writes + `build.js` ..> `cssMangler.js` : calls manglerSelectors() + `cssMangler.js` ..> `dist/BlueMarble.user.css.map.json` : reads + `cssMangler.js` ..> `dist/BlueMarble.user.js` : reads & writes + `cssMangler.js` ..> `dist/BlueMarble.user.css` : reads & writes + `build.js` <.. `cssMangler.js` : returns mapCSS + `build.js` ..> `dist/BlueMarble.user.css.map.json` : writes mapCSS + `patch.js` ..> `docs/README.md` : reads & writes + `patch.js` ..> `utils.js` : calls consoleStyle() + `update-version.js` ..> `package.json` : reads + `update-version.js` ..> `src/BlueMarble.meta.js` : reads & writes + `update-version.js` ..> `utils.js` : calls consoleStyle() +``` +

Development Environment

This is what SwingTheVine uses to program Blue Marble. You don't have to use the exact same thing. This is provided for reference. @@ -149,4 +336,4 @@ Storage: 932 GB SSD Samsung SSD 970 EVO Plus 1TB, 238 GB SSD HFM256GDJTNG-8310A
Graphics Card: NVIDIA GeForce GTX 1660 Ti (6 GB)
System Type: 64-bit operating system -

+

\ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 174119d..7b438e8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,9 @@  Overview + +   Installation Instructions +   Script Settings @@ -21,6 +24,12 @@  FAQ + +   Is Blue Marble malware? + + +   How can Blue Marble place pixels for me? +   How do I hide the overlay? @@ -30,33 +39,35 @@

Blue Marble

-Latest Version +Latest Version Latest Release Software License: MPL-2.0 Contact Me -WakaTime -Total Patches +WakaTime +Total Patches Total Lines of Code Total Comments -Compression +Compression +Visitors Build CodeQL

Overview

- Welcome to Blue Marble! Blue Marble is a userscript for the website wplace.live. If you like this userscript, please ⭐ the repository! + Welcome to Blue Marble! Blue Marble is a userscript for the website wplace.live. If you like this userscript, please ⭐ the repository! If you wish to contribute to Blue Marble, check out the CONTRIBUTING.md file in docs/.

Installation Instructions

Supported Browsers - Unupported Browsers + Unupported Browsers

- Blue Marble has been verified to work on mobile devices. Blue Marble was designed on Chrome, but Blue Marble might work on "unsupported" browsers not listed above. Some versions/forks of FireFox work. Some versions/forks of FireFox do not work. + Blue Marble has been verified to work on mobile devices. Blue Marble was designed on Chrome, but Blue Marble might work on "unsupported" browsers not listed above. Some versions/forks of Firefox work. Some versions/forks of Firefox do not work.
Installation instructions for Blue Marble are below. Click the arrows to expand the instructions you want to see. Blue text is a link.

- Computer - Chrome (Click to Expand) + Install Chrome (Computer) (Click to Expand) + Install Tutorial
  1. Install the TamperMonkey plugin for Chrome.
    @@ -67,42 +78,11 @@
  2. Left-click "Manage Extension."
  3. Enable "Developer Mode."
    - Enable 'Developer Mode' and 'Allow user scripts'
    4. + Enable 'Developer Mode' and 'Allow user scripts'
  4. Enable "Allow user scripts."
  5. Download the BlueMarble.user.js file in the "assets" of the latest release.
  6. Open the TamperMonkey Dashboard.
    - Enter the TamperMonkey 'Dashboard'
    7. -
  7. Drag the BlueMarble.user.js file inside the dashboard of TamperMonkey. -
    - Drag the userscript into the dashboard
    8. -
  8. Click the "Install" button to install Blue Marble. -
    - Click the 'Install' button
    9. -
  9. Enable Blue Marble inside the TamperMonkey dashboard. -
    - Enable Blue Marble
    10. -
  10. Refresh the wplace.live webpage.
    11. -
-
-
- - Computer - Edge (Click to Expand) - -
    -
  1. Install the TamperMonkey plugin for Microsoft Edge. -
    - Click the 'Get' button
    2. -
  2. Right-click the extention. -
    - Enter the 'Manage Extention' menu
    3. -
  3. Left-click "Manage Extension."
    4. -
  4. Enable "Developer Mode." -
    - Enable 'Developer Mode'
    5. -
  5. Download the BlueMarble.user.js file in the "assets" of the latest release.
    6. -
  6. Open the TamperMonkey Dashboard. -
    Enter the TamperMonkey 'Dashboard'
  7. Drag the BlueMarble.user.js file inside the dashboard of TamperMonkey.
    @@ -118,19 +98,50 @@
- Computer - FireFox (Click to Expand) + Install Edge (Computer) (Click to Expand)
    -
  1. Install the TamperMonkey plugin for FireFox. +
  2. Install the TamperMonkey plugin for Microsoft Edge.
    - Click the 'Add to FireFox' button
    3. + Click the 'Get' button +
  3. Right-click the extention. +
    + Enter the 'Manage Extention' menu
    4. +
  4. Left-click "Manage Extension."
    5. +
  5. Enable "Developer Mode." +
    + Enable 'Developer Mode'
  6. Download the BlueMarble.user.js file in the "assets" of the latest release.
  7. Open the TamperMonkey Dashboard.
    - Enter the TamperMonkey 'Dashboard'
    8. + Enter the TamperMonkey 'Dashboard'
  8. Drag the BlueMarble.user.js file inside the dashboard of TamperMonkey.
    - Drag the userscript into the dashboard
    9. + Drag the userscript into the dashboard +
  9. Click the "Install" button to install Blue Marble. +
    + Click the 'Install' button
    10. +
  10. Enable Blue Marble inside the TamperMonkey dashboard. +
    + Enable Blue Marble
    11. +
  11. Refresh the wplace.live webpage.
    12. +
+
+
+ + Install Firefox (Computer) (Click to Expand) + +
    +
  1. Install the TamperMonkey plugin for Firefox. +
    + Click the 'Add to Firefox' button
    2. +
  2. Download the BlueMarble.user.js file in the "assets" of the latest release.
    3. +
  3. Open the TamperMonkey Dashboard. +
    + Enter the TamperMonkey 'Dashboard'
    4. +
  4. Drag the BlueMarble.user.js file inside the dashboard of TamperMonkey. +
    + Drag the userscript into the dashboard
  5. Click the "Install" button to install Blue Marble.
    Click the 'Install' button