Merge pull request #29 from EvenTorset/dev

Dev

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [12.0.0] - 2024-06-27
+
+### Highlights
+- The ComponentSequenceProperty.combineComponents method has been improved so that it should now return an equal HermiteProperty if all of the components have the same number of keyframes and keyframe positions. This method is used internally to, for example, enable correct recoloring of these properties, so the output structure of recolored AC6 effects should now look a lot nicer if they were originally of this type.
+- Added .minify methods to all types of properties.
+  - Modifiers for all properties will be filtered to remove ones that are ineffective, i.e. modifiers that don't change anything about the property, for example a random range modifier with 0 as both the min and max values.
+  - ValueProperty.minify simply returns a clone of the property with the modifiers filtered.
+  - SequenceProperty.minify returns a ConstantProperty with the same value and filtered modifiers if the property only has a single keyframe. Otherwise, it returns a clone of the property with the modifiers filtered.
+  - ComponentSequenceProperty returns a ConstantProperty with the same value and filtered modifiers if all components only have a single keyframe each, and it returns a HermiteProperty if an equivalent one can be constructed with filtered modifiers. Otherwise, it returns a clone of the property with the modifiers filtered.
+- The Action.minify and DataAction.minify methods now also minify all properties.
+- The FXR.read method now gives a much better error message if given some invalid input.
+- Fixed vector fields causing problems in some cases due to not being counted properly. This primarily fixes reading the GPU particle actions, but might have also fixed some other actions.
+- Omitted class properties in actions are now handled in a much better way. They will no longer be in the JSON structure for the action class, and they don't cause read actions to end up with some nullish properties.
+- Improved how modifiers are combined from or separated into components. This fixes a couple of issues with the combined properties in action 10015.
+- Fixed the specular color of spot lights being handled differently depending on the value of the separateSpecular property when writing it for DS3.
+- Added an option to the FXR.read method to automatically round floats to 7 significant digits, which should make most floats a lot easier to read for humans.
+- Added some missing documentation for the game parameter in the FXR.read function.
+- Added a Modifier.isEffective function that can be used to check if a given modifier would have any effect if applied to a property. This is never useful for most people, but it is used internally to filter modifiers when splitting a vector property into its components and when minifying properties.
+
 ## [11.0.0] - 2024-06-09
 
 ### Highlights
@@ -33,4 +52,5 @@
 - External values 2000 and 70200 for AC6 have been documented thanks to lugia19.
 - Fixed action 301 (EqualDistanceEmitter) missing a type for one of its fields, potentially causing issues when writing to DS3's structure.
 
+[12.0.0]: https://github.com/EvenTorset/fxr/compare/v11.0.0...v12.0.0
 [11.0.0]: https://github.com/EvenTorset/fxr/compare/v10.0.1...v11.0.0

NODE.md

@@ -25,7 +25,7 @@ This is using npm to install the library (`@cccode/fxr`) without including the d
 If everything worked correctly, a new folder called `node_modules` and two new files called `package.json` and `package-lock.json` should have shown up in the folder. Those three should so far be the only things in the folder.
 
 # Modules
-Node can run JS code as either CommonJS scripts or ECMAScript modules (ESM). CommonJS is an old, outdated module system that should only be used if it's required by dependencies or for backwards compatiblity. ESM is newer and it is actually part of the JS language specification, unlike CommonJS. This library uses ESM and can not be used from CommonJS (without weird workarounds).
+Node can run JS code as either CommonJS scripts or ECMAScript modules (ESM). CommonJS is an old, outdated module system that should only be used if it's required by dependencies or for backwards compatiblity. ESM is newer and it is actually part of the JS language specification, unlike CommonJS. This library can be used with either, but I very strongly suggest sticking to ESM unless you absolutely know what you're doing (why are you reading this guide, if that's the case?) and your project requires CommonJS for some reason. None of the official examples or guides for the library will use CommonJS, so if you use it, you're on your own.
 
 Node runs JS code as CommonJS scripts by default, so you must tell it that your code is a module. To do that, you have two options (actually more options, but two easy ones that should be preferred):
 1. You can make a single file act as a module by using the `.mjs` file extension instead of `.js`. For example, if you put your code in a file called `example.mjs`, it will always be run as a module.
@@ -34,7 +34,7 @@ Node runs JS code as CommonJS scripts by default, so you must tell it that your
 {
   "type": "module",
   "dependencies": {
-    "@cccode/fxr": "^10.0.0"
+    "@cccode/fxr": "^11.0.0"
   }
 }
 ```
@@ -59,7 +59,7 @@ fxr.root.nodes = [
 
 await fxr.saveAs('example.fxr', Game.EldenRing)
 ```
-This creates a new FXR file with the ID 300 and sets up a single red square as the effect. It then uses the Node file system module to write the file to the folder as `example.fxr`.
+This creates a new FXR file with the ID 300 and sets up a single red square as the effect. It then writes the file to the folder as `example.fxr`.
 
 To run the example script, use this command:
 ```
@@ -109,9 +109,9 @@ Note that this will even update to new major releases, so there might be breakin
 ```text
 npm ls @cccode/fxr
 ```
-If an update has broken your scripts or if you just want to go back to an older version of the library, you can install any specific version by putting the version number after `@` at the end of the package name in the install command. For example, this is how you would install version 3.0.0:
+If an update has broken your scripts or if you just want to go back to an older version of the library, you can install any specific version by putting the version number after `@` at the end of the package name in the install command. For example, this is how you would install version 10.0.0:
 ```text
-npm i @cccode/fxr@3.0.0 --omit=dev
+npm i @cccode/fxr@10.0.0 --omit=dev
 ```
 
 <br>

README.md

@@ -1,7 +1,7 @@
 # FXR
-This is a JavaScript library for creating and editing FXR files (particle effects, lights, etc.) for Dark Souls 3, Sekiro, Elden Ring, and Armored Core 6. It does not require any dependencies, and works in both the browser and in Node.
+This is a JavaScript library for creating and editing FXR files (particle effects, lights, etc.) for Dark Souls 3, Sekiro, Elden Ring, and Armored Core 6. It does not require any dependencies, and works in both the browser and in Node.js.
 
-It includes classes for most known structures in the file format that makes it relatively very easy to create brand new effects from scratch. It also has functions that allow you to modify existing effects in different ways: scaling, recoloring, converting between games, and more.
+It includes classes for all known structures in the file format that makes it relatively very easy to create brand new effects from scratch. It also has functions that allow you to modify existing effects in many different ways: scaling, recoloring, converting between games, and more.
 
 ## Installation
 The library is available on [npm](https://www.npmjs.com/package/@cccode/fxr), so you can use a package manager like npm, yarn or pnpm to install it.
@@ -24,7 +24,11 @@ The library has the ability to deserialize FXR files into JSON objects and it ca
 This can be useful to see what existing effects do, or to copy parts of existing effects to use in your own, like in [the example script about this](https://github.com/EvenTorset/fxr/blob/main/examples/from_json.js). The JSON files can also be edited manually and converted back to FXR after using fxrjson again.
 
 ## Editing FXR files
-To edit existing FXR files, all you need is an ArrayBuffer or typed array with the file's content. The example below is written for Node, but by replacing how you get the buffer and what you do with the output it should also work fine in the browser.
+To edit existing FXR files, you need to first have the library read the file. When using Node.js, you can simply give it the file path and await the result. If you need to do it in the browser, you can give it an ArrayBuffer or typed array instead of a file path.
+
+Once it has been read, you can change things in the FXR object to whatever you need. The library also provides useful functions for common actions like scaling or recoloring effects.
+
+Once you have made your changes to the FXR object, you can write it to a file if you're using Node.js, or you can generate an ArrayBuffer with the file's content if you need it to run in the browser.
 ```js
 import { FXR, Game } from '@cccode/fxr'
 
@@ -77,7 +81,7 @@ fxr.root.recolor(([r, g, b, a]) => {
 await fxr.saveAs('f000450360_edit.fxr', Game.EldenRing)
 ```
 ## Creating new FXR files
-Creating brand new FXR files from scratch requires some knowledge about their structure, but below is an example to get started. The example creates lots of thin rectangular particles that change color over time in a cylindrical volume
+Creating brand new FXR files from scratch requires some knowledge about their structure, but below is an example to get started. The example creates lots of thin rectangular particles that change color over time in a cylindrical volume.
 ```js
 import {
   FXR,

build/build.js

@@ -203,6 +203,8 @@ export default async function(writeToDist = true) {
               'scale' in v ? `, scale: ${scaleMap[v.scale]}` : ''
             }${
               'color' in v ? `, color: 1` : ''
+            }${
+              v.omitClassProp ? `, omit: 1` : ''
             } },`
           }).join('\n          ')}
         },

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cccode/fxr",
-  "version": "11.0.0",
+  "version": "12.0.0",
   "description": "JavaScript library for creating and editing FXR files for Dark Souls 3, Sekiro, Elden Ring, and Armored Core 6.",
   "author": "CCCode",
   "type": "module",
@@ -27,9 +27,12 @@
     "/dist"
   ],
   "keywords": [
+    "elden-ring",
+    "sekiro",
+    "dark-souls-3",
+    "armoredcore6",
     "typescript",
-    "souls",
-    "modding"
+    "modding-tools"
   ],
   "repository": {
     "type": "git",
@@ -41,13 +44,13 @@
   },
   "homepage": "https://fxr-docs.pages.dev/",
   "devDependencies": {
-    "@types/node": "^20.12.7",
+    "@types/node": "^20.14.9",
     "chokidar": "^3.6.0",
     "cpy-cli": "^5.0.0",
-    "npm-run-all2": "^6.1.2",
-    "terser": "^5.29.2",
+    "npm-run-all2": "^6.2.0",
+    "terser": "^5.31.1",
     "typedoc": "^0.26.2",
-    "typescript": "^5.4.3",
-    "yaml": "^2.4.1"
+    "typescript": "^5.5.2",
+    "yaml": "^2.4.5"
   }
 }