Merge pull request #120 from Parallaxes/docs

Update music docs

Author: Parallaxes

Diff for: _notebooks/2024-02-10-music.ipynb

@@ -0,0 +1,172 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "vscode": {
+     "languageId": "yaml"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "---\n",
+    "author: Lucas Masterson\n",
+    "layout: post\n",
+    "title: So you want to add music?\n",
+    "description: Adding music to platformer\n",
+    "permalink: /music\n",
+    "categories: [Miscellaneous]\n",
+    "toc: true\n",
+    "---"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## What am I doing here?\n",
+    "\n",
+    "You may have noticed a few levels have music (my personal favorite being the \"Regicide\" track from the Destiny: The Taken King OST, but I digress), and maybe you want to add that. I had the pleasure of figuring that out and now I may share my knowledge. See this [Pull Request](https://github.com/nighthawkcoders/platformer4x/pull/18)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Introduction\n",
+    "\n",
+    "Most of this capability comes from `GameEnv.js` with these static methods:\n",
+    "\n",
+    "```js\n",
+    "// ~/assets/js/platformer/GameEnv.js\n",
+    "// Play a sound by its ID\n",
+    "static playSound(id) {\n",
+    "    const sound = document.getElementById(id);\n",
+    "    sound.play();\n",
+    "}\n",
+    "\n",
+    "// Play a sound by its ID in a loop\n",
+    "static loopSound(id) {\n",
+    "    const sound = document.getElementById(id);\n",
+    "    sound.loop = true;\n",
+    "    sound.play();\n",
+    "}\n",
+    "\n",
+    "// Stop all sounds\n",
+    "static stopAllSounds() {\n",
+    "    const sounds = document.getElementsByTagName('audio');\n",
+    "    for (let sound of sounds) {\n",
+    "        sound.pause();\n",
+    "        sound.currentTime = 0;\n",
+    "    }\n",
+    "}\n",
+    "```\n",
+    "\n",
+    "I wrote the bottom two methods if you're curious. Anyway, I noticed that sound is played by its \"ID\". Well, what the heck is the id and why is it loaded from HTML (notice the `document.GetElementByID`). Took me a but longer than I should, but these IDs are loaded into HTML itself in `index.md`:\n",
+    "\n",
+    "```html\n",
+    "<!--Index.md-->\n",
+    "<!--Audio for music -->\n",
+    "\n",
+    "  <!--Audio for Everlong by Foo Fighters (Winter) -->\n",
+    "  <audio id=\"everlong\" src=\"{{site.baseurl}}/assets/audio/everlong.mp3\" preload=\"auto\"></audio>\n",
+    "```\n",
+    "\n",
+    "Ok, what does that do? Well, it loads a file from the filepath `{{site.baseurl}}/assets/audio/evelong.mp3` and assigns it the id `everlong`. Boom.\n",
+    "\n",
+    "Now, to play it on levels, I had to do a bit of a workaround. I didn't know where to load it to be unique to levels, so in a VERY jank workaround, I played it in upon loading the background.... Yeah not the best practice, but who'll know?\n",
+    "\n",
+    "```js\n",
+    "// ~/assets/js/platformer/BackgroundSnow.js\n",
+    "import Background from './Background.js';\n",
+    "import GameEnv from './GameEnv.js';\n",
+    "\n",
+    "export class BackgroundSnow extends Background {\n",
+    "    constructor(canvas, image, data) {\n",
+    "        super(canvas, image, data);\n",
+    "\n",
+    "        // Start the background music in loop\n",
+    "        GameEnv.loopSound('everlong');\n",
+    "\n",
+    "        this.parallaxSpeed = 0.3; // Speed for vertical parallax scrolling\n",
+    "    }\n",
+    "```\n",
+    "\n",
+    "Just import `GameEnv` and play the sound using `loopSound` to loop it or `playSound` if you just want to play it once."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## I want it FAST\n",
+    "\n",
+    "OK, OK, sorry for boring you with my frankly uninteresting story. Where's the code?\n",
+    "\n",
+    "1. Add an audio file to `~/assets/audio/`. For example:\n",
+    "\n",
+    "```js\n",
+    "// ~/assets/audio/everlong.mp3\n",
+    "```\n",
+    "\n",
+    "2. Load this audio file into HTML:\n",
+    "\n",
+    "```html\n",
+    "<!-- ~/index.md -->\n",
+    "<!--Audio for Everlong by Foo Fighters (Winter) -->\n",
+    "<audio id=\"everlong\" src=\"{{site.baseurl}}/assets/audio/everlong.mp3\" preload=\"auto\"></audio>\n",
+    "```\n",
+    "\n",
+    "3. Play the sound (here we use a music example):\n",
+    "\n",
+    "```js\n",
+    "// ~/assets/js/platformer/BackgroundSnow.js\n",
+    "import Background from './Background.js';\n",
+    "import GameEnv from './GameEnv.js';\n",
+    "\n",
+    "export class BackgroundSnow extends Background {\n",
+    "    constructor(canvas, image, data) {\n",
+    "        super(canvas, image, data);\n",
+    "\n",
+    "        // Start the background music in loop\n",
+    "        GameEnv.loopSound('everlong');\n",
+    "\n",
+    "        this.parallaxSpeed = 0.3; // Speed for vertical parallax scrolling\n",
+    "    }\n",
+    "```\n",
+    "\n",
+    "4. Done! Should work.\n",
+    "\n",
+    "\n",
+    "Some caveats though.\n",
+    "- All game sounds are automatically stopped upon level transition (I placed a `GameEnv.stopAllSounds();` inside the `transitionToLevel()` function)\n",
+    "- You can loop sounds using `loopSounds()` which is recommended! I used `playSound()` just for sake of example (which is more applicable to other sounds)\n",
+    "- Choose good sounds/music please!\n",
+    "\n",
+    "> Potentia ex nihilo.\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}