Skip to content

Commit

Permalink
Dev (#44)
Browse files Browse the repository at this point in the history 
* The color fields in action 10014 are now vector fields.
This fixes recoloring of this action and greatly simplifies the class for it.

* Improved property minification.
Now, if all keyframes in a sequence property or component sequence property are equivalent, the property can be minified to a constant property.

* The recoloring update.
This includes a ton of things related to recoloring.
It also includes bug fixes and improvements to the anyValueSum and anyValueMult functions.

* Improvements and bug fixes for the color palette-related functions.
- Replaced the 'average' parameter for the palette generation functions with a 'mode' parameter that can be set to one of three values:
  - PaletteMode.First: Same as average=false before.
  - PaletteMode.Average: Same as average=true before.
  - PaletteMode.Random: Adds an entry for each set of colors for each slot in the palette. The Node.recolor method will pick random entries in the palette's slot for each effect.
- The Node.recolor method will now generate fallback entries for missing slots of the given palette based on the existing slots. This means it should be better at recoloring effects when the palette is missing many of the slots. The method no longer warns about missing entries due to this change.
- The common particle slot in color palettes have been split into 4 different ones based on the blend mode used. This should make some recolors more accurate to the sampled effect.
- Bloom strength is now handled slightly differently to prevent the effect from becoming too bright in some cases.

* Added an FXRUtility namespace for utility functions.
Currently only has two functions: line and text.
The line function is useful for drawing lines between 3D points.
The text function generates nodes that form characters without needing any textures. It creates a lot of nodes, so it's not the most optimized way of doing this, but it works really well for debugging.

* Fixed links to functions inside namespaces in the docs website.

* Documented the hex template tag.

* Fixed point lights being way too bright in DS3.

* Added documentation for the FXRUtility namespace and its functions.

* Fixed more broken function links on the docs website.

* Added clone and scaleRateOfTime methods.
FXR objects, nodes, effects, and actions now have a clone method.
Nodes and DataActions now have a scaleRateOfTime method.
When writing for DS3, the rate of time from action 10500 is now automatically applied to all nodes. States still need to have this applied to them, but that will be in a future commit as I'm out of time right now.

* Writing to DS3 now scales the rate of time for states as well.
This was missing from the previous commit. With this, the rate of time should work properly for DS3 just like it does for the other games.

* Updated changelog.

* Throw when writing invalid FXR ID + FXR.name getter.

* Updated readme and Node.js setup guide.

* Cleaned up the Recolor.standardBlend function a bit.

* Fixed the Recolor.hueShift function always returning cyan-ish colors.

* Allow Vector3s to be used for more of the recolor functions.

* Fixed prototype method links not being redirected properly in docs site.

* Changed the fields in the node transform actions to vector fields.

* Updated readme, changelog, and examples.

* Added methods for getting all unique color values in nodes/actions.

* Removed dependency on Node.js Buffers when writing to a file.
Still requires an import for 'node:fs/promises', but that can be aliased in Vite for example if needed in the browser.

* Avoid the flashbang when going to the /q path on the docs site.

* Redirect to the home page when there no matches on the docs site's /q.

* Added sections to the readme and the Node.js guide about the playground.

* Updated the creation example in the readme to use fxr.name.

* Added links to open the two readme examples in the playground.

* 13.0.0

* Tagged v13.0.0 in the changelog.
  • Loading branch information
@EvenTorset
EvenTorset authored Aug 4, 2024
1 parent 8f54d98 commit 6ba3684
Show file tree
Hide file tree
Showing 56 changed files with 3,109 additions and 2,345 deletions.
46 changes: 46 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,50 @@
# Changelog

## [13.0.0] - 2024-08-04

### Highlights
- Many new recolor-related features have been added to make recoloring even easier.
- There is now a template tag for converting hex color strings into color vectors for FXRs. This tag is simply called `hex`, so it is now possible to do something like `` hex`5588ff` `` and it would be equivalent to `[0.333, 0.533, 1, 1]`. It supports 3-, 4-, 6-, and 8-digit hex values. This can be used anywhere where you would normally put color vectors.
- There are now two new functions for generating a color palette from existing effects:
- `Node.generateColorPalette` - Generates a palette from the node it is called on.
- `Recolor.generatePalette` - Generates a palette from an array of nodes or FXR objects.
- The `Node.recolor` method can now also take a color palette generated from the two functions above. This will apply the palette to the node it is called on, allowing you to copy a set of colors from one effect and apply them to another. This can be very useful if you want to make an effect fit an existing theme or set of effects.
- Added a new `Recolor` namespace, which contains many different recolor functions that can be used with the `Node.recolor` and `DataAction.recolor` methods:
- `Recolor.standardBlend`
- `Recolor.replace`
- `Recolor.multiply`
- `Recolor.add`
- `Recolor.invert`
- `Recolor.grayscale`
- `Recolor.curves`
- `Recolor.mix`
- `Recolor.hueShift`
- `Recolor.replaceHue`
- `Recolor.replaceSaturation`
- `Recolor.colorBlend`
- `Recolor.scaleSaturation`
- There is now also a `DataAction.recolorProperty` method that can be used to apply a recolor function to a single color property or color vector field.
- Added `Node.colors` and `DataAction.colors` generator methods, which yield all unique color values in the node/action.
- Added a new `FXRUtility` namespace, which contains methods to simplify various things when creating new effects.
- `FXRUtility.line` - Creates a node with a particle attached that forms a line between two points you give it. This has options for line width, color, and more.
- `FXRUtility.text` - Converts a given string to a node that looks like that string. This has options for font size, text alignment, and more.
- The offset and rotation fields in the node transform actions (35 and 36) have been converted to vector fields.
- The color multiplier and bloom color fields in the LensFlare action (10014) have been converted to vector fields.
- This fixes a bug where these fields were not changed by the recolor functions in the library.
- Converting point lights between DS3 and the other games should now keep the brightness more like the original. DS3 point lights seem to work a bit differently, so it stil won't be perfectly accurate, but it should be much closer than before.
- The rate of time can now be adjusted on nodes or actions using the new scaleRateOfTime method.
- The rate of time in action 10500 is now automatically applied to everything when writing to DS3. This fixes converting effects from newer games to DS3 causing them to play at a different rate than the original effect if the original had a non-unit value for the rate of time.
- The `FXR.toArrayBuffer` method will now throw if the FXR's ID is invalid.
- Added an `FXR.name` getter function to FXR objects, which returns a file name for the FXR based on its ID.
- For example, an FXR with 1 as the ID would return `f000000001.fxr`.
- This is very useful when saving an effect to a file, as now you can just do `await fxr.saveAs(fxr.name, Game.EldenRing)`, for example.
- Various functions that combine properties will now filter out some keyframes if they are less than a millisecond apart.
- Sequence properties and component sequence properties can now be minified to constant properties if all of their keyframes are the same.
- Some bugs have been fixed, and some improvements have been made to the anyValueSum and anyValueMult functions.
- Various broken links on the documentation site have been fixed.
- The Node.js setup guide has been updated to use the new `@cccode/create-fxr` module to set up the project folder, which eliminates some manual steps that are important to get right.
- The editing example in the readme has been updated to use some of the new recolor features instead of doing it the old way.

## [12.2.0] - 2024-07-14

### Highlights
Expand Down Expand Up @@ -70,6 +115,7 @@
- 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.

[13.0.0]: https://github.com/EvenTorset/fxr/compare/v12.2.0...v13.0.0
[12.2.0]: https://github.com/EvenTorset/fxr/compare/v12.1.0...v12.2.0
[12.1.0]: https://github.com/EvenTorset/fxr/compare/v12.0.0...v12.1.0
[12.0.0]: https://github.com/EvenTorset/fxr/compare/v11.0.0...v12.0.0
Expand Down
74 changes: 35 additions & 39 deletions NODE.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
# Before you continue
Just in case you happened upon this page before finding out about it: The [FXR Playground](https://fxr-playground.pages.dev) is website where you can use the library without having to install anything. It is recommended that you check it out before continuing to find out if you really need to install the library locally.

The playground includes a UI for performing simple actions such as recoloring or resizing existing effects, as well as things to simplify manual edits and running scripts that perform more advanced or bulk edits, or create entirely new effects from scratch.

# About this page
This page is for those that are not already familiar with Node.js and want to run scripts using the library locally. It goes over the basics, so that you can better understand how it works, and to get you started.

Expand All @@ -6,39 +11,25 @@ If you run into any problems or get confused about something, check out [the tro
# Node.js
Node.js is a program that lets you run JavaScript files locally. You can download it from the official website here: https://nodejs.org/

This library has only been tested using version 21 of Node, so any version after that is recommended, but it should work fine on v20 and possibly older versions as well.
The library requires version 20 (or newer) of Node.js, and v22 is the recommended version.

When installing it, it will ask if you want to also install various tools for native modules (Python 2, VS Build Tools, Boxstarter, Chocolatey). If you don't know whether you should tick the checkbox or not: It depends on what you want to do with Node. This library does not require any of this, so feel free to leave it unticked if that's all you want to use it for. If you want to use it for other things, it might be a good idea to tick it just in case you'll need a package that requires it at some point.

## npm
Node Package Manager (npm) is a separate program that is installed along with Node. It lets you easily install and manage dependencies for your project.

# Project folder
To use the library with Node, you'll want to make a new empty folder to keep everything related contained somewhere. Next, there is a command that you need to run to install the library. It must be run from inside the new folder, otherwise it will be installed somewhere else on your computer. To make sure that it's run from the correct folder, (on Windows) open the command prompt in that folder by entering `cmd` in the address bar and pressing enter. You can also open the Windows Terminal in the folder by right-clicking in there and selecting "Open in Terminal" if you have that option, or you can open the folder in VS Code and run commands from the termnial in that.
To use the library with Node, you'll want to make a new empty folder to keep everything related contained somewhere. This new folder should be somewhere where you have permission to edit the folder, for example a folder on your desktop, or one in your documents folder. **NOTE**: Do **not** try to use a folder in a system folder (like `C:\Windows\`) or where programs are installed (like `C:\Program Files\`, `C:\Program Files (x86)\`, or where you installed Node.js) - Doing so would most likely break things.

Next, there is a command that you need to run to install the library and set up the project folder. **It must be run from inside the new empty folder.** To make sure that it's run from the correct folder, (on Windows) open the command prompt in that folder by entering `cmd` in the address bar and pressing enter. You can also open the Windows Terminal in the folder by right-clicking in there and selecting "Open in Terminal" if you have that option, or you can open the folder in VS Code and run commands from the termnial in that.

This is the command you must run in that folder to install the library:
```
npm install @cccode/fxr --omit=dev
npm create @cccode/fxr@latest ./
```
This is using npm to install the library (`@cccode/fxr`) without including the dev-dependencies (`--omit=dev`) of it, which are not needed to use the library, only for transpiling it and generating the documentation site.

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 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.
When running this command, you may be prompted to install a module named `@cccode/create-fxr`. Pressing enter (or typing `y`, then enter) should allow it to continue. The `@cccode/create-fxr` module simply sets up the project folder for you so that you don't have to do anything manually to it.

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.
2. You can make the entire project a module by editing the `package.json` file. This means that you can still use the `.js` extension for any file in the folder and it will be run as a module. To do this, open `package.json` in a text editor and set "type" to "module". Your file should look something like this once you're done:
```json
{
"type": "module",
"dependencies": {
"@cccode/fxr": "^11.0.0"
}
}
```
I would recommend using the second option, but it really doesn't matter, the choice is up to you. For the rest of this guide, I'll assume that you went with the second option, so if you chose the first one just replace any `.js` file extensions with `.mjs`.
If everything worked correctly, there should be a message in the terminal that explains some things about the project folder, and there should be a few new files in the folder, for example `package.json`, and a folder called `node_modules`.

# Testing the setup
To test that you have done everything correctly, let's try to make a very simple example FXR file.
Expand All @@ -61,7 +52,7 @@ 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 writes the file to the folder as `example.fxr`.

To run the example script, use this command:
To run the example script, use this command in the project folder:
```
node example.js
```
Expand Down Expand Up @@ -101,11 +92,9 @@ To run your code directly from your text editor, you can set up a task, launch c
You can then run the code by just pressing a hotkey when you have the file open.

# Updating
If a new version of the library has been released and you want to update, you can just run the install command again, but with `@latest` to tell npm to grab the latest release specifically:
```text
npm i @cccode/fxr@latest --omit=dev
```
Note that this will even update to new major releases, so there might be breaking changes. It might be a good idea to write down what your current version is before trying to update if you have some scripts that you want to keep using without updating them to work with the new version. To find out what version of the library you currently have installed, you can use this command:
If a new version of the library has been released and you want to update, you can simply double click the `update.bat` file in the project folder to do it.

Note that this will even update to new major releases, which may contain breaking changes. It might be a good idea to write down what your current version is before trying to update if you have some scripts that you want to keep using without updating them to work with the new version. To find out what version of the library you currently have installed, you can use this command:
```text
npm ls @cccode/fxr
```
Expand All @@ -123,11 +112,21 @@ ___
# Troubleshooting
Below are some common problems you might run into and how to deal with them:

### "Warning: To load an ES module, set "type": "module" in the package.json ..."
If you get this warning when trying to run a JS file, you're running it as a CommonJS script instead of an ES module. To fix that, check out [the section about modules](#modules) above.
### Error: Cannot find module '<some path>\example.js'
This error means that it couldn't find your script file when you ran the command to run the script.

This can happen if you opened the terminal outside of the project folder, for example by opening it through the Windows start menu. The [Project folder](#project-folder) section above explains how you can open the terminal in the right folder.

This can also happen if you put your script file outside of the project folder. Make sure it is in the right place before you run the command.

### "SyntaxError: Cannot use import statement outside a module"
If you get this error when trying to run a JS file, you're running it as a CommonJS script instead of an ES module. To fix that, check out [the section about modules](#modules) above.
### Uncaught SyntaxError: Unexpected identifier 'example'
If you see this error, it means you ran Node.js on its own and then tried to run commands from there instead of cmd. Node.js should not be run on its own unless you know what you're doing with it.

To fix this, you can run this command to exit Node.js and go back to cmd:
```
.exit
```
You can also just close and reopen the terminal in the project folder.

### Tools for Native Modules / Python 2 / VS Build Tools / Boxstarter / Chocolatey
If you see a page in the Node installer mentioning this stuff and you don't know whether to tick the checkbox or not, it depends on what you are going to do with Node. If you are only going to use this library and nothing else, feel free to leave the checkbox unticked, the library doesn't require anything from it. If you plan to use other packages from NPM, it might be a good idea to tick it, since some of them might require it for compiling during installation.
Expand All @@ -137,12 +136,12 @@ To find out what version of Node.js you have installed, run this command:
```
node -v
```
Versions older than v20 are not guaranteed to work with the library.
Versions older than v20 are not supported by the library.

To update from an older version, just grab the installer from the version you want and run it. It should take care of everything on its own.

### "'npm' is not recognized as an internal or external command, ..."
If you get this error when trying to install the library, you either don't have Node.js installed, or you chose not to install npm when installing Node, or you chose not to add it to the PATH environment variable. To fix it, run the Node.js installer again and make sure npm is set to install and that the "Add to PATH" option is enabled.
If you get this error when trying to set up the project folder, you either don't have Node.js installed, or you chose not to install npm when installing Node, or you chose not to add it to the PATH environment variable. To fix it, run the Node.js installer again and make sure npm is set to install and that the "Add to PATH" option is enabled.

Another possible option for why this happens is that you opened the terminal before installing Node and npm, causing it to not know where npm is installed. To fix that, simply close and reopen the terminal.

Expand All @@ -151,19 +150,16 @@ If you get this error when trying to run a JS file, you either don't have Node.j

Another possible option for why this happens is that you opened the terminal before installing Node, causing it to not know where Node is installed. To fix that, simply close and reopen the terminal.

### "Invalid package config ..."
If you get this error when trying to install the library or run a JS file, your package.json file has an error in it. It might be missing a comma somewhere, maybe it has a comma where it shouldn't, or maybe it has the wrong kind of quote character or it's missing a quote character or two. To find the issue and fix it, you can use a JSON linter, like https://jsonlint.com/, which should point out where the error is, and maybe tell you exactly what it is.

### I don't know what code to write
If you don't know JS, there are plenty of free online courses out there to learn the basics, but you can also learn enough to use this library from [the examples in this repo](/examples/) and [the documentation site](https://fxr-docs.pages.dev/).

### I ran the command to install the library, but node_modules didn't appear
If the node_modules folder and the two package JSON files didn't show up when running the command, it either errored or it was run from a different folder.
### I ran the command to set up the project folder, but node_modules didn't appear
If the node_modules folder and the extra files didn't show up when running the command, it either errored or it was run from a different folder.

To check if it errored, just check the terminal where you ran the command. The error will have more information if it's there.

If it didn't error, the command was probably run from a different folder. In the terminal, you can see what folder it's running from in front of where you enter commands. For example, it might say something like
```
C:\Projects\FXR_Test> {your command goes here}
```
If the path there doesn't match the path to your folder, the command will be run from a different folder, and it would have installed the library there instead. To fix this, you can go to the folder at that path and remove the node_modules folder, package.json file, and package-lock.json file if the folder isn't part of a different Node package. You can then go back to the folder where you wanted to install the library and follow [the section about the project folder](#project-folder) again carefully.
If the path there doesn't match the path to your folder, the command will be run from a different folder, and it would have installed the library there instead. To fix this, you can go to the folder at that path and remove the node_modules folder, package.json file, and package-lock.json file if the folder isn't part of a different Node package. You can then go back to the project folder and follow [the section about the project folder](#project-folder) again carefully.
Loading

0 comments on commit 6ba3684

Please sign in to comment.