Merge pull request #57 from LiberatedPixelCup/z-positioning-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

@@ -118,12 +118,39 @@ Finally, to get your sheet to appear, in `source_index.html`, add your new categ
 Make sure the name starts with `div_sheet_`, and match the postfix with the name of your json, in this case `body_robot`.
 
 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`.
 
+#### z-positions
+
+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`
+
+Therefore, before creating a PR, make sure you have committed the CSV to the repo as well.
+
+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.

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;
       }