wle-aligner

Experimental utility tool to align a Wonderland Engine project to another one.
This means:

• matching the IDs of the objects/resources if they represent the same thing on both projects

Source code: https://github.com/SignorPipo/wle-aligner

NPM package: https://www.npmjs.com/package/wle-aligner

⚠️ Warning

This tool is very experimental. To perform this alignment it tries to guess which objects/resources might represent the same thing on both projects. This means that there might be mistakes in this process.

Always verify that the aligned project is OK after using the tool.
Make sure to use version control.

Why should I use this?

The aligner is useful when you have a project which contains multiple wlp projects that share similar resources and objects.
If you find yourself copy pasting stuff between projects, when the same resource does not actually have the same ID on both projects you always have to manually fix the references.

After the projects have been aligned, most resources will share the same ID on both projects, so it will be easier to sync them!

Installing

npm install --save-dev wle-aligner

Running

From the command line:

npm exec wle-aligner -- source-project.wlp target-project.wlp

From an NPM script (in package.json):

wle-aligner source-project.wlp target-project.wlp

Arguments

The command accepts the following arguments:

• <source-project-path>:
  • file path to the source Wonderland Engine project file
  • the path is a glob pattern, which means you can use use *.wlp to use the first wlp found in your folder as the source project
    • if it resolves to multiple paths, the first one will be used
• <target-project-paths...>:
  • file paths to the target Wonderland Engine project files, that will be aligned to the source one
  • it's assumed that the target project does not have IDs in common, or, if it does, those IDs already represent the same resources on the source project
  • each path is a glob pattern, which means you can use use *.wlp to align every wlps in your folder with the specified source project

Options

The following options are available:

• -o | --output <path>:
  • where the aligned project file will be stored
  • defaults to <project-dir>/aligned-<project-name> when this option is not explicitly specified
  • if multiple project paths are specified, the --output option can't be used
• -r | --replace:
  • replace the given project file instead, ignoring the --output option
• -u | --unsafe:
  • align the projects even if there is no editor bundle, it contains errors, or the properties might not represent the same on both projects
  • be sure to out extra care when checking the differences with the original project after performing the operation with this option
• -a | --all-combinations:
  • align every specified project with the others
  • can be used only when the --replace option is also specified
  • you can use *.wlp as both the source and the target project path to align every wlps in your folder
• -s | --strict:
  • align only the resources that contains the same value for all their properties, instead of guessing it just through the name, linked assets, or similar "identifiers" properties
• -a | --align <properties...>:
  • align only the specified resource properties
  • you can choose the following properties:
    • ids
• -i | --include <resources...>:
  • align only the specified project resources
  • you can choose from the following options:
    • objects
    • meshes
    • textures
    • images
    • materials
    • shaders
    • animations
    • skins
    • pipelines
    • files
    • fonts
    • languages
• -b | --editor-bundle <path>:
  • path to the project bundle, usually generated by building the project with the Wonderland Engine editor
  • defaults to <project-dir>/cache/js/_editor_bundle.cjs when this option is not explicitly specified
• -e | --editor-bundle-extras <path>:
  • add extra definitions to the editor bundle via a JS script
  • defaults to <project-dir>/editor-bundle-extras.js when this option is not explicitly specified
  • this option might be needed when the tool complains for some missing definitions, like window or window.location not being defined
  • you can fix these issues by adding the missing definitions to the extras script
  • example:

    let window = {
        navigator: {},
        location: {}
    };
    
    class ExampleClass { }
    
    // This might be needed for some libraries that define their classes in the old js way, like Howler
    let ExampleObjectDefinedClass = {
        prototype: {}
    };

• -h | --help:
  • display help for the command

Credits

• wle-cleaner, used as a base for these tools
• playkostudios, for sponsoring the tools