Branch sync

This commit is contained in:
SwingTheVine 2025-08-10 00:47:48 -04:00
parent 7425e91f9b
commit 7b27054e0e
2 changed files with 244 additions and 46 deletions

View file

@ -33,6 +33,15 @@
<tr>
<td>&emsp;<a href="#how-to-contribute">How to Contribute</a></td>
</tr>
<tr>
<td>&emsp;<a href="#production-enviroment">Production Enviroment</a></td>
</tr>
<tr>
<td>&emsp;&emsp;<a href="#npm-run">Npm Run</a></td>
</tr>
<tr>
<td>&emsp;&emsp;<a href="#charts">Charts</a></td>
</tr>
<tr>
<td>&emsp;<a href="#development-environment">Development Environment</a></td>
</tr>
@ -42,6 +51,8 @@
<a href="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/LICENSE.txt" target="_blank" rel="noopener noreferrer"><img alt="Software License: MPL-2.0" src="https://img.shields.io/badge/Software_License-MPL--2.0-slateblue?style=flat"></a>
<p>
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.
<br>
<b>Note</b>: If you are using AI, and you want to tell the AI how the codebase files are related to each-other, go to the <code>Class diagram of relationships for Blue Marble</code> diagram in the chart section of this file. Copy the chart, and give it to the AI.
</p>
<h2>Summary</h2>
@ -127,6 +138,182 @@
</ol>
</p>
<h2>Production Enviroment</h2>
<p>
Here lies information that may be of interest to those who wish to modify Blue Marble.
<h3>Npm Run</h3>
<p>
Running <code>npm run build</code> will compile Blue Marble. The compiled files can be found in the <code>dist/</code> directory. Running <code>npm run patch</code> will increment the patch version, and compile Blue Marble.
</p>
<h3>Charts</h3>
<p>
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.
</p>
</p>
<!-- https://mermaid.js.org/syntax/classDiagram.html -->
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()
```
<h2>Development Environment</h2>
<p>
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: <code>932 GB SSD Samsung SSD 970 EVO Plus 1TB, 238 GB SSD HFM256GDJTNG-8310A</code><br>
Graphics Card: <code>NVIDIA GeForce GTX 1660 Ti (6 GB)</code><br>
System Type: <code>64-bit operating system</code>
</p>
</p>

View file

@ -6,6 +6,9 @@
<tr>
<td>&emsp;<a href="#overview">Overview</a></td>
</tr>
<tr>
<td>&emsp;&emsp;<a href="#installation-instructions">Installation Instructions</a></td>
</tr>
<tr>
<td>&emsp;&emsp;<a href="#script-settings">Script Settings</a></td>
</tr>
@ -21,6 +24,12 @@
<tr>
<td>&emsp;<a href="#faq">FAQ</a></td>
</tr>
<tr>
<td>&emsp;&emsp;<a href="#is-blue-marble-malware">Is Blue Marble malware?</a></td>
</tr>
<tr>
<td>&emsp;&emsp;<a href="#how-can-blue-marble-place-pixels-for-me">How can Blue Marble place pixels for me?</a></td>
</tr>
<tr>
<td>&emsp;&emsp;<a href="#how-do-i-hide-the-overlay">How do I hide the overlay?</a></td>
</tr>
@ -30,33 +39,35 @@
</table>
<h1>Blue Marble</h1>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Latest Version" src="https://img.shields.io/badge/Latest_Version-0.68.0-lightblue?style=flat"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Latest Version" src="https://img.shields.io/badge/Latest_Version-0.78.0-lightblue?style=flat"></a>
<a href="https://github.com/SwingTheVine/Wplace-BlueMarble/releases" target="_blank" rel="noopener noreferrer"><img alt="Latest Release" src="https://img.shields.io/github/v/release/SwingTheVine/Wplace-BlueMarble?sort=semver&style=flat&label=Latest%20Release&color=blue"></a>
<a href="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/LICENSE.txt" target="_blank" rel="noopener noreferrer"><img alt="Software License: MPL-2.0" src="https://img.shields.io/badge/Software_License-MPL--2.0-slateblue?style=flat"></a>
<a href="https://discord.gg/tpeBPy46hf" target="_blank" rel="noopener noreferrer"><img alt="Contact Me" src="https://img.shields.io/badge/Contact_Me-gray?style=flat&logo=Discord&logoColor=white&logoSize=auto&labelColor=cornflowerblue"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="WakaTime" src="https://img.shields.io/badge/Coding_Time-87hrs_0mins-blue?style=flat&logo=wakatime&logoColor=black&logoSize=auto&labelColor=white"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Total Patches" src="https://img.shields.io/badge/Total_Patches-450-black?style=flat"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="WakaTime" src="https://img.shields.io/badge/Coding_Time-91hrs_0mins-blue?style=flat&logo=wakatime&logoColor=black&logoSize=auto&labelColor=white"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Total Patches" src="https://img.shields.io/badge/Total_Patches-494-black?style=flat"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Total Lines of Code" src="https://tokei.rs/b1/github/SwingTheVine/Wplace-BlueMarble?category=code"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Total Comments" src="https://tokei.rs/b1/github/SwingTheVine/Wplace-BlueMarble?category=comments"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Compression" src="https://img.shields.io/badge/Compression-73.04%25-blue"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Compression" src="https://img.shields.io/badge/Compression-73.86%25-blue"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Visitors" src="https://img.shields.io/badge/Visitors-37_847-gainsboro?style=flat"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Build" src="https://github.com/SwingTheVine/Wplace-BlueMarble/actions/workflows/build.yml/badge.svg"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="CodeQL" src="https://github.com/SwingTheVine/Wplace-BlueMarble/actions/workflows/github-code-scanning/codeql/badge.svg"></a>
<h2>Overview</h2>
<p>
Welcome to Blue Marble! Blue Marble is a userscript for the website <a href="https://wplace.live/" target="_blank" rel="noopener noreferrer">wplace.live</a>. If you like this userscript, please ⭐ the repository!
Welcome to Blue Marble! Blue Marble is a userscript for the website <a href="https://wplace.live/" target="_blank" rel="noopener noreferrer">wplace.live</a>. If you like this userscript, please ⭐ the repository! If you wish to contribute to Blue Marble, check out the <a href="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/CONTRIBUTING.md" target="_blank" rel="noopener noreferrer">CONTRIBUTING.md</a> file in <code>docs/</code>.
<h3>Installation Instructions</h3>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Supported Browsers" src="https://img.shields.io/badge/Supported%20Browsers-Chrome%20%7C%20Firefox%2A%20%7C%20Safari%20%7C%20Edge%20%7C%20Brave-orange?style=flat"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Unupported Browsers" src="https://img.shields.io/badge/Unsupported%20Browsers-FireFox%2A%20%7C%20Kiwi%20%7C%20Vivaldi-red?style=flat"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Unupported Browsers" src="https://img.shields.io/badge/Unsupported%20Browsers-Firefox%2A%20%7C%20Kiwi%20%7C%20Vivaldi-red?style=flat"></a>
<p>
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.
<br>
Installation instructions for Blue Marble are below. Click the arrows to expand the instructions you want to see. Blue text is a link.
<details>
<summary>
<b>Computer - Chrome</b> <sup>(Click to Expand)</sup>
<b>Install Chrome (Computer)</b> <sup>(Click to Expand)</sup>
</summary>
<a href="https://www.youtube.com/watch?v=gg5oiJcftEc" target="_blank" rel="noopener noreferrer"><img alt="Install Tutorial" src="https://img.shields.io/badge/Install_Tutorial-gray?style=flat&logo=YouTube&logoColor=white&logoSize=auto&labelColor=darkred"></a>
<ol>
<li>Install the <a href="https://chromewebstore.google.com/detail/tampermonkey/dhdgffkkebhmkfjojejmpbldmpobfkfo" target="_blank" rel="noopener noreferrer">TamperMonkey</a> plugin for Chrome.
<br>
@ -67,42 +78,11 @@
<li>Left-click "Manage Extension."</li>
<li>Enable "Developer Mode."
<br>
<img alt="Enable 'Developer Mode' and 'Allow user scripts'" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall3.png"></li>
<img alt="Enable 'Developer Mode' and 'Allow user scripts'" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerChromeInstall3.png"></li>
<li>Enable "Allow user scripts."</li>
<li>Download the <a href="https://github.com/SwingTheVine/Wplace-BlueMarble/releases" target="_blank" rel="noopener noreferrer">BlueMarble.user.js</a> file in the "assets" of the latest release.</li>
<li>Open the TamperMonkey Dashboard.
<br>
<img alt="Enter the TamperMonkey 'Dashboard'" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall4.png"></li>
<li>Drag the <code>BlueMarble.user.js</code> file inside the dashboard of TamperMonkey.
<br>
<img alt="Drag the userscript into the dashboard" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall5.png"></li>
<li>Click the "Install" button to install Blue Marble.
<br>
<img alt="Click the 'Install' button" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerChromeInstall6.png"></li>
<li>Enable Blue Marble inside the TamperMonkey dashboard.
<br>
<img alt="Enable Blue Marble" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerChromeInstall7.png"></li>
<li>Refresh the <a href="https://wplace.live/" target="_blank" rel="noopener noreferrer">wplace.live</a> webpage.</li>
</ol>
</details>
<details>
<summary>
<b>Computer - Edge</b> <sup>(Click to Expand)</sup>
</summary>
<ol>
<li>Install the <a href="https://microsoftedge.microsoft.com/addons/detail/iikmkjmpaadaobahmlepeloendndfphd" target="_blank" rel="noopener noreferrer">TamperMonkey</a> plugin for Microsoft Edge.
<br>
<img alt="Click the 'Get' button" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall1.png"></li>
<li>Right-click the extention.
<br>
<img alt="Enter the 'Manage Extention' menu" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall2.png"></li>
<li>Left-click "Manage Extension."</li>
<li>Enable "Developer Mode."
<br>
<img alt="Enable 'Developer Mode'" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerChromeInstall3.png"></li>
<li>Download the <a href="https://github.com/SwingTheVine/Wplace-BlueMarble/releases" target="_blank" rel="noopener noreferrer">BlueMarble.user.js</a> file in the "assets" of the latest release.</li>
<li>Open the TamperMonkey Dashboard.
<br>
<img alt="Enter the TamperMonkey 'Dashboard'" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerChromeInstall4.png"></li>
<li>Drag the <code>BlueMarble.user.js</code> file inside the dashboard of TamperMonkey.
<br>
@ -118,19 +98,50 @@
</details>
<details>
<summary>
<b>Computer - FireFox</b> <sup>(Click to Expand)</sup>
<b>Install Edge (Computer)</b> <sup>(Click to Expand)</sup>
</summary>
<ol>
<li>Install the <a href="https://addons.mozilla.org/en-US/firefox/addon/tampermonkey/" target="_blank" rel="noopener noreferrer">TamperMonkey</a> plugin for FireFox.
<li>Install the <a href="https://microsoftedge.microsoft.com/addons/detail/iikmkjmpaadaobahmlepeloendndfphd" target="_blank" rel="noopener noreferrer">TamperMonkey</a> plugin for Microsoft Edge.
<br>
<img alt="Click the 'Add to FireFox' button" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerFireFoxInstall1.png"></li>
<img alt="Click the 'Get' button" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall1.png"></li>
<li>Right-click the extention.
<br>
<img alt="Enter the 'Manage Extention' menu" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall2.png"></li>
<li>Left-click "Manage Extension."</li>
<li>Enable "Developer Mode."
<br>
<img alt="Enable 'Developer Mode'" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall3.png"></li>
<li>Download the <a href="https://github.com/SwingTheVine/Wplace-BlueMarble/releases" target="_blank" rel="noopener noreferrer">BlueMarble.user.js</a> file in the "assets" of the latest release.</li>
<li>Open the TamperMonkey Dashboard.
<br>
<img alt="Enter the TamperMonkey 'Dashboard'" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall2.png"></li>
<img alt="Enter the TamperMonkey 'Dashboard'" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall4.png"></li>
<li>Drag the <code>BlueMarble.user.js</code> file inside the dashboard of TamperMonkey.
<br>
<img alt="Drag the userscript into the dashboard" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerFireFoxInstall3.png"></li>
<img alt="Drag the userscript into the dashboard" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall5.png"></li>
<li>Click the "Install" button to install Blue Marble.
<br>
<img alt="Click the 'Install' button" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerChromeInstall6.png"></li>
<li>Enable Blue Marble inside the TamperMonkey dashboard.
<br>
<img alt="Enable Blue Marble" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerChromeInstall7.png"></li>
<li>Refresh the <a href="https://wplace.live/" target="_blank" rel="noopener noreferrer">wplace.live</a> webpage.</li>
</ol>
</details>
<details>
<summary>
<b>Install Firefox (Computer)</b> <sup>(Click to Expand)</sup>
</summary>
<ol>
<li>Install the <a href="https://addons.mozilla.org/en-US/firefox/addon/tampermonkey/" target="_blank" rel="noopener noreferrer">TamperMonkey</a> plugin for Firefox.
<br>
<img alt="Click the 'Add to Firefox' button" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerFirefoxInstall1.png"></li>
<li>Download the <a href="https://github.com/SwingTheVine/Wplace-BlueMarble/releases" target="_blank" rel="noopener noreferrer">BlueMarble.user.js</a> file in the "assets" of the latest release.</li>
<li>Open the TamperMonkey Dashboard.
<br>
<img alt="Enter the TamperMonkey 'Dashboard'" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerFirefoxInstall2.png"></li>
<li>Drag the <code>BlueMarble.user.js</code> file inside the dashboard of TamperMonkey.
<br>
<img alt="Drag the userscript into the dashboard" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerFirefoxInstall3.png"></li>
<li>Click the "Install" button to install Blue Marble.
<br>
<img alt="Click the 'Install' button" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerChromeInstall6.png"></li>