wle-uuidify/README.md

Switch Wonderland Engine project incremental number IDs to UUID

# wle-uuidify

Experimental utility tool to switch incremental number IDs of a Wonderland Engine project to UUIDs.

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

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

## :warning: Warning
This tool is very experimental.  
Always verify that the aligned project is OK after using the tool.  
Make sure to use version control.

## Installing

```
npm install --save-dev wle-uuidify
```

## Running

From the command line:
```
npm exec wle-uuidify -- my-project.wlp
```

From an NPM script (in `package.json`):
```
wle-uuidify my-project.wlp
```

### Arguments

The command accepts the following arguments:
- `<project-paths...>`: 
    - file paths to the Wonderland Engine project files that need to be uuidified
    - each path is a [glob](https://en.wikipedia.org/wiki/Glob_(programming)) pattern, which means you can use use `*.wlp` to uuidify every wlps in your folder

### Options

The following options are available:

- `-o | --output <path>`: 
    - where the uuidified project file will be stored
    - defaults to `<project-dir>/uuidified-<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`: 
    - uuidify the project even if there is no editor bundle, it contains errors, or for component properties that might not be incremental number IDs
    - be sure to out extra care when checking the differences with the original project after performing the operation with this option
- `-d | --duplicates`: 
    - checks if there are duplicated IDs in the project
    - this check is normally performed when uuidifying the project, so you can use this option when you just want to check that your project has no duplicates but do not actually need to uuidify it
- `-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:
        ```js
        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](https://github.com/playkostudios/wle-cleaner), used as a base for these tools
- [playkostudios](https://github.com/playkostudios), for sponsoring the tools