Update z-position script usage and readme

.github/workflows/validate-index_html.yml → .github/workflows/validate-site-sources.yml

@@ -1,4 +1,4 @@
-name: Validate index_html
+name: Validate site sources
 
 on:
   push:
@@ -7,8 +7,8 @@ on:
     branches: [ master ]
 
 jobs:
-  validate_index_html:
-    name: Validate index html
+  validate_site_sources:
+    name: Validate site sources
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -17,13 +17,13 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v3
 
-      - name: Validate HTML generation
+      - name: Validate site sources generation
         run: |
           node scripts/generate_sources.js
       - name: Assert git diff
         run: |
           if [[ `git status --porcelain` ]]; then
-            echo "Differences found after (re)generation of the index.html"
-            echo "Please refer to the README in order to learn how to generate the index.html properly."
+            echo "Differences found after (re)generation of the site sources"
+            echo "Please refer to the README in order to learn how to generate the site's sources properly."
             exit -1
           fi

README.md

@@ -75,19 +75,42 @@ Make sure the name starts with `div_sheet_`, and match the postfix with the name
 When adding files to the project, please add valid licensing information inside the json files as well. Note the entire list of authors for that image, a URL for each piece of art from which this image is derived, and a list of licenses under which the art is available. If you don't add license information for your newly added files, the generation of the site sources will fail.
 
 At this point, you will need to run a script that will generate the final `index.html`.
-In order to do that, run `node scripts/generate_sources.js` from the root folder.
+In order to do that, run:
+
+`node scripts/generate_sources.js` 
+
 This will generate the `index.html` from the `source_index.html`.
 
 In case you want to push your changes, be sure to run this script and never change the `index.html` manually.
 The CI will reject any PR's that contain manual changes made on the `index.html`.
 
-### Run
+#### z-positions
 
-To run this project, just clone the repo and open `index.html` in your browser of choice.
+In order to facilitate easier management of the z-positions of the assets in this repo, there is a [script](/scripts/zPositioning/parse_zpos.js) that traverses all JSON files and write's the layer's z-position to a CSV.
+
+To run this script, use:
+
+`node scripts/zPositioning/parse_zpos.js`
+
+This [CSV file](/scripts/zPositioning/z_positions.csv) will be regenerated each time one invokes:
+
+`node scripts/generate_sources.js`
 
-### z-positions
+Therefore, before creating a PR, make sure you have committed the CSV to the repo as well.
 
-TBD
+Using this CSV, one can more clearly see the overview of all the z-position used per asset's layer.
+
+Moreover, one can adjust the z-position from within the CSV, and then run:
+
+`node scripts/zPositioning/update_zpos.js`
+
+In order to reflect the changes made back into the JSON files.
+
+**Concluding, please remember that the JSON files will always contain the source of truth with regard to the z-position an asset will be rendered at. The CSV is there to give an overview of the z-positions in use, and provides a mean to easily alter them from a single file.**
+
+### Run
+
+To run this project, just clone the repo and open `index.html` in your browser of choice.
 
 ### Examples
 ![example](https://github.com/liberatedpixelcup/Universal-LPC-Spritesheet-Character-Generator/blob/master/example.png)

scripts/generate_sources.js

@@ -1,6 +1,8 @@
 const fs = require('fs');
 const readline = require('readline');
 
+require('child_process').fork('scripts/zPositioning/parse_zpos.js');
+
 var licensesFound = [];
 function searchCredit(fileName, credits, origFileName) {
   if (credits.count <= 0) {
@@ -204,4 +206,4 @@ lineReader.on('close', function (line) {
         console.log('Found licenses:', licensesFound)
     }
   });
-});
+});

scripts/parse_zpos.js → scripts/zPositioning/parse_zpos.js

@@ -36,10 +36,10 @@ fs.readdirSync(testFolder).forEach(file => {
     }
   }
 });
-fs.writeFile('sheet_definitions/z_positions.csv', toWrite, function(err) {
+fs.writeFile('scripts/zPositioning/z_positions.csv', toWrite, function(err) {
   if (err) {
       return console.log(err);
   } else {
-      console.log('Updated!');
+      console.log('Updated z_positions.csv!');
   }
 });

scripts/update_zpos.js → scripts/zPositioning/update_zpos.js

@@ -1,6 +1,6 @@
 const fs = require('fs');
 
-const csv = fs.readFileSync('sheet_definitions/z_positions.csv').toString().split("\n");
+const csv = fs.readFileSync('scripts/zPositioning/z_positions.csv').toString().split("\n");
 
 fs.readdirSync('sheet_definitions').forEach(file => {
   if (!file.includes('.json')) {
@@ -17,6 +17,7 @@ fs.readdirSync('sheet_definitions').forEach(file => {
           const requiredZposition = parseInt(item.split(",")[2]);
           definition[`layer_${jdx}`].zPos = requiredZposition;
           fs.writeFileSync(`sheet_definitions/${file}`, JSON.stringify(definition, null, 2), function(err) { });
+          console.log('Updated:', file);
         }
         entryIdx += 1;
       }