upgrade watch script and finalize .ajmodel auto-exporter (#71)

tickets:
- closes #2
- closes #8
- closes #69
- closes #70

highlights:
- watch script is effectively instantaneous now instead of taking ~5s to copy over to client game directory
- delete all AJ export files from the repository
- add AJ export files to `.gitignore`
- add `.env` file support for dev-specific paths (crucial for watch script to function smoothly)
- add AJ export files to `.gitattributes` for nicer diffs in GitHub on old PRs with AJ export files

supplementarily:
- update README with a bunch of new setup steps
- squash `Setup` in README to multiple collapsible sections

.env.EXAMPLE

@@ -0,0 +1,16 @@
+## package-scripts
+BLOCKBENCH_PATH="C:/Users/afro/AppData/Local/Programs/Blockbench/Blockbench.exe"
+MINECRAFT_PATH="C:/Users/afro/AppData/Roaming/.minecraft"
+# name of the resourcepack in your `.minecraft/resourcepacks` folder for omega-flowey-remastered
+RESOURCEPACK_NAME="omega-flowey-remastered-resourcepack"
+# name of the world in your `.minecraft/saves` folder for omega-flowey-remastered
+WORLD_NAME="omega-flowey-remastered"
+
+## relevant to .ajmodel automated exports (`yarn start export`)
+# see: https://www.reddit.com/r/Minecraft/comments/wdx9mk/how_do_i_find_the_assets_folder_in_minecraft/iikxx3d/
+ASSETS_DIR="C:/Users/afro/AppData/Roaming/.minecraft/versions/1.20.1/1.20.1"
+# paths to `pack.mcmeta` for the repo's datapack/resourcepack it uses for Animated Java export files
+DATAPACK_MCMETA="G:/Coding/omega-flowey-minecraft-remastered/datapacks/animated_java/pack.mcmeta"
+RESOURCEPACK_MCMETA="G:/Coding/omega-flowey-minecraft-remastered/resourcepack/pack.mcmeta"
+# fixes #69 -- enables log passthrough from Blockbench (Electron renderer window) to main process
+ELECTRON_ENABLE_LOGGING=1

.gitattributes

@@ -2,3 +2,16 @@
 /.yarn/releases/*    binary
 /.yarn/plugins/**/*  binary
 /.pnp.*              binary linguist-generated
+
+datapacks/omega-flowey/data/animated_java linguist-generated
+datapacks/omega-flowey/datapack.ajmeta linguist-generated
+resourcepack/assets/animated_java linguist-generated
+resourcepack/assets/minecraft/models/item/animated_java_empty.json linguist-generated
+resourcepack/assets/minecraft/models/item/black_dye.json linguist-generated
+resourcepack/assets/minecraft/models/item/brown_dye.json linguist-generated
+resourcepack/assets/minecraft/models/item/golden_sword.json linguist-generated
+resourcepack/assets/minecraft/models/item/gray_dye.json linguist-generated
+resourcepack/assets/minecraft/models/item/white_dye.json linguist-generated
+resourcepack/assets/resourcepack.ajmeta linguist-generated
+
+datapacks/mathf linguist-vendored

.github/workflows/datapack.yml

@@ -7,6 +7,13 @@ env:
   FABRIC_SERVER: https://meta.fabricmc.net/v2/versions/loader/1.20.4/0.15.3/0.11.2/server/jar
   PACKTEST: https://cdn.modrinth.com/data/XsKUhp45/versions/Gq3rUEy6/packtest-1.3-mc1.20.4.jar
 
+  ASSETS_DIR: null
+  BLOCKBENCH_PATH: null
+  DATAPACK_MCMETA: null
+  MINECRAFT_PATH: null
+  RESOURCEPACK_MCMETA: null
+  WORLD_NAME: omega-flowey-remastered
+
 jobs:
   lint:
     runs-on: ubuntu-latest

.github/workflows/resourcepack.yml

@@ -2,6 +2,14 @@ name: resourcepack
 
 on: [push]
 
+env:
+  ASSETS_DIR: null
+  BLOCKBENCH_PATH: null
+  DATAPACK_MCMETA: null
+  MINECRAFT_PATH: null
+  RESOURCEPACK_MCMETA: null
+  WORLD_NAME: omega-flowey-remastered
+
 jobs:
   lint:
     runs-on: ubuntu-latest

.github/workflows/scripts.yml

@@ -2,6 +2,14 @@ name: scripts
 
 on: [push]
 
+env:
+  ASSETS_DIR: null
+  BLOCKBENCH_PATH: null
+  DATAPACK_MCMETA: null
+  MINECRAFT_PATH: null
+  RESOURCEPACK_MCMETA: null
+  WORLD_NAME: omega-flowey-remastered
+
 jobs:
   format:
     runs-on: ubuntu-latest

.gitignore

@@ -1,5 +1,18 @@
+# developer-specific environment variables
+.env
+
+# yarn dependencies
 .yarn
 .pnp*
 
 audio
 versions
+
+# auto-ajexport related
+last_exported_hashes.json
+datapacks/animated_java/data
+datapacks/animated_java/datapack.ajmeta
+resourcepack/assets/animated_java
+resourcepack/assets/minecraft/models/item/animated_java_empty.json
+resourcepack/assets/minecraft/models/item/white_dye.json
+resourcepack/resourcepack.ajmeta

README.md

@@ -11,14 +11,27 @@ Since then I've gained a lot of skills both in Minecraft map development and in
 
 ### Setup
 
-#### Workspace
+---
+
+<details>
+  <summary><strong>Workspace</strong></summary>
+
+1.  Install [`Node.js >= 16.10`](https://nodejs.org/en/download)
+2.  Install [`Yarn 3.6.3`](https://v3.yarnpkg.com/getting-started/install) by running `corepack enable`
+3.  Initialize the repo by running `yarn`
+4.  Enable Yarn's Plug'n'Play with VSCode by running `yarn dlx @yarnpkg/sdks vscode`
+5.  Copy-paste `.env.EXAMPLE` and rename it to `.env`
+
+    1.  Replace all the paths in there with paths on your local machine -- e.g. replacing `afro` with `<YOUR_USERNAME>`.
 
-1. Install [`Node.js >= 16.10`](https://nodejs.org/en/download)
-2. Install [`Yarn 3.6.3`](https://v3.yarnpkg.com/getting-started/install) by running `corepack enable`
-3. Initialize the repo by running `yarn`
-4. Enable Yarn's Plug'n'Play with VSCode by running `yarn dlx @yarnpkg/sdks vscode`
+    Most of these variables are pretty straightforward except for `ASSETS_DIR` -- you'll want to follow this [reddit post](https://www.reddit.com/r/Minecraft/comments/wdx9mk/how_do_i_find_the_assets_folder_in_minecraft/iikxx3d/) to extract a vanilla assets folder that you can point `ASSETS_DIR` to
+
+</details>
+
+---
 
-#### Required Tools
+<details>
+  <summary><strong>Required Tools</strong></summary>
 
 1. [Blockbench](https://www.blockbench.net/downloads) -- for 3D modelling
    1. Install our Blockbench CLI plugin:
@@ -29,9 +42,12 @@ Since then I've gained a lot of skills both in Minecraft map development and in
       3. Run `yarn build:prod` to generate the `animated-java.js` in the `dist` directory
       4. Open Blockbench, then go to `File > Plugins > Load Plugin From File` and select the `animated_java.js` file from your local `animated-java` repo (`animated-java/dist/animated-java.js`)
 
-#### Recommended Tools (Optional)
+</details>
 
-<!-- TODO(8): update this README with installation steps for the custom plugins when they are done -->
+---
+
+<details>
+  <summary><strong>Recommended Tools (Optional)</strong></summary>
 
 Install the following apps:
 
@@ -41,7 +57,12 @@ Install the following apps:
 
 We also recommend using [blockcolors.app](https://blockcolors.app/) to get a representative vanilla block texture for a desired color while texturing models.
 
-#### Testing
+</details>
+
+---
+
+<details>
+  <summary><strong>Testing</strong></summary>
 
 1. Download the [Fabric mod loader](https://fabricmc.net/) and install a new profile to your Minecraft launcher
 2. Download the [Fabric API](https://www.curseforge.com/minecraft/mc-mods/fabric-api/files) jar
@@ -52,20 +73,44 @@ We also recommend using [blockcolors.app](https://blockcolors.app/) to get a rep
    1. Try: `test runall`
    2. See `packtest`'s [README](https://github.com/misode/packtest) for full command documentation
 
+</details>
+
 ---
 
-### Adding a new model/animation
+### Development
+
+#### Important scripts
+
+Read the descriptions of the following scripts and run them when it is recommended to:
+
+1. `yarn start export`: run the AJ model export script
+
+   1. add `ELECTRON_ENABLE_LOGGING=1` to your `.env` file to enable log-passthrough from Blockbench's renderer process to the main process. **Run this if your `watch.models` script (from `yarn start watch.experimental`) runs into an error while exporting AJ models.**
+
+   We recommend running `yarn start export` at least once, and every time changes to `.ajmodel` files occur from new incoming commits.
+
+2. `yarn start`: this keeps your local repository's content synced with your `.minecraft` directory -- datapack/resourcepack changes will reflect in-game
+
+   1. if you run `yarn start watch.experimental`, it also watches `.ajmodel` files and runs our auto-exporter on them -- this reads all `.ajmodel` files in your local repo and runs Animated Java's `Export Project` function on them.
+      1. we specifically _do not_ commit AJ's exported files to the repo since they are _very large_
+      2. the `watch.models` script _will not_ work if you already have Blockbench open, so don't expect it to do anything while that's the case
+      3. its a little janky and experimental still, so \*\*we recommend manually running `yarn start export` if you run into issues relating to Animated Java export files (missing models, animations, attacks not playing properly)
+
+   We recommend keeping `yarn start` running at all times while working on the project.
+
+3. `yarn sync`: zips your Minecraft world and copies it to the repo as (`world.zip`). This is how we handle version-control for the actual Minecraft world. This is especially important to run and commit if you make any _physical changes_ to the world like breaking/placing blocks.
+
+4. `yarn lint`: runs Prettier, ESLint, and our custom linting rules on our files. Run this prior to pushing commits to save on our workflow hours.
+
+#### Adding a new model/animation
 
 1. Create a new Animated Java Rig via `File > New > Animated Java Rig`
 2. Enter inputs for the following required fields:
    1. `Project Name`
    2. `Resource Pack`: select the `pack.mcmeta` file located in the repository at `resourcepack/pack.mcmeta`
-   3. `Data Pack`: select the `pack.mcmeta` file located in the repository at `datapacks/omega-flowey/pack.mcmeta`
-3. Export your model/animations by clicking `Animated Java > Export Project` at the top
-
-When finished, ensure you partition commits into the following categories:
-
-1. `.ajmodel` + custom texture files ([example](https://github.com/TheAfroOfDoom/omega-flowey-minecraft-remastered/pull/55/commits/344c6da2d0676d2a6d358d5bf30df2e419458b77))
-2. automated export files when clicking `Animated Java > Export Project` ([example](https://github.com/TheAfroOfDoom/https://github.com/TheAfroOfDoom/omega-flowey-minecraft-remastered/pull/55/commits/ee471449e7e131b6c38129ddffb492769bf8064d))
-
-This ensures we split commits by what's 100% required (new custom textures + the `.ajmodel` files) and by what's automatically generated (`Export Project` files).
+   3. `Data Pack`: select the `pack.mcmeta` file located in the repository at `datapacks/animated_java/pack.mcmeta`
+3. Save the file with `CTRL + S` to somewhere appropriate under `resourcepack/assets/omega-flowey/models`
+   1. **While the model is still a work-in-progress, append `_dev` to the filename so our auto-export scripts skip it**
+      1. e.g. `housefly_dev.ajmodel`
+4. Export your model/animations by clicking `Animated Java > Export Project` at the top
+5. When finished with the model, remove the `_dev` suffix from the filename (e.g. `housefly.ajmodel`)

datapacks/animated_java/pack.mcmeta

@@ -0,0 +1,6 @@
+{
+  "pack": {
+    "pack_format": 26,
+    "description": "Contains Animated Java's exported datapack files."
+  }
+}